挂载企业知识库检索、长期记忆与 PowerContext 协同
本手册对应 Agentbase v2.10.0(控制台同版本)。
纯粹的大模型对话仅依赖模型预训练参数,既无法回答企业私有的技术白皮书与客服 SOP 规范,也无法在新开启的会话(Thread)中记住老客户的架构环境与历史排障偏好。Agentbase 智能体工作台(Agent Runtime) 原生打通了 企业知识库检索(Knowledge Search)、长期记忆(Memory) 与 持久上下文(PowerContext) 三大上下文增强引擎,让智能体在每一次 ReAct 循环中既能“查准企业权威文档并展示可溯源引用”,又能“跨会话延续用户个性化记忆或交接复杂任务”。
功能概述
在标杆项目 企业智能客服与知识中台(enterprise-ai-hub-210,OceanBase Shared V2 模式)中,智能体工作台围绕“领域知识注入”与“跨会话状态延续”提供三大可组合的集成能力及严格的边界治理:
- 企业知识库检索集成与可溯源出处展示(Knowledge Search):
- 开启
knowledge_search_enabled: true后,支持在当前项目内绑定 1~100 个已就绪的知识库(如knowledge_base_ids: ["kb_enterprise_support"])。 - 智能体在推理过程中会根据用户问题自主决定是否调用内置的
knowledge_retrieve检索工具(支持hybrid混合检索、vector向量检索与fulltext全文检索,默认hybrid)。 - 可验证的知识来源(Knowledge Sources):控制台在每轮回答下方自动渲染可展开的知识来源标签与文档切片预览;业务应用则可通过读取持久化消息中的
TOOL_RESULT载荷提取精确的文档引用信息。
- 开启
- **长期记忆集成(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,智能体依然记得该用户的历史技术栈偏好。
- 当项目已初始化并启用 记忆(Memory) 服务后,在智能体工作台开启
- PowerContext 持久上下文与跨会话任务交接集成:
- 当项目已初始化 上下文(PowerContext) 服务后,开启
powercontext_enabled: true即可赋予智能体持久上下文召回、精确来源引用核对、用户显式触发的跨会话任务交接(Task Handoff)以及从排障证据中生成经验/技能候选(Experience / Skill Candidates)的能力。
- 当项目已初始化 上下文(PowerContext) 服务后,开启
- Memory 与 PowerContext 严格二选一互斥契约:
- 在任何一份有效的 Runtime 配置中,**
memory_enabled与powercontext_enabled严格互斥(最多只能开启其中一个,也可同时关闭)**;而knowledge_search_enabled知识库检索开关完全独立,可与 Memory 或 PowerContext 任意组合使用。
- 在任何一份有效的 Runtime 配置中,**
核心概念与架构
知识库检索、长期记忆与 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 并验证引用卡片
- 确认项目知识库
kb_enterprise_support(企业智能客服与技术支持知识库)下的 4 篇核心技术文档(含《OceanBase分布式事务与向量索引排障指南.md》《AI网关模型路由与限流计费规范.md》等)均已处于 **ready** 状态(详见知识库概览)。 - 进入
/console/project-default-enterprise-ai-hub-210/agent-runtime,在右侧配置面板中找到 知识库检索(Knowledge Search) 区域: - 打开 启用知识库检索 开关(对应
knowledge_search_enabled: true); - 在知识库多选列表中勾选 **
kb_enterprise_support(企业智能客服与技术支持知识库)**(最多可选择 100 个不同知识库;若未来暂时关闭检索开关,已勾选的知识库列表会保留在配置中,方便下次一键重新开启); - 等待配置面板右上角显示 所有更改已保存。
- 打开 启用知识库检索 开关(对应
- 在中间对话框新建会话并输入问题:
当 OceanBase 向量索引构建报 4013 错误时,核心根因是什么?应该调整哪个租户级参数?- 核验检索步骤与知识来源卡片:
- 展开回答上方的 执行过程,可看到智能体发起了
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 集成:
- 确认项目 Memory 已就绪:进入控制台左侧导航 **记忆(
/memory)**,确认项目enterprise-ai-hub-210的记忆服务状态为 **可用(Active)**,且绑定的 Embedding 模型为dashscope-prod下的text-embedding-v3(1024维)(详见记忆概览与启用)。 - 在智能体工作台中开启 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"]
}'- 验证跨 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严格物理隔离,智能体不会读取到张伟的任何集群信息。
- 在 **会话 A(
3. 启用 PowerContext 实现持久上下文与跨会话任务交接(Task Handoff)
若业务场景侧重于长周期复杂任务的跨会话显式交接(Task Handoff)、精确原始来源引用核验以及从真实任务轨迹中提炼经验/技能候选(Experience / Skill Candidates),可在完成项目 **上下文(/powercontext) 初始化后切换为 PowerContext 模式**:
- **切换配置为 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"]
}'- 显式触发跨会话任务交接(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 持久上下文服务属于两套职责重叠但底层存储与工具契约不同的长期上下文体系,因此在同一份运行配置中严格二选一互斥。
- 在 Console 界面上,打开其中一个开关会自动关闭另一个;
- 通过
PATCH /v1/agent-runtime/project/config调用时,若要从 Memory 切换到 PowerContext,必须在同一个 JSON 请求体中显式传入{"powercontext_enabled": true, "memory_enabled": false}。
Q2:已经开启了 knowledge_search_enabled: true 并勾选了知识库,为什么某次对话中回答下方没有显示「知识来源」?
原因与排查步骤: 请按以下三步排查:
- 检查模型是否发起了检索调用:展开该轮回答上方的 执行过程(或查看
GET /runs/{runId}/messages中是否存在tool_name: "knowledge_retrieve"的TOOL_CALL)。对于纯寒暄(如“你好”)或常识性问题,模型可能判断无需检索而直接作答。若希望强制检索,可在system_prompt中明确要求“回答任何产品与技术问题前必须先调用knowledge_retrieve检索知识库”。 - 检查知识库文档状态与范围:确认勾选的知识库(如
kb_enterprise_support)中文档状态均为ready(而非uploaded或failed),且检索返回了非空切片(chunks数组不为空)。 - 区分 Runtime 内部检索与知识库公共接口:Runtime 的内置
knowledge_retrieve使用知识库的基础检索结果(hybrid/vector/fulltext),不等于自动调用知识库公共接口上的全部独立高阶图谱探索接口。
Q3:为什么开启 memory_enabled: true 保存配置时报错,提示 Memory 服务未就绪?
原因与排查步骤: 打开智能体工作台的 memory_enabled 开关只是建立绑定关系,不会替项目自动初始化 Memory 服务。请先检查:
- 当前项目是否运行在 OceanBase **
Shared V2** 表存储模式下(JsonTable项目不支持 Memory); - 前往左侧导航 **记忆(
/memory) 页面,确认已完成首次初始化且顶部状态显示为可用(Active)**; - 确认
PATCH /config中填写的memory_embedding_model_id(如"text-embedding-v3")和memory_embedding_dimensions(如1024)与项目 Memory 实际初始化的向量模型及维度完全相容。