SuperAPI AI 工具集

analyzing-mlflow-trace

测试与质量

查看项目

更新于 10-16 05:05

技能介绍

用途:分析单条 MLflow trace,回答用户关于该 trace 的调试、排查与根因定位问题,适用于用户提供 trace ID 并希望调查 AI/ML 应用执行情况的场景。

主要能力:trace 以 span 树记录一次 AI/ML 应用执行的完整过程,每个 span 代表一次操作(LLM 调用、工具调用、检索步骤等),记录输入、输出、耗时与状态;trace 还携带 assessments(人工或 LLM 评审的质量反馈)。技能可读取 trace 结构、检查状态、定位错误 span、解读 assessments 与 rationale、分析 span 时序与 token 用量,并将 trace 内容与源码关联以更精确地定位根因。

使用方式:建议先阅读 references/trace-structure.md 了解完整数据模型。获取 trace 时始终重定向到文件,不要把 mlflow traces get 直接管道给 jq、head 等命令,否则可能静默无输出: mlflow traces get --trace-id <ID> > /tmp/trace.json 随后用 jq 解析文件,例如 jq '.info.state' /tmp/trace.json、jq '.data.spans | length' /tmp/trace.json。优先获取完整 trace 再解析 JSON,而非使用 --extract-fields,因为该参数对嵌套 span 数据支持有限。trace JSON 顶层为 info(元数据、assessments)与 data(spans)。span 输入输出存放在 attributes 中的序列化 JSON 字符串里,如 mlflow.spanInputs、mlflow.spanOutputs;第三方 OpenTelemetry 客户端可能使用不同属性名。若路径不匹配,可用 jq 'keys'、jq '.data.spans[0] | keys' 等发现结构。

分析要点:state 为 OK 仅表示无未处理异常,不代表输出正确;应检查 assessments 的质量信号,无 assessments 时直接分析输入输出与中间 span。解读 assessment 值必须结合 rationale,值本身可能有歧义。assessment 的 error 表示评分器失败,而非 trace 本身有问题。span 时序可揭示性能问题,重复 span 名可能表示重试,token 用量可解释延迟与成本。span 名通常对应被 @mlflow.trace 装饰或 mlflow.start_span() 包裹的函数,自动记录的 span 遵循框架命名约定;span 树镜像调用栈,输入输出对应函数参数与返回值。

限制:资料未提供该技能的安装方式、收费、平台支持范围与具体版本兼容性信息;trace 结构可能随 MLflow 版本变化,第三方客户端属性名可能不同,需自行核对原始 attributes。