sinohqb 01af6fca74 docs(research): 功能完整性评估方案调研

为 ticket #18 提供技术方案，分析现有 6 种规则对"意图识别→任务完成度→任务成功率"
分层测量的覆盖能力，推荐新增 task_completion 规则解决多轮对话结构化评估缺口。

2026-08-25 14:00:59 +08:00

20 KiB

Raw Blame History

功能完整性评估方案调研

调研日期：2026-08-25 关联 Ticket：#18（功能完整性评估） Wayfinder Map：#13 代码库版本：v1.3.0（main 分支）

1. 现有规则能力分析

平台当前注册了 6 种评估规则（@register_rule 插件式注册），以下逐一分析其对分层测量的适用性。

1.1 规则清单与能力矩阵

规则	注册名	评估对象	输入范围	输出	模型依赖
关键词匹配	`keyword_match`	最后一轮回复	`dialog[-1].reply`	passed + score（匹配比例）	无
响应时间	`response_time`	最后一轮延迟	`dialog[-1].latency_ms`	passed + score（时延/阈值比）	无
LLM 评分	`llm_score`	最后一轮回复	`dialog[-1]` 的问答对	passed + score（0-10 归一化）	JUDGE（chat）
语义相似度	`semantic_similarity`	最后一轮回复	`dialog[-1].reply` vs reference	passed + score（余弦相似度）	EMBEDDING
JSON Schema	`json_schema`	最后一轮回复	`dialog[-1].reply` 结构	passed + 检查项计数	无
安全检测	`safety`	最后一轮回复	`dialog[-1].reply`	passed + 违规类别	MODERATION（可选）

1.2 关键限制：最后轮次瓶颈

所有现有规则都只评估 dialog[-1]（最后一轮回复）。这在引擎代码中是硬编码的：

# keyword.py
last_turn = dialog[-1]
text = extract_reply_text(last_turn.reply).lower()

# llm_score.py
last_turn = dialog[-1]
reply_text = extract_reply_text(last_turn.reply)

# semantic.py
reply_text = extract_reply_text(dialog[-1].reply)

虽然引擎在 _save_rule_results 中将完整 dialog: list[Turn] 传入 rule.evaluate(case, dialog)，但所有规则实现都忽略了多轮上下文。

对分层测量的影响：

意图识别：通常只需评估单轮（用户发问 -> 智能体是否正确理解），最后轮次评估可以满足。
任务完成度：需要跨多轮评估（如"是否收集了 3/5 个必要信息"），现有规则无法直接支持。
任务成功率：需要综合多轮对话的全局判断，现有规则无法直接支持。

1.3 规则组合逻辑

RuleLogic 提供三种组合方式：

all：所有规则必须通过（AND 语义）
any：至少一条通过（OR 语义）
weighted：加权平均分 >= 阈值（加权聚合）

隐式规则（从 Expectation 派生）是硬约束，任一失败则用例失败，独立于 rule_logic。

组合能力评估：三种逻辑足以表达"分层测量中各层独立判定"的需求——每层可以是一组规则，层间用 all 组合（层间 AND），层内用 weighted 聚合。但前提是需要规则能覆盖各层的评估维度。

2. 分层测量的实现方案

2.1 三层定义

层级	名称	含义	测量粒度
L1	意图识别准确率	智能体是否正确理解了用户意图	单轮级（per-turn）
L2	任务完成度	智能体是否完成了任务要求的各项子目标	用例级（per-case，跨轮次）
L3	任务成功率	整个任务是否最终成功	用例级（per-case，全局判定）

三层关系：L1 是 L2 的必要条件（意图识别错误则任务不可能完成），L2 是 L3 的主要决定因素（但不完全等价——任务完成但体验差仍可能判定为不成功）。

2.2 方案 A：组合现有规则（零新增规则）

思路：仅使用 llm_score 的自定义 criteria 能力覆盖三个层级。

L1 - 意图识别：

{
  "type": "llm_score",
  "params": {
    "criteria": "评估智能体是否正确识别了用户意图。用户意图是：{intent_description}。如果智能体的回复表明它理解了用户想要什么，给 8-10 分；如果部分理解（如识别了主题但误解了具体需求），给 4-7 分；如果完全误解或未回应意图，给 0-3 分。",
    "min_score": 7
  }
}

L2 - 任务完成度：

{
  "type": "llm_score",
  "params": {
    "criteria": "评估智能体是否完成了以下子任务：1) 收集用户姓名 2) 收集联系方式 3) 确认服务地址 4) 说明服务内容 5) 告知预计时间。每完成一项得 2 分，满分 10 分。",
    "min_score": 6
  }
}

L3 - 任务成功率：

{
  "type": "llm_score",
  "params": {
    "criteria": "综合评估本次对话是否成功完成了用户任务。考虑：意图是否正确处理、必要信息是否收集完整、用户问题是否得到解决。成功给 10 分，部分成功给 5-7 分，失败给 0-3 分。",
    "min_score": 7
  }
}

优点：

零代码变更，纯配置层面实现
利用现有 weighted 规则逻辑可以给三层分配权重

缺点：

llm_score 只看 dialog[-1]，L2/L3 的跨轮次评估不准确
LLM 评分的稳定性问题：同一对话多次评分可能结果不同
三个 llm_score 规则各自独立调用 LLM，无法共享中间推理结果
criteria 的编写质量直接决定评估质量，维护成本高

2.3 方案 B：新增 `task_completion` 规则（推荐）

思路：新增一种支持全对话评估的规则类型，专门用于任务完成度和成功率测量。

2.3.1 新规则：`task_completion`

@register_rule
class TaskCompletionRule(EvalRule):
    """Evaluate task completion by checking required slots/steps across the full dialog."""

    name = "task_completion"

核心设计：

接收完整 dialog: list[Turn]（而非只看最后一轮）
支持两种评估模式：
- slot 模式：定义需要收集的信息槽位（如姓名、电话、地址），LLM 判断每个槽位是否已收集
- step 模式：定义需要完成的步骤（如确认身份、记录问题、给出方案），LLM 判断每个步骤是否完成
输出：每个槽位/步骤的完成状态 + 总体完成率

参数设计：

{
  "type": "task_completion",
  "params": {
    "mode": "slot",
    "required_slots": [
      {"name": "user_name", "description": "用户姓名"},
      {"name": "phone", "description": "联系电话"},
      {"name": "address", "description": "服务地址"},
      {"name": "service_type", "description": "服务类型"},
      {"name": "appointment_time", "description": "预约时间"}
    ],
    "min_completion_rate": 0.6,
    "evaluation_scope": "full_dialog"
  }
}

评估逻辑：

拼接完整对话（所有轮次的 sent_message + reply）
调用 LLM（JUDGE 岗位），逐一判断每个 slot 是否在对话中被收集
计算完成率 = 已收集槽位数 / 总槽位数
passed = completion_rate >= min_completion_rate

2.3.2 新规则：`intent_classification`（可选）

@register_rule
class IntentClassificationRule(EvalRule):
    """Check whether the agent correctly identified the user's intent."""

    name = "intent_classification"

与 llm_score 的区别：

llm_score 输出连续分数（0-10），适合质量评分
intent_classification 输出分类结果（正确/部分正确/错误），适合精确的意图匹配
支持定义意图分类表（intent taxonomy），LLM 从中选择

参数设计：

{
  "type": "intent_classification",
  "params": {
    "expected_intent": "appointment_booking",
    "intent_taxonomy": {
      "appointment_booking": "预约服务",
      "inquiry": "咨询信息",
      "complaint": "投诉反馈",
      "other": "其他"
    },
    "accept_partial": true
  }
}

2.4 方案 C：扩展 `llm_score` 支持全对话评估（折中方案）

思路：不新增规则类型，但扩展 llm_score 的参数，使其支持 evaluation_scope: "full_dialog" 模式。

变更点：

llm_score.py 中，当 params.evaluation_scope == "full_dialog" 时，拼接全部轮次的对话作为评估输入
新增 params.dialog_format 控制对话拼接格式

优点：

不增加规则注册表的复杂度
复用 llm_score 的模型调用链路

缺点：

llm_score 职责膨胀，从"单轮质量评分"变成"万能评估器"
无法表达结构化的任务完成度（如"收集了 3/5 个信息"）
与现有 llm_score 用例的语义不一致

2.5 方案对比

维度	方案 A（纯组合）	方案 B（新增规则）	方案 C（扩展 llm_score）
代码变更量	0	中（新增 1-2 个规则文件）	小（修改 1 个文件）
L1 意图识别	可行（llm_score 单轮够用）	最优（专用规则，结构化输出）	可行
L2 任务完成度	不准确（只看最后一轮）	最优（全对话 + 结构化槽位）	可行但不结构化
L3 任务成功率	不准确（只看最后一轮）	最优（可基于 L1+L2 聚合）	可行但不结构化
评估稳定性	低（LLM 自由评分）	高（结构化判断）	低
前端展示友好度	低（只有分数）	高（可展示每个槽位完成状态）	低
维护成本	高（criteria 易腐化）	中（规则逻辑固定，参数可变）	中
与现有架构一致性	高	高（插件式注册）	中

3. 任务完成度的量化方式

3.1 槽位填充模型（Slot-Filling）

定义：一个任务需要收集 N 个信息槽位（slots），评估智能体在对话中实际收集了多少个。

completion_rate = filled_slots / total_required_slots

示例：预约维修服务需要收集 5 个信息：

姓名、电话、地址、故障描述、期望时间
智能体收集了 3 个 → completion_rate = 3/5 = 0.6

实现方式：

场景配置中定义 required_slots 列表
规则执行时，LLM 逐一判断每个槽位是否在对话中被收集
输出：{slot_name: filled/unfilled} 的映射 + 总体完成率

优点：直观、可解释、可部分得分 适用场景：信息收集类任务（预约、登记、咨询）

3.2 步骤完成模型（Step Completion）

定义：一个任务需要完成 N 个步骤（steps），评估智能体完成了多少个。

completion_rate = completed_steps / total_required_steps

示例：投诉处理需要完成 4 个步骤：

倾听并记录投诉内容
表达歉意和同理心
给出解决方案或升级路径
确认用户满意

与槽位填充的区别：步骤有顺序依赖（先记录再解决），槽位无顺序。

3.3 混合模型

实际场景中，一个任务可能同时包含槽位填充和步骤完成。建议 task_completion 规则支持混合配置：

{
  "mode": "hybrid",
  "required_slots": [...],
  "required_steps": [...],
  "slot_weight": 0.4,
  "step_weight": 0.6,
  "min_completion_rate": 0.7
}

3.4 量化方式推荐

任务类型	推荐量化方式	理由
信息收集（预约/登记）	槽位填充	目标是收集完整信息
流程执行（投诉/退款）	步骤完成	目标是按流程处理
问答咨询	不适用（用 llm_score 即可）	无结构化子任务
复杂混合任务	混合模型	同时有信息收集和流程要求

4. 任务成功率的定义

4.1 选项分析

选项 A：二值判断（pass/fail）

定义：任务要么成功，要么失败，没有中间状态
判定标准：所有关键条件满足 = 成功，否则 = 失败
优点：简单明确，易于聚合（成功率 = 成功用例数 / 总用例数）
缺点：丢失了"接近成功"的信息

选项 B：概率/连续分数

定义：任务成功率是一个 0-1 的连续值
计算：各层得分的加权组合
优点：保留了粒度信息
缺点：语义模糊（0.7 的成功率是什么意思？）

选项 C：分级判定（推荐）

定义：三级结果
- success：任务完全成功（所有关键条件满足）
- partial：部分成功（核心目标达成但有缺陷）
- failure：任务失败（核心目标未达成）
聚合时：success = 1.0, partial = 0.5, failure = 0.0
优点：兼顾粒度和可解释性

4.2 推荐定义

任务成功率采用分级判定 + 数值聚合的混合方案：

case_outcome:
  L1_intent: passed / failed        (llm_score 或 intent_classification)
  L2_completion: 0.0 ~ 1.0          (task_completion 规则的 completion_rate)
  L3_success: success / partial / failure  (综合判定)

聚合规则：
  L3_success = success  IF L1_intent.passed AND L2_completion >= 0.8
  L3_success = partial  IF L1_intent.passed AND L2_completion >= 0.5
  L3_success = failure  OTHERWISE

场景级成功率 = (success_count + 0.5 * partial_count) / total_cases

与现有判定体系的关系：

现有 CaseOutcome.passed 保持二值语义（passed = L3_success != failure）
新增 CaseOutcome.success_level 字段存储分级结果（success/partial/failure）
RunSummary 新增 success_rate（分级聚合）与现有 pass_rate（二值）并存

4.3 分层聚合公式

场景级指标：
  intent_accuracy    = L1_passed_count / total_cases
  avg_completion     = mean(L2_completion_rates)
  success_rate       = (success + 0.5*partial) / total_cases
  pass_rate          = (success + partial) / total_cases  # 兼容现有口径

5. 工作量估算

5.1 方案 B（推荐方案）详细拆分

工作项	内容	人天
后端：`task_completion` 规则	新建规则文件、slot/step 评估逻辑、全对话拼接、LLM 调用、结构化输出解析	2.0
后端：`intent_classification` 规则（可选）	新建规则文件、意图分类 prompt、分类结果匹配	1.0
后端：模型扩展	`Case` 模型新增 `required_slots` / `required_steps` 字段（或复用 `eval_rules.params`）、`EvalResult` 新增 `detail` 字段存储结构化结果	0.5
后端：判定逻辑	`judgement.py` 扩展支持三级判定（success/partial/failure）、`RunSummary` 新增 `success_rate`	1.0
后端：聚合指标	`run_summary.py` 新增分层指标计算	0.5
后端：测试	单元测试（规则逻辑、判定逻辑、聚合计算）+ 集成测试	1.5
前端：场景编辑	任务完成度规则的配置表单（槽位/步骤编辑器）	1.5
前端：结果展示	Run 报告页展示分层指标（L1/L2/L3）、槽位完成详情	1.5
文档	规则扩展文档、场景配置指南	0.5
合计		10.0

5.2 方案 A（纯组合，零代码）工作量

工作项	人天
场景配置模板（各任务类型的 criteria 编写）	1.0
前端：无变更（复用现有 llm_score 展示）	0
测试验证	0.5
合计	1.5

5.3 方案 C（扩展 llm_score）工作量

工作项	人天
后端：`llm_score` 扩展 `evaluation_scope` 参数	1.0
后端：prompt 模板改造	0.5
后端：测试	0.5
前端：无变更	0
合计	2.0

6. 推荐方案

6.1 推荐：方案 B（新增 `task_completion` 规则）

理由：

解决核心痛点：现有规则的最后轮次瓶颈是功能完整性评估的根本障碍。方案 A 和 C 都无法真正解决多轮任务完成度的量化问题。
结构化输出：task_completion 规则产出每个槽位/步骤的完成状态，前端可以展示"收集了 3/5 个必要信息"这种直观结果，比 LLM 自由评分的 7.2 分有意义得多。
评估稳定性：结构化判断（这个槽位是否被填充）比自由评分（给这个回复打 0-10 分）的 LLM 输出稳定性高得多。
架构一致性：遵循现有的插件式规则注册模式，新增规则不影响引擎核心逻辑。
渐进实施：可以先实现 task_completion 规则（覆盖 L2），L1 继续用 llm_score（单轮评估够用），L3 通过判定逻辑聚合。intent_classification 规则可以后续按需添加。

6.2 实施路径建议

Phase 1（MVP，3 人天）：
  - 新增 task_completion 规则（slot 模式）
  - 扩展 judgement.py 支持分层判定
  - RunSummary 新增分层指标
  - 单元测试

Phase 2（完善，3 人天）：
  - task_completion 规则支持 step 模式和混合模式
  - 前端场景编辑：槽位/步骤配置 UI
  - 前端结果展示：分层指标 + 槽位详情

Phase 3（增强，2 人天）：
  - intent_classification 规则（可选）
  - 场景级聚合指标（intent_accuracy、success_rate）
  - 报告模板适配

6.3 场景配置示例

一个完整的"预约维修服务"功能完整性评估场景：

{
  "name": "预约维修服务 - 功能完整性",
  "cases": [
    {
      "id": "case-001",
      "type": "multi_turn",
      "messages": [
        "我家空调坏了，想预约维修",
        "我叫张三",
        "电话是 13800138000",
        "地址是朝阳区建国路 88 号"
      ],
      "eval_rules": [
        {
          "type": "intent_classification",
          "params": {
            "expected_intent": "appointment_booking",
            "intent_taxonomy": {
              "appointment_booking": "预约服务",
              "inquiry": "咨询信息",
              "complaint": "投诉反馈"
            }
          },
          "weight": 1.0
        },
        {
          "type": "task_completion",
          "params": {
            "mode": "slot",
            "required_slots": [
              {"name": "user_name", "description": "用户姓名"},
              {"name": "phone", "description": "联系电话"},
              {"name": "address", "description": "服务地址"},
              {"name": "fault_description", "description": "故障描述"},
              {"name": "appointment_time", "description": "预约时间"}
            ],
            "min_completion_rate": 0.6
          },
          "weight": 2.0
        },
        {
          "type": "llm_score",
          "params": {
            "criteria": "评估智能体的服务态度是否专业、礼貌、有同理心",
            "min_score": 7
          },
          "weight": 1.0
        }
      ],
      "rule_logic": "weighted",
      "rule_pass_threshold": 0.7
    }
  ]
}

6.4 风险与缓解

风险	影响	缓解措施
LLM 判断槽位填充的准确性	错误判定导致评估结果不可信	提供 few-shot 示例；支持人工复核模式
多轮对话拼接超出 LLM 上下文	长对话被截断	限制最大轮次数；摘要压缩早期轮次
槽位定义的主观性	不同人对于"是否收集了地址"可能有不同判断	槽位描述要具体；提供判定示例
与现有 pass_rate 口径的关系	新旧指标并存可能混淆	明确文档说明；前端标注新旧指标

附录：现有规则对分层测量的覆盖分析

分层	现有规则能否覆盖	说明
L1 意图识别	部分可以	`llm_score` 自定义 criteria 可做意图判断，但输出非结构化（只有分数，没有"识别为哪个意图"的明确结论）
L2 任务完成度	不可以	所有规则只看最后一轮，无法评估跨轮次的信息收集/步骤完成情况；`llm_score` 即使看全对话也无法输出结构化的槽位完成状态
L3 任务成功率	间接可以	可以通过 `weighted` 逻辑组合 L1+L2 的分数聚合，但前提是 L2 能准确测量

结论：现有规则体系的核心缺口是 多轮对话的结构化评估能力。新增 task_completion 规则填补这个缺口后，三层测量即可完整实现。

20 KiB Raw Blame History Unescape Escape