如何像写单元测试一样，系统化地评测你的 AI 智能体？

引言：为什么智能体评测迫在眉睫？

随着大语言模型（LLM）应用从简单的“聊天机器人”进化为复杂的“智能体”（Agent），传统的“凭感觉看回答好不好”的评测方式已经彻底失效。

现在的智能体不再是单次问答，而是涉及多轮对话、工具调用、多步规划的复杂系统。任何一个环节出错——工具选错、参数传错、中间步骤逻辑断裂——都可能导致最终结果失败。因此，建立一套自动化、可量化、可持续的评测体系，已经成为智能体从“能用”迈向“好用”的关键基础设施。

本文假设你已经自建了一个提供 API 接口的智能体，需要在离线环境下评测其效果。我们将带你从框架选型、代码实现，到基于结果进行优化，完成整个闭环。

---

第一章：评测框架选型——哪个最适合你？

目前开源社区提供了多个评测框架，但它们定位差异明显。我们先快速对比四个主流选手：

框架	核心定位	离线支持	最适合场景
DeepEval	LLM 应用的 Pytest	⭐⭐⭐⭐⭐ 原生支持	日常开发迭代、CI/CD 集成
OpenAgent Eval	本地诊断专家	⭐⭐⭐⭐⭐ 完全离线	故障定位、深度诊断
AgentBench	学术研究标准	⭐⭐⭐ 需要 Docker	论文发表、8 大环境推理评测
Exgentic	横向对比平台	⭐⭐ 偏重平台	与 SOTA 对比、权威基准测试

选型建议

• 日常开发迭代 → 选 DeepEval：上手最快，像写单元测试一样写评测。
• 深度诊断问题 → 选 OpenAgent Eval：18+ 指标帮你定位是检索还是生成环节出错。
• 学术研究/发论文 → 选 AgentBench：ICLR 认可的标准评测集。
• 与业界 SOTA 对比 → 选 Exgentic：统一接口跑权威基准。

对于绝大多数开发者，DeepEval 是最务实的选择——本篇文章也以它为主线展开。

---

第二章：离线环境下的 DeepEval 实战

2.1 安装与环境准备

DeepEval 默认离线运行，所有评测均在本地完成，数据不出域。

pip install deepeval

2.2 核心概念：两个“模型”要分清

在 DeepEval 的架构中，你需要配置两个独立的模型：

角色	作用	是否必须兼容 OpenAI 格式
被测智能体 (Your Agent)	被测试的对象，返回回答内容	❌ 不必须，只要返回文本即可
评委模型 (Judge Model)	给智能体的回答打分	✅ 强烈建议，否则需要大量自定义代码

关键洞察：你不需要为了评测去重构智能体的 API 接口。只需写一个薄薄的封装函数调用它，拿到返回文本即可。真正需要关注的是“评委模型”的配置方式。

2.3 配置评委模型（指向你的本地 API）

如果你的评委模型通过 LM Studio、vLLM、Ollama 等工具部署，且兼容 OpenAI Chat Completions 格式，配置将极其简单。

方法一：命令行全局配置

deepeval set-local-model \
  --model-name="Llama-3-8B" \
  --base-url="http://localhost:1234/v1/"

方法二：代码中局部配置（更灵活，推荐）

from deepeval.models import LocalModel
from deepeval.metrics import GEval

local_model = LocalModel(
    model="Llama-3-8B",                      # 模型名称
    base_url="http://localhost:1234/v1/",    # 你的本地 API 地址
    api_key="dummy"                          # 本地服务通常不需要真实密钥
)

metric = GEval(
    name="Correctness",
    criteria="评估回答的正确性。",
    model=local_model  # 关键：指定评委模型
)

提示：如果使用 Ollama，可先通过 OLLAMA_ORIGINS=* ollama serve 启动服务，再配合 base_url="http://localhost:11434/v1/" 使用。

2.4 完整的端到端评测示例

以下脚本演示了如何调用你的智能体 API，并使用本地评委模型进行评分：

import requests
from deepeval import assert_test
from deepeval.test_case import LLMTestCase
from deepeval.metrics import GEval
from deepeval.models import LocalModel

# 1. 封装调用智能体 API 的函数（无需改造智能体本身）
def call_my_agent(question: str) -> str:
    response = requests.post(
        "http://localhost:8080/agent",   # 你现有的智能体地址
        json={"query": question}
    )
    return response.json()["answer"]

# 2. 配置评委模型（指向本地评测模型）
judge_model = LocalModel(
    model="Qwen-7B",
    base_url="http://localhost:1234/v1/",  # LM Studio / vLLM / Ollama
    api_key="dummy"
)

# 3. 准备测试数据
question = "法国的首都是哪里？"
actual_answer = call_my_agent(question)    # 调用你的智能体

test_case = LLMTestCase(
    input=question,
    actual_output=actual_answer,
    expected_output="巴黎"                  # 标准答案
)

# 4. 定义评测指标并运行
metric = GEval(
    name="Correctness",
    criteria="基于期望输出，评估实际输出的正确性。",
    model=judge_model
)

assert_test(test_case, [metric])

2.5 评测智能体的多轮对话与工具调用

如果你的智能体涉及更复杂的交互模式，DeepEval 同样提供了专门的测试结构。

多轮对话测试

from deepeval.test_case import ConversationalTestCase, Turn

test_case = ConversationalTestCase(
    turns=[
        Turn(role="user", content="预订明天晚上7点的两人位。"),
        Turn(role="assistant", content="好的，请问您贵姓？"),
        Turn(role="user", content="我姓张。"),
        Turn(role="assistant", content="张先生，已为您预订。")
    ]
)

# 可配合 ConversationRelevancyMetric 等指标使用

工具调用评测

from deepeval.metrics import ToolUseMetric
from deepeval.tool import ToolCall

available_tools = [
    ToolCall(name="get_weather", description="获取天气信息"),
    ToolCall(name="search_web", description="搜索互联网")
]

metric = ToolUseMetric(available_tools=available_tools)
# 框架会自动评估工具选择的正确性以及参数传递的准确性

---

第三章：如何根据评测结果优化智能体

拿到评分只是第一步，真正有价值的是从分数中提炼出优化方向。

3.1 从指标到归因：先定位问题环节

DeepEval 会输出多个维度的指标分数。你可以根据低分项反向排查问题所在：

低分指标	可能原因	排查方向
Answer Relevancy 低	回答跑题或包含多余信息	检查 Prompt 中的指令是否清晰，是否被无关上下文干扰
Faithfulness 低	回答与检索内容矛盾（出现幻觉）	增强检索相关性，或降低生成温度
Contextual Recall 低	检索遗漏了关键信息	优化检索策略（调整 chunk 大小、更换 embedding 模型）
Contextual Precision 低	检索结果噪声太大	增加重排序（rerank）或过滤机制
Tool Use 低	选错工具或传错参数	检查工具描述是否清晰，补充 Few-shot 示例

3.2 针对性优化三板斧

第一板斧：Prompt 优化（成本最低、见效最快）

• 利用 DeepEval 的 Test Driven Prompt Engineering 功能：每调整一次 Prompt，自动跑一遍评测集，直接观察指标变化。
• 针对工具调用失败，在 Prompt 中加入清晰的工具使用示例（Few-shot），并约束输出格式。

第二板斧：检索策略优化（针对 RAG 类智能体）

• 调整 chunk 大小：从 512 token 开始实验，找到检索粒度的甜点。
• 引入重排序（Rerank）模型：提升 Contextual Precision，让真正相关的文档排在最前面。
• 尝试 HyDE（假设性文档检索）：先让 LLM 生成假设性答案，再用它去检索，可有效提升 Contextual Recall。

第三板斧：模型/架构升级（成本较高）

• 若上述优化效果仍不理想，考虑升级主模型或 embedding 模型。
• 引入更先进的 Agent 框架（如 Reflexion、ReAct 的变体），提升多步推理能力。

3.3 建立持续评测的 CI/CD 流水线

将评测嵌入开发流程，确保每次变更都自动验证。

# GitHub Actions 示例（离线环境使用自建 runner）
name: Agent Evaluation
on: [push, pull_request]
jobs:
  evaluate:
    runs-on: [self-hosted]  # 离线环境自建 runner
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: pip install deepeval
      - name: Run evaluation
        run: deepeval test run
      # 可选：将报告上传到 Confident AI 平台（也支持本地部署）
      # - run: deepeval test run --confident-api-key=${{ secrets.CONFIDENT_API_KEY }}

3.4 效果跟踪：建立评测看板

• 使用 DeepEval 的 Confident AI 平台（支持本地部署）可视化跟踪多次评测的历史趋势。
• 重点关注每次优化后，RAGAS 分数或任务完成率（Task Completion Rate）的变化曲线。

---

第四章：总结与行动路线图

一句话总结

DeepEval 让智能体评测像写单元测试一样自然，本地部署确保数据安全，评测结果则直接为你指明了优化方向。

你的行动清单

1. 选型确认：根据你的场景（离线、智能体 API、日常开发），选择 DeepEval 作为评测框架。
2. 安装配置：pip install deepeval，并配置好本地评委模型的 API 地址。
3. 写第一个测试：从单轮问答开始，覆盖核心业务场景。
4. 扩展测试覆盖：逐步加入多轮对话、工具调用等复杂场景的测试用例。
5. 建立基线：完整跑一轮评测，记录当前各指标分数作为基线。
6. 迭代优化：根据低分项进行针对性优化，每次改动后重新跑评测验证。
7. 持续集成：将评测集成到 CI/CD 流程中，让每次代码变更自动触发评测。

---

没有评测就没有优化，没有量化就没有进步。
为你的智能体建立一套系统化的评测体系，是让它真正走向生产环境最重要的一步。
你的智能体现在有评测体系了吗？如果没有，今天就从第一个测试用例开始吧。