DeepEval 实战入门：5 步把 LLM 应用变成可自动评分的测试套件

DeepEval 实战入门5 步把 LLM 应用变成可自动评分的测试套件【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval你写了一个 RAG 客服机器人每次改完提示词都要手动抽查十几条回答判断有没有编造、有没有答非所问。DeepEval 是一个开源 LLM 评估框架像写 pytest 用例一样写评估用例用 GEval、faithfulness 等指标给模型输出自动打分并可以直接挂进 CI/CD每次发版都跑一遍。从人工抽查到自动评分它解决什么问题LLM 应用有一个尴尬的地方输出是概率性的传统的assert写不出来。你只能靠人眼抽查而抽查既慢又不一致——今天觉得这条回答合格明天再看可能就否决了。改个提示词、换个底座模型你甚至说不清质量是变好还是变坏。DeepEval 的做法是把一次问答抽象成一条带字段的测试用例输入、实际输出、期望输出、检索上下文再定义若干个指标对每条用例打分分数落在 0 到 1 之间超过阈值算通过低于阈值算失败。它同时支持把整个应用当黑盒评也支持钻进应用内部对检索、工具调用等单个组件分别评分。评估在本地运行你可以指定任意 LLM 充当评委。安装 DeepEval 并跑通第一个评估环境要求是 Python 3.9 及以上安装一行命令pip install -U deepeval新建一个test_chatbot.py内容如下。这里用GEval——一个基于LLM 当评委思路的通用指标你用自然语言描述评分标准它就能对任意自定义维度打分from deepeval import assert_test from deepeval.metrics import GEval from deepeval.test_case import LLMTestCase, SingleTurnParams def test_refund_answer(): metric GEval( nameCorrectness, criteriaIs the actual output correct per the expected output?, evaluation_params[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT], threshold0.5, ) case LLMTestCase( inputWhat if these shoes dont fit?, actual_outputYou have 30 days for a full refund, no extra cost., expected_outputWe offer a 30-day full refund at no extra costs., ) assert_test(case, [metric])跑之前先配置评委模型用的 API Key用 OpenAI 做评委的话export OPENAI_API_KEY你的密钥然后用它自带的 CLI 运行deepeval test run test_chatbot.pyassert_test的行为和普通断言一致所有指标分数都达到threshold时测试通过否则 pytest 报错退出分数和失败原因会打印在终端里。你可以把这条命令原样写进 CI 流水线提示词或模型一有回退流水线就会红。按使用场景挑指标DeepEval 的指标都在 deepeval/metrics/ 下按 40 多个模块组织。与其背清单不如按你的场景对号入座评 RAG 管道时FaithfulnessMetric忠实度回答里的每个事实是否都能从retrieval_context里找到依据是回答有没有编造的直接度量。AnswerRelevancyMetric答案相关性回答是否切题而不是自顾自地复述检索片段。ContextualRecallMetric/ContextualPrecisionMetric不评回答而是评检索环节——期望答案需要的信息有没有被检索到、相关片段是否排在前面。当你怀疑问题出在检索而不是生成时用这一对指标定位。注意这些指标都要求你在用例里填retrieval_context字段漏填就无法计算。调试智能体时TaskCompletionMetric任务最终是否完成适合端到端看整体。ToolCorrectnessMetric/ArgumentCorrectnessMetric有没有调对工具、参数传得对不对——智能体最常见的失败模式。StepEfficiencyMetric有没有绕远路做了不必要的步骤。PlanAdherenceMetric实际执行是否偏离了规划的路径。评估多轮对话时KnowledgeRetentionMetric用户第一轮告诉机器人的信息第五轮还记得吗。ConversationCompletenessMetric整段对话下来用户需求是否被真正满足。RoleAdherenceMetric机器人是否始终守着自己的人设比如客服不能跑去聊投资。安全与合规检查ToxicityMetric、BiasMetric、PIILeakageMetric用于扫描输出中的毒性内容、偏见倾向和个人信息泄露适合在上线前和回归测试里固定跑一遍。每个指标都可以单独实例化、调measure(test_case)手动打分也都能拿到一段自然语言的解释reason属性方便你判断它为什么打这个分。批量评估一个数据集单条用例验证流程跑通后下一步通常是拿一批固定问题反复回归。DeepEval 把golden 问题列表 对应测试用例打包成EvaluationDatasetfrom deepeval import evaluate from deepeval.dataset import EvaluationDataset, Golden from deepeval.metrics import AnswerRelevancyMetric from deepeval.test_case import LLMTestCase dataset EvaluationDataset( goldens[Golden(inputWhats the refund policy?)]) for golden in dataset.goldens: case LLMTestCase( inputgolden.input, actual_outputmy_chatbot(golden.input), retrieval_context[All customers get a 30-day full refund.], ) dataset.add_test_case(case) evaluate(dataset.test_cases, [AnswerRelevancyMetric(threshold0.7)])相比单条用例这里多做了两件事一是问题golden和结果test_case分开管理换模型或改提示词后重跑同一批问题即可对比二是evaluate一次汇总所有用例的分数在终端输出整体通过率而不是逐条抛断言。golden 集也可以从 CSV 导入或用内置的 synthesizer 从文档自动合成不用手工攒问题。给智能体路径做组件级追踪基础用法是把应用当黑盒只看输入和最终输出。但智能体失败的原因往往藏在中间——检索没取到对的内容、工具调错了、子代理交接时丢信息。只评最终输出你只知道挂了不知道哪一步挂了。组件级评估靠两个装饰器解决observe把一个函数变成可追踪的 spanupdate_current_span给 span 挂上测试用例指标就绑定到这一步而不是整个流程from deepeval.tracing import observe, update_current_span from deepeval import evaluate from deepeval.dataset import Golden from deepeval.metrics import TaskCompletionMetric from deepeval.test_case import LLMTestCase observe(metrics[TaskCompletionMetric()]) def retrieve_and_answer(q): ctx retriever(q) update_current_span(test_caseLLMTestCase(inputq, actual_outputctx)) return llm_answer(q, ctx) evaluate(observed_callbackretrieve_and_answer, goldens[Golden(inputWhats the refund policy?)])这样检索子步骤有了自己的分数你才能区分检索差还是生成差。如果你的框架是 LangChain、LlamaIndex、CrewAI、OpenAI 等deepeval/integrations/ 下提供了现成的回调和埋点不用手工observe。更进一步dataset.evals_iterator(metrics[...])会在迭代时自动收集整条执行轨迹模型决策、工具调用的有序序列对轨迹本身跑评估这是纯黑盒评分做不到的。常见的坑与边界评委模型要花钱且有噪声。GEval 这类 LLM-as-judge 指标每次评估都要真实调用 LLM 给输出打分有 token 费用和延迟而且评委本身不是 100% 稳定同一个输出两次评分可能有小幅出入。所以threshold不要拍脑袋定成 0.5 就完事——先跑十几条样本看分数分布再决定及格线并且阈值调高比如 0.7会让失败率显著上升这是取舍而不是 bug。登录云平台后用例会上传。不登录时所有评估纯本地跑数据不出机器但执行deepeval login接入 Confident AI 平台后测试用例的输入输出会自动同步到云端生成报告。对数据敏感的项目这是一个明确的隐私边界需要自行权衡。API 命名有新旧两套。老教程里的LLMTestCaseParams已标记弃用当前版本应使用SingleTurnParams否则会收到弃用警告。如果你照着网上旧文章写代码注意这一处差异。部分指标强依赖字段。上文提过 RAG 指标需要retrieval_context工具类指标如ToolCorrectnessMetric则需要expected_tools等字段。字段没填时指标无法计算或得分失真报错信息有时并不直观。环境变量加载有时机。DeepEval 在import时就自动加载当前目录的.env/.env.local优先级是进程环境变量 .env.local.env。如果你指望在脚本运行时才修改环境变量会发现它已经晚了。下一步与延伸阅读从examples/getting_started/test_example.py的完整示例起步把GEval换成FaithfulnessMetric试试 RAG 场景。攒一个 10–20 条问题的 golden 集把deepeval test run挂进 CI作为改提示词后的回归底线。对最弱的指标通常是忠实度做一次组件级追踪定位是检索还是生成环节的问题。跑几个不同评委模型如 GPT-4 与 Claude对比同一批评分验证你设定的阈值是否稳健。需要分享报告时再接入deepeval login在此之前保持纯本地评估。延伸阅读快速上手docs/content/docs/getting-started.mdx组件级评估docs/content/docs/evaluation-component-level-llm-evals.mdx端到端评估docs/content/docs/evaluation-end-to-end-single-turn.mdxMCP 场景示例examples/mcp_evaluation/指标源码总览deepeval/metrics/【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考