deepeval

DeepEval

使用此技能为 AI 应用添加端到端评估循环： 为应用添加埋点、整理或复用数据集、创建并提交 pytest 评估套件、 运行评估，并根据失败结果迭代。

前置条件

需要 Python 3.9+，并在目标项目中运行 pip install deepeval。指标 和合成数据生成需要模型凭据。Confident AI 报告、 托管追踪和在线评估需要运行 deepeval login。

工作流摘要

1. 检查目标应用和现有的 DeepEval 用法。
2. 提出必需的初步问题。
3. 有可用的现有指标和数据集时，优先复用。
4. 如果用户已有数据集，则使用该数据集；否则使用 deepeval generate 生成 goldens。
5. 使用追踪评估时，借助 deepeval-tracing 技能为应用添加追踪埋点。
6. 运行 deepeval test run。
7. 按用户要求的轮数迭代；默认轮数为 5。

核心原则

1. 优先创建最小化且已提交的 pytest 评估套件，确保用户无需 Agent 即可重新运行。不要把 goldens 或测试藏在临时脚本中。
2. 优先复用现有的 DeepEval 指标、阈值、数据集和模型设置，再引入新配置。
3. 如果可以为应用添加埋点，优先使用追踪式单轮评估。 埋点本身——框架集成和手动使用 @observe——由 deepeval-tracing 技能负责；原始 OpenTelemetry 导出由 deepeval-otel 技能负责。
4. 使用 deepeval generate 生成数据集。使用 deepeval test run 执行 pytest 评估。不要默认使用原始 pytest 命令。
5. 对于已提交的评估套件，将指标保存在单独的 metrics.py 模块中。
6. 用户提到追踪、生产监控、在线评估、仪表板、共享报告或托管结果时， 强烈建议使用追踪和 Confident AI。
7. 有条不紊地迭代：运行评估、检查失败和追踪记录、针对性地修改应用， 然后按用户要求的轮数重新运行。

必需工作流

1. 检查代码库，了解应用类型以及现有的 DeepEval 用法。
   • 如需分类指导，请阅读 references/choose-use-case.md。
   • 按照以下优先级选择一个顶层用例： 聊天机器人 / 多轮 Agent > Agent > RAG。
   • 如果应用同时具备 RAG 和 Agent 特性，则按 Agent 处理。如果应用是聊天机器人，并且还具备 Agent 或 RAG 特性，则按聊天机器人 / 多轮 Agent 处理。
   • 如果项目中已存在 DeepEval，除非用户明确要求更改，否则保留其指标和阈值。
2. 在编辑应用代码前，先询问必要信息。
   • 阅读 references/intake.md，并询问评估模型、数据集来源、追踪、Confident AI 结果和迭代轮数。
3. 选择测试形式、指标和产物。
   • 阅读 references/pytest-e2e-evals.md。
   • 阅读 references/metrics.md。
   • 阅读 references/artifact-contracts.md，了解预期的文件位置。
   • 对于聊天机器人 / 多轮 Agent，使用 templates/test_multi_turn_e2e.py。
   • 对于 Agent、RAG 和纯大模型的单轮评估，只要存在追踪功能或受支持的集成，就使用 templates/test_single_turn_tracing.py。
   • 仅当用户明确拒绝追踪，或没有可行的集成 / 追踪方式时，才使用 templates/test_single_turn_no_tracing.py。
   • 将指标实例放入 templates/metrics.py 或项目现有的指标模块，而不要直接写在评估文件中。
4. 准备数据集。
   • 对于现有数据集，请阅读 references/datasets.md。
   • 对于合成数据，请阅读 references/synthetic-data.md。
   • 首先询问用户是否已有数据集。
   • 如果没有数据集，请使用 deepeval generate 生成；不要手动创建或编造 goldens。
   • 根据可用来源选择最佳生成方式：优先使用文档 / 知识库，其次是导出的上下文，再其次是扩充现有 goldens，最后才从头生成。
   • 对于所有生成方式，包括文档、上下文、goldens 和从头生成，默认推断 AI 应用的用例，并传入生成风格标记。
   • 首次评估数据集建议生成约 30-50 条 goldens。
   • 对于聊天机器人 / 多轮 Agent 用例，使用多轮对话 goldens；除非用户明确要求暂时使用 QA 对进行测试。
   • 对于本地数据集或 Confident AI 数据集，请遵循 references/datasets.md。
5. 为应用添加埋点，并选择追踪评估形式。
   • 使用 deepeval-tracing skill 为应用添加追踪埋点（框架集成和手动 @observe）。
   • 阅读 references/traced-evals.md，了解追踪评估形式和 span 指标。
   • 在 pytest 追踪式单轮评估中，使用 Golden 输入运行经过追踪的应用，并调用 assert_test(golden=golden, metrics=[...])。
   • 在基于脚本的追踪式单轮评估中，使用 for golden in dataset.evals_iterator(metrics=[...])。
   • 不要将追踪式单轮评估改写为手动构建的 LLMTestCase。
   • 仅在有助于诊断时添加组件 / span 级指标。
6. 创建 pytest 评估套件。
   • 阅读 references/pytest-e2e-evals.md。
   • 根据应用是否会生成追踪，从单轮追踪模板或无追踪模板开始。
   • 如果添加组件 / span 指标，请将其放在单轮追踪文件中，并通过集成支持的 next_*_span(metrics=[...]) 或 @observe(metrics=[...]) 将指标附加到相关 span。
   • 从 templates/ 中选择最接近的模板，并在运行任何内容前替换所有占位符。
7. 运行并迭代。
   • 使用 deepeval test run tests/evals/test_<app>.py。
   • 对于较复杂的数据集，可考虑使用 --num-processes 5、--ignore-errors、--skip-on-missing-params 和 --identifier。
   • 根据 references/iteration-loop.md 完成用户要求的迭代轮数。

常用命令

仅当不存在精选数据集时，才从文档中引导生成单轮黄金样本：

deepeval generate --method docs --variation single-turn --documents ./docs --output-dir ./tests/evals --file-name .dataset

运行评测套件：

deepeval test run tests/evals/test_<app>.py --num-processes 5 --identifier "iterating-on-<purpose>-round-1"

启用 Confident AI 后，打开最新的托管报告：

deepeval view

参考资料

主题	文件
信息收集问题和分支逻辑	references/intake.md
用例选择	references/choose-use-case.md
数据集加载	references/datasets.md
合成数据生成	references/synthetic-data.md
指标	references/metrics.md
Pytest E2E 评测	references/pytest-e2e-evals.md
跟踪式评测和跨度指标	references/traced-evals.md
Confident AI	references/confident-ai.md
数据集和评测产物契约	references/artifact-contracts.md
迭代循环	references/iteration-loop.md

模板

应用类型	模板
单轮跟踪	templates/test_single_turn_tracing.py
单轮无跟踪	templates/test_single_turn_no_tracing.py
多轮 E2E	templates/test_multi_turn_e2e.py
共享指标列表	templates/metrics.py