概述

DeepEval 是一个简单易用、开源的 LLM（大语言模型）评估框架，专门用于评估大型语言模型系统。它类似于 Pytest，但专门为 LLM 应用的单元测试而设计。DeepEval 整合了最新研究成果，通过 G-Eval、任务完成度、答案相关性、幻觉检测等指标来运行评估，这些指标使用 LLM-as-a-Judge（LLM 作为评判者）和其他 NLP 模型，完全运行在本地机器上。

资料来源：README.md

核心定位

无论你是构建 AI 代理（AI Agents）、RAG（检索增强生成）管道还是聊天机器人，无论是使用 LangChain 还是 OpenAI 实现，DeepEval 都能为你提供支持。通过它，你可以轻松确定最优的模型、提示词和架构，从而：

• 提升 AI 质量
• 防止提示词漂移
• 自信地从 OpenAI 迁移到 Claude

资料来源：README.md

技术架构

系统架构图

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 支持两种主要的评估模式：

资料来源：README.md

核心功能

评估指标体系

DeepEval 提供了多种预置评估指标，所有指标得分范围均为 0-1：

资料来源：README.md

黄金测试用例生成

DeepEval 支持通过 CLI 自动生成合成黄金测试用例，支持多种生成方法：

deepeval generate golden --method [METHOD] --variation [VARIATION]

资料来源：deepeval/cli/generate/command.py

测试用例结构

from deepeval.test_case import LLMTestCase

test_case = LLMTestCase(
    input="用户输入",
    actual_output="实际输出",
    expected_output="期望输出",  # 可选
    retrieval_context=["检索上下文"]  # 可选
)

资料来源：README.md

框架集成

DeepEval 支持与多种主流 AI 框架深度集成：

集成矩阵

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

集成架构

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/cli/main.py

本地开发环境配置

# 复制环境变量模板
cp .env.example .env.local
# 编辑 .env.local（会被 git 忽略）

使用流程

基本使用流程

graph TD
    A[安装 DeepEval] --> B[配置 API Key]
    B --> C[编写测试用例]
    C --> D[选择评估指标]
    D --> E[定义阈值]
    E --> F[运行评估]
    F --> G{是否达标}
    G -->|是| H[测试通过]
    G -->|否| I[调整模型/提示词]
    I --> F

Pytest 集成示例

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."
    )

运行测试：

deepeval test run test_chatbot.py

资料来源：README.md

非 Pytest 评估

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 平台深度集成，提供以下功能：

资料来源：README.md

登录与同步

# 登录
deepeval login

# 运行测试 - 结果自动同步到云端
deepeval test run test_chatbot.py

技能集成

DeepEval 可以作为智能代理（Agent）的技能（Skill）使用：

安装方式

# 使用 skills 兼容的安装器
npx skills add confident-ai/deepeval --skill "deepeval"

# 或手动复制
cp skills/deepeval [agent_skills_directory]

前置条件

资料来源：skills/README.md

测试结果检查

使用 deepeval inspect 命令检查测试运行结果：

deepeval inspect [PATH]

该命令会打开 TUI（文本用户界面）来检查保存的测试运行轨迹。

资料来源：deepeval/cli/inspect.py

性能与扩展性

异步评估支持

DeepEval 支持异步评估模式，适用于大规模评估场景：

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)

并发控制

资料来源：deepeval/cli/generate/command.py

版本与发布

DeepEval 使用语义化版本控制，当前版本信息可通过以下方式获取：

import deepeval
print(deepeval.__version__)

许可证

DeepEval 采用开源许可证，具体信息请参阅 LICENSE.md。

相关资源

核心概念

DeepEval 将 LLM 评估抽象为三个核心概念：测试用例（Test Case）、评估指标（Metric） 和 断言验证（Assertion）。测试用例定义了被评估 LLM 应用的输入、期望输出和上下文信息；评估指标则实现了具体的评估算法，如 G-Eval、答案相关性、幻觉检测等；断言验证将指标得分与阈值进行比较，以判断测试是否通过。资料来源：deepeval/test_case/llm_test_case.py

工作流程

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 为例，在终端中执行以下命令设置环境变量：

export OPENAI_API_KEY="..."

也可使用 .env.local 文件管理密钥：

cp .env.example .env.local
# 编辑 .env.local 文件（该文件已被 git 忽略）

资料来源：README.md

安装 DeepEval

通过 pip 安装 DeepEval：

pip install -U deepeval

资料来源：README.md

使用 Pytest 集成

创建测试文件

创建一个名为 test_chatbot.py 的测试文件：

touch test_chatbot.py

编写测试用例

打开 test_chatbot.py 并编写第一个端到端评估测试。DeepEval 将 LLM 应用视为黑盒进行评估：

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

核心参数说明

资料来源：deepeval/test_case/llm_test_case.py

运行测试

在终端中执行测试命令：

deepeval test run test_chatbot.py

测试通过时将显示成功消息，未通过则显示失败详情。

资料来源：README.md

不使用 Pytest 集成

对于 Jupyter Notebook 环境或偏好命令式编程的场景，DeepEval 提供了 evaluate() 函数：

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 高度模块化，允许在项目任何位置单独使用评估指标：

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 平台的深度集成。登录后，测试结果将自动同步到云端：

deepeval login

登录后运行测试，结果自动上传：

deepeval test run test_chatbot.py

资料来源：README.md

评估指标类型

资料来源：README.md

关键源码结构

deepeval.test_case 模块导出了测试用例相关的核心类：

from deepeval.test_case import LLMTestCase, SingleTurnParams

deepeval.evaluate 模块提供了评估执行接口：

from deepeval import evaluate, assert_test

资料来源：deepeval/test_case/__init__.py, deepeval/evaluate/__init__.py

概述

DeepEval 是一个开源的 LLM（大语言模型）评估框架，采用模块化设计实现评估流程的解耦与扩展。系统架构围绕评估执行引擎、指标计算层、追踪系统和CLI命令接口四大核心模块展开，支持端到端测试、代理评估、合成数据生成等多种评估场景。

DeepEval 的核心设计理念是将 LLM 应用视为黑盒，通过标准化测试用例（LLMTestCase）和可插拔的指标（Metric）系统，实现跨框架的通用评估能力。

整体架构图

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

核心执行层

评估执行器类型

DeepEval 的评估执行层支持两种主要的执行模式，分别针对不同的评估场景：

资料来源：deepeval/evaluate/execute/__init__.py

执行流程

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

Agentic 执行器

代理执行器专门用于评估 LLM 代理（Agent）应用，支持追踪工具调用、多步推理和任务完成度等代理特有指标。

核心职责：

• 追踪代理的完整执行轨迹
• 记录工具调用序列和参数
• 评估任务完成度和步骤效率

资料来源：deepeval/evaluate/execute/agentic.py

指标系统

指标类型概览

DeepEval 提供了丰富的预置指标，涵盖 LLM 评估的多个维度：

资料来源：README.md - Metrics and Features

G-Eval 指标

G-Eval 是 DeepEval 的核心评估方法，基于最新的研究论文实现。它通过 LLM-as-Judge 范式进行自动化评估。

使用方式：

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 代理是否成功完成了给定任务：

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 兼容的设计，同时支持本地追踪和云端同步：

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

核心追踪组件

资料来源：README.md - Evals With Full Traceability

追踪装饰器使用

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 框架的无缝集成，通过统一的回调机制实现追踪和评估：

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

集成能力说明

每个集成支持四种级别的能力：

CLI 命令系统

命令概览

DeepEval CLI 提供了丰富的命令行接口：

黄金数据生成

deepeval generate 命令支持多种数据生成方法：

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]

生成方法配置：

资料来源：deepeval/cli/generate/command.py

inspect 命令

deepeval inspect 命令提供交互式 TUI 用于检视测试结果：

# 查看最新测试运行结果
deepeval inspect

# 查看指定文件
deepeval inspect path/to/test_run_123.json

# 查看指定文件夹的最新结果
deepeval inspect --folder ./results

该命令支持可选的 deepeval[inspect] 扩展包，需要单独安装。

数据模型

LLMTestCase

核心测试用例数据模型：

SingleTurnParams 与 MultiTurnParams

评估参数枚举，用于指定 G-Eval 等指标的评估维度：

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

异步评估配置：

from deepeval.evaluate.configs import AsyncConfig

async_config = AsyncConfig(
    run_async=True,
    max_concurrent=5
)

ContextConstructionConfig

合成数据生成的上下文构建配置：

常量定义

DeepEval 在 deepeval/constants.py 中定义了全局常量，包括：

• 默认阈值配置
• API 超时设置
• 缓存策略配置
• 日志级别定义

这些常量贯穿整个评估流程，确保行为的一致性和可配置性。

资料来源：deepeval/constants.py

评估流程总结

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. 分离关注点：将评估逻辑与业务逻辑解耦

概述

DeepEval 是一个面向大语言模型（LLM）应用的评估框架，采用了模块化架构设计。其核心模块结构围绕指标系统（Metrics）、测试用例（Test Case）、追踪系统（Tracing）和配置管理（Configuration）四大支柱构建。框架的核心设计理念是将 LLM 评估过程抽象为可组合、可扩展的组件，类似于 Pytest 在单元测试领域的角色，但专门针对 LLM 应用场景优化。

DeepEval 的架构设计允许开发者以两种主要方式使用该框架：一是集成到 Pytest 测试流程中，通过 @assert_test 装饰器实现声明式评估；二是作为独立库使用，通过 evaluate() 函数直接调用指标进行评估。这种双重使用模式体现了框架对不同开发工作流的包容性支持。

框架的核心价值在于其本地化评估能力——所有指标计算和 LLM 调用都可以在用户本地机器上运行，无需依赖外部云服务。同时，通过与 Confident AI 平台的集成，开发者可以选择性地将评估结果同步到云端进行可视化和协作分析。

核心模块架构图

graph TD
    subgraph "核心层"
        BM[base_metric.py<br/>BaseMetric 基类]
        IND[indicator.py<br/>Indicator 指标系统]
        TU[test_case/utils.py<br/>LLMTestCase]
        CFG[config/settings.py<br/>配置管理]
    end
    
    subgraph "执行层"
        SYN[Synthesizer<br/>合成器]
        EVAL[evaluate()<br/>评估函数]
        TRACE[Tracing<br/>追踪系统]
    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<br/>生成器]
    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 内置指标的具体实现。指标系统采用策略模式设计，每种指标封装了特定的评估逻辑。

主要指标类型：

资料来源：deepeval/metrics/indicator.py:1-100

指标执行流程

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 中表示测试用例的核心数据结构。它封装了评估所需的输入、输出和上下文信息。

基础参数：

资料来源：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 是合成器用于从文档生成测试数据的配置类：

追踪与可观测性系统

trace 上下文管理器

DeepEval 提供了 trace 上下文管理器用于包装 LLM 调用，实现端到端的评估追踪：

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 装饰器：

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 的集成系统支持四种不同的评估模式：

支持的框架集成

DeepEval 官方支持以下框架的深度集成：

• OpenAI：原生客户端集成
• Anthropic：Claude 模型支持
• LangChain：回调处理器模式
• LangGraph：状态机评估
• LlamaIndex：异步评估支持
• CrewAI：多智能体评估
• Google ADK：Agent Development Kit
• Strands：自定义智能体框架

每种集成都通过统一的回调或包装机制接入 DeepEval 的追踪和评估系统。

CLI 命令结构

generate 命令

deepeval generate 命令用于从多种数据源生成合成测试数据：

deepeval generate --method docs --variation single_turn --documents ./docs

支持的生成方法：

资料来源：deepeval/cli/generate/command.py:1-100

test 命令

deepeval test run 命令执行 Pytest 测试并自动同步结果到 Confident AI 平台：

deepeval test run test_chatbot.py

该命令会自动加载 .env.local 和 .env 中的配置，执行测试后上传结果。

模块间依赖关系

graph LR
    subgraph "依赖层级"
        A[配置层<br/>config/]
        B[基础层<br/>base_metric.py]
        C[指标层<br/>indicator.py]
        D[测试用例层<br/>test_case/]
        E[合成器层<br/>synthesizer/]
        F[追踪层<br/>tracing/]
        G[CLI 层<br/>cli/]
    end
    
    A --> B
    B --> C
    D --> C
    A --> D
    C --> E
    F --> E
    E --> G
    C --> G

关键设计模式

1. 策略模式

所有指标实现统一的 BaseMetric 接口，允许在运行时动态替换评估策略：

# 同一接口，不同实现
metrics = [
    AnswerRelevancyMetric(threshold=0.7),
    FaithfulnessMetric(threshold=0.8),
]

2. 装饰器模式

@assert_test 和 @observe 装饰器为普通函数添加评估能力，无需修改业务逻辑：

@assert_test(llm_output_symbol="actual_output")
def my_llm_app():
    return llm.invoke("Hello")

3. 上下文管理器模式

trace 上下文管理器自动管理追踪生命周期，确保资源正确释放：

with trace(metrics=[metric]):
    # 追踪范围内所有 LLM 调用自动被捕获
    pass

扩展开发指南

创建自定义指标

要创建自定义指标，需继承 BaseMetric 并实现核心方法：

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 应用评估的通用解决方案。

概述

在 DeepEval 框架中，测试用例是评估 LLM 应用质量的核心数据结构。测试用例定义了评估所需的输入、期望输出、实际输出以及相关的上下文信息，DeepEval 通过将这些测试用例与评估指标结合来执行自动化评估。

DeepEval 支持多种类型的测试用例，分别对应不同的评估场景：

资料来源：deepeval/test_case/__init__.py

核心组件

LLMTestCase（单轮测试用例）

LLMTestCase 是 DeepEval 中最基础的测试用例类，用于定义单轮 LLM 交互的评估数据。

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

参数说明

SingleTurnParams 枚举

SingleTurnParams 定义了单轮评估中可用的参数枚举，用于配置 G-Eval 等评估指标：

资料来源：deepeval/test_case/llm_test_case.py:1-50

ConversationalTestCase（多轮对话测试用例）

概述

ConversationalTestCase 用于评估多轮对话场景，每个测试用例包含一系列消息序列。

from deepeval.test_case import ConversationalTestCase, ConversationalTurn

test_case = ConversationalTestCase(
    turns=[]
)

消息结构

多轮测试用例中的每条消息（turn）包含：

资料来源：deepeval/test_case/conversational_test_case.py

ArenaTestCase（对比评估测试用例）

概述

ArenaTestCase 用于模型对比评估场景，允许同时评估多个模型的响应。

from deepeval.test_case import ArenaTestCase

arena_test_case = ArenaTestCase(
    models=["gpt-4", "claude-3-opus"],
    input="What is machine learning?",
    expected_output="..."
)

ArenaTurnParams 枚举

资料来源：deepeval/test_case/arena_test_case.py

测试用例执行流程

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

使用示例

基本单轮评估

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

RAG 场景评估

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."
    ]
)

带上下文的评估

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 执行：

deepeval test run test_chatbot.py

其中 test_chatbot.py 包含使用 assert_test 定义的测试用例。

资料来源：deepeval/cli/inspect.py

与评估指标的集成

测试用例需要与评估指标结合使用才能完成评估。常用的评估指标包括：

from deepeval.metrics import GEval

metric = GEval(
    name="Correctness",
    criteria="评估实际输出与期望输出的一致性",
    evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
    threshold=0.5
)

数据隐私说明

当使用 DeepEval 平台时，所有测试用例数据会自动记录到平台。更多数据隐私信息请参考官方文档。

资料来源：README.md

概述

DeepEval 的评估指标体系是一套模块化的 LLM 应用评估框架，类似于 Pytest 但专为测试大语言模型应用而设计。该体系融合了最新的研究方法，通过 G-Eval、Task Completion、Answer Relevancy 等指标，利用 LLM-as-a-Judge 及其他 NLP 模型在本地机器上运行评估。资料来源：README.md

评估指标体系支持多种使用方式，包括与 Pytest 集成、独立的 evaluate() 函数调用，以及通过 evals_iterator() 实现的端到端追踪评估。资料来源：README.md

架构设计

核心组件关系

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]

指标分类总览

资料来源：README.md

指标基类设计

BaseMetric 抽象基类

所有评估指标继承自 BaseMetric 基类，该基类定义了指标的核心接口和行为规范。资料来源：deepeval/metrics/base_metric.py

#### 核心属性

#### 核心方法

class BaseMetric(ABC):
    """所有评估指标的抽象基类"""
    
    @abstractmethod
    def measure(self, test_case: LLMTestCase) -> float:
        """执行评估的核心方法"""
        pass

资料来源：deepeval/metrics/base_metric.py

指标执行流程

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

#### 参数配置

#### 使用示例

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 工作原理

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

#### 核心参数

#### 实现原理

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

#### 使用方式

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

#### 参数配置

#### 使用示例

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 指标体系全景

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

资料来源：deepeval/metrics/agentic/task_completion/task_completion.py、README.md

指标使用方式

与 Pytest 集成

通过 @assert_test 装饰器实现与 Pytest 的深度集成，这是 DeepEval 推荐的评估方式。资料来源：README.md

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

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

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

Reason 字段

每个指标在评估后会生成 reason 字段，提供 LLM 评判的详细解释，便于调试和理解评估逻辑。资料来源：deepeval/metrics/base_metric.py

print(metric.score)    # 0.85
print(metric.reason)   # "The response correctly addresses the user's question..."

集成框架支持

DeepEval 指标体系支持多种主流 LLM 应用框架的集成评估。资料来源：deepeval/integrations/README.md

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

最佳实践

指标选择指南

阈值设置建议

1. 保守设置：threshold=0.7 适用于生产环境，确保高质量输出
2. 宽松设置：threshold=0.5 适用于开发阶段，快速迭代
3. 渐进调整：根据历史评估结果逐步调整阈值

环境变量配置

DeepEval 自动加载环境变量，优先级为：进程环境变量 > .env.local > .env。可通过 DEEPEVAL_DISABLE_DOTENV=1 禁用自动加载。资料来源：README.md

扩展开发

开发者可以通过继承 BaseMetric 基类创建自定义评估指标：

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 集成、独立调用或追踪模式等多种方式执行评估。

概述

评估执行引擎是 DeepEval 框架的核心组件，负责驱动 LLM 应用的质量评估流程。它封装了评估的完整生命周期，包括测试用例加载、指标计算、结果收集与报告生成。该引擎支持两种主要的评估模式：端到端评估（E2E）和代理式评估（Agentic），能够适应不同的测试场景和集成需求。资料来源：README.md

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/ 目录下，采用分层架构设计：

评估入口函数

评估执行引擎的主入口是 evaluate() 函数，支持同步和异步两种调用模式。开发者可以通过该函数批量执行测试用例并获取评估结果。资料来源：deepeval/evaluate/__init__.py

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

工作流程：

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，通过父-子关系形成完整的调用链。这种设计允许评估引擎回溯任意时间点的执行状态，并针对特定操作进行指标验证。

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

异步配置

对于需要处理大量测试用例的场景，引擎支持异步并发执行。通过 AsyncConfig 类可以控制并发度和超时行为。资料来源：deepeval/evaluate/configs.py

from deepeval.evaluate.configs import AsyncConfig

async_config = AsyncConfig(
    run_async=True,
    max_concurrent=10,  # 最大并发任务数
    timeout=300  # 单个任务超时时间（秒）
)

报告生成

控制台报告

评估完成后，引擎自动生成控制台报告，包含测试用例总数、通过率、各指标得分分布等关键信息。资料来源：deepeval/evaluate/console_report.py

报告内容包括：

• 整体通过率统计
• 各指标得分详情
• 失败用例的错误信息
• 执行耗时分析
• 资源使用情况（如适用）

结构化输出

评估结果以标准化的数据结构返回，便于后续分析和集成：

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

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

集成特性矩阵：

CLI 命令行支持

评估执行引擎可通过 deepeval CLI 调用，支持自动化测试运行和结果持久化。资料来源：deepeval/cli/main.py

常用命令：

# 运行测试文件
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

执行流程图

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 的数据集管理模块是整个 LLM 评估框架的核心基础设施，负责管理和组织用于评估大型语言模型应用的测试数据。该模块支持多种数据格式导入、测试用例的组织与管理、以及与 Confident AI 平台的同步功能。

数据集管理的主要职责包括：

• 测试用例管理：创建、组织和管理 LLMTestCase 对象
• 迭代器功能：通过 evals_iterator() 遍历数据集并执行评估
• Golden 数据集：管理高质量的参考数据集（goldens）用于评估
• 评估结果追踪：记录和回溯每次评估运行的结果

核心组件

LLMTestCase

LLMTestCase 是 DeepEval 中用于定义单个测试用例的基础数据模型。每个测试用例包含输入、期望输出和实际输出等关键字段。

from deepeval.test_case import LLMTestCase, SingleTurnParams

test_case = LLMTestCase(
    input="用户输入内容",
    actual_output="LLM实际输出",
    expected_output="期望的正确答案",
    retrieval_context=["上下文文档1", "上下文文档2"]
)

主要参数说明：

Golden 数据集

Golden 数据集是经过精心准备的高质量参考数据集，用于验证 LLM 应用的输出质量。

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() 是数据集的核心迭代方法，支持在遍历数据集的同时执行评估。该方法与各种框架集成兼容，支持端到端和组件级别的评估。

from deepeval.metrics import TaskCompletionMetric

# 端到端评估
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
    invoke({"prompt": golden.input})

异步评估配置

DeepEval 支持异步评估模式，适用于大规模数据集的高效处理：

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)

异步配置参数

框架集成

OpenAI 集成

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 集成

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 集成

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 集成

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 提供多种方式生成测试数据集：

单轮与多轮变体

数据集支持单轮（Single Turn）和多轮（Multi-turn Conversational）两种评估模式：

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
)

评估工作流

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 命令自动保存：

deepeval test run test_chatbot.py

结果文件格式为 test_run_*.json，可通过 deepeval inspect 命令查看：

deepeval inspect                    # 查看最新运行结果
deepeval inspect path/to/file.json  # 查看指定文件
deepeval inspect -f ./results       # 查看指定目录

配置管理

环境变量

.env 配置

DeepEval 支持 .env.local 文件进行本地配置：

cp .env.example .env.local
# 编辑 .env.local 文件

与 Confident AI 集成

DeepEval 数据集管理与 Confident AI 平台深度集成，提供以下云端功能：

• 数据集存储：云端存储和管理测试数据集
• 评估报告：生成可分享的评估报告
• 迭代追踪：比较不同版本的 LLM 应用表现
• 协作功能：团队成员共享和协作测试数据集

登录命令：

deepeval login

最佳实践

1. 数据集质量：确保 Golden 数据集包含多样化、高质量的测试用例
2. 评估指标选择：根据应用场景选择合适的评估指标
3. 异步处理：大规模数据集建议使用异步模式提高效率
4. 结果回溯：定期保存和审查评估结果用于持续优化
5. 框架集成：选择最适合你技术栈的框架集成方式

概述

合成数据生成（Synthetic Data Generation）是 DeepEval 框架中用于自动创建测试用例的核心功能。该功能通过 LLM 自动生成高质量的测试数据，包括单轮问答和多轮对话场景，帮助开发者快速构建评估数据集。

Synthesizer（合成器）是实现这一功能的核心类，它封装了多种生成策略，支持从文档、上下文、已有测试用例或完全空白状态生成合成数据。资料来源：deepeval/synthesizer/synthesizer.py:1-50

核心架构

类结构

graph TD
    A[Synthesizer] --> B[BaseSynthesizer]
    B --> C[可配置生成策略]
    B --> D[异步/同步模式]
    A --> E[ContextConstructionConfig]
    A --> F[StylingConfig]
    A --> G[ConversationalStylingConfig]

数据模型

合成数据生成涉及以下核心数据模型：

资料来源：deepeval/synthesizer/schema.py:1-100

生成方法

四种生成策略

DeepEval 支持四种主要的合成数据生成方法：

资料来源：deepeval/cli/generate/command.py:1-80

单轮与多轮对话

graph LR
    A[生成请求] --> B{对话类型}
    B -->|单轮| C[GoldenVariation.SINGLE_TURN]
    B -->|多轮| D[GoldenVariation.CONVERSATIONAL]
    C --> E[generate_goldens_from_*]
    D --> F[generate_conversational_goldens_from_*]

Synthesizer 类

主要方法

资料来源：deepeval/synthesizer/synthesizer.py:100-300

初始化参数

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

用于配置文档分块和上下文构建：

资料来源：deepeval/cli/generate/command.py:80-120

样式配置

#### 单轮样式配置 (StylingConfig)

single_turn_styling_config(
    scenario: Optional[str] = None,           # 场景描述
    task: Optional[str] = None,               # 任务描述
    input_format: Optional[str] = None,        # 输入格式模板
    expected_output_format: Optional[str] = None  # 期望输出格式
)

#### 多轮样式配置 (ConversationalStylingConfig)

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 命令

deepeval generate \
    --method <DOCS|CONTEXTS|SCRATCH|GOLDENS> \
    --variation <SINGLE_TURN|CONVERSATIONAL> \
    --output-dir ./output \
    --file-name my_goldens

参数说明

资料来源：deepeval/cli/generate/command.py:40-200

生成流程

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: 输出文件

使用示例

从文档生成单轮测试用例

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"
)

从零生成多轮对话

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"
)

扩展已有测试用例

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__ 机制实现懒加载：

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 格式

{
  "goldens": [
    {
      "input": "用户问题",
      "expected_output": "期望回答",
      "context": ["上下文片段1", "上下文片段2"]
    }
  ]
}

CSV 格式

最佳实践

1. 文档质量：使用结构清晰、内容丰富的源文档可提高生成质量
2. 上下文阈值：根据文档长度调整 context_quality_threshold 和 context_similarity_threshold
3. 并发控制：在 API 限流较严的环境中，适当降低 max_concurrent
4. 异步模式：处理大量数据时启用 async_mode=True 提高效率
5. 成本跟踪：生产环境建议启用 cost_tracking=True 监控 API 消耗

概述

DeepEval 追踪系统（Tracing System）是用于监控、记录和分析 LLM 应用执行过程的组件化框架。该系统提供了端到端的可观测性能力，使开发者能够追踪 LLM 应用的调用链、执行步骤和性能指标。追踪系统与 DeepEval 的评估指标（如 TaskCompletionMetric、GEval 等）深度集成，支持在追踪过程中自动执行评估任务。

追踪系统的核心设计理念是将 LLM 应用视为黑盒，通过装饰器（@observe）和上下文管理器（with trace(...)）自动捕获执行过程中的关键信息，并将这些信息用于后续的评估分析。

核心组件

1. 追踪上下文管理器

追踪系统使用 trace() 上下文管理器来创建追踪范围。当代码在 with trace(...) 块内执行时，所有子调用的追踪数据都会被自动收集并关联到同一个追踪会话中。

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() 装饰器用于将普通函数转换为可追踪的组件。当函数被装饰后，其输入输出和执行上下文会自动被记录。

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() 函数允许在追踪上下文中手动更新当前跨度或追踪的信息。这对于在特定位置注入测试用例、指标或其他元数据非常有用。

架构设计

追踪系统架构图

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 是关键的路由组件，它能够根据当前上下文自动决定数据导出路径。

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 框架的集成能力。集成通过自动创建追踪上下文和使用回调处理器来实现。

集成能力矩阵

OpenAI 集成示例

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 集成示例

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]},
    )

数据流处理

离线评估数据流

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，确保两种传输方式产生的数据能够合并到同一个追踪会话中。

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() 是追踪系统与评估流程结合的核心接口。它支持在迭代过程中自动应用追踪和指标计算。

基础用法

from deepeval.metrics import TaskCompletionMetric

for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
    app(golden.input)

异步配置

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)

配置与初始化

追踪初始化

import deepeval

deepeval.instrument(
    name="my-app",
    environment="development"
)

集成初始化

每个框架集成都提供了 instrument_* 函数来简化初始化过程。例如：

from deepeval.integrations.google_adk import instrument_google_adk

instrument_google_adk()

关键文件说明

与 Confident AI 平台的集成

追踪系统与 Confident AI 平台深度集成，提供以下能力：

1. 云端追踪同步：追踪数据自动同步至 Confident AI 平台
2. 评估报告生成：在平台上生成可分享的测试报告
3. 追踪可视化：在 Web 界面中查看完整的调用链路
4. 生产环境监控：支持生产环境的实时追踪和评估

通过 deepeval login 命令登录后，所有追踪数据会自动同步到平台：

deepeval login
deepeval test run test_chatbot.py

最佳实践

1. 使用 @observe 装饰器包装关键组件：确保所有 LLM 调用和关键业务逻辑都在可追踪的范围内
2. 结合评估指标使用追踪：在 trace() 或 evals_iterator() 中指定指标以获得完整的评估数据
3. 利用上下文更新函数：在需要注入额外信息时使用 update_current_span() 和 update_current_trace()
4. 选择合适的集成方式：根据框架选择原生集成或 OTel 模式集成

相关文档

• 评估指标文档
• 组件级评估指南
• Confident AI 平台文档

Pitfall Log / 踩坑日志

项目：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