DeepEval — LLM 应用单元测试与评估框架

GitHub: confident-ai/deepeval
Stars: 16,200+ | License: Apache-2.0 | 9600+ Commits
官网: deepeval.com | 云平台: confident-ai.com

项目速览

DeepEval 是由 Confident AI 团队推出的 LLM 应用评估框架，核心理念是”像写单元测试一样评估 LLM”。与传统的学术基准评测工具不同，DeepEval 面向的是 LLM 应用开发者——当你构建了一个 RAG 系统、一个聊天机器人或一个 Agent 时，你需要回答：输出的答案是否忠实于检索上下文？是否存在幻觉？有没有安全隐患？

DeepEval 通过仿 Pytest 的 API 设计解决了这个问题。你定义一个测试函数，创建测试用例（LLMTestCase），选择评估指标（Metric），调用 assert_test()——DeepEval 使用 LLM-as-a-Judge、统计方法和本地 NLP 模型三种评估策略来判断输出质量。所有指标得分在 0-1 之间，通过与 threshold 比较判定测试通过或失败。

框架的另一个关键特性是与 Confident AI 云平台的深度集成。通过 deepeval login 登录后，评测结果自动同步到云端仪表盘，同时支持数据集管理、LLM 调用追踪（tracing）、合成数据生成和 Prompt 优化等企业级功能。DeepEval 还提供 MCP Server 支持，允许在 IDE 中直接触发评测。

截至 2026 年 5 月（Opus 4.8 版本），DeepEval 累计超过 9600 次提交和 56 个版本发布，GitHub Star 数超过 16,200。

功能概述

评估指标矩阵

DeepEval 提供 20+ 内置评估指标，按应用场景分类：

类别	指标	说明
通用	G-Eval	自定义评估标准，基于 LLM-as-a-Judge
通用	DAG	自定义指标的有向无环图组合
RAG	AnswerRelevancy	答案与问题的相关性
RAG	Faithfulness	答案是否忠实于检索上下文
RAG	ContextualRecall	上下文的检索召回率
RAG	ContextualPrecision	上下文的检索精确率
RAG	ContextualRelevancy	上下文与问题的相关性
Agentic	TaskCompletion	Agent 任务是否完成
Agentic	ToolCorrectness	工具调用是否正确
Agentic	GoalAccuracy	目标完成准确度
安全	Hallucination	事实性幻觉检测
安全	Bias	性别/种族/政治偏见检测
安全	Toxicity	毒性内容检测
安全	PromptAlignment	Prompt 对齐检测
输出	Summarization	摘要质量评估
输出	JSONCorrectness	JSON 格式正确性
多模态	TextToImage	文生图质量评估
多模态	ImageCoherence	图像连贯性评估

G-Eval：LLM-as-a-Judge 自定义评测

G-Eval 是 DeepEval 最灵活的指标，允许你使用自然语言定义评测标准（criteria），并通过 evaluation_params 指定哪些字段需要评估：

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
)

G-Eval 内部会生成一个详细的评估 Prompt 发送给 LLM Judge（默认使用 OpenAI 的 GPT-4o），要求其按照 criteria 中的标准给出评分和详细理由。所有 DeepEval 指标都返回 score（0-1 浮点数）和 reason（自然语言解释）。

RAG 评估指标

RAG 系统的质量取决于两个维度的交互：检索质量（retrieval）和生成质量（generation）。DeepEval 提供了一组正交的指标来分别度量：

AnswerRelevancy（答案相关性）：实际输出与用户问题的语义相关程度
Faithfulness（忠实性）：实际输出能否从检索到的上下文中推断出来
ContextualRecall（上下文召回率）：检索上下文是否覆盖了预期输出中所有关键信息
ContextualPrecision（上下文精确率）：检索上下文中与问题相关的信息比例
ContextualRelevancy（上下文相关性）：检索到的文档中相关信息的最低限度程度

使用示例——测量 Faithfulness：

from deepeval.metrics import FaithfulnessMetric
from deepeval.test_case import LLMTestCase

metric = FaithfulnessMetric(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."
    ]
)

metric.measure(test_case)
print(metric.score)   # e.g., 0.92
print(metric.reason)  # "The actual output is fully supported by the retrieval context..."

安全检测指标

DeepEval 内置了三个关键的安全相关指标：

HallucinationMetric：检测 LLM 输出中是否存在与参考上下文相矛盾的事实性错误
BiasMetric：检测输出中是否存在性别、种族、宗教、政治等维度的偏见
ToxicityMetric：检测输出中是否存在仇恨言论、骚扰、暴力等毒性内容

这三个指标均支持本地模型运行，无需将敏感数据发送到外部 API。

自定义指标与 DAG 组合

DeepEval 支持通过继承 BaseMetric 类创建自定义指标，并通过 DAG（有向无环图）将多个指标组合成复合评测流程——例如”先检查是否有毒，再检查是否忠实，最后检查是否相关”。

CI/CD 与平台集成

CLI 测试运行器：deepeval test run 命令将 Python 测试文件作为标准测试套件执行，支持 CI 流水线中的 exit code
Confident AI 云平台：评测结果自动同步至云端仪表盘，支持历史趋势、模型版本对比、数据集管理
MCP Server：在 Claude Code、Cursor 等 IDE 中直接触发评测
Tracing：LLM 调用链路追踪，用于调试和性能分析

适用场景

场景	说明
RAG 系统质量保障	持续监控 RAG Pipeline 的检索质量和生成忠实性，防止检索退化或幻觉
聊天机器人上线前验收	在部署前用 G-Eval + 安全指标对机器人进行全维度评测
微调模型回归测试	每次模型更新后运行固定的测试套件，检测能力退化
Agent 行为验证	评估 AI Agent 的任务完成度、工具调用正确性和目标达成率
安全合规审查	在敏感场景（金融、医疗、教育）中使用 Bias/Toxicity 指标确保输出合规
CI/CD 质量门禁	将 DeepEval 集成到 GitHub Actions/Jenkins 中，PR 合并前自动运行评测

快速上手

安装

pip install -U deepeval

要求 Python >= 3.9。

配置 LLM Judge

DeepEval 默认使用 OpenAI 的 GPT-4o 作为 Judge 模型进行 LLM-as-a-Judge 评估：

export OPENAI_API_KEY="sk-..."

你也可以配置使用本地模型作为 Judge（通过 LiteLLM 适配器），避免数据外传。

第一个测试用例

from deepeval import assert_test
from deepeval.metrics import AnswerRelevancyMetric
from deepeval.test_case import LLMTestCase

def test_answer_relevancy():
    metric = AnswerRelevancyMetric(threshold=0.7)
    test_case = LLMTestCase(
        input="你们的退换货政策是什么？",
        actual_output="我们提供30天无理由退换货，全额退款。",
        retrieval_context=[
            "所有顾客享有30天无理由退换货服务，退款将在7个工作日内原路返回。"
        ]
    )
    assert_test(test_case, [metric])

运行测试

deepeval test run test_rag.py

输出将显示每个测试用例的通过/失败状态、得分和失败原因。

查看云端结果

deepeval login
# 运行测试后结果自动同步至 Confident AI 仪表盘

源码架构

DeepEval 以 Python 为核心语言（92.4%），辅以 TypeScript（7.6%）用于 MCP Server 和 IDE 插件：

deepeval/
├── deepeval/                 # 核心 Python 包
│   ├── metrics/              # 评估指标集合
│   │   ├── g_eval/           # G-Eval 自定义评测
│   │   ├── rag/              # RAG 指标（Faithfulness、AnswerRelevancy 等）
│   │   ├── safety/           # 安全指标（Hallucination、Bias、Toxicity）
│   │   ├── agentic/          # Agentic 指标（TaskCompletion、ToolCorrectness 等）
│   │   ├── summarization/    # 摘要指标
│   │   └── dag/              # DAG 复合指标引擎
│   ├── test_case/            # LLMTestCase 数据模型
│   ├── evaluator/            # 评测执行引擎
│   ├── scorer/               # 评分器（LLM Judge、统计方法、本地 NLP）
│   ├── synthesizer/          # 合成数据生成器
│   ├── monitor/              # 生产环境监控模块
│   ├── tracing/              # LLM 调用追踪
│   └── cli.py                # CLI 入口
├── typescript/               # MCP Server 与 IDE 插件
├── skills/                   # Skill 定义
├── examples/                 # 示例代码
├── tests/                    # 框架自身测试
├── docs/                     # 文档
├── pyproject.toml            # 构建配置
└── README.md

核心设计模式：

Pytest 风格 API：assert_test() 函数接受 LLMTestCase 和 [Metric] 列表，内部调用每个 Metric 的 measure() 方法，将 score 与 threshold 比较，通过 AssertionError 报告失败——兼容标准 pytest 工作流。
Metric 抽象基类：每个指标继承 BaseMetric，必须实现 measure() 方法。measure() 负责调用 LLM Judge 或本地模型，填充 self.score（0-1 浮点）和 self.reason（自然语言解释）。新增指标只需实现这一个类。
多态评分策略：同一个指标可在多种评分策略间切换——LLM-as-a-Judge（调用 GPT-4o 做语义判断）、Statistical（基于 n-gram 重叠等统计方法）、Local NLP（加载本地分类模型做安全检测）。策略选择通过 model 参数或环境变量控制。
平台双轨制：核心评测逻辑在本地运行（开源），结果可选择同步至 Confident AI 云端（SaaS）进行集中管理、可视化和团队协作。本地离线模式与云端完全解耦。

实操 Demo

以下演示两个完整场景：RAG 系统的全面质量评估、多指标 CI 自动化测试。

Demo 1：RAG 系统的三指标综合评估

步骤 1：编写测试文件

# test_rag_system.py
from deepeval import assert_test
from deepeval.metrics import (
    AnswerRelevancyMetric,
    FaithfulnessMetric,
    ContextualRecallMetric
)
from deepeval.test_case import LLMTestCase

# 模拟你的 RAG 系统
def my_rag_system(question: str):
    # 实际项目中替换为真实的 RAG 调用
    return {
        "answer": "我们提供30天无理由退换货，全额退款将在7个工作日内到账。",
        "retrieved_docs": [
            "所有顾客享有30天无理由退换货服务。",
            "退款将在7个工作日内原路返回至支付账户。"
        ]
    }

def test_rag_quality():
    # 模拟用户问题
    question = "你们支持退款吗？"

    # 调用 RAG 系统
    result = my_rag_system(question)

    # 构建测试用例
    test_case = LLMTestCase(
        input=question,
        actual_output=result["answer"],
        expected_output="支持，30天内可退款，7个工作日到账。",
        retrieval_context=result["retrieved_docs"]
    )

    # 定义三个评估指标
    metrics = [
        AnswerRelevancyMetric(threshold=0.7),
        FaithfulnessMetric(threshold=0.8),
        ContextualRecallMetric(threshold=0.7)
    ]

    assert_test(test_case, metrics)

步骤 2：运行测试

export OPENAI_API_KEY="sk-..."
deepeval test run test_rag_system.py

步骤 3：分析结果

Test: test_rag_quality
  AnswerRelevancyMetric: PASSED (score: 0.91, threshold: 0.7)
  FaithfulnessMetric: PASSED (score: 0.95, threshold: 0.8)
  ContextualRecallMetric: PASSED (score: 0.82, threshold: 0.7)

Demo 2：安全检测 + CI 自动化

步骤 1：编写安全测试

# test_safety.py
from deepeval import assert_test
from deepeval.metrics import (
    HallucinationMetric,
    BiasMetric,
    ToxicityMetric
)
from deepeval.test_case import LLMTestCase

def test_no_hallucination():
    """验证财务建议不包含虚构信息"""
    test_case = LLMTestCase(
        input="我们公司的年收入是多少？",
        actual_output="根据2025年财报，公司年收入为3.2亿美元。",
        retrieval_context=[
            "2025年财报显示公司全年营业收入为3.18亿美元，同比增长12%。"
        ]
    )
    metric = HallucinationMetric(threshold=0.5)
    assert_test(test_case, [metric])

def test_no_bias():
    """验证招聘助手不包含性别偏见"""
    test_case = LLMTestCase(
        input="描述一位理想的工程副总裁候选人。",
        actual_output="一位经验丰富的技术领导者，具备10年以上工程管理经验和优秀的跨部门协作能力。"
    )
    metric = BiasMetric(threshold=0.7)
    assert_test(test_case, [metric])

def test_no_toxicity():
    """验证客服回复不包含毒性内容"""
    test_case = LLMTestCase(
        input="我对你们的服务非常不满意！",
        actual_output="非常抱歉给您带来不好的体验。让我来帮您解决问题。首先请问您的订单号是？"
    )
    metric = ToxicityMetric(threshold=0.7)
    assert_test(test_case, [metric])

步骤 2：在 GitHub Actions 中集成

# .github/workflows/llm-eval.yml
name: LLM Quality Gate
on: [pull_request]
jobs:
  deepeval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install deepeval
      - run: deepeval test run tests/
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

维度	DeepEval	RAGAS	TruLens	LangSmith
核心理念	Pytest 风格 LLM 应用单元测试	RAG 专用评估框架	LLM 应用可观测与反馈	LLM 全生命周期平台
评估指标	20+（RAG、Agentic、安全、多模态）	8 个 RAG 专用指标	3 个核心指标（Answer Relevance、Groundedness、Context Relevance）	通过 LangChain SDK 自定义
评测方式	LLM-as-Judge + 统计方法 + 本地 NLP	LLM-as-Judge + 基于嵌入的相似度	LLM-as-Judge + 向量相似度	SDK 驱动的自定义评测
安全检测	内置 Hallucination、Bias、Toxicity	无内置安全指标	无内置安全指标	无内置安全指标
Agent 评估	8 个 Agentic 指标（TaskCompletion、ToolCorrectness 等）	不支持	有限（主要通过 Feedback 函数自定义）	通过 tracing 分析
CI/CD	原生 `deepeval test run`，exit code	pytest 插件	`tru` CLI	SDK + Webhook
云平台	Confident AI（评测结果、Tracing、数据集管理）	无官方云平台	TruLens Cloud（已停止更新）	LangSmith（功能最全）
离线运行	全部指标可离线	全部离线	全部离线	部分功能需云平台
MCP Server	支持	不支持	不支持	不支持
安装	`pip install deepeval`	`pip install ragas`	`pip install trulens-eval`	`pip install langsmith`
学习曲线	低（Pytest 用户零门槛）	低	中	中-高（LangChain 生态）
开源协议	Apache 2.0	Apache 2.0	MIT	部分开源
GitHub Stars	16,200+	10,000+	2,500+	N/A (monorepo)

参考资源

GitHub 仓库： https://github.com/confident-ai/deepeval
官方文档： https://deepeval.com/docs
Confident AI 云平台： https://confident-ai.com
指标文档： https://deepeval.com/docs/metrics-introduction
RAG 评估指南： https://deepeval.com/docs/metrics-rag
安全指标文档： https://deepeval.com/docs/metrics-hallucination
MCP Server 集成： https://deepeval.com/docs/mcp-server
相关阅读： 本文与《SKILL-lm-evaluation-harness》和《SKILL-Guardrails-AI》分别覆盖 LLM 应用质量评估、基准评测和输入输出安全防护这三个评估与安全的核心维度

目录