写给AI看的文档：RAG时代的写作新范式

TL;DR

本文核心观点：

  1. 认知错位 — 人类友好≠AI友好，文档现状优秀不代表RAG效果好
  2. 四大原则 — 自包含、显式结构、术语一致性、问答导向
  3. 范式转移 — 从”给人阅读”到”给AI+人类双重读者”写作
  4. 行动路线 — 从诊断到优先改造再到渐进优化，分步迁移

某技术团队花了三个月整理了一份完美的Wiki文档——结构清晰、图文并茂、覆盖全面。但当他们把文档接入AI问答系统时，AI的回答准确率只有35%。问题不在于文档质量，而在于他们一直在写”给人看的文档”，却从来没有学过”给AI看的文档”。

文档工程的认知错位

本节为代表性场景描述（未指名）——业界关于”知识库 AI 化”的报告（如 Glean 2024 Enterprise Search 报告 与 Microsoft Work Trend Index）反复观察到类似模式：人工评估高的文档，在 RAG 问答上的典型准确率区间远低于预期（业界观察常落在 30%-50% 区间，随检索质量与文档结构差异显著）。下文数字为示意场景，不应视为统一基准。

代表性场景（未指名）： 某团队把积累了数年的技术文档接入 RAG，期望 AI 回答新员工问题。文档人工打分高，但 RAG 准确率”反直觉”地低于预期（示意数字：~35%）。

团队排查技术问题（向量模型、分块、检索算法）后未发现明显瓶颈，结论往往回到文档本身缺乏 RAG-Friendly 结构：链接型上下文、隐含缩写、依赖图结构对人类友好，对 AI 不友好。

人类阅读 vs AI阅读：根本差异

人类阅读 vs AI阅读：根本差异

人类怎么读文档

线性浏览：

  • 先看目录，了解整体结构
  • 再读摘要，抓住核心观点
  • 深入细节，按需精读

上下文理解：

  • 通过章节标题推断内容关系
  • 通过排版层次（H1/H2/H3）理解逻辑结构
  • 通过”上文提到…“这类指代建立连接

隐含知识补全：

  • 读到”如前文所述”，人类会回头查找
  • 看到缩写”API Gateway”，人类知道这是指什么
  • 遇到”详见架构设计文档”，人类会跳转阅读

AI怎么”读”文档

向量化分块

语义检索

上下文窗口限制

关键洞察： 人类阅读是主动的、连贯的、有上下文的； AI阅读是被动的、碎片的、局部最优的。

写给人看的文档，AI读不懂；写给AI看的文档，需要完全不同的写作范式。

RAG-Friendly 四大原则

向量化分块

AI处理文档的第一步，是将文本切分成离散的”块”（chunk），然后每个块转换成向量。这个过程叫分块（chunking），转换后的向量叫嵌入（embedding）。

分块策略直接影响检索质量：

  • 固定大小分块：按 token 数硬切（如每512 token切一刀）。简单但粗暴——可能在句子中间断开，破坏语义完整性。
  • 语义分块：按段落、主题或标题边界切。更符合人类理解单元，但实现复杂。
  • 递归分块：按层级结构递归切（如先按段落，再按句子）。兼顾边界质量和覆盖度。

关键参数是块大小（chunk size）和重叠度（overlap）：块太大，检索精度下降；块太小，上下文缺失。重叠度过低，跨块语义丢失；重叠度过高，引入冗余噪声。

这个过程揭示了AI阅读的根本特征：它不是”读全文”，而是”在切好的块里找最相似的那个”。 文档的结构感、作者的论证脉络，对AI来说都不存在。

💡 Key Insight

分块是RAG的起点：块的质量直接决定了检索的上限，再好的向量模型也救不了一块语义破碎的文档。

语义检索

用户提问时，AI并不是”理解问题后去文档里找答案”，而是在向量空间里做相似度匹配。

流程是这样的：

  1. 用户问题被同样的embedding模型转换成向量
  2. 系统计算问题向量与向量数据库中每个文档块向量的相似度分数（常用余弦相似度）
  3. 按分数降序排列，返回 top-k 个最相似的块

这意味着AI做的不是语义理解，而是几何计算。它不知道”API网关”是什么，只知道”API网关”这个向量和哪些块向量离得近。

检索质量取决于三个因素：embedding模型的能力、块划分的质量、以及相似度度量的合理性。top-k 策略也有局限——如果答案恰好在第 k+1 块，而那块只比前 k 块差一点，AI就会给出不完整的回答。

💡 Key Insight

语义检索的核心限制：AI找到的是”最相似的块”，而不是”包含答案的块”——这两个集合并不总是重叠。

上下文窗口限制

即使检索到了正确的块，AI能不能用上，还取决于另一个硬约束：上下文窗口（context window）。

主流LLM的上下文窗口从4k到128k token不等。这意味着：每次推理，AI最多只能”看到”这么多token。如果检索出来的 top-k 块加起来超过了上下文上限，系统必须做截断——丢弃部分块。

这对RAG-Friendly写作提出了直接要求：每个块必须足够紧凑、自包含、独立可理解。 不能说”详见下一节”，因为下一节可能根本没被检索到，也可能被截断丢弃了。

这个限制也解释了为什么原则一（自包含）是最根本的：当上下文窗口有限时，唯一可靠的策略是让每个块携带它所需的全部上下文。

💡 Key Insight

上下文窗口是RAG的天花板：当块数量超出窗口上限，信息必然丢失——设计文档结构时，必须假设每个块都可能孤立地被使用。

RAG-Friendly 文档的核心原则

原则一：自包含（Self-Contained）

反例：

“如前所述，这种架构模式的优势在于…”

问题：AI可能没有检索到”前文”，”这种架构模式”对它来说是未知的。

正例：

“微服务架构模式（Microservices Architecture）的优势在于：每个服务独立部署、独立扩展、技术栈灵活…”

原则：每个文档块必须包含理解它所需的全部上下文，不能依赖外部引用。

原则二：显式结构（Explicit Structure）

反例：

“这种架构采用分层设计，每层各司其职，层与层之间通过标准接口通信…”

问题：AI看到的是纯文本，需要通过语义理解”分层设计”包括哪几层、各层名称是什么。

正例（原则二）：

微服务架构采用三层模式：

  1. API网关层（API Gateway Layer）：统一入口，处理认证、限流、日志
  2. 服务层（Service Layer）：业务逻辑实现，按领域模型划分
  3. 数据层（Data Layer）：持久化存储，对外提供数据访问接口

原则：使用显式编号、列表、定义，而不是依赖隐含的段落结构。

原则三：术语一致性（Terminology Consistency）

反例：

  • 第3页：”API网关（API Gateway）”
  • 第15页：”网关层（Gateway Layer）”
  • 第42页：”入口服务（Ingress Service）”

问题：AI会把这三个当成不同的概念，无法建立关联。

正例（原则三）：

本文档统一使用以下标准术语：

  • API网关（API Gateway）：系统的唯一标准名称
  • 别名声明：网关层（Gateway Layer）、入口服务（Ingress Service）均为本文档中API网关的别名，首次出现时需显式标注：API网关（API Gateway，亦称网关层/入口服务）

原则：每个概念必须有且只有一个标准名称，别名需要显式声明。

原则四：问答导向（QA-Oriented）

反例：

“本系统采用了微服务架构，服务间通过gRPC进行通信，使用Kubernetes进行编排…”

问题：这是陈述，不是回答。当用户问”系统用什么通信协议？”时，AI需要从陈述中提取答案。

正例（原则四）：

Q：本系统服务间通信使用什么协议？ A：gRPC（Remote Procedure Call，远程过程调用协议），基于HTTP/2传输，使用Protocol Buffers作为序列化格式，支持强类型接口定义和服务发现。

Q：服务编排使用什么平台？ A：Kubernetes（K8s），用于容器化服务的自动化部署、扩缩容和运维管理。

原则：直接写出问题和答案，让AI可以精确匹配用户查询。

实践指南：从传统文档到RAG-Friendly文档

迁移策略

第一步：诊断现有文档

使用AI问答系统测试现有文档：

  1. 准备20个常见问题
  2. 让AI基于文档回答
  3. 记录回答准确率
  4. 分析失败案例（为什么答错？）

第二步：优先改造高频文档

不要试图一次性改造所有文档，优先处理：

  • 最常搜索的内容（通过搜索日志分析）
  • 新员工入职必读文档
  • 故障排查和FAQ

第三步：渐进式优化

不要追求完美，采用迭代策略：

  1. 第一轮：确保术语一致性
  2. 第二轮：添加显式结构（编号、列表）
  3. 第三轮：改写为问答形式
  4. 第四轮：测试→反馈→再优化

写作检查清单

在发布文档前，检查：

  • 自包含性：文档块是否包含理解所需的全部上下文？
  • 术语一致性：同一个概念是否使用了不同的名称？
  • 显式结构：是否使用了编号、列表、定义？
  • 问答覆盖：是否直接回答了用户可能提出的问题？
  • 分块友好性：如果在任意位置切分，是否仍能理解？

工具辅助

自动化检查工具

实际迁移中，可以借助工具对文档进行自动化检查，快速识别不符合RAG-Friendly原则的段落。以下是三类核心工具的简要说明：

1. 术语一致性检查器

扫描文档中同一概念出现的所有不同表达，按标准术语表（Glossary）比对，标记出别名使用位置。标准术语表通常是一个简单的两列表格：标准名称 别名列表。

2. 自包含性验证器

基于规则或LLM检测文档块中对外部引用、”前文”、”下节”等隐含上下文的依赖。一种实现思路是：每次只输入单个块，让LLM判断它是否能独立回答该块标题所对应的问题——如果不能，说明块缺乏自包含性。

3. QA覆盖率分析器

输入文档集合和常见问题列表，逐一检查每个问题是否能在文档中找到直接匹配的答案（而非需要从陈述中提取）。覆盖率低于阈值的领域，就是需要优先改造的文档。

工具链建议：三项检查可以串联成一个CI流程，在文档提交时自动运行，确保新增内容符合RAG-Friendly标准。初期覆盖率目标建议设为80%，逐步提升。

💡 Key Insight

工具是加速器，不是替代品：自动化检查能发现结构性问题，但理解文档语义是否自包含、问答是否真正对应用户意图，仍然需要人工 review。

深层思考：写作范式的范式转移

从”叙事”到”检索”

传统写作是线性的、叙事的、渐入佳境的； RAG-Friendly写作是模块化的、自包含的、即插即用的。

这就像从写小说到写百科全书的转变——

  • 小说需要前因后果，百科全书每个词条独立完整
  • 小说可以埋悬念，百科全书必须直截了当
  • 小说依赖上下文，百科全书每段都是入口

💡 Key Insight

写作目的的转变：从”让人类顺着作者的思路读下去”到”让AI在任何位置都能准确提取信息”——这是两种完全不同的写作目标。

从”给人类读者”到”给AI+人类”

RAG-Friendly文档不是只给AI看，而是同时服务两种读者：

  • 人类可以快速扫描、深入阅读
  • AI可以精确检索、准确生成

好的RAG-Friendly文档，对人类同样友好——因为它清晰、结构化、无歧义。

💡 Key Insight

双重读者的要求其实是统一的：结构清晰、无歧义的文档，对人类和AI都更友好。RAG-Friendly不是在迁就AI，而是在提升文档质量本身。

从”文档”到”知识库”

传统文档是静态的、固定的、版本化的； 现代知识库是动态的、可检索的、可组合的。

文档工程的终极形态不是”写一本完美的书”，而是构建一个可被AI理解、检索、重组的知识网络。

结尾

一个反直觉的事实：

AI的能力上限，很大程度上取决于文档的质量。

再强大的LLM，如果基于混乱、不一致、缺乏结构的文档进行RAG，也只能给出混乱、不一致、缺乏依据的回答。

反之，即使是中等水平的模型，基于高质量、结构化、RAG-Friendly的文档，也能给出准确、有用的答案。

写文档的人，正在定义AI的能力边界。

这不是夸张。在RAG时代，文档工程师的角色从未如此重要——他们不是在写”参考资料”，而是在构建”AI的认知基础设施”。

所以，下次当你写文档时，问自己一个问题：

“如果AI只能看到这一小段，它能理解我在说什么吗？”

如果不能，重写它。

深度阅读时间：约 12 分钟

参考与延伸阅读

*Published on 2025-03-11 阅读时间：约 12 分钟*

本文是知识管理系列的第三篇（外化→文档→KBaaC）。