analyzing-mlflow-session

用途

该技能用于分析 MLflow 会话（session）。会话将属于同一聊天对话或用户交互的多个 trace 分组在一起，每个 trace 代表一轮对话，即用户输入与系统响应。会话内的 trace 通过存储在 trace 元数据中的共享 session ID 关联，该 ID 存放在元数据键 mlflow.trace.session 下。所有该键取值相同的 trace 属于同一会话。

主要能力

重建会话对话：从首个 trace 发现输入/输出 schema，再跨所有会话 trace 高效提取字段，并按需检查特定轮次。
识别根 span：查找 parent_span_id 为 null 的 span，检查其属性以确定承载用户输入与系统输出的键。
处理多种属性来源：MLflow 标准属性（mlflow.spanInputs、mlflow.spanOutputs）、自定义属性、第三方 OTel 属性（GenAI Semantic Conventions、OpenInference 等）。
检查评估（assessments）：会话级评估附加在会话首个 trace 上，用于评估整体对话质量与多轮连贯性；轮次级评估针对具体轮次。
区分评估错误与 trace 错误：评估含 feedback.error 表示评分器或评判器失败，而非 trace 本身有问题。
结合代码库关联：查找 mlflow.trace.session 的设置位置以理解会话创建方式；查看上下文窗口管理（滑动窗口、摘要、全量历史）；查看跨轮记忆与状态存储。
提供参考脚本：scripts/discover_schema.sh 与 scripts/inspect_turn.sh。

使用方式

重建会话对话是多步过程：

发现 schema。先找到会话中的一个 trace ID，再获取其完整 JSON 检查 schema：

mlflow traces search \
  --experiment-id <EXPERIMENT_ID> \
  --filter-string 'metadata.`mlflow.trace.session` = "<SESSION_ID>"' \
  --order-by "timestamp_ms ASC" \
  --extract-fields 'info.trace_id' \
  --output json \
  --max-results 1 > /tmp/first_trace.json

mlflow traces get \
  --trace-id <TRACE_ID_FROM_ABOVE> > /tmp/trace_detail.json

查找根 span：

jq '.data.spans[] | select(.parent_span_id == null)' /tmp/trace_detail.json

检查其 attributes 字典，识别哪些键承载用户输入与系统输出。若根 span 输入/输出为空或缺失，可能是包装 span，需查看其直接子 span：

ROOT_ID=$(jq -r '.data.spans[] | select(.parent_span_id == null) | .span_id' /tmp/trace_detail.json)

jq --arg root "$ROOT_ID" '.data.spans[] | select(.parent_span_id == $root) | {name: .name, inputs: .attributes["mlflow.spanInputs"], outputs: .attributes["mlflow.spanOutputs"]}' /tmp/trace_detail.json

检查首个 trace 的评估。会话级评估通过其 metadata 字段中存在 mlflow.trace.session 来识别：

jq '[.info.assessments[] | select(.feedback.error == null) | select(.metadata["mlflow.trace.session"]) | {name: .assessment_name, value: .feedback.value}]' /tmp/trace_detail.json

jq '[.info.assessments[] | select(.feedback.error == null) | select(.metadata["mlflow.trace.session"] == null) | {name: .assessment_name, value: .feedback.value}]' /tmp/trace_detail.json

解释评估值时始终参考 rationale：

jq '[.info.assessments[] | select(.feedback.error == null) | {name: .assessment_name, value: .feedback.value, rationale: .rationale}]' /tmp/trace_detail.json

跨所有会话 trace 提取。确定输入/输出键后，使用 --extract-fields 搜索会话中所有 trace：

mlflow traces search \
  --experiment-id <EXPERIMENT_ID> \
  --filter-string 'metadata.`mlflow.trace.session` = "<SESSION_ID>"' \
  --order-by "timestamp_ms ASC" \
  --extract-fields 'info.trace_id,info.state,info.request_time,info.assessments,info.trace_metadata.`mlflow.traceInputs`,info.trace_metadata.`mlflow.traceOutputs`' \
  --output json \
  --max-results 100 > /tmp/session_traces.json

列出各轮及其有效评估：

jq '.traces[] | {
  trace_id: .info.trace_id,
  time: .info.request_time,
  state: .info.state,
  assessments: [.info.assessments[]? | select(.feedback.error == null) | {
    name: .assessment_name,
    value: .feedback.value
  }]
}' /tmp/session_traces.json

CLI 语法要点：

所有 mlflow traces search 命令必须提供 --experiment-id。
含点的元数据键在 filter 字符串与 extract-fields 中需用反引号转义：metadata.mlflow.trace.session。
Shell 引号：双引号内的反引号会被 bash 解释为命令替换，外层字符串含反引号时应使用单引号。
--max-results 默认 100，最长对话可增至 500（上限）；返回 500 条时需分页获取其余结果。

处理 CLI 输出：MLflow trace 输出可能很大，Claude Code 的 Bash 工具对管道命令有约 30KB 输出限制，超出时会保存到文件而非管道传递，导致静默失败。安全做法是先重定向到文件，再对文件运行命令：

mlflow traces search \
  --experiment-id <EXPERIMENT_ID> \
  [...] \
  --output json > /tmp/output.json

cat /tmp/output.json | jq '.traces[0].info.trace_id'
head -50 /tmp/output.json
wc -l /tmp/output.json

切勿直接管道 MLflow CLI 输出。检查特定轮次详情：

mlflow traces get --trace-id <TRACE_ID> > /tmp/turn_detail.json

适用场景

调试聊天对话，例如用户报告聊天机器人第 5 条消息给出错误答案。
排查多轮对话中的错误传播：第 3 轮的事实错误未被质疑，第 4 轮基于错误信息，第 5 轮进一步放大，根因在第 3 轮。
分析根因轮次：获取该轮完整 trace，检查评估、遍历 span 树、查看检索器结果并与代码关联。
提出改进建议：修复检索器数据源、添加轮次级评估以在错误传播前检测、考虑实现对话级错误检测。

限制

会话 ID 的分配方式、上下文窗口管理、记忆与状态的具体实现需通过搜索代码库确定，资料未提供具体实现细节。
评估值单独看可能误导，必须结合 rationale 解释。
评估错误不等于 trace 错误。
输出处理需遵循重定向到文件的规则，避免静默失败。

技能介绍

用途

主要能力

使用方式

适用场景

限制