用途:为 Python 或 TypeScript 项目接入 MLflow Tracing,实现可观测性。作为工作流的一部分需要配置追踪时加载。
语言选择:Python 项目读 references/python.md;TypeScript/JavaScript 项目读 references/typescript.md。若不确定,检查项目中的 package.json(TypeScript)或 requirements.txt/pyproject.toml(Python)。
应追踪的操作:根操作(主入口、顶层流水线、工作流步骤,用于端到端延迟与输入输出日志)、LLM 调用(聊天补全、嵌入,用于 token 用量与提示/响应检查)、检索(向量库查询、文档获取、搜索)、工具/函数调用(API、数据库查询、网络搜索)、智能体决策(路由、规划、工具选择)、外部服务(HTTP API、文件 I/O、消息队列)。应跳过的操作:简单数据变换、字符串格式化/解析/校验、配置加载与环境设置、日志或指标输出、纯工具函数。原则是只追踪对调试和定位问题重要的操作。
验证:接入后必须验证追踪生效。运行接入代码使至少一个被追踪操作触发;用 mlflow.search_traces() 或 MlflowClient().search_traces() 确认追踪出现在实验中;再确认 span 被捕获而非空壳。若未出现追踪,依次检查:是否在运行前调用 mlflow.set_tracking_uri(...)、autolog 是否有告警、实验 ID 是否正确、网络/认证是否可达。自动化校验可使用 agent-evaluation/scripts/validate_tracing_runtime.py。计划运行 agent-evaluation 前必须确保追踪已工作。
反馈收集:参见 references/feedback-collection.md,包括用 mlflow.log_feedback() 记录用户评分与评论、捕获 trace ID 返回客户端、LLM-as-judge 自动评估。
生产部署:参见 references/production.md,包括环境变量配置、低延迟应用的异步日志、采样配置(MLFLOW_TRACE_SAMPLING_RATIO)、轻量 SDK(mlflow-tracing)、Docker/Kubernetes 部署。
高级与分布式:参见 references/advanced-patterns.md(异步函数追踪、多线程上下文传播、span 处理器做 PII 脱敏)与 references/distributed-tracing.md(跨服务传播追踪上下文、客户端/服务端头部 API)。