deepeval

DeepEval 面向 LLM 应用的单元测试式评测框架。

补充说明

DeepEval 把每个样例写成 LLMTestCase，用 pytest 风格断言指标阈值，适合放进 CI 阻止回归。RAG 常用 AnswerRelevancy、Faithfulness、ContextualRelevancy 和 ContextualPrecision。

与 Ragas 的区别：DeepEval 更像测试框架（assert_test、数据集、非零退出码），Ragas 更像批量打分与实验分析。两者都依赖裁判模型，成本主要来自裁判调用。

安装与启动

pip install -U deepeval
export OPENAI_API_KEY="sk-..."

常用示例

把 RAG 用例写成 pytest，并用 deepeval test run 执行：

cat > test_rag.py <<'PY'
import pytest
from deepeval import assert_test
from deepeval.metrics import AnswerRelevancyMetric, FaithfulnessMetric
from deepeval.test_case import LLMTestCase

CASES = [
    LLMTestCase(
        input="磁盘满了怎么排查？",
        actual_output="先用 df -h 看分区，再用 du 找大目录。",
        retrieval_context=["df -h 查看使用率；du -sh * 定位大目录。"],
        expected_output="df -h、du、lsof 配合定位。",
    ),
]

@pytest.mark.parametrize("case", CASES)
def test_rag_quality(case):
    metrics = [
        AnswerRelevancyMetric(threshold=0.7),
        FaithfulnessMetric(threshold=0.7),
    ]
    assert_test(case, metrics)
PY

deepeval test run test_rag.py

接入本地 OpenAI 兼容服务（vLLM、SGLang、Ollama 的 /v1）作为裁判：

export OPENAI_API_KEY=EMPTY
export OPENAI_BASE_URL=http://localhost:8000/v1
deepeval test run test_rag.py

在 CI 中直接运行；断言失败时 CLI 返回非零退出码：

deepeval test run test_rag.py || exit 1

需要云端报告时再登录 Confident AI，敏感数据环境先确认上报范围：

deepeval login

易错点与排错

• AnswerRelevancyMetric 只要求 input 和 actual_output，而 FaithfulnessMetric 必须有 retrieval_context；字段缺失会直接报错，不是简单扣分。
• expected_output 不是所有指标都必需，但 ContextualPrecision/Recall 一类指标依赖它；用错指标会得到无意义高分。
• 直接用 pytest 跑 assert_test 可能绕过 deepeval test run 的统计与异常处理，CI 应统一用官方 CLI。
• 本地裁判模型不支持 JSON 输出时，指标解析失败；用 vLLM 时开启 guided JSON，或换支持 function calling 的模型。
• 裁判温度、模型版本和 prompt 变化都会导致分数漂移；固定 temperature=0、记录裁判模型名和 deepeval 版本。
• 并发测试会撞裁判 API 限流，表现为随机失败；降低并发、加重试，并把限流错误与真实质量失败分开。
• threshold 默认值不一定适合业务，先人工标注一批样本校准，再写进 CI，避免阈值过松或天天红。
• 使用 GEval 时 criteria 太抽象，裁判会自由发挥；把评分规则拆成可判断的条目，并给出反例。
• 登录云端会把测试结果上传；隐私场景应关闭上报或使用自托管方案。

读完自测

合上页面，先回答，再展开对照。

1. RAG 的三个核心测试字段是什么？
2. 如何让评测在 CI 中真正失败？
3. 本地 vLLM 当裁判要注意什么？

相关条目

• ragas
• promptfoo
• langfuse
• evidently
• vllm