如何 10 分钟跑通 DeepEval 本地 LLM 评测：一份完整的新手指南

如何 10 分钟跑通 DeepEval 本地 LLM 评测：一份完整的新手指南

【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval

如果你已经搭好了 RAG 问答或 AI Agent 应用，但每次改 prompt、换模型后只能靠人工抽查来判断质量，这篇指南就是为你写的。DeepEval 是一个专用于 LLM 评测的开源框架：它像 pytest 一样收集测试用例，用内置指标在本机自动打分。读完本文，你会完成三件事——跑通第一条评测、用指标批量给 RAG 应用打分、把评测接进 CI 做自动回归。

三步从零跑通 DeepEval 本地评测环境

步骤 1：安装 DeepEval

DeepEval 要求 Python 3.9+，在你的虚拟环境中执行：

pip install -U deepeval

它会自动接入 pytest，后续deepeval test run会以 pytest 的方式收集并执行你的评测文件。

步骤 2：写第一个测试用例

新建test_chatbot.py：

from deepeval import assert_test from deepeval.test_case import LLMTestCase, SingleTurnParams from deepeval.metrics import GEval 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, ) case = LLMTestCase( input="If these shoes don't fit, what can I do?", actual_output="You can get a full refund within 30 days for free.", expected_output="We provide a full refund within 30 days for free.", ) assert_test(case, [metric])

这段代码把"用户问题 + 应用真实输出 + 期望答案"打包成一个测试用例，交给 GEval 这个 LLM-as-a-judge（让另一个大模型当裁判）指标按 0~1 分打分，低于 threshold 就判定失败。actual_output在真实项目里应替换成你应用的真实输出。

步骤 3：执行评测

deepeval test run test_chatbot.py

终端会输出每条指标的得分和整体结论，首次跑通 ✅ 之后，你就有了一套可以反复执行的 LLM 回归测试。更多入门细节可参考官方文档 docs/content/docs/getting-started.mdx。

用 DeepEval 内置指标给 RAG 应用打分

逐个手写评测逻辑很慢，DeepEval 内置了 30+ 开箱即用的指标（实现在 deepeval/metrics/），覆盖相关性、事实性、安全性等维度。最常用的几个：

当你手头有一批 Golden 数据（每条含 input、actual_output、retrieval_context）时，用evaluate()一次批量打分：

from deepeval import evaluate from deepeval.metrics import AnswerRelevancyMetric, FaithfulnessMetric evaluate( test_cases=dataset, metrics=[ AnswerRelevancyMetric(threshold=0.7), FaithfulnessMetric(threshold=0.7), ], )

evaluate()会跑完所有用例并输出包含各指标得分与通过率的汇总，方便你对比不同 prompt 或不同模型的版本差异。指标全貌与选型建议见 docs/content/docs/metrics-introduction.mdx。

测试用例不够？批量合成 Golden 数据

真实业务的测试数据往往很少，DeepEval 的 Synthesizer 可以基于你描述的"场景 + 任务 + 输入格式"批量生成 Golden 数据集，省去手工标注。

from deepeval.synthesizer import Synthesizer from deepeval.synthesizer.config import StylingConfig styling = StylingConfig( scenario="A customer support chatbot for a shoe store", task="Answer questions about returns and refunds", input_format="A short user question in plain language", ) goldens = Synthesizer(styling_config=styling).generate_goldens_from_scratch(num_goldens=20)

运行后你会得到 20 条带标准答案的测试数据，可以直接喂给前面的evaluate()。如果手头已有业务文档，也可以改用generate_goldens_from_docs从文档中提取问答对，让评测更贴近实际场景。

把 DeepEval 接进 CI/CD：模型一改就自动回归

人工跑评测很容易漏，把评测放进流水线，才能保证"每次改动都有评测兜底"。DeepEval 的测试文件就是标准 pytest 用例，接入 CI 很简单：

jobs: eval: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.11" - run: pip install -U deepeval - run: deepeval test run tests/

这样每当代码合并或模型更新时自动触发一轮评测 🔁，指标不达标流水线即失败，prompt 漂移、模型降级这类问题能在上线前被拦住。

DeepEval 评测常见问题排查

问题 1：用例总是失败，得分忽高忽低。LLM-as-a-judge 类指标本身带有一定随机性。先确认裁判模型可用（需配置对应模型的环境变量，或换成你指定的模型），再把 threshold 调到合理及格线；对关键用例连续跑几次，观察得分是否稳定。

问题 2：RAG 指标报错或结果无效。Faithfulness、Contextual 系列指标都依赖retrieval_context字段。检查你的测试用例或 Golden 里是否填入了实际检索到的上下文，而不是只填了问题和答案。

问题 3：评测跑得慢、裁判调用费用高。裁判模型调用次数约等于用例数 × 指标数。可以先用 ExactMatchMetric、JsonCorrectnessMetric 这类纯规则指标做初筛，再对可疑用例跑 LLM 裁判指标，也能明显降低调用量。

问题 4：评测数据不想出内网。把裁判模型换成本地部署的开源模型即可：继承 DeepEval 提供的DeepEvalBaseLLM基类、实现自己的调用接口，评测流程就完全在本机执行，数据不出环境。

总结：下一步可以直接做的 3 件事

DeepEval 的价值不在于单个指标多精确，而在于把"LLM 质量"从主观感受变成可量化、可回归的测试，让每次改 prompt、换模型都有据可依。建议按顺序推进：

1. 克隆仓库git clone https://gitcode.com/GitHub_Trending/de/deepeval，对照 examples/ 目录的示例，给你的应用写下第一条assert_test。
2. 用 Synthesizer 生成 20 条 Golden 数据，跑一次 AnswerRelevancy + Faithfulness，记下基线分数。
3. 把deepeval test run加进 CI，让"改一版 prompt 就回归一次"成为团队的默认流程。

【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval