{
"canonical_name": "confident-ai/deepeval",
"compilation_id": "pack_a0a941b2e9f74312a52887ff63fb8322",
"created_at": "2026-05-16T19:39:06.465335+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install -U deepeval` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install -U deepeval",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_861652cdc74f4fa898702893bfb6381a"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_cefa1ea9d5042e5ffd5a993996d1f056",
"canonical_name": "confident-ai/deepeval",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/confident-ai/deepeval",
"slug": "deepeval",
"source_packet_id": "phit_b8d29814f5ed4489a7312120ed418639",
"source_validation_id": "dval_635bb97422114e26ba1712a26f1663e8"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 1433,
"github_stars": 15473,
"one_liner_en": "The LLM Evaluation Framework",
"one_liner_zh": "The LLM Evaluation Framework",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "deepeval",
"title_zh": "deepeval 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Retrieval Augmentation",
"label_zh": "检索增强",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-retrieval-augmentation",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_b8d29814f5ed4489a7312120ed418639",
"page_model": {
"artifacts": {
"artifact_slug": "deepeval",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install -U deepeval",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/confident-ai/deepeval#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"知识库问答",
"检索增强",
"页面观察与动作规划",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "The LLM Evaluation Framework"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_4bc32a715810442d93069925f14aab92 | https://github.com/confident-ai/deepeval/issues/2673 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：'NoneType' object has no attribute 'find'",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_756ddcdc1eda4fd7b87ade56a4a3c10f | https://github.com/confident-ai/deepeval/issues/2554 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：'NoneType' object has no attribute 'find'",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_9a7d5b92cc5948d48aec4ed1e96e7288 | https://github.com/confident-ai/deepeval/releases/tag/v4.0.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:676829188 | https://github.com/confident-ai/deepeval | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LLM Evals - v3.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_9f9371d513c443ab860bbb718a785a2c | https://github.com/confident-ai/deepeval/releases/tag/v3.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：LLM Evals - v3.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 287,
"forks": 1433,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 15473
},
"source_url": "https://github.com/confident-ai/deepeval",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "The LLM Evaluation Framework",
"title": "deepeval 能力包",
"trial_prompt": "# deepeval - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 deepeval 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-test-cases：测试用例定义。围绕“测试用例定义”模拟一次用户任务，不展示安装或运行结果。\n5. page-metrics：评估指标体系。围绕“评估指标体系”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-test-cases\n输入：用户提供的“测试用例定义”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-metrics\n输入：用户提供的“评估指标体系”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-test-cases：Step 4 必须围绕“测试用例定义”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-metrics：Step 5 必须围绕“评估指标体系”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/confident-ai/deepeval\n- https://github.com/confident-ai/deepeval#readme\n- skills/deepeval/SKILL.md\n- README.md\n- deepeval/__init__.py\n- deepeval/_version.py\n- deepeval/test_case/__init__.py\n- deepeval/test_case/llm_test_case.py\n- deepeval/evaluate/__init__.py\n- deepeval/evaluate/evaluate.py\n- deepeval/evaluate/execute/__init__.py\n- deepeval/evaluate/execute/e2e.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 deepeval 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / （https://github.com/confident-ai/deepeval/issues/2673）；github/github_issue: 'NoneType' object has no attribute 'find'（https://github.com/confident-ai/deepeval/issues/2554）；github/github_release: 🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI（https://github.com/confident-ai/deepeval/releases/tag/v4.0.2）；github/github_release: LLM Evals - v3.0（https://github.com/confident-ai/deepeval/releases/tag/v3.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / ",
"url": "https://github.com/confident-ai/deepeval/issues/2673"
},
{
"kind": "github_issue",
"source": "github",
"title": "'NoneType' object has no attribute 'find'",
"url": "https://github.com/confident-ai/deepeval/issues/2554"
},
{
"kind": "github_release",
"source": "github",
"title": "🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI",
"url": "https://github.com/confident-ai/deepeval/releases/tag/v4.0.2"
},
{
"kind": "github_release",
"source": "github",
"title": "LLM Evals - v3.0",
"url": "https://github.com/confident-ai/deepeval/releases/tag/v3.0"
}
],
"status": "已收录 4 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "The LLM Evaluation Framework",
"effort": "安装已验证",
"forks": 1433,
"icon": "code",
"name": "deepeval 能力包",
"risk": "可发布",
"slug": "deepeval",
"stars": 15473,
"tags": [
"安全审查与权限治理",
"知识库问答",
"检索增强",
"页面观察与动作规划",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/confident-ai/deepeval 项目说明书\n\n生成时间：2026-05-16 19:07:22 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [核心模块结构](#page-core-modules)\n- [测试用例定义](#page-test-cases)\n- [评估指标体系](#page-metrics)\n- [评估执行引擎](#page-evaluate-engine)\n- [数据集管理](#page-dataset-management)\n- [合成数据生成](#page-synthetic-data)\n- [追踪系统](#page-tracing-system)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n- [skills/README.md](https://github.com/confident-ai/deepeval/blob/main/skills/README.md)\n- [deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n- [deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)\n- [deepeval/cli/main.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/main.py)\n- [deepeval/cli/inspect.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/inspect.py)\n \n\n# 项目介绍\n\n## 概述\n\nDeepEval 是一个简单易用、开源的 **LLM（大语言模型）评估框架**，专门用于评估大型语言模型系统。它类似于 Pytest，但专门为 LLM 应用的单元测试而设计。DeepEval 整合了最新研究成果，通过 G-Eval、任务完成度、答案相关性、幻觉检测等指标来运行评估，这些指标使用 **LLM-as-a-Judge**（LLM 作为评判者）和其他 NLP 模型，**完全运行在本地机器上**。\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 核心定位\n\n无论你是构建 AI 代理（AI Agents）、RAG（检索增强生成）管道还是聊天机器人，无论是使用 LangChain 还是 OpenAI 实现，DeepEval 都能为你提供支持。通过它，你可以轻松确定最优的模型、提示词和架构，从而：\n\n- 提升 AI 质量\n- 防止提示词漂移\n- 自信地从 OpenAI 迁移到 Claude\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 技术架构\n\n### 系统架构图\n\n```mermaid\ngraph TB\n subgraph 用户层\n A[测试用例编写] --> B[Pytest 集成 / API 调用]\n end\n \n subgraph 核心评估引擎\n C[Metrics 指标] --> D[GEval]\n C --> E[Answer Relevancy]\n C --> F[Task Completion]\n C --> G[Hallucination]\n end\n \n subgraph 集成层\n H[LangChain] --> I[CallbackHandler]\n J[OpenAI] --> K[OpenAI Integration]\n L[Anthropic] --> M[Anthropic Integration]\n N[LlamaIndex] --> O[AsyncConfig]\n P[LangGraph] --> I\n end\n \n subgraph 输出层\n Q[本地评估结果] --> R[Confident AI 云端]\n end\n \n B --> D\n B --> E\n B --> F\n B --> G\n I --> C\n K --> C\n M --> C\n O --> C\n```\n\n### 评估模式\n\nDeepEval 支持两种主要的评估模式：\n\n| 模式 | 描述 | 适用场景 |\n|------|------|----------|\n| **端到端评估（End-to-End）** | 将 LLM 应用视为黑盒，输入输出直接评估 | 快速验证整体输出质量 |\n| **可追溯评估（With Traceability）** | 使用 `evals_iterator()` 追踪组件级调用 | 细粒度分析、定位问题组件 |\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 核心功能\n\n### 评估指标体系\n\nDeepEval 提供了多种预置评估指标，所有指标得分范围均为 **0-1**：\n\n| 指标名称 | 说明 | 评估参数 |\n|----------|------|----------|\n| **GEval** | 基于 G-Eval 算法的通用评估指标，支持自定义评估标准 | SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT |\n| **AnswerRelevancyMetric** | 评估答案与输入的相关性 | retrieval_context |\n| **TaskCompletionMetric** | 评估任务完成度 | 端到端追踪 |\n| **幻觉检测指标** | 检测输出中的幻觉内容 | retrieval_context |\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### 黄金测试用例生成\n\nDeepEval 支持通过 CLI 自动生成合成黄金测试用例，支持多种生成方法：\n\n```bash\ndeepeval generate golden --method [METHOD] --variation [VARIATION]\n```\n\n| 生成方法 | 说明 | 必需参数 |\n|----------|------|----------|\n| `DOCS` | 从文档生成 | `--documents` |\n| `CONTEXTS` | 从上下文生成 | `--contexts-file` |\n| `SCRATCH` | 从零开始生成 | `--num-goldens` |\n| `GOLDENS` | 从现有黄金用例扩展 | `--goldens-file` |\n\n资料来源：[deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n\n### 测试用例结构\n\n```python\nfrom deepeval.test_case import LLMTestCase\n\ntest_case = LLMTestCase(\n input=\"用户输入\",\n actual_output=\"实际输出\",\n expected_output=\"期望输出\", # 可选\n retrieval_context=[\"检索上下文\"] # 可选\n)\n```\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 框架集成\n\nDeepEval 支持与多种主流 AI 框架深度集成：\n\n### 集成矩阵\n\n| 框架 | 集成方式 | 追踪能力 | 本地评估 | 云端同步 |\n|------|----------|----------|----------|----------|\n| **OpenAI** | `@observe` / `trace()` | ✅ | ✅ | ✅ |\n| **Anthropic** | `@observe` / `trace()` | ✅ | ✅ | ✅ |\n| **LangChain** | `CallbackHandler` | ✅ | ✅ | ✅ |\n| **LangGraph** | `CallbackHandler` | ✅ | ✅ | ✅ |\n| **LlamaIndex** | `AsyncConfig` | ✅ | ✅ | ✅ |\n| **Pydantic AI** | `instrument_pydantic_ai()` | ✅ | ✅ | ✅ |\n| **CrewAI** | `instrument_crewai()` | ✅ | ✅ | ✅ |\n| **Google ADK** | `instrument_google_adk()` | ✅ | ✅ | ✅ |\n| **Strands** | `instrument_strands()` | ✅ | ✅ | ✅ |\n| **AWS AgentCore** | `instrument_agentcore()` | ✅ | ✅ | ✅ |\n\n资料来源：[deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)\n\n### 集成架构\n\n```mermaid\ngraph LR\n A[用户代码] --> B[框架集成层]\n B --> C[OTel 追踪]\n B --> D[DeepEval 追踪]\n \n C --> E[ContextAwareSpanProcessor]\n D --> E\n \n E --> F{评估状态判断}\n F -->|评估中| G[REST 路由]\n F -->|非评估| H[OTLP 导出]\n \n G --> I[ConfidentSpanExporter]\n H --> J[远程 OTel 端点]\n```\n\n## 命令行接口\n\n### 可用命令\n\n| 命令 | 说明 | 关键选项 |\n|------|------|----------|\n| `deepeval login` | 登录 Confident AI 平台 | - |\n| `deepeval test run` | 运行测试套件 | `--folder`, pytest 集成 |\n| `deepeval generate golden` | 生成黄金测试用例 | `--method`, `--variation` |\n| `deepeval inspect` | 检查测试运行结果 | `--path`, `--folder` |\n| `deepeval set-gemini` | 设置 Gemini 模型 | `--model` |\n| `deepeval unset-gemini` | 取消 Gemini 配置 | `-x`, `--clear-secrets` |\n\n资料来源：[deepeval/cli/main.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/main.py)\n\n### 本地开发环境配置\n\n```bash\n# 复制环境变量模板\ncp .env.example .env.local\n# 编辑 .env.local（会被 git 忽略）\n```\n\n## 使用流程\n\n### 基本使用流程\n\n```mermaid\ngraph TD\n A[安装 DeepEval] --> B[配置 API Key]\n B --> C[编写测试用例]\n C --> D[选择评估指标]\n D --> E[定义阈值]\n E --> F[运行评估]\n F --> G{是否达标}\n G -->|是| H[测试通过]\n G -->|否| I[调整模型/提示词]\n I --> F\n```\n\n### Pytest 集成示例\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\n@assert_test\ndef test_case():\n correctness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n test_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\"\n )\n```\n\n运行测试：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### 非 Pytest 评估\n\n```python\nfrom deepeval import evaluate\nfrom deepeval.metrics import AnswerRelevancyMetric\nfrom deepeval.test_case import LLMTestCase\n\nanswer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\nevaluate([test_case], [answer_relevancy_metric])\n```\n\n## 云端集成\n\n### Confident AI 平台\n\nDeepEval 与 Confident AI 平台深度集成，提供以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| **测试报告** | 生成可分享的测试报告 |\n| **数据集管理** | 管理评估数据集 |\n| **LLM 应用追踪** | 追踪 LLM 应用的运行轨迹 |\n| **生产环境监控** | 监控生产环境的评估指标 |\n| **在线评估** | 支持在线实时评估 |\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### 登录与同步\n\n```bash\n# 登录\ndeepeval login\n\n# 运行测试 - 结果自动同步到云端\ndeepeval test run test_chatbot.py\n```\n\n## 技能集成\n\nDeepEval 可以作为智能代理（Agent）的技能（Skill）使用：\n\n### 安装方式\n\n```bash\n# 使用 skills 兼容的安装器\nnpx skills add confident-ai/deepeval --skill \"deepeval\"\n\n# 或手动复制\ncp skills/deepeval [agent_skills_directory]\n```\n\n### 前置条件\n\n| 用途 | 必需包 | 配置 |\n|------|--------|------|\n| 本地评估 | `pip install -U deepeval` | - |\n| 云端报告/追踪 | `deepeval login` | Confident AI API Key |\n\n资料来源：[skills/README.md](https://github.com/confident-ai/deepeval/blob/main/skills/README.md)\n\n## 测试结果检查\n\n使用 `deepeval inspect` 命令检查测试运行结果：\n\n```bash\ndeepeval inspect [PATH]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `PATH` | 特定测试运行文件或包含测试结果的文件夹 |\n| `-f, --folder` | 指定扫描文件夹，查找最新的测试运行文件 |\n\n该命令会打开 TUI（文本用户界面）来检查保存的测试运行轨迹。\n\n资料来源：[deepeval/cli/inspect.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/inspect.py)\n\n## 性能与扩展性\n\n### 异步评估支持\n\nDeepEval 支持异步评估模式，适用于大规模评估场景：\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\n\nfor golden in dataset.evals_iterator(\n async_config=AsyncConfig(run_async=True),\n metrics=[TaskCompletionMetric()],\n):\n task = asyncio.create_task(agent.run(golden.input))\n dataset.evaluate(task)\n```\n\n### 并发控制\n\n| 配置项 | 说明 |\n|--------|------|\n| `max_concurrent` | 最大并发数 |\n| `max_retries` | 最大重试次数 |\n\n资料来源：[deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n\n## 版本与发布\n\nDeepEval 使用语义化版本控制，当前版本信息可通过以下方式获取：\n\n```python\nimport deepeval\nprint(deepeval.__version__)\n```\n\n| 版本属性 | 说明 |\n|----------|------|\n| `__version__` | 当前安装的版本号 |\n| GitHub Releases | 发布历史和更新日志 |\n\n## 许可证\n\nDeepEval 采用开源许可证，具体信息请参阅 [LICENSE.md](https://github.com/confident-ai/deepeval/blob/master/LICENSE.md)。\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方文档 | [deepeval.com/docs](https://deepeval.com/docs/getting-started) |\n| GitHub 仓库 | [github.com/confident-ai/deepeval](https://github.com/confident-ai/deepeval) |\n| Discord 社区 | [discord.gg/3SEyvpgu2f](https://discord.gg/3SEyvpgu2f) |\n| Twitter | [@deepeval](https://x.com/deepeval) |\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [测试用例定义](#page-test-cases)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n- [deepeval/test_case/llm_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)\n- [deepeval/evaluate/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/__init__.py)\n- [deepeval/evaluate/evaluate.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/evaluate.py)\n \n\n# 快速开始\n\nDeepEval 的\"快速开始\"模块为开发者提供了在本地环境中快速上手 LLM 评估框架的最简路径。该模块封装了从测试用例定义、指标配置到评估执行的全流程，使开发者能够在几分钟内完成首个 LLM 应用的质量验证。通过深度集成 Pytest 生态，DeepEval 将 LLM 评估转化为标准化的单元测试流程，与现有开发工作流无缝衔接。资料来源：[README.md]()\n\n## 核心概念\n\nDeepEval 将 LLM 评估抽象为三个核心概念：**测试用例（Test Case）**、**评估指标（Metric）** 和 **断言验证（Assertion）**。测试用例定义了被评估 LLM 应用的输入、期望输出和上下文信息；评估指标则实现了具体的评估算法，如 G-Eval、答案相关性、幻觉检测等；断言验证将指标得分与阈值进行比较，以判断测试是否通过。资料来源：[deepeval/test_case/llm_test_case.py]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[创建测试文件] --> B[定义 LLMTestCase]\n B --> C[配置评估指标]\n C --> D[调用 assert_test]\n D --> E[运行测试命令]\n E --> F{测试通过?}\n F -->|是| G[✅ 测试成功]\n F -->|否| H[❌ 测试失败]\n \n I[设置 OPENAI_API_KEY] -.-> A\n```\n\n## 环境准备\n\n### 环境变量配置\n\n在使用 DeepEval 之前，需要设置 LLM API 密钥。DeepEval 支持 OpenAI、Anthropic、Google Gemini 等多种模型提供商。以 OpenAI 为例，在终端中执行以下命令设置环境变量：\n\n```bash\nexport OPENAI_API_KEY=\"...\"\n```\n\n也可使用 `.env.local` 文件管理密钥：\n\n```bash\ncp .env.example .env.local\n# 编辑 .env.local 文件（该文件已被 git 忽略）\n```\n\n资料来源：[README.md]()\n\n### 安装 DeepEval\n\n通过 pip 安装 DeepEval：\n\n```bash\npip install -U deepeval\n```\n\n资料来源：[README.md]()\n\n## 使用 Pytest 集成\n\n### 创建测试文件\n\n创建一个名为 `test_chatbot.py` 的测试文件：\n\n```bash\ntouch test_chatbot.py\n```\n\n### 编写测试用例\n\n打开 `test_chatbot.py` 并编写第一个端到端评估测试。DeepEval 将 LLM 应用视为黑盒进行评估：\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ndef test_case():\n correctness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n test_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n )\n assert_test(test_case, [correctness_metric])\n```\n\n资料来源：[README.md]()\n\n### 核心参数说明\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `input` | str | 用户输入，模拟 LLM 应用的输入 |\n| `actual_output` | str | LLM 应用的实际输出 |\n| `expected_output` | str | 期望的正确答案 |\n| `retrieval_context` | List[str] | 检索上下文，用于 RAG 评估 |\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `name` | str | 指标名称 |\n| `criteria` | str | 评估标准的描述性文本 |\n| `evaluation_params` | List[SingleTurnParams] | 评估所需的参数列表 |\n| `threshold` | float | 通过阈值（0-1） |\n\n资料来源：[deepeval/test_case/llm_test_case.py]()\n\n### 运行测试\n\n在终端中执行测试命令：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n测试通过时将显示成功消息，未通过则显示失败详情。\n\n资料来源：[README.md]()\n\n## 不使用 Pytest 集成\n\n对于 Jupyter Notebook 环境或偏好命令式编程的场景，DeepEval 提供了 `evaluate()` 函数：\n\n```python\nfrom deepeval import evaluate\nfrom deepeval.metrics import AnswerRelevancyMetric\nfrom deepeval.test_case import LLMTestCase\n\nanswer_relevancy_metric = AnswerRelencyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\nevaluate([test_case], [answer_relevancy_metric])\n```\n\n资料来源：[README.md]()\n\n## 独立使用评估指标\n\nDeepEval 高度模块化，允许在项目任何位置单独使用评估指标：\n\n```python\nfrom deepeval.metrics import AnswerRelevancyMetric\nfrom deepeval.test_case import LLMTestCase\n\nanswer_relevancy_metric = AnswerRelencyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\nanswer_relevancy_metric.measure(test_case)\nprint(answer_relevancy_metric.score)\n```\n\n资料来源：[README.md]()\n\n## 与 Confident AI 平台集成\n\nDeepEval 支持与 Confident AI 平台的深度集成。登录后，测试结果将自动同步到云端：\n\n```bash\ndeepeval login\n```\n\n登录后运行测试，结果自动上传：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n资料来源：[README.md]()\n\n## 评估指标类型\n\n| 指标名称 | 说明 | 适用场景 |\n|----------|------|----------|\n| GEval | 基于 LLM 的通用评估指标，支持自定义评估标准 | 通用质量评估 |\n| AnswerRelevancyMetric | 答案相关性评估 | RAG 系统 |\n| TaskCompletionMetric | 任务完成度评估 | AI Agent |\n| HallucinationMetric | 幻觉检测 | 内容生成 |\n\n资料来源：[README.md]()\n\n## 关键源码结构\n\n`deepeval.test_case` 模块导出了测试用例相关的核心类：\n\n```python\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n```\n\n`deepeval.evaluate` 模块提供了评估执行接口：\n\n```python\nfrom deepeval import evaluate, assert_test\n```\n\n资料来源：[deepeval/test_case/__init__.py](), [deepeval/evaluate/__init__.py]()\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心模块结构](#page-core-modules), [评估指标体系](#page-metrics), [追踪系统](#page-tracing-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/evaluate/evaluate.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/evaluate.py)\n- [deepeval/evaluate/execute/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/__init__.py)\n- [deepeval/evaluate/execute/e2e.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/e2e.py)\n- [deepeval/evaluate/execute/agentic.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/agentic.py)\n- [deepeval/constants.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/constants.py)\n \n\n# 系统架构\n\n## 概述\n\nDeepEval 是一个开源的 LLM（大语言模型）评估框架，采用模块化设计实现评估流程的解耦与扩展。系统架构围绕**评估执行引擎**、**指标计算层**、**追踪系统**和**CLI命令接口**四大核心模块展开，支持端到端测试、代理评估、合成数据生成等多种评估场景。\n\nDeepEval 的核心设计理念是将 LLM 应用视为黑盒，通过标准化测试用例（`LLMTestCase`）和可插拔的指标（Metric）系统，实现跨框架的通用评估能力。\n\n## 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"CLI 层\"\n CLI[deepeval CLI]\n Login[login 命令]\n TestRun[test run 命令]\n Generate[generate 命令]\n Inspect[inspect 命令]\n end\n\n subgraph \"评估执行层 (evaluate)\"\n Evaluate[evaluate 函数]\n E2EExecutor[端到端执行器]\n AgenticExecutor[代理执行器]\n SyncRunner[同步运行器]\n AsyncRunner[异步运行器]\n end\n\n subgraph \"核心指标层 (metrics)\"\n GEval[G-Eval 指标]\n TaskCompletion[任务完成度]\n AnswerRelevancy[答案相关性]\n Faithfulness[忠实度]\n Hallucination[幻觉检测]\n end\n\n subgraph \"追踪系统 (tracing)\"\n Observe[@observe 装饰器]\n Trace[trace 上下文管理器]\n SpanProcessor[Span 处理器]\n ConfidentAI[Confident AI 云端]\n end\n\n subgraph \"数据合成层 (synthesizer)\"\n Synthesizer[数据合成器]\n ContextConstruction[上下文构建]\n GoldenGenerator[黄金数据生成]\n end\n\n subgraph \"集成层 (integrations)\"\n LangChain[LangChain]\n LangGraph[LangGraph]\n OpenAI[OpenAI]\n Anthropic[Anthropic]\n LlamaIndex[LlamaIndex]\n CrewAI[CrewAI]\n GoogleADK[Google ADK]\n Strands[Strands]\n end\n\n CLI --> Evaluate\n CLI --> Generate\n CLI --> Login\n CLI --> Inspect\n \n Evaluate --> E2EExecutor\n Evaluate --> AgenticExecutor\n \n E2EExecutor --> SyncRunner\n E2EExecutor --> AsyncRunner\n \n AgenticExecutor --> SyncRunner\n AgenticExecutor --> AsyncRunner\n \n SyncRunner --> GEval\n SyncRunner --> TaskCompletion\n SyncRunner --> AnswerRelevancy\n AsyncRunner --> GEval\n AsyncRunner --> TaskCompletion\n AsyncRunner --> AnswerRelevancy\n \n Observe --> Trace\n Trace --> SpanProcessor\n SpanProcessor --> ConfidentAI\n \n Synthesizer --> ContextConstruction\n Synthesizer --> GoldenGenerator\n \n LangChain --> Observe\n LangGraph --> Observe\n OpenAI --> Observe\n Anthropic --> Observe\n```\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 核心执行层\n\n### 评估执行器类型\n\nDeepEval 的评估执行层支持两种主要的执行模式，分别针对不同的评估场景：\n\n| 执行器类型 | 适用场景 | 源码文件 |\n|-----------|---------|---------|\n| `E2EExecutor` | 端到端评估，将 LLM 应用视为黑盒 | `deepeval/evaluate/execute/e2e.py` |\n| `AgenticExecutor` | 代理级别评估，支持工具调用追踪 | `deepeval/evaluate/execute/agentic.py` |\n\n资料来源：[deepeval/evaluate/execute/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/__init__.py)\n\n### 执行流程\n\n```mermaid\ngraph LR\n A[LLMTestCase 输入] --> B[创建测试用例]\n B --> C{执行模式}\n C -->|同步| D[SyncRunner 执行]\n C -->|异步| E[AsyncRunner 执行]\n D --> F[指标计算]\n E --> F\n F --> G[分数判定]\n G --> H{是否通过阈值}\n H -->|是| I[测试通过]\n H -->|否| J[测试失败]\n```\n\n### E2E 执行器\n\nE2E（端到端）执行器是 DeepEval 最基本的评估执行器。它接收标准化测试用例，按照配置的指标逐一计算评分，最终返回评估结果。\n\n核心职责：\n- 接收 `LLMTestCase` 测试用例\n- 协调多个指标并行或串行计算\n- 聚合评估结果并生成报告\n\n资料来源：[deepeval/evaluate/execute/e2e.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/e2e.py)\n\n### Agentic 执行器\n\n代理执行器专门用于评估 LLM 代理（Agent）应用，支持追踪工具调用、多步推理和任务完成度等代理特有指标。\n\n核心职责：\n- 追踪代理的完整执行轨迹\n- 记录工具调用序列和参数\n- 评估任务完成度和步骤效率\n\n资料来源：[deepeval/evaluate/execute/agentic.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/agentic.py)\n\n## 指标系统\n\n### 指标类型概览\n\nDeepEval 提供了丰富的预置指标，涵盖 LLM 评估的多个维度：\n\n| 指标类别 | 指标名称 | 用途 |\n|---------|---------|-----|\n| **通用指标** | GEval | 基于 LLM-as-Judge 的通用评估 |\n| **答案质量** | Answer Relevancy | 评估答案与问题的相关性 |\n| **答案质量** | Faithfulness | 评估答案与检索上下文的忠实度 |\n| **答案质量** | Hallucination | 检测答案中的幻觉内容 |\n| **代理指标** | Task Completion | 评估代理是否完成任务 |\n| **代理指标** | Tool Correctness | 检查工具调用的正确性 |\n| **代理指标** | Goal Accuracy | 衡量目标达成的准确性 |\n| **代理指标** | Step Efficiency | 评估步骤效率 |\n\n资料来源：[README.md - Metrics and Features](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### G-Eval 指标\n\nG-Eval 是 DeepEval 的核心评估方法，基于最新的研究论文实现。它通过 LLM-as-Judge 范式进行自动化评估。\n\n使用方式：\n\n```python\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ncorrectness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n)\n```\n\n### 任务完成度指标\n\n专门用于评估 LLM 代理是否成功完成了给定任务：\n\n```python\nfrom deepeval.metrics import TaskCompletionMetric\nfrom deepeval.tracing import trace\n\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n## 追踪系统\n\n### 追踪架构\n\nDeepEval 的追踪系统采用 OpenTelemetry 兼容的设计，同时支持本地追踪和云端同步：\n\n```mermaid\ngraph TD\n A[被装饰的函数] --> B[@observe 装饰器]\n B --> C[trace 上下文]\n C --> D[当前 Span]\n D --> E{Span 处理器}\n E -->|本地模式| F[本地存储]\n E -->|云端模式| G[Confident AI]\n E -->|评估模式| H[Trace Manager]\n \n F --> I[评估结果]\n G --> I\n H --> I\n```\n\n### 核心追踪组件\n\n| 组件 | 功能 | 源码位置 |\n|-----|------|---------|\n| `@observe()` | 函数装饰器，自动创建追踪上下文 | `deepeval/tracing` |\n| `trace()` | 上下文管理器，用于批量追踪 | `deepeval/tracing` |\n| `update_current_span()` | 更新当前 span 的数据 | `deepeval/tracing` |\n| `update_current_trace()` | 更新当前 trace 的全局数据 | `deepeval/tracing` |\n\n资料来源：[README.md - Evals With Full Traceability](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### 追踪装饰器使用\n\n```python\nfrom deepeval.tracing import observe, update_current_span\nfrom deepeval.test_case import LLMTestCase\n\n@observe()\ndef inner_component(input: str):\n output = \"result\"\n update_current_span(test_case=LLMTestCase(input=input, actual_output=output))\n return output\n\n@observe()\ndef app(input: str):\n return inner_component(input)\n```\n\n## 框架集成\n\n### 集成矩阵\n\nDeepEval 支持与主流 LLM 框架的无缝集成，通过统一的回调机制实现追踪和评估：\n\n| 框架 | 集成方式 | 源码位置 |\n|-----|---------|---------|\n| OpenAI | 原生支持 | `deepeval.openai` |\n| Anthropic | 原生支持 | `deepeval.anthropic` |\n| LangChain | CallbackHandler | `deepeval/integrations/langchain` |\n| LangGraph | CallbackHandler | `deepeval/integrations/langchain` |\n| LlamaIndex | 异步集成 | `deepeval/integrations/llamaindex` |\n| CrewAI | instrument_crewai | `deepeval/integrations/crewai` |\n| Google ADK | instrument_google_adk | `deepeval/integrations/google_adk` |\n| Strands | instrument_strands | `deepeval/integrations/strands` |\n| AWS AgentCore | instrument_agentcore | `deepeval/integrations/agentcore` |\n| Pydantic AI | 原生支持 | `deepeval/integrations/pydantic_ai` |\n\n资料来源：[deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)\n\n### 集成能力说明\n\n每个集成支持四种级别的能力：\n\n| 能力级别 | 说明 |\n|---------|-----|\n| **Bare** | 直接调用框架即可产生追踪，无需额外包装 |\n| **`@observe` / `with trace(...)`** | 包装后追踪数据流入 DeepEval 原生上下文 |\n| **`evals_iterator`** | 支持在数据集迭代器中使用指标评估 |\n| **`deepeval test run`** | 支持 pytest 入口点的追踪评估 |\n\n## CLI 命令系统\n\n### 命令概览\n\nDeepEval CLI 提供了丰富的命令行接口：\n\n| 命令 | 功能 | 源码文件 |\n|-----|------|---------|\n| `deepeval login` | 登录 Confident AI 平台 | `deepeval/cli/main.py` |\n| `deepeval test run` | 运行 Pytest 测试文件 | `deepeval/cli/test` |\n| `deepeval generate` | 生成合成黄金数据 | `deepeval/cli/generate/command.py` |\n| `deepeval set-model` | 设置默认评估模型 | `deepeval/cli/main.py` |\n| `deepeval inspect` | TUI 检视测试结果 | `deepeval/cli/inspect.py` |\n\n### 黄金数据生成\n\n`deepeval generate` 命令支持多种数据生成方法：\n\n```mermaid\ngraph TD\n A[generate 命令] --> B{生成方法}\n B -->|DOCS| C[从文档生成]\n B -->|CONTEXTS| D[从上下文生成]\n B -->|SCRATCH| E[从零生成]\n B -->|GOLDENS| F[从已有黄金数据生成]\n \n C --> G[文档分块]\n D --> H[上下文质量过滤]\n E --> I[任务描述生成]\n F --> J[变体扩展]\n \n G --> K[Synthesizer]\n H --> K\n I --> K\n J --> K\n \n K --> L[保存为 JSON/CSV]\n```\n\n生成方法配置：\n\n| 方法 | 选项 | 说明 |\n|-----|------|-----|\n| DOCS | `--documents` | 从文档文件路径列表生成 |\n| CONTEXTS | `--contexts-file` | 从上下文文件生成 |\n| SCRATCH | `--num-goldens` | 从零开始生成指定数量 |\n| GOLDENS | `--goldens-file` | 基于已有黄金数据生成变体 |\n\n资料来源：[deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n\n### inspect 命令\n\n`deepeval inspect` 命令提供交互式 TUI 用于检视测试结果：\n\n```python\n# 查看最新测试运行结果\ndeepeval inspect\n\n# 查看指定文件\ndeepeval inspect path/to/test_run_123.json\n\n# 查看指定文件夹的最新结果\ndeepeval inspect --folder ./results\n```\n\n该命令支持可选的 `deepeval[inspect]` 扩展包，需要单独安装。\n\n## 数据模型\n\n### LLMTestCase\n\n核心测试用例数据模型：\n\n| 字段 | 类型 | 必需 | 说明 |\n|-----|------|-----|-----|\n| `input` | str | 是 | 测试输入 |\n| `actual_output` | str | 是 | LLM 实际输出 |\n| `expected_output` | str | 否 | 期望输出 |\n| `retrieval_context` | List[str] | 否 | RAG 检索上下文 |\n| `context` | List[Dict] | 否 | 多轮对话上下文 |\n\n### SingleTurnParams 与 MultiTurnParams\n\n评估参数枚举，用于指定 G-Eval 等指标的评估维度：\n\n```python\nfrom deepeval.test_case import SingleTurnParams, MultiTurnParams\n\n# 单轮评估参数\nSingleTurnParams.INPUT\nSingleTurnParams.ACTUAL_OUTPUT\nSingleTurnParams.EXPECTED_OUTPUT\nSingleTurnParams.RETRIEVAL_CONTEXT\n\n# 多轮评估参数\nMultiTurnParams.INPUT\nMultiTurnParams.ACTUAL_OUTPUT\nMultiTurnParams.EXPECTED_OUTCOME\nMultiTurnParams.RETRIEVAL_CONTEXT\nMultiTurnParams.AGENT_ICONOGRAPHY\n```\n\n## 评估配置\n\n### AsyncConfig\n\n异步评估配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `run_async` | bool | False | 是否启用异步执行 |\n| `max_concurrent` | int | None | 最大并发数 |\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\n\nasync_config = AsyncConfig(\n run_async=True,\n max_concurrent=5\n)\n```\n\n### ContextConstructionConfig\n\n合成数据生成的上下文构建配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `max_contexts_per_document` | int | 5 | 每个文档最多生成上下文数 |\n| `min_contexts_per_document` | int | 1 | 每个文档最少生成上下文数 |\n| `chunk_size` | int | 1000 | 文档分块大小 |\n| `chunk_overlap` | int | 200 | 分块重叠大小 |\n| `context_quality_threshold` | float | 0.5 | 上下文质量阈值 |\n| `context_similarity_threshold` | float | 0.5 | 上下文相似度阈值 |\n| `max_retries` | int | 3 | 最大重试次数 |\n\n## 常量定义\n\nDeepEval 在 `deepeval/constants.py` 中定义了全局常量，包括：\n\n- 默认阈值配置\n- API 超时设置\n- 缓存策略配置\n- 日志级别定义\n\n这些常量贯穿整个评估流程，确保行为的一致性和可配置性。\n\n资料来源：[deepeval/constants.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/constants.py)\n\n## 评估流程总结\n\n```mermaid\ngraph TB\n subgraph \"1. 准备阶段\"\n A1[编写测试用例] --> A2[定义指标]\n A2 --> A3[配置评估参数]\n end\n\n subgraph \"2. 执行阶段\"\n A3 --> B1[创建评估器]\n B1 --> B2{执行模式}\n B2 -->|同步| B3[SyncRunner]\n B2 -->|异步| B4[AsyncRunner]\n B3 --> B5[指标并行计算]\n B4 --> B5\n end\n\n subgraph \"3. 评估阶段\"\n B5 --> C1[调用 LLM 评估]\n C1 --> C2[分数聚合]\n C2 --> C3[阈值判定]\n end\n\n subgraph \"4. 报告阶段\"\n C3 --> D1[生成测试报告]\n D1 --> D2[上传至 Confident AI]\n D2 --> D3[本地保存 JSON]\n end\n```\n\n## 最佳实践\n\n### 测试用例设计\n\n1. **输入多样化**：确保测试用例覆盖各种边界情况和典型场景\n2. **明确期望输出**：为关键测试提供期望输出以便精确评估\n3. **使用 RAG 上下文**：RAG 应用应提供 retrieval_context 参数\n\n### 指标配置\n\n1. **合理设置阈值**：根据业务需求调整 threshold 参数\n2. **多指标组合**：复杂场景可组合使用多个指标\n3. **使用 G-Eval**：对于主观性评估，优先使用 G-Eval\n\n### 追踪配置\n\n1. **使用 `@observe` 装饰器**：确保关键函数被追踪\n2. **更新 span 数据**：在函数内使用 `update_current_span` 丰富追踪信息\n3. **分离关注点**：将评估逻辑与业务逻辑解耦\n\n---\n\n\n\n## 核心模块结构\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [评估指标体系](#page-metrics), [测试用例定义](#page-test-cases)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/metrics/base_metric.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/base_metric.py)\n- [deepeval/metrics/indicator.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/indicator.py)\n- [deepeval/test_case/utils.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/utils.py)\n- [deepeval/config/settings.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/config/settings.py)\n- [deepeval/synthesizer/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/__init__.py)\n \n\n# 核心模块结构\n\n## 概述\n\nDeepEval 是一个面向大语言模型（LLM）应用的评估框架，采用了模块化架构设计。其核心模块结构围绕**指标系统（Metrics）**、**测试用例（Test Case）**、**追踪系统（Tracing）**和**配置管理（Configuration）**四大支柱构建。框架的核心设计理念是将 LLM 评估过程抽象为可组合、可扩展的组件，类似于 Pytest 在单元测试领域的角色，但专门针对 LLM 应用场景优化。\n\nDeepEval 的架构设计允许开发者以两种主要方式使用该框架：一是集成到 Pytest 测试流程中，通过 `@assert_test` 装饰器实现声明式评估；二是作为独立库使用，通过 `evaluate()` 函数直接调用指标进行评估。这种双重使用模式体现了框架对不同开发工作流的包容性支持。\n\n框架的核心价值在于其本地化评估能力——所有指标计算和 LLM 调用都可以在用户本地机器上运行，无需依赖外部云服务。同时，通过与 Confident AI 平台的集成，开发者可以选择性地将评估结果同步到云端进行可视化和协作分析。\n\n## 核心模块架构图\n\n```mermaid\ngraph TD\n subgraph \"核心层\"\n BM[base_metric.py
BaseMetric 基类]\n IND[indicator.py
Indicator 指标系统]\n TU[test_case/utils.py
LLMTestCase]\n CFG[config/settings.py
配置管理]\n end\n \n subgraph \"执行层\"\n SYN[Synthesizer
合成器]\n EVAL[evaluate()
评估函数]\n TRACE[Tracing
追踪系统]\n end\n \n subgraph \"集成层\"\n LC[LangChain]\n OAI[OpenAI]\n ANTH[Anthropic]\n LI[LlamaIndex]\n CR[CrewAI]\n GADK[Google ADK]\n end\n \n subgraph \"CLI 层\"\n CMD[CLI Commands]\n RUN[Test Runner]\n GEN[Generate
生成器]\n end\n \n BM --> IND\n IND --> TU\n CFG --> BM\n SYN --> BM\n EVAL --> IND\n TRACE --> BM\n LC --> TRACE\n OAI --> TRACE\n ANTH --> TRACE\n CMD --> SYN\n CMD --> RUN\n```\n\n## 指标系统（Metrics）\n\n### BaseMetric 基类架构\n\n指标系统是 DeepEval 的核心评估单元，所有评估指标都继承自 `BaseMetric` 基类。基类定义了评估接口的通用契约，确保各类指标实现的一致性和可替换性。\n\n`BaseMetric` 提供了以下核心能力：\n\n1. **分数计算（measure）**：接收 `LLMTestCase` 对象，执行指标评估逻辑\n2. **阈值判定（threshold）**：定义通过/失败的分数边界\n3. **评分理由生成（reason）**：为分数提供人类可读的评估解释\n4. **异步支持**：部分指标支持异步执行模式\n\n资料来源：[deepeval/metrics/base_metric.py:1-50]()\n\n### Indicator 指标实现\n\n`indicator.py` 文件包含了 DeepEval 内置指标的具体实现。指标系统采用策略模式设计，每种指标封装了特定的评估逻辑。\n\n**主要指标类型：**\n\n| 指标类型 | 用途 | 评估维度 |\n|---------|------|---------|\n| GEval | 基于 LLM 的通用评估 | 可配置 criteria |\n| TaskCompletionMetric | 任务完成度评估 | Agent 目标达成 |\n| AnswerRelevancyMetric | 回答相关性评估 | RAG 管道输出质量 |\n| FaithfulnessMetric | 事实一致性评估 | RAG 管道准确性 |\n| HallucinationMetric | 幻觉检测评估 | 内容真实性 |\n\n资料来源：[deepeval/metrics/indicator.py:1-100]()\n\n### 指标执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant Metric as Metric 实例\n participant TC as LLMTestCase\n participant LLM as LLM API\n \n User->>Metric: measure(test_case)\n Metric->>TC: 提取评估参数\n Metric->>LLM: 调用 LLM-as-Judge\n LLM-->>Metric: 返回评分结果\n Metric->>Metric: 应用 threshold 判定\n Metric-->>User: 返回 score 和 reason\n```\n\n## 测试用例系统（Test Case）\n\n### LLMTestCase 数据结构\n\n`LLMTestCase` 是 DeepEval 中表示测试用例的核心数据结构。它封装了评估所需的输入、输出和上下文信息。\n\n**基础参数：**\n\n| 参数名 | 类型 | 必需 | 说明 |\n|--------|------|------|------|\n| input | str | 是 | 测试输入/问题 |\n| actual_output | str | 是 | LLM 实际输出 |\n| expected_output | str | 否 | 期望的标准答案 |\n| retrieval_context | List[str] | 否 | RAG 检索上下文 |\n\n资料来源：[deepeval/test_case/utils.py:1-80]()\n\n### 单轮与多轮参数\n\nDeepEval 通过 `SingleTurnParams` 和 `MultiTurnParams` 枚举区分不同类型的评估参数：\n\n- **SingleTurnParams**：适用于简单问答场景，参数包括 `ACTUAL_OUTPUT`、`EXPECTED_OUTPUT`\n- **MultiTurnParams**：适用于对话系统，需要管理对话历史和轮次间的状态传递\n\n这种设计使得框架能够灵活支持从简单问答到复杂多轮对话的各类评估场景。\n\n## 配置管理体系\n\n### 环境变量配置\n\nDeepEval 实现了自动化的环境变量加载机制，配置文件位于 `deepeval/config/settings.py`。\n\n**配置加载优先级（从高到低）：**\n\n1. 进程环境变量（`os.environ`）\n2. `.env.local` 文件\n3. `.env` 文件\n\n**禁用机制：**\n设置环境变量 `DEPEVAL_DISABLE_DOTENV=1` 可禁用自动环境变量加载。\n\n资料来源：[deepeval/config/settings.py:1-30]()\n\n### 合成器配置\n\n`ContextConstructionConfig` 是合成器用于从文档生成测试数据的配置类：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| chunk_size | int | 1000 | 文档分块大小 |\n| chunk_overlap | int | 200 | 分块重叠区域 |\n| max_contexts_per_document | int | 10 | 单文档最大上下文数 |\n| min_contexts_per_document | int | 1 | 单文档最小上下文数 |\n| context_quality_threshold | float | 0.5 | 上下文质量阈值 |\n\n## 追踪与可观测性系统\n\n### trace 上下文管理器\n\nDeepEval 提供了 `trace` 上下文管理器用于包装 LLM 调用，实现端到端的评估追踪：\n\n```python\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\nwith trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(model=\"claude-sonnet-4-5\", ...)\n```\n\n这种设计允许在追踪上下文中自动捕获和评估所有 LLM 调用，无需修改业务代码。\n\n资料来源：[deepeval/tracing/__init__.py:1-50]()\n\n### @observe 装饰器\n\n对于更细粒度的组件级评估，DeepEval 提供了 `@observe` 装饰器：\n\n```python\nfrom deepeval.tracing import observe, update_current_span\n\n@observe()\ndef inner_component(input: str):\n output = process(input)\n update_current_span(test_case=LLMTestCase(input=input, actual_output=output))\n return output\n```\n\n`update_current_span` 函数允许在任意嵌套层级更新当前追踪 span 的测试用例数据，实现组件级别的精确评估。\n\n## 集成层架构\n\n### 集成模式矩阵\n\nDeepEval 的集成系统支持四种不同的评估模式：\n\n| 模式 | 描述 | 使用场景 |\n|------|------|---------|\n| Bare | 直接调用框架，自动创建追踪 | 快速上手 |\n| @observe / with trace | 包裹在追踪上下文中 | 需要细粒度控制 |\n| evals_iterator | 数据集迭代器集成 | 批量评估 |\n| deepeval test run | Pytest 集成 | 持续集成 |\n\n### 支持的框架集成\n\nDeepEval 官方支持以下框架的深度集成：\n\n- **OpenAI**：原生客户端集成\n- **Anthropic**：Claude 模型支持\n- **LangChain**：回调处理器模式\n- **LangGraph**：状态机评估\n- **LlamaIndex**：异步评估支持\n- **CrewAI**：多智能体评估\n- **Google ADK**：Agent Development Kit\n- **Strands**：自定义智能体框架\n\n每种集成都通过统一的回调或包装机制接入 DeepEval 的追踪和评估系统。\n\n## CLI 命令结构\n\n### generate 命令\n\n`deepeval generate` 命令用于从多种数据源生成合成测试数据：\n\n```bash\ndeepeval generate --method docs --variation single_turn --documents ./docs\n```\n\n**支持的生成方法：**\n\n| 方法 | 参数 | 说明 |\n|------|------|------|\n| DOCS | --documents | 从文档生成 |\n| CONTEXTS | --contexts-file | 从预定义上下文生成 |\n| SCRATCH | --num-goldens | 从零生成 |\n| GOLDENS | --goldens-file | 基于现有测试数据扩充 |\n\n资料来源：[deepeval/cli/generate/command.py:1-100]()\n\n### test 命令\n\n`deepeval test run` 命令执行 Pytest 测试并自动同步结果到 Confident AI 平台：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n该命令会自动加载 `.env.local` 和 `.env` 中的配置，执行测试后上传结果。\n\n## 模块间依赖关系\n\n```mermaid\ngraph LR\n subgraph \"依赖层级\"\n A[配置层
config/]\n B[基础层
base_metric.py]\n C[指标层
indicator.py]\n D[测试用例层
test_case/]\n E[合成器层
synthesizer/]\n F[追踪层
tracing/]\n G[CLI 层
cli/]\n end\n \n A --> B\n B --> C\n D --> C\n A --> D\n C --> E\n F --> E\n E --> G\n C --> G\n```\n\n## 关键设计模式\n\n### 1. 策略模式\n\n所有指标实现统一的 `BaseMetric` 接口，允许在运行时动态替换评估策略：\n\n```python\n# 同一接口，不同实现\nmetrics = [\n AnswerRelevancyMetric(threshold=0.7),\n FaithfulnessMetric(threshold=0.8),\n]\n```\n\n### 2. 装饰器模式\n\n`@assert_test` 和 `@observe` 装饰器为普通函数添加评估能力，无需修改业务逻辑：\n\n```python\n@assert_test(llm_output_symbol=\"actual_output\")\ndef my_llm_app():\n return llm.invoke(\"Hello\")\n```\n\n### 3. 上下文管理器模式\n\n`trace` 上下文管理器自动管理追踪生命周期，确保资源正确释放：\n\n```python\nwith trace(metrics=[metric]):\n # 追踪范围内所有 LLM 调用自动被捕获\n pass\n```\n\n## 扩展开发指南\n\n### 创建自定义指标\n\n要创建自定义指标，需继承 `BaseMetric` 并实现核心方法：\n\n```python\nclass MyCustomMetric(BaseMetric):\n def __init__(self, threshold=0.5):\n self.threshold = threshold\n \n def measure(self, test_case: LLMTestCase) -> float:\n # 实现评估逻辑\n score = self._evaluate(test_case)\n self.score = score\n self.reason = self._generate_reason(score)\n return score\n \n async def a_measure(self, test_case: LLMTestCase) -> float:\n # 可选的异步实现\n pass\n```\n\n### 框架集成开发\n\n开发新的框架集成需要实现相应的回调接口：\n\n1. 实现框架特定的回调处理器\n2. 在回调中调用 `update_current_span` 更新追踪数据\n3. 注册集成模块到 `deepeval/integrations/`\n\n## 总结\n\nDeepEval 的核心模块结构体现了清晰的关注点分离和高度的可扩展性。配置管理、指标系统、测试用例和追踪系统构成了框架的基础骨架，而丰富的集成层则将这一能力延伸到各类 LLM 应用开发框架中。通过统一的设计模式和标准化的接口，开发者可以轻松地添加自定义指标或接入新的框架，使 DeepEval 成为 LLM 应用评估的通用解决方案。\n\n---\n\n\n\n## 测试用例定义\n\n### 相关页面\n\n相关主题：[评估执行引擎](#page-evaluate-engine), [评估指标体系](#page-metrics), [数据集管理](#page-dataset-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n- [deepeval/test_case/llm_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)\n- [deepeval/test_case/conversational_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/conversational_test_case.py)\n- [deepeval/test_case/arena_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/arena_test_case.py)\n- [deepeval/test_case/mcp.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/mcp.py)\n \n\n# 测试用例定义\n\n## 概述\n\n在 DeepEval 框架中，测试用例是评估 LLM 应用质量的核心数据结构。测试用例定义了评估所需的输入、期望输出、实际输出以及相关的上下文信息，DeepEval 通过将这些测试用例与评估指标结合来执行自动化评估。\n\nDeepEval 支持多种类型的测试用例，分别对应不同的评估场景：\n\n| 测试用例类型 | 用途 | 适用场景 |\n|-------------|------|---------|\n| `LLMTestCase` | 单轮对话评估 | 简单的问答、文本生成任务 |\n| `ConversationalTestCase` | 多轮对话评估 | 聊天机器人、对话系统 |\n| `ArenaTestCase` | 对比评估 | 模型比较、A/B 测试 |\n| `MCPTestCase` | MCP 协议评估 | Model Context Protocol 集成 |\n\n资料来源：[deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n\n## 核心组件\n\n### LLMTestCase（单轮测试用例）\n\n`LLMTestCase` 是 DeepEval 中最基础的测试用例类，用于定义单轮 LLM 交互的评估数据。\n\n```python\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\n```\n\n资料来源：[deepeval/test_case/llm_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)\n\n### 参数说明\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `input` | str | 是 | 用户输入或查询 |\n| `actual_output` | str | 是 | LLM 应用的实际输出 |\n| `expected_output` | str | 否 | 期望的正确答案 |\n| `retrieval_context` | List[str] | 否 | RAG 系统的检索上下文 |\n| `context` | List[str] | 否 | 额外的上下文信息 |\n| `id` | str | 否 | 测试用例唯一标识符 |\n\n### SingleTurnParams 枚举\n\n`SingleTurnParams` 定义了单轮评估中可用的参数枚举，用于配置 G-Eval 等评估指标：\n\n| 枚举值 | 对应属性 | 说明 |\n|--------|----------|------|\n| `INPUT` | `input` | 用户输入 |\n| `ACTUAL_OUTPUT` | `actual_output` | 实际输出 |\n| `EXPECTED_OUTPUT` | `expected_output` | 期望输出 |\n| `RETRIEVAL_CONTEXT` | `retrieval_context` | 检索上下文 |\n| `CONTEXT` | `context` | 额外上下文 |\n\n资料来源：[deepeval/test_case/llm_test_case.py:1-50](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)\n\n## ConversationalTestCase（多轮对话测试用例）\n\n### 概述\n\n`ConversationalTestCase` 用于评估多轮对话场景，每个测试用例包含一系列消息序列。\n\n```python\nfrom deepeval.test_case import ConversationalTestCase, ConversationalTurn\n\ntest_case = ConversationalTestCase(\n turns=[]\n)\n```\n\n### 消息结构\n\n多轮测试用例中的每条消息（turn）包含：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `messages` | List[Dict[str, str]] | 消息列表，格式为 `[{\"role\": \"user\"/\"assistant\", \"content\": \"...\"}]` |\n| `expected_output` | str | 期望的最终输出 |\n| `expected_tool_calls` | List[Dict] | 期望的工具调用（可选） |\n\n资料来源：[deepeval/test_case/conversational_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/conversational_test_case.py)\n\n## ArenaTestCase（对比评估测试用例）\n\n### 概述\n\n`ArenaTestCase` 用于模型对比评估场景，允许同时评估多个模型的响应。\n\n```python\nfrom deepeval.test_case import ArenaTestCase\n\narena_test_case = ArenaTestCase(\n models=[\"gpt-4\", \"claude-3-opus\"],\n input=\"What is machine learning?\",\n expected_output=\"...\"\n)\n```\n\n### ArenaTurnParams 枚举\n\n| 枚举值 | 说明 |\n|--------|------|\n| `INPUT` | 用户输入 |\n| `EXPECTED_OUTPUT` | 期望输出 |\n| `MODEL_OUTPUT` | 模型输出 |\n| `RETRIEVAL_CONTEXT` | 检索上下文 |\n\n资料来源：[deepeval/test_case/arena_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/arena_test_case.py)\n\n## 测试用例执行流程\n\n```mermaid\ngraph TD\n A[创建测试用例] --> B{选择测试用例类型}\n B -->|单轮| C[LLMTestCase]\n B -->|多轮| D[ConversationalTestCase]\n B -->|对比| E[ArenaTestCase]\n \n C --> F[定义评估指标]\n D --> F\n E --> F\n \n F --> G[调用 assert_test]\n G --> H{评估结果}\n H -->|通过| I[✅ 测试通过]\n H -->|失败| J[❌ 测试失败]\n```\n\n资料来源：[deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n\n## 使用示例\n\n### 基本单轮评估\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ndef test_case():\n correctness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n test_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n )\n assert_test(test_case, [correctness_metric])\n```\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/master/README.md)\n\n### RAG 场景评估\n\n```python\ntest_case = LLMTestCase(\n input=\"What is the return policy?\",\n actual_output=\"Our return policy allows 30 days for returns.\",\n expected_output=\"30-day return policy\",\n retrieval_context=[\n \"All items can be returned within 30 days of purchase.\",\n \"Items must be in original condition for a full refund.\"\n ]\n)\n```\n\n### 带上下文的评估\n\n```python\ntest_case = LLMTestCase(\n input=\"Summarize the document\",\n actual_output=\"The document discusses...\",\n context=[\n \"Document Title: Annual Report 2024\",\n \"Author: Company XYZ\",\n \"Published: January 2024\"\n ]\n)\n```\n\n## CLI 执行\n\n测试用例可以通过 DeepEval CLI 执行：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n其中 `test_chatbot.py` 包含使用 `assert_test` 定义的测试用例。\n\n资料来源：[deepeval/cli/inspect.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/inspect.py)\n\n## 与评估指标的集成\n\n测试用例需要与评估指标结合使用才能完成评估。常用的评估指标包括：\n\n| 指标名称 | 说明 | 适用场景 |\n|---------|------|---------|\n| `GEval` | 基于 LLM 的自动评估 | 通用评估 |\n| `TaskCompletionMetric` | 任务完成度评估 | Agent 评估 |\n| `AnswerRelevancyMetric` | 答案相关性评估 | RAG 评估 |\n| `HallucinationMetric` | 幻觉检测 | 事实准确性评估 |\n\n```python\nfrom deepeval.metrics import GEval\n\nmetric = GEval(\n name=\"Correctness\",\n criteria=\"评估实际输出与期望输出的一致性\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n)\n```\n\n## 数据隐私说明\n\n当使用 DeepEval 平台时，所有测试用例数据会自动记录到平台。更多数据隐私信息请参考官方文档。\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/master/README.md)\n\n---\n\n\n\n## 评估指标体系\n\n### 相关页面\n\n相关主题：[测试用例定义](#page-test-cases), [评估执行引擎](#page-evaluate-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/metrics/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/__init__.py)\n- [deepeval/metrics/base_metric.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/base_metric.py)\n- [deepeval/metrics/g_eval/g_eval.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/g_eval/g_eval.py)\n- [deepeval/metrics/rag/answer_relevancy/answer_relevancy.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/rag/answer_relevancy/answer_relevancy.py)\n- [deepeval/metrics/rag/faithfulness/faithfulness.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/rag/faithfulness/faithfulness.py)\n- [deepeval/metrics/agentic/task_completion/task_completion.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/agentic/task_completion/task_completion.py)\n- [README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n- [deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)\n \n\n# 评估指标体系\n\n## 概述\n\nDeepEval 的评估指标体系是一套模块化的 LLM 应用评估框架，类似于 Pytest 但专为测试大语言模型应用而设计。该体系融合了最新的研究方法，通过 G-Eval、Task Completion、Answer Relevancy 等指标，利用 LLM-as-a-Judge 及其他 NLP 模型在本地机器上运行评估。资料来源：[README.md]()\n\n评估指标体系支持多种使用方式，包括与 Pytest 集成、独立的 `evaluate()` 函数调用，以及通过 `evals_iterator()` 实现的端到端追踪评估。资料来源：[README.md]()\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[LLMTestCase] --> B[Metric Base Class]\n B --> C[GEval]\n B --> D[RAG Metrics]\n B --> E[Agentic Metrics]\n D --> D1[AnswerRelevancyMetric]\n D --> D2[FaithfulnessMetric]\n E --> E1[TaskCompletionMetric]\n E --> E2[ToolCorrectnessMetric]\n F[评估结果] --> G[Score & Reason]\n```\n\n### 指标分类总览\n\n| 类别 | 指标名称 | 用途 | 适用场景 |\n|------|----------|------|----------|\n| 通用框架 | GEval | 基于自定义标准的多维度评估 | 通用场景 |\n| RAG 评估 | Answer Relevancy | 衡量 RAG 输出的相关性 | RAG 流水线 |\n| RAG 评估 | Faithfulness | 评估输出与检索上下文的忠实度 | RAG 流水线 |\n| Agentic 评估 | Task Completion | 评估 Agent 是否完成目标 | AI Agent |\n| Agentic 评估 | Tool Correctness | 检查工具调用是否正确 | AI Agent |\n| Agentic 评估 | Goal Accuracy | 衡量 Agent 目标达成准确度 | AI Agent |\n\n资料来源：[README.md]()\n\n## 指标基类设计\n\n### BaseMetric 抽象基类\n\n所有评估指标继承自 `BaseMetric` 基类，该基类定义了指标的核心接口和行为规范。资料来源：[deepeval/metrics/base_metric.py]()\n\n#### 核心属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | str | 指标名称 |\n| threshold | float | 通过阈值，范围 0-1 |\n| score | float | 当前测量得分 |\n| reason | str | 评分理由说明 |\n| verbose | bool | 是否输出详细信息 |\n\n#### 核心方法\n\n| 方法 | 说明 |\n|------|------|\n| measure(test_case) | 执行评估并返回分数 |\n| save() | 保存评估结果 |\n| load() | 加载历史评估结果 |\n\n```python\nclass BaseMetric(ABC):\n \"\"\"所有评估指标的抽象基类\"\"\"\n \n @abstractmethod\n def measure(self, test_case: LLMTestCase) -> float:\n \"\"\"执行评估的核心方法\"\"\"\n pass\n```\n\n资料来源：[deepeval/metrics/base_metric.py]()\n\n### 指标执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as Metric\n participant LLM as LLM API\n participant TC as TestCase\n \n U->>M: measure(test_case)\n M->>TC: 提取评估参数\n M->>LLM: 发送评估 Prompt\n LLM-->>M: 评估结果\n M->>M: 计算分数\n M->>M: 生成 Reason\n M-->>U: 返回 Score\n```\n\n## 通用评估框架\n\n### GEval 指标\n\nGEval 是 DeepEval 实现的一种基于最新研究的评估框架，通过 LLM-as-a-Judge 方式对 LLM 输出进行自动化评估。资料来源：[deepeval/metrics/g_eval/g_eval.py]()\n\n#### 参数配置\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | str | 是 | 指标名称 |\n| criteria | str | 是 | 评估标准描述 |\n| evaluation_params | List[SingleTurnParams] | 是 | 评估所需参数 |\n| threshold | float | 否 | 通过阈值，默认 0.5 |\n| model | str | 否 | 使用的 LLM 模型 |\n\n#### 使用示例\n\n```python\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ncorrectness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n)\n\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund.\"\n)\n\nscore = correctness_metric.measure(test_case)\nprint(f\"Score: {score}, Reason: {correctness_metric.reason}\")\n```\n\n资料来源：[deepeval/metrics/g_eval/g_eval.py]()\n\n### GEval 工作原理\n\n```mermaid\ngraph LR\n A[输入 TestCase] --> B[构建 Chain-of-Thought Prompt]\n B --> C[添加评估标准]\n C --> D[调用 LLM API]\n D --> E[LLM 返回评分]\n E --> F[解析分数与理由]\n F --> G[返回评估结果]\n```\n\nGEval 的核心优势在于其灵活性，允许用户定义任意评估标准，通过思维链方式引导 LLM 进行高质量评判。资料来源：[deepeval/metrics/g_eval/g_eval.py]()\n\n## RAG 评估指标\n\nRAG（检索增强生成）评估指标专门用于评估 RAG 流水线的性能，包括答案相关性、忠实度、上下文相关性等维度。资料来源：[deepeval/metrics/rag/answer_relevancy/answer_relevancy.py]()\n\n### Answer Relevancy Metric（答案相关性）\n\n答案相关性指标衡量 RAG 系统输出与输入查询之间的相关程度。资料来源：[deepeval/metrics/rag/answer_relevancy/answer_relevancy.py]()\n\n#### 核心参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| threshold | float | 0.7 | 通过阈值 |\n| model | str | None | 使用的大语言模型 |\n| include_reason | bool | True | 是否包含评分理由 |\n\n#### 实现原理\n\n```python\nanswer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\nanswer_relevancy_metric.measure(test_case)\n```\n\n答案相关性评估会分析输入、输出和检索上下文之间的关系，计算语义相似度得分。资料来源：[deepeval/metrics/rag/answer_relevancy/answer_relevancy.py]()\n\n### Faithfulness Metric（忠实度）\n\n忠实度指标评估 RAG 输出的事实准确性，即输出是否与检索到的上下文信息相符。资料来源：[deepeval/metrics/rag/faithfulness/faithfulness.py]()\n\n#### 使用方式\n\n```python\nfrom deepeval.metrics import FaithfulnessMetric\nfrom deepeval.test_case import LLMTestCase\n\nfaithfulness_metric = FaithfulnessMetric(threshold=0.8)\ntest_case = LLMTestCase(\n input=\"公司年假政策是什么？\",\n actual_output=\"员工每年有15天带薪年假\",\n retrieval_context=[\"公司政策规定：员工第一年享有10天年假，工作满3年后增至15天\"]\n)\n\nfaithfulness_metric.measure(test_case)\n```\n\n该指标通过对比输出内容与检索上下文，识别潜在的幻觉（hallucination）问题。资料来源：[deepeval/metrics/rag/faithfulness/faithfulness.py]()\n\n## Agentic 评估指标\n\nAgentic 评估指标专注于 AI Agent 系统的评估，包括任务完成度、工具调用准确性、目标达成率等关键维度。资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()\n\n### Task Completion Metric（任务完成度）\n\n任务完成度是评估 Agent 是否成功达成用户目标的核心指标。资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()\n\n#### 参数配置\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| threshold | float | 否 | 0.5 | 通过阈值 |\n| model | str | 否 | None | 评估用模型 |\n| include_reason | bool | 否 | True | 包含评分理由 |\n| verbose | bool | 否 | False | 详细输出模式 |\n\n#### 使用示例\n\n```python\nfrom deepeval.metrics import TaskCompletionMetric\n\ntask_completion_metric = TaskCompletionMetric(threshold=0.7)\n\nfor golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()\n\n### Agentic 指标体系全景\n\n```mermaid\ngraph TD\n A[Agentic 评估] --> B[任务完成]\n A --> C[工具使用]\n A --> D[规划能力]\n A --> E[参数正确性]\n \n B --> B1[TaskCompletion]\n B --> B2[GoalAccuracy]\n \n C --> C1[ToolCorrectness]\n C --> C2[ToolUse]\n \n D --> D1[PlanAdherence]\n D --> D2[PlanQuality]\n D --> D3[StepEfficiency]\n \n E --> E1[ArgumentCorrectness]\n \n style A fill:#f9f,color:#000\n style B fill:#bbf,color:#000\n style C fill:#bbf,color:#000\n style D fill:#bbf,color:#000\n style E fill:#bbf,color:#000\n```\n\n| 指标名称 | 用途 | 资料来源 |\n|----------|------|----------|\n| Task Completion | 评估 Agent 是否完成目标 | [task_completion.py]() |\n| Tool Correctness | 检查工具调用正确性 | README.md |\n| Goal Accuracy | 衡量目标达成准确度 | README.md |\n| Step Efficiency | 评估步骤效率 | README.md |\n| Plan Adherence | 检查计划执行情况 | README.md |\n| Plan Quality | 评估计划质量 | README.md |\n| Tool Use | 测量工具使用质量 | README.md |\n| Argument Correctness | 验证工具参数正确性 | README.md |\n\n资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()、[README.md]()\n\n## 指标使用方式\n\n### 与 Pytest 集成\n\n通过 `@assert_test` 装饰器实现与 Pytest 的深度集成，这是 DeepEval 推荐的评估方式。资料来源：[README.md]()\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\n@pytest.mark.parametrize(\n \"test_case\",\n [LLMTestCase(input=\"...\", actual_output=\"...\", expected_output=\"...\")],\n)\n@assert_test\ndef test_correctness(test_case):\n correctness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n return correctness_metric\n```\n\n### 独立评估模式\n\n在 Jupyter Notebook 或脚本环境中，可以使用独立的 `evaluate()` 函数进行评估。资料来源：[README.md]()\n\n```python\nfrom deepeval import evaluate\nfrom deepeval.metrics import AnswerRelevancyMetric\nfrom deepeval.test_case import LLMTestCase\n\nanswer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund\"]\n)\nevaluate([test_case], [answer_relevancy_metric])\n```\n\n### 追踪评估模式\n\n使用 `evals_iterator()` 实现端到端追踪评估，适用于框架集成场景。资料来源：[deepeval/integrations/README.md]()\n\n```python\nfrom deepeval.tracing import observe\nfrom deepeval.metrics import TaskCompletionMetric\n\n@observe(metrics=[TaskCompletionMetric()])\ndef app(input: str):\n # Agent 逻辑\n return result\n\nfor golden in dataset.evals_iterator():\n app(golden.input)\n```\n\n## 指标结果解读\n\n### 评分机制\n\n所有指标分数统一在 0-1 范围内，阈值参数决定测试是否通过。资料来源：[README.md]()\n\n| 分数范围 | 含义 | 行为 |\n|----------|------|------|\n| 0.0-0.5 | 低质量输出 | 通常不满足阈值 |\n| 0.5-0.7 | 中等质量 | 取决于阈值设置 |\n| 0.7-1.0 | 高质量输出 | 通常满足阈值 |\n\n### Reason 字段\n\n每个指标在评估后会生成 `reason` 字段，提供 LLM 评判的详细解释，便于调试和理解评估逻辑。资料来源：[deepeval/metrics/base_metric.py]()\n\n```python\nprint(metric.score) # 0.85\nprint(metric.reason) # \"The response correctly addresses the user's question...\"\n```\n\n## 集成框架支持\n\nDeepEval 指标体系支持多种主流 LLM 应用框架的集成评估。资料来源：[deepeval/integrations/README.md]()\n\n| 框架 | 集成方式 | 评估模式 |\n|------|----------|----------|\n| OpenAI | 原生追踪 | Bare + @observe + evals_iterator |\n| Anthropic | 原生追踪 | Bare + @observe + evals_iterator |\n| LangChain | CallbackHandler | evals_iterator |\n| LangGraph | CallbackHandler | evals_iterator |\n| LlamaIndex | AsyncConfig | evals_iterator |\n| CrewAI | instrument_crewai() | evals_iterator |\n| Pydantic AI | 集成 | evals_iterator |\n| Google ADK | instrument_google_adk() | evals_iterator |\n| Strands | instrument_strands() | evals_iterator |\n| AWS AgentCore | instrument_agentcore() | evals_iterator |\n\n资料来源：[deepeval/integrations/README.md]()\n\n## 最佳实践\n\n### 指标选择指南\n\n| 应用场景 | 推荐指标组合 |\n|----------|--------------|\n| RAG 流水线 | AnswerRelevancy + Faithfulness |\n| AI Agent | TaskCompletion + ToolCorrectness |\n| 通用对话 | GEval（自定义标准）|\n| 多轮对话 | Conversational Metrics |\n\n### 阈值设置建议\n\n1. **保守设置**：threshold=0.7 适用于生产环境，确保高质量输出\n2. **宽松设置**：threshold=0.5 适用于开发阶段，快速迭代\n3. **渐进调整**：根据历史评估结果逐步调整阈值\n\n### 环境变量配置\n\nDeepEval 自动加载环境变量，优先级为：进程环境变量 > .env.local > .env。可通过 `DEEPEVAL_DISABLE_DOTENV=1` 禁用自动加载。资料来源：[README.md]()\n\n## 扩展开发\n\n开发者可以通过继承 `BaseMetric` 基类创建自定义评估指标：\n\n```python\nfrom deepeval.metrics.base_metric import BaseMetric\nfrom deepeval.test_case import LLMTestCase\n\nclass CustomMetric(BaseMetric):\n def __init__(self, threshold: float = 0.5):\n self.threshold = threshold\n \n def measure(self, test_case: LLMTestCase) -> float:\n # 自定义评估逻辑\n score = self._evaluate(test_case)\n self.score = score\n return score\n```\n\n资料来源：[deepeval/metrics/base_metric.py]()\n\n## 总结\n\nDeepEval 的评估指标体系提供了从通用到专用的完整评估能力，通过模块化设计支持灵活组合和扩展。G-Eval 作为核心评估框架，结合 RAG 和 Agentic 专用指标，能够全面覆盖各类 LLM 应用的评估需求。开发者可以根据具体场景选择合适的指标组合，并通过 Pytest 集成、独立调用或追踪模式等多种方式执行评估。\n\n---\n\n\n\n## 评估执行引擎\n\n### 相关页面\n\n相关主题：[测试用例定义](#page-test-cases), [评估指标体系](#page-metrics), [追踪系统](#page-tracing-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/evaluate/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/__init__.py)\n- [deepeval/evaluate/evaluate.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/evaluate.py)\n- [deepeval/evaluate/api.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/api.py)\n- [deepeval/evaluate/execute/e2e.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/e2e.py)\n- [deepeval/evaluate/execute/agentic.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/agentic.py)\n- [deepeval/evaluate/console_report.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/console_report.py)\n- [deepeval/evaluate/configs.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/configs.py)\n \n\n# 评估执行引擎\n\n## 概述\n\n评估执行引擎是 DeepEval 框架的核心组件，负责驱动 LLM 应用的质量评估流程。它封装了评估的完整生命周期，包括测试用例加载、指标计算、结果收集与报告生成。该引擎支持两种主要的评估模式：端到端评估（E2E）和代理式评估（Agentic），能够适应不同的测试场景和集成需求。资料来源：[README.md]()\n\n```mermaid\ngraph TD\n A[评估执行引擎] --> B[端到端评估 E2E]\n A --> C[代理式评估 Agentic]\n B --> D[Test Case 加载]\n B --> E[指标计算]\n B --> F[结果收集]\n C --> G[Trace 追踪]\n C --> H[Span 跨度]\n C --> I[工具调用验证]\n```\n\n## 核心架构\n\n### 模块组织结构\n\n评估执行引擎的代码位于 `deepeval/evaluate/` 目录下，采用分层架构设计：\n\n| 模块路径 | 功能职责 |\n|---------|---------|\n| `__init__.py` | 公共 API 导出 |\n| `evaluate.py` | 核心评估入口函数 |\n| `api.py` | 评估 API 接口定义 |\n| `execute/e2e.py` | 端到端评估执行器 |\n| `execute/agentic.py` | 代理式评估执行器 |\n| `console_report.py` | 控制台报告生成 |\n| `configs.py` | 评估配置管理 |\n\n### 评估入口函数\n\n评估执行引擎的主入口是 `evaluate()` 函数，支持同步和异步两种调用模式。开发者可以通过该函数批量执行测试用例并获取评估结果。资料来源：[deepeval/evaluate/__init__.py]()\n\n```python\nfrom deepeval import evaluate\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase\n\n# 创建评估指标\ncorrectness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n)\n\n# 创建测试用例\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\"\n)\n\n# 执行评估\nevaluate([test_case], [correctness_metric])\n```\n\n## 评估模式\n\n### 端到端评估（E2E）\n\n端到端评估将 LLM 应用视为黑盒，通过输入输出对进行质量验证。这种模式特别适用于快速迭代开发和回归测试场景，无需深入了解应用内部实现。资料来源：[deepeval/evaluate/execute/e2e.py]()\n\n**工作流程：**\n\n```mermaid\ngraph LR\n A[输入 TestCase] --> B[加载指标]\n B --> C[执行指标评估]\n C --> D[收集评分]\n D --> E[生成报告]\n```\n\n端到端评估的核心流程如下：\n\n1. 接收 `LLMTestCase` 测试用例对象\n2. 初始化指定的评估指标\n3. 按顺序或并发执行各项指标计算\n4. 汇总所有指标得分\n5. 与阈值比较判断通过/失败\n6. 生成结构化结果输出\n\n### 代理式评估（Agentic）\n\n代理式评估针对 AI 代理应用设计，不仅验证最终输出，还追踪整个执行过程，包括工具调用、决策路径和中间状态。这种模式适用于复杂的多步骤任务评估。资料来源：[deepeval/evaluate/execute/agentic.py]()\n\n**追踪机制：**\n\n代理式评估利用 OpenTelemetry 标准的 Trace 和 Span 来记录执行轨迹。每个代理操作被封装为独立的 Span，通过父-子关系形成完整的调用链。这种设计允许评估引擎回溯任意时间点的执行状态，并针对特定操作进行指标验证。\n\n```python\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\n# 使用 trace 上下文包装评估\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n## 配置系统\n\n### 评估配置类\n\nDeepEval 提供 `EvaluationConfig` 类用于定制评估行为，支持细粒度的执行控制。资料来源：[deepeval/evaluate/configs.py]()\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `run_async` | bool | 是否启用异步执行模式 |\n| `max_concurrent` | int | 最大并发评估数 |\n| `use_cached_results` | bool | 是否使用缓存的评估结果 |\n| `print_results` | bool | 是否在控制台打印结果 |\n| `save_results` | bool | 是否保存评估结果到文件 |\n\n### 异步配置\n\n对于需要处理大量测试用例的场景，引擎支持异步并发执行。通过 `AsyncConfig` 类可以控制并发度和超时行为。资料来源：[deepeval/evaluate/configs.py]()\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\n\nasync_config = AsyncConfig(\n run_async=True,\n max_concurrent=10, # 最大并发任务数\n timeout=300 # 单个任务超时时间（秒）\n)\n```\n\n## 报告生成\n\n### 控制台报告\n\n评估完成后，引擎自动生成控制台报告，包含测试用例总数、通过率、各指标得分分布等关键信息。资料来源：[deepeval/evaluate/console_report.py]()\n\n**报告内容包括：**\n\n- 整体通过率统计\n- 各指标得分详情\n- 失败用例的错误信息\n- 执行耗时分析\n- 资源使用情况（如适用）\n\n### 结构化输出\n\n评估结果以标准化的数据结构返回，便于后续分析和集成：\n\n```python\nresult = evaluate([test_case], [correctness_metric])\n\n# 结果对象包含以下属性\nprint(result.success) # 整体是否通过\nprint(result.metrics) # 各指标得分\nprint(result.duration) # 执行耗时\nprint(result.error) # 错误信息（如有）\n```\n\n## 集成方式\n\n### Pytest 集成\n\nDeepEval 与 Pytest 无缝集成，通过 `@assert_test` 装饰器将评估逻辑嵌入标准测试用例。资料来源：[README.md]()\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\n@pytest.fixture\ndef correctness_metric():\n return GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n\n@assert_test(assertion_fn=correctness_metric)\ndef test_chatbot_response(test_case: LLMTestCase):\n return test_case\n```\n\n### 框架集成\n\n评估引擎支持主流 LLM 框架的自动检测和集成，包括 OpenAI、Anthropic、LangChain、LangGraph、LlamaIndex、Pydantic AI、CrewAI 等。资料来源：[deepeval/integrations/README.md]()\n\n**集成特性矩阵：**\n\n| 框架 | Bare 模式 | @observe 包装 | evals_iterator | pytest 集成 |\n|------|-----------|--------------|----------------|-------------|\n| OpenAI | ✅ | ✅ | ✅ | ✅ |\n| Anthropic | ✅ | ✅ | ✅ | ✅ |\n| LangChain | ✅ | ✅ | ✅ | ✅ |\n| LangGraph | ✅ | ✅ | ✅ | ✅ |\n| LlamaIndex | ✅ | ✅ | ✅ | ✅ |\n| Pydantic AI | ✅ | ✅ | ✅ | ✅ |\n| CrewAI | ✅ | ✅ | ✅ | ✅ |\n\n## CLI 命令行支持\n\n评估执行引擎可通过 `deepeval` CLI 调用，支持自动化测试运行和结果持久化。资料来源：[deepeval/cli/main.py]()\n\n**常用命令：**\n\n```bash\n# 运行测试文件\ndeepeval test run test_chatbot.py\n\n# 运行特定测试函数\ndeepeval test run test_chatbot.py::test_case\n\n# 指定报告输出目录\ndeepeval test run test_chatbot.py --folder ./results\n\n# 登录 Confident AI 平台同步结果\ndeepeval login\ndeepeval test run test_chatbot.py\n```\n\n## 执行流程图\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant E as 评估引擎\n participant M as 指标模块\n participant R as 报告生成器\n\n U->>E: evaluate(test_cases, metrics)\n E->>E: 初始化评估配置\n E->>M: 加载评估指标\n loop 每个测试用例\n E->>M: 执行指标计算\n M-->>E: 返回指标得分\n E->>E: 与阈值比较\n end\n E->>R: 生成评估报告\n R-->>U: 返回评估结果\n```\n\n## 最佳实践\n\n### 性能优化建议\n\n1. **批量评估**：将多个相关测试用例一起评估，减少 LLM 调用开销\n2. **并发控制**：根据 API 速率限制调整 `max_concurrent` 参数\n3. **指标选择**：仅使用必要的评估指标，避免不必要的计算\n4. **缓存利用**：在迭代开发中使用 `use_cached_results` 跳过未变更用例\n\n### 测试设计原则\n\n1. **单一职责**：每个测试用例应验证单一质量维度\n2. **明确阈值**：为每个指标设置合理的通过阈值\n3. **真实数据**：使用生产环境分布的测试数据\n4. **分层评估**：结合端到端和代理式评估全面覆盖\n\n## 扩展机制\n\n评估执行引擎支持自定义扩展，开发者可以实现以下接口：\n\n- **自定义指标**：继承 `BaseMetric` 类实现特定领域的评估逻辑\n- **自定义报告器**：实现 `BaseReporter` 接口添加新的输出格式\n- **自定义集成**：通过回调机制接入新的 LLM 框架\n\n---\n\n*本文档基于 DeepEval v0.2+ 版本编写，随着框架更新，部分 API 可能发生变化。*\n\n---\n\n\n\n## 数据集管理\n\n### 相关页面\n\n相关主题：[合成数据生成](#page-synthetic-data), [测试用例定义](#page-test-cases)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/dataset/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/__init__.py)\n- [deepeval/dataset/dataset.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/dataset.py)\n- [deepeval/dataset/golden.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/golden.py)\n- [deepeval/dataset/api.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/api.py)\n- [deepeval/dataset/test_run_tracer.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/test_run_tracer.py)\n- [deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n- [deepeval/synthesizer/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/__init__.py)\n\n \n\n# 数据集管理\n\n## 概述\n\nDeepEval 的数据集管理模块是整个 LLM 评估框架的核心基础设施，负责管理和组织用于评估大型语言模型应用的测试数据。该模块支持多种数据格式导入、测试用例的组织与管理、以及与 Confident AI 平台的同步功能。\n\n数据集管理的主要职责包括：\n\n- **测试用例管理**：创建、组织和管理 `LLMTestCase` 对象\n- **迭代器功能**：通过 `evals_iterator()` 遍历数据集并执行评估\n- **Golden 数据集**：管理高质量的参考数据集（goldens）用于评估\n- **评估结果追踪**：记录和回溯每次评估运行的结果\n\n## 核心组件\n\n### LLMTestCase\n\n`LLMTestCase` 是 DeepEval 中用于定义单个测试用例的基础数据模型。每个测试用例包含输入、期望输出和实际输出等关键字段。\n\n```python\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ntest_case = LLMTestCase(\n input=\"用户输入内容\",\n actual_output=\"LLM实际输出\",\n expected_output=\"期望的正确答案\",\n retrieval_context=[\"上下文文档1\", \"上下文文档2\"]\n)\n```\n\n**主要参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `input` | str | 是 | 传入 LLM 应用的输入/提示词 |\n| `actual_output` | str | 是 | LLM 应用的真实输出 |\n| `expected_output` | str | 否 | 期望的参考答案 |\n| `retrieval_context` | List[str] | 否 | RAG 场景中的检索上下文 |\n| `context` | List[str] | 否 | 一般上下文信息 |\n\n### Golden 数据集\n\nGolden 数据集是经过精心准备的高质量参考数据集，用于验证 LLM 应用的输出质量。\n\n```python\nfrom deepeval.synthesizer import Synthesizer\n\nsynthesizer = Synthesizer(model=model)\nsynthesizer.generate_goldens_from_docs(\n document_paths=[\"path/to/doc.pdf\"],\n include_expected_output=True,\n max_goldens_per_context=5\n)\n```\n\n## 数据集迭代与评估\n\n### evals_iterator 方法\n\n`evals_iterator()` 是数据集的核心迭代方法，支持在遍历数据集的同时执行评估。该方法与各种框架集成兼容，支持端到端和组件级别的评估。\n\n```python\nfrom deepeval.metrics import TaskCompletionMetric\n\n# 端到端评估\nfor golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):\n invoke({\"prompt\": golden.input})\n```\n\n### 异步评估配置\n\nDeepEval 支持异步评估模式，适用于大规模数据集的高效处理：\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\nfrom deepeval.metrics import TaskCompletionMetric\n\nasync_config = AsyncConfig(run_async=True, max_concurrent=10)\n\nfor golden in dataset.evals_iterator(\n async_config=async_config,\n metrics=[TaskCompletionMetric()],\n):\n task = asyncio.create_task(agent.run(golden.input))\n dataset.evaluate(task)\n```\n\n### 异步配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `run_async` | bool | False | 启用异步模式 |\n| `max_concurrent` | int | 1 | 最大并发任务数 |\n| `timeout` | int | None | 单个任务超时时间（秒） |\n\n## 框架集成\n\n### OpenAI 集成\n\n```python\nfrom deepeval.anthropic import Anthropic\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\nclient = Anthropic()\n\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n### LangChain 集成\n\n```python\nfrom deepeval.integrations.langchain import CallbackHandler\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator():\n llm.invoke(\n golden.input,\n config={\"callbacks\": [CallbackHandler(metrics=[TaskCompletionMetric()])]},\n )\n```\n\n### LangGraph 集成\n\n```python\nfrom deepeval.integrations.langchain import CallbackHandler\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator():\n agent.invoke(\n {\"messages\": [{\"role\": \"user\", \"content\": golden.input}]},\n config={\"callbacks\": [CallbackHandler(metrics=[TaskCompletionMetric()])]},\n )\n```\n\n### LlamaIndex 集成\n\n```python\nimport asyncio\nfrom deepeval.evaluate.configs import AsyncConfig\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator(\n async_config=AsyncConfig(run_async=True),\n metrics=[TaskCompletionMetric()],\n):\n task = asyncio.create_task(agent.run(golden.input))\n dataset.evaluate(task)\n```\n\n## 数据集生成\n\nDeepEval 提供多种方式生成测试数据集：\n\n| 生成方法 | 说明 | 适用场景 |\n|---------|------|---------|\n| `DOCS` | 从文档中提取 | 已有知识库文档 |\n| `CONTEXTS` | 从上下文中生成 | 结构化上下文数据 |\n| `SCRATCH` | 从零开始生成 | 无预定义数据 |\n| `GOLDENS` | 基于现有数据扩展 | 已有少量高质量数据 |\n\n### 单轮与多轮变体\n\n数据集支持单轮（Single Turn）和多轮（Multi-turn Conversational）两种评估模式：\n\n```python\nfrom deepeval.cli.generate.utils import GoldenVariation\n\n# 单轮评估\nsynthesizer.generate_goldens_from_docs(\n document_paths=document_paths,\n include_expected_output=True\n)\n\n# 多轮对话评估\nsynthesizer.generate_conversational_goldens_from_docs(\n document_paths=document_paths,\n include_expected_outcome=True\n)\n```\n\n## 评估工作流\n\n```mermaid\ngraph TD\n A[准备数据集] --> B[创建 LLMTestCase]\n B --> C[配置评估指标]\n C --> D[使用 evals_iterator 遍历]\n D --> E{框架类型}\n E -->|LangChain| F[CallbackHandler]\n E -->|OpenAI| G[trace 上下文]\n E -->|LlamaIndex| H[AsyncConfig]\n F --> I[执行评估]\n G --> I\n H --> I\n I --> J[记录测试结果]\n J --> K[同步至 Confident AI]\n```\n\n## 测试运行追踪\n\n### Test Run Tracer\n\n`TestRunTracer` 负责记录每次评估运行的关键信息，包括：\n\n- 测试用例执行状态\n- 评估指标得分\n- 执行时间和资源消耗\n- 错误和异常信息\n\n### 评估结果保存\n\n评估结果可以通过 `deepeval test run` 命令自动保存：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n结果文件格式为 `test_run_*.json`，可通过 `deepeval inspect` 命令查看：\n\n```bash\ndeepeval inspect # 查看最新运行结果\ndeepeval inspect path/to/file.json # 查看指定文件\ndeepeval inspect -f ./results # 查看指定目录\n```\n\n## 配置管理\n\n### 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `DEEPEVAL_RESULTS_FOLDER` | 评估结果保存目录 |\n| `DEEPEVAL_API_KEY` | Confident AI API 密钥 |\n\n### .env 配置\n\nDeepEval 支持 `.env.local` 文件进行本地配置：\n\n```bash\ncp .env.example .env.local\n# 编辑 .env.local 文件\n```\n\n## 与 Confident AI 集成\n\nDeepEval 数据集管理与 Confident AI 平台深度集成，提供以下云端功能：\n\n- **数据集存储**：云端存储和管理测试数据集\n- **评估报告**：生成可分享的评估报告\n- **迭代追踪**：比较不同版本的 LLM 应用表现\n- **协作功能**：团队成员共享和协作测试数据集\n\n登录命令：\n\n```bash\ndeepeval login\n```\n\n## 最佳实践\n\n1. **数据集质量**：确保 Golden 数据集包含多样化、高质量的测试用例\n2. **评估指标选择**：根据应用场景选择合适的评估指标\n3. **异步处理**：大规模数据集建议使用异步模式提高效率\n4. **结果回溯**：定期保存和审查评估结果用于持续优化\n5. **框架集成**：选择最适合你技术栈的框架集成方式\n\n---\n\n\n\n## 合成数据生成\n\n### 相关页面\n\n相关主题：[数据集管理](#page-dataset-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/synthesizer/synthesizer.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/synthesizer.py)\n- [deepeval/synthesizer/base_synthesizer.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/base_synthesizer.py)\n- [deepeval/synthesizer/schema.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/schema.py)\n- [deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n- [deepeval/synthesizer/config.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/config.py)\n \n\n# 合成数据生成\n\n## 概述\n\n合成数据生成（Synthetic Data Generation）是 DeepEval 框架中用于自动创建测试用例的核心功能。该功能通过 LLM 自动生成高质量的测试数据，包括单轮问答和多轮对话场景，帮助开发者快速构建评估数据集。\n\nSynthesizer（合成器）是实现这一功能的核心类，它封装了多种生成策略，支持从文档、上下文、已有测试用例或完全空白状态生成合成数据。资料来源：[deepeval/synthesizer/synthesizer.py:1-50]()\n\n## 核心架构\n\n### 类结构\n\n```mermaid\ngraph TD\n A[Synthesizer] --> B[BaseSynthesizer]\n B --> C[可配置生成策略]\n B --> D[异步/同步模式]\n A --> E[ContextConstructionConfig]\n A --> F[StylingConfig]\n A --> G[ConversationalStylingConfig]\n```\n\n### 数据模型\n\n合成数据生成涉及以下核心数据模型：\n\n| 模型类 | 用途 | 关键属性 |\n|--------|------|----------|\n| `GoldenContext` | 单轮对话上下文 | `input`, `expected_output`, `context` |\n| `ScenarioContext` | 多轮对话场景 | `scenario`, `conversational_task`, `participant_roles` |\n| `ConversationTurn` | 单轮对话 | `input`, `expected_output` |\n| `ConversationRound` | 多轮对话 | `turns`, `expected_outcome` |\n\n资料来源：[deepeval/synthesizer/schema.py:1-100]()\n\n## 生成方法\n\n### 四种生成策略\n\nDeepEval 支持四种主要的合成数据生成方法：\n\n| 方法 | 枚举值 | 描述 |\n|------|--------|------|\n| 文档生成 | `GenerationMethod.DOCS` | 从源文档中提取上下文并生成测试用例 |\n| 上下文生成 | `GenerationMethod.CONTEXTS` | 基于预定义的上下文生成测试用例 |\n| 从零生成 | `GenerationMethod.SCRATCH` | 无外部输入，完全由 LLM 创意生成 |\n| Goldens 扩展 | `GenerationMethod.GOLDENS` | 基于已有测试用例进行变体扩展 |\n\n资料来源：[deepeval/cli/generate/command.py:1-80]()\n\n### 单轮与多轮对话\n\n```mermaid\ngraph LR\n A[生成请求] --> B{对话类型}\n B -->|单轮| C[GoldenVariation.SINGLE_TURN]\n B -->|多轮| D[GoldenVariation.CONVERSATIONAL]\n C --> E[generate_goldens_from_*]\n D --> F[generate_conversational_goldens_from_*]\n```\n\n| 变体类型 | 枚举值 | 生成方法 |\n|----------|--------|----------|\n| 单轮对话 | `GoldenVariation.SINGLE_TURN` | `generate_goldens_from_docs/contexts/scratch/goldens` |\n| 多轮对话 | `GoldenVariation.CONVERSATIONAL` | `generate_conversational_goldens_from_*` |\n\n## Synthesizer 类\n\n### 主要方法\n\n| 方法名 | 参数 | 返回值 | 说明 |\n|--------|------|--------|------|\n| `generate_goldens_from_docs()` | `document_paths`, `context_construction_config` | `List[GoldenContext]` | 从文档生成单轮测试用例 |\n| `generate_conversational_goldens_from_docs()` | `document_paths`, `context_construction_config` | `List[ScenarioContext]` | 从文档生成多轮测试用例 |\n| `generate_goldens_from_contexts()` | `contexts`, `max_goldens_per_context` | `List[GoldenContext]` | 从上下文生成单轮测试用例 |\n| `generate_goldens_from_scratch()` | `num_goldens` | `List[GoldenContext]` | 从零生成单轮测试用例 |\n| `generate_goldens_from_goldens()` | `goldens`, `max_goldens_per_golden` | `List[GoldenContext]` | 扩展已有测试用例 |\n| `save_as()` | `file_type`, `directory`, `file_name` | `str` | 保存结果到文件 |\n\n资料来源：[deepeval/synthesizer/synthesizer.py:100-300]()\n\n### 初始化参数\n\n```python\nSynthesizer(\n model: Optional[Any] = None, # 使用的 LLM 模型\n async_mode: bool = False, # 是否启用异步模式\n max_concurrent: int = 10, # 最大并发数\n styling_config: Optional[Any] = None, # 单轮样式配置\n conversational_styling_config: Optional[Any] = None, # 多轮样式配置\n cost_tracking: bool = True # 是否跟踪成本\n)\n```\n\n## 配置选项\n\n### ContextConstructionConfig\n\n用于配置文档分块和上下文构建：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `max_contexts_per_document` | `int` | `10` | 每个文档最多生成的上下文数 |\n| `min_contexts_per_document` | `int` | `1` | 每个文档最少生成的上下文数 |\n| `chunk_size` | `int` | `1000` | 文档分块大小 |\n| `chunk_overlap` | `int` | `200` | 分块重叠大小 |\n| `context_quality_threshold` | `float` | `0.5` | 上下文质量阈值 |\n| `context_similarity_threshold` | `float` | `0.7` | 上下文相似度阈值 |\n| `max_retries` | `int` | `3` | 最大重试次数 |\n\n资料来源：[deepeval/cli/generate/command.py:80-120]()\n\n### 样式配置\n\n#### 单轮样式配置 (StylingConfig)\n\n```python\nsingle_turn_styling_config(\n scenario: Optional[str] = None, # 场景描述\n task: Optional[str] = None, # 任务描述\n input_format: Optional[str] = None, # 输入格式模板\n expected_output_format: Optional[str] = None # 期望输出格式\n)\n```\n\n#### 多轮样式配置 (ConversationalStylingConfig)\n\n```python\nmulti_turn_styling_config(\n scenario_context: Optional[str] = None, # 场景上下文\n conversational_task: Optional[str] = None, # 对话任务描述\n participant_roles: Optional[List[str]] = None, # 参与者角色\n scenario_format: Optional[str] = None, # 场景格式模板\n expected_outcome_format: Optional[str] = None # 期望结果格式\n)\n```\n\n## CLI 命令\n\n### generate 命令\n\n```bash\ndeepeval generate \\\n --method \\\n --variation \\\n --output-dir ./output \\\n --file-name my_goldens\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `--method` | 枚举 | 是 | 生成方法 |\n| `--variation` | 枚举 | 是 | 对话类型 |\n| `--output-dir` | 路径 | 否 | 输出目录 |\n| `--file-name` | 字符串 | 否 | 输出文件名 |\n| `--file-type` | 枚举 | 否 | 输出格式 (json/csv) |\n| `--num-goldens` | 整数 | 条件必需 | 从零生成时的数量 |\n| `--documents` | 文件路径 | 条件必需 | 文档生成时的源文件 |\n| `--contexts-file` | 文件路径 | 条件必需 | 上下文生成时的文件 |\n| `--goldens-file` | 文件路径 | 条件必需 | Goldens 扩展时的输入 |\n| `--model` | 字符串 | 否 | 使用的模型 |\n| `--async-mode` | 布尔 | 否 | 启用异步模式 |\n| `--max-concurrent` | 整数 | 否 | 最大并发数 |\n\n资料来源：[deepeval/cli/generate/command.py:40-200]()\n\n## 生成流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as CLI 命令\n participant Synth as Synthesizer\n participant LLM as LLM API\n participant FS as 文件系统\n\n User->>CLI: deepeval generate --method DOCS\n CLI->>Synth: 创建 Synthesizer 实例\n Synth->>LLM: 请求生成测试用例\n LLM-->>Synth: 返回生成的 goldens\n Synth->>Synth: 应用样式配置\n Synth->>FS: save_as() 保存结果\n FS-->>User: 输出文件\n```\n\n## 使用示例\n\n### 从文档生成单轮测试用例\n\n```python\nfrom deepeval.synthesizer import Synthesizer\nfrom deepeval.synthesizer.config import ContextConstructionConfig\n\nsynthesizer = Synthesizer()\n\nconfig = ContextConstructionConfig(\n chunk_size=1000,\n chunk_overlap=200,\n max_contexts_per_document=5\n)\n\ngoldens = synthesizer.generate_goldens_from_docs(\n document_paths=[\"./docs/guide.md\"],\n context_construction_config=config\n)\n\noutput_path = synthesizer.save_as(\n file_type=\"json\",\n directory=\"./output\",\n file_name=\"my_goldens\"\n)\n```\n\n### 从零生成多轮对话\n\n```python\nfrom deepeval.synthesizer import Synthesizer\nfrom deepeval.cli.generate.utils import GoldenVariation\n\nsynthesizer = Synthesizer(async_mode=True)\n\nscenarios = synthesizer.generate_conversational_goldens_from_scratch(\n num_goldens=50\n)\n\nsynthesizer.save_as(\n file_type=\"json\",\n directory=\"./output\",\n file_name=\"conversational_scenarios\"\n)\n```\n\n### 扩展已有测试用例\n\n```python\nsynthesizer = Synthesizer()\n\nexpanded_goldens = synthesizer.generate_goldens_from_goldens(\n goldens=existing_goldens,\n max_goldens_per_golden=3,\n include_expected_output=True\n)\n```\n\n## 懒加载机制\n\nSynthesizer 和 ContextConstructionConfig 使用 Python 的 `__getattr__` 机制实现懒加载：\n\n```python\ndef __getattr__(name: str) -> Any:\n if name == \"Synthesizer\":\n from deepeval.synthesizer import Synthesizer\n globals()[\"Synthesizer\"] = Synthesizer\n return Synthesizer\n if name == \"ContextConstructionConfig\":\n from deepeval.synthesizer.config import ContextConstructionConfig\n globals()[\"ContextConstructionConfig\"] = ContextConstructionConfig\n return ContextConstructionConfig\n raise AttributeError(f\"module {__name__!r} has no attribute {name!r}\")\n```\n\n这种设计确保了：\n- 未使用生成功能的命令不会加载重型依赖\n- 测试可以方便地通过 monkeypatch 替换模拟对象\n- 模块级别的属性访问保持一致\n\n资料来源：[deepeval/cli/generate/command.py:25-45]()\n\n## 输出格式\n\n### JSON 格式\n\n```json\n{\n \"goldens\": [\n {\n \"input\": \"用户问题\",\n \"expected_output\": \"期望回答\",\n \"context\": [\"上下文片段1\", \"上下文片段2\"]\n }\n ]\n}\n```\n\n### CSV 格式\n\n| input | expected_output | context |\n|-------|-----------------|---------|\n| 用户问题 | 期望回答 | 上下文片段 |\n\n## 最佳实践\n\n1. **文档质量**：使用结构清晰、内容丰富的源文档可提高生成质量\n2. **上下文阈值**：根据文档长度调整 `context_quality_threshold` 和 `context_similarity_threshold`\n3. **并发控制**：在 API 限流较严的环境中，适当降低 `max_concurrent`\n4. **异步模式**：处理大量数据时启用 `async_mode=True` 提高效率\n5. **成本跟踪**：生产环境建议启用 `cost_tracking=True` 监控 API 消耗\n\n---\n\n\n\n## 追踪系统\n\n### 相关页面\n\n相关主题：[评估执行引擎](#page-evaluate-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/tracing/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/__init__.py)\n- [deepeval/tracing/tracing.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/tracing.py)\n- [deepeval/tracing/context.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/context.py)\n- [deepeval/tracing/api.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/api.py)\n- [deepeval/tracing/otel/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/otel/__init__.py)\n- [deepeval/tracing/offline_evals/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/offline_evals/__init__.py)\n \n\n# 追踪系统\n\n## 概述\n\nDeepEval 追踪系统（Tracing System）是用于监控、记录和分析 LLM 应用执行过程的组件化框架。该系统提供了端到端的可观测性能力，使开发者能够追踪 LLM 应用的调用链、执行步骤和性能指标。追踪系统与 DeepEval 的评估指标（如 `TaskCompletionMetric`、`GEval` 等）深度集成，支持在追踪过程中自动执行评估任务。\n\n追踪系统的核心设计理念是将 LLM 应用视为黑盒，通过装饰器（`@observe`）和上下文管理器（`with trace(...)`）自动捕获执行过程中的关键信息，并将这些信息用于后续的评估分析。\n\n## 核心组件\n\n### 1. 追踪上下文管理器\n\n追踪系统使用 `trace()` 上下文管理器来创建追踪范围。当代码在 `with trace(...)` 块内执行时，所有子调用的追踪数据都会被自动收集并关联到同一个追踪会话中。\n\n```python\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n### 2. 观察装饰器\n\n`@observe()` 装饰器用于将普通函数转换为可追踪的组件。当函数被装饰后，其输入输出和执行上下文会自动被记录。\n\n```python\nfrom deepeval.tracing import observe, update_current_span\nfrom deepeval.test_case import LLMTestCase\n\n@observe()\ndef inner_component(input: str):\n output = \"result\"\n update_current_span(test_case=LLMTestCase(input=input, actual_output=output))\n return output\n\n@observe()\ndef app(input: str):\n return inner_component(input)\n```\n\n### 3. 跨度更新函数\n\n`update_current_span()` 和 `update_current_trace()` 函数允许在追踪上下文中手动更新当前跨度或追踪的信息。这对于在特定位置注入测试用例、指标或其他元数据非常有用。\n\n## 架构设计\n\n### 追踪系统架构图\n\n```mermaid\ngraph TD\n subgraph \"应用层\"\n A[LLM 应用代码]\n B[@observe 装饰器]\n C[trace 上下文管理器]\n end\n\n subgraph \"追踪核心\"\n D[TraceManager]\n E[ContextManager]\n F[SpanProcessor]\n end\n\n subgraph \"数据导出层\"\n G[ConfidentSpanExporter]\n H[OTel SpanProcessor]\n I[ContextAwareSpanProcessor]\n end\n\n subgraph \"评估引擎\"\n J[Metrics Engine]\n K[TaskCompletionMetric]\n L[Offline Evals]\n end\n\n A --> B\n A --> C\n B --> D\n C --> D\n D --> E\n D --> F\n F --> G\n F --> I\n I --> H\n D --> J\n J --> K\n J --> L\n```\n\n### 追踪上下文路由\n\n追踪系统支持两种追踪模式：原生追踪模式和 OTel（OpenTelemetry）模式。`ContextAwareSpanProcessor` 是关键的路由组件，它能够根据当前上下文自动决定数据导出路径。\n\n```mermaid\ngraph LR\n A[追踪上下文活跃] --> B{评估状态检查}\n B -->|trace_manager.is_evaluating = True| C[路由至 REST]\n B -->|trace_manager.is_evaluating = False| D[路由至 OTLP]\n C --> E[ConfidentSpanExporter]\n D --> F[OTLP Exporter]\n```\n\n## 框架集成\n\n追踪系统提供了与多种主流 LLM 框架的集成能力。集成通过自动创建追踪上下文和使用回调处理器来实现。\n\n### 集成能力矩阵\n\n| 框架 | Bare 模式追踪 | @observe 支持 | evals_iterator 支持 | deepeval test run |\n|------|--------------|--------------|---------------------|-------------------|\n| OpenAI | ✅ | ✅ | ✅ | ✅ |\n| Anthropic | ✅ | ✅ | ✅ | ✅ |\n| LangChain | ✅ | ✅ | ✅ | ✅ |\n| LangGraph | ✅ | ✅ | ✅ | ✅ |\n| Pydantic AI | ✅ | ✅ | ✅ | ✅ |\n| LlamaIndex | ✅ | ✅ | ✅ | ✅ |\n| Google ADK | ✅ | ✅ | ✅ | ✅ |\n| CrewAI | ✅ | ✅ | ✅ | ✅ |\n| AWS AgentCore | ✅ | ✅ | ✅ | ✅ |\n| Strands | ✅ | ✅ | ✅ | ✅ |\n\n### OpenAI 集成示例\n\n```python\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n # OpenAI 客户端调用会自动被追踪\n response = client.chat.completions.create(\n model=\"gpt-4\",\n messages=[{\"role\": \"user\", \"content\": golden.input}]\n )\n```\n\n### LangChain 集成示例\n\n```python\nfrom deepeval.integrations.langchain import CallbackHandler\nfrom deepeval.metrics import TaskCompletionMetric\n\ncallback_handler = CallbackHandler(metrics=[TaskCompletionMetric()])\n\nfor golden in dataset.evals_iterator():\n llm.invoke(\n golden.input,\n config={\"callbacks\": [callback_handler]},\n )\n```\n\n## 数据流处理\n\n### 离线评估数据流\n\n```mermaid\ngraph TD\n A[追踪数据采集] --> B[Span 数据存储]\n B --> C{评估类型判断}\n C -->|在线评估| D[ConfidentSpanExporter]\n C -->|离线评估| E[Offline Evals 模块]\n D --> F[云端评估引擎]\n E --> G[本地评估执行]\n F --> H[结果聚合]\n G --> H\n```\n\n### OTel 模式下的混合追踪\n\n当 OTel 模式集成在活跃的 `@observe` 或 `with trace(...)` 上下文中运行时，OTel span interceptor 会同步追踪 UUID，确保两种传输方式产生的数据能够合并到同一个追踪会话中。\n\n```mermaid\nsequenceDiagram\n participant App as 应用代码\n participant Observe as @observe 上下文\n participant OTel as OTel SpanInterceptor\n participant Router as ContextAwareSpanProcessor\n participant REST as ConfidentSpanExporter\n\n App->>Observe: 开始追踪\n Observe->>OTel: 同步 trace_id\n App->>OTel: 创建 OTel span\n OTel->>Router: 处理 span\n Router->>REST: 路由至 REST\n REST->>Observe: 合并到同一追踪\n```\n\n## 评估迭代器集成\n\n`dataset.evals_iterator()` 是追踪系统与评估流程结合的核心接口。它支持在迭代过程中自动应用追踪和指标计算。\n\n### 基础用法\n\n```python\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):\n app(golden.input)\n```\n\n### 异步配置\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator(\n async_config=AsyncConfig(run_async=True),\n metrics=[TaskCompletionMetric()],\n):\n task = asyncio.create_task(run_agent(golden.input))\n dataset.evaluate(task)\n```\n\n## 配置与初始化\n\n### 追踪初始化\n\n```python\nimport deepeval\n\ndeepeval.instrument(\n name=\"my-app\",\n environment=\"development\"\n)\n```\n\n### 集成初始化\n\n每个框架集成都提供了 `instrument_*` 函数来简化初始化过程。例如：\n\n```python\nfrom deepeval.integrations.google_adk import instrument_google_adk\n\ninstrument_google_adk()\n```\n\n## 关键文件说明\n\n| 文件路径 | 功能描述 |\n|---------|---------|\n| `deepeval/tracing/__init__.py` | 追踪系统公共 API 导出，包含 `trace`、`@observe`、`update_current_span` 等核心接口 |\n| `deepeval/tracing/tracing.py` | 追踪系统核心实现，包含 TraceManager 类和追踪上下文管理逻辑 |\n| `deepeval/tracing/context.py` | 追踪上下文实现，管理当前活跃的追踪和跨度状态 |\n| `deepeval/tracing/api.py` | 追踪系统 REST API 接口定义，用于与云端服务通信 |\n| `deepeval/tracing/otel/__init__.py` | OpenTelemetry 集成模块，实现 OTel span 拦截和转发 |\n| `deepeval/tracing/offline_evals/__init__.py` | 离线评估模块，支持在没有网络连接时执行本地评估 |\n\n## 与 Confident AI 平台的集成\n\n追踪系统与 Confident AI 平台深度集成，提供以下能力：\n\n1. **云端追踪同步**：追踪数据自动同步至 Confident AI 平台\n2. **评估报告生成**：在平台上生成可分享的测试报告\n3. **追踪可视化**：在 Web 界面中查看完整的调用链路\n4. **生产环境监控**：支持生产环境的实时追踪和评估\n\n通过 `deepeval login` 命令登录后，所有追踪数据会自动同步到平台：\n\n```bash\ndeepeval login\ndeepeval test run test_chatbot.py\n```\n\n## 最佳实践\n\n1. **使用 @observe 装饰器包装关键组件**：确保所有 LLM 调用和关键业务逻辑都在可追踪的范围内\n2. **结合评估指标使用追踪**：在 `trace()` 或 `evals_iterator()` 中指定指标以获得完整的评估数据\n3. **利用上下文更新函数**：在需要注入额外信息时使用 `update_current_span()` 和 `update_current_trace()`\n4. **选择合适的集成方式**：根据框架选择原生集成或 OTel 模式集成\n\n## 相关文档\n\n- [评估指标文档](https://deepeval.com/docs/metrics-llm-evals)\n- [组件级评估指南](https://deepeval.com/docs/evaluation-component-level-llm-evals)\n- [Confident AI 平台文档](https://www.confident-ai.com/docs)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：confident-ai/deepeval\n\n摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)。\n\n## 1. 安全/权限坑 · 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bc32a715810442d93069925f14aab92 | https://github.com/confident-ai/deepeval/issues/2673 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：'NoneType' object has no attribute 'find'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：'NoneType' object has no attribute 'find'\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_756ddcdc1eda4fd7b87ade56a4a3c10f | https://github.com/confident-ai/deepeval/issues/2554 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 配置坑 · 来源证据：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9a7d5b92cc5948d48aec4ed1e96e7288 | https://github.com/confident-ai/deepeval/releases/tag/v4.0.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:676829188 | https://github.com/confident-ai/deepeval | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：LLM Evals - v3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LLM Evals - v3.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f9371d513c443ab860bbb718a785a2c | https://github.com/confident-ai/deepeval/releases/tag/v3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | release_recency=unknown\n\n\n",
"markdown_key": "deepeval",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:676829188",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/confident-ai/deepeval"
},
{
"evidence_id": "art_0e5a3d75ddc44203b6b2bc4bd60f302b",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/confident-ai/deepeval#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "deepeval 说明书",
"toc": [
"https://github.com/confident-ai/deepeval 项目说明书",
"目录",
"项目介绍",
"概述",
"核心定位",
"技术架构",
"核心功能",
"框架集成",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "f2acacf1c09b40e56a4e635613ecf12a5743119d",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"docs/vercel.json",
"docs/source.config.ts",
"docs/package.json",
"docs/proxy.ts",
"docs/README.md",
"docs/tsconfig.json",
"docs/src/assets.ts",
"docs/src/global.d.ts",
"docs/enterprise/read-me.mdx",
"docs/lib/defaults.ts",
"docs/lib/shared.ts",
"docs/lib/llms-route.ts",
"docs/lib/contributors.ts",
"docs/lib/blog-categories.ts",
"docs/lib/cn.ts",
"docs/lib/authors.ts",
"docs/lib/remark-admonitions.ts",
"docs/lib/source.ts",
"docs/home/read-me.mdx",
"docs/app/sitemap.ts",
"docs/app/robots.ts",
"docs/src/components/index.ts",
"docs/src/utils/schema-helpers.ts",
"docs/src/utils/html-to-markdown.ts",
"docs/src/utils/visitor-attribution.ts",
"docs/src/utils/outbound-link-rel.ts",
"docs/src/utils/utm.ts",
"docs/src/components/GithubCtaButton/useGithubStarCount.ts",
"docs/src/layouts/UtmCapture/index.ts",
"docs/src/layouts/HomeLayout/index.ts",
"docs/src/sections/home/CompanyLogos/index.ts",
"docs/src/sections/home/CompanyLogos/types.ts",
"docs/content/docs/meta.json",
"docs/content/docs/troubleshooting.mdx",
"docs/content/docs/data-privacy.mdx",
"docs/content/docs/evaluation-flags-and-configs.mdx",
"docs/content/docs/command-line-interface.mdx",
"docs/content/docs/environment-variables.mdx"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# new_docs - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 new_docs 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`skills/deepeval/SKILL.md` Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/deepeval/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.cursor-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `pip install -U deepeval` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做研究框架试用\n- **为什么**：这个项目面向研究工作流，核心风险是资料可信度和输出质量；先用 Prompt Preview 验证研究框架，再在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做研究框架试用\n- **最小安全下一步**：先用 Prompt Preview 验证研究框架；满意后再隔离试装\n- **先别相信**：研究结论、引用和实验结果不能在安装前相信。\n- **继续会触碰**：研究判断、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`skills/deepeval/SKILL.md` Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/deepeval/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.cursor-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **研究结论、引用和实验结果不能在安装前相信。**（unverified）：研究 Skill 可以组织问题和路径，但不能替代真实资料检索、论文核验和实验复现。\n- **是否适合你的具体研究领域不能直接相信。**（unverified）：Skill 覆盖很多研究主题，不代表对你的领域、资料要求和可信度标准足够。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.cursor-plugin/plugin.json`, `skills/deepeval/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.cursor-plugin/plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **研究判断**：问题拆解、资料路径、实验路径、结论结构和可信度判断。 原因：研究型 Skill 可能让输出看起来更专业，但不能替代真实证据核验。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.cursor-plugin/plugin.json`, `skills/deepeval/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.cursor-plugin/plugin.json`, `README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先验证它能否正确界定研究问题和证据边界，不要先相信研究输出。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留资料和结论核验清单**：如果后续发现引用或实验路径不可靠，可以回到证据边界阶段重新校验。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.cursor-plugin/plugin.json` Claim：`clm_0008` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/deepeval/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.cursor-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1763\n- 重要文件覆盖：40/1763\n- 证据索引条目：78\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 new_docs 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 new_docs 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 new_docs 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **deepeval**（skill）： 激活提示：当用户任务与“deepeval”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/deepeval/SKILL.md`\n\n## 证据索引\n\n- 共索引 78 条证据。\n\n- **.**（documentation）：This is a Next.js application generated with Create Fumadocs https://github.com/fuma-nama/fumadocs . 证据：`docs/README.md`\n- **🔥 Metrics and Features**（documentation）：Documentation Metrics and Features Getting Started Integrations Confident AI 证据：`README.md`\n- **DeepEval Skills**（documentation）：Agent Skills that teach coding assistants how to add DeepEval evaluations, generate datasets, instrument applications with tracing, and iterate on AI applications using eval results. 证据：`skills/README.md`\n- **deepeval.integrations**（documentation）：Contributor reference for the framework integrations. Each integration plugs deepeval's tracing / evaluation into a third-party framework using one of four mechanisms. 证据：`deepeval/integrations/README.md`\n- **DeepEval × Pydantic AI integration**（documentation）：End-to-end reference for running Pydantic AI https://ai.pydantic.dev/ agents with DeepEval / Confident AI tracing. Covers the public API, every supported usage mode, all edge cases we know about, and the exact rules for how trace and span attributes are resolved. 证据：`deepeval/integrations/pydantic_ai/README.md`\n- **The Red Teaming module is now in DeepTeam for deepeval-v3.0 onwards**（documentation）：The Red Teaming module is now in DeepTeam for deepeval-v3.0 onwards 证据：`deepeval/red_teaming/README.md`\n- **Package**（package_manifest）：{ \"name\": \"new docs\", \"version\": \"0.0.0\", \"private\": true, \"scripts\": { \"build\": \"NODE OPTIONS=--max-old-space-size=16384 next build\", \"dev\": \"NODE OPTIONS=--max-old-space-size=16384 next dev\", \"start\": \"next start\", \"types:check\": \"fumadocs-mdx && next typegen && tsc --noEmit\", \"contributors\": \"node scripts/generate-contributors.mjs\", \"changelog-contributors\": \"node scripts/generate-changelog-contributors.mjs\", \"repo-contributors\": \"node scripts/generate-repo-contributors.mjs\", \"prebuild\": \"npm run repo-contributors && npm run contributors && npm run changelog-contributors\", \"postinstall\": \"fumadocs-mdx\" }, \"dependencies\": { \"@radix-ui/react-popover\": \"1.1.15\", \"fumadocs-core\": \"16.8.1\", \"… 证据：`docs/package.json`\n- **Contributing to DeepEval 🥳**（documentation）：Thanks for thinking about contributing to DeepEval! We accept fixes, improvements, or even entire new features. Some reasons why you might want to contribute: 证据：`CONTRIBUTING.md`\n- **DeepEval**（skill_instruction）：Use this skill to add an end-to-end eval loop to AI applications: instrument the app, curate or reuse a dataset, create a committed pytest eval suite, run evals, and iterate on failures. 证据：`skills/deepeval/SKILL.md`\n- **Plugin**（structured_config）：{ \"name\": \"deepeval\", \"displayName\": \"DeepEval\", \"version\": \"1.0.0\", \"description\": \"Skills for adding DeepEval evaluations, tracing, datasets, Confident AI reports, and iterative improvement loops to AI applications.\", \"author\": { \"name\": \"Confident AI\", \"email\": \"founders@confident-ai.com\" }, \"homepage\": \"https://deepeval.com\", \"repository\": \"https://github.com/confident-ai/deepeval\", \"license\": \"Apache-2.0\", \"keywords\": \"deepeval\", \"llm\", \"evaluation\", \"tracing\", \"datasets\", \"confident-ai\" , \"category\": \"developer-tools\", \"skills\": \"./skills/\" } 证据：`.cursor-plugin/plugin.json`\n- **Google ADK trace schemas**（documentation）：Captured trace JSON snapshots used by test sync.py and test async.py . Each schema.json here is the structural fixture for one test method — assert trace json compares the live trace produced by Gemini + the OpenInference instrumentor against this file with the relaxed structural matcher in tests/test integrations/utils.py . 证据：`tests/test_integrations/test_googleadk/schemas/README.md`\n- **Strands trace schemas**（documentation）：Captured trace JSON snapshots used by test sync.py and test async.py . Each schema.json here is the structural fixture for one test method — assert trace json compares the live trace produced by Strands + the deepeval StrandsSpanInterceptor against this file with the relaxed structural matcher in tests/test integrations/utils.py . 证据：`tests/test_integrations/test_strands/schemas/README.md`\n- **License**（source_file）：This skill is distributed under the same license as DeepEval. See the repository root LICENSE.md for the full Apache License, Version 2.0 text. 证据：`skills/deepeval/LICENSE`\n- **License**（documentation）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE.md`\n- **Maintainers**（documentation）：For issues in this repo you can mention one or more of: 证据：`MAINTAINERS.md`\n- **Bug Report**（documentation）：❗BEFORE YOU BEGIN❗ Are you on discord? 🤗 We'd love to have you asking questions on discord instead: https://discord.com/invite/a3K9c8GRGt 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature Request**（documentation）：❗BEFORE YOU BEGIN❗ Are you on discord? 🤗 We'd love to have you asking questions on discord instead: https://discord.com/invite/a3K9c8GRGt 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Artifact Contracts**（documentation）：Create eval artifacts that users can inspect, edit, commit, and rerun without an agent. 证据：`skills/deepeval/references/artifact-contracts.md`\n- **Choose Use Case**（documentation）：Classify the target app before choosing templates, datasets, or metrics. Infer from code first; ask only when the code is ambiguous. 证据：`skills/deepeval/references/choose-use-case.md`\n- **Confident AI**（documentation）：Ask whether the user wants eval results on Confident AI. Describe it as free of charge and useful for hosted reports, traces, run history, dashboards, production monitoring, and online evals. 证据：`skills/deepeval/references/confident-ai.md`\n- **Datasets**（documentation）：Use documented EvaluationDataset APIs directly. Do not invent wrapper helpers for dataset loading in templates. 证据：`skills/deepeval/references/datasets.md`\n- **Intake**（documentation）：Ask these questions before editing application code. Keep them concise and use the defaults when the user wants you to decide. 证据：`skills/deepeval/references/intake.md`\n- **Integrations**（documentation）：Prefer a supported DeepEval integration over manual @observe instrumentation. Manual tracing is only the fallback for app code or framework boundaries that do not have a native integration. 证据：`skills/deepeval/references/integrations.md`\n- **Iteration Loop**（documentation）：Run the number of rounds requested by the user. If they do not choose, recommend and use 5 rounds. 证据：`skills/deepeval/references/iteration-loop.md`\n- **Metrics**（documentation）：Use 3-5 metrics for the first eval suite when the user is unsure. More metrics make iteration slower and harder to interpret. Reuse existing project metrics and thresholds before adding new ones. 证据：`skills/deepeval/references/metrics.md`\n- **Pytest End-to-End Evals**（documentation）：Use this for the default CI/CD path. End-to-end pytest evals run one golden through the real app per test. If tracing or a supported integration is available, pass the golden directly to DeepEval with assert test golden=golden, metrics=... . 证据：`skills/deepeval/references/pytest-e2e-evals.md`\n- **Synthetic Data**（documentation）：Use deepeval generate when the user does not already have a dataset or wants to augment existing goldens. Do not hand-create or make up goldens. Generated files should be visible, editable, and committed with the eval suite when appropriate. 证据：`skills/deepeval/references/synthetic-data.md`\n- **Tracing**（documentation）：Tracing is the default single-turn eval path when the app can produce traces through a DeepEval integration or manual instrumentation. 证据：`skills/deepeval/references/tracing.md`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ESNext\", \"lib\": \"dom\", \"dom.iterable\", \"esnext\" , \"allowJs\": true, \"skipLibCheck\": true, \"strict\": true, \"forceConsistentCasingInFileNames\": true, \"noEmit\": true, \"esModuleInterop\": true, \"module\": \"esnext\", \"moduleResolution\": \"bundler\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"jsx\": \"react-jsx\", \"incremental\": true, \"paths\": { \"@/ \": \"./ \" , \"@site/ \": \"./ \" , \"collections/ \": \"./.source/ \" }, \"plugins\": { \"name\": \"next\" } }, \"include\": \"next-env.d.ts\", \" / .ts\", \" / .tsx\", \".next/types/ / .ts\", \".next/dev/types/ / .ts\" , \"exclude\": \"node modules\" } 证据：`docs/tsconfig.json`\n- **Vercel**（structured_config）：{ \"framework\": \"nextjs\", \"redirects\": { \"source\": \"/docs/synthesizer-introduction\", \"destination\": \"/docs/golden-synthesizer\", \"statusCode\": 301 }, { \"source\": \"/synthesizer-introduction\", \"destination\": \"/golden-synthesizer\", \"statusCode\": 301 }, { \"source\": \"/guides/guides-multi-turn-tracing\", \"destination\": \"/guides/guides-tracing-multi-turn\", \"statusCode\": 301 }, { \"source\": \"/docs/guides-rag-evaluation\", \"destination\": \"/guides/guides-rag-evaluation\", \"statusCode\": 301 }, { \"source\": \"/docs/red-teaming-introduction\", \"destination\": \"https://www.trydeepteam.com/docs/red-teaming-introduction\", \"statusCode\": 301 }, { \"source\": \"/docs/red-teaming-owasp\", \"destination\": \"https://www.trydeep… 证据：`docs/vercel.json`\n- **Meta**（structured_config）：{ \"title\": \"Blog\", \"pages\": \"index\", 证据：`docs/content/blog/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Changelog\", \"pages\": \"---Changelog---\", \"index\", \"changelog-2026\", \"changelog-2025\", \"changelog-2024\" } 证据：`docs/content/changelog/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Agentic\", \"pages\": \"metrics-task-completion\", \"metrics-step-efficiency\", \"metrics-argument-correctness\", \"metrics-tool-correctness\", \"metrics-plan-adherence\", \"metrics-plan-quality\" } 证据：`docs/content/docs/(agentic)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Algorithms\", \"pages\": \"prompt-optimization-gepa\", \"prompt-optimization-miprov2\", \"prompt-optimization-simba\", \"prompt-optimization-copro\" } 证据：`docs/content/docs/(algorithms)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Available Benchmarks\", \"pages\": \"benchmarks-mmlu\", \"benchmarks-hellaswag\", \"benchmarks-big-bench-hard\", \"benchmarks-drop\", \"benchmarks-truthful-qa\", \"benchmarks-human-eval\", \"benchmarks-ifeval\", \"benchmarks-squad\", \"benchmarks-gsm8k\", \"benchmarks-math-qa\", \"benchmarks-logi-qa\", \"benchmarks-bool-q\", \"benchmarks-arc\", \"benchmarks-bbq\", \"benchmarks-lambada\", \"benchmarks-winogrande\" } 证据：`docs/content/docs/(benchmarks)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Test Cases\", \"pages\": \"evaluation-test-cases\", \"evaluation-multiturn-test-cases\", \"evaluation-arena-test-cases\" } 证据：`docs/content/docs/(concepts)/(test-cases)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Concepts\", \"pages\": \" test-cases \", \"evaluation-datasets\", \"evaluation-llm-tracing\", \"evaluation-prompts\", \"evaluation-mcp\" } 证据：`docs/content/docs/(concepts)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Custom\", \"pages\": \"metrics-llm-evals\", \"metrics-dag\", \"metrics-conversational-g-eval\", \"metrics-conversational-dag\", \"metrics-arena-g-eval\", \"metrics-custom\" } 证据：`docs/content/docs/(custom)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Golden Synthesizer\", \"pages\": \"synthesizer-generate-from-docs\", \"synthesizer-generate-from-contexts\", \"synthesizer-generate-from-goldens\", \"synthesizer-generate-from-scratch\" } 证据：`docs/content/docs/(generate-goldens)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Images\", \"pages\": \"multimodal-metrics-image-coherence\", \"multimodal-metrics-image-helpfulness\", \"multimodal-metrics-image-reference\", \"multimodal-metrics-text-to-image\", \"multimodal-metrics-image-editing\" } 证据：`docs/content/docs/(images)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"MCP\", \"pages\": \"metrics-mcp-use\", \"metrics-multi-turn-mcp-use\", \"metrics-mcp-task-completion\" } 证据：`docs/content/docs/(mcp)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Others\", \"pages\": \"metrics-summarization\", \"metrics-prompt-alignment\", \"metrics-hallucination\", \"metrics-ragas\" } 证据：`docs/content/docs/(metrics-others)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Multi-Turn\", \"pages\": \"metrics-turn-relevancy\", \"metrics-role-adherence\", \"metrics-knowledge-retention\", \"metrics-conversation-completeness\", \"metrics-goal-accuracy\", \"metrics-tool-use\", \"metrics-topic-adherence\", \"metrics-turn-faithfulness\", \"metrics-turn-contextual-precision\", \"metrics-turn-contextual-recall\", \"metrics-turn-contextual-relevancy\" } 证据：`docs/content/docs/(multi-turn)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Non-LLM\", \"pages\": \"metrics-exact-match\", \"metrics-pattern-match\", \"metrics-json-correctness\" } 证据：`docs/content/docs/(non-llm)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"RAG\", \"pages\": \"metrics-answer-relevancy\", \"metrics-faithfulness\", \"metrics-contextual-precision\", \"metrics-contextual-recall\", \"metrics-contextual-relevancy\" } 证据：`docs/content/docs/(rag)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Safety\", \"pages\": \"metrics-bias\", \"metrics-toxicity\", \"metrics-non-advice\", \"metrics-misuse\", \"metrics-pii-leakage\", \"metrics-role-violation\" } 证据：`docs/content/docs/(safety)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Use Cases\", \"pages\": \"getting-started-agents\", \"getting-started-chatbots\", \"getting-started-rag\", \"getting-started-mcp\", \"getting-started-llm-arena\" } 证据：`docs/content/docs/(use-cases)/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Conversation Simulator\", \"pages\": \"../conversation-simulator-model-callback\", \"../conversation-simulator-stopping-logic\", \"../conversation-simulator-custom-templates\", \"../conversation-simulator-lifecycle-hooks\" } 证据：`docs/content/docs/conversation-simulator/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"End-to-End Evals\", \"pages\": \"../evaluation-end-to-end-single-turn\", \"../evaluation-end-to-end-multi-turn\" } 证据：`docs/content/docs/evaluation-end-to-end-llm-evals/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Golden Synthesizer\", \"pages\": \"../ generate-goldens /synthesizer-generate-from-docs\", \"../ generate-goldens /synthesizer-generate-from-contexts\", \"../ generate-goldens /synthesizer-generate-from-goldens\", \"../ generate-goldens /synthesizer-generate-from-scratch\" } 证据：`docs/content/docs/golden-synthesizer/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Docs\", \"pages\": \"introduction\", \"introduction-design-philosophy\", \"introduction-comparisons\", 证据：`docs/content/docs/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Guides\", \"pages\": \"--- Bot AI Agents---\", \"guides-ai-agent-evaluation\", \"guides-ai-agent-evaluation-metrics\", 证据：`docs/content/guides/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Orchestration Frameworks\", \"pages\": \"openai\", \"anthropic\", \"agentcore\", \"strands\", \"google-adk\", \"langchain\", \"langgraph\", \"llamaindex\", \"crewai\", \"pydanticai\", \"openai-agents\" } 证据：`docs/content/integrations/frameworks/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Integrations\", \"pages\": \"index\", \"frameworks\", \"models\", \"vector-databases\", \"others\" } 证据：`docs/content/integrations/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Evaluation Models\", \"pages\": \"openai\", \"azure-openai\", \"ollama\", \"openrouter\", \"anthropic\", \"amazon-bedrock\", \"gemini\", \"deepseek\", \"vertex-ai\", \"grok\", \"moonshot\", \"portkey\", \"vllm\", \"lmstudio\", \"litellm\" } 证据：`docs/content/integrations/models/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Others\", \"pages\": \"../frameworks/huggingface\" } 证据：`docs/content/integrations/others/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Vector Databases\", \"pages\": \"cognee\", \"elasticsearch\", \"chroma\", \"weaviate\", \"qdrant\", \"pgvector\" } 证据：`docs/content/integrations/vector-databases/meta.json`\n- **Meta**（structured_config）：{ \"title\": \"Tutorials\", \"pages\": \"---Getting Started---\", \"tutorial-introduction\", \"tutorial-setup\", 证据：`docs/content/tutorials/meta.json`\n- **Changelog Contributors**（structured_config）：{ \"2024\": { \"login\": \"penguine-ip\", \"name\": \"Jeffrey Ip\", \"url\": \"https://github.com/penguine-ip\", \"avatarUrl\": \"https://github.com/penguine-ip.png?size=64\", \"contributions\": 394 }, { \"login\": \"kritinv\", \"name\": \"Kritin Vongthongsri\", \"url\": \"https://github.com/kritinv\", \"avatarUrl\": \"https://github.com/kritinv.png?size=64\", \"contributions\": 100 }, { \"login\": \"Peilun-Li\", \"name\": \"lplcor\", \"url\": \"https://github.com/Peilun-Li\", \"avatarUrl\": \"https://github.com/Peilun-Li.png?size=64\", \"contributions\": 4 }, { \"login\": \"aandyw\", \"name\": \"Andy\", \"url\": \"https://github.com/aandyw\", \"avatarUrl\": \"https://github.com/aandyw.png?size=64\", \"contributions\": 2 }, { \"login\": \"AndresPrez\", \"name\": \"André… 证据：`docs/lib/generated/changelog-contributors.json`\n- **Contributors**（structured_config）：{ \"content/docs/ agentic /metrics-argument-correctness.mdx\": { \"login\": \"penguine-ip\", \"name\": \"Jeffrey Ip\", \"avatarUrl\": \"https://avatars.githubusercontent.com/u/143328635?v=4\", \"url\": \"https://github.com/penguine-ip\", \"commits\": 4 }, { \"login\": \"A-Vamshi\", \"name\": \"A-Vamshi\", \"avatarUrl\": \"https://avatars.githubusercontent.com/u/123094948?v=4\", \"url\": \"https://github.com/A-Vamshi\", \"commits\": 2 }, { \"login\": \"kritinv\", \"name\": \"Kritin Vongthongsri\", \"avatarUrl\": \"https://avatars.githubusercontent.com/u/73642562?v=4\", \"url\": \"https://github.com/kritinv\", \"commits\": 2 } , \"content/docs/ agentic /metrics-plan-adherence.mdx\": { \"login\": \"A-Vamshi\", \"name\": \"A-Vamshi\", \"avatarUrl\": \"https://av… 证据：`docs/lib/generated/contributors.json`\n- 其余 18 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `README.md`, `skills/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `README.md`, `skills/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, deepeval/__init__.py, deepeval/_version.py\n- **快速开始**：importance `high`\n - source_paths: deepeval/test_case/__init__.py, deepeval/test_case/llm_test_case.py, deepeval/evaluate/__init__.py, deepeval/evaluate/evaluate.py\n- **系统架构**：importance `high`\n - source_paths: deepeval/evaluate/evaluate.py, deepeval/evaluate/execute/__init__.py, deepeval/evaluate/execute/e2e.py, deepeval/evaluate/execute/agentic.py, deepeval/constants.py\n- **核心模块结构**：importance `medium`\n - source_paths: deepeval/metrics/base_metric.py, deepeval/metrics/indicator.py, deepeval/test_case/utils.py, deepeval/config/settings.py\n- **测试用例定义**：importance `high`\n - source_paths: deepeval/test_case/__init__.py, deepeval/test_case/llm_test_case.py, deepeval/test_case/conversational_test_case.py, deepeval/test_case/arena_test_case.py, deepeval/test_case/mcp.py\n- **评估指标体系**：importance `high`\n - source_paths: deepeval/metrics/__init__.py, deepeval/metrics/base_metric.py, deepeval/metrics/g_eval/g_eval.py, deepeval/metrics/rag/answer_relevancy/answer_relevancy.py, deepeval/metrics/rag/faithfulness/faithfulness.py\n- **评估执行引擎**：importance `high`\n - source_paths: deepeval/evaluate/__init__.py, deepeval/evaluate/evaluate.py, deepeval/evaluate/api.py, deepeval/evaluate/execute/e2e.py, deepeval/evaluate/execute/agentic.py\n- **数据集管理**：importance `medium`\n - source_paths: deepeval/dataset/__init__.py, deepeval/dataset/dataset.py, deepeval/dataset/golden.py, deepeval/dataset/api.py, deepeval/dataset/test_run_tracer.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `f2acacf1c09b40e56a4e635613ecf12a5743119d`\n- inspected_files: `pyproject.toml`, `README.md`, `docs/vercel.json`, `docs/source.config.ts`, `docs/package.json`, `docs/proxy.ts`, `docs/README.md`, `docs/tsconfig.json`, `docs/src/assets.ts`, `docs/src/global.d.ts`, `docs/enterprise/read-me.mdx`, `docs/lib/defaults.ts`, `docs/lib/shared.ts`, `docs/lib/llms-route.ts`, `docs/lib/contributors.ts`, `docs/lib/blog-categories.ts`, `docs/lib/cn.ts`, `docs/lib/authors.ts`, `docs/lib/remark-admonitions.ts`, `docs/lib/source.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_4bc32a715810442d93069925f14aab92 | https://github.com/confident-ai/deepeval/issues/2673 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：'NoneType' object has no attribute 'find'\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：'NoneType' object has no attribute 'find'\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_756ddcdc1eda4fd7b87ade56a4a3c10f | https://github.com/confident-ai/deepeval/issues/2554 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9a7d5b92cc5948d48aec4ed1e96e7288 | https://github.com/confident-ai/deepeval/releases/tag/v4.0.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:676829188 | https://github.com/confident-ai/deepeval | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：LLM Evals - v3.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LLM Evals - v3.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9f9371d513c443ab860bbb718a785a2c | https://github.com/confident-ai/deepeval/releases/tag/v3.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：confident-ai/deepeval\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：'NoneType' object has no attribute 'find'（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/confident-ai/deepeval 项目说明书\n\n生成时间：2026-05-16 19:07:22 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [核心模块结构](#page-core-modules)\n- [测试用例定义](#page-test-cases)\n- [评估指标体系](#page-metrics)\n- [评估执行引擎](#page-evaluate-engine)\n- [数据集管理](#page-dataset-management)\n- [合成数据生成](#page-synthetic-data)\n- [追踪系统](#page-tracing-system)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n- [skills/README.md](https://github.com/confident-ai/deepeval/blob/main/skills/README.md)\n- [deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n- [deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)\n- [deepeval/cli/main.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/main.py)\n- [deepeval/cli/inspect.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/inspect.py)\n \n\n# 项目介绍\n\n## 概述\n\nDeepEval 是一个简单易用、开源的 **LLM（大语言模型）评估框架**，专门用于评估大型语言模型系统。它类似于 Pytest，但专门为 LLM 应用的单元测试而设计。DeepEval 整合了最新研究成果，通过 G-Eval、任务完成度、答案相关性、幻觉检测等指标来运行评估，这些指标使用 **LLM-as-a-Judge**（LLM 作为评判者）和其他 NLP 模型，**完全运行在本地机器上**。\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 核心定位\n\n无论你是构建 AI 代理（AI Agents）、RAG（检索增强生成）管道还是聊天机器人，无论是使用 LangChain 还是 OpenAI 实现，DeepEval 都能为你提供支持。通过它，你可以轻松确定最优的模型、提示词和架构，从而：\n\n- 提升 AI 质量\n- 防止提示词漂移\n- 自信地从 OpenAI 迁移到 Claude\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 技术架构\n\n### 系统架构图\n\n```mermaid\ngraph TB\n subgraph 用户层\n A[测试用例编写] --> B[Pytest 集成 / API 调用]\n end\n \n subgraph 核心评估引擎\n C[Metrics 指标] --> D[GEval]\n C --> E[Answer Relevancy]\n C --> F[Task Completion]\n C --> G[Hallucination]\n end\n \n subgraph 集成层\n H[LangChain] --> I[CallbackHandler]\n J[OpenAI] --> K[OpenAI Integration]\n L[Anthropic] --> M[Anthropic Integration]\n N[LlamaIndex] --> O[AsyncConfig]\n P[LangGraph] --> I\n end\n \n subgraph 输出层\n Q[本地评估结果] --> R[Confident AI 云端]\n end\n \n B --> D\n B --> E\n B --> F\n B --> G\n I --> C\n K --> C\n M --> C\n O --> C\n```\n\n### 评估模式\n\nDeepEval 支持两种主要的评估模式：\n\n| 模式 | 描述 | 适用场景 |\n|------|------|----------|\n| **端到端评估（End-to-End）** | 将 LLM 应用视为黑盒，输入输出直接评估 | 快速验证整体输出质量 |\n| **可追溯评估（With Traceability）** | 使用 `evals_iterator()` 追踪组件级调用 | 细粒度分析、定位问题组件 |\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 核心功能\n\n### 评估指标体系\n\nDeepEval 提供了多种预置评估指标，所有指标得分范围均为 **0-1**：\n\n| 指标名称 | 说明 | 评估参数 |\n|----------|------|----------|\n| **GEval** | 基于 G-Eval 算法的通用评估指标，支持自定义评估标准 | SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT |\n| **AnswerRelevancyMetric** | 评估答案与输入的相关性 | retrieval_context |\n| **TaskCompletionMetric** | 评估任务完成度 | 端到端追踪 |\n| **幻觉检测指标** | 检测输出中的幻觉内容 | retrieval_context |\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### 黄金测试用例生成\n\nDeepEval 支持通过 CLI 自动生成合成黄金测试用例，支持多种生成方法：\n\n```bash\ndeepeval generate golden --method [METHOD] --variation [VARIATION]\n```\n\n| 生成方法 | 说明 | 必需参数 |\n|----------|------|----------|\n| `DOCS` | 从文档生成 | `--documents` |\n| `CONTEXTS` | 从上下文生成 | `--contexts-file` |\n| `SCRATCH` | 从零开始生成 | `--num-goldens` |\n| `GOLDENS` | 从现有黄金用例扩展 | `--goldens-file` |\n\n资料来源：[deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n\n### 测试用例结构\n\n```python\nfrom deepeval.test_case import LLMTestCase\n\ntest_case = LLMTestCase(\n input=\"用户输入\",\n actual_output=\"实际输出\",\n expected_output=\"期望输出\", # 可选\n retrieval_context=[\"检索上下文\"] # 可选\n)\n```\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 框架集成\n\nDeepEval 支持与多种主流 AI 框架深度集成：\n\n### 集成矩阵\n\n| 框架 | 集成方式 | 追踪能力 | 本地评估 | 云端同步 |\n|------|----------|----------|----------|----------|\n| **OpenAI** | `@observe` / `trace()` | ✅ | ✅ | ✅ |\n| **Anthropic** | `@observe` / `trace()` | ✅ | ✅ | ✅ |\n| **LangChain** | `CallbackHandler` | ✅ | ✅ | ✅ |\n| **LangGraph** | `CallbackHandler` | ✅ | ✅ | ✅ |\n| **LlamaIndex** | `AsyncConfig` | ✅ | ✅ | ✅ |\n| **Pydantic AI** | `instrument_pydantic_ai()` | ✅ | ✅ | ✅ |\n| **CrewAI** | `instrument_crewai()` | ✅ | ✅ | ✅ |\n| **Google ADK** | `instrument_google_adk()` | ✅ | ✅ | ✅ |\n| **Strands** | `instrument_strands()` | ✅ | ✅ | ✅ |\n| **AWS AgentCore** | `instrument_agentcore()` | ✅ | ✅ | ✅ |\n\n资料来源：[deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)\n\n### 集成架构\n\n```mermaid\ngraph LR\n A[用户代码] --> B[框架集成层]\n B --> C[OTel 追踪]\n B --> D[DeepEval 追踪]\n \n C --> E[ContextAwareSpanProcessor]\n D --> E\n \n E --> F{评估状态判断}\n F -->|评估中| G[REST 路由]\n F -->|非评估| H[OTLP 导出]\n \n G --> I[ConfidentSpanExporter]\n H --> J[远程 OTel 端点]\n```\n\n## 命令行接口\n\n### 可用命令\n\n| 命令 | 说明 | 关键选项 |\n|------|------|----------|\n| `deepeval login` | 登录 Confident AI 平台 | - |\n| `deepeval test run` | 运行测试套件 | `--folder`, pytest 集成 |\n| `deepeval generate golden` | 生成黄金测试用例 | `--method`, `--variation` |\n| `deepeval inspect` | 检查测试运行结果 | `--path`, `--folder` |\n| `deepeval set-gemini` | 设置 Gemini 模型 | `--model` |\n| `deepeval unset-gemini` | 取消 Gemini 配置 | `-x`, `--clear-secrets` |\n\n资料来源：[deepeval/cli/main.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/main.py)\n\n### 本地开发环境配置\n\n```bash\n# 复制环境变量模板\ncp .env.example .env.local\n# 编辑 .env.local（会被 git 忽略）\n```\n\n## 使用流程\n\n### 基本使用流程\n\n```mermaid\ngraph TD\n A[安装 DeepEval] --> B[配置 API Key]\n B --> C[编写测试用例]\n C --> D[选择评估指标]\n D --> E[定义阈值]\n E --> F[运行评估]\n F --> G{是否达标}\n G -->|是| H[测试通过]\n G -->|否| I[调整模型/提示词]\n I --> F\n```\n\n### Pytest 集成示例\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\n@assert_test\ndef test_case():\n correctness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n test_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\"\n )\n```\n\n运行测试：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### 非 Pytest 评估\n\n```python\nfrom deepeval import evaluate\nfrom deepeval.metrics import AnswerRelevancyMetric\nfrom deepeval.test_case import LLMTestCase\n\nanswer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\nevaluate([test_case], [answer_relevancy_metric])\n```\n\n## 云端集成\n\n### Confident AI 平台\n\nDeepEval 与 Confident AI 平台深度集成，提供以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| **测试报告** | 生成可分享的测试报告 |\n| **数据集管理** | 管理评估数据集 |\n| **LLM 应用追踪** | 追踪 LLM 应用的运行轨迹 |\n| **生产环境监控** | 监控生产环境的评估指标 |\n| **在线评估** | 支持在线实时评估 |\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### 登录与同步\n\n```bash\n# 登录\ndeepeval login\n\n# 运行测试 - 结果自动同步到云端\ndeepeval test run test_chatbot.py\n```\n\n## 技能集成\n\nDeepEval 可以作为智能代理（Agent）的技能（Skill）使用：\n\n### 安装方式\n\n```bash\n# 使用 skills 兼容的安装器\nnpx skills add confident-ai/deepeval --skill \"deepeval\"\n\n# 或手动复制\ncp skills/deepeval [agent_skills_directory]\n```\n\n### 前置条件\n\n| 用途 | 必需包 | 配置 |\n|------|--------|------|\n| 本地评估 | `pip install -U deepeval` | - |\n| 云端报告/追踪 | `deepeval login` | Confident AI API Key |\n\n资料来源：[skills/README.md](https://github.com/confident-ai/deepeval/blob/main/skills/README.md)\n\n## 测试结果检查\n\n使用 `deepeval inspect` 命令检查测试运行结果：\n\n```bash\ndeepeval inspect [PATH]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `PATH` | 特定测试运行文件或包含测试结果的文件夹 |\n| `-f, --folder` | 指定扫描文件夹，查找最新的测试运行文件 |\n\n该命令会打开 TUI（文本用户界面）来检查保存的测试运行轨迹。\n\n资料来源：[deepeval/cli/inspect.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/inspect.py)\n\n## 性能与扩展性\n\n### 异步评估支持\n\nDeepEval 支持异步评估模式，适用于大规模评估场景：\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\n\nfor golden in dataset.evals_iterator(\n async_config=AsyncConfig(run_async=True),\n metrics=[TaskCompletionMetric()],\n):\n task = asyncio.create_task(agent.run(golden.input))\n dataset.evaluate(task)\n```\n\n### 并发控制\n\n| 配置项 | 说明 |\n|--------|------|\n| `max_concurrent` | 最大并发数 |\n| `max_retries` | 最大重试次数 |\n\n资料来源：[deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n\n## 版本与发布\n\nDeepEval 使用语义化版本控制，当前版本信息可通过以下方式获取：\n\n```python\nimport deepeval\nprint(deepeval.__version__)\n```\n\n| 版本属性 | 说明 |\n|----------|------|\n| `__version__` | 当前安装的版本号 |\n| GitHub Releases | 发布历史和更新日志 |\n\n## 许可证\n\nDeepEval 采用开源许可证，具体信息请参阅 [LICENSE.md](https://github.com/confident-ai/deepeval/blob/master/LICENSE.md)。\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方文档 | [deepeval.com/docs](https://deepeval.com/docs/getting-started) |\n| GitHub 仓库 | [github.com/confident-ai/deepeval](https://github.com/confident-ai/deepeval) |\n| Discord 社区 | [discord.gg/3SEyvpgu2f](https://discord.gg/3SEyvpgu2f) |\n| Twitter | [@deepeval](https://x.com/deepeval) |\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [测试用例定义](#page-test-cases)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n- [deepeval/test_case/llm_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)\n- [deepeval/evaluate/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/__init__.py)\n- [deepeval/evaluate/evaluate.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/evaluate.py)\n \n\n# 快速开始\n\nDeepEval 的\"快速开始\"模块为开发者提供了在本地环境中快速上手 LLM 评估框架的最简路径。该模块封装了从测试用例定义、指标配置到评估执行的全流程，使开发者能够在几分钟内完成首个 LLM 应用的质量验证。通过深度集成 Pytest 生态，DeepEval 将 LLM 评估转化为标准化的单元测试流程，与现有开发工作流无缝衔接。资料来源：[README.md]()\n\n## 核心概念\n\nDeepEval 将 LLM 评估抽象为三个核心概念：**测试用例（Test Case）**、**评估指标（Metric）** 和 **断言验证（Assertion）**。测试用例定义了被评估 LLM 应用的输入、期望输出和上下文信息；评估指标则实现了具体的评估算法，如 G-Eval、答案相关性、幻觉检测等；断言验证将指标得分与阈值进行比较，以判断测试是否通过。资料来源：[deepeval/test_case/llm_test_case.py]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[创建测试文件] --> B[定义 LLMTestCase]\n B --> C[配置评估指标]\n C --> D[调用 assert_test]\n D --> E[运行测试命令]\n E --> F{测试通过?}\n F -->|是| G[✅ 测试成功]\n F -->|否| H[❌ 测试失败]\n \n I[设置 OPENAI_API_KEY] -.-> A\n```\n\n## 环境准备\n\n### 环境变量配置\n\n在使用 DeepEval 之前，需要设置 LLM API 密钥。DeepEval 支持 OpenAI、Anthropic、Google Gemini 等多种模型提供商。以 OpenAI 为例，在终端中执行以下命令设置环境变量：\n\n```bash\nexport OPENAI_API_KEY=\"...\"\n```\n\n也可使用 `.env.local` 文件管理密钥：\n\n```bash\ncp .env.example .env.local\n# 编辑 .env.local 文件（该文件已被 git 忽略）\n```\n\n资料来源：[README.md]()\n\n### 安装 DeepEval\n\n通过 pip 安装 DeepEval：\n\n```bash\npip install -U deepeval\n```\n\n资料来源：[README.md]()\n\n## 使用 Pytest 集成\n\n### 创建测试文件\n\n创建一个名为 `test_chatbot.py` 的测试文件：\n\n```bash\ntouch test_chatbot.py\n```\n\n### 编写测试用例\n\n打开 `test_chatbot.py` 并编写第一个端到端评估测试。DeepEval 将 LLM 应用视为黑盒进行评估：\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ndef test_case():\n correctness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n test_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n )\n assert_test(test_case, [correctness_metric])\n```\n\n资料来源：[README.md]()\n\n### 核心参数说明\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `input` | str | 用户输入，模拟 LLM 应用的输入 |\n| `actual_output` | str | LLM 应用的实际输出 |\n| `expected_output` | str | 期望的正确答案 |\n| `retrieval_context` | List[str] | 检索上下文，用于 RAG 评估 |\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `name` | str | 指标名称 |\n| `criteria` | str | 评估标准的描述性文本 |\n| `evaluation_params` | List[SingleTurnParams] | 评估所需的参数列表 |\n| `threshold` | float | 通过阈值（0-1） |\n\n资料来源：[deepeval/test_case/llm_test_case.py]()\n\n### 运行测试\n\n在终端中执行测试命令：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n测试通过时将显示成功消息，未通过则显示失败详情。\n\n资料来源：[README.md]()\n\n## 不使用 Pytest 集成\n\n对于 Jupyter Notebook 环境或偏好命令式编程的场景，DeepEval 提供了 `evaluate()` 函数：\n\n```python\nfrom deepeval import evaluate\nfrom deepeval.metrics import AnswerRelevancyMetric\nfrom deepeval.test_case import LLMTestCase\n\nanswer_relevancy_metric = AnswerRelencyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\nevaluate([test_case], [answer_relevancy_metric])\n```\n\n资料来源：[README.md]()\n\n## 独立使用评估指标\n\nDeepEval 高度模块化，允许在项目任何位置单独使用评估指标：\n\n```python\nfrom deepeval.metrics import AnswerRelevancyMetric\nfrom deepeval.test_case import LLMTestCase\n\nanswer_relevancy_metric = AnswerRelencyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\nanswer_relevancy_metric.measure(test_case)\nprint(answer_relevancy_metric.score)\n```\n\n资料来源：[README.md]()\n\n## 与 Confident AI 平台集成\n\nDeepEval 支持与 Confident AI 平台的深度集成。登录后，测试结果将自动同步到云端：\n\n```bash\ndeepeval login\n```\n\n登录后运行测试，结果自动上传：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n资料来源：[README.md]()\n\n## 评估指标类型\n\n| 指标名称 | 说明 | 适用场景 |\n|----------|------|----------|\n| GEval | 基于 LLM 的通用评估指标，支持自定义评估标准 | 通用质量评估 |\n| AnswerRelevancyMetric | 答案相关性评估 | RAG 系统 |\n| TaskCompletionMetric | 任务完成度评估 | AI Agent |\n| HallucinationMetric | 幻觉检测 | 内容生成 |\n\n资料来源：[README.md]()\n\n## 关键源码结构\n\n`deepeval.test_case` 模块导出了测试用例相关的核心类：\n\n```python\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n```\n\n`deepeval.evaluate` 模块提供了评估执行接口：\n\n```python\nfrom deepeval import evaluate, assert_test\n```\n\n资料来源：[deepeval/test_case/__init__.py](), [deepeval/evaluate/__init__.py]()\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心模块结构](#page-core-modules), [评估指标体系](#page-metrics), [追踪系统](#page-tracing-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/evaluate/evaluate.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/evaluate.py)\n- [deepeval/evaluate/execute/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/__init__.py)\n- [deepeval/evaluate/execute/e2e.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/e2e.py)\n- [deepeval/evaluate/execute/agentic.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/agentic.py)\n- [deepeval/constants.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/constants.py)\n \n\n# 系统架构\n\n## 概述\n\nDeepEval 是一个开源的 LLM（大语言模型）评估框架，采用模块化设计实现评估流程的解耦与扩展。系统架构围绕**评估执行引擎**、**指标计算层**、**追踪系统**和**CLI命令接口**四大核心模块展开，支持端到端测试、代理评估、合成数据生成等多种评估场景。\n\nDeepEval 的核心设计理念是将 LLM 应用视为黑盒，通过标准化测试用例（`LLMTestCase`）和可插拔的指标（Metric）系统，实现跨框架的通用评估能力。\n\n## 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"CLI 层\"\n CLI[deepeval CLI]\n Login[login 命令]\n TestRun[test run 命令]\n Generate[generate 命令]\n Inspect[inspect 命令]\n end\n\n subgraph \"评估执行层 (evaluate)\"\n Evaluate[evaluate 函数]\n E2EExecutor[端到端执行器]\n AgenticExecutor[代理执行器]\n SyncRunner[同步运行器]\n AsyncRunner[异步运行器]\n end\n\n subgraph \"核心指标层 (metrics)\"\n GEval[G-Eval 指标]\n TaskCompletion[任务完成度]\n AnswerRelevancy[答案相关性]\n Faithfulness[忠实度]\n Hallucination[幻觉检测]\n end\n\n subgraph \"追踪系统 (tracing)\"\n Observe[@observe 装饰器]\n Trace[trace 上下文管理器]\n SpanProcessor[Span 处理器]\n ConfidentAI[Confident AI 云端]\n end\n\n subgraph \"数据合成层 (synthesizer)\"\n Synthesizer[数据合成器]\n ContextConstruction[上下文构建]\n GoldenGenerator[黄金数据生成]\n end\n\n subgraph \"集成层 (integrations)\"\n LangChain[LangChain]\n LangGraph[LangGraph]\n OpenAI[OpenAI]\n Anthropic[Anthropic]\n LlamaIndex[LlamaIndex]\n CrewAI[CrewAI]\n GoogleADK[Google ADK]\n Strands[Strands]\n end\n\n CLI --> Evaluate\n CLI --> Generate\n CLI --> Login\n CLI --> Inspect\n \n Evaluate --> E2EExecutor\n Evaluate --> AgenticExecutor\n \n E2EExecutor --> SyncRunner\n E2EExecutor --> AsyncRunner\n \n AgenticExecutor --> SyncRunner\n AgenticExecutor --> AsyncRunner\n \n SyncRunner --> GEval\n SyncRunner --> TaskCompletion\n SyncRunner --> AnswerRelevancy\n AsyncRunner --> GEval\n AsyncRunner --> TaskCompletion\n AsyncRunner --> AnswerRelevancy\n \n Observe --> Trace\n Trace --> SpanProcessor\n SpanProcessor --> ConfidentAI\n \n Synthesizer --> ContextConstruction\n Synthesizer --> GoldenGenerator\n \n LangChain --> Observe\n LangGraph --> Observe\n OpenAI --> Observe\n Anthropic --> Observe\n```\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n## 核心执行层\n\n### 评估执行器类型\n\nDeepEval 的评估执行层支持两种主要的执行模式，分别针对不同的评估场景：\n\n| 执行器类型 | 适用场景 | 源码文件 |\n|-----------|---------|---------|\n| `E2EExecutor` | 端到端评估，将 LLM 应用视为黑盒 | `deepeval/evaluate/execute/e2e.py` |\n| `AgenticExecutor` | 代理级别评估，支持工具调用追踪 | `deepeval/evaluate/execute/agentic.py` |\n\n资料来源：[deepeval/evaluate/execute/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/__init__.py)\n\n### 执行流程\n\n```mermaid\ngraph LR\n A[LLMTestCase 输入] --> B[创建测试用例]\n B --> C{执行模式}\n C -->|同步| D[SyncRunner 执行]\n C -->|异步| E[AsyncRunner 执行]\n D --> F[指标计算]\n E --> F\n F --> G[分数判定]\n G --> H{是否通过阈值}\n H -->|是| I[测试通过]\n H -->|否| J[测试失败]\n```\n\n### E2E 执行器\n\nE2E（端到端）执行器是 DeepEval 最基本的评估执行器。它接收标准化测试用例，按照配置的指标逐一计算评分，最终返回评估结果。\n\n核心职责：\n- 接收 `LLMTestCase` 测试用例\n- 协调多个指标并行或串行计算\n- 聚合评估结果并生成报告\n\n资料来源：[deepeval/evaluate/execute/e2e.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/e2e.py)\n\n### Agentic 执行器\n\n代理执行器专门用于评估 LLM 代理（Agent）应用，支持追踪工具调用、多步推理和任务完成度等代理特有指标。\n\n核心职责：\n- 追踪代理的完整执行轨迹\n- 记录工具调用序列和参数\n- 评估任务完成度和步骤效率\n\n资料来源：[deepeval/evaluate/execute/agentic.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/agentic.py)\n\n## 指标系统\n\n### 指标类型概览\n\nDeepEval 提供了丰富的预置指标，涵盖 LLM 评估的多个维度：\n\n| 指标类别 | 指标名称 | 用途 |\n|---------|---------|-----|\n| **通用指标** | GEval | 基于 LLM-as-Judge 的通用评估 |\n| **答案质量** | Answer Relevancy | 评估答案与问题的相关性 |\n| **答案质量** | Faithfulness | 评估答案与检索上下文的忠实度 |\n| **答案质量** | Hallucination | 检测答案中的幻觉内容 |\n| **代理指标** | Task Completion | 评估代理是否完成任务 |\n| **代理指标** | Tool Correctness | 检查工具调用的正确性 |\n| **代理指标** | Goal Accuracy | 衡量目标达成的准确性 |\n| **代理指标** | Step Efficiency | 评估步骤效率 |\n\n资料来源：[README.md - Metrics and Features](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### G-Eval 指标\n\nG-Eval 是 DeepEval 的核心评估方法，基于最新的研究论文实现。它通过 LLM-as-Judge 范式进行自动化评估。\n\n使用方式：\n\n```python\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ncorrectness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n)\n```\n\n### 任务完成度指标\n\n专门用于评估 LLM 代理是否成功完成了给定任务：\n\n```python\nfrom deepeval.metrics import TaskCompletionMetric\nfrom deepeval.tracing import trace\n\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n## 追踪系统\n\n### 追踪架构\n\nDeepEval 的追踪系统采用 OpenTelemetry 兼容的设计，同时支持本地追踪和云端同步：\n\n```mermaid\ngraph TD\n A[被装饰的函数] --> B[@observe 装饰器]\n B --> C[trace 上下文]\n C --> D[当前 Span]\n D --> E{Span 处理器}\n E -->|本地模式| F[本地存储]\n E -->|云端模式| G[Confident AI]\n E -->|评估模式| H[Trace Manager]\n \n F --> I[评估结果]\n G --> I\n H --> I\n```\n\n### 核心追踪组件\n\n| 组件 | 功能 | 源码位置 |\n|-----|------|---------|\n| `@observe()` | 函数装饰器，自动创建追踪上下文 | `deepeval/tracing` |\n| `trace()` | 上下文管理器，用于批量追踪 | `deepeval/tracing` |\n| `update_current_span()` | 更新当前 span 的数据 | `deepeval/tracing` |\n| `update_current_trace()` | 更新当前 trace 的全局数据 | `deepeval/tracing` |\n\n资料来源：[README.md - Evals With Full Traceability](https://github.com/confident-ai/deepeval/blob/main/README.md)\n\n### 追踪装饰器使用\n\n```python\nfrom deepeval.tracing import observe, update_current_span\nfrom deepeval.test_case import LLMTestCase\n\n@observe()\ndef inner_component(input: str):\n output = \"result\"\n update_current_span(test_case=LLMTestCase(input=input, actual_output=output))\n return output\n\n@observe()\ndef app(input: str):\n return inner_component(input)\n```\n\n## 框架集成\n\n### 集成矩阵\n\nDeepEval 支持与主流 LLM 框架的无缝集成，通过统一的回调机制实现追踪和评估：\n\n| 框架 | 集成方式 | 源码位置 |\n|-----|---------|---------|\n| OpenAI | 原生支持 | `deepeval.openai` |\n| Anthropic | 原生支持 | `deepeval.anthropic` |\n| LangChain | CallbackHandler | `deepeval/integrations/langchain` |\n| LangGraph | CallbackHandler | `deepeval/integrations/langchain` |\n| LlamaIndex | 异步集成 | `deepeval/integrations/llamaindex` |\n| CrewAI | instrument_crewai | `deepeval/integrations/crewai` |\n| Google ADK | instrument_google_adk | `deepeval/integrations/google_adk` |\n| Strands | instrument_strands | `deepeval/integrations/strands` |\n| AWS AgentCore | instrument_agentcore | `deepeval/integrations/agentcore` |\n| Pydantic AI | 原生支持 | `deepeval/integrations/pydantic_ai` |\n\n资料来源：[deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)\n\n### 集成能力说明\n\n每个集成支持四种级别的能力：\n\n| 能力级别 | 说明 |\n|---------|-----|\n| **Bare** | 直接调用框架即可产生追踪，无需额外包装 |\n| **`@observe` / `with trace(...)`** | 包装后追踪数据流入 DeepEval 原生上下文 |\n| **`evals_iterator`** | 支持在数据集迭代器中使用指标评估 |\n| **`deepeval test run`** | 支持 pytest 入口点的追踪评估 |\n\n## CLI 命令系统\n\n### 命令概览\n\nDeepEval CLI 提供了丰富的命令行接口：\n\n| 命令 | 功能 | 源码文件 |\n|-----|------|---------|\n| `deepeval login` | 登录 Confident AI 平台 | `deepeval/cli/main.py` |\n| `deepeval test run` | 运行 Pytest 测试文件 | `deepeval/cli/test` |\n| `deepeval generate` | 生成合成黄金数据 | `deepeval/cli/generate/command.py` |\n| `deepeval set-model` | 设置默认评估模型 | `deepeval/cli/main.py` |\n| `deepeval inspect` | TUI 检视测试结果 | `deepeval/cli/inspect.py` |\n\n### 黄金数据生成\n\n`deepeval generate` 命令支持多种数据生成方法：\n\n```mermaid\ngraph TD\n A[generate 命令] --> B{生成方法}\n B -->|DOCS| C[从文档生成]\n B -->|CONTEXTS| D[从上下文生成]\n B -->|SCRATCH| E[从零生成]\n B -->|GOLDENS| F[从已有黄金数据生成]\n \n C --> G[文档分块]\n D --> H[上下文质量过滤]\n E --> I[任务描述生成]\n F --> J[变体扩展]\n \n G --> K[Synthesizer]\n H --> K\n I --> K\n J --> K\n \n K --> L[保存为 JSON/CSV]\n```\n\n生成方法配置：\n\n| 方法 | 选项 | 说明 |\n|-----|------|-----|\n| DOCS | `--documents` | 从文档文件路径列表生成 |\n| CONTEXTS | `--contexts-file` | 从上下文文件生成 |\n| SCRATCH | `--num-goldens` | 从零开始生成指定数量 |\n| GOLDENS | `--goldens-file` | 基于已有黄金数据生成变体 |\n\n资料来源：[deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n\n### inspect 命令\n\n`deepeval inspect` 命令提供交互式 TUI 用于检视测试结果：\n\n```python\n# 查看最新测试运行结果\ndeepeval inspect\n\n# 查看指定文件\ndeepeval inspect path/to/test_run_123.json\n\n# 查看指定文件夹的最新结果\ndeepeval inspect --folder ./results\n```\n\n该命令支持可选的 `deepeval[inspect]` 扩展包，需要单独安装。\n\n## 数据模型\n\n### LLMTestCase\n\n核心测试用例数据模型：\n\n| 字段 | 类型 | 必需 | 说明 |\n|-----|------|-----|-----|\n| `input` | str | 是 | 测试输入 |\n| `actual_output` | str | 是 | LLM 实际输出 |\n| `expected_output` | str | 否 | 期望输出 |\n| `retrieval_context` | List[str] | 否 | RAG 检索上下文 |\n| `context` | List[Dict] | 否 | 多轮对话上下文 |\n\n### SingleTurnParams 与 MultiTurnParams\n\n评估参数枚举，用于指定 G-Eval 等指标的评估维度：\n\n```python\nfrom deepeval.test_case import SingleTurnParams, MultiTurnParams\n\n# 单轮评估参数\nSingleTurnParams.INPUT\nSingleTurnParams.ACTUAL_OUTPUT\nSingleTurnParams.EXPECTED_OUTPUT\nSingleTurnParams.RETRIEVAL_CONTEXT\n\n# 多轮评估参数\nMultiTurnParams.INPUT\nMultiTurnParams.ACTUAL_OUTPUT\nMultiTurnParams.EXPECTED_OUTCOME\nMultiTurnParams.RETRIEVAL_CONTEXT\nMultiTurnParams.AGENT_ICONOGRAPHY\n```\n\n## 评估配置\n\n### AsyncConfig\n\n异步评估配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `run_async` | bool | False | 是否启用异步执行 |\n| `max_concurrent` | int | None | 最大并发数 |\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\n\nasync_config = AsyncConfig(\n run_async=True,\n max_concurrent=5\n)\n```\n\n### ContextConstructionConfig\n\n合成数据生成的上下文构建配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `max_contexts_per_document` | int | 5 | 每个文档最多生成上下文数 |\n| `min_contexts_per_document` | int | 1 | 每个文档最少生成上下文数 |\n| `chunk_size` | int | 1000 | 文档分块大小 |\n| `chunk_overlap` | int | 200 | 分块重叠大小 |\n| `context_quality_threshold` | float | 0.5 | 上下文质量阈值 |\n| `context_similarity_threshold` | float | 0.5 | 上下文相似度阈值 |\n| `max_retries` | int | 3 | 最大重试次数 |\n\n## 常量定义\n\nDeepEval 在 `deepeval/constants.py` 中定义了全局常量，包括：\n\n- 默认阈值配置\n- API 超时设置\n- 缓存策略配置\n- 日志级别定义\n\n这些常量贯穿整个评估流程，确保行为的一致性和可配置性。\n\n资料来源：[deepeval/constants.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/constants.py)\n\n## 评估流程总结\n\n```mermaid\ngraph TB\n subgraph \"1. 准备阶段\"\n A1[编写测试用例] --> A2[定义指标]\n A2 --> A3[配置评估参数]\n end\n\n subgraph \"2. 执行阶段\"\n A3 --> B1[创建评估器]\n B1 --> B2{执行模式}\n B2 -->|同步| B3[SyncRunner]\n B2 -->|异步| B4[AsyncRunner]\n B3 --> B5[指标并行计算]\n B4 --> B5\n end\n\n subgraph \"3. 评估阶段\"\n B5 --> C1[调用 LLM 评估]\n C1 --> C2[分数聚合]\n C2 --> C3[阈值判定]\n end\n\n subgraph \"4. 报告阶段\"\n C3 --> D1[生成测试报告]\n D1 --> D2[上传至 Confident AI]\n D2 --> D3[本地保存 JSON]\n end\n```\n\n## 最佳实践\n\n### 测试用例设计\n\n1. **输入多样化**：确保测试用例覆盖各种边界情况和典型场景\n2. **明确期望输出**：为关键测试提供期望输出以便精确评估\n3. **使用 RAG 上下文**：RAG 应用应提供 retrieval_context 参数\n\n### 指标配置\n\n1. **合理设置阈值**：根据业务需求调整 threshold 参数\n2. **多指标组合**：复杂场景可组合使用多个指标\n3. **使用 G-Eval**：对于主观性评估，优先使用 G-Eval\n\n### 追踪配置\n\n1. **使用 `@observe` 装饰器**：确保关键函数被追踪\n2. **更新 span 数据**：在函数内使用 `update_current_span` 丰富追踪信息\n3. **分离关注点**：将评估逻辑与业务逻辑解耦\n\n---\n\n\n\n## 核心模块结构\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [评估指标体系](#page-metrics), [测试用例定义](#page-test-cases)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/metrics/base_metric.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/base_metric.py)\n- [deepeval/metrics/indicator.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/indicator.py)\n- [deepeval/test_case/utils.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/utils.py)\n- [deepeval/config/settings.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/config/settings.py)\n- [deepeval/synthesizer/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/__init__.py)\n \n\n# 核心模块结构\n\n## 概述\n\nDeepEval 是一个面向大语言模型（LLM）应用的评估框架，采用了模块化架构设计。其核心模块结构围绕**指标系统（Metrics）**、**测试用例（Test Case）**、**追踪系统（Tracing）**和**配置管理（Configuration）**四大支柱构建。框架的核心设计理念是将 LLM 评估过程抽象为可组合、可扩展的组件，类似于 Pytest 在单元测试领域的角色，但专门针对 LLM 应用场景优化。\n\nDeepEval 的架构设计允许开发者以两种主要方式使用该框架：一是集成到 Pytest 测试流程中，通过 `@assert_test` 装饰器实现声明式评估；二是作为独立库使用，通过 `evaluate()` 函数直接调用指标进行评估。这种双重使用模式体现了框架对不同开发工作流的包容性支持。\n\n框架的核心价值在于其本地化评估能力——所有指标计算和 LLM 调用都可以在用户本地机器上运行，无需依赖外部云服务。同时，通过与 Confident AI 平台的集成，开发者可以选择性地将评估结果同步到云端进行可视化和协作分析。\n\n## 核心模块架构图\n\n```mermaid\ngraph TD\n subgraph \"核心层\"\n BM[base_metric.py
BaseMetric 基类]\n IND[indicator.py
Indicator 指标系统]\n TU[test_case/utils.py
LLMTestCase]\n CFG[config/settings.py
配置管理]\n end\n \n subgraph \"执行层\"\n SYN[Synthesizer
合成器]\n EVAL[evaluate()
评估函数]\n TRACE[Tracing
追踪系统]\n end\n \n subgraph \"集成层\"\n LC[LangChain]\n OAI[OpenAI]\n ANTH[Anthropic]\n LI[LlamaIndex]\n CR[CrewAI]\n GADK[Google ADK]\n end\n \n subgraph \"CLI 层\"\n CMD[CLI Commands]\n RUN[Test Runner]\n GEN[Generate
生成器]\n end\n \n BM --> IND\n IND --> TU\n CFG --> BM\n SYN --> BM\n EVAL --> IND\n TRACE --> BM\n LC --> TRACE\n OAI --> TRACE\n ANTH --> TRACE\n CMD --> SYN\n CMD --> RUN\n```\n\n## 指标系统（Metrics）\n\n### BaseMetric 基类架构\n\n指标系统是 DeepEval 的核心评估单元，所有评估指标都继承自 `BaseMetric` 基类。基类定义了评估接口的通用契约，确保各类指标实现的一致性和可替换性。\n\n`BaseMetric` 提供了以下核心能力：\n\n1. **分数计算（measure）**：接收 `LLMTestCase` 对象，执行指标评估逻辑\n2. **阈值判定（threshold）**：定义通过/失败的分数边界\n3. **评分理由生成（reason）**：为分数提供人类可读的评估解释\n4. **异步支持**：部分指标支持异步执行模式\n\n资料来源：[deepeval/metrics/base_metric.py:1-50]()\n\n### Indicator 指标实现\n\n`indicator.py` 文件包含了 DeepEval 内置指标的具体实现。指标系统采用策略模式设计，每种指标封装了特定的评估逻辑。\n\n**主要指标类型：**\n\n| 指标类型 | 用途 | 评估维度 |\n|---------|------|---------|\n| GEval | 基于 LLM 的通用评估 | 可配置 criteria |\n| TaskCompletionMetric | 任务完成度评估 | Agent 目标达成 |\n| AnswerRelevancyMetric | 回答相关性评估 | RAG 管道输出质量 |\n| FaithfulnessMetric | 事实一致性评估 | RAG 管道准确性 |\n| HallucinationMetric | 幻觉检测评估 | 内容真实性 |\n\n资料来源：[deepeval/metrics/indicator.py:1-100]()\n\n### 指标执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant Metric as Metric 实例\n participant TC as LLMTestCase\n participant LLM as LLM API\n \n User->>Metric: measure(test_case)\n Metric->>TC: 提取评估参数\n Metric->>LLM: 调用 LLM-as-Judge\n LLM-->>Metric: 返回评分结果\n Metric->>Metric: 应用 threshold 判定\n Metric-->>User: 返回 score 和 reason\n```\n\n## 测试用例系统（Test Case）\n\n### LLMTestCase 数据结构\n\n`LLMTestCase` 是 DeepEval 中表示测试用例的核心数据结构。它封装了评估所需的输入、输出和上下文信息。\n\n**基础参数：**\n\n| 参数名 | 类型 | 必需 | 说明 |\n|--------|------|------|------|\n| input | str | 是 | 测试输入/问题 |\n| actual_output | str | 是 | LLM 实际输出 |\n| expected_output | str | 否 | 期望的标准答案 |\n| retrieval_context | List[str] | 否 | RAG 检索上下文 |\n\n资料来源：[deepeval/test_case/utils.py:1-80]()\n\n### 单轮与多轮参数\n\nDeepEval 通过 `SingleTurnParams` 和 `MultiTurnParams` 枚举区分不同类型的评估参数：\n\n- **SingleTurnParams**：适用于简单问答场景，参数包括 `ACTUAL_OUTPUT`、`EXPECTED_OUTPUT`\n- **MultiTurnParams**：适用于对话系统，需要管理对话历史和轮次间的状态传递\n\n这种设计使得框架能够灵活支持从简单问答到复杂多轮对话的各类评估场景。\n\n## 配置管理体系\n\n### 环境变量配置\n\nDeepEval 实现了自动化的环境变量加载机制，配置文件位于 `deepeval/config/settings.py`。\n\n**配置加载优先级（从高到低）：**\n\n1. 进程环境变量（`os.environ`）\n2. `.env.local` 文件\n3. `.env` 文件\n\n**禁用机制：**\n设置环境变量 `DEPEVAL_DISABLE_DOTENV=1` 可禁用自动环境变量加载。\n\n资料来源：[deepeval/config/settings.py:1-30]()\n\n### 合成器配置\n\n`ContextConstructionConfig` 是合成器用于从文档生成测试数据的配置类：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| chunk_size | int | 1000 | 文档分块大小 |\n| chunk_overlap | int | 200 | 分块重叠区域 |\n| max_contexts_per_document | int | 10 | 单文档最大上下文数 |\n| min_contexts_per_document | int | 1 | 单文档最小上下文数 |\n| context_quality_threshold | float | 0.5 | 上下文质量阈值 |\n\n## 追踪与可观测性系统\n\n### trace 上下文管理器\n\nDeepEval 提供了 `trace` 上下文管理器用于包装 LLM 调用，实现端到端的评估追踪：\n\n```python\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\nwith trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(model=\"claude-sonnet-4-5\", ...)\n```\n\n这种设计允许在追踪上下文中自动捕获和评估所有 LLM 调用，无需修改业务代码。\n\n资料来源：[deepeval/tracing/__init__.py:1-50]()\n\n### @observe 装饰器\n\n对于更细粒度的组件级评估，DeepEval 提供了 `@observe` 装饰器：\n\n```python\nfrom deepeval.tracing import observe, update_current_span\n\n@observe()\ndef inner_component(input: str):\n output = process(input)\n update_current_span(test_case=LLMTestCase(input=input, actual_output=output))\n return output\n```\n\n`update_current_span` 函数允许在任意嵌套层级更新当前追踪 span 的测试用例数据，实现组件级别的精确评估。\n\n## 集成层架构\n\n### 集成模式矩阵\n\nDeepEval 的集成系统支持四种不同的评估模式：\n\n| 模式 | 描述 | 使用场景 |\n|------|------|---------|\n| Bare | 直接调用框架，自动创建追踪 | 快速上手 |\n| @observe / with trace | 包裹在追踪上下文中 | 需要细粒度控制 |\n| evals_iterator | 数据集迭代器集成 | 批量评估 |\n| deepeval test run | Pytest 集成 | 持续集成 |\n\n### 支持的框架集成\n\nDeepEval 官方支持以下框架的深度集成：\n\n- **OpenAI**：原生客户端集成\n- **Anthropic**：Claude 模型支持\n- **LangChain**：回调处理器模式\n- **LangGraph**：状态机评估\n- **LlamaIndex**：异步评估支持\n- **CrewAI**：多智能体评估\n- **Google ADK**：Agent Development Kit\n- **Strands**：自定义智能体框架\n\n每种集成都通过统一的回调或包装机制接入 DeepEval 的追踪和评估系统。\n\n## CLI 命令结构\n\n### generate 命令\n\n`deepeval generate` 命令用于从多种数据源生成合成测试数据：\n\n```bash\ndeepeval generate --method docs --variation single_turn --documents ./docs\n```\n\n**支持的生成方法：**\n\n| 方法 | 参数 | 说明 |\n|------|------|------|\n| DOCS | --documents | 从文档生成 |\n| CONTEXTS | --contexts-file | 从预定义上下文生成 |\n| SCRATCH | --num-goldens | 从零生成 |\n| GOLDENS | --goldens-file | 基于现有测试数据扩充 |\n\n资料来源：[deepeval/cli/generate/command.py:1-100]()\n\n### test 命令\n\n`deepeval test run` 命令执行 Pytest 测试并自动同步结果到 Confident AI 平台：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n该命令会自动加载 `.env.local` 和 `.env` 中的配置，执行测试后上传结果。\n\n## 模块间依赖关系\n\n```mermaid\ngraph LR\n subgraph \"依赖层级\"\n A[配置层
config/]\n B[基础层
base_metric.py]\n C[指标层
indicator.py]\n D[测试用例层
test_case/]\n E[合成器层
synthesizer/]\n F[追踪层
tracing/]\n G[CLI 层
cli/]\n end\n \n A --> B\n B --> C\n D --> C\n A --> D\n C --> E\n F --> E\n E --> G\n C --> G\n```\n\n## 关键设计模式\n\n### 1. 策略模式\n\n所有指标实现统一的 `BaseMetric` 接口，允许在运行时动态替换评估策略：\n\n```python\n# 同一接口，不同实现\nmetrics = [\n AnswerRelevancyMetric(threshold=0.7),\n FaithfulnessMetric(threshold=0.8),\n]\n```\n\n### 2. 装饰器模式\n\n`@assert_test` 和 `@observe` 装饰器为普通函数添加评估能力，无需修改业务逻辑：\n\n```python\n@assert_test(llm_output_symbol=\"actual_output\")\ndef my_llm_app():\n return llm.invoke(\"Hello\")\n```\n\n### 3. 上下文管理器模式\n\n`trace` 上下文管理器自动管理追踪生命周期，确保资源正确释放：\n\n```python\nwith trace(metrics=[metric]):\n # 追踪范围内所有 LLM 调用自动被捕获\n pass\n```\n\n## 扩展开发指南\n\n### 创建自定义指标\n\n要创建自定义指标，需继承 `BaseMetric` 并实现核心方法：\n\n```python\nclass MyCustomMetric(BaseMetric):\n def __init__(self, threshold=0.5):\n self.threshold = threshold\n \n def measure(self, test_case: LLMTestCase) -> float:\n # 实现评估逻辑\n score = self._evaluate(test_case)\n self.score = score\n self.reason = self._generate_reason(score)\n return score\n \n async def a_measure(self, test_case: LLMTestCase) -> float:\n # 可选的异步实现\n pass\n```\n\n### 框架集成开发\n\n开发新的框架集成需要实现相应的回调接口：\n\n1. 实现框架特定的回调处理器\n2. 在回调中调用 `update_current_span` 更新追踪数据\n3. 注册集成模块到 `deepeval/integrations/`\n\n## 总结\n\nDeepEval 的核心模块结构体现了清晰的关注点分离和高度的可扩展性。配置管理、指标系统、测试用例和追踪系统构成了框架的基础骨架，而丰富的集成层则将这一能力延伸到各类 LLM 应用开发框架中。通过统一的设计模式和标准化的接口，开发者可以轻松地添加自定义指标或接入新的框架，使 DeepEval 成为 LLM 应用评估的通用解决方案。\n\n---\n\n\n\n## 测试用例定义\n\n### 相关页面\n\n相关主题：[评估执行引擎](#page-evaluate-engine), [评估指标体系](#page-metrics), [数据集管理](#page-dataset-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n- [deepeval/test_case/llm_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)\n- [deepeval/test_case/conversational_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/conversational_test_case.py)\n- [deepeval/test_case/arena_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/arena_test_case.py)\n- [deepeval/test_case/mcp.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/mcp.py)\n \n\n# 测试用例定义\n\n## 概述\n\n在 DeepEval 框架中，测试用例是评估 LLM 应用质量的核心数据结构。测试用例定义了评估所需的输入、期望输出、实际输出以及相关的上下文信息，DeepEval 通过将这些测试用例与评估指标结合来执行自动化评估。\n\nDeepEval 支持多种类型的测试用例，分别对应不同的评估场景：\n\n| 测试用例类型 | 用途 | 适用场景 |\n|-------------|------|---------|\n| `LLMTestCase` | 单轮对话评估 | 简单的问答、文本生成任务 |\n| `ConversationalTestCase` | 多轮对话评估 | 聊天机器人、对话系统 |\n| `ArenaTestCase` | 对比评估 | 模型比较、A/B 测试 |\n| `MCPTestCase` | MCP 协议评估 | Model Context Protocol 集成 |\n\n资料来源：[deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n\n## 核心组件\n\n### LLMTestCase（单轮测试用例）\n\n`LLMTestCase` 是 DeepEval 中最基础的测试用例类，用于定义单轮 LLM 交互的评估数据。\n\n```python\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\n```\n\n资料来源：[deepeval/test_case/llm_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)\n\n### 参数说明\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `input` | str | 是 | 用户输入或查询 |\n| `actual_output` | str | 是 | LLM 应用的实际输出 |\n| `expected_output` | str | 否 | 期望的正确答案 |\n| `retrieval_context` | List[str] | 否 | RAG 系统的检索上下文 |\n| `context` | List[str] | 否 | 额外的上下文信息 |\n| `id` | str | 否 | 测试用例唯一标识符 |\n\n### SingleTurnParams 枚举\n\n`SingleTurnParams` 定义了单轮评估中可用的参数枚举，用于配置 G-Eval 等评估指标：\n\n| 枚举值 | 对应属性 | 说明 |\n|--------|----------|------|\n| `INPUT` | `input` | 用户输入 |\n| `ACTUAL_OUTPUT` | `actual_output` | 实际输出 |\n| `EXPECTED_OUTPUT` | `expected_output` | 期望输出 |\n| `RETRIEVAL_CONTEXT` | `retrieval_context` | 检索上下文 |\n| `CONTEXT` | `context` | 额外上下文 |\n\n资料来源：[deepeval/test_case/llm_test_case.py:1-50](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)\n\n## ConversationalTestCase（多轮对话测试用例）\n\n### 概述\n\n`ConversationalTestCase` 用于评估多轮对话场景，每个测试用例包含一系列消息序列。\n\n```python\nfrom deepeval.test_case import ConversationalTestCase, ConversationalTurn\n\ntest_case = ConversationalTestCase(\n turns=[]\n)\n```\n\n### 消息结构\n\n多轮测试用例中的每条消息（turn）包含：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `messages` | List[Dict[str, str]] | 消息列表，格式为 `[{\"role\": \"user\"/\"assistant\", \"content\": \"...\"}]` |\n| `expected_output` | str | 期望的最终输出 |\n| `expected_tool_calls` | List[Dict] | 期望的工具调用（可选） |\n\n资料来源：[deepeval/test_case/conversational_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/conversational_test_case.py)\n\n## ArenaTestCase（对比评估测试用例）\n\n### 概述\n\n`ArenaTestCase` 用于模型对比评估场景，允许同时评估多个模型的响应。\n\n```python\nfrom deepeval.test_case import ArenaTestCase\n\narena_test_case = ArenaTestCase(\n models=[\"gpt-4\", \"claude-3-opus\"],\n input=\"What is machine learning?\",\n expected_output=\"...\"\n)\n```\n\n### ArenaTurnParams 枚举\n\n| 枚举值 | 说明 |\n|--------|------|\n| `INPUT` | 用户输入 |\n| `EXPECTED_OUTPUT` | 期望输出 |\n| `MODEL_OUTPUT` | 模型输出 |\n| `RETRIEVAL_CONTEXT` | 检索上下文 |\n\n资料来源：[deepeval/test_case/arena_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/arena_test_case.py)\n\n## 测试用例执行流程\n\n```mermaid\ngraph TD\n A[创建测试用例] --> B{选择测试用例类型}\n B -->|单轮| C[LLMTestCase]\n B -->|多轮| D[ConversationalTestCase]\n B -->|对比| E[ArenaTestCase]\n \n C --> F[定义评估指标]\n D --> F\n E --> F\n \n F --> G[调用 assert_test]\n G --> H{评估结果}\n H -->|通过| I[✅ 测试通过]\n H -->|失败| J[❌ 测试失败]\n```\n\n资料来源：[deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n\n## 使用示例\n\n### 基本单轮评估\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ndef test_case():\n correctness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n test_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n )\n assert_test(test_case, [correctness_metric])\n```\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/master/README.md)\n\n### RAG 场景评估\n\n```python\ntest_case = LLMTestCase(\n input=\"What is the return policy?\",\n actual_output=\"Our return policy allows 30 days for returns.\",\n expected_output=\"30-day return policy\",\n retrieval_context=[\n \"All items can be returned within 30 days of purchase.\",\n \"Items must be in original condition for a full refund.\"\n ]\n)\n```\n\n### 带上下文的评估\n\n```python\ntest_case = LLMTestCase(\n input=\"Summarize the document\",\n actual_output=\"The document discusses...\",\n context=[\n \"Document Title: Annual Report 2024\",\n \"Author: Company XYZ\",\n \"Published: January 2024\"\n ]\n)\n```\n\n## CLI 执行\n\n测试用例可以通过 DeepEval CLI 执行：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n其中 `test_chatbot.py` 包含使用 `assert_test` 定义的测试用例。\n\n资料来源：[deepeval/cli/inspect.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/inspect.py)\n\n## 与评估指标的集成\n\n测试用例需要与评估指标结合使用才能完成评估。常用的评估指标包括：\n\n| 指标名称 | 说明 | 适用场景 |\n|---------|------|---------|\n| `GEval` | 基于 LLM 的自动评估 | 通用评估 |\n| `TaskCompletionMetric` | 任务完成度评估 | Agent 评估 |\n| `AnswerRelevancyMetric` | 答案相关性评估 | RAG 评估 |\n| `HallucinationMetric` | 幻觉检测 | 事实准确性评估 |\n\n```python\nfrom deepeval.metrics import GEval\n\nmetric = GEval(\n name=\"Correctness\",\n criteria=\"评估实际输出与期望输出的一致性\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n)\n```\n\n## 数据隐私说明\n\n当使用 DeepEval 平台时，所有测试用例数据会自动记录到平台。更多数据隐私信息请参考官方文档。\n\n资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/master/README.md)\n\n---\n\n\n\n## 评估指标体系\n\n### 相关页面\n\n相关主题：[测试用例定义](#page-test-cases), [评估执行引擎](#page-evaluate-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/metrics/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/__init__.py)\n- [deepeval/metrics/base_metric.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/base_metric.py)\n- [deepeval/metrics/g_eval/g_eval.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/g_eval/g_eval.py)\n- [deepeval/metrics/rag/answer_relevancy/answer_relevancy.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/rag/answer_relevancy/answer_relevancy.py)\n- [deepeval/metrics/rag/faithfulness/faithfulness.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/rag/faithfulness/faithfulness.py)\n- [deepeval/metrics/agentic/task_completion/task_completion.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/agentic/task_completion/task_completion.py)\n- [README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)\n- [deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)\n \n\n# 评估指标体系\n\n## 概述\n\nDeepEval 的评估指标体系是一套模块化的 LLM 应用评估框架，类似于 Pytest 但专为测试大语言模型应用而设计。该体系融合了最新的研究方法，通过 G-Eval、Task Completion、Answer Relevancy 等指标，利用 LLM-as-a-Judge 及其他 NLP 模型在本地机器上运行评估。资料来源：[README.md]()\n\n评估指标体系支持多种使用方式，包括与 Pytest 集成、独立的 `evaluate()` 函数调用，以及通过 `evals_iterator()` 实现的端到端追踪评估。资料来源：[README.md]()\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[LLMTestCase] --> B[Metric Base Class]\n B --> C[GEval]\n B --> D[RAG Metrics]\n B --> E[Agentic Metrics]\n D --> D1[AnswerRelevancyMetric]\n D --> D2[FaithfulnessMetric]\n E --> E1[TaskCompletionMetric]\n E --> E2[ToolCorrectnessMetric]\n F[评估结果] --> G[Score & Reason]\n```\n\n### 指标分类总览\n\n| 类别 | 指标名称 | 用途 | 适用场景 |\n|------|----------|------|----------|\n| 通用框架 | GEval | 基于自定义标准的多维度评估 | 通用场景 |\n| RAG 评估 | Answer Relevancy | 衡量 RAG 输出的相关性 | RAG 流水线 |\n| RAG 评估 | Faithfulness | 评估输出与检索上下文的忠实度 | RAG 流水线 |\n| Agentic 评估 | Task Completion | 评估 Agent 是否完成目标 | AI Agent |\n| Agentic 评估 | Tool Correctness | 检查工具调用是否正确 | AI Agent |\n| Agentic 评估 | Goal Accuracy | 衡量 Agent 目标达成准确度 | AI Agent |\n\n资料来源：[README.md]()\n\n## 指标基类设计\n\n### BaseMetric 抽象基类\n\n所有评估指标继承自 `BaseMetric` 基类，该基类定义了指标的核心接口和行为规范。资料来源：[deepeval/metrics/base_metric.py]()\n\n#### 核心属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | str | 指标名称 |\n| threshold | float | 通过阈值，范围 0-1 |\n| score | float | 当前测量得分 |\n| reason | str | 评分理由说明 |\n| verbose | bool | 是否输出详细信息 |\n\n#### 核心方法\n\n| 方法 | 说明 |\n|------|------|\n| measure(test_case) | 执行评估并返回分数 |\n| save() | 保存评估结果 |\n| load() | 加载历史评估结果 |\n\n```python\nclass BaseMetric(ABC):\n \"\"\"所有评估指标的抽象基类\"\"\"\n \n @abstractmethod\n def measure(self, test_case: LLMTestCase) -> float:\n \"\"\"执行评估的核心方法\"\"\"\n pass\n```\n\n资料来源：[deepeval/metrics/base_metric.py]()\n\n### 指标执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as Metric\n participant LLM as LLM API\n participant TC as TestCase\n \n U->>M: measure(test_case)\n M->>TC: 提取评估参数\n M->>LLM: 发送评估 Prompt\n LLM-->>M: 评估结果\n M->>M: 计算分数\n M->>M: 生成 Reason\n M-->>U: 返回 Score\n```\n\n## 通用评估框架\n\n### GEval 指标\n\nGEval 是 DeepEval 实现的一种基于最新研究的评估框架，通过 LLM-as-a-Judge 方式对 LLM 输出进行自动化评估。资料来源：[deepeval/metrics/g_eval/g_eval.py]()\n\n#### 参数配置\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | str | 是 | 指标名称 |\n| criteria | str | 是 | 评估标准描述 |\n| evaluation_params | List[SingleTurnParams] | 是 | 评估所需参数 |\n| threshold | float | 否 | 通过阈值，默认 0.5 |\n| model | str | 否 | 使用的 LLM 模型 |\n\n#### 使用示例\n\n```python\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ncorrectness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n)\n\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund.\"\n)\n\nscore = correctness_metric.measure(test_case)\nprint(f\"Score: {score}, Reason: {correctness_metric.reason}\")\n```\n\n资料来源：[deepeval/metrics/g_eval/g_eval.py]()\n\n### GEval 工作原理\n\n```mermaid\ngraph LR\n A[输入 TestCase] --> B[构建 Chain-of-Thought Prompt]\n B --> C[添加评估标准]\n C --> D[调用 LLM API]\n D --> E[LLM 返回评分]\n E --> F[解析分数与理由]\n F --> G[返回评估结果]\n```\n\nGEval 的核心优势在于其灵活性，允许用户定义任意评估标准，通过思维链方式引导 LLM 进行高质量评判。资料来源：[deepeval/metrics/g_eval/g_eval.py]()\n\n## RAG 评估指标\n\nRAG（检索增强生成）评估指标专门用于评估 RAG 流水线的性能，包括答案相关性、忠实度、上下文相关性等维度。资料来源：[deepeval/metrics/rag/answer_relevancy/answer_relevancy.py]()\n\n### Answer Relevancy Metric（答案相关性）\n\n答案相关性指标衡量 RAG 系统输出与输入查询之间的相关程度。资料来源：[deepeval/metrics/rag/answer_relevancy/answer_relevancy.py]()\n\n#### 核心参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| threshold | float | 0.7 | 通过阈值 |\n| model | str | None | 使用的大语言模型 |\n| include_reason | bool | True | 是否包含评分理由 |\n\n#### 实现原理\n\n```python\nanswer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund at no extra costs.\"]\n)\nanswer_relevancy_metric.measure(test_case)\n```\n\n答案相关性评估会分析输入、输出和检索上下文之间的关系，计算语义相似度得分。资料来源：[deepeval/metrics/rag/answer_relevancy/answer_relevancy.py]()\n\n### Faithfulness Metric（忠实度）\n\n忠实度指标评估 RAG 输出的事实准确性，即输出是否与检索到的上下文信息相符。资料来源：[deepeval/metrics/rag/faithfulness/faithfulness.py]()\n\n#### 使用方式\n\n```python\nfrom deepeval.metrics import FaithfulnessMetric\nfrom deepeval.test_case import LLMTestCase\n\nfaithfulness_metric = FaithfulnessMetric(threshold=0.8)\ntest_case = LLMTestCase(\n input=\"公司年假政策是什么？\",\n actual_output=\"员工每年有15天带薪年假\",\n retrieval_context=[\"公司政策规定：员工第一年享有10天年假，工作满3年后增至15天\"]\n)\n\nfaithfulness_metric.measure(test_case)\n```\n\n该指标通过对比输出内容与检索上下文，识别潜在的幻觉（hallucination）问题。资料来源：[deepeval/metrics/rag/faithfulness/faithfulness.py]()\n\n## Agentic 评估指标\n\nAgentic 评估指标专注于 AI Agent 系统的评估，包括任务完成度、工具调用准确性、目标达成率等关键维度。资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()\n\n### Task Completion Metric（任务完成度）\n\n任务完成度是评估 Agent 是否成功达成用户目标的核心指标。资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()\n\n#### 参数配置\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| threshold | float | 否 | 0.5 | 通过阈值 |\n| model | str | 否 | None | 评估用模型 |\n| include_reason | bool | 否 | True | 包含评分理由 |\n| verbose | bool | 否 | False | 详细输出模式 |\n\n#### 使用示例\n\n```python\nfrom deepeval.metrics import TaskCompletionMetric\n\ntask_completion_metric = TaskCompletionMetric(threshold=0.7)\n\nfor golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()\n\n### Agentic 指标体系全景\n\n```mermaid\ngraph TD\n A[Agentic 评估] --> B[任务完成]\n A --> C[工具使用]\n A --> D[规划能力]\n A --> E[参数正确性]\n \n B --> B1[TaskCompletion]\n B --> B2[GoalAccuracy]\n \n C --> C1[ToolCorrectness]\n C --> C2[ToolUse]\n \n D --> D1[PlanAdherence]\n D --> D2[PlanQuality]\n D --> D3[StepEfficiency]\n \n E --> E1[ArgumentCorrectness]\n \n style A fill:#f9f,color:#000\n style B fill:#bbf,color:#000\n style C fill:#bbf,color:#000\n style D fill:#bbf,color:#000\n style E fill:#bbf,color:#000\n```\n\n| 指标名称 | 用途 | 资料来源 |\n|----------|------|----------|\n| Task Completion | 评估 Agent 是否完成目标 | [task_completion.py]() |\n| Tool Correctness | 检查工具调用正确性 | README.md |\n| Goal Accuracy | 衡量目标达成准确度 | README.md |\n| Step Efficiency | 评估步骤效率 | README.md |\n| Plan Adherence | 检查计划执行情况 | README.md |\n| Plan Quality | 评估计划质量 | README.md |\n| Tool Use | 测量工具使用质量 | README.md |\n| Argument Correctness | 验证工具参数正确性 | README.md |\n\n资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()、[README.md]()\n\n## 指标使用方式\n\n### 与 Pytest 集成\n\n通过 `@assert_test` 装饰器实现与 Pytest 的深度集成，这是 DeepEval 推荐的评估方式。资料来源：[README.md]()\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\n@pytest.mark.parametrize(\n \"test_case\",\n [LLMTestCase(input=\"...\", actual_output=\"...\", expected_output=\"...\")],\n)\n@assert_test\ndef test_correctness(test_case):\n correctness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n return correctness_metric\n```\n\n### 独立评估模式\n\n在 Jupyter Notebook 或脚本环境中，可以使用独立的 `evaluate()` 函数进行评估。资料来源：[README.md]()\n\n```python\nfrom deepeval import evaluate\nfrom deepeval.metrics import AnswerRelevancyMetric\nfrom deepeval.test_case import LLMTestCase\n\nanswer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"We offer a 30-day full refund at no extra costs.\",\n retrieval_context=[\"All customers are eligible for a 30 day full refund\"]\n)\nevaluate([test_case], [answer_relevancy_metric])\n```\n\n### 追踪评估模式\n\n使用 `evals_iterator()` 实现端到端追踪评估，适用于框架集成场景。资料来源：[deepeval/integrations/README.md]()\n\n```python\nfrom deepeval.tracing import observe\nfrom deepeval.metrics import TaskCompletionMetric\n\n@observe(metrics=[TaskCompletionMetric()])\ndef app(input: str):\n # Agent 逻辑\n return result\n\nfor golden in dataset.evals_iterator():\n app(golden.input)\n```\n\n## 指标结果解读\n\n### 评分机制\n\n所有指标分数统一在 0-1 范围内，阈值参数决定测试是否通过。资料来源：[README.md]()\n\n| 分数范围 | 含义 | 行为 |\n|----------|------|------|\n| 0.0-0.5 | 低质量输出 | 通常不满足阈值 |\n| 0.5-0.7 | 中等质量 | 取决于阈值设置 |\n| 0.7-1.0 | 高质量输出 | 通常满足阈值 |\n\n### Reason 字段\n\n每个指标在评估后会生成 `reason` 字段，提供 LLM 评判的详细解释，便于调试和理解评估逻辑。资料来源：[deepeval/metrics/base_metric.py]()\n\n```python\nprint(metric.score) # 0.85\nprint(metric.reason) # \"The response correctly addresses the user's question...\"\n```\n\n## 集成框架支持\n\nDeepEval 指标体系支持多种主流 LLM 应用框架的集成评估。资料来源：[deepeval/integrations/README.md]()\n\n| 框架 | 集成方式 | 评估模式 |\n|------|----------|----------|\n| OpenAI | 原生追踪 | Bare + @observe + evals_iterator |\n| Anthropic | 原生追踪 | Bare + @observe + evals_iterator |\n| LangChain | CallbackHandler | evals_iterator |\n| LangGraph | CallbackHandler | evals_iterator |\n| LlamaIndex | AsyncConfig | evals_iterator |\n| CrewAI | instrument_crewai() | evals_iterator |\n| Pydantic AI | 集成 | evals_iterator |\n| Google ADK | instrument_google_adk() | evals_iterator |\n| Strands | instrument_strands() | evals_iterator |\n| AWS AgentCore | instrument_agentcore() | evals_iterator |\n\n资料来源：[deepeval/integrations/README.md]()\n\n## 最佳实践\n\n### 指标选择指南\n\n| 应用场景 | 推荐指标组合 |\n|----------|--------------|\n| RAG 流水线 | AnswerRelevancy + Faithfulness |\n| AI Agent | TaskCompletion + ToolCorrectness |\n| 通用对话 | GEval（自定义标准）|\n| 多轮对话 | Conversational Metrics |\n\n### 阈值设置建议\n\n1. **保守设置**：threshold=0.7 适用于生产环境，确保高质量输出\n2. **宽松设置**：threshold=0.5 适用于开发阶段，快速迭代\n3. **渐进调整**：根据历史评估结果逐步调整阈值\n\n### 环境变量配置\n\nDeepEval 自动加载环境变量，优先级为：进程环境变量 > .env.local > .env。可通过 `DEEPEVAL_DISABLE_DOTENV=1` 禁用自动加载。资料来源：[README.md]()\n\n## 扩展开发\n\n开发者可以通过继承 `BaseMetric` 基类创建自定义评估指标：\n\n```python\nfrom deepeval.metrics.base_metric import BaseMetric\nfrom deepeval.test_case import LLMTestCase\n\nclass CustomMetric(BaseMetric):\n def __init__(self, threshold: float = 0.5):\n self.threshold = threshold\n \n def measure(self, test_case: LLMTestCase) -> float:\n # 自定义评估逻辑\n score = self._evaluate(test_case)\n self.score = score\n return score\n```\n\n资料来源：[deepeval/metrics/base_metric.py]()\n\n## 总结\n\nDeepEval 的评估指标体系提供了从通用到专用的完整评估能力，通过模块化设计支持灵活组合和扩展。G-Eval 作为核心评估框架，结合 RAG 和 Agentic 专用指标，能够全面覆盖各类 LLM 应用的评估需求。开发者可以根据具体场景选择合适的指标组合，并通过 Pytest 集成、独立调用或追踪模式等多种方式执行评估。\n\n---\n\n\n\n## 评估执行引擎\n\n### 相关页面\n\n相关主题：[测试用例定义](#page-test-cases), [评估指标体系](#page-metrics), [追踪系统](#page-tracing-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/evaluate/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/__init__.py)\n- [deepeval/evaluate/evaluate.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/evaluate.py)\n- [deepeval/evaluate/api.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/api.py)\n- [deepeval/evaluate/execute/e2e.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/e2e.py)\n- [deepeval/evaluate/execute/agentic.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/agentic.py)\n- [deepeval/evaluate/console_report.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/console_report.py)\n- [deepeval/evaluate/configs.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/configs.py)\n \n\n# 评估执行引擎\n\n## 概述\n\n评估执行引擎是 DeepEval 框架的核心组件，负责驱动 LLM 应用的质量评估流程。它封装了评估的完整生命周期，包括测试用例加载、指标计算、结果收集与报告生成。该引擎支持两种主要的评估模式：端到端评估（E2E）和代理式评估（Agentic），能够适应不同的测试场景和集成需求。资料来源：[README.md]()\n\n```mermaid\ngraph TD\n A[评估执行引擎] --> B[端到端评估 E2E]\n A --> C[代理式评估 Agentic]\n B --> D[Test Case 加载]\n B --> E[指标计算]\n B --> F[结果收集]\n C --> G[Trace 追踪]\n C --> H[Span 跨度]\n C --> I[工具调用验证]\n```\n\n## 核心架构\n\n### 模块组织结构\n\n评估执行引擎的代码位于 `deepeval/evaluate/` 目录下，采用分层架构设计：\n\n| 模块路径 | 功能职责 |\n|---------|---------|\n| `__init__.py` | 公共 API 导出 |\n| `evaluate.py` | 核心评估入口函数 |\n| `api.py` | 评估 API 接口定义 |\n| `execute/e2e.py` | 端到端评估执行器 |\n| `execute/agentic.py` | 代理式评估执行器 |\n| `console_report.py` | 控制台报告生成 |\n| `configs.py` | 评估配置管理 |\n\n### 评估入口函数\n\n评估执行引擎的主入口是 `evaluate()` 函数，支持同步和异步两种调用模式。开发者可以通过该函数批量执行测试用例并获取评估结果。资料来源：[deepeval/evaluate/__init__.py]()\n\n```python\nfrom deepeval import evaluate\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase\n\n# 创建评估指标\ncorrectness_metric = GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct based on the 'expected output'.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n)\n\n# 创建测试用例\ntest_case = LLMTestCase(\n input=\"What if these shoes don't fit?\",\n actual_output=\"You have 30 days to get a full refund at no extra cost.\",\n expected_output=\"We offer a 30-day full refund at no extra costs.\"\n)\n\n# 执行评估\nevaluate([test_case], [correctness_metric])\n```\n\n## 评估模式\n\n### 端到端评估（E2E）\n\n端到端评估将 LLM 应用视为黑盒，通过输入输出对进行质量验证。这种模式特别适用于快速迭代开发和回归测试场景，无需深入了解应用内部实现。资料来源：[deepeval/evaluate/execute/e2e.py]()\n\n**工作流程：**\n\n```mermaid\ngraph LR\n A[输入 TestCase] --> B[加载指标]\n B --> C[执行指标评估]\n C --> D[收集评分]\n D --> E[生成报告]\n```\n\n端到端评估的核心流程如下：\n\n1. 接收 `LLMTestCase` 测试用例对象\n2. 初始化指定的评估指标\n3. 按顺序或并发执行各项指标计算\n4. 汇总所有指标得分\n5. 与阈值比较判断通过/失败\n6. 生成结构化结果输出\n\n### 代理式评估（Agentic）\n\n代理式评估针对 AI 代理应用设计，不仅验证最终输出，还追踪整个执行过程，包括工具调用、决策路径和中间状态。这种模式适用于复杂的多步骤任务评估。资料来源：[deepeval/evaluate/execute/agentic.py]()\n\n**追踪机制：**\n\n代理式评估利用 OpenTelemetry 标准的 Trace 和 Span 来记录执行轨迹。每个代理操作被封装为独立的 Span，通过父-子关系形成完整的调用链。这种设计允许评估引擎回溯任意时间点的执行状态，并针对特定操作进行指标验证。\n\n```python\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\n# 使用 trace 上下文包装评估\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n## 配置系统\n\n### 评估配置类\n\nDeepEval 提供 `EvaluationConfig` 类用于定制评估行为，支持细粒度的执行控制。资料来源：[deepeval/evaluate/configs.py]()\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `run_async` | bool | 是否启用异步执行模式 |\n| `max_concurrent` | int | 最大并发评估数 |\n| `use_cached_results` | bool | 是否使用缓存的评估结果 |\n| `print_results` | bool | 是否在控制台打印结果 |\n| `save_results` | bool | 是否保存评估结果到文件 |\n\n### 异步配置\n\n对于需要处理大量测试用例的场景，引擎支持异步并发执行。通过 `AsyncConfig` 类可以控制并发度和超时行为。资料来源：[deepeval/evaluate/configs.py]()\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\n\nasync_config = AsyncConfig(\n run_async=True,\n max_concurrent=10, # 最大并发任务数\n timeout=300 # 单个任务超时时间（秒）\n)\n```\n\n## 报告生成\n\n### 控制台报告\n\n评估完成后，引擎自动生成控制台报告，包含测试用例总数、通过率、各指标得分分布等关键信息。资料来源：[deepeval/evaluate/console_report.py]()\n\n**报告内容包括：**\n\n- 整体通过率统计\n- 各指标得分详情\n- 失败用例的错误信息\n- 执行耗时分析\n- 资源使用情况（如适用）\n\n### 结构化输出\n\n评估结果以标准化的数据结构返回，便于后续分析和集成：\n\n```python\nresult = evaluate([test_case], [correctness_metric])\n\n# 结果对象包含以下属性\nprint(result.success) # 整体是否通过\nprint(result.metrics) # 各指标得分\nprint(result.duration) # 执行耗时\nprint(result.error) # 错误信息（如有）\n```\n\n## 集成方式\n\n### Pytest 集成\n\nDeepEval 与 Pytest 无缝集成，通过 `@assert_test` 装饰器将评估逻辑嵌入标准测试用例。资料来源：[README.md]()\n\n```python\nimport pytest\nfrom deepeval import assert_test\nfrom deepeval.metrics import GEval\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\n@pytest.fixture\ndef correctness_metric():\n return GEval(\n name=\"Correctness\",\n criteria=\"Determine if the 'actual output' is correct.\",\n evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],\n threshold=0.5\n )\n\n@assert_test(assertion_fn=correctness_metric)\ndef test_chatbot_response(test_case: LLMTestCase):\n return test_case\n```\n\n### 框架集成\n\n评估引擎支持主流 LLM 框架的自动检测和集成，包括 OpenAI、Anthropic、LangChain、LangGraph、LlamaIndex、Pydantic AI、CrewAI 等。资料来源：[deepeval/integrations/README.md]()\n\n**集成特性矩阵：**\n\n| 框架 | Bare 模式 | @observe 包装 | evals_iterator | pytest 集成 |\n|------|-----------|--------------|----------------|-------------|\n| OpenAI | ✅ | ✅ | ✅ | ✅ |\n| Anthropic | ✅ | ✅ | ✅ | ✅ |\n| LangChain | ✅ | ✅ | ✅ | ✅ |\n| LangGraph | ✅ | ✅ | ✅ | ✅ |\n| LlamaIndex | ✅ | ✅ | ✅ | ✅ |\n| Pydantic AI | ✅ | ✅ | ✅ | ✅ |\n| CrewAI | ✅ | ✅ | ✅ | ✅ |\n\n## CLI 命令行支持\n\n评估执行引擎可通过 `deepeval` CLI 调用，支持自动化测试运行和结果持久化。资料来源：[deepeval/cli/main.py]()\n\n**常用命令：**\n\n```bash\n# 运行测试文件\ndeepeval test run test_chatbot.py\n\n# 运行特定测试函数\ndeepeval test run test_chatbot.py::test_case\n\n# 指定报告输出目录\ndeepeval test run test_chatbot.py --folder ./results\n\n# 登录 Confident AI 平台同步结果\ndeepeval login\ndeepeval test run test_chatbot.py\n```\n\n## 执行流程图\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant E as 评估引擎\n participant M as 指标模块\n participant R as 报告生成器\n\n U->>E: evaluate(test_cases, metrics)\n E->>E: 初始化评估配置\n E->>M: 加载评估指标\n loop 每个测试用例\n E->>M: 执行指标计算\n M-->>E: 返回指标得分\n E->>E: 与阈值比较\n end\n E->>R: 生成评估报告\n R-->>U: 返回评估结果\n```\n\n## 最佳实践\n\n### 性能优化建议\n\n1. **批量评估**：将多个相关测试用例一起评估，减少 LLM 调用开销\n2. **并发控制**：根据 API 速率限制调整 `max_concurrent` 参数\n3. **指标选择**：仅使用必要的评估指标，避免不必要的计算\n4. **缓存利用**：在迭代开发中使用 `use_cached_results` 跳过未变更用例\n\n### 测试设计原则\n\n1. **单一职责**：每个测试用例应验证单一质量维度\n2. **明确阈值**：为每个指标设置合理的通过阈值\n3. **真实数据**：使用生产环境分布的测试数据\n4. **分层评估**：结合端到端和代理式评估全面覆盖\n\n## 扩展机制\n\n评估执行引擎支持自定义扩展，开发者可以实现以下接口：\n\n- **自定义指标**：继承 `BaseMetric` 类实现特定领域的评估逻辑\n- **自定义报告器**：实现 `BaseReporter` 接口添加新的输出格式\n- **自定义集成**：通过回调机制接入新的 LLM 框架\n\n---\n\n*本文档基于 DeepEval v0.2+ 版本编写，随着框架更新，部分 API 可能发生变化。*\n\n---\n\n\n\n## 数据集管理\n\n### 相关页面\n\n相关主题：[合成数据生成](#page-synthetic-data), [测试用例定义](#page-test-cases)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/dataset/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/__init__.py)\n- [deepeval/dataset/dataset.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/dataset.py)\n- [deepeval/dataset/golden.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/golden.py)\n- [deepeval/dataset/api.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/api.py)\n- [deepeval/dataset/test_run_tracer.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/test_run_tracer.py)\n- [deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)\n- [deepeval/synthesizer/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/__init__.py)\n\n \n\n# 数据集管理\n\n## 概述\n\nDeepEval 的数据集管理模块是整个 LLM 评估框架的核心基础设施，负责管理和组织用于评估大型语言模型应用的测试数据。该模块支持多种数据格式导入、测试用例的组织与管理、以及与 Confident AI 平台的同步功能。\n\n数据集管理的主要职责包括：\n\n- **测试用例管理**：创建、组织和管理 `LLMTestCase` 对象\n- **迭代器功能**：通过 `evals_iterator()` 遍历数据集并执行评估\n- **Golden 数据集**：管理高质量的参考数据集（goldens）用于评估\n- **评估结果追踪**：记录和回溯每次评估运行的结果\n\n## 核心组件\n\n### LLMTestCase\n\n`LLMTestCase` 是 DeepEval 中用于定义单个测试用例的基础数据模型。每个测试用例包含输入、期望输出和实际输出等关键字段。\n\n```python\nfrom deepeval.test_case import LLMTestCase, SingleTurnParams\n\ntest_case = LLMTestCase(\n input=\"用户输入内容\",\n actual_output=\"LLM实际输出\",\n expected_output=\"期望的正确答案\",\n retrieval_context=[\"上下文文档1\", \"上下文文档2\"]\n)\n```\n\n**主要参数说明：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `input` | str | 是 | 传入 LLM 应用的输入/提示词 |\n| `actual_output` | str | 是 | LLM 应用的真实输出 |\n| `expected_output` | str | 否 | 期望的参考答案 |\n| `retrieval_context` | List[str] | 否 | RAG 场景中的检索上下文 |\n| `context` | List[str] | 否 | 一般上下文信息 |\n\n### Golden 数据集\n\nGolden 数据集是经过精心准备的高质量参考数据集，用于验证 LLM 应用的输出质量。\n\n```python\nfrom deepeval.synthesizer import Synthesizer\n\nsynthesizer = Synthesizer(model=model)\nsynthesizer.generate_goldens_from_docs(\n document_paths=[\"path/to/doc.pdf\"],\n include_expected_output=True,\n max_goldens_per_context=5\n)\n```\n\n## 数据集迭代与评估\n\n### evals_iterator 方法\n\n`evals_iterator()` 是数据集的核心迭代方法，支持在遍历数据集的同时执行评估。该方法与各种框架集成兼容，支持端到端和组件级别的评估。\n\n```python\nfrom deepeval.metrics import TaskCompletionMetric\n\n# 端到端评估\nfor golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):\n invoke({\"prompt\": golden.input})\n```\n\n### 异步评估配置\n\nDeepEval 支持异步评估模式，适用于大规模数据集的高效处理：\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\nfrom deepeval.metrics import TaskCompletionMetric\n\nasync_config = AsyncConfig(run_async=True, max_concurrent=10)\n\nfor golden in dataset.evals_iterator(\n async_config=async_config,\n metrics=[TaskCompletionMetric()],\n):\n task = asyncio.create_task(agent.run(golden.input))\n dataset.evaluate(task)\n```\n\n### 异步配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `run_async` | bool | False | 启用异步模式 |\n| `max_concurrent` | int | 1 | 最大并发任务数 |\n| `timeout` | int | None | 单个任务超时时间（秒） |\n\n## 框架集成\n\n### OpenAI 集成\n\n```python\nfrom deepeval.anthropic import Anthropic\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\nclient = Anthropic()\n\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n### LangChain 集成\n\n```python\nfrom deepeval.integrations.langchain import CallbackHandler\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator():\n llm.invoke(\n golden.input,\n config={\"callbacks\": [CallbackHandler(metrics=[TaskCompletionMetric()])]},\n )\n```\n\n### LangGraph 集成\n\n```python\nfrom deepeval.integrations.langchain import CallbackHandler\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator():\n agent.invoke(\n {\"messages\": [{\"role\": \"user\", \"content\": golden.input}]},\n config={\"callbacks\": [CallbackHandler(metrics=[TaskCompletionMetric()])]},\n )\n```\n\n### LlamaIndex 集成\n\n```python\nimport asyncio\nfrom deepeval.evaluate.configs import AsyncConfig\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator(\n async_config=AsyncConfig(run_async=True),\n metrics=[TaskCompletionMetric()],\n):\n task = asyncio.create_task(agent.run(golden.input))\n dataset.evaluate(task)\n```\n\n## 数据集生成\n\nDeepEval 提供多种方式生成测试数据集：\n\n| 生成方法 | 说明 | 适用场景 |\n|---------|------|---------|\n| `DOCS` | 从文档中提取 | 已有知识库文档 |\n| `CONTEXTS` | 从上下文中生成 | 结构化上下文数据 |\n| `SCRATCH` | 从零开始生成 | 无预定义数据 |\n| `GOLDENS` | 基于现有数据扩展 | 已有少量高质量数据 |\n\n### 单轮与多轮变体\n\n数据集支持单轮（Single Turn）和多轮（Multi-turn Conversational）两种评估模式：\n\n```python\nfrom deepeval.cli.generate.utils import GoldenVariation\n\n# 单轮评估\nsynthesizer.generate_goldens_from_docs(\n document_paths=document_paths,\n include_expected_output=True\n)\n\n# 多轮对话评估\nsynthesizer.generate_conversational_goldens_from_docs(\n document_paths=document_paths,\n include_expected_outcome=True\n)\n```\n\n## 评估工作流\n\n```mermaid\ngraph TD\n A[准备数据集] --> B[创建 LLMTestCase]\n B --> C[配置评估指标]\n C --> D[使用 evals_iterator 遍历]\n D --> E{框架类型}\n E -->|LangChain| F[CallbackHandler]\n E -->|OpenAI| G[trace 上下文]\n E -->|LlamaIndex| H[AsyncConfig]\n F --> I[执行评估]\n G --> I\n H --> I\n I --> J[记录测试结果]\n J --> K[同步至 Confident AI]\n```\n\n## 测试运行追踪\n\n### Test Run Tracer\n\n`TestRunTracer` 负责记录每次评估运行的关键信息，包括：\n\n- 测试用例执行状态\n- 评估指标得分\n- 执行时间和资源消耗\n- 错误和异常信息\n\n### 评估结果保存\n\n评估结果可以通过 `deepeval test run` 命令自动保存：\n\n```bash\ndeepeval test run test_chatbot.py\n```\n\n结果文件格式为 `test_run_*.json`，可通过 `deepeval inspect` 命令查看：\n\n```bash\ndeepeval inspect # 查看最新运行结果\ndeepeval inspect path/to/file.json # 查看指定文件\ndeepeval inspect -f ./results # 查看指定目录\n```\n\n## 配置管理\n\n### 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `DEEPEVAL_RESULTS_FOLDER` | 评估结果保存目录 |\n| `DEEPEVAL_API_KEY` | Confident AI API 密钥 |\n\n### .env 配置\n\nDeepEval 支持 `.env.local` 文件进行本地配置：\n\n```bash\ncp .env.example .env.local\n# 编辑 .env.local 文件\n```\n\n## 与 Confident AI 集成\n\nDeepEval 数据集管理与 Confident AI 平台深度集成，提供以下云端功能：\n\n- **数据集存储**：云端存储和管理测试数据集\n- **评估报告**：生成可分享的评估报告\n- **迭代追踪**：比较不同版本的 LLM 应用表现\n- **协作功能**：团队成员共享和协作测试数据集\n\n登录命令：\n\n```bash\ndeepeval login\n```\n\n## 最佳实践\n\n1. **数据集质量**：确保 Golden 数据集包含多样化、高质量的测试用例\n2. **评估指标选择**：根据应用场景选择合适的评估指标\n3. **异步处理**：大规模数据集建议使用异步模式提高效率\n4. **结果回溯**：定期保存和审查评估结果用于持续优化\n5. **框架集成**：选择最适合你技术栈的框架集成方式\n\n---\n\n\n\n## 合成数据生成\n\n### 相关页面\n\n相关主题：[数据集管理](#page-dataset-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/synthesizer/synthesizer.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/synthesizer.py)\n- [deepeval/synthesizer/base_synthesizer.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/base_synthesizer.py)\n- [deepeval/synthesizer/schema.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/schema.py)\n- [deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)\n- [deepeval/synthesizer/config.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/config.py)\n \n\n# 合成数据生成\n\n## 概述\n\n合成数据生成（Synthetic Data Generation）是 DeepEval 框架中用于自动创建测试用例的核心功能。该功能通过 LLM 自动生成高质量的测试数据，包括单轮问答和多轮对话场景，帮助开发者快速构建评估数据集。\n\nSynthesizer（合成器）是实现这一功能的核心类，它封装了多种生成策略，支持从文档、上下文、已有测试用例或完全空白状态生成合成数据。资料来源：[deepeval/synthesizer/synthesizer.py:1-50]()\n\n## 核心架构\n\n### 类结构\n\n```mermaid\ngraph TD\n A[Synthesizer] --> B[BaseSynthesizer]\n B --> C[可配置生成策略]\n B --> D[异步/同步模式]\n A --> E[ContextConstructionConfig]\n A --> F[StylingConfig]\n A --> G[ConversationalStylingConfig]\n```\n\n### 数据模型\n\n合成数据生成涉及以下核心数据模型：\n\n| 模型类 | 用途 | 关键属性 |\n|--------|------|----------|\n| `GoldenContext` | 单轮对话上下文 | `input`, `expected_output`, `context` |\n| `ScenarioContext` | 多轮对话场景 | `scenario`, `conversational_task`, `participant_roles` |\n| `ConversationTurn` | 单轮对话 | `input`, `expected_output` |\n| `ConversationRound` | 多轮对话 | `turns`, `expected_outcome` |\n\n资料来源：[deepeval/synthesizer/schema.py:1-100]()\n\n## 生成方法\n\n### 四种生成策略\n\nDeepEval 支持四种主要的合成数据生成方法：\n\n| 方法 | 枚举值 | 描述 |\n|------|--------|------|\n| 文档生成 | `GenerationMethod.DOCS` | 从源文档中提取上下文并生成测试用例 |\n| 上下文生成 | `GenerationMethod.CONTEXTS` | 基于预定义的上下文生成测试用例 |\n| 从零生成 | `GenerationMethod.SCRATCH` | 无外部输入，完全由 LLM 创意生成 |\n| Goldens 扩展 | `GenerationMethod.GOLDENS` | 基于已有测试用例进行变体扩展 |\n\n资料来源：[deepeval/cli/generate/command.py:1-80]()\n\n### 单轮与多轮对话\n\n```mermaid\ngraph LR\n A[生成请求] --> B{对话类型}\n B -->|单轮| C[GoldenVariation.SINGLE_TURN]\n B -->|多轮| D[GoldenVariation.CONVERSATIONAL]\n C --> E[generate_goldens_from_*]\n D --> F[generate_conversational_goldens_from_*]\n```\n\n| 变体类型 | 枚举值 | 生成方法 |\n|----------|--------|----------|\n| 单轮对话 | `GoldenVariation.SINGLE_TURN` | `generate_goldens_from_docs/contexts/scratch/goldens` |\n| 多轮对话 | `GoldenVariation.CONVERSATIONAL` | `generate_conversational_goldens_from_*` |\n\n## Synthesizer 类\n\n### 主要方法\n\n| 方法名 | 参数 | 返回值 | 说明 |\n|--------|------|--------|------|\n| `generate_goldens_from_docs()` | `document_paths`, `context_construction_config` | `List[GoldenContext]` | 从文档生成单轮测试用例 |\n| `generate_conversational_goldens_from_docs()` | `document_paths`, `context_construction_config` | `List[ScenarioContext]` | 从文档生成多轮测试用例 |\n| `generate_goldens_from_contexts()` | `contexts`, `max_goldens_per_context` | `List[GoldenContext]` | 从上下文生成单轮测试用例 |\n| `generate_goldens_from_scratch()` | `num_goldens` | `List[GoldenContext]` | 从零生成单轮测试用例 |\n| `generate_goldens_from_goldens()` | `goldens`, `max_goldens_per_golden` | `List[GoldenContext]` | 扩展已有测试用例 |\n| `save_as()` | `file_type`, `directory`, `file_name` | `str` | 保存结果到文件 |\n\n资料来源：[deepeval/synthesizer/synthesizer.py:100-300]()\n\n### 初始化参数\n\n```python\nSynthesizer(\n model: Optional[Any] = None, # 使用的 LLM 模型\n async_mode: bool = False, # 是否启用异步模式\n max_concurrent: int = 10, # 最大并发数\n styling_config: Optional[Any] = None, # 单轮样式配置\n conversational_styling_config: Optional[Any] = None, # 多轮样式配置\n cost_tracking: bool = True # 是否跟踪成本\n)\n```\n\n## 配置选项\n\n### ContextConstructionConfig\n\n用于配置文档分块和上下文构建：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `max_contexts_per_document` | `int` | `10` | 每个文档最多生成的上下文数 |\n| `min_contexts_per_document` | `int` | `1` | 每个文档最少生成的上下文数 |\n| `chunk_size` | `int` | `1000` | 文档分块大小 |\n| `chunk_overlap` | `int` | `200` | 分块重叠大小 |\n| `context_quality_threshold` | `float` | `0.5` | 上下文质量阈值 |\n| `context_similarity_threshold` | `float` | `0.7` | 上下文相似度阈值 |\n| `max_retries` | `int` | `3` | 最大重试次数 |\n\n资料来源：[deepeval/cli/generate/command.py:80-120]()\n\n### 样式配置\n\n#### 单轮样式配置 (StylingConfig)\n\n```python\nsingle_turn_styling_config(\n scenario: Optional[str] = None, # 场景描述\n task: Optional[str] = None, # 任务描述\n input_format: Optional[str] = None, # 输入格式模板\n expected_output_format: Optional[str] = None # 期望输出格式\n)\n```\n\n#### 多轮样式配置 (ConversationalStylingConfig)\n\n```python\nmulti_turn_styling_config(\n scenario_context: Optional[str] = None, # 场景上下文\n conversational_task: Optional[str] = None, # 对话任务描述\n participant_roles: Optional[List[str]] = None, # 参与者角色\n scenario_format: Optional[str] = None, # 场景格式模板\n expected_outcome_format: Optional[str] = None # 期望结果格式\n)\n```\n\n## CLI 命令\n\n### generate 命令\n\n```bash\ndeepeval generate \\\n --method \\\n --variation \\\n --output-dir ./output \\\n --file-name my_goldens\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `--method` | 枚举 | 是 | 生成方法 |\n| `--variation` | 枚举 | 是 | 对话类型 |\n| `--output-dir` | 路径 | 否 | 输出目录 |\n| `--file-name` | 字符串 | 否 | 输出文件名 |\n| `--file-type` | 枚举 | 否 | 输出格式 (json/csv) |\n| `--num-goldens` | 整数 | 条件必需 | 从零生成时的数量 |\n| `--documents` | 文件路径 | 条件必需 | 文档生成时的源文件 |\n| `--contexts-file` | 文件路径 | 条件必需 | 上下文生成时的文件 |\n| `--goldens-file` | 文件路径 | 条件必需 | Goldens 扩展时的输入 |\n| `--model` | 字符串 | 否 | 使用的模型 |\n| `--async-mode` | 布尔 | 否 | 启用异步模式 |\n| `--max-concurrent` | 整数 | 否 | 最大并发数 |\n\n资料来源：[deepeval/cli/generate/command.py:40-200]()\n\n## 生成流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as CLI 命令\n participant Synth as Synthesizer\n participant LLM as LLM API\n participant FS as 文件系统\n\n User->>CLI: deepeval generate --method DOCS\n CLI->>Synth: 创建 Synthesizer 实例\n Synth->>LLM: 请求生成测试用例\n LLM-->>Synth: 返回生成的 goldens\n Synth->>Synth: 应用样式配置\n Synth->>FS: save_as() 保存结果\n FS-->>User: 输出文件\n```\n\n## 使用示例\n\n### 从文档生成单轮测试用例\n\n```python\nfrom deepeval.synthesizer import Synthesizer\nfrom deepeval.synthesizer.config import ContextConstructionConfig\n\nsynthesizer = Synthesizer()\n\nconfig = ContextConstructionConfig(\n chunk_size=1000,\n chunk_overlap=200,\n max_contexts_per_document=5\n)\n\ngoldens = synthesizer.generate_goldens_from_docs(\n document_paths=[\"./docs/guide.md\"],\n context_construction_config=config\n)\n\noutput_path = synthesizer.save_as(\n file_type=\"json\",\n directory=\"./output\",\n file_name=\"my_goldens\"\n)\n```\n\n### 从零生成多轮对话\n\n```python\nfrom deepeval.synthesizer import Synthesizer\nfrom deepeval.cli.generate.utils import GoldenVariation\n\nsynthesizer = Synthesizer(async_mode=True)\n\nscenarios = synthesizer.generate_conversational_goldens_from_scratch(\n num_goldens=50\n)\n\nsynthesizer.save_as(\n file_type=\"json\",\n directory=\"./output\",\n file_name=\"conversational_scenarios\"\n)\n```\n\n### 扩展已有测试用例\n\n```python\nsynthesizer = Synthesizer()\n\nexpanded_goldens = synthesizer.generate_goldens_from_goldens(\n goldens=existing_goldens,\n max_goldens_per_golden=3,\n include_expected_output=True\n)\n```\n\n## 懒加载机制\n\nSynthesizer 和 ContextConstructionConfig 使用 Python 的 `__getattr__` 机制实现懒加载：\n\n```python\ndef __getattr__(name: str) -> Any:\n if name == \"Synthesizer\":\n from deepeval.synthesizer import Synthesizer\n globals()[\"Synthesizer\"] = Synthesizer\n return Synthesizer\n if name == \"ContextConstructionConfig\":\n from deepeval.synthesizer.config import ContextConstructionConfig\n globals()[\"ContextConstructionConfig\"] = ContextConstructionConfig\n return ContextConstructionConfig\n raise AttributeError(f\"module {__name__!r} has no attribute {name!r}\")\n```\n\n这种设计确保了：\n- 未使用生成功能的命令不会加载重型依赖\n- 测试可以方便地通过 monkeypatch 替换模拟对象\n- 模块级别的属性访问保持一致\n\n资料来源：[deepeval/cli/generate/command.py:25-45]()\n\n## 输出格式\n\n### JSON 格式\n\n```json\n{\n \"goldens\": [\n {\n \"input\": \"用户问题\",\n \"expected_output\": \"期望回答\",\n \"context\": [\"上下文片段1\", \"上下文片段2\"]\n }\n ]\n}\n```\n\n### CSV 格式\n\n| input | expected_output | context |\n|-------|-----------------|---------|\n| 用户问题 | 期望回答 | 上下文片段 |\n\n## 最佳实践\n\n1. **文档质量**：使用结构清晰、内容丰富的源文档可提高生成质量\n2. **上下文阈值**：根据文档长度调整 `context_quality_threshold` 和 `context_similarity_threshold`\n3. **并发控制**：在 API 限流较严的环境中，适当降低 `max_concurrent`\n4. **异步模式**：处理大量数据时启用 `async_mode=True` 提高效率\n5. **成本跟踪**：生产环境建议启用 `cost_tracking=True` 监控 API 消耗\n\n---\n\n\n\n## 追踪系统\n\n### 相关页面\n\n相关主题：[评估执行引擎](#page-evaluate-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [deepeval/tracing/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/__init__.py)\n- [deepeval/tracing/tracing.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/tracing.py)\n- [deepeval/tracing/context.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/context.py)\n- [deepeval/tracing/api.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/api.py)\n- [deepeval/tracing/otel/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/otel/__init__.py)\n- [deepeval/tracing/offline_evals/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/offline_evals/__init__.py)\n \n\n# 追踪系统\n\n## 概述\n\nDeepEval 追踪系统（Tracing System）是用于监控、记录和分析 LLM 应用执行过程的组件化框架。该系统提供了端到端的可观测性能力，使开发者能够追踪 LLM 应用的调用链、执行步骤和性能指标。追踪系统与 DeepEval 的评估指标（如 `TaskCompletionMetric`、`GEval` 等）深度集成，支持在追踪过程中自动执行评估任务。\n\n追踪系统的核心设计理念是将 LLM 应用视为黑盒，通过装饰器（`@observe`）和上下文管理器（`with trace(...)`）自动捕获执行过程中的关键信息，并将这些信息用于后续的评估分析。\n\n## 核心组件\n\n### 1. 追踪上下文管理器\n\n追踪系统使用 `trace()` 上下文管理器来创建追踪范围。当代码在 `with trace(...)` 块内执行时，所有子调用的追踪数据都会被自动收集并关联到同一个追踪会话中。\n\n```python\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": golden.input}],\n )\n```\n\n### 2. 观察装饰器\n\n`@observe()` 装饰器用于将普通函数转换为可追踪的组件。当函数被装饰后，其输入输出和执行上下文会自动被记录。\n\n```python\nfrom deepeval.tracing import observe, update_current_span\nfrom deepeval.test_case import LLMTestCase\n\n@observe()\ndef inner_component(input: str):\n output = \"result\"\n update_current_span(test_case=LLMTestCase(input=input, actual_output=output))\n return output\n\n@observe()\ndef app(input: str):\n return inner_component(input)\n```\n\n### 3. 跨度更新函数\n\n`update_current_span()` 和 `update_current_trace()` 函数允许在追踪上下文中手动更新当前跨度或追踪的信息。这对于在特定位置注入测试用例、指标或其他元数据非常有用。\n\n## 架构设计\n\n### 追踪系统架构图\n\n```mermaid\ngraph TD\n subgraph \"应用层\"\n A[LLM 应用代码]\n B[@observe 装饰器]\n C[trace 上下文管理器]\n end\n\n subgraph \"追踪核心\"\n D[TraceManager]\n E[ContextManager]\n F[SpanProcessor]\n end\n\n subgraph \"数据导出层\"\n G[ConfidentSpanExporter]\n H[OTel SpanProcessor]\n I[ContextAwareSpanProcessor]\n end\n\n subgraph \"评估引擎\"\n J[Metrics Engine]\n K[TaskCompletionMetric]\n L[Offline Evals]\n end\n\n A --> B\n A --> C\n B --> D\n C --> D\n D --> E\n D --> F\n F --> G\n F --> I\n I --> H\n D --> J\n J --> K\n J --> L\n```\n\n### 追踪上下文路由\n\n追踪系统支持两种追踪模式：原生追踪模式和 OTel（OpenTelemetry）模式。`ContextAwareSpanProcessor` 是关键的路由组件，它能够根据当前上下文自动决定数据导出路径。\n\n```mermaid\ngraph LR\n A[追踪上下文活跃] --> B{评估状态检查}\n B -->|trace_manager.is_evaluating = True| C[路由至 REST]\n B -->|trace_manager.is_evaluating = False| D[路由至 OTLP]\n C --> E[ConfidentSpanExporter]\n D --> F[OTLP Exporter]\n```\n\n## 框架集成\n\n追踪系统提供了与多种主流 LLM 框架的集成能力。集成通过自动创建追踪上下文和使用回调处理器来实现。\n\n### 集成能力矩阵\n\n| 框架 | Bare 模式追踪 | @observe 支持 | evals_iterator 支持 | deepeval test run |\n|------|--------------|--------------|---------------------|-------------------|\n| OpenAI | ✅ | ✅ | ✅ | ✅ |\n| Anthropic | ✅ | ✅ | ✅ | ✅ |\n| LangChain | ✅ | ✅ | ✅ | ✅ |\n| LangGraph | ✅ | ✅ | ✅ | ✅ |\n| Pydantic AI | ✅ | ✅ | ✅ | ✅ |\n| LlamaIndex | ✅ | ✅ | ✅ | ✅ |\n| Google ADK | ✅ | ✅ | ✅ | ✅ |\n| CrewAI | ✅ | ✅ | ✅ | ✅ |\n| AWS AgentCore | ✅ | ✅ | ✅ | ✅ |\n| Strands | ✅ | ✅ | ✅ | ✅ |\n\n### OpenAI 集成示例\n\n```python\nfrom deepeval.tracing import trace\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator():\n with trace(metrics=[TaskCompletionMetric()]):\n # OpenAI 客户端调用会自动被追踪\n response = client.chat.completions.create(\n model=\"gpt-4\",\n messages=[{\"role\": \"user\", \"content\": golden.input}]\n )\n```\n\n### LangChain 集成示例\n\n```python\nfrom deepeval.integrations.langchain import CallbackHandler\nfrom deepeval.metrics import TaskCompletionMetric\n\ncallback_handler = CallbackHandler(metrics=[TaskCompletionMetric()])\n\nfor golden in dataset.evals_iterator():\n llm.invoke(\n golden.input,\n config={\"callbacks\": [callback_handler]},\n )\n```\n\n## 数据流处理\n\n### 离线评估数据流\n\n```mermaid\ngraph TD\n A[追踪数据采集] --> B[Span 数据存储]\n B --> C{评估类型判断}\n C -->|在线评估| D[ConfidentSpanExporter]\n C -->|离线评估| E[Offline Evals 模块]\n D --> F[云端评估引擎]\n E --> G[本地评估执行]\n F --> H[结果聚合]\n G --> H\n```\n\n### OTel 模式下的混合追踪\n\n当 OTel 模式集成在活跃的 `@observe` 或 `with trace(...)` 上下文中运行时，OTel span interceptor 会同步追踪 UUID，确保两种传输方式产生的数据能够合并到同一个追踪会话中。\n\n```mermaid\nsequenceDiagram\n participant App as 应用代码\n participant Observe as @observe 上下文\n participant OTel as OTel SpanInterceptor\n participant Router as ContextAwareSpanProcessor\n participant REST as ConfidentSpanExporter\n\n App->>Observe: 开始追踪\n Observe->>OTel: 同步 trace_id\n App->>OTel: 创建 OTel span\n OTel->>Router: 处理 span\n Router->>REST: 路由至 REST\n REST->>Observe: 合并到同一追踪\n```\n\n## 评估迭代器集成\n\n`dataset.evals_iterator()` 是追踪系统与评估流程结合的核心接口。它支持在迭代过程中自动应用追踪和指标计算。\n\n### 基础用法\n\n```python\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):\n app(golden.input)\n```\n\n### 异步配置\n\n```python\nfrom deepeval.evaluate.configs import AsyncConfig\nfrom deepeval.metrics import TaskCompletionMetric\n\nfor golden in dataset.evals_iterator(\n async_config=AsyncConfig(run_async=True),\n metrics=[TaskCompletionMetric()],\n):\n task = asyncio.create_task(run_agent(golden.input))\n dataset.evaluate(task)\n```\n\n## 配置与初始化\n\n### 追踪初始化\n\n```python\nimport deepeval\n\ndeepeval.instrument(\n name=\"my-app\",\n environment=\"development\"\n)\n```\n\n### 集成初始化\n\n每个框架集成都提供了 `instrument_*` 函数来简化初始化过程。例如：\n\n```python\nfrom deepeval.integrations.google_adk import instrument_google_adk\n\ninstrument_google_adk()\n```\n\n## 关键文件说明\n\n| 文件路径 | 功能描述 |\n|---------|---------|\n| `deepeval/tracing/__init__.py` | 追踪系统公共 API 导出，包含 `trace`、`@observe`、`update_current_span` 等核心接口 |\n| `deepeval/tracing/tracing.py` | 追踪系统核心实现，包含 TraceManager 类和追踪上下文管理逻辑 |\n| `deepeval/tracing/context.py` | 追踪上下文实现，管理当前活跃的追踪和跨度状态 |\n| `deepeval/tracing/api.py` | 追踪系统 REST API 接口定义，用于与云端服务通信 |\n| `deepeval/tracing/otel/__init__.py` | OpenTelemetry 集成模块，实现 OTel span 拦截和转发 |\n| `deepeval/tracing/offline_evals/__init__.py` | 离线评估模块，支持在没有网络连接时执行本地评估 |\n\n## 与 Confident AI 平台的集成\n\n追踪系统与 Confident AI 平台深度集成，提供以下能力：\n\n1. **云端追踪同步**：追踪数据自动同步至 Confident AI 平台\n2. **评估报告生成**：在平台上生成可分享的测试报告\n3. **追踪可视化**：在 Web 界面中查看完整的调用链路\n4. **生产环境监控**：支持生产环境的实时追踪和评估\n\n通过 `deepeval login` 命令登录后，所有追踪数据会自动同步到平台：\n\n```bash\ndeepeval login\ndeepeval test run test_chatbot.py\n```\n\n## 最佳实践\n\n1. **使用 @observe 装饰器包装关键组件**：确保所有 LLM 调用和关键业务逻辑都在可追踪的范围内\n2. **结合评估指标使用追踪**：在 `trace()` 或 `evals_iterator()` 中指定指标以获得完整的评估数据\n3. **利用上下文更新函数**：在需要注入额外信息时使用 `update_current_span()` 和 `update_current_trace()`\n4. **选择合适的集成方式**：根据框架选择原生集成或 OTel 模式集成\n\n## 相关文档\n\n- [评估指标文档](https://deepeval.com/docs/metrics-llm-evals)\n- [组件级评估指南](https://deepeval.com/docs/evaluation-component-level-llm-evals)\n- [Confident AI 平台文档](https://www.confident-ai.com/docs)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：confident-ai/deepeval\n\n摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)。\n\n## 1. 安全/权限坑 · 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bc32a715810442d93069925f14aab92 | https://github.com/confident-ai/deepeval/issues/2673 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：'NoneType' object has no attribute 'find'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：'NoneType' object has no attribute 'find'\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_756ddcdc1eda4fd7b87ade56a4a3c10f | https://github.com/confident-ai/deepeval/issues/2554 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 配置坑 · 来源证据：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9a7d5b92cc5948d48aec4ed1e96e7288 | https://github.com/confident-ai/deepeval/releases/tag/v4.0.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:676829188 | https://github.com/confident-ai/deepeval | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：LLM Evals - v3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LLM Evals - v3.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f9371d513c443ab860bbb718a785a2c | https://github.com/confident-ai/deepeval/releases/tag/v3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：confident-ai/deepeval\n\n摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)。\n\n## 1. 安全/权限坑 · 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bc32a715810442d93069925f14aab92 | https://github.com/confident-ai/deepeval/issues/2673 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：'NoneType' object has no attribute 'find'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：'NoneType' object has no attribute 'find'\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_756ddcdc1eda4fd7b87ade56a4a3c10f | https://github.com/confident-ai/deepeval/issues/2554 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 配置坑 · 来源证据：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9a7d5b92cc5948d48aec4ed1e96e7288 | https://github.com/confident-ai/deepeval/releases/tag/v4.0.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:676829188 | https://github.com/confident-ai/deepeval | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：LLM Evals - v3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LLM Evals - v3.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f9371d513c443ab860bbb718a785a2c | https://github.com/confident-ai/deepeval/releases/tag/v3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# deepeval - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 deepeval 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-test-cases：测试用例定义。围绕“测试用例定义”模拟一次用户任务，不展示安装或运行结果。\n5. page-metrics：评估指标体系。围绕“评估指标体系”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-test-cases\n输入：用户提供的“测试用例定义”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-metrics\n输入：用户提供的“评估指标体系”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-test-cases：Step 4 必须围绕“测试用例定义”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-metrics：Step 5 必须围绕“评估指标体系”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/confident-ai/deepeval\n- https://github.com/confident-ai/deepeval#readme\n- skills/deepeval/SKILL.md\n- README.md\n- deepeval/__init__.py\n- deepeval/_version.py\n- deepeval/test_case/__init__.py\n- deepeval/test_case/llm_test_case.py\n- deepeval/evaluate/__init__.py\n- deepeval/evaluate/evaluate.py\n- deepeval/evaluate/execute/__init__.py\n- deepeval/evaluate/execute/e2e.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 deepeval 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：confident-ai/deepeval\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install -U deepeval\n```\n\n来源：https://github.com/confident-ai/deepeval#readme\n\n## 来源\n\n- repo: https://github.com/confident-ai/deepeval\n- docs: https://github.com/confident-ai/deepeval#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_635bb97422114e26ba1712a26f1663e8"
}