AgentEvalTool/docs/evaluation-workflow.md

使用 OpenClaw + AgentEvalTool 进行 AI 评测的流程

整体架构

┌─────────────────────────────────────────────────────────────────┐
│                      AgentEvalTool 管理后台                       │
│                     http://192.168.8.145:8001                    │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │ 评测对象  │  │ 评测场景  │  │ 评测执行  │  │ AI 助手(OpenClaw)│ │
│  │ (Target) │  │(Scenario)│  │  (Run)   │  │                  │ │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘ │
└──────────────┬───────────────────────────────┬──────────────────┘
               │ HTTP API + 轮询               │ iframe 嵌入
               ▼                               ▼
        ┌──────────────┐              ┌──────────────┐
        │  tutu-api    │              │  OpenClaw    │
        │  (被评测对象)  │              │  容器        │
        │  AI 客服      │              │  doubao-     │
        └──────────────┘              │  seed-2.0    │
                                      └──────────────┘

角色说明：

组件	角色	说明
AgentEvalTool	评测引擎	发送消息、收集回复、执行评测规则、生成报告
tutu-api	被评测对象	AI 数字员工 / AI 助手，通过 tutu 聊天 API 收发消息
OpenClaw	AI 助手 + 编排者	可通过对话触发评测，也可直接在管理后台使用

---

第一步：配置评测对象（Target）

评测对象是你要测试的 AI 系统。在管理后台「评测对象」页面新增。

配置信息

{
  "base_url": "https://tutu-gateway.lovebenefits.com/tutu-api",
  "token": "Bearer JWT Token",
  "tenant": "sx-jczs",
  "chat_channel_id": "0qlox3lg",
  "chat_contact_id": "vooddlwv"
}

字段	说明
base_url	tutu-api 网关地址
token	鉴权 JWT Token
tenant	租户标识
chat_channel_id	聊天频道 ID
chat_contact_id	聊天联系人 ID（模拟用户身份发消息）

验证连通性

配置完成后点击「测试」按钮，系统会调用 GET /api/{tenant}/v1/chat/message 验证连通性。

---

第二步：创建评测场景（Scenario）

评测场景包含一组测试用例，每个用例定义要发送的消息和评测规则。

场景 JSON 格式

[
  {
    "id": "case-001",
    "type": "single",
    "messages": [
      "你好，我想问下你们那边是否有做三伏灸"
    ],
    "expectations": {
      "response_time_max_ms": 30000,
      "keywords_include": ["三伏灸"]
    },
    "eval_rules": [
      {
        "type": "keyword_match",
        "params": { "keywords": ["三伏灸"] }
      },
      {
        "type": "response_time",
        "params": { "max_ms": 30000 }
      }
    ]
  }
]

多轮对话用例

{
  "id": "case-002",
  "type": "multi_turn",
  "messages": [
    "你们医院在哪里",
    "周末可以看诊吗"
  ],
  "eval_rules": [
    {
      "type": "response_time",
      "params": { "max_ms": 30000 }
    }
  ]
}

字段说明

字段	类型	说明
id	string	用例唯一标识
type	single / multi_turn	单轮 / 多轮对话
messages	string[]	依次发送给被评测对象的消息列表
eval_rules	object[]	评测规则列表（见下方）
expectations	object	预期结果（可自动推导规则）

评测规则

规则类型	说明	参数
keyword_match	检查回复是否包含/不包含指定关键词	keywords: 必须包含的关键词列表
response_time	检查回复延迟是否在阈值内	max_ms: 最大允许延迟（毫秒）
llm_score	调用 LLM 对回复质量打分	api_url, api_key, model, criteria, min_score

提示：如果不写 eval_rules，系统会根据 expectations 自动推导规则。

---

第三步：启动评测（Run）

方式一：Web 管理后台

1. 打开「评测执行」页面
2. 选择评测对象和评测场景
3. 点击「启动评测」
4. 右侧抽屉实时显示 WebSocket 推送的执行日志

方式二：CLI 命令

agenteval run start --target-id <target_id> --scenario-id <scenario_id>

方式三：OpenClaw AI 助手

在管理后台的「AI 助手」页面，通过对话让 OpenClaw 帮你触发评测：

请帮我执行一次评测，评测对象是社区医院AI客服，场景是社区医院基础服务评测

OpenClaw 会通过插件调用 agenteval run start CLI 命令，并返回评测报告。

---

第四步：查看评测结果

执行过程（实时）

评测启动后，系统对每个用例依次执行：

发送消息 → 轮询等待回复（最长30秒）→ 记录对话 → 执行评测规则 → 输出结果

WebSocket 实时推送以下事件：

事件	说明
case_start	开始执行某个用例
turn_end	一轮对话完成（含用户消息 + AI 回复 + 延迟）
rule_result	一条评测规则的判定结果
turn_error	消息发送或回复超时

评测报告

评测完成后，在「评测报告」页面查看：

• 统计数据：总用例数、通过数、失败数、通过率
• 元信息：评测对象、场景、开始/完成时间
• 用例明细：每个用例的逐轮对话内容 + 规则判定结果

也可以导出 HTML 报告。

---

当前已配置的资源

评测对象

名称	平台	通道	状态
社区医院AI客服	AI 数字员工	tutu-api	active

评测场景

名称	用例数	标签
社区医院基础服务评测	2	health, basic-service
科室导航与挂号咨询	3	health, department, navigation

历史评测记录

已执行 8 次评测，全部通过（pass_rate 100%），平均响应时间约 11 秒。

---

快速上手 Checklist

• 确认评测对象连通性（管理后台 → 评测对象 → 测试）
• 创建或选择评测场景
• 启动评测（Web UI / CLI / OpenClaw 对话）
• 查看实时执行日志
• 查看评测报告和用例明细