2. 快速入门第一个评估文档基于 DeepEval v4.1.0 编写来源https://deepeval.com/docs/getting-started文章目录2. 快速入门第一个评估2.1. 核心概念速览2.2. 最小可运行示例2.2.1. Answer Relevancy —— 15 行代码跑通2.2.2. 运行结果解读2.2.3. 参数详解AnswerRelevancyMetricLLMTestCase1. input必填2. actual_output必填3. expected_output可选4. context可选5. retrieval_context可选6. turns可选7. metadata可选8. name可选2.3. 三种使用模式2.3.1. 单独 .measure() —— 调试模式2.3.2. evaluate() 批量模式 —— 脚本模式2.3.3. pytest 集成模式 —— CI/CD 模式2.4. 关键配置项2.4.1. 指定评估用 LLM2.4.2. 缓存机制2.5. 小结2.1. 核心概念速览在开始写代码之前先理解三个核心概念组件一句话解释类比LLMTestCase封装一次 LLM 交互的输入和输出测试用例 输入 输出 期望Metric评分规则输出 0~1 的分数评分标准 规则 阈值evaluate()/assert_test()执行评估的入口测试运行器2.2. 最小可运行示例2.2.1. Answer Relevancy —— 15 行代码跑通# 来源: https://deepeval.com/docs/metrics-answer-relevancy# 导入评估所需模块fromdeepevalimportevaluatefromdeepeval.metricsimportAnswerRelevancyMetricfromdeepeval.test_caseimportLLMTestCase# 创建评估指标设定阈值为 0.7分数 0.7 才算通过metricAnswerRelevancyMetric(threshold0.7,modelgpt-4.1,# 评估用的 LLM可替换为 DeepSeekinclude_reasonTrue# 输出评分原因)# 创建测试用例test_caseLLMTestCase(input如果鞋子不合脚怎么办,# 用户输入actual_output我们提供 30 天全额退款无需额外费用。# LLM 实际输出)# 运行评估evaluate(test_cases[test_case],metrics[metric])如果使用本地的模型来跑测试fromdeepevalimportevaluatefromdeepeval.metricsimportAnswerRelevancyMetricfromdeepeval.modelsimportOllamaModelfromdeepeval.test_caseimportLLMTestCasefromsrc.utils.configimportConfig llmOllamaModel(modelqwen3:0.6b)# 创建评估指标设定阈值为 0.7分数 0.7 才算通过metricAnswerRelevancyMetric(threshold0.7,modelllm,# 评估用的 LLM可替换为 DeepSeekinclude_reasonTrue# 输出评分原因)# 创建测试用例test_caseLLMTestCase(input如果鞋子不合脚怎么办,# 用户输入actual_output我们提供 30 天全额退款无需额外费用。# LLM 实际输出)resultevaluate(test_cases[test_case],metrics[metric])print(result)2.2.2. 运行结果解读# 运行上面代码后终端输出类似 ✨ Youre running DeepEvals latest Answer Relevancy Metric! (using qwen3:0.6b (Ollama), strictFalse, async_modeTrue)... ╭──────────────────────────────────────────────────────────────────────────────╮ │ DeepEval Evaluation Results │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────────────────────────────────────────╮ │ ✅ test_case_0 (Passed 1 metrics) │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────────────────────────────────────────╮ │ Aggregate Metrics │ │ │ │ Metric ┃ Average Score ┃ Pass Rate ┃ Total │ │ ━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━ │ │ Answer Relevancy │ 1.00 │ 100.00% │ 1 │ ╰──────────────────────────────────────────────────────────────────────────────╯ ⚠ WARNING: No hyperparameters logged. » Log hyperparameters to attribute prompts and models to your test runs. ✓ Evaluation completed ! (time taken: 17.28s | token cost: None) » Test Results (1 total tests): » Pass Rate: 100.0% | Passed: 1 | Failed: 0 » Want to share evals with your team, or a place for your test cases to live? ❤️ » Run deepeval view to analyze and save testing results on Confident AI. test_results[TestResult(nametest_case_0, successTrue, metrics_data[MetricData(nameAnswer Relevancy, threshold0.7, successTrue, score1.0, reasonThe score is 1.00 because there are no irrelevant statements in the output. The response directly addresses the question without unnecessary information., strict_modeFalse, evaluation_modelqwen3:0.6b (Ollama), errorNone, evaluation_cost0.0, input_tokens0, output_tokens0, verbose_logsStatements:\n[\n We offer a 30-day full refund without additional fees.\n] \n \nVerdicts:\n[\n {\n verdict: yes,\n reason: relevant\n },\n {\n verdict: yes,\n reason: relevant\n },\n {\n verdict: yes,\n reason: relevant\n }\n])], conversationalFalse, index0, multimodalFalse, input如果鞋子不合脚怎么办, actual_output我们提供 30 天全额退款无需额外费用。, expected_outputNone, contextNone, retrieval_contextNone, turnsNone, metadataNone)] confident_linkNone test_run_idNone 进程已结束退出代码为 0# 也可以通过 metric.score 和 metric.reason 获取结果{score:0.92,success:true,reason:The actual output is highly relevant to the input...,metric_name:Answer Relevancy}以下是对您提供的 DeepEval 评估输出结果的详细解析评估任务概览• 评估类型Answer Relevancy Metric答案相关性指标用于衡量模型输出是否紧扣输入问题、是否存在无关信息。• 评判模型qwen3:0.6b (Ollama) —— 即本地通过 Ollama 运行的千问3-0.6B 小模型负责给被测答案打分。• 运行参数strictFalse非严格模式async_modeTrue异步执行。• 总耗时17.28 秒Token 成本None因为是本地模型无 API 费用。测试用例test_case_0明细• 输入input如果鞋子不合脚怎么办• 实际输出actual_output我们提供 30 天全额退款无需额外费用。• 期望输出expected_output未设置None。• 上下文/检索上下文均未提供。这个用例模拟了一个电商客服场景用户询问鞋子尺码不符的处理方式模型给出了退款政策。答案相关性指标结果•指标名Answer Relevancy• 阈值threshold0.7≥0.7 视为通过• 实测得分score1.00满分• 是否通过success✅ True• 评判理由reason 这个比较重要 后续我们细说 测评的标准是什么The score is 1.00 because there are no irrelevant statements in the output. The response directly addresses the question without unnecessary information.翻译成中文得分为 1.00因为输出中没有无关陈述回复直接针对问题且不含多余信息。• 详细日志verbose_logs内部拆解• Statements评判模型将输出拆解为句子这里意外地显示成了英文[“We offer a 30-day fullrefund without additional fees.”]可能是 Ollama 模型内部做了翻译或 DeepEval 的预处理。• Verdicts对该语句给出了 3 次判定可能是重复采样或拆分全部为 {“verdict”: “yes”,“reason”: “relevant”}即全部判定为“相关”。因此加权平均后得到完美分数 1.0。整体聚合统计Aggregate MetricsMetric Average Score Pass Rate TotalAnswer Relevancy 1.00 100.00% 1• 本次共执行 1 个测试test_case_0通过 1 个失败 0 个总通过率 100%。最终结果对象test_results程序退出时返回了一个 TestResult 对象其关键字段对应上面内容TestResult(nametest_case_0,successTrue,metrics_data[MetricData(nameAnswer Relevancy,threshold0.7,successTrue,score1.0,reason...,strict_modeFalse,evaluation_modelqwen3:0.6b (Ollama),evaluation_cost0.0,...)],input如果鞋子不合脚怎么办,actual_output我们提供 30 天全额退款无需额外费用。,...)进程退出代码为 0表示正常结束无错误。2.2.3. 参数详解AnswerRelevancyMetric参数名类型你的取值作用说明evaluation_model(或model)str / BaseLMqwen3:0.6b (Ollama)评委模型。负责把答案拆成陈述并打分。这里用了本地 Ollama 拉的千问3-0.6B因此evaluation_cost0无 API 费用。thresholdfloat0.7通过阈值。分数 ≥ 0.7 时successTrue。你的得分 1.0远高于线。strict_mode(或strict)boolFalse严格模式。关闭时允许一定容错比如部分陈述不相关但整体仍可能高分开启时通常要求全部陈述都必须相关才能拿满分。async_modeboolTrue异步执行。测评并发调用评委模型加快速度你总耗时 17.28s 是包含模型加载/调用的。verbosebool隐含True是否输出verbose_logs陈述拆分、verdicts 明细。你的日志里打印了 Statements / Verdicts说明构建了该开关。include_reasonbool隐含True是否在结果里生成自然语言reason你看到了“The score is 1.00 because…”。AnswerRelevancyMetric 的 threshold 通过红线threshold 值含义适用场景0.0永不通过所有用例都失败无实际用途0.5默认及格线分数 0.5 通过开发调试阶段0.7推荐值要求较高生产环境0.9严格要求接近满分才通过安全敏感场景1.0必须满分确定性输出场景注意threshold设置为 0 表示永不通过设置为 1 表示必须满分才通过。生产环境建议从 0.7 开始根据实际场景调整。AnswerRelevancyMetric 的 model 模型 评委模型评委模型 评委模型。负责把答案拆成陈述并打分。这里用了本地 Ollama 拉的千问3-0.6B因此 evaluation_cost0无API 费用。AnswerRelevancyMetric 的 include_reason是否在结果里生成自然语言 reason你看到了 “The score is 1.00 because…”。LLMTestCase参数名类型必填你的示例值inputstr✅如果鞋子不合脚怎么办actual_outputstr✅我们提供 30 天全额退款无需额外费用。expected_outputstr❌NonecontextList[str]❌Noneretrieval_contextList[str]❌NoneturnsList[Dict]❌None每个参数的深入解读1.input必填含义模拟用户向系统提出的问题或指令。在案例如果鞋子不合脚怎么办评估中的作用AnswerRelevancyMetric用它来判定actual_output是否真的在回答这个问题。没有input评委模型就不知道“该相关到什么”。2.actual_output必填含义你的业务模型 / 待评测 LLM 给出的真实回复。在你的案例我们提供 30 天全额退款无需额外费用。评估中的作用被切成若干“陈述句”statements由评委模型逐条打 verdict。是你刚才拿到1.0 分的直接载体。3.expected_output可选含义理想情况下模型应该给出的答案。在你的案例None未提供。评估中的作用当使用答案正确性Correctness、BLEU、Rouge等指标时必需。AnswerRelevancyMetric不需要它因为它只关心“有没有答非所问”不关心“是否正确”。4.context可选含义一组字符串代表模型生成答案时被允许参考的上下文例如产品手册、知识库段落。在你的案例None。评估中的作用用于FaithfulnessMetric忠实度检查actual_output是否编造了context之外的信息。用于ContextualRelevancyMetric上下文相关性检查context是否真的和input有关。对纯答案相关性而言它是非必需的。5.retrieval_context可选含义RAG 系统中检索器从向量库拉回来的候选文档块。在的案例None。评估中的作用支撑ContextualPrecisionMetric、ContextualRecallMetric等 RAG 专用指标。与context的区别context常指“最终喂给生成模型的上下文”retrieval_context是“检索初始结果”。6.turns可选含义多轮对话列表一般格式[{user:你好,assistant:您好有什么可以帮您},{user:如果鞋子不合脚怎么办,assistant:...}]在案例None且conversationalFalse。评估中的作用当测试对话系统时需要单轮 QA 留空即可。7.metadata可选含义任意字典记录实验标签。metadata{scene:refund_policy,model_version:v2.3}在案例None。评估中的作用不影响打分但能在deepeval view或导出报告时做筛选分组。8.name可选含义测试用例名字。在案例未显式传入DeepEval 自动赋为test_case_0。建议自己指定可读性高的名称如namerefund_shoe_fitting。evaluate 是 DeepEval 的统一调度入口。它的职责是 接收一批 LLMTestCase待测数据 接收一批BaseMetric 子类实例如 AnswerRelevancyMetric 对每个用例 × 每个指标执行评分可异步 汇总成TestResult / 聚合表格 可选打印报告、存本地文件、传 Confident AI 之前看到的这张表就是 evaluate画出来的╭──────────────────────────────────────────────────────────────────────────────╮ │AggregateMetrics│ │ │ │Metric┃AverageScore┃PassRate┃Total│ │ ━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━ │ │AnswerRelevancy│1.00│100.00%│1│ ╰──────────────────────────────────────────────────────────────────────────────╯核心参数总览按重要性参数名类型必填你的隐式取值作用test_casesList[LLMTestCase]/LLMTestCase✅[test_case_0]待测用例集合metricsList[BaseMetric]/BaseMetric✅[answer_relevancy]要跑的评估指标async_modebool❌True是否并发评分你日志里标了async_modeTrueverbosebool❌True是否打印详细过程与表格evaluation_modelstr/BaseLM❌未设指标内已指定全局评委模型指标缺省时兜底hyperparametersdict❌None→ 触发警告记录 prompt / 模型超参run_namestr❌未给Confident AI 上的运行名confident_api_keystr❌未给上传云端用的密钥output_pathstr❌未给结果 JSON / CSV 落盘路径ignore_errorsbool❌False默认单指标报错是否跳过skip_on_failurebool❌False默认前一指标失败是否停后续2.3. 三种使用模式2.3.1. 单独.measure()—— 调试模式适用于单个用例调试、快速验证。# 来源: https://deepeval.com/docs/metrics-answer-relevancy#as-a-standalonefromdeepeval.metricsimportAnswerRelevancyMetricfromdeepeval.test_caseimportLLMTestCase# 创建测试用例test_caseLLMTestCase(input什么是机器学习,actual_output机器学习是人工智能的一个子领域使计算机能够从数据中学习和改进。)# 创建指标并单独执行metricAnswerRelevancyMetric(threshold0.7)metric.measure(test_case)# 查看结果print(f分数:{metric.score})print(f通过:{metric.success})print(f原因:{metric.reason})# 运行上面代码后输出类似 分数: 0.85 通过: True 原因: 答案与问题高度相关准确解释了机器学习的定义。2.3.2.evaluate()批量模式 —— 脚本模式适用于批量评估多个用例。# 来源: https://deepeval.com/docs/metrics-introductionfromdeepevalimportevaluatefromdeepeval.metricsimportAnswerRelevancyMetric,FaithfulnessMetricfromdeepeval.test_caseimportLLMTestCase# 创建多个测试用例test_cases[LLMTestCase(input退货政策是什么,actual_output我们提供 30 天全额退款。,retrieval_context[所有客户享有 30 天全额退款保障。]),LLMTestCase(input如何联系客服,actual_output您可以通过邮件 supportexample.com 联系我们。,retrieval_context[客服邮箱: supportexample.com]),LLMTestCase(input产品支持哪些语言,actual_output我们支持中文和英文。,retrieval_context[支持中文、英文、日文共三种语言]),]# 同时运行两个指标metrics[AnswerRelevancyMetric(threshold0.7),FaithfulnessMetric(threshold0.7),]# 批量评估resultsevaluate(test_casestest_cases,metricsmetrics)print(f\n全部通过:{all(r.successforrinresults)})# 运行上面代码后输出类似Evaluating3testcase(s)with2metric(s)...Test Case1(退货政策是什么):Answer Relevancy:0.95✅ Faithfulness:0.88✅ Test Case2(如何联系客服):Answer Relevancy:0.90✅ Faithfulness:0.92✅ Test Case3(产品支持哪些语言):Answer Relevancy:0.78✅ Faithfulness:0.45❌ Summary:Passed:5/6(83.3%)Failed:1/6(16.7%)2.3.3. pytest 集成模式 —— CI/CD 模式适用于持续集成流水线。# 来源: https://deepeval.com/docs/getting-started#create-your-first-test-run# 文件名: test_chatbot.pyimportpytestfromdeepevalimportassert_testfromdeepeval.metricsimportGEvalfromdeepeval.test_caseimportLLMTestCase,SingleTurnParamsdeftest_correctness():# 定义评估指标判断实际输出是否正确correctness_metricGEval(nameCorrectness,criteriaDetermine if the actual output is correct based on the expected output.,evaluation_params[SingleTurnParams.ACTUAL_OUTPUT,SingleTurnParams.EXPECTED_OUTPUT],threshold0.5)# 创建测试用例test_caseLLMTestCase(input我持续咳嗽发烧需要担心吗,# 替换为你的 LLM 应用的实际输出actual_output持续咳嗽和发烧可能是病毒感染如症状加重建议就医。,expected_output持续咳嗽和发烧可能从轻微病毒感染到肺炎等严重疾病如症状持续或伴随呼吸困难应就医。)# 断言测试通过assert_test(test_case,[correctness_metric])# 运行 pytest 测试deepeval test run test_chatbot.py text text# 运行上面命令后输出类似test session startscollected1item test_chatbot.py.[100%]1passedin2.34s方式适用场景代码量是否可 CI/CD单独.measure()单个用例调试少否evaluate()批量脚本/Notebook 批量评估中可需自行封装pytest 集成CI/CD 流水线多是2.4. 关键配置项2.4.1. 指定评估用 LLM# 来源: https://deepeval.com/docs/metrics-introductionfromdeepeval.metricsimportAnswerRelevancyMetric# 方式一使用 OpenAI 的不同模型metricAnswerRelevancyMetric(modelgpt-4.1)# 方式二使用 gpt-4ometricAnswerRelevancyMetric(modelgpt-4o)# 方式三使用自定义模型如 DeepSeekfrommy_modelsimportDeepSeekModel deepseekDeepSeekModel()metricAnswerRelevancyMetric(modeldeepseek)2.4.2. 缓存机制DeepEval 默认启用缓存相同参数的评估不会重复调用 LLM节省成本和时间。# 来源: https://deepeval.com/docs/metrics-introduction# 缓存默认开启无需额外配置# 如需关闭缓存importos os.environ[DEEPEVAL_CACHE_ENABLED]NO2.5. 小结最小可运行LLMTestCaseMetricevaluate() 15 行代码即可完成一次评估三种模式.measure()用于调试evaluate()用于批量assert_test()deepeval test run用于 CI/CD关键参数threshold控制通过标准model指定评估 LLMinclude_reason输出评分理由推荐配置开发环境 threshold0.5生产环境 threshold0.7国内用 DeepSeek 替代 OpenAI