Docs
文档目录

经验(Experiences)与技能(Skills)知识蒸馏

功能概述与核心场景

在企业级智能体(Agent)生产体系中,传统的陈述性记忆(Declarative Memory,如单条事实 fact 和用户偏好 preference)只能回答“用户是谁、系统当前配置是什么”,却无法回答“当遇到某类复杂生产故障时,应该按照什么方法论和步骤调用工具解决问题”。随着客服与运维智能体每天处理成百上千次多轮工单对话与工具执行(Tool Execution Trajectories),如果不能将成功排障的操作轨迹沉淀为程序性知识(Procedural Knowledge),智能体在下次遇到同类故障时仍需从零试错。

Agentbase Memory 提供原生的经验(Experiences)与技能(Skills)知识蒸馏(Knowledge Distillation)能力。系统通过可编排的知识蒸馏流水线(distillation Pipeline),使用项目配置的模型处理会话消息(messages)和工具调用事件轨迹(toolEvents),生成经验与技能候选;实际结果需要结合证据检查:

在 Agentbase 企业智能中台(组织 ID:69c6d1aa00062e6bb60)的示例项目 企业智能客服与知识中台(项目 ID:enterprise-ai-hub-210,基于 OceanBase Shared V2 存储模式)中,运维团队将 VIP 架构师 user_zhangwei_001 与一线工程师 user_lina_002 处置 OceanBase 向量内存不足 (-4013)、AI 网关 429 限流自动故障转移 等示例工单的对话与工具轨迹提交蒸馏(如示例蒸馏任务 dst_3e5b09f456c5d5c332507ec1dbe3eb6d 与 dst_adc2cfda21c940fb5d5e4a3263ae56f9),实现了跨会话、跨用户的排障智慧自动复用。


核心概念与架构

Agentbase Memory 的知识蒸馏引擎通过七步标准流水线(7-Step Distillation Pipeline)串联证据接收、技能抽取与合并、经验抽取与关联、安全质量校验及落库投影。

1. Experience(经验)vs Skill(技能)结构化模型深度对比

虽然 Experience 与 Skill 同属 L1 程序性知识层(共享 knowledgeId 命名体系与不可变修订版本 revisionId),但二者在认知定位、结构化 Schema 与消费方式上职责分明:

对比维度排障经验(Experience)标准化技能(Skill)
核心认知定位情境化案例与避坑指南(Case-Based Reasoning):回答“在什么业务背景和故障现象下,为什么某做法有效或失败,有哪些经验教训”。可执行的标准作业程序(Standard Operating Procedure, SOP):回答“当触发某条件时,第一步查什么、第二步调什么工具、参数怎么填、怎么验证恢复”。
结构化核心字段外层知识对象含 knowledgeId、title、version、scope 与 experience;经验内容含 situation、decision、action、constraints、evidence、outcome 和 skillItemIds。外层知识对象含 knowledgeId、title、version、scope 与 skill;技能内容含 description、inputs、applicability、preconditions、procedure 和 expectedOutcome。
相互引用关系一条 Experience 可以关联引用本次或存量产出的 Skill(当所依赖的 Skill 尚未被批准激活时,会触发 skill_dependency_not_approved 保护)。Skill 在蒸馏流水线中先于 Experience 抽取(Step 2 & 3),以便后续 Experience(Step 4)能够直接引用已标准化的技能标识。
Prompt 注入时机在智能体开展根因分析、方案选型或回答复杂咨询时注入,提供历史同类案例参考。在智能体规划工具调用(Tool Planning)或执行自动化运维 SOP 时注入,指导精确的多步操作。

2. 七步知识蒸馏流水线(distillation Pipeline)逐节点解析

在 记忆 → 配置 → 经验与技能 Pipeline 中,每条蒸馏流水线固定由以下 7 个顺序节点构成:

步骤序号节点标识 (step)是否必选核心处理逻辑、模型调用与可调参数
Step 1receive必选接收与有界证据校验:校验输入的 messages 对话轮次与 toolEvents 工具执行轨迹(通过 maxToolEvents 限制单次最大工具事件数,防止超长循环日志撑爆上下文),并在 OceanBase sources 表中冻结不可变的 L0 原始证据记录。
Step 2skill_extraction可开关(与 Step 4 至少开启一项)抽取可复用 SOP 技能候选:调用配置的模型分析对话与 toolEvents 中的成功工具调用序列,提炼包含 title、preconditions、procedure、inputs 与 expectedOutcome 的候选技能。支持自定义 skillDistillationPrompt。
Step 3skill_merge随 Step 2 联动召回相似存量技能并决策合并:使用项目实例配置的向量模型和维度,在同一治理作用域内召回 Top maxCandidates(取值 1~20)存量技能,结合余弦相似度阈值 mergeThreshold(取值 (0, 1])与 skillMergePrompt 交由模型决策:新增独立技能(ADD)、融合补充进既有技能并生成新修订版本(MERGE)或跳过重复项(SKIP)。
Step 4experience_extraction可开关(与 Step 2 至少开启一项)抽取排障经验并关联技能引用:调用配置的模型从任务全貌中提炼情境案例(situation、decision、action、outcome、evidence),并自动将 Step 2/3 产出的相关技能绑定为知识引用。支持自定义 experienceDistillationPrompt。
Step 5experience_merge随 Step 4 联动召回相似存量经验并决策合并:召回 Top maxCandidates(1~20)相似存量经验,按 mergeThreshold 与 experienceMergePrompt 执行跨会话合并(累加有效来源标识 sourceIds;不同来源不保证来自不同会话,助推达到 minIndependentSessionsForAgent 激活门槛)或新增。
Step 6validation必选质量与安全守门校验:强制执行的独立验证节点(支持定制 evolutionValidationPrompt)。检查候选知识的逻辑、证据与置信度(confidence);低置信度知识可能被保留在 shadow,而非一律丢弃。输入与生成内容的安全检查覆盖有限模式,提交前必须脱敏,不能依赖系统拦截全部敏感信息。
Step 7knowledge_operation必选知识落库与状态路由:持久化知识主记录、不可变版本快照(Revision)及 L0 来源关联;之后根据来源策略可能单独排队向量投影任务。主记录已创建不代表投影已就绪。知识状态由验证、作用域与配置等共同决定;已激活状态为 user-active 或 agent-active,也可能处于 candidate、shadow 等状态。

功能入口与权限矩阵

控制台入口位于:项目 enterprise-ai-hub-210 → 记忆(Memory) → 演化页签,配套流水线配置位于 记忆 → 配置 → 经验与技能 Pipeline。

功能动作控制台 UI 入口REST API 端点Server SDK 方法 (agentbase-node-sdk@2.12.0)所需 RBAC / API Key Scope跨模块关联依赖
提交知识蒸馏任务演化 → 手动蒸馏 → 提交POST /v1/memory/memories/distillationsmemory.submitDistillationmemories.write使用 模型路由 与 配置中心 中的实际配置
查询蒸馏任务列表与详情演化 → 蒸馏任务列表GET /v1/memory/memories/distillations、GET .../{distillationId}memory.listDistillations / memory.getDistillationmemories.read关联 记忆审计 与 记忆链路追踪
重放失败蒸馏任务蒸馏任务行尾 重放(Replay)POST /v1/memory/memories/distillations/{distillationId}/replaymemory.replayDistillationmemories.write 和知识管理权限仅重放 failed 或 dead 终态的任务;沿用原运行快照
列表与语义搜索经验(Experiences)演化 → 经验 列表与搜索框GET /v1/memory/memories/experiences、POST .../experiences/searchmemory.listExperiences / memory.searchExperiencesmemories.read为智能体工作台与 recall 提供情境经验
列表与语义搜索技能(Skills)演化 → 技能 列表与搜索框GET /v1/memory/memories/skills、POST .../skills/searchmemory.listSkills / memory.searchSkillsmemories.read为智能体工作台与 recall 提供多步 SOP
追溯经验/技能的 L0 原始来源展开经验或技能详情 → 来源证据GET /v1/memory/memories/experiences/{knowledgeId}/sources、/skills/{knowledgeId}/sourcesmemory.listExperienceSources / memory.listSkillSourcesmemories.read关联 多层记忆划分 中的 L0 原始证据层
更新或遗忘(删除)经验/技能经验/技能行尾 编辑 / 遗忘 按钮PATCH /v1/memory/memories/knowledge/{knowledgeId}、DELETE .../knowledge/{knowledgeId}(或 /experiences/{id}、/skills/{id})memory.updateKnowledge / memory.forgetKnowledgememories.write / memories.delete遗忘标记使知识不再参与召回,物理清理由后续任务处理

功能详解与操作指南

步骤一:在控制台按归属范围提交执行证据蒸馏并检索产出

  1. 登录 Agentbase 控制台,进入目标项目,在左侧导航栏单击 记忆 并切换至 演化页签。提交蒸馏前检查 evolution.enabled 已启用;平台默认值为 false,实际配置可能不同。

  2. 在顶部 归属范围(Scope) 配置栏选择目标作用域:

    • 范围(scope):支持 user(个人级)、agent(智能体级,须同时填写 agentId 如 enterprise-support-agent)与 project(项目全局共享级);

    • 用户 ID(userId):输入 user_zhangwei_001(或 user_lina_002),单击 应用范围。

  3. 单击 手动蒸馏,在弹窗的对话证据中逐行填写内容,可使用 user:、assistant:、system:、tool: 保留角色;选择默认流程或已发布的自定义流程,单击 确认。

  4. 提交后,在下方 蒸馏任务列表 中可实时查看蒸馏作业(如 dst_3e5b09f456c5d5c332507ec1dbe3eb6d 与 dst_adc2cfda21c940fb5d5e4a3263ae56f9)的执行状态(queued -> running -> succeeded)及产出统计(created、merged、skipped、blocked)。

  5. 切换到下方的 经验 或 技能 页签,按需要查询结果并查看其详情和来源。

步骤二:通过 REST API 提交并查询含 toolEvents 的蒸馏任务

在实际智能体运行时(Agent Runtime)中,后端服务可在工单结单或任务执行成功后,将完整对话 messages 与结构化工具轨迹 toolEvents 一并提交至 POST /v1/memory/memories/distillations:

每个新任务都要设置独立的 DISTILLATION_IDEMPOTENCY_KEY;仅重试同一次提交时沿用原键和相同请求内容,避免复用旧任务或发生冲突。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY for the target environment}"
  : "${DISTILLATION_IDEMPOTENCY_KEY:?Set a unique key for this new task}"

  # 1. 提交携带 messages 与 toolEvents 的知识蒸馏任务 (mode="wait",最长等待 20s 返回终态)
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories/distillations" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "Idempotency-Key: ${DISTILLATION_IDEMPOTENCY_KEY}" \
    -H "Content-Type: application/json" \
    --data '{
      "userId": "user_zhangwei_001",
      "scope": "user",
      "sessionId": "sess_ticket_TK_20261022_001",
      "runId": "run_tk_20261022_001",
      "mode": "wait",
      "messages": [
        {
          "role": "user",
          "content": "生产告警:enterprise-ai-hub-210 项目在批量构建 1024 维 HNSW 向量索引时报错 OB_ALLOCATE_MEMORY_FAILED (-4013),请排查并恢复。"
        },
        {
          "role": "assistant",
          "content": "这是合成示例:已记录并检查测试工单,处理结果已记录。真实内存错误需结合数据库版本、日志和资源指标排查。"
        }
      ],
      "toolEvents": [
        {
          "eventId": "event-ob-sql-1",
          "name": "check_ticket",
          "status": "succeeded",
          "arguments": {
            "ticketId": "TK-20261022-001"
          },
          "result": {
            "status": "open"
          }
        },
        {
          "eventId": "event-ob-parameter-2",
          "name": "record_ticket",
          "status": "succeeded",
          "arguments": {
            "ticketId": "TK-20261022-001"
          },
          "result": {
            "status": "resolved"
          }
        }
      ]
    }'
)

从提交响应中取得 distillationId,设置为 DISTILLATION_ID。确认相同用户与范围后,单独查询任务状态与产出。

(
  set +x
  set -o pipefail
  : "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set project ID}"
  : "${APPBASE_API_KEY:?Set API key}"
  : "${DISTILLATION_ID:?Set distillation ID from the submitted task}"
  builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS "${APPBASE_ENDPOINT%/}/memory/memories/distillations/${DISTILLATION_ID}?scope=user&userId=user_zhangwei_001" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" | jq .
)

仅确认任务处于 failed 或 dead 终态、需要重放且具备知识管理权限时,单独执行下列命令。若响应丢失或结果未知,请先查询任务状态并核实执行情况,不要盲目重试;重放接口不提供幂等键保障。

(
  set +x
  set -o pipefail
  : "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set project ID}"
  : "${APPBASE_API_KEY:?Set API key}"
  : "${DISTILLATION_ID:?Set distillation ID from the submitted task}"
  builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT%/}/memory/memories/distillations/${DISTILLATION_ID}/replay?scope=user&userId=user_zhangwei_001" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "Content-Type: application/json" \
    --data '{}' | jq .
)

重放不会采用新流水线或模型配置;需要使用新配置时应另行提交任务。

步骤三:使用 Server SDK 检索经验与技能、追溯 sources 与淘汰过时知识

在 Node.js 业务后端中,可通过 agentbase-node-sdk@2.12.0 分别调用 searchExperiences、searchSkills、listSkillSources 与 forgetKnowledge,完成从知识检索、来源审计到淘汰清理的完整闭环:

运行前将 <APPBASE_ENDPOINT_WITH_V1> 和 <APPBASE_PROJECT_ID> 替换为已确认的目标 API 地址和项目 ID。未替换时 SDK 会拒绝无效地址,不会发送请求。

// 使用官方服务端 SDK: agentbase-node-sdk@2.12.0
import { Client, Memory } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
    .setProject('<APPBASE_PROJECT_ID>')
    .setKey(process.env.APPBASE_API_KEY);

const memory = new Memory(client);

// 1. 语义搜索匹配的排障经验 (POST /v1/memory/memories/experiences/search)
const experiences = await memory.searchExperiences({
    userId: 'user_zhangwei_001',
    scope: 'user',
    query: 'OceanBase 向量索引构建报 -4013 内存不足如何解决',
    limit: 5
});

for (const item of experiences.items || []) {
    const exp = item.knowledge;
    console.log('[Experience]', exp.knowledgeId, exp.title, 'score:', item.score);
}

// 2. 语义搜索匹配的标准 SOP 技能 (POST /v1/memory/memories/skills/search)
const skills = await memory.searchSkills({
    userId: 'user_zhangwei_001',
    scope: 'user',
    query: '测试工单排查与处理记录',
    limit: 5
});

if (skills.items?.length > 0) {
    const topSkill = skills.items[0].knowledge;
    console.log('[Skill SOP]', topSkill.knowledgeId, topSkill.title, 'steps:', topSkill.skill?.procedure?.length);

    // 3. 追溯支撑该技能的 L0 原始会话与工具轨迹来源 (GET .../skills/{knowledgeId}/sources)
    const sources = await memory.listSkillSources({
        knowledgeId: topSkill.knowledgeId,
        userId: 'user_zhangwei_001',
        scope: 'user',
        limit: 10
    });
    console.log('关联的不可变 L0 Source 数量:', sources.total);
}

// 4. 当某项旧经验因系统架构升级不再适用时,调用遗忘接口处理旧经验 (DELETE)
async function retireObsoleteKnowledge(knowledge) {
    await memory.forgetKnowledge({
        knowledgeId: knowledge.knowledgeId,
        expectedVersion: knowledge.version,
        userId: 'user_zhangwei_001',
        scope: 'user',
        reason: 'OceanBase 集群已升级至自动弹性向量内存管理,旧手动阈值经验退役'
    });
}

常见问题与排障(FAQ)

遗忘操作使用已读取知识对象的 version;遇到版本冲突时重新读取并确认后再操作。

1. 为什么在配置“经验与技能 Pipeline”时,不能同时关闭 skill_extraction 和 experience_extraction 两个节点?

2. 提交蒸馏请求时使用 mode: "wait",如果返回了 HTTP 202 且带有 "waitTimedOut": true,任务是否失败了?需要重新提交吗?

3. 为什么某条经验(Experience)已经完成了抽取,但在激活或审批时提示 skill_dependency_not_approved?


相关文档