DeepEval LLM评测框架：从入门到生产完全指南

DeepEval LLM评测框架：从入门到生产完全指南

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

一个客服机器人上线前夜的故事

周四晚上，你盯着刚合并的prompt改动：只调整了两句措辞，客服机器人对退款政策的回答却开始编造不存在的条款。测试脚本里没有任何一条用例能抓到这种漂移，因为你们一直在"人肉抽查"。第二天早上，你把上周的对话日志拉了200条，需要一个能自动给每条回答打分、并把不达标的挑出来的工具——DeepEval这个 LLM 评测框架（基于 LLM 作为裁判来给输出打分的测试框架）就是为这类场景准备的：它让你像写单元测试一样，给 LLM 应用写可回归的评测。

DeepEval 定位：一个专测 LLM 应用的 pytest 式框架

DeepEval 是一个用于 LLM 应用评测的开源 Python 框架，用法和 pytest 类似，但每条"断言"背后是一个评测指标。和同类工具相比，它的差异点集中在四处：

• pytest 原生：用例就写在普通的test_*.py文件里，deepeval test run一条命令出报告，不用另学一套 runner。
• 指标覆盖全链路：内置 60 余个指标，覆盖 RAG、Agent 轨迹、多轮对话、安全合规、多模态与语音，每个指标都能独立调用。
• 裁判模型可换：打分用的 judge 可以是 OpenAI、Anthropic，也可以是你自己包装的本地模型，评测逻辑不用动。
• 轨迹级评测：内置基于 OpenTelemetry（一套标准化的分布式追踪协议）的 tracing，能还原 Agent 的每一步决策和工具调用，而不只是看最终输出。

当前版本 4.2.0，要求 Python ≥ 3.9，License 为 Apache-2.0。

架构走读：一条评测从用例到报告的数据流

抛开组件清单，看数据怎么流：

1. 输入是LLMTestCase：一个结构化数据，装下 input、actual_output、expected_output、retrieval_context。设计意图是把"应用产出"和"评测"解耦——你的应用怎么实现不重要，交出一个标准用例即可。
2. 指标层按裁判打分：每个指标内部用 judge LLM 按模板对用例打分，分数统一归一到 0-1；threshold判定逻辑集中在基类BaseMetric.is_successful()，新指标只需实现measure与a_measure。这是刻意的约束，保证几十个指标行为一致。
3. trace 捕获中间轨迹：对 Agent 场景，OTel 层记录完整的调用序列，TaskCompletionMetric这类轨迹指标直接消费它，而不是只看最终答案。
4. 输出是 test run：pytest 插件把整场运行的分数聚合成一次 test run，可导出 JSON、可同步到平台做跨版本对比，这是"回归"能成立的基础。

10分钟跑通第一个评测用例

安装只要一条命令：pip install -U deepeval。下面这段代码在做什么：定义一个 GEval 裁判指标（判断回答是否符合期望），构造一条测试用例，然后断言。代码取自 README 的 quickstart，把actual_output换成你应用的真实输出即可。

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

GEval 需要裁判模型，导出一个 API key 即可（也可换成自包装的本地模型）：

export OPENAI_API_KEY="..." deepeval test run test_chatbot.py

你看到的是一行带 PASS/FAIL 的用例结果，加上每个指标的 0-1 分数；阈值 0.5 意味着分数跌破一半才算失败。这个结果的价值在于：它是一次可复跑的判定，下次改 prompt 再跑一遍，分数涨跌一目了然。

核心能力拆解：你真正关心的三个问题

结果可复现吗？可以，前提是你固定两样东西：评测数据集和裁判模型。分数本身是裁判输出的确定性函数，test run 会把参数（可用log_hyperparameters记录）和结果一起落盘，跨版本对比时口径一致。

换个模型后端要改多少代码？通常是一行。指标构造时传入你自己的模型对象即可，例如FaithfulnessMetric(model=your_local_model)，评测脚本其余部分不动。

批量跑几千条数据扛得住吗？扛得住，靠的是异步并发加限流。evaluate和evals_iterator支持AsyncConfig，默认max_concurrent=20；测试文件层面还可以用 pytest-xdist 多进程分发。

三种评估粒度怎么选，看这张表：

落地姿势：三种角色的工作流变化

独立开发者。最痛的点是"每次改 prompt 都在赌"。用 DeepEval 之后：把线上抓的几十条好问题存成 golden 数据集；用例写成普通 pytest 文件；本地deepeval test run一分钟出分；不达标的指标直接暴露在哪条用例上。边界要说清楚：它保证的是"相对上次没有变差"，不替你做产品决策。

平台工程团队。最痛的点是多个团队各写各的评测，口径不一致、结果不可比。引入后：CI 里统一跑deepeval test run作为门禁；结果同步到平台，跨项目横向可比；失败用例回流成新的数据集条目。边界：平台同步属于配套的 Confident AI 服务，纯本地跑也完全可用，只是少了跨团队视图。

算法研究员。最关心模型与 prompt 版本的分数差异。evaluate()可以在 notebook 里直接跑，compare支持多模型横向对比，指标层还会记录每次评测的 token 消耗和成本，方便你算"质量提升花了多少评测费"。边界：对比的前提是数据集和裁判配置完全一致，别在换裁判模型的同时换数据集。

进阶：并发配置与自定义指标骨架

万级用例的异步并发与限流配置

大规模评测的瓶颈几乎都在裁判 API 的限流上。AsyncConfig把评测请求做成异步并发，两个参数控制节奏：

from deepeval.evaluate.configs import AsyncConfig # max_concurrent 控制并发数，throttle_value 在每条请求间加间隔 async_config = AsyncConfig(run_async=True, max_concurrent=10, throttle_value=0.5)

这套配置能压住 429 错误，代价是总耗时被限流拉长；本地 NLP 类指标（如 ExactMatch、PatternMatch）不经过裁判 API，没有这个瓶颈。

8行骨架写出一个自定义指标

继承BaseMetric实现两个方法，框架会把你的指标和内置指标放进同一套流程（阈值判定、报告、pytest 断言都自动生效），完整清单可翻 自定义指标文档/)。

from deepeval.metrics import BaseMetric from deepeval.test_case import LLMTestCase class LengthLimitMetric(BaseMetric): def measure(self, test_case: LLMTestCase, *a, **k) -> float: return 1.0 if len(test_case.actual_output) <= 200 else 0.0 async def a_measure(self, test_case: LLMTestCase, *a, **k) -> float: return self.measure(test_case)

两个 trade-off 值得提前知道：LLM 裁判类指标每条用例都会产生真实 token 开销，大规模回归前先估预算；另外轨迹级指标依赖 tracing 开启，纯黑盒跑法拿不到中间步骤。

生态：框架集成与路线图

最相关的上下游工具，按集成方式列：

• OpenAI / Anthropic：官方 client wrapper，换 import 即可拿到 trace 和评测。
• LangChain / LangGraph：通过CallbackHandler挂载到config["callbacks"]，链式调用全程被记录。
• Pydantic AI / CrewAI：前者靠类型安全的自动回调，后者一行instrument_crewai()完成埋点。
• LlamaIndex：专用 handler 捕获 RAG 检索上下文，直接喂给上下文类指标。
• OTel 后端：trace 是标准 OpenTelemetry 格式，可导出到任意兼容后端，不锁定单一平台。

社区信号方面：仓库自带一套 TypeScript SDK 和完整文档站源码，Python 侧测试套件覆盖到指标、tracing、集成三大块；README 列出的框架集成目前有 12 个。路线图在 README 中有明确清单：DAG 自定义指标和 Guardrails 两项尚未完成（已勾选的包括 G-Eval、RAG 指标、会话指标、红队测试等）。

你的下一步

1. git clone https://gitcode.com/GitHub_Trending/de/deepeval，本地pip install -U deepeval，用本文第4章的用例跑通第一条 PASS。
2. 打开 getting-started 文档，把 quickstart 里的用例改成你业务的真实输入输出，选 2-3 个贴合场景的指标。
3. 在 CI 流水线里加一步deepeval test run，每晚跑一次基线数据集，分数异常就收到告警。

做完这三步，你手里会有的是一个可以每晚自动回归的 LLM 质量基线：任何一次 prompt 或模型改动，第二天早上就知道是涨了还是跌了。

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