AI 驱动的产品文档站

我见过一份文档站的真实数据:用户平均点 1.8 个页面就离开,搜索框的使用率不到 7%,而社区 Slack 里"文档里有写吗?"这类问题每天上百条。不是用户懒,是文档站本身让人找不到。

传统文档站只有两条路:目录,和搜索。目录靠你猜信息藏在哪一级;搜索靠你猜作者用了什么词。用户问"怎么接 OAuth 登录",页面标题却叫"身份认证"——关键词对不上,搜索返回空,用户直接放弃,跑去问人。这篇文章讲怎么把一个静态文档站升级成 AI 可问答:用户用人话提问,直接拿到答案 + 能点回原文的引用,以及这套东西该自建还是用托管。

一、传统文档站为什么"找不到"

三个老毛病,每一个都让用户流失:

• 目录太深:一个 API 文档动辄四层目录,用户不知道"重试策略"是归在"配置"还是"高级用法"下。他不是来读树的,他是来找答案的。
• 搜索是关键词匹配:全文检索只能匹配字面。"部署"搜不到标题叫"上线"的页面;错误码 ERR_TIMEOUT 搜不到,因为正文里写的是"超时"。模糊需求(怎么做、为什么、区别是什么)关键词搜索基本无解。
• 找到之前已经放弃:用户点开三四个候选页,Ctrl+F 不到关键句,就关了。文档"有"和用户"找到"之间,隔着一整条认知鸿沟。

AI 问答补的就是这条鸿沟。它的本质是:把"用户用人话描述的问题"直接映射到"文档里那段答案",跳过导航树和检索词匹配这两道关卡。用户不用猜目录,也不用猜词——他只要会说人话。

二、架构:从静态文档到可问答

把一个 MDX/Markdown 文档站升级成 AI 可问答,核心是一条"离线索引 + 在线问答"的管道。

┌──────────────┐     ┌───────────────────────────────┐
│  文档源(MDX) │────▶│  构建管道(CI / Git Webhook)    │
│  Git 仓库     │     │  parse → 切片 → embed → 入库   │
└──────────────┘     └───────────────────────────────┘
                               │
                               ▼
                     ┌─────────────────────┐
                     │ 向量库 + 关键词索引   │  pgvector / Qdrant
                     └─────────────────────┘
                               ▲  top-k
                               │
┌──────────────┐     ┌─────────────────────┐
│  用户提问     │────▶│  问答 API           │
│ "怎么实现 X"  │     │  检索 → 拼 prompt →  │
└──────────────┘     │  LLM 生成答案 + 引用 │
       ▲             └─────────────────────┘
       │   流式回答 + 引用 [1][2] 可点击跳原文锚点
       └─────────────────────────────────────┘

三个关键环节:

1. 切片(chunking)——这一步决定上限。 别按固定字数无脑切(会把一个完整步骤切成两半)。按文档的标题层级切:一个 H2/H3 下的一小段就是一个 chunk,同时把它的"路径上下文"(文档标题、父级标题、URL、锚点)一起塞进 metadata。这样检索命中的不是孤立片段,而是带"出身"的片段——问答时模型知道这段来自哪篇、哪节,引用才挂得上去。

2. 索引——向量为王,但别只靠向量。 纯向量检索对精确词(配置项名、错误码、函数名)反而弱。生产配置是向量 + 关键词混合检索(RRF 融合),代码标识符、版本号这些走关键词分支接得住。已有 PostgreSQL 就用 pgvector,别平白起一个向量服务。

3. 问答——检索为辅,生成为主。 把召回的 top-k chunk 作为 context 喂给 LLM,要求它基于 context 回答,并在每个论断后标引用。流式输出答案,引用区附在下面,可点击跳转到原文档对应锚点。

三、引用是底线,不是加分项

这是整个方案里我最要强调的一点:没有引用的 AI 答案,等于不可信的幻觉源。

用户对 AI 文档问答的信任,完全建立在"我能追到原文"上。如果 AI 说"你需要在配置里加 retries: 3",用户第一反应是"这是真的吗?哪写的?"——如果给不出处,他要么不信,要么照做然后踩坑。所以引用不能只是装饰,要做到三件事:

1. 可追溯:每个关键论断后挂 [1][2],对应到具体 chunk。
2. 可跳转:点击引用直接打开原文档,并定位到对应锚点(所以切片时要保留 #section-id),不是只甩一个"来自配置文档"。
3. 可校验:用户能对照原文核对 AI 有没有断章取义。AI 答错时用户能发现,AI 答对时用户能深入。

一个实操技巧:在 system prompt 里强制要求"只基于提供的 context 回答,context 没有的就说文档未提及,并标注引用编号",并在前端把引用渲染成可点击的卡片。把"答不出来"也当成合法输出,比让它硬编一个幻觉强一百倍。

四、为 AI 重写文档:结构化是新的 SEO

接了 AI 问答之后,你会发现一个反直觉的事:文档能不能被答好,70% 取决于文档本身怎么写。 RAG 调参是后面 30%。要让文档"AI 友好",本质是让它结构化——这同时也是人类友好。

• 标题要描述性。"如何配置 OAuth 回调地址" 远好于 "配置"。标题是 chunk 的"门面",也是检索和生成时权重最高的文本。
• 一个概念/步骤独立成块。别把 OAuth 配置揉进一段 800 字的叙述里。独立的小节 = 独立的 chunk = 检索能精准命中。长段落一旦被切分,上下文就散了。
• 关键信息别只放在图片里。架构图、流程图里的文字,LLM 看不到、检索不到。图旁边一定要配文字说明,代码配置用代码块而不是截图。
• 代码块标语言。```tsx 比 ``` 好——解析器能识别,模型理解更准,前端高亮也对。

一句话:AI 友好 = 结构化 = 人类也更好读。 为 AI 写文档没有额外负担,它只是逼你把文档写好。

五、托管 vs 自建:别为了 AI 问答把文档托管权交出去

市面上两类方案,选错代价很大。

托管型(Mintlify、Convex、Intercom Fin 等):文档托管在它们平台,开箱即用 AI 问答、引用、样式全套。优点是省事,一周上线;缺点是文档要从你的仓库迁过去,定制受限,版本控制和文档Review流程被平台绑住,数据也在别人手里。

自建 RAG:文档留在自己仓库(MDX in Git),你只加一条"切片→索引→问答"的管道。完全可控、可定制、可演进,但要自己处理切片策略、索引更新、问答 prompt、引用渲染。

我的判断标准很简单:

• 文档量小、团队没人手、要快:用托管。Mintlify 这类把"AI 文档站"当产品做的,体验确实打磨得好。
• 文档是产品核心、有定制需求、文档已经在 Git 里:自建。尤其开发者文档——MDX 在仓库里、PR Review、版本化是基本盘,为了 AI 问答把这套交出去不划算。

中间路线最稳:文档用自己的(MDX in repo,Next.js 渲染),只把 AI 问答这层作为独立模块接进去。 既留住文档主权,又拿到 AI 能力。这也是我推荐大多数团队的做法。

六、AI 是文档的检索层,不是替代品

接到一半最容易犯的错:觉得"反正 AI 能答",文档本身就不好好写了。 这是饮鸩止渴。

AI 会答错、会漏、会因为索引没更新而过时。它本质是文档的前台检索层——快速把用户引到答案,而不是答案本身。文档本身仍然是唯一的权威源。所以两件事必须保留:

• 完整可浏览的文档:目录、页面、全文搜索一个都不能少。AI 答不好时,用户要能自己翻文档查证;搜索引擎的 SEO 流量也靠这些静态页面。
• 把 AI 当"前台",不是"整栋楼"。用户问了,AI 快速给答案 + 引用;用户要深入,点引用回到原文档。两层各司其职。

一个反例:有团队把文档全部塞进 AI,撤掉了目录和搜索,结果文档站 SEO 流量腰斩,AI 一旦答错用户连退路都没有。AI 是放大器,不是替代品——它放大好文档的价值,也放大烂文档的危害。

七、进阶:让用户的提问反向补全文档

真正成熟的 AI 文档站,会形成一个闭环。

文档变更自动重索引:Git Webhook 或 CI 监听文档目录,哪篇改了只重切那一篇、重算 embedding、版本化覆盖。别让索引滞后于文档——AI 拿着过时的 context 回答,比不答还糟。这跟代码部署一样,要做成自动化流水线,不能手动跑脚本。

高频提问反向补文档:这是最被低估的价值。把用户的提问日志聚合,你会发现两类信号:

• 答得好但问得多:说明这个功能文档藏得深,该提上来、优化标题。
• 答不好/答不出:这就是文档的缺口——用户有需求,文档没覆盖。

把这些"答不好"的问题聚合成一份"待补全清单",直接喂给文档维护者。高频提问 = 文档缺失的最强信号,比你拍脑袋想文档大纲准十倍。补完文档 → 重索引 → 下次答得好,闭环转起来,AI 文档站会越用越聪明。

小结

把静态文档站升级成 AI 可问答,核心是一条索引管道 + 一个带引用的问答层,但成败取决于文档本身。

1. 痛点在"找不到":目录深、搜索弱,AI 问答跳过导航和检索词匹配,直接人话→答案。
2. 切片决定上限:按标题层级切、保留路径上下文,别无脑按字数切;向量 + 关键词混合检索是生产标配。
3. 引用是底线:答案必须能追溯到原文锚点,可点击、可校验;没引用的答案不可信。
4. 文档要为 AI 重写:结构化标题、概念独立成块、关键信息别只放图里——AI 友好就是人类友好。
5. 托管 vs 自建看主权:文档是核心就自建(MDX in repo),只为 AI 把这层接进去;别为省事交出文档托管权。

最后一句:AI 是文档的前台,不是文档本身。 把 AI 当成把用户快速引到答案的检索层,文档该写的还得好好写——否则 AI 答得越快,把用户带偏得也越快。