experiment-analyzer

统一实验分析器

分析一个或两个大模型实验。根据输入支持四种模式：

输入	模式
2 个 ID，无问题	对比探索
2 个 ID + 问题	对比问答
1 个 ID，无问题	单项探索
1 个 ID + 问题	单项问答

用法

/experiment-analyzer <experiment_id_1> [experiment_id_2] [question text] [--output agent|file|notebook]

参数：$ARGUMENTS

可用工具

工具	用途
mcp__datadog-llmo-mcp__get_llmobs_experiment_summary	获取事件总数、错误数、指标统计和可用维度
mcp__datadog-llmo-mcp__list_llmobs_experiment_events	使用筛选条件、排序和分页查询事件
mcp__datadog-llmo-mcp__get_llmobs_experiment_event	获取完整事件详情（输入、输出、预期输出、指标）
mcp__datadog-llmo-mcp__get_llmobs_experiment_metric_values	获取整体指标统计，以及按维度细分的统计
mcp__datadog-llmo-mcp__get_llmobs_experiment_dimension_values	列出某个维度的唯一值及其计数
mcp__datadog-mcp-core__create_datadog_notebook	将报告导出为 Datadog Notebook

---

阶段 0 — 确定模式和输出方式

解析 $ARGUMENTS：

1. 提取一个或两个 UUID 格式的字符串作为实验 ID（第一个为基线/主要实验，第二个为候选实验）。
2. 如果存在，提取 --output agent|file|notebook 标志。
3. ID 和标志之后的剩余文本为问题（如果有）。

确定模式：

• 2 个 ID + 问题 → 对比问答
• 2 个 ID，无问题 → 对比探索
• 1 个 ID + 问题 → 单项问答
• 1 个 ID，无问题 → 单项探索

确定输出模式：

如果参数中提供了 --output，使用该模式并跳过询问。

否则，在继续之前发送一条合并的澄清消息。只询问确实不明确的事项：

• 如果模式不明确（例如，用户在周边上下文中提出了问题，但只提供了 ID），请用通俗语言询问：“您有具体问题想了解，还是希望进行探索性分析？”
• 如果未指定输出目标，始终询问：“您希望我将结果保存到文件、导出到 Datadog Notebook，还是直接显示在此聊天中？”

切勿分多轮澄清。一条消息应涵盖所有未解决的问题。

输出模式：

1. Agent（默认）： 在对话中显示完整报告。
2. 文件： 开始之前，建议一个路径： evals/reports/YYYY-MM-DD-<experiment-slug>-analysis.md 将路径告知用户，让他们确认或修改。然后继续。
3. Notebook： 在最后使用 mcp__datadog-mcp-core__create_datadog_notebook。 如果工具不可用，则输出以下设置说明，而不是直接失败：

   To enable Datadog notebook export, add the MCP server:
     claude mcp add --transport http datadog-mcp https://mcp.datadoghq.com/api/unstable/mcp-server
   See: https://docs.datadoghq.com/bits_ai/mcp_server/setup/
   

   然后询问：“您想改为文件或 Agent 输出吗？” 完整的 Notebook 调用详情请参见阶段 5。

确定模式和输出方式后，无需再与用户交互，即可全自动完成阶段 1–5。

---

阶段 1 — 初步了解

对比分析： 对两个实验分别调用 get_llmobs_experiment_summary。进行并排比较：

• 规模：各自的事件总数和错误率
• 指标：各自包含哪些指标；哪些指标共有
• 维度：各自包含哪些维度；哪些维度共有
• 明显风险：错误率高、缺少指标、数据稀疏
• 从摘要层面即可看出的明显改进或退步

单项分析： 调用实验的 get_llmobs_experiment_summary。确定：

• 事件总数、错误数、错误率
• 可用指标（归类为精确匹配或评分标准/质量指标）
• 可用于细分分析的维度
• 任何明显风险

---

第 2 阶段 — 信号发现 + UI 链接

对比： 仅使用双方共有的指标和维度，识别：

• 候选版本优于基线的细分群体
• 候选版本出现退化的细分群体
• 一方存在而另一方罕见的错误类型
• 分布变化或覆盖缺口
• 权衡（例如，召回率更高、精确率更低）

生成 Datadog 对比 UI 链接：

• 基础 URL：https://app.datadoghq.com/llm/experiment-comparison
• 必需参数：baselineExperimentId、experimentIds（candidate%2Cbaseline）、tableView=all
• 可选参数（若能找到则包含）：project、compareDatasetId、selectedEvaluation
• selectedEvaluation 优先级：overall/overall_score/评分标准指标 → 主要指标 → 第一个共有指标
• 生成 2–4 个链接：主要对比、退化视图、校准视图（如适用）、最差细分群体视图（仅在支持时——切勿伪造筛选条件）

单次实验： 衡量所有维度下各项指标的表现。识别：

• 表现最差的细分群体（按指标 × 维度）
• 通过率异常的细分群体
• 整体通过率和方差

生成 Datadog 实验 UI 链接：

• https://app.datadoghq.com/llm/experiments/{experiment_id}

---

第 3 阶段 — 深入分析

自动执行所有必要的深入分析。不要请求批准或暂停。

问答模式： 围绕直接回答问题所需的信息开展深入分析。提取具体事件，按相关维度细分，并检查示例。

探索模式： 广泛调查最有意思的信号：

• 按细分群体和类别分析差值（对比模式），或分析通过率（单次实验模式）
• 分析重叠错误与独有失败模式
• 抽样并定性检查具有代表性的失败案例（每个问题 2–5 个）
• 对错误主题进行聚类分析

规则：

• 优先开展成本低、信号强的分析；不要过早停止。
• 对所有输出中的个人身份信息（PII）进行掩码处理或删改。
• 避免破坏性操作。

为每个抽样事件生成直接的 span 链接： https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&sp=[{"p":{"experimentId":"{experiment_id}","spanId":"{span_id}"},"i":"experiment-details"}]&spanId={span_id}

为每个深入分析的细分群体生成链接，以便在（候选版本）实验中查看相关事件： https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value} 如果无法确定该维度的筛选 URL 格式是否有效，请省略筛选参数，改为链接到实验根页面。切勿伪造筛选 URL。

---

第 4 阶段 — 综合分析

对比探索模式：

• 候选版本优于基线的明确优势
• 候选版本引入的明确退化或风险
• 持平或未发生变化的方面
• 与证据相关的根因假设（1–4 条）
• 按优先级排列的建议：按现状发布 / 阻止发布 / 按细分群体设置门控 / 组合不同的行为

对比问答模式：

• 直接回答问题并给出明确结论
• 支持性证据（指标、百分比、事件示例）
• 相关背景（例如，注意事项、数据局限）

单次实验探索模式：

• 整体表现评估
• 表现最差的细分群体及其根因
• 失败原因假设
• 建议开展的后续实验

单次实验问答模式：

• 直接回答问题并给出明确结论
• 基于实验数据的支持性证据

所有模式：尽可能使用量化差值/比率。删改 PII。

---

阶段 5 — 交付输出

Agent： 使用下方的报告格式，在对话中呈现完整报告。

文件： 将报告写入预先确认的路径。确认时说：“报告已保存到 <path>。”

Notebook： 使用以下参数调用 mcp__datadog-mcp-core__create_datadog_notebook：

• name（按模式）：

  模式	名称
  Comparative Exploratory	Experiment Analysis: {baseline_short} (Baseline) vs {candidate_short} (Candidate) — YYYY-MM-DD
  Comparative Q&A	Experiment Q&A: {baseline_short} vs {candidate_short} — YYYY-MM-DD
  Single Exploratory	Experiment Analysis: {experiment_short} — YYYY-MM-DD
  Single Q&A	Experiment Q&A: {experiment_short} — YYYY-MM-DD
  其中，short = UUID 的前 8 个字符。

• cells：将完整报告作为单个 Markdown 单元格 — [{ "type": "markdown", "text": "<full report markdown>" }]。从单元格内容中省略顶级标题 # Experiment Analysis Report，因为它已显示为 notebook 标题。

• time：{ "live_span": "1h" }

创建 notebook 后，在聊天中输出 URL：“报告已导出到 notebook：”

如果工具不可用，请遵循阶段 0 中的备用说明。

---

阶段 6 — 对话式后续跟进

交付报告后，追加一个后续跟进部分：

---
## Want to explore further?

Here are a few directions based on the findings:

1. [Specific question derived from actual findings — e.g., "Want me to dig deeper into why the SQL scenarios regressed in the candidate?"]
2. [Another specific follow-up — e.g., "Should I compare error patterns between the two failing clusters?"]
3. [A third option if relevant]

Do you have any other questions about this analysis?

报告交付后保持活跃。使用相同的 MCP 工具回答后续问题，并参考已收集的发现。除非新问题确有需要，否则不要重新运行已完成的分析。

---

报告格式

链接规则：

• 实验 ID：凡出现完整实验 UUID，都将其渲染为指向 https://app.datadoghq.com/llm/experiments/{full_uuid} 的 Markdown 链接。
• 对比表格列标题：在 Orientation 表格以及之后所有包含 Baseline/Candidate 列的表格中，将整个列标题设为链接，而不只是短 ID。格式：[Baseline \{short_id}`]({baseline_url})和Candidate `{short_id}``。这样整个标题单元格都可点击，而不只是 ID 部分。

# Experiment Analysis Report

> **Question:** {original question text}
> _(Q&A modes only — omit for Exploratory modes)_

## Summary & Recommendations

[Comparative: **Baseline**: [`{baseline_short}`]({baseline_url}) | **Candidate**: [`{candidate_short}`]({candidate_url}) | **Compare**: [`{baseline_short}-{candidate_short}`](https://app.datadoghq.com/llm/experiment-comparison?baselineExperimentId={baseline_id}&experimentIds={candidate_id}%2C{baseline_id}&tableView=all&selectedEvaluation=pass) — Single: **Experiment**: [`{experiment_short}`]({experiment_url}). Always the first line of this section.]

[2–3 sentence executive summary directly below the links line. Open with "This is a **{Mode}** analysis..." where {Mode} is one of: Comparative Exploratory, Comparative Q&A, Single Exploratory, Single Q&A. Include experiment(s) purpose, scale, and key finding with specific numbers.]

[If the report uses opaque dimension values (e.g. category labels like b1/b2/b3/bx), add a `### Dataset Categories` subsection here. Include: one sentence explaining where the categories come from (i.e. labels from the evaluation dataset grouping questions by required tools/data sources), then a bullet per value with its name bolded and a brief description. Infer descriptions from input question patterns, capability tags, and expected tool calls. Omit this subsection if all dimension values are self-explanatory.]

[Wins, regressions, neutral areas, prioritized actions. For Q&A: verdict + rationale.]

## Orientation

[Side-by-side table for comparative; summary table for single. Include: events, error rate, metrics, dimensions. Experiment IDs in column headers must be Markdown links.]


## What Changed

[Comparative modes only. Table of differences between baseline and candidate: model, toolset/skill profile,
dataset, evaluator schema, and any other metadata differences detectable from the summary data.
If no differences are detectable, write: "No configuration differences detected between experiments."]

## [Signals | Answer to Question]

[For exploratory: ranked table of signals/segments with metric deltas and impact counts.]
[For Q&A: direct answer with verdict, then supporting evidence.]

## Deep Dive Findings

### [Issue/Finding Title]

**Segment**: `[dimension=value]` | **Impact**: N events | **Severity**: metric pass rate = X% | [View events](https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value})

**What's happening**: [1–2 sentences: key observation and metric impact only]

**Representative examples**:
- [Span link]: [input → output → expected, what went wrong]

**Root cause hypothesis**: [Category]: [Explanation tied to evidence]

**Recommendation**: [Specific, actionable next step]

---
[Repeat for each major issue]

## UI Links

[All generated Datadog UI links with labels]

---

操作规则

• 不要对实验作任何假设（模型、任务、指标、架构、维度）。通过检查数据推断所有信息。
• 所有结论都必须以具体证据为依据：事件 ID、数量、百分比。
• 展示计算过程：包含数量和比率，不能只给出定性结论。
• 避免提出缺乏观测证据支持的推测性解释。
• 在所有面向用户的输出中遮盖或删去个人身份信息（PII）。
• 切勿向用户展示内部工具调用、架构或实现细节。
• MCP 结果解析安全性：在编写任何用于遍历或访问 MCP 工具结果字段的脚本（Python、jq 等）之前，先检查原始结构——查看 type(result)、顶层键，以及负载是否嵌套在内容块中（例如 [{'type': 'text', 'text': '<json>'}]）。如有需要，先提取内部负载并使用 json.loads() 解析，再进行处理。切勿假设 MCP 结果一定是裸 dict 或列表。