适用场景与目标

AI Agent 和 RAG 系统批量上线后，团队最常面临一个灵魂拷问：“这个系统比上周好了没有？”

传统的做法是”手动测试 → 发现问题 → 修提示词 → 再手动测试”循环，烧了大量 API 费用，却始终说不清改进有没有效果。原因在于：LLM 输出天然具有非确定性，一次测试结果只能反映”可能发生什么”，而不能说明”通常发生什么”。

DeepEval（Apache-2.0 开源，由 Confident AI 维护）正是为解决这一痛点而生。它将 LLM 输出的质量评估变成工程化、可量化、可自动化的过程，核心能力包括：

• 50+ 研究背书的评估指标（幻觉率、忠实度、答案相关性、毒性、偏见等）
• 与 pytest 无缝集成，评估即单元测试，可直接接入 CI/CD
• 支持 RAG 三元组（查询 / 检索上下文 / 回答）评估、AI Agent 多轮对话评估
• 合成测试数据生成 + 红队安全扫描
• 被 OpenAI、Google、Microsoft 内部使用，社区活跃

落地目标：在一周内，为你的 AI 应用搭建起自动化质量评估管线，让每一次 Prompt 修改都有数据支撑而非”感觉好了”。

---

最小可行方案（MVP）步骤

第一步：安装与初始化

pip install deepeval

登录 Confident AI（可选，用于云端结果查看；纯开源可跳过）：

deepeval login

第二步：定义评估数据集

DeepEval 使用 Golden 对象定义输入/期望输出，类似单元测试的测试用例：

from deepeval.dataset import Golden, EvaluationDataset

# 单轮测试用例
goldens = [
    Golden(input="什么是 RAG？"),
    Golden(input="用一句话解释 Transformer 架构"),
]

# 多轮对话测试用例（AI Agent 场景）
from deepeval.dataset import ConversationalGolden

multi_turn_goldens = [
    ConversationalGolden(
        scenario="用户先问天气，再问是否需要带伞",
        expected_outcome="第一轮给出城市天气，第二轮根据天气判断是否建议带伞"
    ),
]

dataset = EvaluationDataset(goldens=goldens)
# dataset.save_as(file_type="json", directory="./test_data")

第三步：封装你的 LLM 应用

所有 LLM 应用只需添加 @observe 装饰器即可接入 DeepEval 评估：

from deepeval import observe

@observe
def your_rag_app(query: str) -> str:
    # 你的 RAG pipeline
    context = retrieve_docs(query)
    answer = llm_generate(query, context)
    return answer

@observe
def your_agent_app(user_message: str, conversation_history: list) -> str:
    # 你的 Agent pipeline
    response = agent.run(user_message, history=conversation_history)
    return response

第四步：运行评估

from deepeval import evaluate
from deepeval.metrics import AnswerRelevancyMetric, FaithfulnessMetric, HallucinationMetric

metrics = [
    AnswerRelevancyMetric(threshold=0.5),
    FaithfulnessMetric(threshold=0.7),
    HallucinationMetric(threshold=0.3),
]

evaluate(
    test_cases=dataset.test_cases,
    metrics=metrics,
)

在任意 Python 文件（如 test_evaluation.py）中运行：

python test_evaluation.py

或在 pytest 中运行（推荐，CI/CD 友好）：

pytest test_evaluation.py -v

---

关键实现细节

核心指标速查

指标	测量什么	适用场景
AnswerRelevancyMetric	回答与问题的相关性	所有场景
FaithfulnessMetric	回答是否忠实于检索上下文	RAG 类应用
HallucinationMetric	回答是否包含上下文中不存在的内容（幻觉）	RAG/知识助手
ContextualPrecisionMetric	检索上下文中有多少相关信息被正确利用	检索质量
ContextualRecallMetric	检索上下文是否覆盖了完整答案	检索召回
ToxicityMetric	回答是否包含有害内容	对外服务
BiasMetric	回答是否存在偏见	对外服务
SummarizationMetric	摘要是否保留了原文核心信息	摘要类任务

CI/CD 集成示例

在 GitHub Actions 中 gate merge：

# .github/workflows/llm-eval.yml
name: LLM Evaluation
on:
  pull_request:
    paths: ['src/**/*.py']

jobs:
  evaluate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install deepeval openai faiss-cpu
      - run: pytest tests/test_llm_outputs.py --strict --tb=short
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

自定义评估指标（GEval）

如果内置指标不够用，用自然语言定义你自己的指标：

from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCaseParams

# 定义一个"专业度"评估指标
professionalism = GEval(
    name="Professionalism",
    criteria="评估回答是否保持专业语气、避免口语化表达",
    evaluation_steps=[
        "判断回答是否全程保持专业语气",
        "检查语言是否体现领域专业性",
        "确认回答是否清晰、尊重，避免俚语或过于随意的表达",
    ],
    evaluation_params=[LLMTestCaseParams.ACTUAL_OUTPUT],
    threshold=0.7,
)

RAG 三元组评估

from deepeval.metrics import (
    AnswerRelevancyMetric,
    FaithfulnessMetric,
    ContextualPrecisionMetric,
)

# 创建包含检索上下文的测试用例
from deepeval.test_case import LLMTestCase

test_case = LLMTestCase(
    input="2026年 Q1 收入是多少？",
    actual_output="2026年 Q1 收入为 12 亿元，同比增长 20%。",
    expected_output="2026年 Q1 收入为 12 亿元，同比增长 20%。",
    context=[
        "2026年 Q1：收入 12 亿元，同比增长 20%",
        "2026年 Q2：收入 14 亿元，同比增长 25%",
    ],
)

metrics = [
    AnswerRelevancyMetric(),
    FaithfulnessMetric(),
    ContextualPrecisionMetric(),
]

evaluate(test_cases=[test_case], metrics=metrics)

---

常见坑与规避清单

坑 1：threshold 设置过于严格导致 CI 全线飘红

现象：初次接入时所有测试都是 FAIL，不是因为系统差，而是 threshold 默认值（0.5）偏高。

规避：

• 先跑一次不设 threshold 的评估，记录分数分布
• 再根据 P50/P80 分位数设置合理的 threshold -strict mode 下必须每个指标都超过 threshold 才能通过，建议初期关闭

# 初期评估（不设 threshold），观察分数分布
metrics = [AnswerRelevancyMetric(), FaithfulnessMetric()]
evaluate(test_cases=dataset.test_cases, metrics=metrics)

# 确认阈值后再打开严格模式
metrics = [AnswerRelevancyMetric(threshold=0.4, strict_mode=False)]

坑 2：只评估最终输出，不评估中间步骤

现象：Agent 选错了工具、参数填错了，但最终回答恰好”蒙对了”，评估通过但实际有问题。

规避：使用多粒度评估——不仅评估最终答案，还要评估每个 tool call 的选择和参数准确性。DeepEval 支持对 Agent 的每个 action 设置 ToolCallAccuracyMetric 等中间层指标。

坑 3：数据集太小导致评估结果不稳定

现象：同一个测试跑 5 遍，分数波动超过 15%。

规避：

• 每个场景至少 20 个测试用例
• 使用 include_reason=True 查看评估理由，识别异常案例
• 对于不确定的案例，用 GEval 配合人工 review

坑 4：评估 LLM 与被测 LLM 使用同款模型增加偏差

现象：用 GPT-4o 评估 GPT-4o-mini，因为模型风格相近导致分数虚高。

规避：DeepEval 支持任意 LLM 作为评估器，不要使用与被测系统相同的模型，建议使用更强大的模型（如 GPT-4o 评估 GPT-4o-mini 应用）：

from deepeval.metrics import GEval

professionalism = GEval(
    name="Professionalism",
    model="gpt-4o",  # 用更强大的模型评估
    criteria="...",
    evaluation_params=[LLMTestCaseParams.ACTUAL_OUTPUT],
)

坑 5：合成数据质量差导致评估失真

现象：用 Synthesizer 自动生成的测试数据与实际用户 query 分布差距大，评估通过但上线翻车。

规避：

• 合成数据只作为补充，核心评测集必须基于真实用户 query
• 用 ConversationalGolden 做多轮对话评估时，scenario 描述要具体，避免过于泛化
• 定期用生产日志中的真实失败案例更新 Golden 数据集

坑 6：忽视了跨语言场景的特殊性

现象：中文 RAG 系统的 Embedding 模型（如 OpenAI text-embedding-3-large）数据出境存在合规风险，且中文语义评估标准与英文不同。

规避：

• 中文场景建议使用 bge-large-zh-v1.5 或 FlagEmbedding/bge-m3（可私有化部署）
• 中文幻觉检测需要专门的领域知识，避免直接用英文评估 prompt 直译

---

成本 / 性能 / 维护权衡

成本

• DeepEval 本身免费（Apache-2.0 开源）
• 评估会产生额外的 LLM 调用费用（作为 judge 的模型）
• 建议策略：小模型评估 → 发现异常 → 大模型复核

评估规模	推荐 Judge 模型	单次评估成本估算
日常 CI（100 次 / 天）	GPT-4o-mini / Qwen-plus	~$0.01 / 次
全量回归（1000 次 / 天）	GPT-4o-mini	~$0.005 / 次
关键场景精细评估	GPT-4o	~$0.05 / 次

性能

• 评估延迟 ≈ LLM judge 响应时间，RAG 场景单次评估通常 < 10 秒
• 通过并行 ThreadPoolExecutor 可将评估速度提升 3-5 倍
• 云端 Confident AI 平台提供批量评估 + 历史趋势追踪，适合团队协作

维护

• 评估数据集需要持续更新：每次线上 bug 修复后新增对应测试用例
• 建议每月 review 一次数据集，清理低质量或过时的 Golden
• 与 A/B 测试结合：每次 Prompt 改动必须产生评估分数提升，否则 rollback

---

一周内可执行行动清单

Day 1-2：安装 + 跑通最小流程

• pip install deepeval
• 准备 20 个核心场景的 Golden 测试用例
• 为你的 RAG/Agent 应用添加 @observe 装饰器
• 运行第一次评估，记录各指标分数

Day 3-4：接入 CI/CD + 配置指标

• 将评估集成到 GitHub Actions 或你使用的 CI 平台
• 配置核心指标 threshold（先宽松，确保初期不阻断开发）
• 启用 include_reason=True，分析低分案例的评估理由

Day 5：建立评估文化

• 制定规范：每次 Prompt 修改必须通过评估，分数不允许低于基线
• 建立 baseline 数据集快照，标记每次大版本改动的分数差异
• 选定评估 judge 模型（建议与被测模型不同级别）

Day 6-7：扩展 + 优化

• 扩展到多轮 Agent 评估场景（ConversationalGolden）
• 接入红队扫描，检测 prompt injection 等安全风险
• 如有条件，部署 Confident AI 云端平台，让 PM 和 QA 也参与评估 review

---

一句话总结：DeepEval 将 LLM 质量评估从”玄学”变成”数据驱动”——用 pytest 的方式跑评估，让每一次 AI 系统迭代都有客观数字支撑，而不是靠感觉判断”好像好了”。一周内即可落地，推荐立刻开始。