Docs
文档目录

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

本页的项目工作台知识库选择说明已对照 2.12.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;控制台最多选择 10 个(如 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 与 memory_embedding_dimensions 必须与该项目已初始化的配置相容)。

    • 启用 Memory 后,新会话在请求的 userId(如 user_zhangwei_001)非空且服务可用时尝试加载用户画像;推理过程中可按需调用 memory_search 检索授权范围内的事实。能否在新 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 的已授权访问项目级共享(限于 knowledge_base_ids 选定的知识库;控制台最多选择 10 个)
新建或归档 Thread 时的影响新建 Thread 开启空白会话历史;归档 Thread 隐藏该段会话仅随所属 Thread 存在,新 Thread 从零开始计算窗口预算已保存的记忆或任务交接可供后续会话使用,实际结果取决于作用域与访问权限完全独立:知识库文档与切片不受任何会话创建或归档影响
触发方式每次 Run 自动按序读取当单次 Run 输入逼近 context_window_tokens - reserved_output_tokens 时自动触发满足条件的新会话尝试加载 Memory 画像;事实通过 memory_search 按需检索,PowerContext 由 powercontext_prepare 等工具按需调用模型在 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(以项目实际初始化的模型与维度为准)。
memory_enabled: true
powercontext_enabled: false
memory_embedding_model_id
memory_embedding_dimensions(按项目已初始化值配置)
仅需 agent-runtime.project(直接调用 /v1/memory/* 时须按操作授予相应权限,例如检索使用 memories.read,创建使用 memories.write,删除使用 memories.delete;其他操作以接口要求为准)访问由项目、主体、记忆作用域和相应权限共同控制;仅打开 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) 区域:

    • 在知识库多选列表中先选择需要检索的知识库(控制台最多选择 10 个);

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

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

  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 记录:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 1. 更新项目 Runtime 配置,开启知识库检索并绑定 kb_enterprise_support
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X PATCH "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_search_enabled": true,
    "knowledge_base_ids": [
      "kb_enterprise_support"
    ]
  }'
)

确认配置更新返回 2xx,且运行完成后,再单独读取本次运行的消息。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 2. 在 Run 完成后拉取本次运行的全量持久化消息(含 TOOL_CALL 与 TOOL_RESULT)
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -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}" \
  --header @-
)

响应中 TOOL_CALL 与 TOOL_RESULT 的配对结构示例: 以下为结构示例。通过消息外层 tool_call_id 配对调用与结果;knowledge_retrieve 输入使用单数 knowledge_base_id,也可由已绑定知识库提供。结果位于 payload.results,id、sourceId、source 和 locator 等来源字段可能缺失,应按实际返回检查;无命中时 results 可为空。

[
  {
    "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",
      "arguments": {
        "query": "OceanBase 向量索引 4013 OB_ALLOCATE_MEMORY_FAILED 租户参数",
        "search_mode": "hybrid",
        "knowledge_base_id": "kb_enterprise_support"
      },
      "side_effect_free": true
    },
    "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": {
      "knowledge_base_id": "kb_enterprise_support",
      "results": [
        {
          "knowledgeBaseId": "kb_enterprise_support",
          "id": "chk_ob_4013_01",
          "sourceId": "doc_ob_troubleshooting",
          "score": 0.918,
          "content": "内存分配失败可能有多种原因,请结合当前数据库版本、错误日志和资源指标排查,并参考对应版本的官方文档。"
        }
      ],
      "total": 1
    },
    "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": "根据提供的排障资料,内存分配失败需结合当前数据库版本、错误日志和资源指标定位;请按对应版本的官方文档评估处理方案。",
    "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),并核对已绑定的向量模型与维度。下方 text-embedding-v3 和 1024 仅为示例,实际调用应替换为当前项目已初始化的值(详见记忆概览与启用)。

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

    (
      set +x
      set -o pipefail
      : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
    builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X PATCH "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
      -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
      --header @- \
      -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),直接提问:"请回顾我负责的集群规格和之前记录的排查需求。"

    • 检查会话 B 的回答和工具调用:如果 user_zhangwei_001 的 32C128G 环境信息已保存且本次成功加载画像或通过 memory_search 检索到,回答可以包含该信息;保存或检索未命中时不能保证回忆成功。

    • 再以另一位工程师 "userId": "user_lina_002" 验证:不应访问未授权的用户私有记忆;项目共享信息仍按其作用域和权限控制。userId 本身不代表物理隔离。


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

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

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

    (
      set +x
      set -o pipefail
      : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
    builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X PATCH "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
      -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
      --header @- \
      -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),且检索结果中的 results 数组非空。

  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 实际初始化的向量模型及维度完全相容。


相关文档