 ignores step parameter 解决方案){kind=tracking}
【Bug已解决】[Bug]： TrackioTracker.log() ignores step parameter 解决方案
一、现象长什么样
用accelerate的TrackioTracker做实验追踪，调用tracker.log({"loss": 0.3}, step=120)期望在 Trackio 面板上看到这条记录挂在 step=120。可实际上：
期望：loss=0.3 @ step 120 实际：loss=0.3 @ step =（Trackio 内部自动递增的步数，不是 120）也就是说，传给log的step参数被完全忽略了。结果：
- 多条不同 step 的日志被压到同一个自动步数上，x 轴错位；
- 学习率曲线、loss 曲线和真实训练 step 对不上；
- 当你用
step显式对齐多个指标（如每隔 N 个 step 记一次）时，全部失效。
最隐蔽的是：它不报错、不告警，只是"step 没生效"。这种 silent ignore 最容易被当成"Trackio 自己的步数逻辑"，排查半天找不到原因。
二、背景
accelerator.log是accelerate统一的指标上报入口，它会把调用转发给当前激活的各个Tracker。每个 Tracker 需实现log(values, step=None, **kwargs)，并在上报时尊重调用方传入的step。
TrackioTracker是接入 Trackio 后端的实现。Trackio 自己的logAPI 通常也有step参数。问题在于TrackioTracker.log在转发时没有把step透传给底层 Trackio 客户端，而是依赖 Trackio 内部的自动步数（每调用一次 +1）。于是：
- 上游
accelerator.log({"loss": x}, step=120)把step=120传给了TrackioTracker.log； TrackioTracker.log在内部调用trackio_client.log(values)时漏掉了step；- Trackio 客户端按自己的自动计数器记步，120 被丢弃。
根因是"透传缺失"：Tracker 实现忘记把step继续往下传。这类 bug 在多个 Tracker（MLflow、Wandb、TensorBoard）的适配代码里都出现过，本质是同一个模式——适配器在转发参数时丢字段。
三、根因
抽象成代码（示意，非照抄源码）：
class TrackioTracker: def log(self, values, step=None, **kwargs): # BUG：调用底层时没把 step 传下去 self.client.log(values, **kwargs) # step 被丢弃根因链条：
accelerator.log(values, step=120)把step传入TrackioTracker.log；TrackioTracker.log的签名里有step形参，却没用到；- 转发给
trackio_client.log时只传了values与**kwargs，step被忽略； - Trackio 客户端退回到自动步数，120 丢失；
- 全链路无异常，现象只是"步数对不上"——典型 silent ignore。
为什么**kwargs没救回来？因为上游传的是位置/关键字step，而step已被log方法的签名捕获，不会进入**kwargs；除非显式self.client.log(values, step=step, **kwargs)，否则它永远到不了底层。
四、最小可运行复现
用纯 Python 模拟"适配器吞掉 step"：
# repro_trackio_step.py class FakeTrackioClient: def __init__(self): self.auto_step = 0 self.records = [] def log(self, values, step=None, **kwargs): if step is None: step = self.auto_step self.auto_step += 1 self.records.append((step, values)) class TrackioTracker: def __init__(self, client): self.client = client def log(self, values, step=None, **kwargs): # BUG：漏传 step self.client.log(values, **kwargs) def main(): client = FakeTrackioClient() tracker = TrackioTracker(client) tracker.log({"loss": 0.3}, step=120) # 期望 step=120 print("实际记录：", client.records) got_step = client.records[0][0] assert got_step != 120, "step 被忽略，落到了自动步数" print("确认：传入的 step=120 被丢弃，落到了", got_step) if __name__ == "__main__": main()运行输出：
实际记录： [(0, {'loss': 0.3})] 确认：传入的 step=120 被丢弃，落到了 0传入的step=120掉到了自动步数 0，正是真实 bug 的抽象。
五、解决方案（第一层：最小直接修复）
最小且必须的一步：转发时把step透传给底层客户端。
# fix_layer1.py class TrackioTracker: def log(self, values, step=None, **kwargs): # 修复：把 step 继续往下传 self.client.log(values, step=step, **kwargs)这一行改动让step=120真正到达 Trackio 客户端，曲线按预期对齐。但它依赖"每个 Tracker 实现都记得透传"，若以后新增适配器又漏字段，问题会复发。
六、解决方案（第二层：结构性改进）
把"上报必须尊重 step"做成基类的统一契约，并让BaseTracker.log负责把step注入，子类只管"如何发"。这样透传由父类保证，子类无法漏：
# fix_layer2.py from abc import ABC, abstractmethod from dataclasses import dataclass @dataclass(frozen=True) class LogCall: values: dict step: int | None class BaseTracker(ABC): @abstractmethod def _emit(self, call: LogCall) -> None: ... def log(self, values, step=None, **kwargs): # 父类统一构造 LogCall，子类只能从 call.step 取值 call = LogCall(values=dict(values), step=step) self._emit(call) class TrackioTracker(BaseTracker): def __init__(self, client): self.client = client def _emit(self, call: LogCall) -> None: # step 来自 call，不可能被忽略 self.client.log(call.values, step=call.step) class FakeClient: def __init__(self): self.records = [] def log(self, values, step=None): self.records.append((step, values))要点：
BaseTracker.log把step固化进LogCall，子类_emit只能读call.step；- 子类无法"忘记透传"，因为根本没有单独接收
step形参的自由； - 新增任何 Tracker 都继承该契约，silent ignore 类 bug 在结构上被消灭。
七、解决方案（第三层：断言 / CI 守护）
写 pytest 验证"传入的 step 必须到达底层"：
# test_trackio_step.py import pytest class FakeClient: def __init__(self): self.last_step = "NOT_SET" def log(self, values, step=None, **kwargs): self.last_step = step class TrackioTracker: def __init__(self, client): self.client = client def log(self, values, step=None, **kwargs): self.client.log(values, step=step, **kwargs) # 修复后 def test_step_is_forwarded(): client = FakeClient() tracker = TrackioTracker(client) tracker.log({"loss": 0.3}, step=120) assert client.last_step == 120, "step 必须透传到底层" def test_none_step_allowed(): client = FakeClient() tracker = TrackioTracker(client) tracker.log({"loss": 0.3}) # 不传 step assert client.last_step is None def test_step_not_collapsed_to_zero(): client = FakeClient() tracker = TrackioTracker(client) tracker.log({"loss": 0.3}, step=999) assert client.last_step != 0, "不能落到自动步数 0"CI 一旦有人把step=step删掉，前两个测试立刻变红。
八、排查清单
发现 Trackio 步数对不上时：
- 确认
accelerator.log(values, step=...)是否真的传了step； - 检查
TrackioTracker.log是否把step透传给了底层客户端； - 临时打印底层客户端收到的
step，若为None即命中本 bug； - 按第五 / 六节修复，确保
step透传； - 若多个 Tracker 都接
accelerator，逐一确认各自适配器； - 把第七节的 pytest 接进 CI，守护"step 透传"；
- 用基类契约（
BaseTracker）把透传固化，防未来新增适配器漏字段。
九、小结
TrackioTracker.log()忽略了step参数，根因是适配器在把调用转发给底层 Trackio 客户端时漏传了step——step被方法签名捕获后没有继续往下传，客户端退回自动步数，导致曲线错位。这是"适配器透传丢字段"的典型 silent ignore。
三层层级：
- 第一层：转发时显式
self.client.log(values, step=step, **kwargs)； - 第二层：用
BaseTracker把step固化进LogCall契约，子类无法漏传； - 第三层：pytest 验证 step 透传与不为 0，锁进 CI。
核心教训：所有"参数透传"型适配器，最易犯的错误就是丢字段。把透传收口到父类 / 单一入口，比依赖每个子类"记得传"可靠得多。
