2. 快速入门：第一个评估

文档基于 DeepEval v4.1.0 编写
来源：https://deepeval.com/docs/getting-started

2.1. 核心概念速览

在开始写代码之前，先理解三个核心概念：

2.2. 最小可运行示例

2.2.1. Answer Relevancy —— 15 行代码跑通

# 来源: https://deepeval.com/docs/metrics-answer-relevancy# 导入评估所需模块fromdeepevalimportevaluatefromdeepeval.metricsimportAnswerRelevancyMetricfromdeepeval.test_caseimportLLMTestCase# 创建评估指标：设定阈值为 0.7（分数 >= 0.7 才算通过）metric=AnswerRelevancyMetric(threshold=0.7,model="gpt-4.1",# 评估用的 LLM，可替换为 DeepSeekinclude_reason=True# 输出评分原因)# 创建测试用例test_case=LLMTestCase(input="如果鞋子不合脚怎么办？",# 用户输入actual_output="我们提供 30 天全额退款，无需额外费用。"# LLM 实际输出)# 运行评估evaluate(test_cases=[test_case],metrics=[metric])

如果使用本地的模型来跑测试

fromdeepevalimportevaluatefromdeepeval.metricsimportAnswerRelevancyMetricfromdeepeval.modelsimportOllamaModelfromdeepeval.test_caseimportLLMTestCasefromsrc.utils.configimportConfig llm=OllamaModel(model="qwen3:0.6b")# 创建评估指标：设定阈值为 0.7（分数 >= 0.7 才算通过）metric=AnswerRelevancyMetric(threshold=0.7,model=llm,# 评估用的 LLM，可替换为 DeepSeekinclude_reason=True# 输出评分原因)# 创建测试用例test_case=LLMTestCase(input="如果鞋子不合脚怎么办？",# 用户输入actual_output="我们提供 30 天全额退款，无需额外费用。"# LLM 实际输出)result=evaluate(test_cases=[test_case],metrics=[metric])print(result)

2.2.2. 运行结果解读

# 运行上面代码后，终端输出类似： ✨ You're running DeepEval's latest Answer Relevancy Metric! (using qwen3:0.6b (Ollama), strict=False, async_mode=True)... ╭──────────────────────────────────────────────────────────────────────────────╮ │ 🚀 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(name='test_case_0', success=True, metrics_data=[MetricData(name='Answer Relevancy', threshold=0.7, success=True, score=1.0, reason='The score is 1.00 because there are no irrelevant statements in the output. The response directly addresses the question without unnecessary information.', strict_mode=False, evaluation_model='qwen3:0.6b (Ollama)', error=None, evaluation_cost=0.0, input_tokens=0, output_tokens=0, verbose_logs='Statements:\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]')], conversational=False, index=0, multimodal=False, input='如果鞋子不合脚怎么办？', actual_output='我们提供 30 天全额退款，无需额外费用。', expected_output=None, context=None, retrieval_context=None, turns=None, metadata=None)] confident_link=None test_run_id=None 进程已结束，退出代码为 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 评估输出结果的详细解析：

1. 评估任务概览

• 评估类型：Answer Relevancy Metric（答案相关性指标），用于衡量模型输出是否紧扣输入问题、是否存在无关信息。

• 评判模型：qwen3:0.6b (Ollama) —— 即本地通过 Ollama 运行的千问3-0.6B 小模型，负责给被测答案打分。

• 运行参数：strict=False（非严格模式），async_mode=True（异步执行）。

• 总耗时：17.28 秒，Token 成本：None（因为是本地模型，无 API 费用）。

2. 测试用例（test_case_0）明细

• 输入（input）：如果鞋子不合脚怎么办？

• 实际输出（actual_output）：我们提供 30 天全额退款，无需额外费用。

• 期望输出（expected_output）：未设置（None）。

• 上下文/检索上下文：均未提供。

这个用例模拟了一个电商客服场景：用户询问鞋子尺码不符的处理方式，模型给出了退款政策。

3. 答案相关性指标结果

•指标名：Answer Relevancy

• 阈值（threshold）：0.7（≥0.7 视为通过）

• 实测得分（score）：1.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 full
refund without additional fees.”]，可能是 Ollama 模型内部做了翻译或 DeepEval 的预处理）。

• Verdicts：对该语句给出了 3 次判定（可能是重复采样或拆分），全部为 {“verdict”: “yes”,
“reason”: “relevant”}，即全部判定为“相关”

。

因此加权平均后得到完美分数 1.0。

4. 整体聚合统计（Aggregate Metrics）

Metric Average Score Pass Rate Total

Answer Relevancy 1.00 100.00% 1

• 本次共执行 1 个测试（test_case_0），通过 1 个，失败 0 个，总通过率 100%。

5. 最终结果对象（test_results）

程序退出时返回了一个 TestResult 对象，其关键字段对应上面内容：

TestResult(name='test_case_0',success=True,metrics_data=[MetricData(name='Answer Relevancy',threshold=0.7,success=True,score=1.0,reason='...',strict_mode=False,evaluation_model='qwen3:0.6b (Ollama)',evaluation_cost=0.0,...)],input='如果鞋子不合脚怎么办？',actual_output='我们提供 30 天全额退款，无需额外费用。',...)

进程退出代码为 0，表示正常结束，无错误。

2.2.3. 参数详解

AnswerRelevancyMetric

• AnswerRelevancyMetric 的 threshold 通过红线

注意：threshold设置为 0 表示永不通过，设置为 1 表示必须满分才通过。生产环境建议从 0.7 开始，根据实际场景调整。

• AnswerRelevancyMetric 的 model 模型 评委模型

评委模型 评委模型。负责把答案拆成陈述并打分。这里用了本地 Ollama 拉的千问3-0.6B，因此 evaluation_cost=0（无
API 费用）。

• AnswerRelevancyMetric 的 include_reason

是否在结果里生成自然语言 reason（你看到了 “The score is 1.00 because…”）。

LLMTestCase

每个参数的深入解读

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，且conversational=False。

• 评估中的作用：

  • 当测试对话系统时需要；单轮 QA 留空即可。

7.metadata（可选）

• 含义：任意字典，记录实验标签。

  metadata={"scene":"refund_policy","model_version":"v2.3"}

• 在案例：None。

• 评估中的作用：

  • 不影响打分，但能在deepeval view或导出报告时做筛选分组。

8.name（可选）

• 含义：测试用例名字。

• 在案例：未显式传入，DeepEval 自动赋为test_case_0。

• 建议：自己指定可读性高的名称，如name="refund_shoe_fitting"。

evaluate 是 DeepEval 的统一调度入口。它的职责是： 接收一批 LLMTestCase（待测数据） 接收一批
BaseMetric 子类实例（如 AnswerRelevancyMetric） 对每个用例 × 每个指标执行评分（可异步） 汇总成
TestResult / 聚合表格 可选：打印报告、存本地文件、传 Confident AI 之前看到的这张表，就是 evaluate
画出来的：

╭──────────────────────────────────────────────────────────────────────────────╮ │AggregateMetrics│ │ │ │Metric┃AverageScore┃PassRate┃Total│ │ ━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━ │ │AnswerRelevancy│1.00│100.00%│1│ ╰──────────────────────────────────────────────────────────────────────────────╯

核心参数总览（按重要性）

2.3. 三种使用模式

2.3.1. 单独.measure()—— 调试模式

适用于单个用例调试、快速验证。

# 来源: https://deepeval.com/docs/metrics-answer-relevancy#as-a-standalonefromdeepeval.metricsimportAnswerRelevancyMetricfromdeepeval.test_caseimportLLMTestCase# 创建测试用例test_case=LLMTestCase(input="什么是机器学习？",actual_output="机器学习是人工智能的一个子领域，使计算机能够从数据中学习和改进。")# 创建指标并单独执行metric=AnswerRelevancyMetric(threshold=0.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="您可以通过邮件 support@example.com 联系我们。",retrieval_context=["客服邮箱: support@example.com"]),LLMTestCase(input="产品支持哪些语言？",actual_output="我们支持中文和英文。",retrieval_context=["支持中文、英文、日文共三种语言"]),]# 同时运行两个指标metrics=[AnswerRelevancyMetric(threshold=0.7),FaithfulnessMetric(threshold=0.7),]# 批量评估results=evaluate(test_cases=test_cases,metrics=metrics)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_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="我持续咳嗽发烧，需要担心吗？",# 替换为你的 LLM 应用的实际输出actual_output="持续咳嗽和发烧可能是病毒感染，如症状加重建议就医。",expected_output="持续咳嗽和发烧可能从轻微病毒感染到肺炎等严重疾病，如症状持续或伴随呼吸困难，应就医。")# 断言测试通过assert_test(test_case,[correctness_metric])

# 运行 pytest 测试deepeval test run test_chatbot.py ```text ```text# 运行上面命令后，输出类似：=============================test session starts==============================collected1item test_chatbot.py.[100%]==============================1passedin2.34s===============================

2.4. 关键配置项

2.4.1. 指定评估用 LLM

# 来源: https://deepeval.com/docs/metrics-introductionfromdeepeval.metricsimportAnswerRelevancyMetric# 方式一：使用 OpenAI 的不同模型metric=AnswerRelevancyMetric(model="gpt-4.1")# 方式二：使用 gpt-4ometric=AnswerRelevancyMetric(model="gpt-4o")# 方式三：使用自定义模型（如 DeepSeek）frommy_modelsimportDeepSeekModel deepseek=DeepSeekModel()metric=AnswerRelevancyMetric(model=deepseek)

2.4.2. 缓存机制

DeepEval 默认启用缓存，相同参数的评估不会重复调用 LLM，节省成本和时间。

# 来源: https://deepeval.com/docs/metrics-introduction# 缓存默认开启，无需额外配置# 如需关闭缓存：importos os.environ["DEEPEVAL_CACHE_ENABLED"]="NO"

2.5. 小结

最小可运行：LLMTestCase+Metric+evaluate()= 15 行代码即可完成一次评估

三种模式：.measure()用于调试，evaluate()用于批量，assert_test()+deepeval test run用于 CI/CD

关键参数：threshold控制通过标准，model指定评估 LLM，include_reason输出评分理由

推荐配置：开发环境 threshold=0.5，生产环境 threshold=0.7，国内用 DeepSeek 替代 OpenAI