deepeval 项目说明书

Doramagic 项目包 · 项目说明书

deepeval 项目

LLM 评估框架

Overview & Getting Started

DeepEval 是一个面向大语言模型（LLM）应用的评估框架，由 Confident AI 团队维护。它最初以 Python 生态为核心，提供指标计算、数据集生成、红队测试、回溯（tracing）等能力，并逐步将 Confident AI 平台层面的能力扩展到 TypeScript 生态中。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 LLM 模型接入与回溯

继续阅读本节完整说明和来源证据。

章节 回溯结构

继续阅读本节完整说明和来源证据。

项目概述

项目顶层 README.md 描述了核心特性矩阵：G-Eval、RAG 指标、会话指标、数据集创建、红队测试、与 Confident AI 的集成等。在 Roadmap 中，已完成项包括集成 Confident AI、上述四类指标与红队测试；仍在推进的包括自定义 DAG 指标与 Guardrails。

DeepEval 4.0 引入了面向编码代理（coding agents）的 Eval Harness、单行集成（1-line integrations）以及用于回溯检视的 TUI，进一步将框架定位为生产级 AI 系统的调试与评估工具。

安装与配置

Python 端的 DeepEval 通过标准包管理器安装并配合 CLI 使用。CLI 工具通过 deepeval/cli/utils.py 中的入口与配置函数（例如 with_utm、PROD 常量）将日志和链接注入到 Confident AI 控制台，便于在评估结果中直接跳转平台。

CLI 的合成数据生成子命令实现位于 deepeval/cli/generate/command.py，它支持从文档、上下文或空白（SCRATCH）出发生成单轮（SINGLE_TURN）或多轮（CONVERSATIONAL）golden 数据，覆盖了入门阶段最常见的 ETL 需求。

TypeScript 端的 SDK 以独立包形式发布于 typescript/ 子目录，包名为 deepeval，可通过 npm/yarn/pnpm 单独安装。其当前版本与入口配置定义在 typescript/package.json 中。

核心模块与能力

DeepEval 的能力可被拆解为若干高层模块，下表总结了它们在仓库中的对应位置与典型用例：

能力	入口/位置	用途
LLM 网关与重试	deepeval/models/llms/gateway_model.py	统一多 provider 接入、集中重试、成本与模型元数据查询
OpenAI 模型接入	deepeval/models/llms/openai_model.py	结构化输出、JSON 模式、token 成本与 span 更新
模型注册表	deepeval/models/llms/constants.py	维护每个模型的 logprobs、多模态、结构化输出与价格元数据
CLI 工具与生成	deepeval/cli/utils.py、deepeval/cli/generate/command.py	提供 `deepeval` CLI 与数据集合成
TypeScript 平台 SDK	typescript/src/index.ts	暴露 dataset、tracing、confident、openai 等子模块
平台 API 客户端	typescript/src/confident/index.ts	封装 Confident AI 的 HTTP 接口与 `evaluate`
Prompt 管理	typescript/src/prompt/index.ts	推送/拉取 prompt 与版本，提供 `PromptMessage`、`Tool` 等模型
回溯与 Span	typescript/src/tracing/api.ts、typescript/src/tracing/tracing.ts	定义 `TraceApi`、`BaseApiSpan` 等 DTO 并将内部 span 转为上报结构

LLM 模型接入与回溯

DeepEval 在 Python 端将多 provider 抽象为统一的网关模型（GatewayModel），由 gateway_model.py 描述。其核心思路是：子类声明 PROVIDER_SLUG 与 PROVIDER_LABEL，并在初始化时通过 create_retry_decorator 装配统一的同步/异步重试策略，然后实现 _generate / _a_generate 即可获得一致的错误恢复能力。

以 OpenAI 为例，deepeval/models/llms/openai_model.py 中通过 client.beta.chat.completions.parse 与 client.chat.completions.create 处理结构化输出、JSON 模式以及自由文本三档路径，并在每次调用后通过 self._update_llm_span_from_completion 自动写入 prompt/completion token 数量与成本，使 LLM span 自动携带计费信息。

回溯结构

TypeScript 端的回溯 DTO 在 typescript/src/tracing/api.ts 中定义，其中 BaseApiSpan 同时携带 model、inputTokenCount、outputTokenCount、costPerInputToken、costPerOutputToken 等字段，并在上层用 expectedOutput、retrievalContext、toolsCalled、expectedTools 等附加字段映射到 LLMTestCase。在 typescript/src/tracing/tracing.ts 中，转换器负责将内部 BaseSpan 中的 Date 序列化为 ISO 字符串，并保证当 endTime 缺失或早于 startTime 时回退到 startTime，从而避免上报非法时间区间。

多语言支持与社区焦点

根据 typescript/README.md，TypeScript SDK 计划于 6 月 5 日发布首个公开版本，目前聚焦在 Confident AI 平台特性（dataset、prompt、evaluate reporting）。本地化的 LLM-as-a-judge 指标、NLP 模型与本地评估能力仍保留在 Python 包中。该路线图还提到，到 7 月底将在 Confident AI 集成面达到 80% 的特性对等。

社区当前关注的高频问题包括：

通过自定义 OpenTelemetry/OpenInference OTLP 上报 LLM span 时，llm.token_count.* 属性未被映射到 UI 的 tokens 字段（参见 issue 2746）。
pydantic-ai 集成配合 ConfidentInstrumentationSettings 时，actual_output、tools_called、expected_tools 为 None（参见 issue 2508）。
希望在 LlmSpan 中支持缓存输入 token 的成本追踪（参见 issue 2741）。
CLI 缺少仅显示失败用例的开关，影响 Git pre-push 体验（参见 issue 1235）。

这些问题在阅读官方文档与对应源码时，建议结合本节列出的入口文件进一步定位。

常见起步路径

安装 Python 包并运行 deepeval --help，确认 CLI 与 deepeval/cli/utils.py 中定义的 Confident AI 控制台集成正常。
通过 deepeval generate（实现于 deepeval/cli/generate/command.py）合成单轮或多轮 golden 数据集。
在 TypeScript 工程中安装 deepeval 包（参考 typescript/package.json 的 exports），通过 deepeval.confident.evaluate 或 deepeval.dataset 等子模块接入 Confident AI。
若需自定义 LLM 接入，参考 deepeval/models/llms/gateway_model.py 的 _run/_arun 重试约定与 deepeval/models/llms/openai_model.py 的 span 更新机制。

Evaluation Metrics

DeepEval 的 Evaluation Metrics（评估指标）模块是整个框架的核心理念，旨在为大语言模型（LLM）应用提供一套可量化、可观测的评分体系。该模块不仅覆盖传统的 RAG（检索增强生成）质量评估，还扩展到 Agent 工具调用、多轮对话、MCP 协议以及多模态场景。资料来源：[README.md]()

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

DeepEval 的 Evaluation Metrics（评估指标）模块是整个框架的核心理念，旨在为大语言模型（LLM）应用提供一套可量化、可观测的评分体系。该模块不仅覆盖传统的 RAG（检索增强生成）质量评估，还扩展到 Agent 工具调用、多轮对话、MCP 协议以及多模态场景。资料来源：README.md

从架构上看，指标体系与 deepeval/models/llms/ 下的模型网关、CLI 合成器、以及 typescript/src/tracing/ 中的追踪客户端深度耦合。Python 包提供完整的本地 LLM-as-a-Judge 与 NLP 评分能力，而 TypeScript SDK 则通过 Confident AI 平台提供数据集、提示词、追踪和评估结果的上报。资料来源：typescript/README.md、typescript/src/confident/index.ts

指标分类

依据 README 中列出的功能矩阵，DeepEval 将评估指标划分为若干主要家族：

指标家族	代表指标	评估目标
工具使用	Tool Use、Argument Correctness	LLM 调用工具的质量与参数正确性
RAG 指标	Answer Relevancy、Faithfulness、Contextual Recall/Precision/Relevancy、RAGAS	检索上下文与生成答案的契合度
多轮对话	Knowledge Retention、Conversation Completeness、Turn Relevancy、Turn Faithfulness、Role Adherence	跨轮次的事实保持与角色一致性
MCP 指标	MCP Task Completion、MCP Use、Multi-Turn MCP Use	基于 MCP 协议的代理完成任务的能力
Agent 指标	Task Completion（v3.9.9+）	从追踪轨迹中分析代理是否真正完成目标

资料来源：README.md

需要注意的是，部分 RAG 指标对重叠片段比较敏感。例如 ContextualPrecisionMetric 在处理带有重叠切片的金融文档时，可能将相似度极高的检索块视为独立低质量节点，从而低估检索质量（参考社区 Issue #2594）。在设计数据集时应预先对切片重叠策略进行敏感性测试。资料来源：README.md 与社区反馈

评估执行与模型网关

所有指标在执行评分时都会调用底层的 LLM 网关。gateway_model.py 抽象了统一的重试机制与成本核算逻辑，子类只需实现 _generate / _a_generate 即可获得集中化的重试与计费。资料来源：deepeval/models/llms/gateway_model.py

constants.py 中以 ModelDataRegistry 的形式集中维护每个模型的能力位（如 supports_log_probs、supports_multimodal、supports_structured_outputs）以及输入/输出价格。社区最近的功能请求 #2741 提出要为 LlmSpan 增加缓存输入 token 的成本字段，目前 LlmSpan 仍只支持 input_token_count、output_token_count、cost_per_input_token、cost_per_output_token 四个成本相关属性。资料来源：deepeval/models/llms/constants.py、社区 Issue #2741

CLI 侧，deepeval/cli/generate/command.py 负责将文档、上下文或已有 Goldens 转化为可评估用例，支持单轮与多轮 GoldenVariation、多种生成方法（DOCS、CONTEXTS、SCRATCH、GOLDENS），并在每个分支内统一注入上下文构造配置（ContextConstructionConfig）。资料来源：deepeval/cli/generate/command.py

追踪集成与 TypeScript 互操作

指标评分结果可与追踪系统结合，形成端到端的可观测链路。typescript/src/tracing/tracing.ts 中定义的 LlmSpan、AgentSpan、RetrieverSpan、ToolSpan 在上报到 Confident AI 时，会把 inputTokenCount、outputTokenCount、costPerInputToken、costPerOutputToken 等字段一并发送，从而把"指标分数"与"运行成本"在同一个 Trace 视图中呈现。资料来源：typescript/src/tracing/tracing.ts

社区 Issue #2746 报告：使用自定义 OpenTelemetry / OpenInference OTLP 导出时，即使 span 中携带 llm.token_count.* 整数属性，Trace UI 的 tokens 字段仍为空——这通常是因为字段命名或属性命名空间未与 DeepEval 的 OTLP 解析器对齐，需在导出端按 OpenInference 语义标准命名。资料来源：社区 Issue #2746

TypeScript 包当前以 Confident AI 平台集成面为主：./dataset、./testCase、./tracing、./confident、./openai、./integrations/ai-sdk 等子入口在 package.json 的 exports 字段中显式声明，提示词管理通过 typescript/src/prompt/index.ts 中的 PromptMessage、Tool 等类对外暴露。资料来源：typescript/package.json、typescript/src/prompt/index.ts

已知问题与社区反馈

下面汇总与指标评估密切相关的几个高频社区问题，使用时建议提前规避：

CLI 输出过载（Issue #1235）：在 Git pre-push 钩子中执行时，所有用例的完整输出会一并打印，建议通过 --only-show-failures 之类的过滤参数（若版本支持）只保留失败项。资料来源：社区 Issue #1235
OTLP Token 字段缺失（Issue #2746）：自建 OTLP 导出器需遵循 OpenInference 属性命名约定，否则 tokens 字段为空。资料来源：社区 Issue #2746
缓存输入 Token 未计入成本（Issue #2741）：当前 LlmSpan 数据模型尚未包含 cached_input_token_count 等字段。资料来源：社区 Issue #2741
pydantic-ai + OpenAIResponsesModel 集成缺陷（Issue #2508）：ConfidentInstrumentationSettings 在该组合下 tools_called、expected_tools、actual_output 均为 None，需等待上游修复。资料来源：社区 Issue #2508
Contextual Precision 重叠切片惩罚（Issue #2594）：使用 ContextualPrecisionMetric 评估带重叠切片的 RAG 流水线时可能低估检索质量，建议在指标对比中加入切片去重预处理。资料来源：社区 Issue #2594

进阶能力与版本演进

v3.7.2 引入了 Arena-GEval——首个 LLM-arena-as-a-Judge 指标，显著减少了 ETL 代码量。v3.9.9 进一步推出针对 AI Agent 的 Task Completion 指标，结合 Trace 行为判定代理是否真正完成目标。v4.0.2 发布"Eval Harness for Coding Agents"、1 行集成与 TUI 跟踪检查器，将指标体系与编码代理的开发循环深度融合。v4.0.3 新增 Decision Graph API（simulation_graph）以细粒度控制对话仿真，controller 已被弃用。v4.0.5 提供 claude-opus-4-8 Day 0 支持并更新定价元数据。资料来源：社区 Release Notes

Tracing & Framework Integrations

章节 相关页面

继续阅读本节完整说明和来源证据。

1. 概览与设计目标

Tracing（链路追踪）与 Framework Integrations（框架集成）是 DeepEval 4.0 引入的"agent-native"评估工作流核心。它们让用户在不改写业务代码的前提下，把 LLM 应用、Agent 框架或 RAG 管线的运行轨迹捕获到 Confident AI 平台，并在轨迹上直接挂载评估指标。集成层在仓库内被拆成两个主要形态：Python 端的 deepeval.integrations.*（通过回调、OTel 拦截器或原生客户端包装器接入）以及 TypeScript 端以 @observe / with trace(...) 装饰器为核心的声明式 API。

资料来源：deepeval/integrations/README.md、typescript/README.md

2. 传输机制：REST 与 OTLP

集成层向 Confident AI 上报数据时支持两种传输：

模式	触发条件	端点	关键组件
REST	通过 `@observe` / `with trace(...)` 包裹；或 `dataset.evals_iterator` 中 `trace_manager.is_evaluating=True`	`api.confident-ai.com/v1/traces`	`trace_manager` 一次 POST 整条 trace
OTLP	社区 OTel 注入器；自定义 OpenTelemetry/OpenInference 导出	`otel.confident-ai.com/v1/traces`	`BatchSpanProcessor` 定时 / 阈值刷新

OTel 模式下，系统通过 ContextAwareSpanProcessor 在检测到 trace_manager.is_evaluating=True 时自动切换到 REST 路由，避免 OTel span 与 trace_manager 双向维护 UUID。资料来源：deepeval/integrations/README.md

flowchart LR
    A[Framework SDK] -->|callback / OTel span| B(Integration Layer)
    B -->|REST 模式| C[api.confident-ai.com]
    B -->|OTLP 模式| D[otel.confident-ai.com]
    C --> E[Confident AI Trace UI]
    D --> E
    B -->|is_evaluating=True| F[trace_manager]
    F --> C

3. 框架集成矩阵

集成层在 README 中维护了一份"能力矩阵"，按四个维度评估每个集成：是否能"裸跑"（无需显式 @observe）、是否能融入 with trace(...) 上下文、是否兼容 evals_iterator、以及是否能在 deepeval test run 下工作。顶层模块如 deepeval.openai、deepeval.anthropic、deepeval.openai_agents 并不放在 deepeval/integrations/ 目录下，但被纳入同一张矩阵。LangChain、LangGraph、Pydantic AI、CrewAI、AWS AgentCore、LlamaIndex 等则通过回调处理器或顶层客户端包装器接入（见主 README 的 integrations 列表）。资料来源：README.md、deepeval/integrations/README.md

TypeScript 端的核心导出集中在 typescript/src/tracing/index.ts，对外暴露 observe、updateCurrentSpan、updateCurrentTrace、getCurrentSpan、getCurrentTrace、evaluateThread、evaluateTrace、evaluateSpan 等函数，实现与 Python @observe 几乎对等的 API 表面。资料来源：typescript/src/tracing/index.ts

4. OpenInference 通用集成

deepeval/integrations/openinference/ 是为社区维护的 OpenInference 注入器（如 openinference-instrumentation-google-adk）提供的 SpanInterceptor + Processor 套件。它会安装 TracerProvider，注册 OpenInferenceSpanInterceptor 把 openinference.span.kind、llm.input_messages.{idx}、llm.output_messages.{idx}、tool.name、llm.token_count.* 等语义约定属性翻译成 confident.span.* 命名空间下的内部属性，并最终通过 ContextAwareSpanProcessor 路由。顶层 deepeval.instrument(name=..., environment=...) 是用户调用的入口。资料来源：deepeval/integrations/README.md

TypeScript 端的等价实现在 typescript/src/integrations/openinference/processor.ts，它定义了 OI_KIND_TO_SPAN_TYPE 映射（AGENT/CHAIN/LLM/TOOL/RETRIEVER → 内部 SpanType），并在拦截 span 时通过 getCurrentTrace / traceManager 复用现有 trace 上下文。

5. 已知问题与社区反馈

社区中暴露的若干问题都与该模块密切相关：

Token 字段为空：当通过自定义 OTLP 端点发送 OpenInference span 时，UI 的 tokens 字段为空白，尽管 span 已携带 llm.token_count.* 整数属性（issue #2746）。
Pydantic AI 字段缺失：ConfidentInstrumentationSettings 与 OpenAIResponsesModel 配合时，actual_output、tools_called、expected_tools 全部为 None（issue #2508）。
缺少 Cached Token 计费：LlmSpan / update_llm_span / @observe(type="llm") 仅支持 input_token_count、output_token_count 两个成本字段，社区希望加入 cached input token（issue #2741）。
TypeScript 支持路线：仓库已宣布 TypeScript SDK 计划，首版瞄准"6 月 5 日发布、7 月底达到 Confident AI 集成面 80% 特性对等"，当前 /typescript 目录已作为 Confident API 的客户端包装器存在（issue #2734、typescript/README.md）。

6. 典型使用模式

Python 用户最常见的写法是：先调用 deepeval.instrument(...) 开启 OTLP 通道，再让框架原生的注入器（如 GoogleADKInstrumentor().instrument()）接管，DeepEval 自动把 OTel span 折叠为内部 BaseSpan 并通过 ContextAwareSpanProcessor 上报。TypeScript 用户则使用 with trace(...) { ... } 包裹业务代码，在内部用 updateLlmSpan({ promptTokens, completionTokens, toolsCalled }) 补全成本与工具调用字段——这些字段在 typescript/src/openai/extractor.ts 中由 ChatCompletion / Response API 响应自动提取，再由 typescript/src/openai/types.ts 中的 OutputParameters 类型契约约束。资料来源：typescript/src/openai/extractor.ts、typescript/src/openai/types.ts、typescript/src/integrations/openinference/processor.ts

Datasets, Synthesis & Simulation

deepeval 中的"数据集、合成与模拟"是一组用于构建、扩充实测样本，并在受控条件下回放多轮对话工作流的核心能力。从 typescript/src/index.ts 的顶层导出可以看出，这套能力由三个相互协作的子系统组成：EvaluationDataset（数据集）、Prompt（提示词模板）以及 ConversationSimulator（多轮对话模拟器）。资料来源：...

章节 相关页面

继续阅读本节完整说明和来源证据。

数据集、合成与模拟（Datasets, Synthesis & Simulation）

概述与定位

deepeval 中的"数据集、合成与模拟"是一组用于构建、扩充实测样本，并在受控条件下回放多轮对话工作流的核心能力。从 typescript/src/index.ts 的顶层导出可以看出，这套能力由三个相互协作的子系统组成：EvaluationDataset（数据集）、Prompt（提示词模板）以及 ConversationSimulator（多轮对话模拟器）。资料来源：typescript/src/index.ts:1-22

在 Python 端，能力通过 deepeval.dataset、deepeval.synthesizer、deepeval.simulator 等子包实现；而在 TypeScript SDK 中，这一层目前以客户端封装的形式提供，专注于与 Confident AI 平台的数据集/提示词接口对接，本地执行仍以 Python 实现为主。资料来源：typescript/README.md:11-19

flowchart LR
    A[EvaluationDataset<br/>数据集] --> B[Golden / GoldenConversational<br/>样本规约]
    B --> C[Synthesizer<br/>合成器]
    C --> D[ConversationSimulator<br/>多轮模拟]
    D --> E[Tracing & Evals<br/>跟踪与评估]
    E --> F[Confident AI Platform<br/>云平台上报]

数据集管理（EvaluationDataset）

EvaluationDataset 是整个工作流的入口，负责承载从平台拉取或本地创建的黄金样本集合。在 TypeScript 端，typescript/src/dataset/index.ts 显式导出了 dataset、api、golden、utils 四个子模块，表明数据集子系统不仅包含样本对象，还包括与平台交互的 API 层以及格式转换工具。资料来源：typescript/src/dataset/index.ts:1-5

从顶层模块入口的命名导出可以看出，Python 端对应的核心类型为 EvaluationDataset、Golden 与 ConversationalGolden，这三者构成了"单轮"与"多轮"两类样本的规约基类。资料来源：typescript/src/index.ts:18-20

dataset/api 子模块承担与 Confident AI 平台之间的推送/拉取动作，开发者无需手动维护 ETL 代码即可完成数据集同步；utils 子模块负责在本地对象与平台载荷之间进行格式归一化。资料来源：typescript/src/dataset/index.ts:2-4

合成器（Synthesizer）

合成器的作用是基于"种子"或上下文生成多样化的扩展样本，常用于冷启动评估、回归覆盖以及对抗性测试。基于 v3.9.9 的发布说明，社区已经可以利用 DeepEval 完成"多轮合成数据生成"（multi-turn synthetic data generation），这是合成器能力在多轮场景中的扩展。资料来源：community_context: v3.9.9 release notes

在工程实现上，合成器在生成样本时通常会调用一个 DeepEvalBaseLLM 子类来产出文本。gateway_model.py 文档注释中明确指出，开发者自定义网关模型时需要实现 load_model、_generate 与 _a_generate 等方法，并返回 (output, cost) 二元组以便合成器进行成本核算与限流。资料来源：deepeval/models/llms/gateway_model.py:7-19

此外，gateway_model.py 中的 _run 与 _arun 帮助方法会在每次调用时套用统一的 create_retry_decorator(self.PROVIDER_SLUG)，从而保证合成器在跨多家 LLM 提供方时具有一致的容错行为。资料来源：deepeval/models/llms/gateway_model.py:36-44

多轮对话模拟（ConversationSimulator）

多轮模拟用于在没有真实用户的情况下，自动驱动被测 agent 与一个由 LLM 扮演的"用户"进行若干轮对话，从而采集完整的轨迹与中间状态用于评估。资料来源：typescript/src/index.ts:22

v4.0.3 版本引入了全新的"决策图（simulation graph）"机制：ConversationSimulator 新增 simulation_graph 参数，用于细粒度控制用户回合的生成逻辑；同时旧的 controller 参数被标记为 stopping_controller，并在运行时给出弃用警告。资料来源：community_context: v4.0.3 release notes

在追踪层面，typescript/src/tracing/tracing.ts 中的 convertSpanToApiSpan 方法负责把内部 BaseSpan 转换为 BaseApiSpan，其中显式区分了输入/输出、时间戳以及状态字段（SUCCESS/ERROR）。这一转换是模拟器产出可上报轨迹的关键路径。资料来源：typescript/src/tracing/tracing.ts:38-67

与评估工作流的衔接

数据集、合成的样本以及模拟得到的轨迹，最终需要被评估链路消费。deepeval/integrations/README.md 中描述的 evals_iterator 能力明确指出：在 dataset.evals_iterator(...) 内部既可以端到端地传入 metrics=[...]，也可以在单个 span 上通过 @observe(metrics=[...]) 进行组件级评估。资料来源：deepeval/integrations/README.md:11-13

对于以 OpenTelemetry 模式接入的集成，ContextAwareSpanProcessor 会在 trace_manager.is_evaluating 为 True 时自动切换到 REST 路由，从而让 span 直接流入 trace_manager 而不是 OTLP；这一行为保证了在 evals_iterator 上下文中产生的合成与模拟数据能够被就地评估。资料来源：deepeval/integrations/README.md:11-13

CLI 层则提供了 deepeval test run 等入口与平台凭证管理（如 set_confident_api_key、get_confident_api_key），方便在 CI 中批量回放数据集并把结果上报到 Confident AI。资料来源：deepeval/cli/utils.py:31-37

常见失败模式与社区反馈

OTel 路径下的 Token 丢失：当用户通过自定义 OpenTelemetry/OpenInference OTLP 上报时，llm.token_count.* 属性未能被识别为成本字段，导致 UI 中 tokens 为空。这间接反映了在 OTel 模式下，合成/模拟产生的 span 需要走统一的成本归一化流程。资料来源：community_context: issue #2746
pydantic-ai 集成捕获失败：使用 OpenAIResponsesModel 时 actual_output、tools_called、expected_tools 均为 None，提示集成在某些模型分支下尚未覆盖完整的事件抽取逻辑。资料来源：community_context: issue #2508
上下文精度对重叠块过度惩罚：ContextualPrecisionMetric 将 RAG 中为保留表格上下文而引入的近重复块视为多次低质量检索，开发者需要在合成数据集时显式去重以避免误评。资料来源：community_context: issue #2594

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：CLI improvement: option to display only failed tests

可能增加新用户试用和生产接入成本。

high 来源证据：ConfidentInstrumentationSettings with pydantic-ai: tools_called, expected_tools, and actual_output are all None when us…

可能阻塞安装或首次运行。

high 失败模式：security_permissions: Security: request for a submitting security vulnerabilities.

Developers may expose sensitive permissions or credentials: Security: request for a submitting security vulnerabilities.

high 来源证据：Contextual Precision over-penalizes overlapping chunks in financial-document RAG

可能影响授权、密钥配置或安全边界。

Pitfall Log / 踩坑日志

项目：confident-ai/deepeval

摘要：发现 28 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：CLI improvement: option to display only failed tests。

1. 安装坑 · 来源证据：CLI improvement: option to display only failed tests

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CLI improvement: option to display only failed tests
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/confident-ai/deepeval/issues/1235 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：ConfidentInstrumentationSettings with pydantic-ai: tools_called, expected_tools, and actual_output are all None when us…

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ConfidentInstrumentationSettings with pydantic-ai: tools_called, expected_tools, and actual_output are all None when using OpenAIResponsesModel
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/confident-ai/deepeval/issues/2508 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安全/权限坑 · 失败模式：security_permissions: Security: request for a submitting security vulnerabilities.

严重度：high
证据强度：source_linked
发现：Developers should check this security_permissions risk before relying on the project: Security: request for a submitting security vulnerabilities.
对用户的影响：Developers may expose sensitive permissions or credentials: Security: request for a submitting security vulnerabilities.
证据：failure_mode_cluster:github_issue | https://github.com/confident-ai/deepeval/issues/2744 | Security: request for a submitting security vulnerabilities.

4. 安全/权限坑 · 来源证据：Contextual Precision over-penalizes overlapping chunks in financial-document RAG

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Contextual Precision over-penalizes overlapping chunks in financial-document RAG
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/confident-ai/deepeval/issues/2594 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 配置坑 · 可能修改宿主 AI 配置

严重度：medium
证据强度：source_linked
发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
证据：capability.host_targets | github_repo:676829188 | https://github.com/confident-ai/deepeval | host_targets=claude, chatgpt

6. 配置坑 · 失败模式：configuration: 🎉 New Interfaces, Reduce ETL Code < 50%!

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: 🎉 New Interfaces, Reduce ETL Code < 50%!
对用户的影响：Upgrade or migration may change expected behavior: 🎉 New Interfaces, Reduce ETL Code < 50%!
证据：failure_mode_cluster:github_release | https://github.com/confident-ai/deepeval/releases/tag/v3.7.2 | 🎉 New Interfaces, Reduce ETL Code < 50%!

7. 配置坑 · 失败模式：configuration: 🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: 🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!
对用户的影响：Upgrade or migration may change expected behavior: 🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!
证据：failure_mode_cluster:github_release | https://github.com/confident-ai/deepeval/releases/tag/v4.0.2 | 🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!

8. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | github_repo:676829188 | https://github.com/confident-ai/deepeval | README/documentation is current enough for a first validation pass.

9. 运行坑 · 失败模式：runtime: ConfidentInstrumentationSettings with pydantic-ai: tools_called, expected_tools, and actual_o...

严重度：medium
证据强度：source_linked
发现：Developers should check this runtime risk before relying on the project: ConfidentInstrumentationSettings with pydantic-ai: tools_called, expected_tools, and actual_output are all None when using OpenAIResponsesModel
对用户的影响：Developers may hit a documented source-backed failure mode: ConfidentInstrumentationSettings with pydantic-ai: tools_called, expected_tools, and actual_output are all None when using OpenAIResponsesModel
证据：failure_mode_cluster:github_issue | https://github.com/confident-ai/deepeval/issues/2508 | ConfidentInstrumentationSettings with pydantic-ai: tools_called, expected_tools, and actual_output are all None when using OpenAIResponsesModel

10. 维护坑 · 失败模式：migration: 🎉 New Decision Graph Logic for Granular Simulation Control

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: 🎉 New Decision Graph Logic for Granular Simulation Control
对用户的影响：Upgrade or migration may change expected behavior: 🎉 New Decision Graph Logic for Granular Simulation Control
证据：failure_mode_cluster:github_release | https://github.com/confident-ai/deepeval/releases/tag/v4.0.3 | 🎉 New Decision Graph Logic for Granular Simulation Control

11. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium

13. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium

14. 安全/权限坑 · 来源证据：Feature: support cached input tokens in LLM span cost tracking

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: support cached input tokens in LLM span cost tracking
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/confident-ai/deepeval/issues/2741 | 来源类型 github_issue 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：LLM tokens not displayed when using custom OpenTelemetry / OpenInference OTLP export

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LLM tokens not displayed when using custom OpenTelemetry / OpenInference OTLP export
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/confident-ai/deepeval/issues/2746 | 来源类型 github_issue 暴露的待验证使用条件。

16. 能力坑 · 失败模式：capability: CLI improvement: option to display only failed tests

严重度：low
证据强度：source_linked
发现：Developers should check this capability risk before relying on the project: CLI improvement: option to display only failed tests
对用户的影响：Developers may hit a documented source-backed failure mode: CLI improvement: option to display only failed tests
证据：failure_mode_cluster:github_issue | https://github.com/confident-ai/deepeval/issues/1235 | CLI improvement: option to display only failed tests

17. 能力坑 · 失败模式：capability: Feature: support cached input tokens in LLM span cost tracking

严重度：low
证据强度：source_linked
发现：Developers should check this capability risk before relying on the project: Feature: support cached input tokens in LLM span cost tracking
对用户的影响：Developers may hit a documented source-backed failure mode: Feature: support cached input tokens in LLM span cost tracking
证据：failure_mode_cluster:github_issue | https://github.com/confident-ai/deepeval/issues/2741 | Feature: support cached input tokens in LLM span cost tracking

18. 能力坑 · 失败模式：conceptual: DeepEval for Typescript

严重度：low
证据强度：source_linked
发现：Developers should check this conceptual risk before relying on the project: DeepEval for Typescript
对用户的影响：Developers may hit a documented source-backed failure mode: DeepEval for Typescript
证据：failure_mode_cluster:github_issue | https://github.com/confident-ai/deepeval/issues/2734 | DeepEval for Typescript

19. 运行坑 · 失败模式：performance: Contextual Precision over-penalizes overlapping chunks in financial-document RAG

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: Contextual Precision over-penalizes overlapping chunks in financial-document RAG
对用户的影响：Developers may hit a documented source-backed failure mode: Contextual Precision over-penalizes overlapping chunks in financial-document RAG
证据：failure_mode_cluster:github_issue | https://github.com/confident-ai/deepeval/issues/2594 | Contextual Precision over-penalizes overlapping chunks in financial-document RAG

20. 运行坑 · 失败模式：performance: LLM tokens not displayed when using custom OpenTelemetry / OpenInference OTLP export

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: LLM tokens not displayed when using custom OpenTelemetry / OpenInference OTLP export
对用户的影响：Developers may hit a documented source-backed failure mode: LLM tokens not displayed when using custom OpenTelemetry / OpenInference OTLP export
证据：failure_mode_cluster:github_issue | https://github.com/confident-ai/deepeval/issues/2746 | LLM tokens not displayed when using custom OpenTelemetry / OpenInference OTLP export

21. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | issue_or_pr_quality=unknown

22. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | release_recency=unknown

23. 维护坑 · 失败模式：maintenance: Opus 4.8: Day 0 Support

严重度：low
证据强度：source_linked
发现：Developers should check this maintenance risk before relying on the project: Opus 4.8: Day 0 Support
对用户的影响：Upgrade or migration may change expected behavior: Opus 4.8: Day 0 Support
证据：failure_mode_cluster:github_release | https://github.com/confident-ai/deepeval/releases/tag/v4.0.5 | Opus 4.8: Day 0 Support

24. 维护坑 · 失败模式：maintenance: 🎉 Metrics for AI agents, multi-turn synthetic data generation, and more!

严重度：low
证据强度：source_linked
发现：Developers should check this maintenance risk before relying on the project: 🎉 Metrics for AI agents, multi-turn synthetic data generation, and more!
对用户的影响：Upgrade or migration may change expected behavior: 🎉 Metrics for AI agents, multi-turn synthetic data generation, and more!
证据：failure_mode_cluster:github_release | https://github.com/confident-ai/deepeval/releases/tag/v3.9.9 | 🎉 Metrics for AI agents, multi-turn synthetic data generation, and more!

25. 维护坑 · 失败模式：maintenance: 🎉 New Arena GEval Metric, for Pairwise Comparisons

严重度：low
证据强度：source_linked
发现：Developers should check this maintenance risk before relying on the project: 🎉 New Arena GEval Metric, for Pairwise Comparisons
对用户的影响：Upgrade or migration may change expected behavior: 🎉 New Arena GEval Metric, for Pairwise Comparisons
证据：failure_mode_cluster:github_release | https://github.com/confident-ai/deepeval/releases/tag/v3.1.9 | 🎉 New Arena GEval Metric, for Pairwise Comparisons

26. 维护坑 · 失败模式：maintenance: 🎉 New Conversational Evaluation, LiteLLM Integration

严重度：low
证据强度：source_linked
发现：Developers should check this maintenance risk before relying on the project: 🎉 New Conversational Evaluation, LiteLLM Integration
对用户的影响：Upgrade or migration may change expected behavior: 🎉 New Conversational Evaluation, LiteLLM Integration
证据：failure_mode_cluster:github_release | https://github.com/confident-ai/deepeval/releases/tag/v3.0.8 | 🎉 New Conversational Evaluation, LiteLLM Integration

27. 维护坑 · 失败模式：maintenance: 🎉 New Multimodal Metrics, with Platform Support

严重度：low
证据强度：source_linked
发现：Developers should check this maintenance risk before relying on the project: 🎉 New Multimodal Metrics, with Platform Support
对用户的影响：Upgrade or migration may change expected behavior: 🎉 New Multimodal Metrics, with Platform Support
证据：failure_mode_cluster:github_release | https://github.com/confident-ai/deepeval/releases/tag/v3.1.5 | 🎉 New Multimodal Metrics, with Platform Support

28. 维护坑 · 失败模式：maintenance: 🎉 Renewed datasets, single vs multi-turn

严重度：low
证据强度：source_linked
发现：Developers should check this maintenance risk before relying on the project: 🎉 Renewed datasets, single vs multi-turn
对用户的影响：Upgrade or migration may change expected behavior: 🎉 Renewed datasets, single vs multi-turn
证据：failure_mode_cluster:github_release | https://github.com/confident-ai/deepeval/releases/tag/v3.2.6 | 🎉 Renewed datasets, single vs multi-turn

来源：Doramagic 发现、验证与编译记录

deepeval 项目

Overview & Getting Started

项目概述

安装与配置

核心模块与能力

LLM 模型接入与回溯

回溯结构

多语言支持与社区焦点

常见起步路径

See Also

Evaluation Metrics

概述

指标分类

评估执行与模型网关

追踪集成与 TypeScript 互操作

已知问题与社区反馈

进阶能力与版本演进

See Also

Tracing & Framework Integrations

1. 概览与设计目标

2. 传输机制：REST 与 OTLP

3. 框架集成矩阵

4. OpenInference 通用集成

5. 已知问题与社区反馈

6. 典型使用模式

See Also

Datasets, Synthesis & Simulation

数据集、合成与模拟（Datasets, Synthesis & Simulation）

概述与定位

数据集管理（EvaluationDataset）

合成器（Synthesizer）

多轮对话模拟（ConversationSimulator）

与评估工作流的衔接

常见失败模式与社区反馈

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安装坑 · 来源证据：CLI improvement: option to display only failed tests

2. 安装坑 · 来源证据：ConfidentInstrumentationSettings with pydantic-ai: tools_called, expected_tools, and actual_output are all None when us…

3. 安全/权限坑 · 失败模式：security_permissions: Security: request for a submitting security vulnerabilities.

4. 安全/权限坑 · 来源证据：Contextual Precision over-penalizes overlapping chunks in financial-document RAG

5. 配置坑 · 可能修改宿主 AI 配置

6. 配置坑 · 失败模式：configuration: 🎉 New Interfaces, Reduce ETL Code < 50%!

7. 配置坑 · 失败模式：configuration: 🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!

8. 能力坑 · 能力判断依赖假设

9. 运行坑 · 失败模式：runtime: ConfidentInstrumentationSettings with pydantic-ai: tools_called, expected_tools, and actual_o...

10. 维护坑 · 失败模式：migration: 🎉 New Decision Graph Logic for Granular Simulation Control

11. 维护坑 · 维护活跃度未知

13. 安全/权限坑 · 存在评分风险

14. 安全/权限坑 · 来源证据：Feature: support cached input tokens in LLM span cost tracking

15. 安全/权限坑 · 来源证据：LLM tokens not displayed when using custom OpenTelemetry / OpenInference OTLP export

16. 能力坑 · 失败模式：capability: CLI improvement: option to display only failed tests

17. 能力坑 · 失败模式：capability: Feature: support cached input tokens in LLM span cost tracking

18. 能力坑 · 失败模式：conceptual: DeepEval for Typescript

19. 运行坑 · 失败模式：performance: Contextual Precision over-penalizes overlapping chunks in financial-document RAG

20. 运行坑 · 失败模式：performance: LLM tokens not displayed when using custom OpenTelemetry / OpenInference OTLP export

21. 维护坑 · issue/PR 响应质量未知

22. 维护坑 · 发布节奏不明确

23. 维护坑 · 失败模式：maintenance: Opus 4.8: Day 0 Support

24. 维护坑 · 失败模式：maintenance: 🎉 Metrics for AI agents, multi-turn synthetic data generation, and more!

25. 维护坑 · 失败模式：maintenance: 🎉 New Arena GEval Metric, for Pairwise Comparisons

26. 维护坑 · 失败模式：maintenance: 🎉 New Conversational Evaluation, LiteLLM Integration

27. 维护坑 · 失败模式：maintenance: 🎉 New Multimodal Metrics, with Platform Support

28. 维护坑 · 失败模式：maintenance: 🎉 Renewed datasets, single vs multi-turn