章节二十七：智库——文档处理节点

一、PDF转Markdown

1. 节点作用

把非结构化的PDF文档转换成结构清晰的Markdown格式，为后续的文本切分和图片理解打基础。

2. 实现思路

云端算力卸载：PDF解析（OCR、布局分析）非常耗资源，所以调用MinerU在线API来处理，不占用本地算力。

异步轮询机制：大文件解析耗时长，设计了"上传 -> 提交 -> 轮询 -> 下载"的异步流程，定时查询状态避免超时。

完整性保障：解析完不仅提取Markdown文本，还同步下载关联的图片资源。

3. 处理步骤

第一步：校验路径——从状态中获取PDF路径和输出目录，确认文件存在。
第二步：上传与轮询——调用MinerU API申请上传链接，上传PDF，提交解析任务，循环查询任务状态直到完成。
第三步：下载与解压——下载生成的ZIP包，解压后读取.md文件内容，更新到状态中。

需要在.env中配置MINERU_API_TOKEN（在MinerU官网申请）。

---

二、图片处理

1. 节点作用

实现文档的"多模态语义对齐"——把图片从本地迁移到对象存储，并用AI给每张图片生成文字摘要，让图片也能被文本检索到。

2. 实现思路

图文解耦与持久化：把图片从本地文件系统迁移到MinIO对象存储，实现计算和存储分离。

语义增强：用多模态大模型（qwen3-vl-flash）对每张图片"看图说话"，把视觉信息转成文字摘要，写入Markdown图片的Alt文本中。

速率控制：调用VLM API时实现令牌桶算法限流，防止图片太多触发API风控。

3. 处理步骤

第一步：获取内容与路径——从状态中读取Markdown文件路径和内容。
第二步：图片扫描——用正则表达式扫描Markdown中引用的本地图片，校验图片是否存在，同时提取图片的上下文（前后文）。
第三步：图片摘要——用多模态大模型对每张图片生成中文摘要，通过令牌桶算法控制调用频率。
第四步：上传与替换——清理MinIO中的旧图片目录，将图片批量上传到MinIO，把Markdown中的本地路径替换为MinIO的HTTP URL，Alt文本填入生成的摘要。
第五步：备份文件——将处理后的内容保存为_new.md文件，更新状态中的路径。

---

三、文档切分

1. 节点作用

将长文档切分成适合向量检索的小片段（Chunk），在保持语义完整的前提下控制切片长度，最大化检索的召回率和准确率。

2. 实现思路

结构化优先：不简单按固定字符数切，而是优先按Markdown标题层级分块，保持同一知识点的连贯性。

递归优化：对超长段落采用"段落 -> 句子"的递归切分策略，先按换行符切，还超长就按句号切，避免在句子中间截断。

上下文保留：每个切片保留file_title和parent_title（父级标题），为后续LLM回答提供丰富上下文。

3. 处理步骤

第一步：获取输入——从状态中提取Markdown内容、文件标题等，进行基础清洗。
第二步：标题初切——基于Markdown标题语法（#）进行第一轮粗略切分，保留层级结构。
第三步：无标题兜底——处理没有任何Markdown标题的纯文本文件，避免丢失内容。
第四步：精细化处理——对过长的Chunk用RecursiveCharacterTextSplitter递归切分（先按段落再按句子），对过短的Chunk合并（仅合并同父标题且长度不足阈值的相邻块）。
第五步：打印统计——输出原始行数、最终Chunk数量等统计信息。
第六步：备份与更新——将切分结果备份到本地JSON文件，更新到状态中。

---

名词解释

MinerU：PDF转Markdown的在线工具，支持公式、表格等复杂排版提取。
OCR：光学字符识别，把图片里的文字提取出来变成可编辑文本。
多模态：同时处理文字、图片等多种类型数据的能力。
令牌桶：一种限流算法，控制API调用频率，防止触发风控。
Chunk：文档切分后的小片段，是向量检索的基本单位。
RecursiveCharacterTextSplitter：LangChain提供的递归文本分割器，按分隔符优先级递归切分文本。
Alt文本：图片的替代文字描述，图片无法显示时会展示，也用于SEO和辅助检索。