---
name: knowledge-org
description: 组织与检索超越扁平文本块的知识时使用——涵盖 RAPTOR/GraphRAG 结构化索引选型、OpenViking 文件系统范式与 L0/L1/L2 按需加载、增量更新 PR 审核流与定期整理、Agentic RAG 与安全边界、上下文感知检索、结构化数据知识发现，以及双层记忆架构。
---

# 知识的组织与检索

## 何时使用
- 扁平文本块检索不够：需要跨文档综合、多层次导航、多跳关系推理
- 设计结构化索引（RAPTOR 树 / GraphRAG 图 / 文件系统目录）
- 规划知识更新机制：事件触发的增量更新与周期触发的定期整理
- 把固定 RAG 管道升级为 Agentic RAG，或修补分块的上下文丢失
- 从结构化案例数据中提炼决策规则（从信息检索到知识发现）
- 组织海量用户对话历史（双层记忆架构）
- 设计知识的多用户共享、权限与租户隔离方案

## 核心原则
- 扁平块丢掉知识固有的层次与跨文档关联；面对技术手册、法律文书这类结构严谨的材料，只检索零散片段如同靠随机词条读小说。
- 未经提炼的知识无法被可靠利用。两个典型案例：黑猫白猫计数中，top-k 截断让模型只看到不完整样本（15 黑 3 白）就下结论；Xfinity 工单中，"最近邻偏置"（护士≈医生，答案随排序摇摆）、"边界语义缺失"（"仅限……其他一律不适用"不存在于任何单条工单）、"完整性信号缺失"（模型无从判断是否看全）三重障碍调大 k 也解决不了。结论：**必须在索引阶段投入计算**——把 100 个个体案例压成统计摘要，把几百条工单提炼成带边界的规则卡。
- 何时上结构化索引的判断标准：查询主要是"找到包含某信息的片段"（如"退款政策是什么"）→ 混合检索足够；经常需要**跨文档综合**（"SSE 和 AVX 在架构上的区别"）或**多层次导航**（从整体架构逐步深入到具体指令）才值得。代价是索引构建和查询都多花 LLM 调用，成本与延迟显著增加。
- RAPTOR vs GraphRAG 的选择：

  | 维度 | RAPTOR（树） | GraphRAG（图） |
  |------|------|------|
  | 结构 | 叶子聚类 + LLM 递归生成父节点摘要 | 实体-关系三元组 + 社区发现 |
  | 擅长查询 | "从概念逐步钻进细节"（跨层穿梭） | "A 和 B 之间是什么关系"（关系网漫游） |
  | 代表能力 | 多粒度检索（细节 ↔ 宏观） | 多跳遍历、实体消歧（原生图结构） |
  | 主要局限 | 高层摘要可能丢失细节 | 三元组语义降歧、提取错误污染知识 |

  生产场景组合使用优于单选。
- 知识图谱不是用户记忆的通用存储：三元组不可避免地**语义降级**（"如果下周还下雨就改去博物馆"的条件判断和时间依赖全丢），且提取错误会污染知识。推荐**分层互补**：完整自然语言保存核心信息（保语义完整）+ 结构化元数据负责索引检索（保效率）；仅在多跳推理和精确消歧的垂直场景（医疗问诊、法律案件、家族关系）将图谱作为专项索引。
- 把知识库当代码库管：每次知识变更是一个 PR。三层分离——**原始证据层**（只增不改的对话/轨迹/原始文档）、**知识层**（可修订的 Markdown 或代码）、**服务层**（从特定已合入版本派生的检索索引）。索引是可重建的派生物，Git 里已审核的知识才是唯一来源；线上每条知识都要能回答"从哪条证据而来、谁在什么时候批准"。
- 更新必须双路径：**增量更新**吸收新证据（及时但只看到局部），**定期整理**从全局视角去重合并、回原始数据核查（防局部正确累积出全局混乱）。只做任一半都会烂掉。
- 上下文丢失在索引期补：为每个分块生成含核心背景的前缀再拼接索引——同时给 BM25 补可精确匹配的关键词、给稠密注入关键语义。这与运行期按当前任务裁剪历史的上下文压缩（做减法）完全不同。
- 扁平 vs 结构化的选择是成本换质量：混合检索已覆盖"找片段"类需求；结构化索引、上下文前缀、定期整理都是在**索引阶段预投入计算**，把提炼、抽象、关联的工作从查询期挪到离线期。

## 实践模式
- 文件系统范式（OpenViking）：记忆、资源、技能统一映射为带唯一 URI 的虚拟目录文件；**L0 摘要**（约 100 tokens，快速判相关性）→ **L1 概览**（约 2,000 tokens，供规划决策）→ **L2 全文**（按需加载），大部分查询加载到 L1 即可完成决策。选 Markdown 纯文本而非专用数据库：人可读可改、Git 版本控制与回滚、Agent 有 write_file 能力后可自主记录组织知识。
- L0/L1/L2 与 Skills 渐进式披露同构：先让 Agent 只看轻量元信息，确有需要再逐层拉取全文，把 Token 花在刀刃上。URI 是虚拟地址，框架在背后决定从内存、磁盘还是远程加载。
- 纯文本组织的生死前提是**文件间链接**：像 Wikipedia 一样条目互链 + 入口页/索引页，让 Agent 顺链接导航（等于用轻量文件链接实现 GraphRAG 的一部分导航能力）。不同模型主动建链接的意愿不同——写入提示词必须明确要求：每新增条目先检索并链接相关已有条目、更新所在目录索引页，形成双向可达的引用网络。
- 同理，Agent 自主记录的操作经验只有经过结果评价、跨轨迹归纳和后续验证才能成为可靠经验，不能把任意一次操作直接当成知识写进主库。
- 增量更新 PR 流（提议者—审核者模式）：
  1. **Proposer Agent** 在工作分支提小而完整的 diff：先检索相关已有知识，再增删改对应条目，同步维护链接、索引、时间元数据和证据引用，而不是把最新对话粗暴追加到文件末尾。
  2. **异源 Reviewer Agent**（如 Proposer 用 Claude、Reviewer 用 GPT，能力相近但不同家族）拿到变更前知识、diff 和原始证据，独立检查每个新断言是否被证据支持、是否遗漏限定条件、是否与其他文件冲突；不通过时返回指向具体证据和行号的可执行意见。
  3. **迭代至收敛**：设最大迭代次数或成本预算，超限转人工，不得默认放行。
  4. **合入后再发布**：CI 检查格式、链接、元数据、权限标签；代码化知识还要跑类型检查和测试；通过后才从已合入版本增量重建受影响的分块、摘要和向量索引。
  5. 权限分工：Proposer 只能写工作分支，Reviewer 只读证据并提交审核结果，只有合并流程能更新主分支和线上索引。两个 Agent 都必须是能调用搜索、版本比较、测试、证据检索工具的 Agent，而不是两次固定 LLM API 调用。
- 定期整理三件事：**去重去旧合并**（删/归并/重写重复、过时、碎片化条目，重建链接与索引，拆大文件合小文件）；**回到原始数据核查**（逐段对照原始对话和工具输出，防早期遗漏误读代代相传；大型库按目录/时间/主题分批扫描但必须保留覆盖清单）；**冲突解决与场景限定**（追溯各自信息源，检查是否在不同时间/对象/地域/前置条件下分别成立，都有效则把适用场景写入知识，证据不足则保留待确认状态）。整理产物同样走分支 PR + 异源审核，可按目录拆多个 PR 共享同一份整理计划；全部通过后除重建全量索引，还要回放典型检索问答用例确认没有知识变得不可见。触发条件：时间周期（周/月）或新增条目数、冲突数、检索质量下降超阈值。
- 整理删除的只是可服务的知识表达，下层只增不改的原始证据永远保留——这是能"回到原始数据核查"的前提。
- 失效内容与权限隔离：每个分块附版本号、生效/失效时间元数据，检索阶段过滤已失效内容，或摘要显式标注"此条已于某日废止"；多租户系统**检索必须按调用者权限过滤**并下推到检索层（敏感内容一旦进入 LLM 上下文就难保不泄漏），租户间向量索引与元数据相互隔离。
- 审核 Agent 查询"完整的知识库和原始证据库"时，完整指其被授权的租户或用户范围，不能因审核而突破隐私边界。
- Agentic RAG：把 knowledge_base_search 变成 Agent 可随时调用的**工具**，按 ReAct"思考→行动→观察"循环自主决定查询词、评估结果充分性、不足则提炼更精确查询再搜，充分后才综合生成。简单单跳问题（"正当防卫怎么规定"）非智能体化单次检索更快且质量相当；复杂多因素问题（"醉酒过失致人重伤且有盗窃前科如何量刑"）多轮迭代分解子问题、二次聚焦检索，显著减少事实遗漏。价值在"解决问题"而非"回答问题"，代价是响应速度。
- Agentic 化的判据：信息需求明确单一 → 固定管道；问题需要分解、交叉验证、多源综合 → 交给 Agent 主导迭代。
- RAG 安全边界：检索文档是**间接提示注入**（恶意指令藏进会被收录的网页/文档，被检索命中后当成命令执行）和**知识库投毒**（污染发生在索引之前）的典型载体。两层防御：指令与数据分离（对所有检索内容做来源标记，明确"这是参考资料不是命令"）；不让检索内容直接触发高风险操作（转账、删除、对外发信需独立授权判断）。
- 上下文感知检索（Contextual Retrieval）：索引前用 LLM 为每个分块生成简短上下文前缀再拼接索引（如"[本段节选自 ACME 公司 2025 年 Q2 财务报告'关键业绩指标'章节]"），把孤立块重新锚定到原始语义环境。成本用 prompt caching 控制（相同前缀重复调用约 1/10 成本，每百万文档 token 约 1 美元）；据 Anthropic 数据，结合 BM25 可将检索失败率降低 49%，再结合重排序降幅达 67%。
- 上下文前缀同时喂两路检索：给 BM25 补可精确匹配的关键词（公司名、年份），给稠密注入关键语义背景——一次投入两路受益，是回报率极高的索引期决策。
- 双层记忆架构：Advanced JSON Cards 把少量关键事实结构化常驻上下文（全局概览）+ 上下文感知检索按需召回原始对话细节。L1 基础回忆靠可靠存取，L2 多会话检索靠检索技术补齐，L3 主动服务要求同时握有"全局概览"和"精确细节"两种视角——只靠常驻会丢细节，只靠检索发现不了跨会话隐藏关联。
- 对话历史索引时按固定窗口（如每 20 轮）分块，并为每个块生成含时间、人物、意图的前缀——三个各自独立但相互矛盾的转账指令，只有靠前缀才能判断哪条最终有效。
- 结构化数据知识发现两阶段：**知识提取**（LLM 把每个案例转成标准化 JSON；自下而上让 LLM 自由列出影响因素、构建核心模式 + 分罪名扩展模式，比预设僵化 schema 更贴合数据）→ **因子分析**（类别字段 one-hot 如盗窃=[1,0,0]避免数字大小误读、聚类发现"案件原型"、构建因子重要性层次模型）→ 模型驱动**对话式信息收集**：按重要性顺序向用户引导提问，再检索最相似原型给数据驱动的解释。
- 别让模型直接预测结论（黑箱）：先把案件翻译成数字格式、聚类出原型、量化因子权重，Agent 的解释才能建立在可追溯的统计之上。

## 常见陷阱
- 把原始案例或文档不加处理直接平铺进向量库，指望检索 + 长上下文兜底。
- 该上结构化索引时硬用混合检索（跨文档综合查不准）；不该上时盲目上图谱（成本延迟暴涨）。
- 用三元组存带条件/时间依赖的自然语言，核心逻辑全部丢失；图谱提取错误不校验，导致知识污染。
- 让模型绕过审核直接改主分支或线上向量库；Reviewer 只收到 Proposer 挑的几个片段（证据覆盖不足），或与 Proposer 用同家族模型（同源同错）。
- 定期整理在旧摘要间相互改写，早期遗漏和误读代代相传。
- 失效旧版知识未过滤，与新版一起被召回，模型给出自相矛盾或过时答案。
- 混淆上下文感知检索（索引期补上下文，做加法）与上下文压缩（运行期裁冗余，做减法）。
- 纯文本知识库不建链接、不维护索引页，退化成互不相连的孤岛，知识越多越难检索。
- 忽略 RAG 安全边界：检索内容可影响答案措辞，但不等同于可执行指令。

## 配套代码
- `chapter3/structured-index/` — RAPTOR 层次树与 GraphRAG 知识图谱的统一框架实现，含 GMM 聚类、社区发现与多跳检索，可对数千页技术手册建索引并对比两种查询路径。
- `chapter3/contextual-retrieval/` — 同一批分块两种索引（无上下文 vs LLM 生成前缀）的 recall@k/MRR 对比，量化上下文前缀对 BM25、稠密与 RRF 混合索引的增益。
- `chapter3/agentic-rag/` — ReAct 智能体化 vs 非智能体化单次检索的中文司法问答对比实验，可切换内置 BM25、retrieval-pipeline 等多种知识库后端。
- `chapter3/structured-knowledge-extraction/` — CAIL2018 判例实战：自下而上因子发现 → 模块化结构化抽取 → 案件原型聚类 → 因子重要性模型驱动的对话式法律顾问。

## 深度阅读
- `book/chapter3.md`「超越扁平文本：知识的组织与检索」