opik-evaluate

评估 — 构建评估并运行

完成标准：在 Opik 中生成一个带评分的实验、其实验链接，以及一份用户可据此采取行动的评分摘要——通过在一组案例上运行用户的应用（或提示词），并针对真实故障模式进行评分来生成。如果无法构建或运行评估，请在遇到第一个真实阻碍时停止，并且只返回一个下一步。没有运行的 dataset、没有评分的评审提示词，或纯文字计划，都不算成功。

操作方式：**根据实际故障构建案例，先用代码评分，再使用评审模型；每次只评估一种故障模式；端到端运行一次；从 Opik 读取评分——不要更改应用代码。**此技能写入的唯一文件是仓库外的运行器。

输入

入口为 /opik-evaluate（评估此仓库中的应用）、/opik-evaluate <what>（“RAG 答案”“退款流程”），或 /opik-evaluate <dataset-or-suite>（针对现有案例运行）。推断其余信息；将以下内容视为可选覆盖项：

• 案例来源（默认：现有套件／dataset → 最近的 traces → 合成数据）· 评分方式（默认：存在预期输出时使用启发式方法，否则针对每种故障模式使用一个评审模型）· 方法（默认：Agent 使用测试套件；需要内置指标或精确匹配时使用 dataset + evaluate()）· 评审模型 · 样本量（默认：20–50 项）。

仅在确实存在无法推断的阻碍时提问（参见阻碍）。

激活 — 唯一允许处理的工作

1. 确定目标

确认 Opik 可访问（~/.opik.config 或 OPIK_API_KEY；否则 → 阻碍）。找到要评估的入口（trace 根 span 所命名的函数，或用户指定的函数）。检查现有内容——client.get_test_suites(project_name=…)、client.get_datasets()——优先复用，再创建。

**已经有评估了吗？**先审查（references/eval-audit.md）：评审模型未经验证、没有错误分析、指标虚高。先修复最严重的问题，再运行。

2. 根据故障构建案例（错误分析）

在编写任何评分器之前，先读取真实 traces——client.search_traces(project_name=…, max_results=100)（优先查看错误、低分和耗时较长的记录）。归类故障类型并统计频率（references/error-analysis.md）。如果还没有 traces → 生成案例（references/generate-synthetic-data.md），并在报告中说明。

3. 选择形式

情况	使用
Agent／聊天机器人，预期表现是行为（“提及巴黎”“拒绝提供法律建议”）	测试套件——条目 + 由评审模型检查的字符串断言；opik.run_tests()
预期输出精确，或使用内置指标（Hallucination、AnswerRelevance、RAG ContextPrecision/ContextRecall）	使用 scoring_metrics 的 Dataset + evaluate()
被测对象是提示词版本，而非代码	服务端：client.rest_client.experiments.execute_experiment(...)——无需运行器

Agent 优先使用测试套件；/opik-test 和 /opik-compare 都是针对测试套件操作的。

4. 构建案例

import opik
client = opik.Opik()

suite = client.get_or_create_test_suite(
    name="<project>-eval", project_name="<project>",
    global_assertions=["<one behavior every answer must show>"],   # optional
)
suite.insert([
    {"data": {"input": t.input, "source_trace_id": t.id}, "assertions": ["<what a correct output does>"]}
    for t in sampled_traces
])

对于 dataset 路径：使用 client.get_or_create_dataset(name, project_name)，然后使用 dataset.insert([{"input": …, "expected_output": …}])。原样保存输入；保留 source_trace_id，以便将案例追溯到生产环境。

5. 定义评分

1. **先用代码。**只要检查可以通过机械方式完成，就使用 opik.evaluation.metrics 中的 Equals、Contains、RegexMatch、IsJson、JsonSchemaMatch、LevenshteinRatio。
2. 然后针对每种故障模式使用一个评审模型，进行二元通过／失败判断，依据第 2 步中的故障类别（references/write-judge-prompt.md）。可将其作为测试套件断言，或在 dataset 路径中用作 GEval／自定义 BaseMetric。
3. **RAG：**分别评估检索和生成（references/evaluate-rag.md）。
4. 在重要场景中信任评审模型之前，先用一些人工标注进行校准（references/validate-evaluator.md）——看 TPR/TNR，而非准确率。

6. 运行

将任务适配器写入仓库外部的临时文件（需要应用的提供方凭据——缺少凭据即为阻塞项）。切勿运行会写入、发送或消耗资源的生产入口点。

# Test suite
results = opik.run_tests(test_suite=suite, task=lambda item: {"input": item["input"], "output": str(app(item["input"]))},
                         experiment_name="baseline-<sha>", model="<judge model>",
                         generate_report=False)   # default True writes opik_test_suite_reports/ into cwd — keep the repo clean
# Dataset
from opik.evaluation import evaluate
res = evaluate(dataset=dataset, task=task, scoring_metrics=[...], experiment_name="baseline-<sha>",
               scoring_key_mapping={"reference": "expected_output"})   # map dataset keys onto metric args

project_name 很重要：数据集、测试套件、提示词和实验都按项目划分；如果应用使用 @track，它必须与跟踪项目匹配。创建数据集或测试套件时就要设置此项——evaluate() 会继承数据集所属的项目，其自身的 project_name 参数已弃用（SDK 会发出警告并忽略它）。

评判器凭据检查：如果 LLM 评判器（测试套件断言或 LLM 指标）没有提供方密钥，run_tests/evaluate 不会抛出异常——每个条目的得分都会是 0，且 scoring_failed=True，原因是 "Missing credentials"，并且仍会创建实验。报告前请先检查；这是一个阻塞项（“设置评判器的提供方密钥并重新运行”），不是评估结果。

7. 读取分数

exp = client.get_experiment_by_id(results.experiment_id)     # or res.experiment_id
items = exp.get_items()   # dataset_item_data, evaluation_task_output, feedback_scores [{name,value,reason}], assertion_results [{passed,reason}], trace_id
# aggregate: mean per score name; pass rate = items where every assertion passed / items with assertions

在数据集路径上，res.aggregate_evaluation_scores().aggregated_scores 可直接提供每项指标的统计数据。指出最差的条目及各自遇到的失败模式——这才是可采取行动的部分。（get_experiment_by_name 已弃用；请使用 get_experiments_by_name / get_experiment_by_id。）

8. 报告

实验链接、分数表、三个最差条目及其原因、用例的依据来源（跟踪记录还是合成数据），以及一个后续步骤（参见 输出）。本次运行是 /opik-compare 将用于比较的基线。

阻塞项

遇到最早的阻塞项时停止，并且只返回一个后续步骤：

• "运行 opik configure，然后重新运行 /opik-evaluate。"
• "你希望评估哪个函数？请指出入口点（例如 answer(question)）。"
• "运行器需要提供方凭据——设置 OPENAI_API_KEY（或相关密钥）并重新运行。"
• "目前既没有跟踪记录，也没有用例——请提供 5–10 个示例输入（如果知道，也请提供预期行为），或者说 synthetic，我会生成用例。"

输出

**面向用户：**简短的用户消息——包括实验链接、分数表、带原因的最差条目、用例来源，以及唯一的后续步骤。不要原样转储所有条目。

底层（用于组合 / 评估），采用以下一种结构：

• status：evaluated | blocked
• shape：test_suite | dataset | server_side
• cases：name、id、count、source（traces | provided | synthetic | existing）
• scoring：{name, kind: heuristic|judge|assertion, failure_mode} 列表
• experiment：id、name、url、project
• scores：{metric, value} 列表（包含通过率）
• worst：{dataset_item_id, input, score_or_assertion, reason, trace_url} 列表
• next_step：且仅有一个

不变量：evaluated 必须包含 experiment.url 和非空的 scores；scoring 中的每个评判器都必须指定一个 failure_mode；blocked 必须且只能包含一个 next_step；任何路径都不得更改代码库。

示例

Agent，基于追踪记录。 /opik-evaluate。读取 100 条追踪记录：30% 给出了错误的退款期限，10% 编造了政策。测试套件 support-bot-eval，包含从追踪记录中提取的 40 个条目，断言为“说明退款期限为 5–7 个工作日”和“不编造文档中未提及的政策”。构建运行器，run_tests → 27/40。读回结果：表现最差的条目都未通过退款断言。→ evaluated；下一步 = “无需使用 /opik-test——测试套件已存在；修复 retrieve()，然后运行 /opik-compare support-bot-eval”。

RAG，数据集路径。 /opik-evaluate the RAG answers。数据集包含 input、expected_output、context；使用 ContextPrecision、ContextRecall、Hallucination 执行 evaluate()。召回率 0.61 是薄弱环节。→ evaluated；下一步 = “提高 top-k / 修复检索器，然后运行 /opik-compare”。

仅提示词。 目标是库中的提示词版本。使用变体执行 execute_experiment；轮询直至填入所有条目；读回结果。→ evaluated，且 shape: server_side。

受阻。 无法从仓库推断入口点。→ blocked：“应该评估哪个函数？”

核心原则

• 先分析错误，再编写评估器。 未先阅读追踪记录，绝不编写评分器。
• 先做代码检查，再用 LLM 裁判。 凡是能通过机械方式检查的地方，都使用启发式指标。
• 二元通过/失败，每个裁判只判断一种失败模式。 整体性裁判给出的结论无法指导行动。
• 在用裁判把关之前，先根据人工标签验证裁判（TPR/TNR）。
• 始终在创建对象时传入 project_name。 适用于 get_or_create_dataset、get_or_create_test_suite、create_prompt。evaluate() 和 run_tests() 会从数据集/测试套件继承该值（evaluate(project_name=…) 参数已弃用）。
• 从 Opik 读取结果，而不是从 stdout 读取——这样 /opik-compare 之后读取的就是相同的数据。

反模式

尚未阅读任何追踪记录就构建裁判；使用“质量 1–10”裁判；用裁判对 Equals 能检查的内容打分；创建没有运行记录的数据集；报告汇总结果却不指出最差案例；将运行器写入仓库；修改应用代码以通过评估；省略 project_name；使用已弃用的 get_experiment_by_name。

参考资料

本技能自身参考资料中的方法论：references/eval-audit.md（审查现有流水线）、references/error-analysis.md（根据追踪记录分类失败）、references/generate-synthetic-data.md（基于维度生成输入）、references/write-judge-prompt.md（二元裁判）、references/validate-evaluator.md（TPR/TNR 校准）、references/evaluate-rag.md（检索与生成）。

SDK 详情位于与本技能一同安装的 opik 技能中——相对于此文件的路径：../opik/references/evaluation-test-suites.md（测试套件、run_tests、结果）、../opik/references/evaluation-datasets.md（evaluate()、60+ 指标、OQL、从追踪记录创建数据集）、../opik/references/production.md（search_traces）。如果你的宿主以不同方式组织技能，请找到 opik 技能的 references/ 目录。

如果未安装 opik 技能，请在报告中说明，并使用 https://www.comet.com/docs/opik/，不要凭记忆作答。