Docs
文档目录

经验与技能蒸馏演进

功能概述与核心场景

经验与技能演进(Memory Evolution,控制台页签为 演化)是 Agentbase Memory 实现智能体“从实战中自我学习与沉淀知识”的核心能力。在企业级客服与运维排障场景中,智能体每天执行大量多轮对话与工具调用(Tool Execution)。普通记忆(Memories)侧重记录“关于用户的客观事实与偏好”,而经验与技能蒸馏(Distillation)则从真实的任务执行轨迹与排障对话证据中,提炼出跨会话可复用的排障经验(Experience)与标准化操作技能(Skill)。

在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的示例项目 企业智能客服与知识中台(enterprise-ai-hub-210)中,系统通过蒸馏流水线(调用 dashscope-prod 的 qwen-plus 与 text-embedding-v3)完成了两项典型示例蒸馏任务(dst_3e5b09f456c5d5c332507ec1dbe3eb6d 与 dst_adc2cfda21c940fb5d5e4a3263ae56f9):


核心概念与架构

经验与技能蒸馏从对话或工具轨迹中提取候选知识,并进行去重与验证。验证通过不代表一定生效:用户范围还受发布策略约束,未满足条件时可保持 shadow;请以实际状态为准。

Experience 与 Skill 的核心区别与属性表

对比维度经验(Experience)技能(Skill)
定位与形态可复用的情境洞察与避坑经验:记录“在什么场景下遇到什么问题、哪些做法有效、哪些做法会导致失败”。可复用的标准化操作步骤(SOP):记录“为达成某类明确目标,应按什么顺序执行哪些检查、命令或工具调用”。
核心结构化字段知识对象包含 knowledgeId、title、version 与 experience;经验内容包含 situation、decision、action、evidence、outcome、skillItemIds。知识对象包含 knowledgeId、title、version 与 skill;技能内容包含 inputs、applicability、preconditions、procedure、expectedOutcome。
归属范围 (scope)支持 user(用户级)、agent(智能体级,需指定 agentId)、project(项目全局级)。支持 user、agent、project;Agent 级技能要求满足多个有效来源(minIndependentSessionsForAgent)的验证才自动激活。
生命周期状态知识状态包括 candidate、shadow、user-active、agent-active、quarantine、deprecated;user-active 和 agent-active 表示已激活。遗忘通过标记控制召回,不是独立的状态枚举。相同状态集合适用于技能;当经验依赖未批准的 Skill 版本时,会触发 skill_dependency_not_approved 阻塞保护。
检索与溯源接口GET /v1/memory/memories/experiences、POST .../experiences/search、GET .../experiences/{knowledgeId}/sourcesGET /v1/memory/memories/skills、POST .../skills/search、GET .../skills/{knowledgeId}/sources

功能入口与权限矩阵

控制台入口与 API 权限矩阵

控制台入口位于:项目 enterprise-ai-hub-210 → 记忆(Memory) → 演化页签。

功能模块控制台操作入口REST API 路径所需权限与认证要求
提交蒸馏任务手动蒸馏 → 弹窗内 确认POST /v1/memory/memories/distillationsmemories.write
查询与重放蒸馏任务蒸馏任务列表GET /v1/memory/memories/distillations、GET .../{distillationId}、POST .../{distillationId}/replaymemories.read / memories.write
查询与检索经验/技能经验 / 技能 列表与搜索框GET/POST /v1/memory/memories/experiences(/search)、GET/POST /v1/memory/memories/skills(/search)memories.read
查询知识来源证据展开经验/技能详情 → 来源证据GET /v1/memory/memories/experiences/{knowledgeId}/sources、/skills/{knowledgeId}/sourcesmemories.read
版本对比与人工二次确认审核队列 子页签GET/PATCH /v1/memory/memories/knowledge/reviews/{reviewId}、POST .../approve、POST .../reject、POST .../{knowledgeId}/rollback查询需要 memories.read;编辑、批准、拒绝及回滚需要 memories.write 和具备项目管理权限的真实用户主体(Console 会话或管理员 JWT),普通无主体 API Key 不可代替审批人
停止复用(遗忘知识)经验/技能行尾 遗忘 按钮DELETE /v1/memory/memories/experiences/{knowledgeId}、/skills/{knowledgeId}memories.delete

功能详解与操作指南

1. 选择归属范围并提交执行证据蒸馏(POST /v1/memory/memories/distillations)

  1. 登录 Agentbase 控制台,进入项目 企业智能客服与知识中台(enterprise-ai-hub-210),打开 记忆(Memory) → 演化页签。提交前在 记忆 → 配置 → 基础配置 检查并启用 evolution.enabled;平台默认值为 false,实际值可能由环境覆盖。自动蒸馏还需启用 evolution.autoDistillEnabled。

  2. 在页面顶部 归属范围 栏设置知识作用域:

    • 选择范围(user、agent 或 project);

    • 输入目标用户 ID(如 user_zhangwei_001 或 user_lina_002);若选择 agent 范围,还需填写目标 agentId(如 enterprise-support-agent),然后单击 应用范围。

  3. 单击 手动蒸馏,在弹窗中输入已脱敏的客服排障对话或工具调用证据(可使用 user:、assistant:、system:、tool: 前缀标记角色),选择 使用默认流程(或指定已发布的经验与技能流水线),单击 确认。

  4. API 调用与 mode=async | wait 双模式说明: 通过 API 提交蒸馏时,支持两种等待语义:

    • mode: "async":首次持久化入队后返回 HTTP 202;幂等重放可能返回 HTTP 200。响应包含 distillationId 和当前 status(首次入队通常为 queued,重放可返回其他状态);

    • mode: "wait":服务端保持连接等待最长 20 秒。若任务在 20 秒窗口内进入终态(succeeded、partial_failed、failed 或 dead),返回 HTTP 200 及任务标识、状态等回执;使用 distillationId 查询任务详情和实际结果;若超过 20 秒仍处于 queued 或 running,则返回 HTTP 202,并附带 "waitTimedOut": true 与 Location 状态查询地址(等待超时仅结束本次 HTTP 阻塞,绝不会取消已在后台运行的蒸馏任务)。

为每个新任务设置独立的 DISTILLATION_IDEMPOTENCY_KEY;仅重试同一次提交时沿用原键和相同请求内容。

(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${DISTILLATION_IDEMPOTENCY_KEY:?Set a unique key for this new task}"
: "${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}"
# 提交工单 TK-20261022-001 的排障轨迹进行经验与技能蒸馏 (mode=wait)
builtin printf 'X-Appwrite-Key: %s\n' "$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_9f8e7d6c5b4a",
    "mode": "wait",
    "messages": [
      {
        "role": "user",
        "content": "工单 TK-20261022-001:OceanBase Shared V2 表在写入 1024 维向量时报错 OB_ALLOCATE_MEMORY_FAILED (错误码 -4013),如何快速恢复?"
      },
      {
        "role": "tool",
        "content": "{\"tool\":\"check_ticket\",\"output\":\"示例工单已记录,等待排查\"}"
      },
      {
        "role": "assistant",
        "content": "这是一条合成示例:已记录工单,后续应结合数据库版本、日志和资源指标定位原因,并依据对应版本的官方文档评估处理方案。"
      }
    ]
  }' | jq .
)
  1. 在 蒸馏任务列表 中查看任务进度(如标杆环境中的 dst_3e5b09f456c5d5c332507ec1dbe3eb6d 与 dst_adc2cfda21c940fb5d5e4a3263ae56f9),核对产出统计计数:

    • created:全新创建的 Experience 或 Skill 数量;

    • merged:与既有知识语义高度重合、完成证据合并与版本推进的数量;

    • skipped:模型判定对话不含可复用方法论而跳过的数量;

    • blocked:因验证未通过或治理策略拦截而未激活的数量。

2. 激活策略配置(evolution.activation)与知识生命周期

新蒸馏知识是否进入激活状态由验证结果、作用域、来源及配置共同决定;相关配置在 记忆 → 配置 → 基础配置 中的 evolution 命名空间控制:

配置字段路径类型默认值 / 取值范围作用与激活判定逻辑
evolution.enabledbooleanfalse(平台默认值)是否启用项目级经验与技能演进能力;环境可能覆盖默认值,禁用时不能提交蒸馏。
evolution.autoDistillEnabledbooleanfalse是否在常规会话写入时自动触发后台知识蒸馏。
evolution.requireConfirmationbooleanfalse自进化二次确认开关。开启后,所有新增或合并更新的知识候选均保持 shadow 状态并生成待审批确认单(pending),必须由项目管理员人工批准后才进入生效状态。
evolution.allowSingleVerifiedUserActivationbooleantrue在 user 作用域下,是否允许单次已验证成功的任务直接激活个人经验与技能。
evolution.activation.minConfidencenumber0.0 ~ 1.0(如 0.8)模型验证阶段给出的置信度评分必须不低于该阈值,否则留在 shadow 态。
evolution.activation.minIndependentSessionsForAgentinteger正整数(如 2 或 3)针对 agent 作用域知识,按不同的有效来源标识计数;达到配置门槛后才可能从 shadow 晋升为 agent-active。不同来源不保证来自不同 sessionId,同一会话的多次内联提交可能产生多个来源。
evolution.activation.requireVerifiedSuccessbooleantrue是否要求可信来源具备已验证成功的证据。公开提交接口不会将请求体中的声明当作可信验证;请按项目配置与审核结果判断能否激活。

3. 版本对比、人工二次确认与回滚(审核队列)

当开启 自进化二次确认(evolution.requireConfirmation: true) 或管理员主动发起知识修订时:

  1. 在 演化页签中切换到 审核队列 子视图,筛选 pending(待确认)记录。

  2. 展开目标确认单,页面完整展示:

    • 候选正文与结构化步骤、来源证据列表(Provenance,最多展示 100 条并显示总数)、复用范围;

    • 版本 Diff:逐字段对比候选版本(candidateRevisionId)与当前线上生效基线(baseActiveRevisionId)的新增、修改或删减差异。

  3. 在线编辑候选(可选):若管理员发现候选步骤措辞需要微调,可单击 编辑候选,修改内容并填写原因后保存。后台会启动异步编辑验证任务(editJob),重新校验全部来源治理策略并重算向量投影。

  4. 批准(Approve)或拒绝(Reject):

    • 待验证就绪(canApprove: true,无 projections_not_ready、verified_success_required、skill_dependency_not_approved 或 source_set_changed 阻塞原因)后,填写审批原因并单击 批准,候选版本原子切换为当前生效版本;

    • 若单击 拒绝,则丢弃该候选,线上继续保留原生效版本。

  5. 历史版本回滚(Rollback):在 历史版本 列表中选择任一曾被批准且底层来源依然有效的历史修订,填写原因即可安全回滚。

4. 检索经验与技能及溯源查询(agentbase-node-sdk@2.12.0)

应用可通过专用搜索接口或统一召回(recall)在智能体推理前检索匹配的已激活经验与技能(user-active / agent-active),并随时核查其来源证据:

运行前将 <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. 语义检索已激活的排障经验 (Experiences)
const expResults = await memory.searchExperiences({
    userId: 'user_zhangwei_001',
    scope: 'user',
    query: 'OceanBase 向量索引构建内存不足 -4013 排障经验',
    limit: 5
});

// 2. 语义检索已激活的标准化技能 (Skills)
const skillResults = await memory.searchSkills({
    userId: 'user_zhangwei_001',
    scope: 'user',
    query: 'AI 网关 429 限流与故障转移配置步骤',
    limit: 5
});

// 3. 查询某条技能的不可变来源证据链 (Provenance Sources)
if (skillResults.items?.length > 0) {
    const provenance = await memory.listSkillSources({
        knowledgeId: skillResults.items[0].knowledge.knowledgeId,
        userId: 'user_zhangwei_001',
        scope: 'user',
        limit: 20
    });
    console.log('支撑该技能的原始会话来源数:', provenance.total);
}

常见问题与排障(FAQ)

1. 为什么蒸馏任务状态显示 succeeded,但在已激活经验与技能列表中看不到新记录?

2. 在“审核队列”中点击批准时,为什么按钮禁用并提示 projections_not_ready 或 source_set_changed?

3. 关闭“自进化二次确认(evolution.requireConfirmation)”开关后,之前积压的待确认候选会自动发布吗?


相关文档