TypeError: MLflowTracker.log() missing 1 required positional argument: ‘step’

快速结论：该报错发生在使用 Accelerate 的 MLflowTracker 记录日志时，调用 tracker.log() 或 accelerator.log() 缺少 step 参数。优先排查是否使用了 accelerate 版本 ≤ 1.14.0.dev0（当前问题版本），并检查 MLflowTracker.log() 方法签名是否缺少 step: Optional[int] = None 默认值。

问题场景

用户在 Accelerate 中使用 MLflowTracker 进行实验跟踪。具体场景包括：

直接调用 MLflowTracker.log() 方法时不传入 step 参数。
通过 Accelerator.log() 传入 log_kwargs 为 MLflowTracker 传递额外参数（如 synchronous）。

报错原文

TypeError: MLflowTracker.log() missing 1 required positional argument: 'step'

以及关联错误：

TypeError: MLflowTracker.log() got an unexpected keyword argument 'synchronous'

原因分析

在 src/accelerate/tracking.py 中，MLflowTracker.log() 的方法签名与其他跟踪器（如 WandB、CometML、ClearML、DVCLive、TrackioTracker）不一致：

其他跟踪器使用 step: Optional[int] = None 且支持 **kwargs。
MLflowTracker.log() 声明为 step: Optional[int]（无默认值）且不接受 **kwargs。
尽管文档字符串明确说明 step 是可选参数（*optional*），但实际实现要求必须提供。
第二种错误是因为 Accelerator.log() 会通过 **log_kwargs.get(tracker.name, {}) 转发参数，但 MLflowTracker.log() 缺少 **kwargs 接收。

该问题在 Accelerate 1.14.0.dev0（commit 29e03d185d6）以及更早版本中存在。

环境排查

确认 accelerate 版本：1.14.0.dev0 及以下版本受影响（查看 accelerate.__version__）。
确认 mlflow 版本：3.12.0（Issue 中提及）。
确认 Python 版本：3.11.14（Issue 中提及）。
操作系统：macOS 26.3 arm64（Issue 中提及，但问题与平台无关）。

解决步骤

升级 accelerate 到修复版本：该问题已在 upstream/main 分支通过 PR #4039 修复，建议更新 accelerate 到包含该修复的版本（≥ 1.14.0 正式版或使用最近的主分支 commit）。
如果无法升级，临时规避方案：
- 调用 tracker.log() 时始终传入 step 参数（即使是 step=None）。
- 调用 accelerator.log() 时不要为 MLflowTracker 传入 log_kwargs，或者确保 log_kwargs["mlflow"] 字典为空。
手动修补代码（可选，不推荐）：
- 修改 src/accelerate/tracking.py 中 MLflowTracker.log 方法签名：将 step: Optional[int] 改为 step: Optional[int] = None，并添加 **kwargs。

验证方法

运行以下测试确认问题已修复：

pytest tests/test_tracking.py::MLflowTrackingTest::test_log_without_step -v --tb=short
pytest tests/test_tracking.py::MLflowTrackingTest::test_log_accepts_extra_kwargs -v --tb=short

如果两个测试均通过（PASSED），则问题已解决。如果其中一个仍失败（FAILED），请检查 accelerate 版本是否已正确升级。

参考来源

huggingface/accelerate #4041 — Issue 讨论包含复现步骤、完整报错、环境信息以及合并的修复 PR。

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

TypeError: MLflowTracker.log() missing 1 required positional argument: ‘step’