AgentbaseDocs
文档目录

挂载企业知识库检索、长期记忆与 PowerContext 协同

本手册对应 Agentbase v2.10.0(控制台同版本)。

纯粹的大模型对话仅依赖模型预训练参数,既无法回答企业私有的技术白皮书与客服 SOP 规范,也无法在新开启的会话(Thread)中记住老客户的架构环境与历史排障偏好。Agentbase 智能体工作台(Agent Runtime) 原生打通了 企业知识库检索(Knowledge Search)、长期记忆(Memory) 与 持久上下文(PowerContext) 三大上下文增强引擎,让智能体在每一次 ReAct 循环中既能“查准企业权威文档并展示可溯源引用”,又能“跨会话延续用户个性化记忆或交接复杂任务”。


功能概述

在标杆项目 企业智能客服与知识中台(enterprise-ai-hub-210,OceanBase Shared V2 模式)中,智能体工作台围绕“领域知识注入”与“跨会话状态延续”提供三大可组合的集成能力及严格的边界治理:


核心概念与架构

知识库检索、长期记忆与 PowerContext 协同架构图

flowchart TB
    subgraph ConfigGuard["1. 运行配置开关与互斥守卫 (PATCH /v1/agent-runtime/project/config)"]
        KBConfig["知识库检索开关 (独立可组合)\nknowledge_search_enabled = true\nknowledge_base_ids = ['kb_enterprise_support'] (1..100 个)"]
        MutexGuard{"长期上下文二选一互斥守卫\n(不可同时为 true)"}
        MemMode["模式 A:长期记忆 (Memory)\nmemory_enabled = true\npowercontext_enabled = false\n(text-embedding-v3 / 1024 维)"]
        PCMode["模式 B:持久上下文 (PowerContext)\npowercontext_enabled = true\nmemory_enabled = false"]
        OffMode["模式 C:纯会话历史模式\n两者均为 false"]
    end

    subgraph ContextAssembly["2. 单次 Run 启动与 ReAct 推理期上下文组装 (绑定 userId: user_zhangwei_001)"]
        ThreadHist["短期会话层:当前 Thread 历史消息\n+ 早期轮次自动精简摘要 (Context Compaction)"]
        MemRecall["长期记忆召回层 (若开启 Memory):\n按 userId 召回用户画像 (Profile) + 相关事实记忆"]
        PCRecall["持久上下文层 (若开启 PowerContext):\n持久上下文准备 + 按需读取最新任务交接 (Handoff) / 来源"]
        KBTool["按需证据检索层 (若开启 Knowledge Search):\n模型自主调用 knowledge_retrieve (hybrid / vector / fulltext)"]
    end

    subgraph OutputAndPersist["3. 回答生成、引用溯源与跨会话沉淀"]
        Answer["模型 (qwen-plus) 基于检索片段与用户画像生成接地回答"]
        Citations["持久化 TOOL_RESULT 消息\nConsole 渲染「知识来源」卡片 / 业务应用解析引用"]
        PostRun["跨会话沉淀:\n• Memory: 异步提取事实与更新画像\n• PowerContext: 显式保存记忆、任务交接记录或生成技能候选"]
    end

    KBConfig --> KBTool
    MutexGuard --> MemMode --> MemRecall
    MutexGuard --> PCMode --> PCRecall
    MutexGuard --> OffMode --> ThreadHist
    ThreadHist & MemRecall & PCRecall & KBTool --> Answer
    Answer --> Citations & PostRun

四类上下文机制的核心职责与边界对比表

在实际工程中,开发者常将“会话历史(Thread History)”、“上下文精简(Context Compaction)”、“长期记忆(Memory / PowerContext)”与“企业知识库(Knowledge Base)”混为一谈。下表清晰界定了四者在 Agent Runtime 中的分工与生命周期:

维度会话历史(Thread History)自动上下文精简(Context Compaction)长期记忆 / 持久上下文(Memory / PowerContext)企业知识库检索(Knowledge Search)
解决的核心问题“这段对话刚才说了什么?”(维持当前单个会话窗口内的前后指代连贯)“当前会话太长塞不进模型窗口怎么办?”(压缩当前会话早期轮次以控制输入 Token)“这个用户在过去的会话中留下了什么个人背景、偏好或未完任务?”“企业制度、产品架构白皮书和排障手册里是怎么规定的?”
数据隔离作用域单项目 + 单 userId + **单个 thread_id**单项目 + 单 userId + **单个 thread_id**单项目 + **跨所有 thread_id(按 userId 共享)**项目级共享(限于 knowledge_base_ids 勾选的 1~100 个知识库)
新建或归档 Thread 时的影响新建 Thread 开启空白会话历史;归档 Thread 隐藏该段会话仅随所属 Thread 存在,新 Thread 从零开始计算窗口预算完全保留且跨会话生效:归档旧 Thread 绝不会删除已提取的长期记忆或任务交接完全独立:知识库文档与切片不受任何会话创建或归档影响
触发方式每次 Run 自动按序读取当单次 Run 输入逼近 context_window_tokens - reserved_output_tokens 时自动触发Run 开始时自动召回画像/上下文,或由模型在推理中按需调用记忆/交接工具模型在 ReAct 循环中根据问题自主决定是否调用 knowledge_retrieve

角色、入口与关联关系

前置依赖、权限 Scope 与配置映射矩阵

集成能力必须满足的项目前置条件工作台 Config 关键字段调用方 API Key 所需 Scope权限与安全边界说明
企业知识库检索(Knowledge Search)1. 已在 **知识库(/knowledge-base)** 创建知识库(如 kb_enterprise_support);<br/>2. 已上传文档并完成异步摄取(文档状态为 ready)。knowledge_search_enabled: true<br/>knowledge_base_ids: ["kb_enterprise_support"]仅需 **agent-runtime.project**(Runtime 内部通过服务端受托凭据检索已绑定的知识库,无需给调用 Key 额外赋 knowledgebases.read)模型只能检索 knowledge_base_ids 白名单内且属于当前项目的知识库;提示词无法越权访问未绑定的其他知识库。
长期记忆(Memory)1. 项目必须为 OceanBase **Shared V2 表模式;<br/>2. 已在 记忆(/memory)** 完成初始化且状态为 active(锁定 text-embedding-v3 1024 维)。memory_enabled: true<br/>powercontext_enabled: false<br/>memory_embedding_model_id: "text-embedding-v3"<br/>memory_embedding_dimensions: 1024仅需 **agent-runtime.project**(直接调用 /v1/memory/* 公开接口管理记忆时才需 memory.read / memory.write)记忆严格按请求传入的 userId 隔离召回;仅打开 memory_enabled 开关不会替尚未初始化的项目自动创建 Memory 表组。
持久上下文(PowerContext)已在 **上下文(/powercontext)** 完成项目级 PowerContext 服务初始化。powercontext_enabled: true<br/>memory_enabled: false仅需 **agent-runtime.project**与 memory_enabled 严格二选一互斥;任务交接(Handoff)与技能候选审批均需用户明确指令触发。

功能详解与操作指南

1. 挂载企业知识库(kb_enterprise_support)并验证可溯源问答

1. 在 Console 工作台中开启 Knowledge Search 并验证引用卡片

   当 OceanBase 向量索引构建报 4013 错误时,核心根因是什么?应该调整哪个租户级参数?

2. 通过服务端 API 开启知识库检索并从 TOOL_RESULT 解析引用来源

需要注意:**SSE 流式文本增量事件(TEXT_MESSAGE_CONTENT)仅传输回答文字,不包含完整的结构化来源清单**。企业前端若需在回答下方渲染可点击的引用文档卡片,应在 Run 完成后(或收到 TOOL_CALL_RESULT 通知后)读取持久化消息接口 GET /runs/{runId}/messages 中的 TOOL_CALL 与 TOOL_RESULT 记录:

# 1. 更新项目 Runtime 配置,开启知识库检索并绑定 kb_enterprise_support
curl -fsSL -X PATCH "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_search_enabled": true,
    "knowledge_base_ids": [
      "kb_enterprise_support"
    ]
  }'

# 2. 在 Run 完成后拉取本次运行的全量持久化消息(含 TOOL_CALL 与 TOOL_RESULT)
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/messages?userId=user_zhangwei_001&after=0&limit=100" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

**响应中 TOOL_CALL 与 TOOL_RESULT 的配对结构示例**:

[
  {
    "message_id": "msg_usr_101",
    "thread_id": "thd_01j8x9k2m4n6p8q0r2s4t6u8v0",
    "run_id": "run_01j8x9p1q2r3s4t5u6v7w8x9y0",
    "message_seq": 3,
    "message_type": "USER",
    "payload": "当 OceanBase 向量索引构建报 4013 错误时,应该调整哪个租户级参数?",
    "tool_call_id": null,
    "created_at": "2026-10-22T09:20:00Z"
  },
  {
    "message_id": "msg_tc_102",
    "thread_id": "thd_01j8x9k2m4n6p8q0r2s4t6u8v0",
    "run_id": "run_01j8x9p1q2r3s4t5u6v7w8x9y0",
    "message_seq": 4,
    "message_type": "TOOL_CALL",
    "payload": {
      "call_id": "call_kb_8801",
      "tool_name": "knowledge_retrieve",
      "source": "SERVER",
      "arguments": {
        "query": "OceanBase 向量索引 4013 OB_ALLOCATE_MEMORY_FAILED 租户参数",
        "search_mode": "hybrid",
        "knowledge_base_ids": ["kb_enterprise_support"]
      }
    },
    "tool_call_id": "call_kb_8801",
    "created_at": "2026-10-22T09:20:02Z"
  },
  {
    "message_id": "msg_tr_103",
    "thread_id": "thd_01j8x9k2m4n6p8q0r2s4t6u8v0",
    "run_id": "run_01j8x9p1q2r3s4t5u6v7w8x9y0",
    "message_seq": 5,
    "message_type": "TOOL_RESULT",
    "payload": {
      "call_id": "call_kb_8801",
      "tool_name": "knowledge_retrieve",
      "status": "succeeded",
      "chunks": [
        {
          "knowledge_base_id": "kb_enterprise_support",
          "document_id": "doc_ob_troubleshooting",
          "document_title": "OceanBase分布式事务与向量索引排障指南.md",
          "chunk_id": "chk_ob_4013_01",
          "score": 0.918,
          "content": "错误码 -4013 (OB_ALLOCATE_MEMORY_FAILED):在构建 HNSW 向量索引时若触发 4013 报错,表明租户向量内存区配额不足。请将租户参数 ob_vector_memory_limit_percentage 从默认值调高至 30%~40%。"
        }
      ]
    },
    "tool_call_id": "call_kb_8801",
    "created_at": "2026-10-22T09:20:03Z"
  },
  {
    "message_id": "msg_ast_104",
    "thread_id": "thd_01j8x9k2m4n6p8q0r2s4t6u8v0",
    "run_id": "run_01j8x9p1q2r3s4t5u6v7w8x9y0",
    "trace_id": "7f8e9d0c1b2a3f4e5d6c7b8a9f0e1d2c",
    "message_seq": 6,
    "message_type": "ASSISTANT",
    "payload": "根据《OceanBase分布式事务与向量索引排障指南.md》,构建 HNSW 向量索引时报 `-4013`(`OB_ALLOCATE_MEMORY_FAILED`)是因为租户向量内存区配额不足。建议将租户级参数 `ob_vector_memory_limit_percentage` 调高至 **30%~40%**。",
    "tool_call_id": null,
    "created_at": "2026-10-22T09:20:05Z"
  }
]

2. 启用长期记忆(Memory)实现跨会话用户画像与事实召回

当企业希望智能客服在不同工单会话(不同 Thread)之间持续记住 VIP 客户张伟(user_zhangwei_001)的生产集群规格与排障习惯时,可启用 Memory 集成:

   curl -fsSL -X PATCH "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "memory_enabled": true,
       "powercontext_enabled": false,
       "memory_embedding_model_id": "text-embedding-v3",
       "memory_embedding_dimensions": 1024,
       "knowledge_search_enabled": true,
       "knowledge_base_ids": ["kb_enterprise_support"]
     }'

3. 启用 PowerContext 实现持久上下文与跨会话任务交接(Task Handoff)

若业务场景侧重于长周期复杂任务的跨会话显式交接(Task Handoff)、精确原始来源引用核验以及从真实任务轨迹中提炼经验/技能候选(Experience / Skill Candidates),可在完成项目 **上下文(/powercontext) 初始化后切换为 PowerContext 模式**:

   curl -fsSL -X PATCH "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "powercontext_enabled": true,
       "memory_enabled": false,
       "knowledge_search_enabled": true,
       "knowledge_base_ids": ["kb_enterprise_support"]
     }'

常见问题与排障

Q1:同时将 memory_enabled 和 powercontext_enabled 设为 true 时,为什么接口返回 HTTP 400 INVALID_REQUEST?

原因与排查步骤: 在 Agent Runtime 的架构设计中,独立 Memory 服务与 PowerContext 持久上下文服务属于两套职责重叠但底层存储与工具契约不同的长期上下文体系,因此在同一份运行配置中严格二选一互斥。

Q2:已经开启了 knowledge_search_enabled: true 并勾选了知识库,为什么某次对话中回答下方没有显示「知识来源」?

原因与排查步骤: 请按以下三步排查:

Q3:为什么开启 memory_enabled: true 保存配置时报错,提示 Memory 服务未就绪?

原因与排查步骤: 打开智能体工作台的 memory_enabled 开关只是建立绑定关系,不会替项目自动初始化 Memory 服务。请先检查:


相关文档