RAG 文档解析

RAG 文档解析解决的是把 Markdown / MDX 内容变成可检索、可追踪、可更新结构的问题。RAG 的目标不是让模型显得更懂，而是让回答建立在可追溯、可更新、可评估的外部知识之上。

在 Way To Agent 的知识体系里，这篇文章关注的是 Markdown / MDX 文档解析、frontmatter 提取、正文清洗和结构化元数据如何进入 RAG 链路。它要回答的是“哪些结构必须保住，哪些噪声必须清掉”。

原始文档为什么不能直接喂模型

文档解析会在这些地方决定后面整条链路的上限：

• 内容源会持续变化，不能依赖模型训练时的旧知识。
• 用户需要的不只是答案，还要知道答案来自哪篇文档、哪个标题、哪个片段。
• 一次错误回答可能来自解析、切片、召回、Rerank、Prompt 或模型生成任一环节。
• 读取 Markdown / MDX 与 frontmatter。
• 清理导航、样式和无关代码。
• 保留标题层级、来源路径和元数据。

这些问题最后都会落回一点：原始文档里的结构如果没保住，后面再强的检索和生成也只能在残缺材料上工作。

解析阶段到底在做什么

文档解析的工作方式是把原始 Markdown / MDX 拆成标题、正文、元数据和来源路径，再把它们交给后续切片和检索使用。

用户输入
  -> 业务上下文与权限判断
  -> 数据、检索、Prompt 或工具编排
  -> 模型调用或确定性服务执行
  -> 结构化校验、引用、日志和反馈

真正关键的，不是解析步骤多不多，而是有没有把关键结构留下来。解析阶段丢掉的结构，后面很难靠向量检索补回来。

必须保住哪些结构

从工程实现看，文档解析通常会牵涉以下组件：

• 文档解析与元数据提取
• 标题感知切片与 chunk 管理
• Embedding 与向量库写入
• 召回、过滤、Rerank 与上下文拼接
• 引用溯源、日志和效果评估

这些组件不一定都要在第一天完整引入。更稳妥的做法是先用最小闭环验证业务价值，再沿着质量、成本、权限和可观测性逐步补齐能力。

哪些内容该清掉

不要把 RAG 简化成“向量数据库加大模型”。向量检索只是链路中的一段，解析质量、片段结构、引用字段和评估闭环同样决定最终效果。

以 Way To Agent 当前版本为例，公开文档阅读、分类、标签、文章详情和基础搜索应能静态独立运行；会调用 LLM、Embedding、Rerank 或外部工具的能力，必须登录后限量使用，并记录调用日志和额度消耗。这个例子说明：不是所有知识库能力都应该变成模型调用，成本、权限和部署复杂度必须被单独约束。

最常见的误解

• 只看模型效果，不看权限、日志、成本和失败恢复。
• 只堆框架名，不说明框架在链路中的职责。
• 把 Demo 的成功当成生产系统的可靠性证明。
• 在没有评估样例和调用记录的情况下讨论“效果好不好”。

怎么排查

当文档解析相关功能表现不稳定时，不要先猜模型不好。更有效的排查顺序是：

输入是否明确
上下文是否正确
权限与数据范围是否匹配
Prompt / 工具 / 检索配置是否符合预期
模型调用是否超时、限流或输出不合规
日志、引用和评估样例是否能复现问题

这个顺序的好处是把问题从“玄学调参”拉回工程事实。只要每一步都有记录，就能判断是输入、数据、配置、模型还是展示层的问题。

一句话结论

RAG 文档解析的核心不是记住一个名词，而是理解它在 AI 应用链路中的责任边界。解析阶段丢掉的结构，后面很难靠向量检索补回来。

上手前先画清楚

1. 用一张图画出“文档解析”在你的 AI 应用链路中的位置。
2. 标注哪些步骤是确定性工程逻辑，哪些步骤会调用模型或检索服务。
3. 为一次失败结果写出排查字段：输入、上下文、配置、模型、日志和用户反馈。

继续阅读

04-rag/001-what-is-rag.md
04-rag/002-rag-architecture.md
04-rag/004-chunking-strategy.md