# https://github.com/confident-ai/deepeval 项目说明书
生成时间：2026-05-16 19:07:22 UTC
## 目录
- [项目介绍](#page-introduction)
- [快速开始](#page-quickstart)
- [系统架构](#page-architecture)
- [核心模块结构](#page-core-modules)
- [测试用例定义](#page-test-cases)
- [评估指标体系](#page-metrics)
- [评估执行引擎](#page-evaluate-engine)
- [数据集管理](#page-dataset-management)
- [合成数据生成](#page-synthetic-data)
- [追踪系统](#page-tracing-system)
## 项目介绍
### 相关页面
相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
- [skills/README.md](https://github.com/confident-ai/deepeval/blob/main/skills/README.md)
- [deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)
- [deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)
- [deepeval/cli/main.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/main.py)
- [deepeval/cli/inspect.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/inspect.py)
# 项目介绍
## 概述
DeepEval 是一个简单易用、开源的 **LLM（大语言模型）评估框架**，专门用于评估大型语言模型系统。它类似于 Pytest，但专门为 LLM 应用的单元测试而设计。DeepEval 整合了最新研究成果，通过 G-Eval、任务完成度、答案相关性、幻觉检测等指标来运行评估，这些指标使用 **LLM-as-a-Judge**（LLM 作为评判者）和其他 NLP 模型，**完全运行在本地机器上**。
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
## 核心定位
无论你是构建 AI 代理（AI Agents）、RAG（检索增强生成）管道还是聊天机器人，无论是使用 LangChain 还是 OpenAI 实现，DeepEval 都能为你提供支持。通过它，你可以轻松确定最优的模型、提示词和架构，从而：
- 提升 AI 质量
- 防止提示词漂移
- 自信地从 OpenAI 迁移到 Claude
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
## 技术架构
### 系统架构图
```mermaid
graph TB
subgraph 用户层
A[测试用例编写] --> B[Pytest 集成 / API 调用]
end
subgraph 核心评估引擎
C[Metrics 指标] --> D[GEval]
C --> E[Answer Relevancy]
C --> F[Task Completion]
C --> G[Hallucination]
end
subgraph 集成层
H[LangChain] --> I[CallbackHandler]
J[OpenAI] --> K[OpenAI Integration]
L[Anthropic] --> M[Anthropic Integration]
N[LlamaIndex] --> O[AsyncConfig]
P[LangGraph] --> I
end
subgraph 输出层
Q[本地评估结果] --> R[Confident AI 云端]
end
B --> D
B --> E
B --> F
B --> G
I --> C
K --> C
M --> C
O --> C
```
### 评估模式
DeepEval 支持两种主要的评估模式：
| 模式 | 描述 | 适用场景 |
|------|------|----------|
| **端到端评估（End-to-End）** | 将 LLM 应用视为黑盒，输入输出直接评估 | 快速验证整体输出质量 |
| **可追溯评估（With Traceability）** | 使用 `evals_iterator()` 追踪组件级调用 | 细粒度分析、定位问题组件 |
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
## 核心功能
### 评估指标体系
DeepEval 提供了多种预置评估指标，所有指标得分范围均为 **0-1**：
| 指标名称 | 说明 | 评估参数 |
|----------|------|----------|
| **GEval** | 基于 G-Eval 算法的通用评估指标，支持自定义评估标准 | SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT |
| **AnswerRelevancyMetric** | 评估答案与输入的相关性 | retrieval_context |
| **TaskCompletionMetric** | 评估任务完成度 | 端到端追踪 |
| **幻觉检测指标** | 检测输出中的幻觉内容 | retrieval_context |
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
### 黄金测试用例生成
DeepEval 支持通过 CLI 自动生成合成黄金测试用例，支持多种生成方法：
```bash
deepeval generate golden --method [METHOD] --variation [VARIATION]
```
| 生成方法 | 说明 | 必需参数 |
|----------|------|----------|
| `DOCS` | 从文档生成 | `--documents` |
| `CONTEXTS` | 从上下文生成 | `--contexts-file` |
| `SCRATCH` | 从零开始生成 | `--num-goldens` |
| `GOLDENS` | 从现有黄金用例扩展 | `--goldens-file` |
资料来源：[deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)
### 测试用例结构
```python
from deepeval.test_case import LLMTestCase
test_case = LLMTestCase(
input="用户输入",
actual_output="实际输出",
expected_output="期望输出", # 可选
retrieval_context=["检索上下文"] # 可选
)
```
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
## 框架集成
DeepEval 支持与多种主流 AI 框架深度集成：
### 集成矩阵
| 框架 | 集成方式 | 追踪能力 | 本地评估 | 云端同步 |
|------|----------|----------|----------|----------|
| **OpenAI** | `@observe` / `trace()` | ✅ | ✅ | ✅ |
| **Anthropic** | `@observe` / `trace()` | ✅ | ✅ | ✅ |
| **LangChain** | `CallbackHandler` | ✅ | ✅ | ✅ |
| **LangGraph** | `CallbackHandler` | ✅ | ✅ | ✅ |
| **LlamaIndex** | `AsyncConfig` | ✅ | ✅ | ✅ |
| **Pydantic AI** | `instrument_pydantic_ai()` | ✅ | ✅ | ✅ |
| **CrewAI** | `instrument_crewai()` | ✅ | ✅ | ✅ |
| **Google ADK** | `instrument_google_adk()` | ✅ | ✅ | ✅ |
| **Strands** | `instrument_strands()` | ✅ | ✅ | ✅ |
| **AWS AgentCore** | `instrument_agentcore()` | ✅ | ✅ | ✅ |
资料来源：[deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)
### 集成架构
```mermaid
graph LR
A[用户代码] --> B[框架集成层]
B --> C[OTel 追踪]
B --> D[DeepEval 追踪]
C --> E[ContextAwareSpanProcessor]
D --> E
E --> F{评估状态判断}
F -->|评估中| G[REST 路由]
F -->|非评估| H[OTLP 导出]
G --> I[ConfidentSpanExporter]
H --> J[远程 OTel 端点]
```
## 命令行接口
### 可用命令
| 命令 | 说明 | 关键选项 |
|------|------|----------|
| `deepeval login` | 登录 Confident AI 平台 | - |
| `deepeval test run` | 运行测试套件 | `--folder`, pytest 集成 |
| `deepeval generate golden` | 生成黄金测试用例 | `--method`, `--variation` |
| `deepeval inspect` | 检查测试运行结果 | `--path`, `--folder` |
| `deepeval set-gemini` | 设置 Gemini 模型 | `--model` |
| `deepeval unset-gemini` | 取消 Gemini 配置 | `-x`, `--clear-secrets` |
资料来源：[deepeval/cli/main.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/main.py)
### 本地开发环境配置
```bash
# 复制环境变量模板
cp .env.example .env.local
# 编辑 .env.local（会被 git 忽略）
```
## 使用流程
### 基本使用流程
```mermaid
graph TD
A[安装 DeepEval] --> B[配置 API Key]
B --> C[编写测试用例]
C --> D[选择评估指标]
D --> E[定义阈值]
E --> F[运行评估]
F --> G{是否达标}
G -->|是| H[测试通过]
G -->|否| I[调整模型/提示词]
I --> F
```
### Pytest 集成示例
```python
import pytest
from deepeval import assert_test
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, SingleTurnParams
@assert_test
def test_case():
correctness_metric = GEval(
name="Correctness",
criteria="Determine if the 'actual output' is correct based on the 'expected output'.",
evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
threshold=0.5
)
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="You have 30 days to get a full refund at no extra cost.",
expected_output="We offer a 30-day full refund at no extra costs."
)
```
运行测试：
```bash
deepeval test run test_chatbot.py
```
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
### 非 Pytest 评估
```python
from deepeval import evaluate
from deepeval.metrics import AnswerRelevancyMetric
from deepeval.test_case import LLMTestCase
answer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="We offer a 30-day full refund at no extra costs.",
retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
)
evaluate([test_case], [answer_relevancy_metric])
```
## 云端集成
### Confident AI 平台
DeepEval 与 Confident AI 平台深度集成，提供以下功能：
| 功能 | 说明 |
|------|------|
| **测试报告** | 生成可分享的测试报告 |
| **数据集管理** | 管理评估数据集 |
| **LLM 应用追踪** | 追踪 LLM 应用的运行轨迹 |
| **生产环境监控** | 监控生产环境的评估指标 |
| **在线评估** | 支持在线实时评估 |
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
### 登录与同步
```bash
# 登录
deepeval login
# 运行测试 - 结果自动同步到云端
deepeval test run test_chatbot.py
```
## 技能集成
DeepEval 可以作为智能代理（Agent）的技能（Skill）使用：
### 安装方式
```bash
# 使用 skills 兼容的安装器
npx skills add confident-ai/deepeval --skill "deepeval"
# 或手动复制
cp skills/deepeval [agent_skills_directory]
```
### 前置条件
| 用途 | 必需包 | 配置 |
|------|--------|------|
| 本地评估 | `pip install -U deepeval` | - |
| 云端报告/追踪 | `deepeval login` | Confident AI API Key |
资料来源：[skills/README.md](https://github.com/confident-ai/deepeval/blob/main/skills/README.md)
## 测试结果检查
使用 `deepeval inspect` 命令检查测试运行结果：
```bash
deepeval inspect [PATH]
```
| 参数 | 说明 |
|------|------|
| `PATH` | 特定测试运行文件或包含测试结果的文件夹 |
| `-f, --folder` | 指定扫描文件夹，查找最新的测试运行文件 |
该命令会打开 TUI（文本用户界面）来检查保存的测试运行轨迹。
资料来源：[deepeval/cli/inspect.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/inspect.py)
## 性能与扩展性
### 异步评估支持
DeepEval 支持异步评估模式，适用于大规模评估场景：
```python
from deepeval.evaluate.configs import AsyncConfig
for golden in dataset.evals_iterator(
async_config=AsyncConfig(run_async=True),
metrics=[TaskCompletionMetric()],
):
task = asyncio.create_task(agent.run(golden.input))
dataset.evaluate(task)
```
### 并发控制
| 配置项 | 说明 |
|--------|------|
| `max_concurrent` | 最大并发数 |
| `max_retries` | 最大重试次数 |
资料来源：[deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)
## 版本与发布
DeepEval 使用语义化版本控制，当前版本信息可通过以下方式获取：
```python
import deepeval
print(deepeval.__version__)
```
| 版本属性 | 说明 |
|----------|------|
| `__version__` | 当前安装的版本号 |
| GitHub Releases | 发布历史和更新日志 |
## 许可证
DeepEval 采用开源许可证，具体信息请参阅 [LICENSE.md](https://github.com/confident-ai/deepeval/blob/master/LICENSE.md)。
## 相关资源
| 资源 | 链接 |
|------|------|
| 官方文档 | [deepeval.com/docs](https://deepeval.com/docs/getting-started) |
| GitHub 仓库 | [github.com/confident-ai/deepeval](https://github.com/confident-ai/deepeval) |
| Discord 社区 | [discord.gg/3SEyvpgu2f](https://discord.gg/3SEyvpgu2f) |
| Twitter | [@deepeval](https://x.com/deepeval) |
---
## 快速开始
### 相关页面
相关主题：[项目介绍](#page-introduction), [测试用例定义](#page-test-cases)
相关源码文件
以下源码文件用于生成本页说明：
- [deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)
- [deepeval/test_case/llm_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)
- [deepeval/evaluate/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/__init__.py)
- [deepeval/evaluate/evaluate.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/evaluate.py)
# 快速开始
DeepEval 的"快速开始"模块为开发者提供了在本地环境中快速上手 LLM 评估框架的最简路径。该模块封装了从测试用例定义、指标配置到评估执行的全流程，使开发者能够在几分钟内完成首个 LLM 应用的质量验证。通过深度集成 Pytest 生态，DeepEval 将 LLM 评估转化为标准化的单元测试流程，与现有开发工作流无缝衔接。资料来源：[README.md]()
## 核心概念
DeepEval 将 LLM 评估抽象为三个核心概念：**测试用例（Test Case）**、**评估指标（Metric）** 和 **断言验证（Assertion）**。测试用例定义了被评估 LLM 应用的输入、期望输出和上下文信息；评估指标则实现了具体的评估算法，如 G-Eval、答案相关性、幻觉检测等；断言验证将指标得分与阈值进行比较，以判断测试是否通过。资料来源：[deepeval/test_case/llm_test_case.py]()
## 工作流程
```mermaid
graph TD
A[创建测试文件] --> B[定义 LLMTestCase]
B --> C[配置评估指标]
C --> D[调用 assert_test]
D --> E[运行测试命令]
E --> F{测试通过?}
F -->|是| G[✅ 测试成功]
F -->|否| H[❌ 测试失败]
I[设置 OPENAI_API_KEY] -.-> A
```
## 环境准备
### 环境变量配置
在使用 DeepEval 之前，需要设置 LLM API 密钥。DeepEval 支持 OpenAI、Anthropic、Google Gemini 等多种模型提供商。以 OpenAI 为例，在终端中执行以下命令设置环境变量：
```bash
export OPENAI_API_KEY="..."
```
也可使用 `.env.local` 文件管理密钥：
```bash
cp .env.example .env.local
# 编辑 .env.local 文件（该文件已被 git 忽略）
```
资料来源：[README.md]()
### 安装 DeepEval
通过 pip 安装 DeepEval：
```bash
pip install -U deepeval
```
资料来源：[README.md]()
## 使用 Pytest 集成
### 创建测试文件
创建一个名为 `test_chatbot.py` 的测试文件：
```bash
touch test_chatbot.py
```
### 编写测试用例
打开 `test_chatbot.py` 并编写第一个端到端评估测试。DeepEval 将 LLM 应用视为黑盒进行评估：
```python
import pytest
from deepeval import assert_test
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, SingleTurnParams
def test_case():
correctness_metric = GEval(
name="Correctness",
criteria="Determine if the 'actual output' is correct based on the 'expected output'.",
evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
threshold=0.5
)
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="You have 30 days to get a full refund at no extra cost.",
expected_output="We offer a 30-day full refund at no extra costs.",
retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
)
assert_test(test_case, [correctness_metric])
```
资料来源：[README.md]()
### 核心参数说明
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `input` | str | 用户输入，模拟 LLM 应用的输入 |
| `actual_output` | str | LLM 应用的实际输出 |
| `expected_output` | str | 期望的正确答案 |
| `retrieval_context` | List[str] | 检索上下文，用于 RAG 评估 |
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `name` | str | 指标名称 |
| `criteria` | str | 评估标准的描述性文本 |
| `evaluation_params` | List[SingleTurnParams] | 评估所需的参数列表 |
| `threshold` | float | 通过阈值（0-1） |
资料来源：[deepeval/test_case/llm_test_case.py]()
### 运行测试
在终端中执行测试命令：
```bash
deepeval test run test_chatbot.py
```
测试通过时将显示成功消息，未通过则显示失败详情。
资料来源：[README.md]()
## 不使用 Pytest 集成
对于 Jupyter Notebook 环境或偏好命令式编程的场景，DeepEval 提供了 `evaluate()` 函数：
```python
from deepeval import evaluate
from deepeval.metrics import AnswerRelevancyMetric
from deepeval.test_case import LLMTestCase
answer_relevancy_metric = AnswerRelencyMetric(threshold=0.7)
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="We offer a 30-day full refund at no extra costs.",
retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
)
evaluate([test_case], [answer_relevancy_metric])
```
资料来源：[README.md]()
## 独立使用评估指标
DeepEval 高度模块化，允许在项目任何位置单独使用评估指标：
```python
from deepeval.metrics import AnswerRelevancyMetric
from deepeval.test_case import LLMTestCase
answer_relevancy_metric = AnswerRelencyMetric(threshold=0.7)
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="We offer a 30-day full refund at no extra costs.",
retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
)
answer_relevancy_metric.measure(test_case)
print(answer_relevancy_metric.score)
```
资料来源：[README.md]()
## 与 Confident AI 平台集成
DeepEval 支持与 Confident AI 平台的深度集成。登录后，测试结果将自动同步到云端：
```bash
deepeval login
```
登录后运行测试，结果自动上传：
```bash
deepeval test run test_chatbot.py
```
资料来源：[README.md]()
## 评估指标类型
| 指标名称 | 说明 | 适用场景 |
|----------|------|----------|
| GEval | 基于 LLM 的通用评估指标，支持自定义评估标准 | 通用质量评估 |
| AnswerRelevancyMetric | 答案相关性评估 | RAG 系统 |
| TaskCompletionMetric | 任务完成度评估 | AI Agent |
| HallucinationMetric | 幻觉检测 | 内容生成 |
资料来源：[README.md]()
## 关键源码结构
`deepeval.test_case` 模块导出了测试用例相关的核心类：
```python
from deepeval.test_case import LLMTestCase, SingleTurnParams
```
`deepeval.evaluate` 模块提供了评估执行接口：
```python
from deepeval import evaluate, assert_test
```
资料来源：[deepeval/test_case/__init__.py](), [deepeval/evaluate/__init__.py]()
---
## 系统架构
### 相关页面
相关主题：[核心模块结构](#page-core-modules), [评估指标体系](#page-metrics), [追踪系统](#page-tracing-system)
相关源码文件
以下源码文件用于生成本页说明：
- [deepeval/evaluate/evaluate.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/evaluate.py)
- [deepeval/evaluate/execute/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/__init__.py)
- [deepeval/evaluate/execute/e2e.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/e2e.py)
- [deepeval/evaluate/execute/agentic.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/agentic.py)
- [deepeval/constants.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/constants.py)
# 系统架构
## 概述
DeepEval 是一个开源的 LLM（大语言模型）评估框架，采用模块化设计实现评估流程的解耦与扩展。系统架构围绕**评估执行引擎**、**指标计算层**、**追踪系统**和**CLI命令接口**四大核心模块展开，支持端到端测试、代理评估、合成数据生成等多种评估场景。
DeepEval 的核心设计理念是将 LLM 应用视为黑盒，通过标准化测试用例（`LLMTestCase`）和可插拔的指标（Metric）系统，实现跨框架的通用评估能力。
## 整体架构图
```mermaid
graph TB
subgraph "CLI 层"
CLI[deepeval CLI]
Login[login 命令]
TestRun[test run 命令]
Generate[generate 命令]
Inspect[inspect 命令]
end
subgraph "评估执行层 (evaluate)"
Evaluate[evaluate 函数]
E2EExecutor[端到端执行器]
AgenticExecutor[代理执行器]
SyncRunner[同步运行器]
AsyncRunner[异步运行器]
end
subgraph "核心指标层 (metrics)"
GEval[G-Eval 指标]
TaskCompletion[任务完成度]
AnswerRelevancy[答案相关性]
Faithfulness[忠实度]
Hallucination[幻觉检测]
end
subgraph "追踪系统 (tracing)"
Observe[@observe 装饰器]
Trace[trace 上下文管理器]
SpanProcessor[Span 处理器]
ConfidentAI[Confident AI 云端]
end
subgraph "数据合成层 (synthesizer)"
Synthesizer[数据合成器]
ContextConstruction[上下文构建]
GoldenGenerator[黄金数据生成]
end
subgraph "集成层 (integrations)"
LangChain[LangChain]
LangGraph[LangGraph]
OpenAI[OpenAI]
Anthropic[Anthropic]
LlamaIndex[LlamaIndex]
CrewAI[CrewAI]
GoogleADK[Google ADK]
Strands[Strands]
end
CLI --> Evaluate
CLI --> Generate
CLI --> Login
CLI --> Inspect
Evaluate --> E2EExecutor
Evaluate --> AgenticExecutor
E2EExecutor --> SyncRunner
E2EExecutor --> AsyncRunner
AgenticExecutor --> SyncRunner
AgenticExecutor --> AsyncRunner
SyncRunner --> GEval
SyncRunner --> TaskCompletion
SyncRunner --> AnswerRelevancy
AsyncRunner --> GEval
AsyncRunner --> TaskCompletion
AsyncRunner --> AnswerRelevancy
Observe --> Trace
Trace --> SpanProcessor
SpanProcessor --> ConfidentAI
Synthesizer --> ContextConstruction
Synthesizer --> GoldenGenerator
LangChain --> Observe
LangGraph --> Observe
OpenAI --> Observe
Anthropic --> Observe
```
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
## 核心执行层
### 评估执行器类型
DeepEval 的评估执行层支持两种主要的执行模式，分别针对不同的评估场景：
| 执行器类型 | 适用场景 | 源码文件 |
|-----------|---------|---------|
| `E2EExecutor` | 端到端评估，将 LLM 应用视为黑盒 | `deepeval/evaluate/execute/e2e.py` |
| `AgenticExecutor` | 代理级别评估，支持工具调用追踪 | `deepeval/evaluate/execute/agentic.py` |
资料来源：[deepeval/evaluate/execute/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/__init__.py)
### 执行流程
```mermaid
graph LR
A[LLMTestCase 输入] --> B[创建测试用例]
B --> C{执行模式}
C -->|同步| D[SyncRunner 执行]
C -->|异步| E[AsyncRunner 执行]
D --> F[指标计算]
E --> F
F --> G[分数判定]
G --> H{是否通过阈值}
H -->|是| I[测试通过]
H -->|否| J[测试失败]
```
### E2E 执行器
E2E（端到端）执行器是 DeepEval 最基本的评估执行器。它接收标准化测试用例，按照配置的指标逐一计算评分，最终返回评估结果。
核心职责：
- 接收 `LLMTestCase` 测试用例
- 协调多个指标并行或串行计算
- 聚合评估结果并生成报告
资料来源：[deepeval/evaluate/execute/e2e.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/e2e.py)
### Agentic 执行器
代理执行器专门用于评估 LLM 代理（Agent）应用，支持追踪工具调用、多步推理和任务完成度等代理特有指标。
核心职责：
- 追踪代理的完整执行轨迹
- 记录工具调用序列和参数
- 评估任务完成度和步骤效率
资料来源：[deepeval/evaluate/execute/agentic.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/agentic.py)
## 指标系统
### 指标类型概览
DeepEval 提供了丰富的预置指标，涵盖 LLM 评估的多个维度：
| 指标类别 | 指标名称 | 用途 |
|---------|---------|-----|
| **通用指标** | GEval | 基于 LLM-as-Judge 的通用评估 |
| **答案质量** | Answer Relevancy | 评估答案与问题的相关性 |
| **答案质量** | Faithfulness | 评估答案与检索上下文的忠实度 |
| **答案质量** | Hallucination | 检测答案中的幻觉内容 |
| **代理指标** | Task Completion | 评估代理是否完成任务 |
| **代理指标** | Tool Correctness | 检查工具调用的正确性 |
| **代理指标** | Goal Accuracy | 衡量目标达成的准确性 |
| **代理指标** | Step Efficiency | 评估步骤效率 |
资料来源：[README.md - Metrics and Features](https://github.com/confident-ai/deepeval/blob/main/README.md)
### G-Eval 指标
G-Eval 是 DeepEval 的核心评估方法，基于最新的研究论文实现。它通过 LLM-as-Judge 范式进行自动化评估。
使用方式：
```python
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, SingleTurnParams
correctness_metric = GEval(
name="Correctness",
criteria="Determine if the 'actual output' is correct based on the 'expected output'.",
evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
threshold=0.5
)
```
### 任务完成度指标
专门用于评估 LLM 代理是否成功完成了给定任务：
```python
from deepeval.metrics import TaskCompletionMetric
from deepeval.tracing import trace
for golden in dataset.evals_iterator():
with trace(metrics=[TaskCompletionMetric()]):
client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": golden.input}],
)
```
## 追踪系统
### 追踪架构
DeepEval 的追踪系统采用 OpenTelemetry 兼容的设计，同时支持本地追踪和云端同步：
```mermaid
graph TD
A[被装饰的函数] --> B[@observe 装饰器]
B --> C[trace 上下文]
C --> D[当前 Span]
D --> E{Span 处理器}
E -->|本地模式| F[本地存储]
E -->|云端模式| G[Confident AI]
E -->|评估模式| H[Trace Manager]
F --> I[评估结果]
G --> I
H --> I
```
### 核心追踪组件
| 组件 | 功能 | 源码位置 |
|-----|------|---------|
| `@observe()` | 函数装饰器，自动创建追踪上下文 | `deepeval/tracing` |
| `trace()` | 上下文管理器，用于批量追踪 | `deepeval/tracing` |
| `update_current_span()` | 更新当前 span 的数据 | `deepeval/tracing` |
| `update_current_trace()` | 更新当前 trace 的全局数据 | `deepeval/tracing` |
资料来源：[README.md - Evals With Full Traceability](https://github.com/confident-ai/deepeval/blob/main/README.md)
### 追踪装饰器使用
```python
from deepeval.tracing import observe, update_current_span
from deepeval.test_case import LLMTestCase
@observe()
def inner_component(input: str):
output = "result"
update_current_span(test_case=LLMTestCase(input=input, actual_output=output))
return output
@observe()
def app(input: str):
return inner_component(input)
```
## 框架集成
### 集成矩阵
DeepEval 支持与主流 LLM 框架的无缝集成，通过统一的回调机制实现追踪和评估：
| 框架 | 集成方式 | 源码位置 |
|-----|---------|---------|
| OpenAI | 原生支持 | `deepeval.openai` |
| Anthropic | 原生支持 | `deepeval.anthropic` |
| LangChain | CallbackHandler | `deepeval/integrations/langchain` |
| LangGraph | CallbackHandler | `deepeval/integrations/langchain` |
| LlamaIndex | 异步集成 | `deepeval/integrations/llamaindex` |
| CrewAI | instrument_crewai | `deepeval/integrations/crewai` |
| Google ADK | instrument_google_adk | `deepeval/integrations/google_adk` |
| Strands | instrument_strands | `deepeval/integrations/strands` |
| AWS AgentCore | instrument_agentcore | `deepeval/integrations/agentcore` |
| Pydantic AI | 原生支持 | `deepeval/integrations/pydantic_ai` |
资料来源：[deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)
### 集成能力说明
每个集成支持四种级别的能力：
| 能力级别 | 说明 |
|---------|-----|
| **Bare** | 直接调用框架即可产生追踪，无需额外包装 |
| **`@observe` / `with trace(...)`** | 包装后追踪数据流入 DeepEval 原生上下文 |
| **`evals_iterator`** | 支持在数据集迭代器中使用指标评估 |
| **`deepeval test run`** | 支持 pytest 入口点的追踪评估 |
## CLI 命令系统
### 命令概览
DeepEval CLI 提供了丰富的命令行接口：
| 命令 | 功能 | 源码文件 |
|-----|------|---------|
| `deepeval login` | 登录 Confident AI 平台 | `deepeval/cli/main.py` |
| `deepeval test run` | 运行 Pytest 测试文件 | `deepeval/cli/test` |
| `deepeval generate` | 生成合成黄金数据 | `deepeval/cli/generate/command.py` |
| `deepeval set-model` | 设置默认评估模型 | `deepeval/cli/main.py` |
| `deepeval inspect` | TUI 检视测试结果 | `deepeval/cli/inspect.py` |
### 黄金数据生成
`deepeval generate` 命令支持多种数据生成方法：
```mermaid
graph TD
A[generate 命令] --> B{生成方法}
B -->|DOCS| C[从文档生成]
B -->|CONTEXTS| D[从上下文生成]
B -->|SCRATCH| E[从零生成]
B -->|GOLDENS| F[从已有黄金数据生成]
C --> G[文档分块]
D --> H[上下文质量过滤]
E --> I[任务描述生成]
F --> J[变体扩展]
G --> K[Synthesizer]
H --> K
I --> K
J --> K
K --> L[保存为 JSON/CSV]
```
生成方法配置：
| 方法 | 选项 | 说明 |
|-----|------|-----|
| DOCS | `--documents` | 从文档文件路径列表生成 |
| CONTEXTS | `--contexts-file` | 从上下文文件生成 |
| SCRATCH | `--num-goldens` | 从零开始生成指定数量 |
| GOLDENS | `--goldens-file` | 基于已有黄金数据生成变体 |
资料来源：[deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)
### inspect 命令
`deepeval inspect` 命令提供交互式 TUI 用于检视测试结果：
```python
# 查看最新测试运行结果
deepeval inspect
# 查看指定文件
deepeval inspect path/to/test_run_123.json
# 查看指定文件夹的最新结果
deepeval inspect --folder ./results
```
该命令支持可选的 `deepeval[inspect]` 扩展包，需要单独安装。
## 数据模型
### LLMTestCase
核心测试用例数据模型：
| 字段 | 类型 | 必需 | 说明 |
|-----|------|-----|-----|
| `input` | str | 是 | 测试输入 |
| `actual_output` | str | 是 | LLM 实际输出 |
| `expected_output` | str | 否 | 期望输出 |
| `retrieval_context` | List[str] | 否 | RAG 检索上下文 |
| `context` | List[Dict] | 否 | 多轮对话上下文 |
### SingleTurnParams 与 MultiTurnParams
评估参数枚举，用于指定 G-Eval 等指标的评估维度：
```python
from deepeval.test_case import SingleTurnParams, MultiTurnParams
# 单轮评估参数
SingleTurnParams.INPUT
SingleTurnParams.ACTUAL_OUTPUT
SingleTurnParams.EXPECTED_OUTPUT
SingleTurnParams.RETRIEVAL_CONTEXT
# 多轮评估参数
MultiTurnParams.INPUT
MultiTurnParams.ACTUAL_OUTPUT
MultiTurnParams.EXPECTED_OUTCOME
MultiTurnParams.RETRIEVAL_CONTEXT
MultiTurnParams.AGENT_ICONOGRAPHY
```
## 评估配置
### AsyncConfig
异步评估配置：
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|-----|
| `run_async` | bool | False | 是否启用异步执行 |
| `max_concurrent` | int | None | 最大并发数 |
```python
from deepeval.evaluate.configs import AsyncConfig
async_config = AsyncConfig(
run_async=True,
max_concurrent=5
)
```
### ContextConstructionConfig
合成数据生成的上下文构建配置：
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|-----|
| `max_contexts_per_document` | int | 5 | 每个文档最多生成上下文数 |
| `min_contexts_per_document` | int | 1 | 每个文档最少生成上下文数 |
| `chunk_size` | int | 1000 | 文档分块大小 |
| `chunk_overlap` | int | 200 | 分块重叠大小 |
| `context_quality_threshold` | float | 0.5 | 上下文质量阈值 |
| `context_similarity_threshold` | float | 0.5 | 上下文相似度阈值 |
| `max_retries` | int | 3 | 最大重试次数 |
## 常量定义
DeepEval 在 `deepeval/constants.py` 中定义了全局常量，包括：
- 默认阈值配置
- API 超时设置
- 缓存策略配置
- 日志级别定义
这些常量贯穿整个评估流程，确保行为的一致性和可配置性。
资料来源：[deepeval/constants.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/constants.py)
## 评估流程总结
```mermaid
graph TB
subgraph "1. 准备阶段"
A1[编写测试用例] --> A2[定义指标]
A2 --> A3[配置评估参数]
end
subgraph "2. 执行阶段"
A3 --> B1[创建评估器]
B1 --> B2{执行模式}
B2 -->|同步| B3[SyncRunner]
B2 -->|异步| B4[AsyncRunner]
B3 --> B5[指标并行计算]
B4 --> B5
end
subgraph "3. 评估阶段"
B5 --> C1[调用 LLM 评估]
C1 --> C2[分数聚合]
C2 --> C3[阈值判定]
end
subgraph "4. 报告阶段"
C3 --> D1[生成测试报告]
D1 --> D2[上传至 Confident AI]
D2 --> D3[本地保存 JSON]
end
```
## 最佳实践
### 测试用例设计
1. **输入多样化**：确保测试用例覆盖各种边界情况和典型场景
2. **明确期望输出**：为关键测试提供期望输出以便精确评估
3. **使用 RAG 上下文**：RAG 应用应提供 retrieval_context 参数
### 指标配置
1. **合理设置阈值**：根据业务需求调整 threshold 参数
2. **多指标组合**：复杂场景可组合使用多个指标
3. **使用 G-Eval**：对于主观性评估，优先使用 G-Eval
### 追踪配置
1. **使用 `@observe` 装饰器**：确保关键函数被追踪
2. **更新 span 数据**：在函数内使用 `update_current_span` 丰富追踪信息
3. **分离关注点**：将评估逻辑与业务逻辑解耦
---
## 核心模块结构
### 相关页面
相关主题：[系统架构](#page-architecture), [评估指标体系](#page-metrics), [测试用例定义](#page-test-cases)
相关源码文件
以下源码文件用于生成本页说明：
- [deepeval/metrics/base_metric.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/base_metric.py)
- [deepeval/metrics/indicator.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/indicator.py)
- [deepeval/test_case/utils.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/utils.py)
- [deepeval/config/settings.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/config/settings.py)
- [deepeval/synthesizer/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/__init__.py)
# 核心模块结构
## 概述
DeepEval 是一个面向大语言模型（LLM）应用的评估框架，采用了模块化架构设计。其核心模块结构围绕**指标系统（Metrics）**、**测试用例（Test Case）**、**追踪系统（Tracing）**和**配置管理（Configuration）**四大支柱构建。框架的核心设计理念是将 LLM 评估过程抽象为可组合、可扩展的组件，类似于 Pytest 在单元测试领域的角色，但专门针对 LLM 应用场景优化。
DeepEval 的架构设计允许开发者以两种主要方式使用该框架：一是集成到 Pytest 测试流程中，通过 `@assert_test` 装饰器实现声明式评估；二是作为独立库使用，通过 `evaluate()` 函数直接调用指标进行评估。这种双重使用模式体现了框架对不同开发工作流的包容性支持。
框架的核心价值在于其本地化评估能力——所有指标计算和 LLM 调用都可以在用户本地机器上运行，无需依赖外部云服务。同时，通过与 Confident AI 平台的集成，开发者可以选择性地将评估结果同步到云端进行可视化和协作分析。
## 核心模块架构图
```mermaid
graph TD
subgraph "核心层"
BM[base_metric.py
BaseMetric 基类]
IND[indicator.py
Indicator 指标系统]
TU[test_case/utils.py
LLMTestCase]
CFG[config/settings.py
配置管理]
end
subgraph "执行层"
SYN[Synthesizer
合成器]
EVAL[evaluate()
评估函数]
TRACE[Tracing
追踪系统]
end
subgraph "集成层"
LC[LangChain]
OAI[OpenAI]
ANTH[Anthropic]
LI[LlamaIndex]
CR[CrewAI]
GADK[Google ADK]
end
subgraph "CLI 层"
CMD[CLI Commands]
RUN[Test Runner]
GEN[Generate
生成器]
end
BM --> IND
IND --> TU
CFG --> BM
SYN --> BM
EVAL --> IND
TRACE --> BM
LC --> TRACE
OAI --> TRACE
ANTH --> TRACE
CMD --> SYN
CMD --> RUN
```
## 指标系统（Metrics）
### BaseMetric 基类架构
指标系统是 DeepEval 的核心评估单元，所有评估指标都继承自 `BaseMetric` 基类。基类定义了评估接口的通用契约，确保各类指标实现的一致性和可替换性。
`BaseMetric` 提供了以下核心能力：
1. **分数计算（measure）**：接收 `LLMTestCase` 对象，执行指标评估逻辑
2. **阈值判定（threshold）**：定义通过/失败的分数边界
3. **评分理由生成（reason）**：为分数提供人类可读的评估解释
4. **异步支持**：部分指标支持异步执行模式
资料来源：[deepeval/metrics/base_metric.py:1-50]()
### Indicator 指标实现
`indicator.py` 文件包含了 DeepEval 内置指标的具体实现。指标系统采用策略模式设计，每种指标封装了特定的评估逻辑。
**主要指标类型：**
| 指标类型 | 用途 | 评估维度 |
|---------|------|---------|
| GEval | 基于 LLM 的通用评估 | 可配置 criteria |
| TaskCompletionMetric | 任务完成度评估 | Agent 目标达成 |
| AnswerRelevancyMetric | 回答相关性评估 | RAG 管道输出质量 |
| FaithfulnessMetric | 事实一致性评估 | RAG 管道准确性 |
| HallucinationMetric | 幻觉检测评估 | 内容真实性 |
资料来源：[deepeval/metrics/indicator.py:1-100]()
### 指标执行流程
```mermaid
sequenceDiagram
participant User as 用户代码
participant Metric as Metric 实例
participant TC as LLMTestCase
participant LLM as LLM API
User->>Metric: measure(test_case)
Metric->>TC: 提取评估参数
Metric->>LLM: 调用 LLM-as-Judge
LLM-->>Metric: 返回评分结果
Metric->>Metric: 应用 threshold 判定
Metric-->>User: 返回 score 和 reason
```
## 测试用例系统（Test Case）
### LLMTestCase 数据结构
`LLMTestCase` 是 DeepEval 中表示测试用例的核心数据结构。它封装了评估所需的输入、输出和上下文信息。
**基础参数：**
| 参数名 | 类型 | 必需 | 说明 |
|--------|------|------|------|
| input | str | 是 | 测试输入/问题 |
| actual_output | str | 是 | LLM 实际输出 |
| expected_output | str | 否 | 期望的标准答案 |
| retrieval_context | List[str] | 否 | RAG 检索上下文 |
资料来源：[deepeval/test_case/utils.py:1-80]()
### 单轮与多轮参数
DeepEval 通过 `SingleTurnParams` 和 `MultiTurnParams` 枚举区分不同类型的评估参数：
- **SingleTurnParams**：适用于简单问答场景，参数包括 `ACTUAL_OUTPUT`、`EXPECTED_OUTPUT`
- **MultiTurnParams**：适用于对话系统，需要管理对话历史和轮次间的状态传递
这种设计使得框架能够灵活支持从简单问答到复杂多轮对话的各类评估场景。
## 配置管理体系
### 环境变量配置
DeepEval 实现了自动化的环境变量加载机制，配置文件位于 `deepeval/config/settings.py`。
**配置加载优先级（从高到低）：**
1. 进程环境变量（`os.environ`）
2. `.env.local` 文件
3. `.env` 文件
**禁用机制：**
设置环境变量 `DEPEVAL_DISABLE_DOTENV=1` 可禁用自动环境变量加载。
资料来源：[deepeval/config/settings.py:1-30]()
### 合成器配置
`ContextConstructionConfig` 是合成器用于从文档生成测试数据的配置类：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| chunk_size | int | 1000 | 文档分块大小 |
| chunk_overlap | int | 200 | 分块重叠区域 |
| max_contexts_per_document | int | 10 | 单文档最大上下文数 |
| min_contexts_per_document | int | 1 | 单文档最小上下文数 |
| context_quality_threshold | float | 0.5 | 上下文质量阈值 |
## 追踪与可观测性系统
### trace 上下文管理器
DeepEval 提供了 `trace` 上下文管理器用于包装 LLM 调用，实现端到端的评估追踪：
```python
from deepeval.tracing import trace
from deepeval.metrics import TaskCompletionMetric
with trace(metrics=[TaskCompletionMetric()]):
client.messages.create(model="claude-sonnet-4-5", ...)
```
这种设计允许在追踪上下文中自动捕获和评估所有 LLM 调用，无需修改业务代码。
资料来源：[deepeval/tracing/__init__.py:1-50]()
### @observe 装饰器
对于更细粒度的组件级评估，DeepEval 提供了 `@observe` 装饰器：
```python
from deepeval.tracing import observe, update_current_span
@observe()
def inner_component(input: str):
output = process(input)
update_current_span(test_case=LLMTestCase(input=input, actual_output=output))
return output
```
`update_current_span` 函数允许在任意嵌套层级更新当前追踪 span 的测试用例数据，实现组件级别的精确评估。
## 集成层架构
### 集成模式矩阵
DeepEval 的集成系统支持四种不同的评估模式：
| 模式 | 描述 | 使用场景 |
|------|------|---------|
| Bare | 直接调用框架，自动创建追踪 | 快速上手 |
| @observe / with trace | 包裹在追踪上下文中 | 需要细粒度控制 |
| evals_iterator | 数据集迭代器集成 | 批量评估 |
| deepeval test run | Pytest 集成 | 持续集成 |
### 支持的框架集成
DeepEval 官方支持以下框架的深度集成：
- **OpenAI**：原生客户端集成
- **Anthropic**：Claude 模型支持
- **LangChain**：回调处理器模式
- **LangGraph**：状态机评估
- **LlamaIndex**：异步评估支持
- **CrewAI**：多智能体评估
- **Google ADK**：Agent Development Kit
- **Strands**：自定义智能体框架
每种集成都通过统一的回调或包装机制接入 DeepEval 的追踪和评估系统。
## CLI 命令结构
### generate 命令
`deepeval generate` 命令用于从多种数据源生成合成测试数据：
```bash
deepeval generate --method docs --variation single_turn --documents ./docs
```
**支持的生成方法：**
| 方法 | 参数 | 说明 |
|------|------|------|
| DOCS | --documents | 从文档生成 |
| CONTEXTS | --contexts-file | 从预定义上下文生成 |
| SCRATCH | --num-goldens | 从零生成 |
| GOLDENS | --goldens-file | 基于现有测试数据扩充 |
资料来源：[deepeval/cli/generate/command.py:1-100]()
### test 命令
`deepeval test run` 命令执行 Pytest 测试并自动同步结果到 Confident AI 平台：
```bash
deepeval test run test_chatbot.py
```
该命令会自动加载 `.env.local` 和 `.env` 中的配置，执行测试后上传结果。
## 模块间依赖关系
```mermaid
graph LR
subgraph "依赖层级"
A[配置层
config/]
B[基础层
base_metric.py]
C[指标层
indicator.py]
D[测试用例层
test_case/]
E[合成器层
synthesizer/]
F[追踪层
tracing/]
G[CLI 层
cli/]
end
A --> B
B --> C
D --> C
A --> D
C --> E
F --> E
E --> G
C --> G
```
## 关键设计模式
### 1. 策略模式
所有指标实现统一的 `BaseMetric` 接口，允许在运行时动态替换评估策略：
```python
# 同一接口，不同实现
metrics = [
AnswerRelevancyMetric(threshold=0.7),
FaithfulnessMetric(threshold=0.8),
]
```
### 2. 装饰器模式
`@assert_test` 和 `@observe` 装饰器为普通函数添加评估能力，无需修改业务逻辑：
```python
@assert_test(llm_output_symbol="actual_output")
def my_llm_app():
return llm.invoke("Hello")
```
### 3. 上下文管理器模式
`trace` 上下文管理器自动管理追踪生命周期，确保资源正确释放：
```python
with trace(metrics=[metric]):
# 追踪范围内所有 LLM 调用自动被捕获
pass
```
## 扩展开发指南
### 创建自定义指标
要创建自定义指标，需继承 `BaseMetric` 并实现核心方法：
```python
class MyCustomMetric(BaseMetric):
def __init__(self, threshold=0.5):
self.threshold = threshold
def measure(self, test_case: LLMTestCase) -> float:
# 实现评估逻辑
score = self._evaluate(test_case)
self.score = score
self.reason = self._generate_reason(score)
return score
async def a_measure(self, test_case: LLMTestCase) -> float:
# 可选的异步实现
pass
```
### 框架集成开发
开发新的框架集成需要实现相应的回调接口：
1. 实现框架特定的回调处理器
2. 在回调中调用 `update_current_span` 更新追踪数据
3. 注册集成模块到 `deepeval/integrations/`
## 总结
DeepEval 的核心模块结构体现了清晰的关注点分离和高度的可扩展性。配置管理、指标系统、测试用例和追踪系统构成了框架的基础骨架，而丰富的集成层则将这一能力延伸到各类 LLM 应用开发框架中。通过统一的设计模式和标准化的接口，开发者可以轻松地添加自定义指标或接入新的框架，使 DeepEval 成为 LLM 应用评估的通用解决方案。
---
## 测试用例定义
### 相关页面
相关主题：[评估执行引擎](#page-evaluate-engine), [评估指标体系](#page-metrics), [数据集管理](#page-dataset-management)
相关源码文件
以下源码文件用于生成本页说明：
- [deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)
- [deepeval/test_case/llm_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)
- [deepeval/test_case/conversational_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/conversational_test_case.py)
- [deepeval/test_case/arena_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/arena_test_case.py)
- [deepeval/test_case/mcp.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/mcp.py)
# 测试用例定义
## 概述
在 DeepEval 框架中，测试用例是评估 LLM 应用质量的核心数据结构。测试用例定义了评估所需的输入、期望输出、实际输出以及相关的上下文信息，DeepEval 通过将这些测试用例与评估指标结合来执行自动化评估。
DeepEval 支持多种类型的测试用例，分别对应不同的评估场景：
| 测试用例类型 | 用途 | 适用场景 |
|-------------|------|---------|
| `LLMTestCase` | 单轮对话评估 | 简单的问答、文本生成任务 |
| `ConversationalTestCase` | 多轮对话评估 | 聊天机器人、对话系统 |
| `ArenaTestCase` | 对比评估 | 模型比较、A/B 测试 |
| `MCPTestCase` | MCP 协议评估 | Model Context Protocol 集成 |
资料来源：[deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)
## 核心组件
### LLMTestCase（单轮测试用例）
`LLMTestCase` 是 DeepEval 中最基础的测试用例类，用于定义单轮 LLM 交互的评估数据。
```python
from deepeval.test_case import LLMTestCase, SingleTurnParams
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="You have 30 days to get a full refund at no extra cost.",
expected_output="We offer a 30-day full refund at no extra costs.",
retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
)
```
资料来源：[deepeval/test_case/llm_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)
### 参数说明
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `input` | str | 是 | 用户输入或查询 |
| `actual_output` | str | 是 | LLM 应用的实际输出 |
| `expected_output` | str | 否 | 期望的正确答案 |
| `retrieval_context` | List[str] | 否 | RAG 系统的检索上下文 |
| `context` | List[str] | 否 | 额外的上下文信息 |
| `id` | str | 否 | 测试用例唯一标识符 |
### SingleTurnParams 枚举
`SingleTurnParams` 定义了单轮评估中可用的参数枚举，用于配置 G-Eval 等评估指标：
| 枚举值 | 对应属性 | 说明 |
|--------|----------|------|
| `INPUT` | `input` | 用户输入 |
| `ACTUAL_OUTPUT` | `actual_output` | 实际输出 |
| `EXPECTED_OUTPUT` | `expected_output` | 期望输出 |
| `RETRIEVAL_CONTEXT` | `retrieval_context` | 检索上下文 |
| `CONTEXT` | `context` | 额外上下文 |
资料来源：[deepeval/test_case/llm_test_case.py:1-50](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/llm_test_case.py)
## ConversationalTestCase（多轮对话测试用例）
### 概述
`ConversationalTestCase` 用于评估多轮对话场景，每个测试用例包含一系列消息序列。
```python
from deepeval.test_case import ConversationalTestCase, ConversationalTurn
test_case = ConversationalTestCase(
turns=[]
)
```
### 消息结构
多轮测试用例中的每条消息（turn）包含：
| 属性 | 类型 | 说明 |
|------|------|------|
| `messages` | List[Dict[str, str]] | 消息列表，格式为 `[{"role": "user"/"assistant", "content": "..."}]` |
| `expected_output` | str | 期望的最终输出 |
| `expected_tool_calls` | List[Dict] | 期望的工具调用（可选） |
资料来源：[deepeval/test_case/conversational_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/conversational_test_case.py)
## ArenaTestCase（对比评估测试用例）
### 概述
`ArenaTestCase` 用于模型对比评估场景，允许同时评估多个模型的响应。
```python
from deepeval.test_case import ArenaTestCase
arena_test_case = ArenaTestCase(
models=["gpt-4", "claude-3-opus"],
input="What is machine learning?",
expected_output="..."
)
```
### ArenaTurnParams 枚举
| 枚举值 | 说明 |
|--------|------|
| `INPUT` | 用户输入 |
| `EXPECTED_OUTPUT` | 期望输出 |
| `MODEL_OUTPUT` | 模型输出 |
| `RETRIEVAL_CONTEXT` | 检索上下文 |
资料来源：[deepeval/test_case/arena_test_case.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/arena_test_case.py)
## 测试用例执行流程
```mermaid
graph TD
A[创建测试用例] --> B{选择测试用例类型}
B -->|单轮| C[LLMTestCase]
B -->|多轮| D[ConversationalTestCase]
B -->|对比| E[ArenaTestCase]
C --> F[定义评估指标]
D --> F
E --> F
F --> G[调用 assert_test]
G --> H{评估结果}
H -->|通过| I[✅ 测试通过]
H -->|失败| J[❌ 测试失败]
```
资料来源：[deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)
## 使用示例
### 基本单轮评估
```python
import pytest
from deepeval import assert_test
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, SingleTurnParams
def test_case():
correctness_metric = GEval(
name="Correctness",
criteria="Determine if the 'actual output' is correct based on the 'expected output'.",
evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
threshold=0.5
)
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="You have 30 days to get a full refund at no extra cost.",
expected_output="We offer a 30-day full refund at no extra costs.",
retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
)
assert_test(test_case, [correctness_metric])
```
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/master/README.md)
### RAG 场景评估
```python
test_case = LLMTestCase(
input="What is the return policy?",
actual_output="Our return policy allows 30 days for returns.",
expected_output="30-day return policy",
retrieval_context=[
"All items can be returned within 30 days of purchase.",
"Items must be in original condition for a full refund."
]
)
```
### 带上下文的评估
```python
test_case = LLMTestCase(
input="Summarize the document",
actual_output="The document discusses...",
context=[
"Document Title: Annual Report 2024",
"Author: Company XYZ",
"Published: January 2024"
]
)
```
## CLI 执行
测试用例可以通过 DeepEval CLI 执行：
```bash
deepeval test run test_chatbot.py
```
其中 `test_chatbot.py` 包含使用 `assert_test` 定义的测试用例。
资料来源：[deepeval/cli/inspect.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/inspect.py)
## 与评估指标的集成
测试用例需要与评估指标结合使用才能完成评估。常用的评估指标包括：
| 指标名称 | 说明 | 适用场景 |
|---------|------|---------|
| `GEval` | 基于 LLM 的自动评估 | 通用评估 |
| `TaskCompletionMetric` | 任务完成度评估 | Agent 评估 |
| `AnswerRelevancyMetric` | 答案相关性评估 | RAG 评估 |
| `HallucinationMetric` | 幻觉检测 | 事实准确性评估 |
```python
from deepeval.metrics import GEval
metric = GEval(
name="Correctness",
criteria="评估实际输出与期望输出的一致性",
evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
threshold=0.5
)
```
## 数据隐私说明
当使用 DeepEval 平台时，所有测试用例数据会自动记录到平台。更多数据隐私信息请参考官方文档。
资料来源：[README.md](https://github.com/confident-ai/deepeval/blob/master/README.md)
---
## 评估指标体系
### 相关页面
相关主题：[测试用例定义](#page-test-cases), [评估执行引擎](#page-evaluate-engine)
相关源码文件
以下源码文件用于生成本页说明：
- [deepeval/metrics/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/__init__.py)
- [deepeval/metrics/base_metric.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/base_metric.py)
- [deepeval/metrics/g_eval/g_eval.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/g_eval/g_eval.py)
- [deepeval/metrics/rag/answer_relevancy/answer_relevancy.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/rag/answer_relevancy/answer_relevancy.py)
- [deepeval/metrics/rag/faithfulness/faithfulness.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/rag/faithfulness/faithfulness.py)
- [deepeval/metrics/agentic/task_completion/task_completion.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/metrics/agentic/task_completion/task_completion.py)
- [README.md](https://github.com/confident-ai/deepeval/blob/main/README.md)
- [deepeval/integrations/README.md](https://github.com/confident-ai/deepeval/blob/main/deepeval/integrations/README.md)
# 评估指标体系
## 概述
DeepEval 的评估指标体系是一套模块化的 LLM 应用评估框架，类似于 Pytest 但专为测试大语言模型应用而设计。该体系融合了最新的研究方法，通过 G-Eval、Task Completion、Answer Relevancy 等指标，利用 LLM-as-a-Judge 及其他 NLP 模型在本地机器上运行评估。资料来源：[README.md]()
评估指标体系支持多种使用方式，包括与 Pytest 集成、独立的 `evaluate()` 函数调用，以及通过 `evals_iterator()` 实现的端到端追踪评估。资料来源：[README.md]()
## 架构设计
### 核心组件关系
```mermaid
graph TD
A[LLMTestCase] --> B[Metric Base Class]
B --> C[GEval]
B --> D[RAG Metrics]
B --> E[Agentic Metrics]
D --> D1[AnswerRelevancyMetric]
D --> D2[FaithfulnessMetric]
E --> E1[TaskCompletionMetric]
E --> E2[ToolCorrectnessMetric]
F[评估结果] --> G[Score & Reason]
```
### 指标分类总览
| 类别 | 指标名称 | 用途 | 适用场景 |
|------|----------|------|----------|
| 通用框架 | GEval | 基于自定义标准的多维度评估 | 通用场景 |
| RAG 评估 | Answer Relevancy | 衡量 RAG 输出的相关性 | RAG 流水线 |
| RAG 评估 | Faithfulness | 评估输出与检索上下文的忠实度 | RAG 流水线 |
| Agentic 评估 | Task Completion | 评估 Agent 是否完成目标 | AI Agent |
| Agentic 评估 | Tool Correctness | 检查工具调用是否正确 | AI Agent |
| Agentic 评估 | Goal Accuracy | 衡量 Agent 目标达成准确度 | AI Agent |
资料来源：[README.md]()
## 指标基类设计
### BaseMetric 抽象基类
所有评估指标继承自 `BaseMetric` 基类，该基类定义了指标的核心接口和行为规范。资料来源：[deepeval/metrics/base_metric.py]()
#### 核心属性
| 属性 | 类型 | 说明 |
|------|------|------|
| name | str | 指标名称 |
| threshold | float | 通过阈值，范围 0-1 |
| score | float | 当前测量得分 |
| reason | str | 评分理由说明 |
| verbose | bool | 是否输出详细信息 |
#### 核心方法
| 方法 | 说明 |
|------|------|
| measure(test_case) | 执行评估并返回分数 |
| save() | 保存评估结果 |
| load() | 加载历史评估结果 |
```python
class BaseMetric(ABC):
"""所有评估指标的抽象基类"""
@abstractmethod
def measure(self, test_case: LLMTestCase) -> float:
"""执行评估的核心方法"""
pass
```
资料来源：[deepeval/metrics/base_metric.py]()
### 指标执行流程
```mermaid
sequenceDiagram
participant U as 用户
participant M as Metric
participant LLM as LLM API
participant TC as TestCase
U->>M: measure(test_case)
M->>TC: 提取评估参数
M->>LLM: 发送评估 Prompt
LLM-->>M: 评估结果
M->>M: 计算分数
M->>M: 生成 Reason
M-->>U: 返回 Score
```
## 通用评估框架
### GEval 指标
GEval 是 DeepEval 实现的一种基于最新研究的评估框架，通过 LLM-as-a-Judge 方式对 LLM 输出进行自动化评估。资料来源：[deepeval/metrics/g_eval/g_eval.py]()
#### 参数配置
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | str | 是 | 指标名称 |
| criteria | str | 是 | 评估标准描述 |
| evaluation_params | List[SingleTurnParams] | 是 | 评估所需参数 |
| threshold | float | 否 | 通过阈值，默认 0.5 |
| model | str | 否 | 使用的 LLM 模型 |
#### 使用示例
```python
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, SingleTurnParams
correctness_metric = GEval(
name="Correctness",
criteria="Determine if the 'actual output' is correct based on the 'expected output'.",
evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
threshold=0.5
)
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="You have 30 days to get a full refund at no extra cost.",
expected_output="We offer a 30-day full refund."
)
score = correctness_metric.measure(test_case)
print(f"Score: {score}, Reason: {correctness_metric.reason}")
```
资料来源：[deepeval/metrics/g_eval/g_eval.py]()
### GEval 工作原理
```mermaid
graph LR
A[输入 TestCase] --> B[构建 Chain-of-Thought Prompt]
B --> C[添加评估标准]
C --> D[调用 LLM API]
D --> E[LLM 返回评分]
E --> F[解析分数与理由]
F --> G[返回评估结果]
```
GEval 的核心优势在于其灵活性，允许用户定义任意评估标准，通过思维链方式引导 LLM 进行高质量评判。资料来源：[deepeval/metrics/g_eval/g_eval.py]()
## RAG 评估指标
RAG（检索增强生成）评估指标专门用于评估 RAG 流水线的性能，包括答案相关性、忠实度、上下文相关性等维度。资料来源：[deepeval/metrics/rag/answer_relevancy/answer_relevancy.py]()
### Answer Relevancy Metric（答案相关性）
答案相关性指标衡量 RAG 系统输出与输入查询之间的相关程度。资料来源：[deepeval/metrics/rag/answer_relevancy/answer_relevancy.py]()
#### 核心参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| threshold | float | 0.7 | 通过阈值 |
| model | str | None | 使用的大语言模型 |
| include_reason | bool | True | 是否包含评分理由 |
#### 实现原理
```python
answer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="We offer a 30-day full refund at no extra costs.",
retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
)
answer_relevancy_metric.measure(test_case)
```
答案相关性评估会分析输入、输出和检索上下文之间的关系，计算语义相似度得分。资料来源：[deepeval/metrics/rag/answer_relevancy/answer_relevancy.py]()
### Faithfulness Metric（忠实度）
忠实度指标评估 RAG 输出的事实准确性，即输出是否与检索到的上下文信息相符。资料来源：[deepeval/metrics/rag/faithfulness/faithfulness.py]()
#### 使用方式
```python
from deepeval.metrics import FaithfulnessMetric
from deepeval.test_case import LLMTestCase
faithfulness_metric = FaithfulnessMetric(threshold=0.8)
test_case = LLMTestCase(
input="公司年假政策是什么？",
actual_output="员工每年有15天带薪年假",
retrieval_context=["公司政策规定：员工第一年享有10天年假，工作满3年后增至15天"]
)
faithfulness_metric.measure(test_case)
```
该指标通过对比输出内容与检索上下文，识别潜在的幻觉（hallucination）问题。资料来源：[deepeval/metrics/rag/faithfulness/faithfulness.py]()
## Agentic 评估指标
Agentic 评估指标专注于 AI Agent 系统的评估，包括任务完成度、工具调用准确性、目标达成率等关键维度。资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()
### Task Completion Metric（任务完成度）
任务完成度是评估 Agent 是否成功达成用户目标的核心指标。资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()
#### 参数配置
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| threshold | float | 否 | 0.5 | 通过阈值 |
| model | str | 否 | None | 评估用模型 |
| include_reason | bool | 否 | True | 包含评分理由 |
| verbose | bool | 否 | False | 详细输出模式 |
#### 使用示例
```python
from deepeval.metrics import TaskCompletionMetric
task_completion_metric = TaskCompletionMetric(threshold=0.7)
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
with trace(metrics=[TaskCompletionMetric()]):
client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": golden.input}],
)
```
资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()
### Agentic 指标体系全景
```mermaid
graph TD
A[Agentic 评估] --> B[任务完成]
A --> C[工具使用]
A --> D[规划能力]
A --> E[参数正确性]
B --> B1[TaskCompletion]
B --> B2[GoalAccuracy]
C --> C1[ToolCorrectness]
C --> C2[ToolUse]
D --> D1[PlanAdherence]
D --> D2[PlanQuality]
D --> D3[StepEfficiency]
E --> E1[ArgumentCorrectness]
style A fill:#f9f,color:#000
style B fill:#bbf,color:#000
style C fill:#bbf,color:#000
style D fill:#bbf,color:#000
style E fill:#bbf,color:#000
```
| 指标名称 | 用途 | 资料来源 |
|----------|------|----------|
| Task Completion | 评估 Agent 是否完成目标 | [task_completion.py]() |
| Tool Correctness | 检查工具调用正确性 | README.md |
| Goal Accuracy | 衡量目标达成准确度 | README.md |
| Step Efficiency | 评估步骤效率 | README.md |
| Plan Adherence | 检查计划执行情况 | README.md |
| Plan Quality | 评估计划质量 | README.md |
| Tool Use | 测量工具使用质量 | README.md |
| Argument Correctness | 验证工具参数正确性 | README.md |
资料来源：[deepeval/metrics/agentic/task_completion/task_completion.py]()、[README.md]()
## 指标使用方式
### 与 Pytest 集成
通过 `@assert_test` 装饰器实现与 Pytest 的深度集成，这是 DeepEval 推荐的评估方式。资料来源：[README.md]()
```python
import pytest
from deepeval import assert_test
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, SingleTurnParams
@pytest.mark.parametrize(
"test_case",
[LLMTestCase(input="...", actual_output="...", expected_output="...")],
)
@assert_test
def test_correctness(test_case):
correctness_metric = GEval(
name="Correctness",
criteria="Determine if the 'actual output' is correct based on the 'expected output'.",
evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
threshold=0.5
)
return correctness_metric
```
### 独立评估模式
在 Jupyter Notebook 或脚本环境中，可以使用独立的 `evaluate()` 函数进行评估。资料来源：[README.md]()
```python
from deepeval import evaluate
from deepeval.metrics import AnswerRelevancyMetric
from deepeval.test_case import LLMTestCase
answer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="We offer a 30-day full refund at no extra costs.",
retrieval_context=["All customers are eligible for a 30 day full refund"]
)
evaluate([test_case], [answer_relevancy_metric])
```
### 追踪评估模式
使用 `evals_iterator()` 实现端到端追踪评估，适用于框架集成场景。资料来源：[deepeval/integrations/README.md]()
```python
from deepeval.tracing import observe
from deepeval.metrics import TaskCompletionMetric
@observe(metrics=[TaskCompletionMetric()])
def app(input: str):
# Agent 逻辑
return result
for golden in dataset.evals_iterator():
app(golden.input)
```
## 指标结果解读
### 评分机制
所有指标分数统一在 0-1 范围内，阈值参数决定测试是否通过。资料来源：[README.md]()
| 分数范围 | 含义 | 行为 |
|----------|------|------|
| 0.0-0.5 | 低质量输出 | 通常不满足阈值 |
| 0.5-0.7 | 中等质量 | 取决于阈值设置 |
| 0.7-1.0 | 高质量输出 | 通常满足阈值 |
### Reason 字段
每个指标在评估后会生成 `reason` 字段，提供 LLM 评判的详细解释，便于调试和理解评估逻辑。资料来源：[deepeval/metrics/base_metric.py]()
```python
print(metric.score) # 0.85
print(metric.reason) # "The response correctly addresses the user's question..."
```
## 集成框架支持
DeepEval 指标体系支持多种主流 LLM 应用框架的集成评估。资料来源：[deepeval/integrations/README.md]()
| 框架 | 集成方式 | 评估模式 |
|------|----------|----------|
| OpenAI | 原生追踪 | Bare + @observe + evals_iterator |
| Anthropic | 原生追踪 | Bare + @observe + evals_iterator |
| LangChain | CallbackHandler | evals_iterator |
| LangGraph | CallbackHandler | evals_iterator |
| LlamaIndex | AsyncConfig | evals_iterator |
| CrewAI | instrument_crewai() | evals_iterator |
| Pydantic AI | 集成 | evals_iterator |
| Google ADK | instrument_google_adk() | evals_iterator |
| Strands | instrument_strands() | evals_iterator |
| AWS AgentCore | instrument_agentcore() | evals_iterator |
资料来源：[deepeval/integrations/README.md]()
## 最佳实践
### 指标选择指南
| 应用场景 | 推荐指标组合 |
|----------|--------------|
| RAG 流水线 | AnswerRelevancy + Faithfulness |
| AI Agent | TaskCompletion + ToolCorrectness |
| 通用对话 | GEval（自定义标准）|
| 多轮对话 | Conversational Metrics |
### 阈值设置建议
1. **保守设置**：threshold=0.7 适用于生产环境，确保高质量输出
2. **宽松设置**：threshold=0.5 适用于开发阶段，快速迭代
3. **渐进调整**：根据历史评估结果逐步调整阈值
### 环境变量配置
DeepEval 自动加载环境变量，优先级为：进程环境变量 > .env.local > .env。可通过 `DEEPEVAL_DISABLE_DOTENV=1` 禁用自动加载。资料来源：[README.md]()
## 扩展开发
开发者可以通过继承 `BaseMetric` 基类创建自定义评估指标：
```python
from deepeval.metrics.base_metric import BaseMetric
from deepeval.test_case import LLMTestCase
class CustomMetric(BaseMetric):
def __init__(self, threshold: float = 0.5):
self.threshold = threshold
def measure(self, test_case: LLMTestCase) -> float:
# 自定义评估逻辑
score = self._evaluate(test_case)
self.score = score
return score
```
资料来源：[deepeval/metrics/base_metric.py]()
## 总结
DeepEval 的评估指标体系提供了从通用到专用的完整评估能力，通过模块化设计支持灵活组合和扩展。G-Eval 作为核心评估框架，结合 RAG 和 Agentic 专用指标，能够全面覆盖各类 LLM 应用的评估需求。开发者可以根据具体场景选择合适的指标组合，并通过 Pytest 集成、独立调用或追踪模式等多种方式执行评估。
---
## 评估执行引擎
### 相关页面
相关主题：[测试用例定义](#page-test-cases), [评估指标体系](#page-metrics), [追踪系统](#page-tracing-system)
相关源码文件
以下源码文件用于生成本页说明：
- [deepeval/evaluate/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/__init__.py)
- [deepeval/evaluate/evaluate.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/evaluate.py)
- [deepeval/evaluate/api.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/api.py)
- [deepeval/evaluate/execute/e2e.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/e2e.py)
- [deepeval/evaluate/execute/agentic.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/execute/agentic.py)
- [deepeval/evaluate/console_report.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/console_report.py)
- [deepeval/evaluate/configs.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/evaluate/configs.py)
# 评估执行引擎
## 概述
评估执行引擎是 DeepEval 框架的核心组件，负责驱动 LLM 应用的质量评估流程。它封装了评估的完整生命周期，包括测试用例加载、指标计算、结果收集与报告生成。该引擎支持两种主要的评估模式：端到端评估（E2E）和代理式评估（Agentic），能够适应不同的测试场景和集成需求。资料来源：[README.md]()
```mermaid
graph TD
A[评估执行引擎] --> B[端到端评估 E2E]
A --> C[代理式评估 Agentic]
B --> D[Test Case 加载]
B --> E[指标计算]
B --> F[结果收集]
C --> G[Trace 追踪]
C --> H[Span 跨度]
C --> I[工具调用验证]
```
## 核心架构
### 模块组织结构
评估执行引擎的代码位于 `deepeval/evaluate/` 目录下，采用分层架构设计：
| 模块路径 | 功能职责 |
|---------|---------|
| `__init__.py` | 公共 API 导出 |
| `evaluate.py` | 核心评估入口函数 |
| `api.py` | 评估 API 接口定义 |
| `execute/e2e.py` | 端到端评估执行器 |
| `execute/agentic.py` | 代理式评估执行器 |
| `console_report.py` | 控制台报告生成 |
| `configs.py` | 评估配置管理 |
### 评估入口函数
评估执行引擎的主入口是 `evaluate()` 函数，支持同步和异步两种调用模式。开发者可以通过该函数批量执行测试用例并获取评估结果。资料来源：[deepeval/evaluate/__init__.py]()
```python
from deepeval import evaluate
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase
# 创建评估指标
correctness_metric = GEval(
name="Correctness",
criteria="Determine if the 'actual output' is correct based on the 'expected output'.",
evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
threshold=0.5
)
# 创建测试用例
test_case = LLMTestCase(
input="What if these shoes don't fit?",
actual_output="You have 30 days to get a full refund at no extra cost.",
expected_output="We offer a 30-day full refund at no extra costs."
)
# 执行评估
evaluate([test_case], [correctness_metric])
```
## 评估模式
### 端到端评估（E2E）
端到端评估将 LLM 应用视为黑盒，通过输入输出对进行质量验证。这种模式特别适用于快速迭代开发和回归测试场景，无需深入了解应用内部实现。资料来源：[deepeval/evaluate/execute/e2e.py]()
**工作流程：**
```mermaid
graph LR
A[输入 TestCase] --> B[加载指标]
B --> C[执行指标评估]
C --> D[收集评分]
D --> E[生成报告]
```
端到端评估的核心流程如下：
1. 接收 `LLMTestCase` 测试用例对象
2. 初始化指定的评估指标
3. 按顺序或并发执行各项指标计算
4. 汇总所有指标得分
5. 与阈值比较判断通过/失败
6. 生成结构化结果输出
### 代理式评估（Agentic）
代理式评估针对 AI 代理应用设计，不仅验证最终输出，还追踪整个执行过程，包括工具调用、决策路径和中间状态。这种模式适用于复杂的多步骤任务评估。资料来源：[deepeval/evaluate/execute/agentic.py]()
**追踪机制：**
代理式评估利用 OpenTelemetry 标准的 Trace 和 Span 来记录执行轨迹。每个代理操作被封装为独立的 Span，通过父-子关系形成完整的调用链。这种设计允许评估引擎回溯任意时间点的执行状态，并针对特定操作进行指标验证。
```python
from deepeval.tracing import trace
from deepeval.metrics import TaskCompletionMetric
# 使用 trace 上下文包装评估
for golden in dataset.evals_iterator():
with trace(metrics=[TaskCompletionMetric()]):
client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": golden.input}],
)
```
## 配置系统
### 评估配置类
DeepEval 提供 `EvaluationConfig` 类用于定制评估行为，支持细粒度的执行控制。资料来源：[deepeval/evaluate/configs.py]()
| 配置项 | 类型 | 说明 |
|-------|------|------|
| `run_async` | bool | 是否启用异步执行模式 |
| `max_concurrent` | int | 最大并发评估数 |
| `use_cached_results` | bool | 是否使用缓存的评估结果 |
| `print_results` | bool | 是否在控制台打印结果 |
| `save_results` | bool | 是否保存评估结果到文件 |
### 异步配置
对于需要处理大量测试用例的场景，引擎支持异步并发执行。通过 `AsyncConfig` 类可以控制并发度和超时行为。资料来源：[deepeval/evaluate/configs.py]()
```python
from deepeval.evaluate.configs import AsyncConfig
async_config = AsyncConfig(
run_async=True,
max_concurrent=10, # 最大并发任务数
timeout=300 # 单个任务超时时间（秒）
)
```
## 报告生成
### 控制台报告
评估完成后，引擎自动生成控制台报告，包含测试用例总数、通过率、各指标得分分布等关键信息。资料来源：[deepeval/evaluate/console_report.py]()
**报告内容包括：**
- 整体通过率统计
- 各指标得分详情
- 失败用例的错误信息
- 执行耗时分析
- 资源使用情况（如适用）
### 结构化输出
评估结果以标准化的数据结构返回，便于后续分析和集成：
```python
result = evaluate([test_case], [correctness_metric])
# 结果对象包含以下属性
print(result.success) # 整体是否通过
print(result.metrics) # 各指标得分
print(result.duration) # 执行耗时
print(result.error) # 错误信息（如有）
```
## 集成方式
### Pytest 集成
DeepEval 与 Pytest 无缝集成，通过 `@assert_test` 装饰器将评估逻辑嵌入标准测试用例。资料来源：[README.md]()
```python
import pytest
from deepeval import assert_test
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, SingleTurnParams
@pytest.fixture
def correctness_metric():
return GEval(
name="Correctness",
criteria="Determine if the 'actual output' is correct.",
evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
threshold=0.5
)
@assert_test(assertion_fn=correctness_metric)
def test_chatbot_response(test_case: LLMTestCase):
return test_case
```
### 框架集成
评估引擎支持主流 LLM 框架的自动检测和集成，包括 OpenAI、Anthropic、LangChain、LangGraph、LlamaIndex、Pydantic AI、CrewAI 等。资料来源：[deepeval/integrations/README.md]()
**集成特性矩阵：**
| 框架 | Bare 模式 | @observe 包装 | evals_iterator | pytest 集成 |
|------|-----------|--------------|----------------|-------------|
| OpenAI | ✅ | ✅ | ✅ | ✅ |
| Anthropic | ✅ | ✅ | ✅ | ✅ |
| LangChain | ✅ | ✅ | ✅ | ✅ |
| LangGraph | ✅ | ✅ | ✅ | ✅ |
| LlamaIndex | ✅ | ✅ | ✅ | ✅ |
| Pydantic AI | ✅ | ✅ | ✅ | ✅ |
| CrewAI | ✅ | ✅ | ✅ | ✅ |
## CLI 命令行支持
评估执行引擎可通过 `deepeval` CLI 调用，支持自动化测试运行和结果持久化。资料来源：[deepeval/cli/main.py]()
**常用命令：**
```bash
# 运行测试文件
deepeval test run test_chatbot.py
# 运行特定测试函数
deepeval test run test_chatbot.py::test_case
# 指定报告输出目录
deepeval test run test_chatbot.py --folder ./results
# 登录 Confident AI 平台同步结果
deepeval login
deepeval test run test_chatbot.py
```
## 执行流程图
```mermaid
sequenceDiagram
participant U as 用户代码
participant E as 评估引擎
participant M as 指标模块
participant R as 报告生成器
U->>E: evaluate(test_cases, metrics)
E->>E: 初始化评估配置
E->>M: 加载评估指标
loop 每个测试用例
E->>M: 执行指标计算
M-->>E: 返回指标得分
E->>E: 与阈值比较
end
E->>R: 生成评估报告
R-->>U: 返回评估结果
```
## 最佳实践
### 性能优化建议
1. **批量评估**：将多个相关测试用例一起评估，减少 LLM 调用开销
2. **并发控制**：根据 API 速率限制调整 `max_concurrent` 参数
3. **指标选择**：仅使用必要的评估指标，避免不必要的计算
4. **缓存利用**：在迭代开发中使用 `use_cached_results` 跳过未变更用例
### 测试设计原则
1. **单一职责**：每个测试用例应验证单一质量维度
2. **明确阈值**：为每个指标设置合理的通过阈值
3. **真实数据**：使用生产环境分布的测试数据
4. **分层评估**：结合端到端和代理式评估全面覆盖
## 扩展机制
评估执行引擎支持自定义扩展，开发者可以实现以下接口：
- **自定义指标**：继承 `BaseMetric` 类实现特定领域的评估逻辑
- **自定义报告器**：实现 `BaseReporter` 接口添加新的输出格式
- **自定义集成**：通过回调机制接入新的 LLM 框架
---
*本文档基于 DeepEval v0.2+ 版本编写，随着框架更新，部分 API 可能发生变化。*
---
## 数据集管理
### 相关页面
相关主题：[合成数据生成](#page-synthetic-data), [测试用例定义](#page-test-cases)
相关源码文件
以下源码文件用于生成本页说明：
- [deepeval/dataset/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/__init__.py)
- [deepeval/dataset/dataset.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/dataset.py)
- [deepeval/dataset/golden.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/golden.py)
- [deepeval/dataset/api.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/api.py)
- [deepeval/dataset/test_run_tracer.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/dataset/test_run_tracer.py)
- [deepeval/test_case/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/test_case/__init__.py)
- [deepeval/synthesizer/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/__init__.py)
# 数据集管理
## 概述
DeepEval 的数据集管理模块是整个 LLM 评估框架的核心基础设施，负责管理和组织用于评估大型语言模型应用的测试数据。该模块支持多种数据格式导入、测试用例的组织与管理、以及与 Confident AI 平台的同步功能。
数据集管理的主要职责包括：
- **测试用例管理**：创建、组织和管理 `LLMTestCase` 对象
- **迭代器功能**：通过 `evals_iterator()` 遍历数据集并执行评估
- **Golden 数据集**：管理高质量的参考数据集（goldens）用于评估
- **评估结果追踪**：记录和回溯每次评估运行的结果
## 核心组件
### LLMTestCase
`LLMTestCase` 是 DeepEval 中用于定义单个测试用例的基础数据模型。每个测试用例包含输入、期望输出和实际输出等关键字段。
```python
from deepeval.test_case import LLMTestCase, SingleTurnParams
test_case = LLMTestCase(
input="用户输入内容",
actual_output="LLM实际输出",
expected_output="期望的正确答案",
retrieval_context=["上下文文档1", "上下文文档2"]
)
```
**主要参数说明：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `input` | str | 是 | 传入 LLM 应用的输入/提示词 |
| `actual_output` | str | 是 | LLM 应用的真实输出 |
| `expected_output` | str | 否 | 期望的参考答案 |
| `retrieval_context` | List[str] | 否 | RAG 场景中的检索上下文 |
| `context` | List[str] | 否 | 一般上下文信息 |
### Golden 数据集
Golden 数据集是经过精心准备的高质量参考数据集，用于验证 LLM 应用的输出质量。
```python
from deepeval.synthesizer import Synthesizer
synthesizer = Synthesizer(model=model)
synthesizer.generate_goldens_from_docs(
document_paths=["path/to/doc.pdf"],
include_expected_output=True,
max_goldens_per_context=5
)
```
## 数据集迭代与评估
### evals_iterator 方法
`evals_iterator()` 是数据集的核心迭代方法，支持在遍历数据集的同时执行评估。该方法与各种框架集成兼容，支持端到端和组件级别的评估。
```python
from deepeval.metrics import TaskCompletionMetric
# 端到端评估
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
invoke({"prompt": golden.input})
```
### 异步评估配置
DeepEval 支持异步评估模式，适用于大规模数据集的高效处理：
```python
from deepeval.evaluate.configs import AsyncConfig
from deepeval.metrics import TaskCompletionMetric
async_config = AsyncConfig(run_async=True, max_concurrent=10)
for golden in dataset.evals_iterator(
async_config=async_config,
metrics=[TaskCompletionMetric()],
):
task = asyncio.create_task(agent.run(golden.input))
dataset.evaluate(task)
```
### 异步配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `run_async` | bool | False | 启用异步模式 |
| `max_concurrent` | int | 1 | 最大并发任务数 |
| `timeout` | int | None | 单个任务超时时间（秒） |
## 框架集成
### OpenAI 集成
```python
from deepeval.anthropic import Anthropic
from deepeval.tracing import trace
from deepeval.metrics import TaskCompletionMetric
client = Anthropic()
for golden in dataset.evals_iterator():
with trace(metrics=[TaskCompletionMetric()]):
client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": golden.input}],
)
```
### LangChain 集成
```python
from deepeval.integrations.langchain import CallbackHandler
from deepeval.metrics import TaskCompletionMetric
for golden in dataset.evals_iterator():
llm.invoke(
golden.input,
config={"callbacks": [CallbackHandler(metrics=[TaskCompletionMetric()])]},
)
```
### LangGraph 集成
```python
from deepeval.integrations.langchain import CallbackHandler
from deepeval.metrics import TaskCompletionMetric
for golden in dataset.evals_iterator():
agent.invoke(
{"messages": [{"role": "user", "content": golden.input}]},
config={"callbacks": [CallbackHandler(metrics=[TaskCompletionMetric()])]},
)
```
### LlamaIndex 集成
```python
import asyncio
from deepeval.evaluate.configs import AsyncConfig
from deepeval.metrics import TaskCompletionMetric
for golden in dataset.evals_iterator(
async_config=AsyncConfig(run_async=True),
metrics=[TaskCompletionMetric()],
):
task = asyncio.create_task(agent.run(golden.input))
dataset.evaluate(task)
```
## 数据集生成
DeepEval 提供多种方式生成测试数据集：
| 生成方法 | 说明 | 适用场景 |
|---------|------|---------|
| `DOCS` | 从文档中提取 | 已有知识库文档 |
| `CONTEXTS` | 从上下文中生成 | 结构化上下文数据 |
| `SCRATCH` | 从零开始生成 | 无预定义数据 |
| `GOLDENS` | 基于现有数据扩展 | 已有少量高质量数据 |
### 单轮与多轮变体
数据集支持单轮（Single Turn）和多轮（Multi-turn Conversational）两种评估模式：
```python
from deepeval.cli.generate.utils import GoldenVariation
# 单轮评估
synthesizer.generate_goldens_from_docs(
document_paths=document_paths,
include_expected_output=True
)
# 多轮对话评估
synthesizer.generate_conversational_goldens_from_docs(
document_paths=document_paths,
include_expected_outcome=True
)
```
## 评估工作流
```mermaid
graph TD
A[准备数据集] --> B[创建 LLMTestCase]
B --> C[配置评估指标]
C --> D[使用 evals_iterator 遍历]
D --> E{框架类型}
E -->|LangChain| F[CallbackHandler]
E -->|OpenAI| G[trace 上下文]
E -->|LlamaIndex| H[AsyncConfig]
F --> I[执行评估]
G --> I
H --> I
I --> J[记录测试结果]
J --> K[同步至 Confident AI]
```
## 测试运行追踪
### Test Run Tracer
`TestRunTracer` 负责记录每次评估运行的关键信息，包括：
- 测试用例执行状态
- 评估指标得分
- 执行时间和资源消耗
- 错误和异常信息
### 评估结果保存
评估结果可以通过 `deepeval test run` 命令自动保存：
```bash
deepeval test run test_chatbot.py
```
结果文件格式为 `test_run_*.json`，可通过 `deepeval inspect` 命令查看：
```bash
deepeval inspect # 查看最新运行结果
deepeval inspect path/to/file.json # 查看指定文件
deepeval inspect -f ./results # 查看指定目录
```
## 配置管理
### 环境变量
| 变量名 | 说明 |
|--------|------|
| `DEEPEVAL_RESULTS_FOLDER` | 评估结果保存目录 |
| `DEEPEVAL_API_KEY` | Confident AI API 密钥 |
### .env 配置
DeepEval 支持 `.env.local` 文件进行本地配置：
```bash
cp .env.example .env.local
# 编辑 .env.local 文件
```
## 与 Confident AI 集成
DeepEval 数据集管理与 Confident AI 平台深度集成，提供以下云端功能：
- **数据集存储**：云端存储和管理测试数据集
- **评估报告**：生成可分享的评估报告
- **迭代追踪**：比较不同版本的 LLM 应用表现
- **协作功能**：团队成员共享和协作测试数据集
登录命令：
```bash
deepeval login
```
## 最佳实践
1. **数据集质量**：确保 Golden 数据集包含多样化、高质量的测试用例
2. **评估指标选择**：根据应用场景选择合适的评估指标
3. **异步处理**：大规模数据集建议使用异步模式提高效率
4. **结果回溯**：定期保存和审查评估结果用于持续优化
5. **框架集成**：选择最适合你技术栈的框架集成方式
---
## 合成数据生成
### 相关页面
相关主题：[数据集管理](#page-dataset-management)
相关源码文件
以下源码文件用于生成本页说明：
- [deepeval/synthesizer/synthesizer.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/synthesizer.py)
- [deepeval/synthesizer/base_synthesizer.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/base_synthesizer.py)
- [deepeval/synthesizer/schema.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/schema.py)
- [deepeval/cli/generate/command.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/cli/generate/command.py)
- [deepeval/synthesizer/config.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/synthesizer/config.py)
# 合成数据生成
## 概述
合成数据生成（Synthetic Data Generation）是 DeepEval 框架中用于自动创建测试用例的核心功能。该功能通过 LLM 自动生成高质量的测试数据，包括单轮问答和多轮对话场景，帮助开发者快速构建评估数据集。
Synthesizer（合成器）是实现这一功能的核心类，它封装了多种生成策略，支持从文档、上下文、已有测试用例或完全空白状态生成合成数据。资料来源：[deepeval/synthesizer/synthesizer.py:1-50]()
## 核心架构
### 类结构
```mermaid
graph TD
A[Synthesizer] --> B[BaseSynthesizer]
B --> C[可配置生成策略]
B --> D[异步/同步模式]
A --> E[ContextConstructionConfig]
A --> F[StylingConfig]
A --> G[ConversationalStylingConfig]
```
### 数据模型
合成数据生成涉及以下核心数据模型：
| 模型类 | 用途 | 关键属性 |
|--------|------|----------|
| `GoldenContext` | 单轮对话上下文 | `input`, `expected_output`, `context` |
| `ScenarioContext` | 多轮对话场景 | `scenario`, `conversational_task`, `participant_roles` |
| `ConversationTurn` | 单轮对话 | `input`, `expected_output` |
| `ConversationRound` | 多轮对话 | `turns`, `expected_outcome` |
资料来源：[deepeval/synthesizer/schema.py:1-100]()
## 生成方法
### 四种生成策略
DeepEval 支持四种主要的合成数据生成方法：
| 方法 | 枚举值 | 描述 |
|------|--------|------|
| 文档生成 | `GenerationMethod.DOCS` | 从源文档中提取上下文并生成测试用例 |
| 上下文生成 | `GenerationMethod.CONTEXTS` | 基于预定义的上下文生成测试用例 |
| 从零生成 | `GenerationMethod.SCRATCH` | 无外部输入，完全由 LLM 创意生成 |
| Goldens 扩展 | `GenerationMethod.GOLDENS` | 基于已有测试用例进行变体扩展 |
资料来源：[deepeval/cli/generate/command.py:1-80]()
### 单轮与多轮对话
```mermaid
graph LR
A[生成请求] --> B{对话类型}
B -->|单轮| C[GoldenVariation.SINGLE_TURN]
B -->|多轮| D[GoldenVariation.CONVERSATIONAL]
C --> E[generate_goldens_from_*]
D --> F[generate_conversational_goldens_from_*]
```
| 变体类型 | 枚举值 | 生成方法 |
|----------|--------|----------|
| 单轮对话 | `GoldenVariation.SINGLE_TURN` | `generate_goldens_from_docs/contexts/scratch/goldens` |
| 多轮对话 | `GoldenVariation.CONVERSATIONAL` | `generate_conversational_goldens_from_*` |
## Synthesizer 类
### 主要方法
| 方法名 | 参数 | 返回值 | 说明 |
|--------|------|--------|------|
| `generate_goldens_from_docs()` | `document_paths`, `context_construction_config` | `List[GoldenContext]` | 从文档生成单轮测试用例 |
| `generate_conversational_goldens_from_docs()` | `document_paths`, `context_construction_config` | `List[ScenarioContext]` | 从文档生成多轮测试用例 |
| `generate_goldens_from_contexts()` | `contexts`, `max_goldens_per_context` | `List[GoldenContext]` | 从上下文生成单轮测试用例 |
| `generate_goldens_from_scratch()` | `num_goldens` | `List[GoldenContext]` | 从零生成单轮测试用例 |
| `generate_goldens_from_goldens()` | `goldens`, `max_goldens_per_golden` | `List[GoldenContext]` | 扩展已有测试用例 |
| `save_as()` | `file_type`, `directory`, `file_name` | `str` | 保存结果到文件 |
资料来源：[deepeval/synthesizer/synthesizer.py:100-300]()
### 初始化参数
```python
Synthesizer(
model: Optional[Any] = None, # 使用的 LLM 模型
async_mode: bool = False, # 是否启用异步模式
max_concurrent: int = 10, # 最大并发数
styling_config: Optional[Any] = None, # 单轮样式配置
conversational_styling_config: Optional[Any] = None, # 多轮样式配置
cost_tracking: bool = True # 是否跟踪成本
)
```
## 配置选项
### ContextConstructionConfig
用于配置文档分块和上下文构建：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `max_contexts_per_document` | `int` | `10` | 每个文档最多生成的上下文数 |
| `min_contexts_per_document` | `int` | `1` | 每个文档最少生成的上下文数 |
| `chunk_size` | `int` | `1000` | 文档分块大小 |
| `chunk_overlap` | `int` | `200` | 分块重叠大小 |
| `context_quality_threshold` | `float` | `0.5` | 上下文质量阈值 |
| `context_similarity_threshold` | `float` | `0.7` | 上下文相似度阈值 |
| `max_retries` | `int` | `3` | 最大重试次数 |
资料来源：[deepeval/cli/generate/command.py:80-120]()
### 样式配置
#### 单轮样式配置 (StylingConfig)
```python
single_turn_styling_config(
scenario: Optional[str] = None, # 场景描述
task: Optional[str] = None, # 任务描述
input_format: Optional[str] = None, # 输入格式模板
expected_output_format: Optional[str] = None # 期望输出格式
)
```
#### 多轮样式配置 (ConversationalStylingConfig)
```python
multi_turn_styling_config(
scenario_context: Optional[str] = None, # 场景上下文
conversational_task: Optional[str] = None, # 对话任务描述
participant_roles: Optional[List[str]] = None, # 参与者角色
scenario_format: Optional[str] = None, # 场景格式模板
expected_outcome_format: Optional[str] = None # 期望结果格式
)
```
## CLI 命令
### generate 命令
```bash
deepeval generate \
--method \
--variation \
--output-dir ./output \
--file-name my_goldens
```
### 参数说明
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `--method` | 枚举 | 是 | 生成方法 |
| `--variation` | 枚举 | 是 | 对话类型 |
| `--output-dir` | 路径 | 否 | 输出目录 |
| `--file-name` | 字符串 | 否 | 输出文件名 |
| `--file-type` | 枚举 | 否 | 输出格式 (json/csv) |
| `--num-goldens` | 整数 | 条件必需 | 从零生成时的数量 |
| `--documents` | 文件路径 | 条件必需 | 文档生成时的源文件 |
| `--contexts-file` | 文件路径 | 条件必需 | 上下文生成时的文件 |
| `--goldens-file` | 文件路径 | 条件必需 | Goldens 扩展时的输入 |
| `--model` | 字符串 | 否 | 使用的模型 |
| `--async-mode` | 布尔 | 否 | 启用异步模式 |
| `--max-concurrent` | 整数 | 否 | 最大并发数 |
资料来源：[deepeval/cli/generate/command.py:40-200]()
## 生成流程
```mermaid
sequenceDiagram
participant User as 用户
participant CLI as CLI 命令
participant Synth as Synthesizer
participant LLM as LLM API
participant FS as 文件系统
User->>CLI: deepeval generate --method DOCS
CLI->>Synth: 创建 Synthesizer 实例
Synth->>LLM: 请求生成测试用例
LLM-->>Synth: 返回生成的 goldens
Synth->>Synth: 应用样式配置
Synth->>FS: save_as() 保存结果
FS-->>User: 输出文件
```
## 使用示例
### 从文档生成单轮测试用例
```python
from deepeval.synthesizer import Synthesizer
from deepeval.synthesizer.config import ContextConstructionConfig
synthesizer = Synthesizer()
config = ContextConstructionConfig(
chunk_size=1000,
chunk_overlap=200,
max_contexts_per_document=5
)
goldens = synthesizer.generate_goldens_from_docs(
document_paths=["./docs/guide.md"],
context_construction_config=config
)
output_path = synthesizer.save_as(
file_type="json",
directory="./output",
file_name="my_goldens"
)
```
### 从零生成多轮对话
```python
from deepeval.synthesizer import Synthesizer
from deepeval.cli.generate.utils import GoldenVariation
synthesizer = Synthesizer(async_mode=True)
scenarios = synthesizer.generate_conversational_goldens_from_scratch(
num_goldens=50
)
synthesizer.save_as(
file_type="json",
directory="./output",
file_name="conversational_scenarios"
)
```
### 扩展已有测试用例
```python
synthesizer = Synthesizer()
expanded_goldens = synthesizer.generate_goldens_from_goldens(
goldens=existing_goldens,
max_goldens_per_golden=3,
include_expected_output=True
)
```
## 懒加载机制
Synthesizer 和 ContextConstructionConfig 使用 Python 的 `__getattr__` 机制实现懒加载：
```python
def __getattr__(name: str) -> Any:
if name == "Synthesizer":
from deepeval.synthesizer import Synthesizer
globals()["Synthesizer"] = Synthesizer
return Synthesizer
if name == "ContextConstructionConfig":
from deepeval.synthesizer.config import ContextConstructionConfig
globals()["ContextConstructionConfig"] = ContextConstructionConfig
return ContextConstructionConfig
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
```
这种设计确保了：
- 未使用生成功能的命令不会加载重型依赖
- 测试可以方便地通过 monkeypatch 替换模拟对象
- 模块级别的属性访问保持一致
资料来源：[deepeval/cli/generate/command.py:25-45]()
## 输出格式
### JSON 格式
```json
{
"goldens": [
{
"input": "用户问题",
"expected_output": "期望回答",
"context": ["上下文片段1", "上下文片段2"]
}
]
}
```
### CSV 格式
| input | expected_output | context |
|-------|-----------------|---------|
| 用户问题 | 期望回答 | 上下文片段 |
## 最佳实践
1. **文档质量**：使用结构清晰、内容丰富的源文档可提高生成质量
2. **上下文阈值**：根据文档长度调整 `context_quality_threshold` 和 `context_similarity_threshold`
3. **并发控制**：在 API 限流较严的环境中，适当降低 `max_concurrent`
4. **异步模式**：处理大量数据时启用 `async_mode=True` 提高效率
5. **成本跟踪**：生产环境建议启用 `cost_tracking=True` 监控 API 消耗
---
## 追踪系统
### 相关页面
相关主题：[评估执行引擎](#page-evaluate-engine)
相关源码文件
以下源码文件用于生成本页说明：
- [deepeval/tracing/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/__init__.py)
- [deepeval/tracing/tracing.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/tracing.py)
- [deepeval/tracing/context.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/context.py)
- [deepeval/tracing/api.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/api.py)
- [deepeval/tracing/otel/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/otel/__init__.py)
- [deepeval/tracing/offline_evals/__init__.py](https://github.com/confident-ai/deepeval/blob/main/deepeval/tracing/offline_evals/__init__.py)
# 追踪系统
## 概述
DeepEval 追踪系统（Tracing System）是用于监控、记录和分析 LLM 应用执行过程的组件化框架。该系统提供了端到端的可观测性能力，使开发者能够追踪 LLM 应用的调用链、执行步骤和性能指标。追踪系统与 DeepEval 的评估指标（如 `TaskCompletionMetric`、`GEval` 等）深度集成，支持在追踪过程中自动执行评估任务。
追踪系统的核心设计理念是将 LLM 应用视为黑盒，通过装饰器（`@observe`）和上下文管理器（`with trace(...)`）自动捕获执行过程中的关键信息，并将这些信息用于后续的评估分析。
## 核心组件
### 1. 追踪上下文管理器
追踪系统使用 `trace()` 上下文管理器来创建追踪范围。当代码在 `with trace(...)` 块内执行时，所有子调用的追踪数据都会被自动收集并关联到同一个追踪会话中。
```python
from deepeval.tracing import trace
from deepeval.metrics import TaskCompletionMetric
for golden in dataset.evals_iterator():
with trace(metrics=[TaskCompletionMetric()]):
client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": golden.input}],
)
```
### 2. 观察装饰器
`@observe()` 装饰器用于将普通函数转换为可追踪的组件。当函数被装饰后，其输入输出和执行上下文会自动被记录。
```python
from deepeval.tracing import observe, update_current_span
from deepeval.test_case import LLMTestCase
@observe()
def inner_component(input: str):
output = "result"
update_current_span(test_case=LLMTestCase(input=input, actual_output=output))
return output
@observe()
def app(input: str):
return inner_component(input)
```
### 3. 跨度更新函数
`update_current_span()` 和 `update_current_trace()` 函数允许在追踪上下文中手动更新当前跨度或追踪的信息。这对于在特定位置注入测试用例、指标或其他元数据非常有用。
## 架构设计
### 追踪系统架构图
```mermaid
graph TD
subgraph "应用层"
A[LLM 应用代码]
B[@observe 装饰器]
C[trace 上下文管理器]
end
subgraph "追踪核心"
D[TraceManager]
E[ContextManager]
F[SpanProcessor]
end
subgraph "数据导出层"
G[ConfidentSpanExporter]
H[OTel SpanProcessor]
I[ContextAwareSpanProcessor]
end
subgraph "评估引擎"
J[Metrics Engine]
K[TaskCompletionMetric]
L[Offline Evals]
end
A --> B
A --> C
B --> D
C --> D
D --> E
D --> F
F --> G
F --> I
I --> H
D --> J
J --> K
J --> L
```
### 追踪上下文路由
追踪系统支持两种追踪模式：原生追踪模式和 OTel（OpenTelemetry）模式。`ContextAwareSpanProcessor` 是关键的路由组件，它能够根据当前上下文自动决定数据导出路径。
```mermaid
graph LR
A[追踪上下文活跃] --> B{评估状态检查}
B -->|trace_manager.is_evaluating = True| C[路由至 REST]
B -->|trace_manager.is_evaluating = False| D[路由至 OTLP]
C --> E[ConfidentSpanExporter]
D --> F[OTLP Exporter]
```
## 框架集成
追踪系统提供了与多种主流 LLM 框架的集成能力。集成通过自动创建追踪上下文和使用回调处理器来实现。
### 集成能力矩阵
| 框架 | Bare 模式追踪 | @observe 支持 | evals_iterator 支持 | deepeval test run |
|------|--------------|--------------|---------------------|-------------------|
| OpenAI | ✅ | ✅ | ✅ | ✅ |
| Anthropic | ✅ | ✅ | ✅ | ✅ |
| LangChain | ✅ | ✅ | ✅ | ✅ |
| LangGraph | ✅ | ✅ | ✅ | ✅ |
| Pydantic AI | ✅ | ✅ | ✅ | ✅ |
| LlamaIndex | ✅ | ✅ | ✅ | ✅ |
| Google ADK | ✅ | ✅ | ✅ | ✅ |
| CrewAI | ✅ | ✅ | ✅ | ✅ |
| AWS AgentCore | ✅ | ✅ | ✅ | ✅ |
| Strands | ✅ | ✅ | ✅ | ✅ |
### OpenAI 集成示例
```python
from deepeval.tracing import trace
from deepeval.metrics import TaskCompletionMetric
for golden in dataset.evals_iterator():
with trace(metrics=[TaskCompletionMetric()]):
# OpenAI 客户端调用会自动被追踪
response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": golden.input}]
)
```
### LangChain 集成示例
```python
from deepeval.integrations.langchain import CallbackHandler
from deepeval.metrics import TaskCompletionMetric
callback_handler = CallbackHandler(metrics=[TaskCompletionMetric()])
for golden in dataset.evals_iterator():
llm.invoke(
golden.input,
config={"callbacks": [callback_handler]},
)
```
## 数据流处理
### 离线评估数据流
```mermaid
graph TD
A[追踪数据采集] --> B[Span 数据存储]
B --> C{评估类型判断}
C -->|在线评估| D[ConfidentSpanExporter]
C -->|离线评估| E[Offline Evals 模块]
D --> F[云端评估引擎]
E --> G[本地评估执行]
F --> H[结果聚合]
G --> H
```
### OTel 模式下的混合追踪
当 OTel 模式集成在活跃的 `@observe` 或 `with trace(...)` 上下文中运行时，OTel span interceptor 会同步追踪 UUID，确保两种传输方式产生的数据能够合并到同一个追踪会话中。
```mermaid
sequenceDiagram
participant App as 应用代码
participant Observe as @observe 上下文
participant OTel as OTel SpanInterceptor
participant Router as ContextAwareSpanProcessor
participant REST as ConfidentSpanExporter
App->>Observe: 开始追踪
Observe->>OTel: 同步 trace_id
App->>OTel: 创建 OTel span
OTel->>Router: 处理 span
Router->>REST: 路由至 REST
REST->>Observe: 合并到同一追踪
```
## 评估迭代器集成
`dataset.evals_iterator()` 是追踪系统与评估流程结合的核心接口。它支持在迭代过程中自动应用追踪和指标计算。
### 基础用法
```python
from deepeval.metrics import TaskCompletionMetric
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
app(golden.input)
```
### 异步配置
```python
from deepeval.evaluate.configs import AsyncConfig
from deepeval.metrics import TaskCompletionMetric
for golden in dataset.evals_iterator(
async_config=AsyncConfig(run_async=True),
metrics=[TaskCompletionMetric()],
):
task = asyncio.create_task(run_agent(golden.input))
dataset.evaluate(task)
```
## 配置与初始化
### 追踪初始化
```python
import deepeval
deepeval.instrument(
name="my-app",
environment="development"
)
```
### 集成初始化
每个框架集成都提供了 `instrument_*` 函数来简化初始化过程。例如：
```python
from deepeval.integrations.google_adk import instrument_google_adk
instrument_google_adk()
```
## 关键文件说明
| 文件路径 | 功能描述 |
|---------|---------|
| `deepeval/tracing/__init__.py` | 追踪系统公共 API 导出，包含 `trace`、`@observe`、`update_current_span` 等核心接口 |
| `deepeval/tracing/tracing.py` | 追踪系统核心实现，包含 TraceManager 类和追踪上下文管理逻辑 |
| `deepeval/tracing/context.py` | 追踪上下文实现，管理当前活跃的追踪和跨度状态 |
| `deepeval/tracing/api.py` | 追踪系统 REST API 接口定义，用于与云端服务通信 |
| `deepeval/tracing/otel/__init__.py` | OpenTelemetry 集成模块，实现 OTel span 拦截和转发 |
| `deepeval/tracing/offline_evals/__init__.py` | 离线评估模块，支持在没有网络连接时执行本地评估 |
## 与 Confident AI 平台的集成
追踪系统与 Confident AI 平台深度集成，提供以下能力：
1. **云端追踪同步**：追踪数据自动同步至 Confident AI 平台
2. **评估报告生成**：在平台上生成可分享的测试报告
3. **追踪可视化**：在 Web 界面中查看完整的调用链路
4. **生产环境监控**：支持生产环境的实时追踪和评估
通过 `deepeval login` 命令登录后，所有追踪数据会自动同步到平台：
```bash
deepeval login
deepeval test run test_chatbot.py
```
## 最佳实践
1. **使用 @observe 装饰器包装关键组件**：确保所有 LLM 调用和关键业务逻辑都在可追踪的范围内
2. **结合评估指标使用追踪**：在 `trace()` 或 `evals_iterator()` 中指定指标以获得完整的评估数据
3. **利用上下文更新函数**：在需要注入额外信息时使用 `update_current_span()` 和 `update_current_trace()`
4. **选择合适的集成方式**：根据框架选择原生集成或 OTel 模式集成
## 相关文档
- [评估指标文档](https://deepeval.com/docs/metrics-llm-evals)
- [组件级评估指南](https://deepeval.com/docs/evaluation-component-level-llm-evals)
- [Confident AI 平台文档](https://www.confident-ai.com/docs)
---
---
## Doramagic 踩坑日志
项目：confident-ai/deepeval
摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)。
## 1. 安全/权限坑 · 来源证据：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: OWASP LLM02 output-handling metrics pack (XSS / SQLi / Shell / Path)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4bc32a715810442d93069925f14aab92 | https://github.com/confident-ai/deepeval/issues/2673 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 配置坑 · 来源证据：'NoneType' object has no attribute 'find'
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：'NoneType' object has no attribute 'find'
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_756ddcdc1eda4fd7b87ade56a4a3c10f | https://github.com/confident-ai/deepeval/issues/2554 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 配置坑 · 来源证据：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：🔥 DeepEval 4.0: Eval Harness for Coding Agents, 1-line integrations, TUI for trace inspection!
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9a7d5b92cc5948d48aec4ed1e96e7288 | https://github.com/confident-ai/deepeval/releases/tag/v4.0.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 4. 能力坑 · 能力判断依赖假设
- 严重度：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.
## 5. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | last_activity_observed missing
## 6. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium
## 7. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:676829188 | https://github.com/confident-ai/deepeval | no_demo; severity=medium
## 8. 安全/权限坑 · 来源证据：LLM Evals - v3.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LLM Evals - v3.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9f9371d513c443ab860bbb718a785a2c | https://github.com/confident-ai/deepeval/releases/tag/v3.0 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | issue_or_pr_quality=unknown
## 10. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:676829188 | https://github.com/confident-ai/deepeval | release_recency=unknown