📚 Agent 集成
概述
知识库的集成并非简单的“让 Agent 自己去搜”，而是通过 上下文管道（Context Pipeline） 机制实现的。系统通过识别消息中的 占位符（Placeholder），在消息发送给 AI 之前自动执行检索、重构和注入操作。
这种设计允许你通过 Prompt 精确控制知识的获取时机、范围和方式，实现高度可定制的 RAG 流程。
核心：占位符系统
在 LLM Chat 的 系统提示词（System Prompt）、Agent 模板 或 用户消息 中，你可以使用特定的占位符来触发知识库检索。
基础语法
【kb】 或 【knowledge】
当系统在消息中发现该占位符时，KnowledgeProcessor 会介入，根据当前对话上下文执行检索，并将占位符替换为格式化后的知识条目。
进阶语法（链式参数）
你可以通过双冒号 :: 传递详细参数来精细控制检索行为： 【kb::名称::数量::阈值::模式::模式参数::引擎】
| 参数位置 | 说明 | 示例 |
|---|---|---|
| 名称 | 指定知识库名称（为空则检索所有已绑定库） | 技术文档 |
| 数量 | 召回条目上限（Limit） | 5 |
| 阈值 | 最低相关度分数（0.0 ~ 1.0） | 0.45 |
| 模式 | 激活模式（always/gate/turn/static） | gate |
| 模式参数 | 对应模式的特定参数（如关键词、轮次等） | Vue,响应式 |
| 引擎 | 指定检索引擎 ID | lens |
示例：
【kb::我的笔记::3】：从“我的笔记”库中检索前 3 条相关内容。【kb::::5::0.3::gate::代码,报错】：当对话中出现“代码”或“报错”时，从所有库检索前 5 条。
激活模式（Activation Modes）
知识库处理器支持多种激活模式，避免无效检索消耗 Token：
1. 总是激活 (always)
- 语法：
【kb】或【kb:::::always】 - 行为：每一轮对话都会执行检索。适合需要 AI 深度依赖知识库的场景。
2. 静态加载 (static)
- 语法：
【kb:::::static::all】或【kb:::::static::ID1,ID2】 - 行为：
all：直接加载指定库的所有已启用条目。ID列表：加载特定的知识条目。
- 场景：将知识库作为“固定上下文”注入，不随对话内容变化。
3. 轮次触发 (turn)
- 语法：
【kb:::::turn::3】 - 行为：每隔 N 轮对话触发一次检索。
- 场景：减少频繁检索带来的上下文冗余。
4. 门控触发 (gate)
- 语法：
【kb:::::gate::关键词1,关键词2】 - 行为：扫描最近几轮对话，只有出现指定关键词时才激活检索。
- 场景：按需检索，只有聊到特定话题时才查资料。
检索增强流程（RAG Pipeline）
当占位符被激活后，系统会执行以下自动化流程：
- 查询构建：取最近 N 轮对话，分别提取用户消息和 AI 回复，通过向量空间加权融合（用户文本权重较高）构建检索向量，提供丰富的语义上下文。
- 查询预处理：对用户文本进行清洗、分词、停用词过滤，并尝试在全局标签池中进行语义匹配。
- 多路检索：根据选定的引擎（如
Blender融合引擎）同时发射字面量、语义和引力信号。 - 分数截断与过滤：低于最低分数阈值的条目直接丢弃，再按召回上限和字数上限进一步过滤。
- 格式化注入：根据配置的模板将结果转换为 Markdown 文本，替换掉原有的占位符。
检索增强配置
在 Agent 的 知识库设置 或全局设置中，你可以调整 RAG 流程的底层参数：
| 参数 | 说明 | 默认值 |
|---|---|---|
| 上下文窗口 | 取最近 N 轮对话（User + AI），分别向量化后加权融合为检索向量 | 1 |
| 最低分数阈值 | 低于此分数的条目直接丢弃，这是实际的截断依据 | 0.3 |
| 召回上限 | 检索结果的数量上限（实际截断以分数阈值为主） | 5 |
| 最大召回字数 | 注入上下文的总字符上限（0 为不限制） | 0 |
| 检索缓存 | 精确文本匹配缓存，同一查询文本直接复用结果 | 开启 |
Agent 工具能力（Tool Calling）
除了自动化的占位符注入，知识库还为具备工具调用能力的 Agent 提供了直接操作接口。这主要用于 “让 AI 帮你管理知识库”。
1. 知识库（基础）- kbBasic
适合所有 Agent，用于日常的显式搜索和条目维护。
searchEntries：显式搜索。当用户要求“帮我查一下...”时，Agent 可以调用此工具获取更精准、带序号的结果。upsertEntry：创建或更新。让 AI 帮你记笔记或整理知识。updateEntryContent：局部更新。支持精确替换条目中的特定片段。
2. 知识库（管理）- kbAdmin
高权限工具，建议仅在特定管理型 Agent 中启用。
batchUpdateMetadata：批量修改标签、优先级或启用状态。deleteEntry：删除条目（需显式确认）。
常见问题
Q：AI 在聊天时没有自动查知识库怎么办？
- 检查占位符：确认你的 System Prompt 或消息中包含了
【kb】。 - 检查模式：如果你使用了
gate或turn模式，确认是否满足触发条件。 - 检查绑定：确认当前会话已在右侧面板绑定了目标知识库。
Q：为什么 AI 总是说“未检索到相关知识”？
- 向量化状态：确认条目已完成向量化（绿色闪电图标）。
- 阈值过高：如果你在占位符中设置了
minScore，尝试调低它（例如0.3）。 - 模型一致性：确认搜索时使用的 Embedding 模型与索引时一致。
Q：如何实现“固定参考资料”？
使用静态加载模式：【kb::资料库名称::::static::all】。这会将该库的所有内容一次性注入上下文，不再随用户提问而变化。
updateEntryContent（更新条目内容）
让 AI 帮你修改已有条目的特定内容：
把刚才的 RxJS 笔记里，把"Observable"改成"Subject"，并加上"多播"的说明AI 支持两种更新模式：
- 精确替换：指定原文片段进行局部替换（至少 15 个字符以保证精度）
- 整体替换：替换整个条目的内容、标题、标签或优先级
支持 dryRun 模式预览变更而不实际执行。
整体替换参数说明：
replaceContent：替换整个条目的内容replaceKey：替换条目的标题replaceTags：替换标签replacePriority：替换优先级
知识库（管理）- 管理员操作
用于批量管理和维护操作：
listKnowledgeBases（列出知识库）
列出我所有知识库返回知识库列表及统计信息（条目数、向量化率等）。
listEntriesMetadata（查询条目元数据）
查一下"技术文档"知识库里有哪些关于 React 的条目支持按标题关键词、标签、启用状态、向量状态过滤，以及分页和排序。
batchUpdateMetadata（批量更新元数据）
把"技术文档"知识库中所有关于 React 的条目都加上"前端"标签支持批量设置启用状态、优先级、添加/移除标签。单次最多 100 条。
deleteEntry（删除条目）
把第 3 条关于"过时的方案"的条目删掉吧，我确定需要显式设置 confirm: true 才能执行删除，防止误操作。
工具调用示例
以下是一个完整的 AI 使用知识库的场景：
用户：帮我整理一下今天关于 Docker 的学习笔记
AI：好的，我先在知识库里搜一下有没有现成的 Docker 相关内容。
（调用 searchEntries → 发现已有 3 条 Docker 相关笔记）
AI：我找到了一些已有的 Docker 笔记。我来基于今天的讨论创建一条新的综合笔记。
（调用 upsertEntry → 创建新条目 "Docker 学习笔记 (2024-12-15)"）
AI：已帮你创建了「Docker 学习笔记 (2024-12-15)」，包含容器网络、数据卷和 Compose 三部分内容。我顺便给这条笔记加上了 #Docker #容器化 标签，优先级设置为 120。需要我继续补充什么吗？TODO: 截图 - AI 聊天中展示工具调用的执行过程和结果
配置建议
为了让 AI Agent 更有效地使用知识库，推荐以下配置：
Embedding 模型选择
- 使用中等规模的 Embedding 模型以平衡效果和速度
- 确保模型维度已正确配置（可通过"探测模型维度"自动检测）
检索参数调优
- 召回上限适当增加：如果 AI 回答不够准确，可以增加搜索返回的条目数
- 最小分数阈值调整：设置适当的最小分数阈值可以过滤掉不相关的结果
- 引擎选择：
- 精确关键词匹配场景：使用 keyword（关键词引擎）
- 语义理解场景：使用 vector（向量引擎）
- 复杂语义推理：使用 lens（透镜引擎）
权限考虑
- kbBasic（基础）：适合在用户日常对话中自动调用，包含搜索和条目编辑功能
- kbAdmin（管理）：建议仅在用户明确指令下触发，包含删除和批量操作
常见问题
Q：AI 在聊天时没有自动查知识库怎么办？
- 确认知识库已在上下文面板中正确绑定
- 检查绑定的知识库是否有已向量化的条目
- 确认 Embedding 模型配置正确
- 尝试在对话中明确提及"帮我查一下知识库"
Q：AI 搜索到的内容不相关怎么办？
- 检查当前使用的检索引擎是否适合该场景
- 在知识库设置中调整"最小分数阈值"，过滤低相关性结果
- 检查条目标签是否准确，标签能显著提升语义匹配效果
- 确认向量化使用的 Embedding 模型与搜索时一致
Q：AI 如何区分多个知识库？
在调用 searchEntries 时，可以通过 kbNames 参数指定具体知识库名称。如果不指定，AI 会搜索所有绑定的知识库。
Q：知识库条目更新后 AI 能立即看到吗？
如果开启了自动向量化，条目更新后会重新生成向量，AI 在下次搜索时就能检索到新内容。如果没有开启自动向量化，需要手动触发向量化后 AI 才能搜索到更新后的内容。
Q：AI 能创建多少条目？
没有硬性限制。但单次 upsertEntry 的内容长度建议控制在 12,000 字符以内。需要记录大量内容时，建议拆分为多个条目。