追踪 Qwen Code

MLflow Tracing 为 Qwen Code（阿里巴巴的开源终端编码智能体）提供自动追踪功能。设置完成后，MLflow 将自动捕获 Qwen Code 对话的追踪记录，包括：

• 用户提示词 (User prompts) 和助手回复
• 工具使用情况（文件操作、shell 命令等）
• Token 用量（输入、输出和总 Token 数）
• 会话元数据，包括工作目录和用户

每次对话轮次结束后会创建追踪记录。

设置

要求

• 正在运行的 MLflow 追踪服务器
• 已安装 Qwen Code (npm install -g @qwen-code/qwen-code)
• Node.js 18+
• @mlflow/qwen-code npm 包

第 1 步：安装追踪插件

bash

npm install -g @mlflow/qwen-code

如果您不想全局安装，可以通过 npx 调用二进制文件（例如 npx @mlflow/qwen-code setup）——下面的所有操作方式相同。

第 2 步：运行设置命令

运行 mlflow-qwen-code setup 将启动一个交互式流程，用于设置追踪钩子（hook）。

text

~/my-project $ mlflow-qwen-code setup

Configure MLflow tracing for Qwen Code
? Where should MLflow tracing be installed?
  ● Project  ./.qwen/  (default)
  ○ User  ~/.qwen/

  ↑/↓ to move, enter to select

✓ Registered Stop hook in /path/to/project/.qwen/settings.json

  MLflow tracking URI [https://:5000] https://:5000
  MLflow experiment ID [0] 1

✓ Wrote tracing config to /path/to/project/.qwen/mlflow-tracing.json

Next steps
  1. Start the MLflow tracking server in a separate terminal:
       mlflow server --port 5000
  2. Launch qwen — traces appear at https://:5000 after each turn.

使用 --non-interactive / -y 参数可跳过交互式流程并使用默认值。

注意

旧版本 Qwen Code（0.14 之前）默认禁用钩子系统，需要顶级配置 "hooksConfig": { "enabled": true } 才能开启。当前版本会忽略该设置并无条件运行钩子——如果已配置，保留它也是安全的，但已不再需要。

第 3 步：启动 MLflow 追踪服务器

必须运行 MLflow 服务器才能接收追踪记录。请在另一个终端中启动它

bash

mlflow server --port 5000

第 4 步：启动 Qwen Code

bash

qwen

每次对话轮次完成后，追踪记录将在 https://:5000 可见。

注意

MLFLOW_TRACKING_URI 和 MLFLOW_EXPERIMENT_ID 环境变量（如果在启动 qwen 的 shell 中设置）会覆盖写入 mlflow-tracing.json 的值。这对于 CI 中的一次性覆盖或在本地与 Databricks 端点之间切换非常方便。

工作原理

1. 停止钩子（Stop hook）在每个 Qwen Code 对话轮次后触发
2. Qwen 通过标准输入（stdin）传递会话 ID 和转录路径
3. 该插件读取按时间顺序排列的 ChatRecord JSONL 转录文件，并根据 callId 将每个 functionCall 与其 tool_result 进行匹配
4. 创建的 MLflow 追踪包含一个 AGENT 根 Span（qwen_code_conversation）以及 LLM/TOOL 子 Span。LLM Span 使用 OpenAI 聊天格式（{model, messages} 输入，{choices} 输出）

配置示例

通过 mlflow-qwen-code setup 或直接编辑 ~/.qwen/mlflow-tracing.json 来写入这些值

本地 MLflow 服务器

json

{ "trackingUri": "https://:5000", "experimentId": "0" }

Databricks MLflow

json

{ "trackingUri": "databricks", "experimentId": "123456789" }

通过环境变量进行单次运行覆盖（优先级高于配置文件）

bash

MLFLOW_TRACKING_URI=databricks MLFLOW_EXPERIMENT_ID=123456789 qwen

Token 使用与成本

MLflow 会自动跟踪 Qwen Code 对话中每次 LLM 调用的 token 使用情况。详细信息请参阅令牌使用和成本追踪文档。

故障排除

常见问题

追踪未生效

• 确认 mlflow-qwen-code 已在 PATH 中：运行 which mlflow-qwen-code（在 npm install -g @mlflow/qwen-code 后应能找到路径）
• 确认 ~/.qwen/mlflow-tracing.json 存在并包含有效的 trackingUri。如果文件缺失或已过期，请重新运行 mlflow-qwen-code setup。
• 验证是否正在使用 Node.js 18+（支持 fetch 所必需）
• 在 0.14 之前的 Qwen Code 版本中，默认禁用钩子——添加顶级配置 "hooksConfig": { "enabled": true } 以启用它们

追踪丢失

• 追踪记录是按对话轮次创建的，而非按会话创建
• 验证 MLflow 追踪服务器是否可访问
• 检查 Qwen 调试日志（~/.qwen/debug/latest）以获取钩子执行状态

重复的追踪记录

• 确保钩子仅注册了一次——检查 ~/.qwen/settings.json 和 .qwen/settings.json 中是否有重复条目

禁用追踪

从 settings.json 中移除 hooks 部分。现有追踪记录将保留。

(在仍支持 hooksConfig 的旧版 Qwen Code 中，设置 "hooksConfig": { "enabled": false } 也可以禁用钩子系统，而无需删除条目。)