Docs
文档目录

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

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

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


功能概述

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

  1. 企业知识库检索集成与可溯源出处展示(Knowledge Search):

    • 开启 knowledge_search_enabled: true 后,支持在当前项目内绑定 1~100 个已就绪的知识库(如 knowledge_base_ids: ["kb_enterprise_support"])。

    • 智能体在推理过程中会根据用户问题自主决定是否调用内置的 knowledge_retrieve 检索工具(支持 hybrid 混合检索、vector 向量检索与 fulltext 全文检索,默认 hybrid)。

    • 可验证的知识来源(Knowledge Sources):控制台在每轮回答下方自动渲染可展开的知识来源标签与文档切片预览;业务应用则可通过读取持久化消息中的 TOOL_RESULT 载荷提取精确的文档引用信息。

  2. 长期记忆集成(Memory,Shared V2 专属):

    • 当项目已初始化并启用 记忆(Memory) 服务后,在智能体工作台开启 memory_enabled: true(并对齐 memory_embedding_model_id: "text-embedding-v3" 与 memory_embedding_dimensions: 1024)。

    • Runtime 在每次 Run 启动准备上下文时,自动按当前请求的 userId(如 user_zhangwei_001)召回该用户的个人画像(Profile)与高相关多层事实记忆(L0~L3),并在对话过程中异步沉淀有价值的长期事实。即使为同一 userId 新建一个全新的 Thread,智能体依然记得该用户的历史技术栈偏好。

  3. PowerContext 持久上下文与跨会话任务交接集成:

    • 当项目已初始化 上下文(PowerContext) 服务后,开启 powercontext_enabled: true 即可赋予智能体持久上下文召回、精确来源引用核对、用户显式触发的跨会话任务交接(Task Handoff)以及从排障证据中生成经验/技能候选(Experience / Skill Candidates)的能力。

  4. Memory 与 PowerContext 严格二选一互斥契约:

    • 在任何一份有效的 Runtime 配置中,memory_enabled 与 powercontext_enabled 严格互斥(最多只能开启其中一个,也可同时关闭);而 knowledge_search_enabled 知识库检索开关完全独立,可与 Memory 或 PowerContext 任意组合使用。


核心概念与架构

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

挂载企业知识库检索、长期记忆与 PowerContext 协同:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

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

在实际工程中,开发者常将“会话历史(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);
2. 已上传文档并完成异步摄取(文档状态为 ready)。
knowledge_search_enabled: true
knowledge_base_ids: ["kb_enterprise_support"]
仅需 agent-runtime.project(Runtime 内部通过服务端受托凭据检索已绑定的知识库,无需给调用 Key 额外赋 knowledgebases.read)模型只能检索 knowledge_base_ids 白名单内且属于当前项目的知识库;提示词无法越权访问未绑定的其他知识库。
长期记忆(Memory)1. 项目必须为 OceanBase Shared V2 表模式;
2. 已在 记忆(/memory) 完成初始化且状态为 active(锁定 text-embedding-v3 1024 维)。
memory_enabled: true
powercontext_enabled: false
memory_embedding_model_id: "text-embedding-v3"
memory_embedding_dimensions: 1024
仅需 agent-runtime.project(直接调用 /v1/memory/* 公开接口管理记忆时才需 memory.read / memory.write)记忆严格按请求传入的 userId 隔离召回;仅打开 memory_enabled 开关不会替尚未初始化的项目自动创建 Memory 表组。
持久上下文(PowerContext)已在 上下文(/powercontext) 完成项目级 PowerContext 服务初始化。powercontext_enabled: true
memory_enabled: false
仅需 agent-runtime.project与 memory_enabled 严格二选一互斥;任务交接(Handoff)与技能候选审批均需用户明确指令触发。

功能详解与操作指南

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

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

  1. 确认项目知识库 kb_enterprise_support(企业智能客服与技术支持知识库)下的 4 篇核心技术文档(含《OceanBase分布式事务与向量索引排障指南.md》《AI网关模型路由与限流计费规范.md》等)均已处于 ready 状态(详见知识库概览)。

  2. 进入 /console/project-default-enterprise-ai-hub-210/agent-runtime,在右侧配置面板中找到 知识库检索(Knowledge Search) 区域:

    • 打开 启用知识库检索 开关(对应 knowledge_search_enabled: true);

    • 在知识库多选列表中勾选 kb_enterprise_support(企业智能客服与技术支持知识库)(最多可选择 100 个不同知识库;若未来暂时关闭检索开关,已勾选的知识库列表会保留在配置中,方便下次一键重新开启);

    • 等待配置面板右上角显示 所有更改已保存。

  3. 在中间对话框新建会话并输入问题:

    当 OceanBase 向量索引构建报 4013 错误时,核心根因是什么?应该调整哪个租户级参数?
  4. 核验检索步骤与知识来源卡片:

    • 展开回答上方的 执行过程,可看到智能体发起了 knowledge_retrieve 工具调用(默认采用 hybrid 向量+全文混合检索模式,结合绑定的词库自动将 4013 扩展为 OB_ALLOCATE_MEMORY_FAILED);

    • 在模型生成的回答正文下方,单击展开 知识来源(Knowledge Sources) 标签栏,即可查看本轮检索命中的具体文档名称(《OceanBase分布式事务与向量索引排障指南.md》)、切片预览文本与定位元数据。

    准确理解「知识来源」:回答下方展示的“知识来源”是本轮 Run 中 knowledge_retrieve 实际召回并送入模型上下文的参考片段集合,用于可追溯性核验,并不代表模型在最终回答里逐字引用了每一个召回片段。

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 集成:

  1. 确认项目 Memory 已就绪:进入控制台左侧导航 记忆(/memory),确认项目 enterprise-ai-hub-210 的记忆服务状态为 可用(Active),且绑定的 Embedding 模型为 dashscope-prod 下的 text-embedding-v3(1024 维)(详见记忆概览与启用)。

  2. 在智能体工作台中开启 Memory(同时关闭 PowerContext): 在工作台右侧配置栏中打开 长期记忆(Memory) 开关(控制台会自动将互斥的 PowerContext 切换为关闭),或通过 API 配置:

    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. 验证跨 Thread 记忆延续:

    • 在 会话 A(thd_session_a) 中,以 "userId": "user_zhangwei_001" 发送消息:"我负责的核心交易集群运行在 OceanBase 4.3 Shared V2 模式下,租户规格为 32C128G,请帮我记住这个环境信息。"

    • 随后为同一个 "userId": "user_zhangwei_001" 创建一个全新的会话 B(thd_session_b),直接提问:"基于我负责的集群租户规格,如果将 ob_vector_memory_limit_percentage 设为 30%,大约会分配多少 GB 的向量内存?"

    • Runtime 在会话 B 的 Run 启动时自动从 Memory 服务召回 user_zhangwei_001 的用户画像与 32C128G 环境事实,并结合 kb_enterprise_support 的计算规则直接算出约 38.4 GB,无需用户在每个新会话中重复交代背景。

    • 若此时以另一位工程师 "userId": "user_lina_002" 创建会话并询问同样的问题,由于 userId 严格物理隔离,智能体不会读取到张伟的任何集群信息。


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

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

  1. 切换配置为 PowerContext 模式(powercontext_enabled: true):

    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"]
      }'
  2. 显式触发跨会话任务交接(Task Handoff)与新会话续接:

    • 重要机制说明:普通的 Run 结束时不会自动生成任务交接记录;任务交接必须由用户在对话中发出明确的交接指令触发。

    • 在当前排障会话中保存交接:当排障进行到一半需要换班或开启新会话时,发送指令:"请整理当前工单 TK-20261022-001 的排障目标、已确认的事实、未完成检查项和下一步计划,并保存一份任务交接记录。" Runtime 会调用内部交接工具结构化保存当前任务状态。

    • 在新会话中恢复并延续任务:创建新 Thread 后,发送指令:"请读取最新的任务交接记录,继续完成未排查的检查项。" 智能体即会拉取上一会话保存的交接清单与关联引用来源,无缝接续未完成工作。

    • 经验与技能候选治理:在 PowerContext 模式下,智能体还可按用户要求从已验证的排障证据中生成经验(Experience)或技能(Skill)候选,并在用户明确指示批准或拒绝时更新候选状态(注意:生成候选不等于自动审批生效,读取技能说明也不等于自动获得工具执行授权)。


常见问题与排障

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

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

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

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

  1. 检查模型是否发起了检索调用:展开该轮回答上方的 执行过程(或查看 GET /runs/{runId}/messages 中是否存在 tool_name: "knowledge_retrieve" 的 TOOL_CALL)。对于纯寒暄(如 “你好”)或常识性问题,模型可能判断无需检索而直接作答。若希望强制检索,可在 system_prompt 中明确要求“回答任何产品与技术问题前必须先调用 knowledge_retrieve 检索知识库”。

  2. 检查知识库文档状态与范围:确认勾选的知识库(如 kb_enterprise_support)中文档状态均为 ready(而非 uploaded 或 failed),且检索返回了非空切片(chunks 数组不为空)。

  3. 区分 Runtime 内部检索与知识库公共接口:Runtime 的内置 knowledge_retrieve 使用知识库的基础检索结果(hybrid / vector / fulltext),不等于自动调用知识库公共接口上的全部独立高阶图谱探索接口。

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

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

  1. 当前项目是否运行在 OceanBase Shared V2 表存储模式下(JsonTable 项目不支持 Memory);

  2. 前往左侧导航 记忆(/memory) 页面,确认已完成首次初始化且顶部状态显示为 可用(Active);

  3. 确认 PATCH /config 中填写的 memory_embedding_model_id(如 "text-embedding-v3")和 memory_embedding_dimensions(如 1024)与项目 Memory 实际初始化的向量模型及维度完全相容。


相关文档