AgentbaseDocs
文档目录

在线与数据集评估、知识库评测与根因分析

功能概述

在线与数据集评估(Evaluations & Root Cause Analysis,控制台入口为 智能体运维 → 评估 与 评估技能)是 Agentbase(v2.10.0)提供的全场景自动化质量度量与智能归因引擎。在企业大模型应用落地过程中,仅靠人工抽检无法覆盖海量线上对话,也难以量化每次 Prompt 调整、模型切换或知识库分块/索引参数变更带来的真实收益或退化。

在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 **企业智能客服与知识中台**(enterprise-ai-hub-210)中,评估引擎基于 dashscope-prod 下的 qwen-plus(默认评估模型)与 qwen-vl-max(视觉评估模型),提供四大类专业评估任务与端到端根因诊断闭环:


核心概念与架构

评估系统将“评测模板与技能管理 → 多源目标变量映射 → 异步评测执行与二次复核 → 低分自动/手动根因分析(RCA)”整合在一条可验证、防篡改的流水线中。

flowchart TB
    subgraph EvalAssets["1. 评估资产与模型底座"]
        Templates["评估模板目录 (内置三语 / RAGAS / 自定义多版本)\n多标签分类筛选 & 证据化归因标签"]
        EvalSkills["评估技能包 (Evaluation Skills)\n只读 SKILL.md 与参考文档 (ZIP导入/导出)\n仅向 Judge 开放 skills_list & skill_view"]
        MCPTools["只读 MCP 取证工具\n从 AI Gateway 发现并挂载至 Agent 评估器"]
        JudgeModels["项目评估模型配置\n默认评估模型: qwen-plus | 视觉评估模型: qwen-vl-max"]
    end

    subgraph TaskTypes["2. 四大评估任务类型 (/observability/evals)"]
        GeneralEval["通用评估任务\n目标: Trace / Observation (observationScope) / Session / Dataset Run"]
        MemoryEval["Memory 阶段评估任务\n覆盖事实抽取、画像、技能/经验蒸馏等 10 大阶段"]
        ParsingEval["知识库解析与分块评估\n解析3维 (50%) + 分块5维 (50%) -> knowledgeBaseQuality"]
        IndexEval["知识索引质量评估 (v2.10.0)\nGraphRAG / RAPTOR / LLM Wiki -> knowledgeIndexQuality\n规则全检 + 默认30条分层抽样 + 独立二次复核"]
    end

    subgraph OutputAndRCA["3. 评分产出与根因分析闭环 (scoreAnalysis)"]
        Scores["产出正式 Score (保留两位小数)\n附带明细下钻 quality-details?kind=parsing|index"]
        RuleRCA["确定性规则根因分析 (trace_only / trace_plus_config)\n输出观测事实 + 根因置信度 (已确认/很可能/可能)"]
        ModelRCA["模型辅助根因分析 (useModel=true, 300s 预算)\n输出待验证原因假设 + 参数优化建议 (parameterChange v2)\n支持 knowledge_search_overrides 单变量对照试验"]
    end

    Templates --> GeneralEval
    EvalSkills --> GeneralEval
    MCPTools --> GeneralEval
    JudgeModels --> GeneralEval
    JudgeModels --> MemoryEval
    JudgeModels --> ParsingEval
    JudgeModels --> IndexEval
    GeneralEval --> Scores
    MemoryEval --> Scores
    ParsingEval --> Scores
    IndexEval --> Scores
    Scores --> RuleRCA
    RuleRCA --> ModelRCA

四大评估任务类型与适用场景对照表

任务类型评测对象与数据来源核心评测维度与算法机制评分元数据标识
通用评估单条/批量 Trace、特定 Observation(通过 observationScope 按类型与名称规则扇出)、Session 或 Dataset Run使用 LLM-as-a-Judge 模板(Prompt / Program / Agent 执行方式)映射 input、output、expected_output、trajectory 等变量打分。标准 EVAL Score(智能体工作台专用 RAG 模板生成 ragEvaluation 签名元数据)
Memory 评估项目内带 capability:memory 的记忆操作链路针对事实抽取、冲突更新决策、画像生成、技能蒸馏、经验蒸馏、知识合并/验证、查询改写与检索共 10 类流水线阶段执行证据核查。EVAL Score(关联 Memory 阶段归因标签)
知识库解析评估开启了摄取追踪(tracingEnabled=true)的知识库文档与切片(如 kb_enterprise_support)- 文档解析(占 50%):完整性、忠实度、结构 3 个维度;<br>- 文档分块(占 50%):边界合理性、上下文保留、独立完整性、块大小、冗余度 5 个维度。支持 PDF/图片页调用 qwen-vl-max 视觉比对。knowledgeBaseQuality(下钻接口 quality-details)
**知识索引质量评估(v2.10.0)**已成功构建索引产物的知识库版本(GraphRAG / RAPTOR / LLM Wiki)- GraphRAG:实体描述忠实度、关系支持度、社区报告忠实度与覆盖;<br>- RAPTOR:摘要忠实度、关键内容覆盖、层级摘要一致性;<br>- LLM Wiki:页面忠实度、引用支持度、内容覆盖、跨页面一致性。<br>三类各自独立聚合成 0~1 能力级质量分(不合成总分)。knowledgeIndexQuality(下钻接口 quality-details?kind=index)

角色、入口与关联关系

控制台入口与 REST API 权限矩阵

控制台入口位于:**项目 enterprise-ai-hub-210 → 智能体运维(Observability / AgentOps) → 评估(Evals) 及 评估技能(Evaluation Skills)**。

功能模块控制台路径后缀核心 REST API 端点所需权限 Scope
评估模板与任务管理/observability/evals/v1/observability/evals/*observability.evals.read / write
默认/视觉评估模型与模型 RCA 开关/observability/evals(顶部模型设置区)GET/PUT /v1/observability/evals/root-cause-analysis-settingsobservability.models.read / write
知识索引质量评估预览与创建创建评估任务 → 知识库解析评估(勾选索引能力)POST /v1/observability/evals/index-preview、POST /v1/observability/evals/indexobservability.evals.write + 知识库读取权限
评分明细下钻(解析/分块/索引)评分详情页 质量明细GET /v1/observability/scores/{scoreId}/quality-details?kind=indexobservability.scores.read
评估技能包管理与 ZIP 下载/observability/evaluation-skillsGET/POST /v1/observability/evaluation-skills、GET .../:skillId/versions/:versionId/downloadobservability.evals.read / write
Prompt 确定性解析/observability/promptsGET /v1/observability/prompts/resolveobservability.prompts.read

功能详解与操作指南

1. 浏览评估模板目录与配置默认/视觉评估模型

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

2. 管理评估技能(Evaluation Skills)与挂载只读 MCP 工具

当内置 Prompt 模板不足以表达复杂的企业专属评审规范(如多达数十页的金融客服合规手册或特定 SQL 审美规范)时,可创建项目级、版本化的 评估技能(Evaluation Skills):

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

3. 创建知识库解析质量与知识索引质量评估任务(kb_enterprise_support)

针对标杆知识库 **kb_enterprise_support(企业智能客服与技术支持知识库)**(已摄取 4 篇核心技术文档并启用了 GraphRAG、RAPTOR 与 Wiki 10 个编译页面),可在同一向导中发起解析/分块评估与索引产物质量评估:

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

# 示例:通过 REST API 预览并创建 kb_enterprise_support 的 GraphRAG、RAPTOR 与 Wiki 索引质量评估
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"

# 1. 预览三类索引产物的可评估记录规模
curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/evals/index-preview" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "knowledgeBaseId": "kb_enterprise_support",
    "capabilities": {
      "graphrag": { "enabled": true, "sampleSize": 30 },
      "raptor": { "enabled": true, "sampleSize": 30 },
      "wiki": { "enabled": true, "sampleSize": 30 }
    }
  }' | jq .

# 2. 正式提交知识索引质量评估任务 (指定中文评分模板 zh-CN)
curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/evals/index" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "kb_enterprise_support-v210-索引产物全面质量评估",
    "knowledgeBaseId": "kb_enterprise_support",
    "locale": "zh-CN",
    "capabilities": {
      "graphrag": { "enabled": true, "sampleSize": 30 },
      "raptor": { "enabled": true, "sampleSize": 30 },
      "wiki": { "enabled": true, "sampleSize": 30 }
    }
  }' | jq .

4. 评分根因分析(Root Cause Analysis / scoreAnalysis)与参数对照验证

当评估产生低分(关联 Trace 且归一化值 normalizedValue <= 0.5 的数值评分会自动触发;用户也可在评分详情或“分析洞察”列表中对任意关联 Trace 的数值评分手动点击 根因分析)时,系统异步生成结构化的 scoreAnalysis 诊断报告:

诊断层次与字段运行机制与技术特性输出内容与行动指导
**分析模式 (analysisMode)**自动识别 trace_only(外部上报或无配置快照)与 trace_plus_config(平台托管 Agent / RAG / Memory 且携带服务端签名配置快照)。严格基于当次冻结证据,绝不拿当前可变配置伪造历史运行状态。
**确定性规则诊断 (source=rules)**默认零模型成本执行,核验执行状态、工具错误、检索空结果、上下文截断与理由一致性。输出可核验的观测事实、根因分类及三级置信度(**已确认 confirmed / 很可能 probable / 可能 possible**)。
**模型增强归因 (source=model)**当项目开启 PUT /v1/observability/evals/root-cause-analysis-settings({"useModel": true})时启用,单次调用超时预算提升至 300 秒(24 KB 证据预算)。对照问题、检索候选、模型回答、标准答案与解析/索引原文,输出待验证原因假设(最高置信度为 probable),如 query_drift、context_irrelevance、answer_ungrounded、threshold_filtering。
**参数级修改建议 (parameterChange)**遵循 schemaVersion=2 协议,仅引用当次已知历史值的白名单配置字段(如 RAG 的 limit、similarityThreshold、vectorWeight、rerank、allowDegraded,或 Memory 的 prompt.skillDistillationPrompt)。给出 1 个主修改参数(primary)与最多 2 个依赖参数(dependencies),附带当前实际值、建议新值(百分之一网格精度)、支撑候选 ID 与原文短引文。
单变量对照试验验证系统不会自动修改生产配置。针对 RAG 参数建议,开发者可在 Agent Runtime ReAct Run 请求中传入 knowledge_search_overrides 对同题、同标准答案执行隔离对照。对比修改前后的四项 RAG 分数(查询质量、上下文相关性、忠实度、答案准确性)与 Token 消耗,确认真实改善后再合入正式配置。

用数据集评估 RAG 回答

需要比较检索配置或回答效果时,使用 Datasets → 目标数据集 → Runs → 创建运行。当前版本沿用该流程,不需要寻找额外的“评估 RAG”按钮。创建运行前确认具有数据集、运行与评估权限,项目中已有可用模型和配置了知识来源的 Agent。

准备与创建

评估指标回答的问题需要检查的证据
查询质量检索问题是否准确表达原问题用户问题与实际检索查询
上下文相关性用于回答的资料是否相关本次运行的检索上下文
回答忠实性回答是否受到资料支持实际回答与检索上下文
答案准确性回答是否与参考答案一致实际回答与独立准备的参考答案

读取结果与继续改进

在 Runs 打开运行,逐项对照问题、参考答案、实际回答、各指标评分和错误;通过关联 Trace 检查检索与生成过程,并在可用的评分详情查看根因分析。缺少检索证据、证据身份无法验证或缺少参考答案属于评估错误,不是零分,也不表示通过。

先区分没有运行成功、没有检索到资料、答案未引用正确资料以及评分失败,再决定修改知识库、Agent 或评估配置。每次只调整一个待验证因素,用同一组问题与参考答案创建下一次运行;同时比较逐题结果、失败数量及延迟,而不只比较平均分。高分和模型给出的优化建议仍需人工核对关键事实。

提交回执丢失时

超时或强制刷新可能发生在服务已经接收请求之后。保留原标签页,先在运行列表确认是否已创建。 原标签页的页面会话仍保留时,刷新或在同一标签页返回创建流程,才可恢复待确认请求身份;同时保持项目、数据集、执行方式和语言一致,保留待确认名称并重新填写相同配置。

若提示上次结果尚未确认,不要改名或更改配置反复提交。新开标签页、关闭后重新打开、清除浏览器数据或换浏览器时,都不能保证待确认请求身份仍在;即使是同一浏览器,也不能承诺重新提交会去重。此时先核对已有运行及其状态,无法确认则联系管理员协助检查,不直接重提。

常见问题与排障

1. 创建知识库解析评估或索引质量评估时,为什么某些知识库或索引能力选项处于禁用状态?

2. 为什么知识索引质量评估的得分旁标记了“样本质量分”或“部分完成”,且部分记录进入了“待复核区”?

3. 开启“使用模型进行根因分析(useModel: true)”后,历史已经生成的低分 Score 会自动重新调用模型分析吗?


相关文档