DeepEval 实战指南开源 LLM 评估框架的指标体系、评测流程与全链路溯源【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepevalDeepEvalThe LLM Evaluation Framework是一个开源的大语言模型评估框架定位类似于 Pytest但专门用于 LLM 应用的单元测试。它通过 G-Eval、任务完成度、答案相关性、幻觉检测等数十种指标以 LLM-as-a-judge 和可本地运行的 NLP 模型对 LLM 系统进行量化打分。读完本文你将掌握 DeepEval 的指标体系与选型方法、deepeval test run的完整评测流程、evals_iterator()全链路溯源评测的接入方式以及evaluate()、独立指标、.env加载机制等进阶用法并了解其底层源码的实现依据。一、DeepEval 是什么三种粒度的评估对象官方定义DeepEval 是一个易用、开源的 LLM 评估框架借鉴最新研究通过G-Eval、task completion、answer relevancy、hallucination等指标运行评测这些指标使用 LLM-as-a-judge 以及在你本机运行的其他 NLP 模型。无论你用 LangChain 还是 OpenAI 构建 AI Agent、RAG 流水线或聊天机器人DeepEval 都支持三种评估粒度见 README.md端到端End-to-End把 LLM 应用当黑盒整体评估完整 Agent 轨迹Complete Agent Trajectories覆盖 Agent 每一次决策与动作的完整路径单个 Agent 步骤Individual Agent StepsLLM 调用、工具使用、检索、子 Agent 交接等组件级评估。这类评测可用于选出最优的模型与提示词架构、防止提示词漂移prompt drifting、以及例如从 OpenAI 切换到 Claude 时验证质量是否回退。二、指标体系开箱即用的 LLM 评测指标DeepEval 的指标库位于 deepeval/metrics/ 目录从目录结构看每个指标家族如answer_relevancy/、faithfulness/、g_eval/、task_completion/都包含独立的实现与评分模板文件。所有指标支持由你选择的任意 LLM、统计方法或本地 NLP 模型驱动。2.1 通用自定义指标指标说明G-Eval有研究背书的 LLM-as-a-judge 通用指标可按任意自定义标准评估接近人类判断精度实现见 g_eval.pyDAGDeepEval 基于图的确定性 LLM-as-a-judge 指标构建器实现见 dag/2.2 Agentic 指标指标说明Task Completion评估 Agent 是否达成目标Tool Correctness检查是否以正确参数调用了正确的工具Goal Accuracy衡量 Agent 达成预期目标的准确度Step Efficiency评估 Agent 是否存在不必要的步骤Plan Adherence检查 Agent 是否遵循了预期计划Plan Quality评估 Agent 计划本身的质量Tool Use衡量工具使用的质量Argument Correctness校验工具调用参数2.3 RAG 指标指标说明Answer Relevancy衡量 RAG 输出与输入的相关性Faithfulness评估 RAG 输出是否与检索上下文事实一致Contextual Recall衡量检索上下文与期望输出reference的对齐程度Contextual Precision评估相关检索节点是否排在更靠前位置Contextual Relevancy衡量检索上下文对输入的整体相关性RAGAS上述 answer relevancy、faithfulness、contextual precision、contextual recall 的均值实现见 ragas.py2.4 多轮对话Multi-Turn指标指标说明Knowledge Retention评估聊天机器人在整个会话中是否保持事实信息Conversation Completeness衡量聊天机器人是否在整个会话中满足用户需求Turn Relevancy评估每一轮回复是否持续相关Turn Faithfulness检查各轮回复是否有检索上下文的事实支撑Role Adherence评估聊天机器人是否全程遵守其角色设定2.5 MCP 指标指标说明MCP Task Completion评估基于 MCP 的 Agent 完成任务的有效性MCP Use衡量 Agent 使用可用 MCP Server 的有效性Multi-Turn MCP Use跨会话轮次评估 MCP Server 使用2.6 多模态指标指标说明Text to Image基于语义一致性与感知质量评估图像生成Image Editing基于语义一致性与感知质量评估图像编辑Image Coherence衡量图像与配文的一致性Image Helpfulness评估图像对用户理解文本的帮助程度Image Reference评估文本对图像的引用/描述准确性实现位于 multimodal_metrics/。2.7 其他指标指标说明Hallucination检查 LLM 相对于给定上下文是否生成事实正确的信息Summarization评估摘要是否事实正确且包含必要细节Bias检测 LLM 输出中的性别、种族或政治偏见Toxicity评估 LLM 输出的毒性JSON Correctness检查输出是否符合预期的 JSON SchemaPrompt Alignment衡量输出与提示词模板指令的对齐程度除指标库本身外README 还列出以下框架能力且都能从仓库源码中得到印证同时支持端到端与组件级评估deepeval/evaluate/可构建自定义指标并自动融入 DeepEval 生态基类 base_metric.py 与 plugins/生成单轮与多轮合成评测数据集synthesizer/无缝集成任意 CI/CD 环境deepeval test run会透传 pytest 退出码见 5.3 节基于评测结果自动优化提示词optimizer/含algorithms/、rewriter/、scorer/子模块不到 10 行代码在主流 LLM 基准上评测任意模型官方列出 MMLU、HellaSwag、DROP、BIG-Bench Hard、TruthfulQA、HumanEval、GSM8K从 deepeval/benchmarks/ 目录结构看还包含 ARC、BBQ、BoolQ、EquityMedQA、IFEval、LAMBADA、LogiQA、MathQA、SQuAD、WinoGrande 等任务。三、快速上手安装、登录与第一个端到端测试3.1 安装DeepEval 要求Python 3.9pip install -U deepeval3.2 创建账户强烈推荐登录 Confident AI 平台后可在云端生成可分享的测试报告免费且不需要额外代码deepeval login按 CLI 提示创建账户、复制 API Key 并粘贴进 CLI登录命令实现见 command.py。登录后所有测试用例会被自动记录。3.3 写第一个端到端测试创建测试文件touch test_chatbot.py假设你的 LLM 应用是一个基于 RAG 的客服聊天机器人test_chatbot.py内容如下来自 README.md 的 Human QuickStart仓库中 examples/tracing/test_chatbot.py 也有同类示例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( nameCorrectness, criteriaDetermine if the actual output is correct based on the expected output., evaluation_params[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT], threshold0.5 ) test_case LLMTestCase( inputWhat if these shoes dont fit?, # Replace this with the actual output from your LLM application actual_outputYou have 30 days to get a full refund at no extra cost., expected_outputWe 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])设置OPENAI_API_KEY环境变量也可以用自己的自定义模型作为评判 LLMexport OPENAI_API_KEY...在 CLI 中运行deepeval test run test_chatbot.py如果一切顺利测试用例应当通过。逐点拆解input模拟用户输入actual_output占位你的应用对该输入的实际输出expected_output表示该输入的理想答案GEval是有研究背书的自定义指标可按任意标准评估输出本例的criteria是基于expected_output判断actual_output是否正确所有指标分数都在 0–1 之间threshold0.5决定测试通过与否。3.4 测试用例数据结构源码视角LLMTestCase定义在 llm_test_case.py其核心字段为class LLMTestCase(BaseModel): input: str # 必填 actual_output: Optional[str] ... # 实际输出 expected_output: Optional[str] ... # 期望输出 retrieval_context: Optional[List[Union[str, RetrievedContextData]]] ...SingleTurnParams是声明式枚举llm_test_case.py列出指标可引用的全部字段INPUT、ACTUAL_OUTPUT、EXPECTED_OUTPUT、CONTEXT、RETRIEVAL_CONTEXT、METADATA、TAGS、TOOLS_CALLED、EXPECTED_TOOLS、MCP_SERVERS、MCP_TOOLS_CALLED、MCP_RESOURCES_CALLED、MCP_PROMPTS_CALLED。旧的LLMTestCaseParams名称已标记弃用源码中会对其发出DeprecationWarning。assert_test()的实现evaluate.py中有几个值得注意的机制调用check_at_least_one_metric_has_threshold至少一个指标必须设置 threshold才能断言任一指标失败时抛出AssertionError消息中包含每个失败指标的 name、score、threshold、strict 模式、error 与 reason若测试用例标记为flaky失败时只发出 warning 而不阻断 CIpytest 的 warnings summary 中可见。evaluate/assert_test等公共 API 在 deepeval/init.py 统一导出__all__中还包含login、compare、instrument、flush_traces等。四、deepeval test runCLI 参数详解deepeval test run本质上包装 pytest。其完整参数定义在 command.py可组合使用选项短选项作用--exit-on-first-failure-x首个用例失败即停止--show-warnings-w显示 warning默认禁用--identifier-id为该测试运行打标--num-processes-npytest 并发进程数--repeat-r每个用例重复运行次数--use-cache-c使用缓存的评测结果--ignore-errors-i忽略评测过程中的错误--skip-on-missing-params-s跳过缺少必需参数的用例--verbose-v打开详细模式--display-d结束时展示全部还是部分结果--mark-m按 pytest mark 筛选用例--official-o将该次运行标记为 Confident AI 上的官方基线需要CONFIDENT_API_KEY--pdb—失败时进入调试器--durations/--color—慢用例统计条数默认 10/ 彩色输出默认 yes两个对 CI 场景很重要的实现细节来自同一段源码额外参数透传Typer 配置了allow_extra_argsTrue因此deepeval test run test_chatbot.py -k smoke这类写法会把-k smoke直接透传给 pytest退出码透传源码在 pytest 返回非零码时显式sys.exit(int(pytest_retcode))使测试失败能正确在 CI 中暴露1失败2中断3内部错误4用法错误5未收集到用例。五、全链路溯源评测evals_iterator 与框架集成5.1 原理使用dataset.evals_iterator()实现见 dataset.py可把同一份数据集逐条跑过你的应用——无论是手动埋点还是通过 DeepEval 的框架集成。因为 tracing 捕获的是有顺序的模型决策、工具调用与中间步骤序列你可以对 Agent 走过的完整路径运行轨迹级trajectory-based评测。5.2 手动埋点示例from deepeval.tracing import observe, update_current_span from deepeval.test_case import LLMTestCase from deepeval.metrics import TaskCompletionMetric observe() def inner_component(input: str): output result update_current_span(test_caseLLMTestCase(inputinput, actual_outputoutput)) return output observe() def app(input: str): return inner_component(input) # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): app(golden.input)observe装饰器定义在 tracing.py支持将函数追踪为 spantype参数可指定agent、llm、retriever、tool或自定义类型并兼容同步、异步与异步生成器函数。5.3 框架集成示例DeepEval 的集成代码集中在 deepeval/integrations/ 与各 provider 包装模块中。以下是 README 给出的各框架接法均使用TaskCompletionMetric()评估本次运行捕获的完整轨迹OpenAI客户端包装 trace上下文管理器包装器位于 deepeval/openai/from deepeval.openai import OpenAI from deepeval.tracing import trace from deepeval.metrics import TaskCompletionMetric client OpenAI() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(): with trace(metrics[TaskCompletionMetric()]): client.chat.completions.create( modelgpt-4o, messages[{role: user, content: golden.input}], )OpenAI Agents仅需在集成 patch 生效后正常运行 Agentfrom agents import Runner from deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): Runner.run_sync(agent, golden.input)Anthropic客户端包装位于 deepeval/anthropic/from deepeval.anthropic import Anthropic from deepeval.tracing import trace from deepeval.metrics import TaskCompletionMetric client Anthropic() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(): with trace(metrics[TaskCompletionMetric()]): client.messages.create( modelclaude-sonnet-4-5, max_tokens1024, messages[{role: user, content: golden.input}], )LangChain回调处理器from deepeval.integrations.langchain import CallbackHandler from deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(): llm.invoke( golden.input, config{callbacks: [CallbackHandler(metrics[TaskCompletionMetric()])]}, )LangGraph同样走 LangChain 回调处理器但作用于 agent 状态from deepeval.integrations.langchain import CallbackHandler from deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(): agent.invoke( {messages: [{role: user, content: golden.input}]}, config{callbacks: [CallbackHandler(metrics[TaskCompletionMetric()])]}, )Pydantic AIfrom deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): agent.run_sync(golden.input)CrewAIfrom deepeval.integrations.crewai import instrument_crewai from deepeval.metrics import TaskCompletionMetric instrument_crewai() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): crew.kickoff({input: golden.input})AI SDKTypeScriptimport { generateText } from ai; import { configureAiSdkTracing } from deepeval/integrations/ai-sdk; import { TaskCompletionMetric } from deepeval/metrics; const tracer configureAiSdkTracing({ name: my-agent }); const ask (input: string) generateText({ model, prompt: input, experimental_telemetry: { isEnabled: true, tracer }, }); // This metric evaluates the complete trajectory captured for this run. for await (const golden of dataset.evalsIterator({ metrics: [new TaskCompletionMetric()], })) { await ask(golden.input); }MastraTypeScriptimport { Mastra } from mastra/core/mastra; import { Observability } from mastra/observability; import { DeepEvalExporter } from deepeval/integrations/mastra; import { TaskCompletionMetric } from deepeval/metrics; const mastra new Mastra({ agents: { agent }, observability: new Observability({ configs: { deepeval: { exporters: [new DeepEvalExporter()] }, }, }), }); // This metric evaluates the complete trajectory captured for this run. for await (const golden of dataset.evalsIterator({ metrics: [new TaskCompletionMetric()], })) { await mastra.getAgent(agent).generate(golden.input); }AWS AgentCorefrom deepeval.integrations.agentcore import instrument_agentcore from deepeval.metrics import TaskCompletionMetric instrument_agentcore() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): invoke({prompt: golden.input})LlamaIndex异步运行配合AsyncConfig与dataset.evaluate(task)import asyncio from deepeval.evaluate.configs import AsyncConfig from deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator( async_configAsyncConfig(run_asyncTrue), metrics[TaskCompletionMetric()], ): task asyncio.create_task(agent.run(golden.input)) dataset.evaluate(task)Google ADKimport asyncio from deepeval.evaluate.configs import AsyncConfig from deepeval.integrations.google_adk import instrument_google_adk from deepeval.metrics import TaskCompletionMetric instrument_google_adk() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator( async_configAsyncConfig(run_asyncTrue), metrics[TaskCompletionMetric()], ): task asyncio.create_task(run_agent(golden.input)) dataset.evaluate(task)Strandsfrom deepeval.integrations.strands import instrument_strands from deepeval.metrics import TaskCompletionMetric instrument_strands() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): agent(golden.input)5.4 支持的框架一览README 列出的框架集成及其接入方式框架接入方式LangChain / LangGraph回调处理器callback handlerPydantic AI类型安全校验CrewAI多 Agent 系统集成Anthropic / OpenAI客户端包装器client wrapperOpenAI Agents端到端一分钟接入AWS AgentCoreAgentCore 部署的 AgentGoogle ADKADK Agent 与多 Agent 工作流LlamaIndexLlamaIndex RAG 应用AI SDK / MastraTypeScript原生追踪tracer / exporter对应的 Python 侧测试位于 tests/test_integrations/TypeScript 侧位于 typescript/test/test-integrations/可用于验证各集成的 span 捕获行为。六、不依赖 Pytest 的评测evaluate()更适合 notebook 环境的写法README 原文示例from deepeval import evaluate from deepeval.metrics import AnswerRelevancyMetric from deepeval.test_case import LLMTestCase answer_relevancy_metric AnswerRelevancyMetric(threshold0.7) test_case LLMTestCase( inputWhat if these shoes dont fit?, # Replace this with the actual output from your LLM application actual_outputWe 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.] ) evaluate([test_case], [answer_relevancy_metric])从 evaluate.py 的函数签名看evaluate()还支持async_config/display_config/cache_config/error_config四组配置定义在 configs.py分别控制异步并发、终端展示含 HTML/Markdown 报告导出、结果缓存与错误处理identifier标记本次运行、hyperparameters记录超参供对比迭代、metric_collection推送云端指标集评估默认走异步执行run_asyncTrue执行结束后经global_test_run_manager.wrap_up_test_run()完成本地保存与云端上报。七、独立使用单个指标模块化设计DeepEval 高度模块化任何指标都可以脱离测试框架单独调用README 示例from deepeval.metrics import AnswerRelevancyMetric from deepeval.test_case import LLMTestCase answer_relevancy_metric AnswerRelevancyMetric(threshold0.7) test_case LLMTestCase( inputWhat if these shoes dont fit?, # Replace this with the actual output from your LLM application actual_outputWe 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.] ) answer_relevancy_metric.measure(test_case) print(answer_relevancy_metric.score) # All metrics also offer an explanation print(answer_relevancy_metric.reason)注意不同指标面向的场景不同有的面向 RAG 流水线有的面向微调选指标时应针对自己的用例。八、环境变量.env / .env.local 加载机制README 说明DeepEval 会在**导入时import time**自动从当前工作目录加载.env.local和.env优先级为 进程环境变量 →.env.local→.env设置DEEPEVAL_DISABLE_DOTENV1可关闭。推荐做法cp .env.example .env.local # then edit .env.local (ignored by git)源码层面settings.py 的dotenv_search_paths()与autoload_dotenv()给出了更完整的规则加载顺序低优先级 → 高优先级.env→.env.{APP_ENV}→.env.local后加载的文件覆盖先加载的同名键进程环境变量永远优先于任何文件值只写入os.environ中尚不存在的键支持APP_ENV选择环境专属文件如.env.staging支持ENV_DIR_PATH指定.env所在目录默认为当前工作目录DEEPEVAL_DISABLE_DOTENV1时完全跳过加载官方建议在 pytest/CI 环境中设置避免导入时意外读取本地 env 文件。入口位置在 deepeval/init.py——注释明确标注必须在其他 import 之前加载环境变量随后才暴露公共 API。九、DeepEval Confident AI结果同步与 MCP 持久层Confident AI 是配套的企业级 AI 评估与可观测平台与 DeepEval 原生集成且保持模型/框架无关。产品团队可在发布前评估 AI 应用、在生产中监控线上 traceonline evals平台团队可定义组织级质量标准通过治理与红队red teaming强制执行。使用方式CLI 登录后按正常流程运行测试结果自动同步到平台deepeval login deepeval test run test_chatbot.py对应源码行为登录后CONFIDENT_API_KEY在 settings.py 中定义为SecretStr类型字段被global_test_run_manager.wrap_up_test_run()用于上报本次运行--official选项则把某次运行标记为 Confident AI 上的官方基线。如果不想离开 IDE可以只用 Confident AI 作为持久层——通过其 MCP Server 从 Claude Code 或 Cursor 中运行评测、拉取数据集、查看 trace无需 UI。架构如下十、路线图、贡献与许可README 中的 Roadmap 状态截至本仓库快照与 Confident AI 集成G-EvalRAG 指标会话Conversational指标评测数据集创建红队Red-TeamingDAG 自定义指标Guardrails贡献流程见 CONTRIBUTING.mdDeepEval 采用 Apache 2.0 许可详见 LICENSE.md。十一、小结从单条断言到组织级评测标准回到源码可以勾勒出 DeepEval 的完整调用链deepeval test runcli/test/command.py包装 pytest 并注入-p deepeval插件 → 测试函数中assert_test/evaluateevaluate.py驱动BaseMetric.measure()计算 0–1 分并按 threshold 断言 → tracing 子系统tracing.py在observe与框架集成中采集有序 span →global_test_run_manager汇总本次运行、导出本地结果并可选上报 Confident AI。对开发者的实用建议先用assert_testGEval/AnswerRelevancyMetric建立端到端基线接入框架集成后用evals_iterator(metrics[TaskCompletionMetric()])做轨迹级评测用--use-cache、--num-processes、--repeat等 CLI 选项控制 CI 中的成本与稳定性需要跨团队共享报告时再登录 Confident AI。更深入的指标原理与 API 参考可浏览仓库的 docs/content/docs/ 文档目录。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepEval 实战指南：开源 LLM 评估框架的指标体系、评测流程与全链路溯源
DeepEval 实战指南开源 LLM 评估框架的指标体系、评测流程与全链路溯源【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepevalDeepEvalThe LLM Evaluation Framework是一个开源的大语言模型评估框架定位类似于 Pytest但专门用于 LLM 应用的单元测试。它通过 G-Eval、任务完成度、答案相关性、幻觉检测等数十种指标以 LLM-as-a-judge 和可本地运行的 NLP 模型对 LLM 系统进行量化打分。读完本文你将掌握 DeepEval 的指标体系与选型方法、deepeval test run的完整评测流程、evals_iterator()全链路溯源评测的接入方式以及evaluate()、独立指标、.env加载机制等进阶用法并了解其底层源码的实现依据。一、DeepEval 是什么三种粒度的评估对象官方定义DeepEval 是一个易用、开源的 LLM 评估框架借鉴最新研究通过G-Eval、task completion、answer relevancy、hallucination等指标运行评测这些指标使用 LLM-as-a-judge 以及在你本机运行的其他 NLP 模型。无论你用 LangChain 还是 OpenAI 构建 AI Agent、RAG 流水线或聊天机器人DeepEval 都支持三种评估粒度见 README.md端到端End-to-End把 LLM 应用当黑盒整体评估完整 Agent 轨迹Complete Agent Trajectories覆盖 Agent 每一次决策与动作的完整路径单个 Agent 步骤Individual Agent StepsLLM 调用、工具使用、检索、子 Agent 交接等组件级评估。这类评测可用于选出最优的模型与提示词架构、防止提示词漂移prompt drifting、以及例如从 OpenAI 切换到 Claude 时验证质量是否回退。二、指标体系开箱即用的 LLM 评测指标DeepEval 的指标库位于 deepeval/metrics/ 目录从目录结构看每个指标家族如answer_relevancy/、faithfulness/、g_eval/、task_completion/都包含独立的实现与评分模板文件。所有指标支持由你选择的任意 LLM、统计方法或本地 NLP 模型驱动。2.1 通用自定义指标指标说明G-Eval有研究背书的 LLM-as-a-judge 通用指标可按任意自定义标准评估接近人类判断精度实现见 g_eval.pyDAGDeepEval 基于图的确定性 LLM-as-a-judge 指标构建器实现见 dag/2.2 Agentic 指标指标说明Task Completion评估 Agent 是否达成目标Tool Correctness检查是否以正确参数调用了正确的工具Goal Accuracy衡量 Agent 达成预期目标的准确度Step Efficiency评估 Agent 是否存在不必要的步骤Plan Adherence检查 Agent 是否遵循了预期计划Plan Quality评估 Agent 计划本身的质量Tool Use衡量工具使用的质量Argument Correctness校验工具调用参数2.3 RAG 指标指标说明Answer Relevancy衡量 RAG 输出与输入的相关性Faithfulness评估 RAG 输出是否与检索上下文事实一致Contextual Recall衡量检索上下文与期望输出reference的对齐程度Contextual Precision评估相关检索节点是否排在更靠前位置Contextual Relevancy衡量检索上下文对输入的整体相关性RAGAS上述 answer relevancy、faithfulness、contextual precision、contextual recall 的均值实现见 ragas.py2.4 多轮对话Multi-Turn指标指标说明Knowledge Retention评估聊天机器人在整个会话中是否保持事实信息Conversation Completeness衡量聊天机器人是否在整个会话中满足用户需求Turn Relevancy评估每一轮回复是否持续相关Turn Faithfulness检查各轮回复是否有检索上下文的事实支撑Role Adherence评估聊天机器人是否全程遵守其角色设定2.5 MCP 指标指标说明MCP Task Completion评估基于 MCP 的 Agent 完成任务的有效性MCP Use衡量 Agent 使用可用 MCP Server 的有效性Multi-Turn MCP Use跨会话轮次评估 MCP Server 使用2.6 多模态指标指标说明Text to Image基于语义一致性与感知质量评估图像生成Image Editing基于语义一致性与感知质量评估图像编辑Image Coherence衡量图像与配文的一致性Image Helpfulness评估图像对用户理解文本的帮助程度Image Reference评估文本对图像的引用/描述准确性实现位于 multimodal_metrics/。2.7 其他指标指标说明Hallucination检查 LLM 相对于给定上下文是否生成事实正确的信息Summarization评估摘要是否事实正确且包含必要细节Bias检测 LLM 输出中的性别、种族或政治偏见Toxicity评估 LLM 输出的毒性JSON Correctness检查输出是否符合预期的 JSON SchemaPrompt Alignment衡量输出与提示词模板指令的对齐程度除指标库本身外README 还列出以下框架能力且都能从仓库源码中得到印证同时支持端到端与组件级评估deepeval/evaluate/可构建自定义指标并自动融入 DeepEval 生态基类 base_metric.py 与 plugins/生成单轮与多轮合成评测数据集synthesizer/无缝集成任意 CI/CD 环境deepeval test run会透传 pytest 退出码见 5.3 节基于评测结果自动优化提示词optimizer/含algorithms/、rewriter/、scorer/子模块不到 10 行代码在主流 LLM 基准上评测任意模型官方列出 MMLU、HellaSwag、DROP、BIG-Bench Hard、TruthfulQA、HumanEval、GSM8K从 deepeval/benchmarks/ 目录结构看还包含 ARC、BBQ、BoolQ、EquityMedQA、IFEval、LAMBADA、LogiQA、MathQA、SQuAD、WinoGrande 等任务。三、快速上手安装、登录与第一个端到端测试3.1 安装DeepEval 要求Python 3.9pip install -U deepeval3.2 创建账户强烈推荐登录 Confident AI 平台后可在云端生成可分享的测试报告免费且不需要额外代码deepeval login按 CLI 提示创建账户、复制 API Key 并粘贴进 CLI登录命令实现见 command.py。登录后所有测试用例会被自动记录。3.3 写第一个端到端测试创建测试文件touch test_chatbot.py假设你的 LLM 应用是一个基于 RAG 的客服聊天机器人test_chatbot.py内容如下来自 README.md 的 Human QuickStart仓库中 examples/tracing/test_chatbot.py 也有同类示例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( nameCorrectness, criteriaDetermine if the actual output is correct based on the expected output., evaluation_params[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT], threshold0.5 ) test_case LLMTestCase( inputWhat if these shoes dont fit?, # Replace this with the actual output from your LLM application actual_outputYou have 30 days to get a full refund at no extra cost., expected_outputWe 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])设置OPENAI_API_KEY环境变量也可以用自己的自定义模型作为评判 LLMexport OPENAI_API_KEY...在 CLI 中运行deepeval test run test_chatbot.py如果一切顺利测试用例应当通过。逐点拆解input模拟用户输入actual_output占位你的应用对该输入的实际输出expected_output表示该输入的理想答案GEval是有研究背书的自定义指标可按任意标准评估输出本例的criteria是基于expected_output判断actual_output是否正确所有指标分数都在 0–1 之间threshold0.5决定测试通过与否。3.4 测试用例数据结构源码视角LLMTestCase定义在 llm_test_case.py其核心字段为class LLMTestCase(BaseModel): input: str # 必填 actual_output: Optional[str] ... # 实际输出 expected_output: Optional[str] ... # 期望输出 retrieval_context: Optional[List[Union[str, RetrievedContextData]]] ...SingleTurnParams是声明式枚举llm_test_case.py列出指标可引用的全部字段INPUT、ACTUAL_OUTPUT、EXPECTED_OUTPUT、CONTEXT、RETRIEVAL_CONTEXT、METADATA、TAGS、TOOLS_CALLED、EXPECTED_TOOLS、MCP_SERVERS、MCP_TOOLS_CALLED、MCP_RESOURCES_CALLED、MCP_PROMPTS_CALLED。旧的LLMTestCaseParams名称已标记弃用源码中会对其发出DeprecationWarning。assert_test()的实现evaluate.py中有几个值得注意的机制调用check_at_least_one_metric_has_threshold至少一个指标必须设置 threshold才能断言任一指标失败时抛出AssertionError消息中包含每个失败指标的 name、score、threshold、strict 模式、error 与 reason若测试用例标记为flaky失败时只发出 warning 而不阻断 CIpytest 的 warnings summary 中可见。evaluate/assert_test等公共 API 在 deepeval/init.py 统一导出__all__中还包含login、compare、instrument、flush_traces等。四、deepeval test runCLI 参数详解deepeval test run本质上包装 pytest。其完整参数定义在 command.py可组合使用选项短选项作用--exit-on-first-failure-x首个用例失败即停止--show-warnings-w显示 warning默认禁用--identifier-id为该测试运行打标--num-processes-npytest 并发进程数--repeat-r每个用例重复运行次数--use-cache-c使用缓存的评测结果--ignore-errors-i忽略评测过程中的错误--skip-on-missing-params-s跳过缺少必需参数的用例--verbose-v打开详细模式--display-d结束时展示全部还是部分结果--mark-m按 pytest mark 筛选用例--official-o将该次运行标记为 Confident AI 上的官方基线需要CONFIDENT_API_KEY--pdb—失败时进入调试器--durations/--color—慢用例统计条数默认 10/ 彩色输出默认 yes两个对 CI 场景很重要的实现细节来自同一段源码额外参数透传Typer 配置了allow_extra_argsTrue因此deepeval test run test_chatbot.py -k smoke这类写法会把-k smoke直接透传给 pytest退出码透传源码在 pytest 返回非零码时显式sys.exit(int(pytest_retcode))使测试失败能正确在 CI 中暴露1失败2中断3内部错误4用法错误5未收集到用例。五、全链路溯源评测evals_iterator 与框架集成5.1 原理使用dataset.evals_iterator()实现见 dataset.py可把同一份数据集逐条跑过你的应用——无论是手动埋点还是通过 DeepEval 的框架集成。因为 tracing 捕获的是有顺序的模型决策、工具调用与中间步骤序列你可以对 Agent 走过的完整路径运行轨迹级trajectory-based评测。5.2 手动埋点示例from deepeval.tracing import observe, update_current_span from deepeval.test_case import LLMTestCase from deepeval.metrics import TaskCompletionMetric observe() def inner_component(input: str): output result update_current_span(test_caseLLMTestCase(inputinput, actual_outputoutput)) return output observe() def app(input: str): return inner_component(input) # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): app(golden.input)observe装饰器定义在 tracing.py支持将函数追踪为 spantype参数可指定agent、llm、retriever、tool或自定义类型并兼容同步、异步与异步生成器函数。5.3 框架集成示例DeepEval 的集成代码集中在 deepeval/integrations/ 与各 provider 包装模块中。以下是 README 给出的各框架接法均使用TaskCompletionMetric()评估本次运行捕获的完整轨迹OpenAI客户端包装 trace上下文管理器包装器位于 deepeval/openai/from deepeval.openai import OpenAI from deepeval.tracing import trace from deepeval.metrics import TaskCompletionMetric client OpenAI() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(): with trace(metrics[TaskCompletionMetric()]): client.chat.completions.create( modelgpt-4o, messages[{role: user, content: golden.input}], )OpenAI Agents仅需在集成 patch 生效后正常运行 Agentfrom agents import Runner from deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): Runner.run_sync(agent, golden.input)Anthropic客户端包装位于 deepeval/anthropic/from deepeval.anthropic import Anthropic from deepeval.tracing import trace from deepeval.metrics import TaskCompletionMetric client Anthropic() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(): with trace(metrics[TaskCompletionMetric()]): client.messages.create( modelclaude-sonnet-4-5, max_tokens1024, messages[{role: user, content: golden.input}], )LangChain回调处理器from deepeval.integrations.langchain import CallbackHandler from deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(): llm.invoke( golden.input, config{callbacks: [CallbackHandler(metrics[TaskCompletionMetric()])]}, )LangGraph同样走 LangChain 回调处理器但作用于 agent 状态from deepeval.integrations.langchain import CallbackHandler from deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(): agent.invoke( {messages: [{role: user, content: golden.input}]}, config{callbacks: [CallbackHandler(metrics[TaskCompletionMetric()])]}, )Pydantic AIfrom deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): agent.run_sync(golden.input)CrewAIfrom deepeval.integrations.crewai import instrument_crewai from deepeval.metrics import TaskCompletionMetric instrument_crewai() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): crew.kickoff({input: golden.input})AI SDKTypeScriptimport { generateText } from ai; import { configureAiSdkTracing } from deepeval/integrations/ai-sdk; import { TaskCompletionMetric } from deepeval/metrics; const tracer configureAiSdkTracing({ name: my-agent }); const ask (input: string) generateText({ model, prompt: input, experimental_telemetry: { isEnabled: true, tracer }, }); // This metric evaluates the complete trajectory captured for this run. for await (const golden of dataset.evalsIterator({ metrics: [new TaskCompletionMetric()], })) { await ask(golden.input); }MastraTypeScriptimport { Mastra } from mastra/core/mastra; import { Observability } from mastra/observability; import { DeepEvalExporter } from deepeval/integrations/mastra; import { TaskCompletionMetric } from deepeval/metrics; const mastra new Mastra({ agents: { agent }, observability: new Observability({ configs: { deepeval: { exporters: [new DeepEvalExporter()] }, }, }), }); // This metric evaluates the complete trajectory captured for this run. for await (const golden of dataset.evalsIterator({ metrics: [new TaskCompletionMetric()], })) { await mastra.getAgent(agent).generate(golden.input); }AWS AgentCorefrom deepeval.integrations.agentcore import instrument_agentcore from deepeval.metrics import TaskCompletionMetric instrument_agentcore() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): invoke({prompt: golden.input})LlamaIndex异步运行配合AsyncConfig与dataset.evaluate(task)import asyncio from deepeval.evaluate.configs import AsyncConfig from deepeval.metrics import TaskCompletionMetric # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator( async_configAsyncConfig(run_asyncTrue), metrics[TaskCompletionMetric()], ): task asyncio.create_task(agent.run(golden.input)) dataset.evaluate(task)Google ADKimport asyncio from deepeval.evaluate.configs import AsyncConfig from deepeval.integrations.google_adk import instrument_google_adk from deepeval.metrics import TaskCompletionMetric instrument_google_adk() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator( async_configAsyncConfig(run_asyncTrue), metrics[TaskCompletionMetric()], ): task asyncio.create_task(run_agent(golden.input)) dataset.evaluate(task)Strandsfrom deepeval.integrations.strands import instrument_strands from deepeval.metrics import TaskCompletionMetric instrument_strands() # This metric evaluates the complete trajectory captured for this run. for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): agent(golden.input)5.4 支持的框架一览README 列出的框架集成及其接入方式框架接入方式LangChain / LangGraph回调处理器callback handlerPydantic AI类型安全校验CrewAI多 Agent 系统集成Anthropic / OpenAI客户端包装器client wrapperOpenAI Agents端到端一分钟接入AWS AgentCoreAgentCore 部署的 AgentGoogle ADKADK Agent 与多 Agent 工作流LlamaIndexLlamaIndex RAG 应用AI SDK / MastraTypeScript原生追踪tracer / exporter对应的 Python 侧测试位于 tests/test_integrations/TypeScript 侧位于 typescript/test/test-integrations/可用于验证各集成的 span 捕获行为。六、不依赖 Pytest 的评测evaluate()更适合 notebook 环境的写法README 原文示例from deepeval import evaluate from deepeval.metrics import AnswerRelevancyMetric from deepeval.test_case import LLMTestCase answer_relevancy_metric AnswerRelevancyMetric(threshold0.7) test_case LLMTestCase( inputWhat if these shoes dont fit?, # Replace this with the actual output from your LLM application actual_outputWe 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.] ) evaluate([test_case], [answer_relevancy_metric])从 evaluate.py 的函数签名看evaluate()还支持async_config/display_config/cache_config/error_config四组配置定义在 configs.py分别控制异步并发、终端展示含 HTML/Markdown 报告导出、结果缓存与错误处理identifier标记本次运行、hyperparameters记录超参供对比迭代、metric_collection推送云端指标集评估默认走异步执行run_asyncTrue执行结束后经global_test_run_manager.wrap_up_test_run()完成本地保存与云端上报。七、独立使用单个指标模块化设计DeepEval 高度模块化任何指标都可以脱离测试框架单独调用README 示例from deepeval.metrics import AnswerRelevancyMetric from deepeval.test_case import LLMTestCase answer_relevancy_metric AnswerRelevancyMetric(threshold0.7) test_case LLMTestCase( inputWhat if these shoes dont fit?, # Replace this with the actual output from your LLM application actual_outputWe 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.] ) answer_relevancy_metric.measure(test_case) print(answer_relevancy_metric.score) # All metrics also offer an explanation print(answer_relevancy_metric.reason)注意不同指标面向的场景不同有的面向 RAG 流水线有的面向微调选指标时应针对自己的用例。八、环境变量.env / .env.local 加载机制README 说明DeepEval 会在**导入时import time**自动从当前工作目录加载.env.local和.env优先级为 进程环境变量 →.env.local→.env设置DEEPEVAL_DISABLE_DOTENV1可关闭。推荐做法cp .env.example .env.local # then edit .env.local (ignored by git)源码层面settings.py 的dotenv_search_paths()与autoload_dotenv()给出了更完整的规则加载顺序低优先级 → 高优先级.env→.env.{APP_ENV}→.env.local后加载的文件覆盖先加载的同名键进程环境变量永远优先于任何文件值只写入os.environ中尚不存在的键支持APP_ENV选择环境专属文件如.env.staging支持ENV_DIR_PATH指定.env所在目录默认为当前工作目录DEEPEVAL_DISABLE_DOTENV1时完全跳过加载官方建议在 pytest/CI 环境中设置避免导入时意外读取本地 env 文件。入口位置在 deepeval/init.py——注释明确标注必须在其他 import 之前加载环境变量随后才暴露公共 API。九、DeepEval Confident AI结果同步与 MCP 持久层Confident AI 是配套的企业级 AI 评估与可观测平台与 DeepEval 原生集成且保持模型/框架无关。产品团队可在发布前评估 AI 应用、在生产中监控线上 traceonline evals平台团队可定义组织级质量标准通过治理与红队red teaming强制执行。使用方式CLI 登录后按正常流程运行测试结果自动同步到平台deepeval login deepeval test run test_chatbot.py对应源码行为登录后CONFIDENT_API_KEY在 settings.py 中定义为SecretStr类型字段被global_test_run_manager.wrap_up_test_run()用于上报本次运行--official选项则把某次运行标记为 Confident AI 上的官方基线。如果不想离开 IDE可以只用 Confident AI 作为持久层——通过其 MCP Server 从 Claude Code 或 Cursor 中运行评测、拉取数据集、查看 trace无需 UI。架构如下十、路线图、贡献与许可README 中的 Roadmap 状态截至本仓库快照与 Confident AI 集成G-EvalRAG 指标会话Conversational指标评测数据集创建红队Red-TeamingDAG 自定义指标Guardrails贡献流程见 CONTRIBUTING.mdDeepEval 采用 Apache 2.0 许可详见 LICENSE.md。十一、小结从单条断言到组织级评测标准回到源码可以勾勒出 DeepEval 的完整调用链deepeval test runcli/test/command.py包装 pytest 并注入-p deepeval插件 → 测试函数中assert_test/evaluateevaluate.py驱动BaseMetric.measure()计算 0–1 分并按 threshold 断言 → tracing 子系统tracing.py在observe与框架集成中采集有序 span →global_test_run_manager汇总本次运行、导出本地结果并可选上报 Confident AI。对开发者的实用建议先用assert_testGEval/AnswerRelevancyMetric建立端到端基线接入框架集成后用evals_iterator(metrics[TaskCompletionMetric()])做轨迹级评测用--use-cache、--num-processes、--repeat等 CLI 选项控制 CI 中的成本与稳定性需要跨团队共享报告时再登录 Confident AI。更深入的指标原理与 API 参考可浏览仓库的 docs/content/docs/ 文档目录。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
