企业官网建设流程全解析

今天翻了翻 GitHub 上的每日热评，发现 Firecrawl 的 anydoc 又被推到前排了。这个项目我在做 RAG 和文档解析的时候实际用过一段时间，感受挺直接：它把“办公文档转 Markdown”这件事的下限拉高了一大截。以前处理 PDF、Word、PPT，最笨的办法是先截图、再 OCR，识别完之后排版全乱，表格经常粘在一起，标题层级也丢了；现在直接丢给 anydoc，出来的就是带标题层级、表格、代码块的 Markdown，省掉的不只是一两步操作，而是整个“预处理心智”。

这篇不打算做成项目文档的翻译版，更多的还是把我自己从“截图 OCR”切到“文档直转 Markdown”这条路上踩过的坑、对比过的方案、实际跑通的步骤整理出来。不管你是做知识库、RAG 管线，还是被合同、发票、PPT 预处理折磨的内容从业者，这篇文章应该都能给你省下不少试错时间。

1. 为什么“先截图再 OCR”这条老路，越来越走不通了

1.1 老流程的三大痛点

先说说我以前是怎么处理办公文档的，估计不少人和我一样：拿到一份 PDF，先按页转成 PNG，再用 PaddleOCR 或 Tesseract 跑一遍文字识别，最后把识别结果手动整理成结构化的文本。这套流程在文档量小的时候勉强能用，但一旦规模化，问题就全部冒出来了。

第一个痛点是流程繁琐。截图这一步看似简单，但要保证分辨率够高、页面完整、文字不模糊，实际操作起来要在渲染参数上反复试。PDF 渲染成图片之后，OCR 那一步又要调模型、调阈值、调语言包，整个链路里任何一环出问题，结果就废了。而且“截图 + OCR”本质上是把电子文档当成扫描件来处理，明明 PDF 里就有文字层，非要绕一圈去识别，效率低就算了，准确率还不一定比直接提取高。

第二个痛点是版式丢失。OCR 输出的是扁平的文本流，它识别出“这是一行字”很容易，但要还原“这是二级标题”“这是表格第三列”“这是代码块”就很难。我自己处理过一份带多级标题和技术参数的 PDF，OCR 完之后标题层级全平了，表格的列对齐也全乱了，最后我还得写脚本去猜原文的结构。猜来猜去，人工校正成本比重新排版还高。

第三个痛点是表格和代码块几乎无法还原。识别出来的表格经常是行列错位、单元格内容串行；代码块里的缩进和换行更是重灾区。普通文字识别错了还能靠上下文猜，代码缩进错了、引号识别成全角，整个片段就没法用。我一度怀疑 OCR 工具是不是对等宽字体有天然敌意。

1.2 真正的需求是“结构化文本”，不只是“识别出来的字”

后来我做 RAG 项目，对文档处理的要求发生了本质变化。以前做 OCR 是为了“把纸面文字变成可搜索的文本”，只要字对就行；但把文档喂给大模型或者放进知识库做检索的时候，光有字是不够的，还得有结构。

举个例子，一份产品手册里写着“最大负载 500kg，工作温度 -10℃ 到 40℃”，如果只是识别成一行纯文本，检索“温度范围”的时候很可能召回不到；但如果转成 Markdown，它可能是一张表格里的两列，或者一个列表项里的键值对，模型一眼就能看出“温度”对应的值是“-10℃ 到 40℃”。结构本身就是语义信息。

这也是为什么 Markdown 在 LLM 生态里越来越像“通用语”。它没有 Word 那么复杂，没有 PDF 那么封闭，也没有纯文本那么扁平。一个带##的标题、一个|分隔的表格、一个三个反引号包起来的代码块，这些都是机器能直接理解的结构化信号。所以文档预处理的真正目标，不是“把 PDF 变成 txt”，而是“把 PDF 变成结构完整的 Markdown”。纯 OCR 思路解决不了这个问题，必须靠“文档结构化解析”的思路。

2. Firecrawl anydoc 的工作方式与效果拆解

2.1 它不是 OCR，但和 OCR 是一条战线的

Firecrawl 这个项目最早是做网页抓取的，核心能力是把网页内容转换成干净的 Markdown。后来他们把能力扩展到了本地文档，这个扩展出来的文档解析能力就叫 anydoc。我理解它的定位是：把 PDF、Word、PPT 这类办公文档，当作“网页之外的另一种内容来源”，最终都统一输出成 Markdown。

那 it 和 OCR 是什么关系？我的理解是，anydoc 不是“传统的 OCR 工具”，它更像一个“结构化文档提取引擎”。对电子版 PDF，它会尝试直接读取文档内部的文字层和样式信息，包括字体大小、加粗、缩进、表格线框这些，然后根据这些信息判断标题层级和表格结构。这个过程不依赖 OCR，所以速度更快，字符还原也更准。对扫描版的 PDF，也就是没有文字层的图片型文档，它才会回退到 OCR 引擎来处理。所以更准确地说，anydoc 和 OCR 是一条战线的：OCR 是它的兜底，而不是主干。

那为什么说“不必先截图再 OCR”？因为电子文档的原始信息本来就是结构化的，PDF 里有文本对象，PPT 里有形状和文本框，Word 里有段落样式。截图会把这些信息全部拍扁成像素，OCR 又要从像素里把字抠回来，这一来一回损失太大了。anydoc 的思路是直接从原始文档解析，该用文本层就用文本层，该套用版面分析就套用版面分析，最后把内容映射成 Markdown 语法。这个思路比 OCR 靠谱，是因为它尊重了文档本身的构造方式。

2.2 对比几类文档的实测差异

我拿三类典型的文档做过对比测试：多级标题的 PDF、带复杂表格的 Word、PPT 转出来的 PDF。每一类都同时跑“先截图再 OCR”和“Firecrawl anydoc”两条路径，结果差异挺明显的。

我印象最深的是表格类的文档。以前用 OCR 识别一个带合并单元格的表格，输出结果经常变成一堆碎片文本，我要靠肉眼去对行列。anydoc 输出的表格虽然偶尔也会有识别不完整的情况，但整体行列关系是能看出来的，后处理成本低很多。

当然，它也不是万能的。我遇到过一份排版非常极端的宣传册，文字叠在图片背景上，anydoc 的输出还是会有内容串位的问题。但横向对比下来，绝大多数常规办公文档，它的准确率和结构化程度都优于“截图 + OCR”的组合方案。

3. 本地部署与实操流程

3.1 为什么建议本地部署，环境怎么准备

Firecrawl 有云服务，但如果你的文档涉及内部资料，或者批量处理的量比较大，我建议本地部署。自己做 RAG 项目的时候，我一开始用的云 API，跑了几百份文档之后发现成本有点压不住，而且把客户合同传到外部服务这件事本身也有合规风险。后来改成 Docker 本地部署，数据不出内网，速度也稳定。

本地部署的方式其实很常规：把仓库拉下来，用 Docker Compose 把整套服务跑起来。Firecrawl 在部署文档里写得很清楚，需要注意的就是 Redis 和数据库的容器要一并启动，因为任务队列和元数据存储都依赖它们。如果只是短期试用，也可以直接 npm install 然后用本地模式跑，但我实测下来还是 Docker Compose 最省心，依赖不会散落到系统里，清理也方便。

# 拉取仓库（基于官方常见部署方式） git clone https://github.com/firecrawl/firecrawl.git cd firecrawl # 复制环境变量模板并做最小配置 cp .env.example .env # 启动整套服务（Redis、数据库、应用容器一起拉起） docker compose up -d

启动之后，服务默认监听在http://localhost:3002。我遇到过端口占用的问题，改一下docker-compose.yml里的映射端口就行。整个过程大概十分钟，比我想象中顺利。

3.2 用接口把 PDF 转成 Markdown

Firecrawl 的接口风格和它的网页抓取接口是统一的，都是 POST 一个任务，拿回一个结果。把 PDF 转成 Markdown 其实就一个请求的事。我用curl跑过一次，响应很快，尤其是有文字层的 PDF，几乎不需要额外等待。

curl -X POST http://localhost:3002/v1/convert \ -H "Content-Type: application/json" \ -d '{ "url": "file:///data/samples/product-manual.pdf", "formats": ["markdown"] }'

这里的url字段有意思，它在本地部署模式下可以直接用file://协议指向服务器上的文件，也可以使用对象存储的地址。返回结果里会带markdown字段，内容就是转换好的结构化文本。我在 Python 里是这样调用的：

import requests resp = requests.post( "http://localhost:3002/v1/convert", json={ "url": "file:///data/samples/product-manual.pdf", "formats": ["markdown"] } ) data = resp.json() markdown_text = data["data"]["markdown"] with open("output.md", "w", encoding="utf-8") as f: f.write(markdown_text)

这段代码看起来简单，但实际用的时候有几个细节要注意。第一，返回结果的 JSON 层级不要搞错，我一开始按错误的结构去解析，白折腾了十几分钟；第二，如果文档很大，建议先把 PDF 放到服务能访问到的目录里，再走file://，直接传 Base64 数据量一大就很容易超时；第三，建议在请求里加一个waitFor参数，让接口等转换完成再返回，否则可能需要轮询任务状态。这几个小点不解决，接口能通但用起来会很别扭。

3.3 接进 RAG 工作流的效果表现

本地部署 Firecrawl 之后，我做的最有价值的一件事，就是把它接进了 RAG 预处理管线。以前我的管线是“PDF 转图片 -> OCR -> 纯文本”，现在换成了“PDF -> anydoc 转 Markdown -> 按标题分块”。这个替换带来的变化是实实在在的。

首先是分块质量的提升。Markdown 里的#、##级别的标题给了我很清晰的分块边界，我可以用一个小脚本把 Markdown 按标题层级切成块，每一块正好是一个独立的知识单元。以前用纯文本分块，经常把表格劈成两半，检索的时候上下文明显断裂。

其次是检索召回率的提升。同样一批文档，我用相同的 Embedding 模型和相同的向量库，把文档从纯文本改成 Markdown 之后再入库，召回测试的命中率明显上升。原因也简单：Markdown 里的表格语法让模型能区分“键”和“值”，标题语法让段落之间的关系更明确，向量表达里的语义层次更丰富。

import requests import re def pdf_to_markdown_chunks(pdf_path, chunk_by="##"): resp = requests.post( "http://localhost:3002/v1/convert", json={"url": f"file://{pdf_path}", "formats": ["markdown"]} ) md = resp.json()["data"]["markdown"] chunks = [] current_section = [] for line in md.splitlines(): if line.startswith(chunk_by + " "): if current_section: chunks.append("\n".join(current_section)) current_section = [line] else: current_section.append(line) if current_section: chunks.append("\n".join(current_section)) return chunks

这段分块逻辑不复杂，但效果比按固定字符数硬切好很多。我建议所有做 RAG 的朋友，不管用什么解析工具，都尽量让分块边界跟着语义结构走，而不是跟着字符数走。Markdown 标题就是最简单可靠的语义边界。

4. 常见问题与排查技巧实录

4.1 常见问题速查表

用 Firecrawl anydoc 的过程中，我遇到过不少问题，有些是环境层面的，有些是文档本身的，也有一些是接口用法上的。整理成一张速查表，方便直接对照排查。

这张表里最值得注意的是表格识别的问题。我测试下来，凡是“看着像表格但其实是图片”的表格，anydoc 的输出都不会是 Markdown 表格语法，而是图片本身或者 OCR 后的文本。遇到这种文档，期望值要放低一些，不能指望一个工具解决所有问题。

4.2 踩过坑之后的一些心得

第一个心得是：不要盲目加 OCR。我一开始总觉得 OCR 是万能的后备方案，后来发现对电子版 PDF 强行开 OCR，反而会把原本清晰的文字层搞乱。mma我现在的习惯是先看文档有没有文字层，有就优先让 anydoc 走文本提取路径，没有才考虑 OCR 兜底。这是“按需兜底”，不是“默认全开”。

第二个心得是：文档命名的规范性很重要。不管是用file://还是用对象存储，文件名里的空格、括号、中文有时候会在接口调用时出问题。我建议把文件名统一成纯英文加下划线，比如product_manual_2024.pdf，绝不要在文件名里用空格和特殊符号。这算不上 Firecrawl 的 bug，但能避免很多不必要的麻烦。

第三个心得是：Markdown 只是中间产物，不是最终答案。转换完成之后，一定要用一个自动化脚本去检查输出的质量，比如看看表格语法是不是闭合、标题层级是不是连续、有没有异常的换行符。我自己写了一个几百行的校验脚本，专门扫这些低级错误。批量处理几百份文档的时候，人工根本看不过来，脚本能帮你把质量下限兜住。

5. 从文档解析到 AI 知识库，还能怎么延伸

5.1 把 Markdown 直接变成模型上下文

文档转换完成之后，一个很自然的延伸方向是配合大模型做问答。我在本地跑过一个小实验：把一份几十页的设备手册转成 Markdown 之后，交给本地部署的模型直接回答“设备故障代码 E203 怎么处理”，模型能直接从标题定位到故障排查章节，然后给出答案。这个过程里没有做 RAG 检索，纯粹是把 Markdown 拼进上下文，但效果已经比用纯文本好很多。因为 Markdown 的结构让模型知道哪里是重点，哪里是例子，哪里是警告。

这种方式特别适合文档量不大但需要精确引用的场景。比如内部知识库只有几十份核心文档，与其搭一套完整的向量检索系统，不如直接把 Markdown 文本按章节组织好，让模型在有限的上下文里读取。速度快，部署也简单，输出质量还能接受。

5.2 在批量导入场景里的组合用法

如果你的场景是“一次性把办公文档批量导进知识库”，那就可以把 Firecrawl anydoc 放在流水线的最前面，后面接上清洗、分块、向量化。我在生产环境里的做法是：写一个监控脚本盯住某个文件夹，里面有新文件进来就自动触发生成 Markdown，再把它写进向量库。整套流程跑起来之后，基本做到了“文件落地，知识立即可查”。

这里有一个小技巧：转换后的 Markdown 建议保留一份原始的，不要只存向量。向量是机器理解的，Markdown 是人类可读的，而且模型在回答时如果能引用原文，会比直接引用向量片段更有说服力。我在知识库系统里加了一个“查看原文”的按钮，点击之后能看到对应的 Markdown 片段，内部同事反馈这种可溯源的设计比单纯给答案靠谱得多。

5.3 后续可以尝试的能力组合

Firecrawl 本身的能力一直在迭代，anydoc 只是其中一块。实际使用中我还会结合它的网页抓取能力，把外部参考资料和内部文档统一转成 Markdown 后一起入库。它在formats参数里支持markdown之外的多种输出格式，延展的空间很大。

我做 RAG 项目时总结出的一个体会是：不要把工具当黑盒，可以去读它的源码，尤其是文档解析的边界情况处理。清楚工具能做什么、不能做什么，才能在真正的业务场景里把它用好。比如我发现它对单栏文档的支持好于多栏，那在设计文档模板时就会主动改成单栏排版，源头上减少解析误差。这种“为解析而设计”的思路，比事后补丁高效得多。

最后再说几句

我个人在实际操作中的体会是：Firecrawl anydoc 不是来“取代 OCR”的，它是来告诉你“很多文档压根不该用 OCR”的。过去我们习惯先截图再识别，是因为工具链里只有这一条路；现在有了解析文档本身结构的工具，正确做法是让文本回到文本、让结构回到结构，OCR 只在真正需要它的时候顶上。我踩过一次把电子文档强行送去 OCR、结果好好的文字层被识别错乱的坑之后，就再也没回到“截图 + OCR”的老路上去了。如果你也正在被办公文档预处理折磨，不妨先拿一份典型的 PDF 丢给 anydoc 试跑一下，大概率你会回来把这篇收藏了。