ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

MLflow Qwen Code 集成指南:自动追踪编程智能体完整会话的 Tracing 实战

MLflow Qwen Code 集成指南:自动追踪编程智能体完整会话的 Tracing 实战 MLflow Qwen Code 集成指南自动追踪编程智能体完整会话的 Tracing 实战【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow本指南基于 MLflow 仓库中的 libs/typescript/integrations/qwen-code/README.md完整讲解如何通过mlflow/qwen-code这个 NPM 包将 Qwen Code 编程智能体的每次对话回合用户提示、助手响应、工具调用与结果、Token 消耗自动记录为 MLflow Trace。读完本文你将掌握集成包的安装、一键配置、配置解析优先级以及底层从 JSONL 转录文件到 AGENT/LLM/TOOL 三层 Span 的完整链路能够在自己或团队的 Qwen Code 工作流中落地可观测性。一、集成概览这个包解决什么问题mlflow/qwen-code是 MLflow Typescript SDK 体系mlflow/core的一个自动插桩集成包面向 Qwen Code 这一编程智能体coding agent。它的核心价值在于零侵入自动追踪不需要修改 Qwen Code 源码只需注册一个 Qwen Code 的Stop钩子每轮对话结束时自动触发追踪采集完整会话语义记录用户提示user prompt、助手响应assistant response、工具调用tool usage以及 Token 消耗token consumption而不是只记录孤立的 LLM 请求回合级实时可见每一次对话回合结束即可看到该回合的 Trace无需等整个 session 结束。从 package.json 可以看到该包当前版本为0.4.0唯一运行时依赖是mlflow/core^0.4.0通过bin字段将mlflow-qwen-code命令暴露为全局 CLI。构建产物分为distTypeScript 编译产物main指向dist/index.js与bundleesbuild 打出的可直接执行 CLI 包。二、工作原理Stop 钩子 JSONL 转录 → MLflow Trace理解这个集成先要看清三条信息流的走向钩子注册mlflow-qwen-code setup把一条Stop钩子写入 Qwen Code 的settings.json钩子命令是mlflow-qwen-code stop-hook见 src/commands/setup.ts 的HOOK_COMMAND常量钩子触发Qwen Code 在每次会话回合结束时通过 stdin 向该命令推送一段 JSON 载荷包含session_id、transcript_path、cwd、timestamp等字段见 src/types.ts 的StopHookInput定义转录解析stop-hook命令读取transcript_path指向的 JSONL 文件解析出最后一轮对话重建为 OpenAI Chat 格式的消息序列再以 AGENT/LLM/TOOL 三层 Span 的结构写入 MLflow。2.1 转录文件长什么样Qwen Code 会把聊天记录写到~/.qwen/projects/project-id/chats/sessionId.jsonl见 src/transcript.ts 的注释。每一行是一条ChatRecord按时间顺序输出同时带uuid/parentUuid供树形遍历。消息体采用 Gemini 风格{role, parts: [...]}信封parts有三种形态见 src/types.ts{text, thought?}—— 文本thought: true表示内部推理chain-of-thought不会渲染到 Chat 视图{functionCall: {id, name, args}}—— 模型发起的工具调用{functionResponse: {id, name, response}}—— 工具结果返回给模型。工具结果还会以独立的type: tool_result记录出现携带toolCallResult: {callId, status, resultDisplay}块通过callId与助手的functionCall配对。仓库中的测试样例 tests/fixtures/with-tool-call.jsonl 展示了一条用户要求列目录 → 模型调用list_directory→ 返回三个文件的完整回合包含thought文本、functionCall、tool_result以及累计的usageMetadata是理解转录结构的绝佳素材。2.2 生成的 Trace 结构processTranscript见 src/tracing.ts把最后一轮对话转换为一棵三层 Span 树AGENT qwen_code_conversation ├─ LLM llm_call 每条 assistant 记录一个OpenAI Chat 格式的 messages tool_calls └─ TOOL tool_name 每个 functionCall 一个按 callId 与 tool_result 配对根 Span 名为qwen_code_conversation类型为AGENTinputs直接传用户提示的原始字符串便于 MLflow 自动生成干净的请求预览每条 assistant 记录生成一个名为llm_call的LLMSpaninputs是截至该记录为止重建的 OpenAI Chat 消息历史含此前工具结果outputs为{choices: [{message: {...}}]}形态每个functionCall生成一个名为tool_name的TOOLSpaninputs为调用参数outputs为工具结果字符串优先取toolCallResult.resultDisplay缺失时回退到functionResponse.response见 src/transcript.ts。工具调用的失败状态会被如实反映当tool_result.status不是successQwen Code 实际观测到success与cancelled两种取值其余值防御性视为失败时对应 TOOL Span 会被标记为ERROR状态错误消息为Tool call status见 src/tracing.ts方便在 Trace UI 中一眼定位被用户取消或被拒绝的工具调用。2.3 Span 的时序模型为了让时间轴贴合真实执行过程集成采用了与 codex 集成一致的计时模型见 src/tracing.tsLLM Span从上一个边界回合第一条记录或最近一条tool_result的时间戳到本条 assistant 记录的时间戳——即模型在拿到全部所需上下文后产出该响应的区间TOOL Span从 assistant 记录时间戳到按callId匹配到的tool_result时间戳若工具结果缺失工具仍在执行中回退到 assistant 时间戳。时间戳由 ISO 字符串统一换算为纳秒毫秒 × 1e6见 src/transcript.ts。三、安装npm install -g mlflow/qwen-code该命令会在全局安装mlflow-qwen-codeCLI。如果不想全局安装可以改用npx mlflow/qwen-code调用后续所有命令的用法完全一致。前置要求将 Trace 数据落到自建 MLflow Tracking Server 需要 Python 3.10 及以上版本若本机没有现成服务端也可以使用托管版 MLflow 服务快速起步。四、快速开始4.1 启动 MLflow Tracking Server若还没有可用的 Tracking Server先启动一个pip install mlflow mlflow server --port 50004.2 运行交互式配置mlflow-qwen-code setup该命令会做两件事见 src/commands/setup.ts注册 Stop 钩子在 Qwen Code 的settings.json的hooks.Stop下追加一条{type: command, command: mlflow-qwen-code stop-hook}并保留文件中无关字段不动若钩子已存在则跳过写入并给出警告持久化追踪配置把 MLflow 的trackingUri与experimentId写入mlflow-tracing.json这样钩子在无 shell 环境变量导出时也能独立运行。交互式运行时会先让你在两种安装范围中二选一Project项目级写入./.qwen/默认选项User用户级写入~/.qwen/对所有项目生效。随后依次提示输入 MLflow tracking URI默认http://localhost:5000与 experiment ID默认0。tracking URI 会做严格校验必须是绝对http://或https://URL形如localhost:5000这类缺协议写法会被拒绝校验逻辑见 src/commands/setup.ts 的isValidTrackingUri。4.3 非交互式配置CI/脚本友好跳过所有提示使用默认值或显式覆盖mlflow-qwen-code setup -y --tracking-uri http://localhost:5000 --experiment-id 0setup命令支持的完整参数如下见 src/commands/setup.ts 的参数解析实现与 src/cli.ts 的用法输出参数别名作用--project-p强制安装到项目级./.qwen/跳过范围选择提示--non-interactive-y跳过全部提示未显式给出的值使用默认值--tracking-uri url—直接指定 tracking URI跳过对应提示--experiment-id id—直接指定 experiment ID跳过对应提示非交互模式下默认安装到项目级与交互模式的默认项保持一致-p也可以与-y组合使用。4.4 正常使用 Qwen Codeqwen help me refactor this function此后每一轮对话回合结束MLflow 都会记录一条包含消息历史、工具调用与结果、Token 消耗的 Trace——不需要等待整个 session 结束。setup 完成后命令还会打印下一步提示在独立终端启动对应端口的mlflow server然后在qwen中开始对话Trace 即出现在指定 tracking URI 上见 src/commands/setup.ts。五、配置解析优先级mlflow-qwen-code钩子按以下顺序解析配置先命中者优先见 src/config.ts 的resolveTracingConfig实现环境变量MLFLOW_TRACKING_URI/MLFLOW_EXPERIMENT_ID./.qwen/mlflow-tracing.json项目级~/.qwen/mlflow-tracing.json用户级tracking URI 与 experiment ID 两个字段分别独立按此顺序解析读取 JSON 文件时若文件不存在或解析失败均按空配置处理不阻断运行src/config.ts。5.1 用环境变量做一次性覆盖环境变量适合临时切换目标比如在本地 server 与 Databricks workspace 之间切换MLFLOW_TRACKING_URIdatabricks MLFLOW_EXPERIMENT_ID123456789 qwen ...5.2 未配置时的行为如果三个来源都拿不到 tracking URIensureInitialized会在 stderr 打印排查指引提示已检查过的三个位置并建议运行mlflow-qwen-code setup然后直接返回而不初始化 SDKsrc/config.ts避免产生无主 Trace。六、深入实现Token 聚合与元数据6.1 Token 消耗的防重复计算这是集成中最值得一提的细节。Qwen Code 转录中每条 assistant 记录都带usageMetadataGemini 风格键promptTokenCount/candidatesTokenCount/totalTokenCount偶尔出现 OpenAI 风格input_tokens/output_tokens回退见 src/types.ts。其中promptTokenCount是累计值——每条 assistant 记录报告的 prompt 都包含此前全部 user/assistant/tool 上下文。如果简单地逐条相加多工具回合的输入 Token 会被虚增 23 倍。因此aggregateTokenUsagesrc/tracing.ts采取的策略是输入 Token取最后一条 assistant 记录的promptTokenCount即模型最终处理过的累计 prompt输出 Token累加所有 assistant 记录的candidatesTokenCount总计两者相加。同时每个llm_callSpan 上仍保留该次 API 调用自身的账单级用量src/tracing.ts做到回合级去重、调用级原样。6.2 会话与用户元数据Trace 创建后集成通过InMemoryTraceManager直接给traceMetadata附加mlflow.trace.session会话 ID缺失时回退为qwen-时间戳与mlflow.trace.user取$USER两个键src/tracing.ts。之所以不调用updateCurrentTrace()是因为钩子型集成没有活动中的 OTel Span 上下文——这与 codex/opencode 集成采用同一模式。七、测试与验证仓库为这个集成提供了较完整的单元测试覆盖tests/tracing.test.tsmockmlflow/core验证多工具回合下 AGENT/LLM/TOOL Span 的创建顺序、父子关系、时间戳、token 属性、traceMetadata 以及工具失败状态transcript.test.ts验证 JSONL 解析、getLastTurnRecords的回合切分、buildToolResultMap的 callId 配对等工具函数setup.test.ts验证--project/-y/--tracking-uri/--experiment-id参数解析与 tracking URI 校验。配套的三个 fixturebasic.jsonl、with-tool-call.jsonl、with-cancelled-tool.jsonl分别覆盖纯对话、含工具调用、工具被取消三种真实转录形态其中with-cancelled-tool.jsonl正是用于验证非 success 状态被标记为 ERROR这一行为的样例。开发时可用npm test运行 Jest 测试套件见 package.json 的 scripts。八、License本集成包与整个 MLflow 项目一致遵循 Apache License 2.0 开源许可见 libs/typescript/integrations/qwen-code/README.md。九、小结与延伸阅读mlflow/qwen-code以注册一个 Stop 钩子 解析一份 JSONL 转录的轻量设计把 Qwen Code 的每一次编程会话回合变成结构化的 MLflow TraceAGENT 根 Span 承载用户提示与最终回复LLM Span 保留 OpenAI Chat 格式的消息历史TOOL Span 忠实记录每次工具调用的入参、出参与成败状态Token 消耗在回合级做了去重聚合。整体思路与 MLflow Typescript SDK 下 codex、opencode、Claude Code 等编程智能体集成一脉相承。想进一步深入可以阅读 mlflow/qwen-code 的 README 与 src/cli.ts 了解 CLI 子命令全貌对照 src/tracing.ts 与 src/transcript.ts 研究 Span 结构与解析细节参考 libs/typescript/integrations/ 下其他编程智能体集成对比不同 agent 的追踪建模方式。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表