企业官网建设流程全解析

文档解析这个环节，过去很长一段时间都是“能做，但做得不彻底”。尤其是企业内部大量 PDF、扫描件、表格和多栏排版的文档，传统文本抽取和 OCR 方案往往要么丢掉层级结构，要么把表格拆得稀碎，数据一旦进入大模型或知识库，问题就会被下游无限放大。Cohere 这次发布的 Parse 5（parse-v5.0）走的是另一条路线：它本身是一个 2.3B 参数的视觉语言模型，通过视觉方式直接阅读文档页面，再把版面内容转换成结构化的 Markdown 输出。下面我会围绕 parse-v5.0 聊清楚它到底解决什么问题、接入前的准备工作、单文档和批量任务怎么跑，以及最后如何判断 Markdown 质量。

这类工具最值得关注的不是“能不能识别文字”，而是“能不能把文档结构一起带出来”。一个表格、一个层级分明的标题、一组嵌套列表，在 Markdown 里都有明确的语法结构，这意味着下游不需要再靠正则去猜段落关系。如果你正在搭 RAG 知识库、做企业文档数字化，或者需要用大模型处理合同、发票、技术方案这类文件，这篇文章可以帮你把 parse-v5.0 的接入流程和价值边界一次理清楚。

1. 文档解析不是新话题，但“直接输出 Markdown”这一步很关键

文档解析多年来都是数据工程里的隐性成本。早期做法基本分两种：一种是从 PDF 里直接提取文本层，遇到扫描件就束手无策；另一种是 OCR 识别，把图片变成文字，但版面信息基本靠人工后处理。这两种方式在处理排版简单的电子文档时勉强够用，一旦遇到多栏排列、单元格合并、跨页表格、页眉页脚混排的内容，输出质量就会明显下滑。

parse-v5.0 的差异在于，它不是先做版面分析再套规则，而是把整个页面当作视觉输入，交给一个 2.3B 参数的视觉语言模型去理解。模型看到了表格的边框，看到了标题的字号和位置，看到了列表的缩进关系，然后基于这些视觉线索生成 Markdown。这个思路更接近人眼阅读文档的方式，而不是按像素坐标生硬地切块。

1.1 传统解析到底会被哪些文档难住

我把常见问题分成四类，你在实际项目里大概率都遇到过：

• 扫描件和图片型 PDF：文本层不存在，OCR 结果经常把两栏文字混在一起，阅读顺序完全错乱。
• 复杂表格：合并单元格、跨页表头、无边框表格，规则解析基本无能为力。
• 多层级标题和嵌套列表：文本提取只能拿到一段连续字符串，标题和列表的从属关系需要靠排版坐标反推。
• 页眉页脚与正文混排：页码、公司名称、免责声明被当成正文抽出来，污染后续检索。

这些问题的本质是：传统方案在“看到”文档，而不是“理解”文档。视觉语言模型正好补上了这个缺口。当然，这里说的“理解”不是指理解文档语义，而是理解版面结构，知道哪些内容属于表格、哪些属于标题、哪些属于正文。

1.2 输出 Markdown 后，下游流程会顺很多

Markdown 是一种轻量级标记语言，但它同时具备人类可读和机器可解析两个优点。拿到 Markdown 之后，企业文档的很多下游流程会被明显简化：

• RAG 知识库可以直接按标题、表格、代码块做结构化切片，而不是按固定字数硬切。
• 大模型可以把 Markdown 当作文本语料输入，保留了标题层级和表格结构，理解能力会好很多。
• 技术文档、API 说明、操作手册可以近乎无损地发布到博客、Wiki 或者内部文档系统。
• 因为 Markdown 是纯文本，放在 Git 里可以做 diff，每次解析结果的变化都能被追踪到。

这也是为什么现在很多工作流都愿意用 Markdown 作为中间格式。从编辑器到转换工具，整条工具链都已经非常成熟。markdown 编辑器、markdown 转 Word、markdown 渲染 HTML，这些环节都可以直接接上，不需要额外开发解析器。你只需要把 parse-v5.0 的输出落成 .md 文件，剩下的展示、转换、归档都可以交给现成工具。

2. parse-v5.0 适合放在哪，又不适合做什么

先明确一个判断：parse-v5.0 是文档解析模型，不是通用对话模型。它的核心任务是“把文档变成 Markdown”，而不是“回答关于文档的问题”。如果你想做一个 PDF 问答机器人，parse-v5.0 应该用在前期把 PDF 转成干净文本，后续的问答能力还要交给另一个大模型来做。

这个定位其实很重要。很多人一看到“视觉语言模型”就期待过高，觉得它什么都能处理。但从工程角度看，把解析和问答拆成两个独立环节，反而更容易排查问题。解析输出质量差，就去调解析环节；回答质量差，就去调问答模型。如果混在一起，你根本不知道错误出在哪一层。

2.1 先分清需求是“看懂内容”还是“还原版面”

企业文档处理里有两种需求，经常被混为一谈：

• 看懂内容：关注文档讲什么，需要把正文、标题、表格内容准确提取出来，不要求视觉上和原页面一模一样。
• 还原版面：关注文档排成什么样，比如字体、颜色、位置、图片叠放关系，通常需要 PDF 转 Word 或者转网页，要求视觉效果尽量接近原稿。

parse-v5.0 输出 Markdown，定位更偏向第一种。Markdown 本身能表达结构，但表达不了像素级排版。如果你的场景是“把扫描合同里的条款转成可编辑文本”，它很合适；如果需求是“保持每一页排版一模一样再导出”，那你需要的不是 Markdown 解析模型，而是版面还原工具。

我在实际项目中还会再细分一层：即便只需要内容，也要区分“结构完整”和“内容完整”。有些文档的标题层级乱了，但正文文字都在；有些文档文字丢了几个字，但结构没问题。这两类问题对下游的影响完全不同，验收时要分开统计。

2.2 2.3B 参数意味着什么

这一点要客观看待。2.3B 在视觉语言模型里属于轻量级别，好处是服务端推理开销相对可控，请求延迟通常会比百亿、千亿参数模型低，适合高频批量处理。但代价是，它对复杂图表的数据理解、对长文档中细粒度逻辑关系的把握，不能和更大规模的模型直接比。

比如一份带复杂图表的年报，它能保证把标题、表格、正文抽出来，但“图表里某个数值是多少”这种推理任务，不一定稳定。实际使用时建议把它当做一个高质量文档解析引擎，而不是全能的文档理解大脑。需要做数值抽取和数据推理的，后面再接一个专门的表格解析或数据提取流程更稳妥。

3. 接入之前，先把这几类条件准备好

文档解析模型的接入本身不复杂，但前置条件一旦没理顺，后续排查会非常痛苦。我建议在第一次调用前，先按这几类清单逐个确认。这里给的是通用准备顺序，具体接口路径、参数和支持格式要以你拿到的官方文档为准，因为模型版本和服务商接口都可能调整。

3.1 输入文档的预处理

输入质量直接决定输出质量。parse-v5.0 虽然能直接读页面，但如果给它的是一份低分辨率扫描件，任何模型都很难还原内容。进入解析流程前，至少要确认：

• 文件格式：PDF、Word、图片还是其他格式，接口支持哪个就传哪个，不要把 PDF 硬改成 .txt 后缀。
• 扫描分辨率：扫描件建议控制在 200 DPI 到 300 DPI 之间。太低会糊，太高会明显增加传输时间和解析耗时。
• 页面数量：单次请求通常有页数限制，几十页的 PDF 建议按章节拆分，或者走异步任务接口。
• 文件是否加密：带密码的 PDF 必须提前解密，否则解析请求会直接失败。
• 文件名和路径：不要用中文逗号、空格、特殊符号，容易在脚本里造成路径问题。这个坑很小，但出现频率很高。

还有一点容易被忽略：扫描件的方向。如果原文档是横向表格，扫描出来却被旋转成了纵向，模型虽然能读，但表格的宽窄比例变了，解析结果的列顺序可能受影响。批量处理前，先抽样检查几份扫描件的方向和清晰度。

3.2 调用流程和返回结构

Cohere 的模型一般是走云端 API 方式调用。你提交文档，服务返回 Markdown 文本。调用流程通常分两步：先鉴权，再提交文档。鉴权用 API Key，提交时把文件内容放在请求体里。下面是一个通用风格的 Python 示例，帮你理解流程，实际接口路径和字段名请以官方文档为准：

import requests # 通用示例：实际 endpoint、字段名和版本号以官方文档为准 api_key = "your_api_key" endpoint = "https://api.example.com/v1/parse" headers = { "Authorization": f"Bearer {api_key}", } with open("sample.pdf", "rb") as f: resp = requests.post( endpoint, headers=headers, files={"file": f}, data={"version": "parse-v5.0"}, timeout=60, ) if resp.status_code == 200: result = resp.json() markdown_text = result.get("markdown", "") print(markdown_text[:500]) # 先看前 500 个字符 else: print(resp.status_code, resp.text)

如果文档比较大，同步请求容易超时，这时通常需要用异步任务模式：提交任务返回一个 job_id，然后轮询任务状态，任务完成后拿到 Markdown。这也是为什么建议把“单文档测试”和“批量任务”分开设计，后者的调用方式很可能不一样。我第一次接入时就是没注意这个区别，用同步方式批量提交大 PDF，结果连续超时，还以为是模型出问题了。

4. 从单个文档到批量任务，按这个顺序跑

我在实测这类模型时，一定会遵守一个原则：先跑单条，再跑小批，最后才上全量。不要一上来就把几百个 PDF 丢进脚本，因为一旦出问题，你根本分不清是文档本身的格式问题、模型参数问题，还是脚本逻辑问题。这个顺序虽然看起来慢，但其实是整套流程里最能省时间的部分。

4.1 最小验证流程

第一步，选一份有代表性的文档。不要选最简单的，也不要选最复杂的。选一份带标题、两个表格、一段多级列表的正常企业文档，这最能暴露解析能力。如果一上来就选纯文本 PDF，跑通了也没什么参考价值。

接着执行四步：

1. 用上面的脚本调用一次，确认鉴权和请求路径没问题。
2. 把返回的 Markdown 保存成 .md 文件。
3. 用 Markdown 编辑器打开，人工检查标题、表格、列表是否完整。
4. 如果这一步通过，再换第二份文档，验证不同类型文件的兼容性。

判断标准不是“接口返回了内容”，而是“返回的 Markdown 能不能直接作为下游输入使用”。我见过很多项目在第一步就卡住了，不是因为模型不行，而是因为返回内容里带着大段 JSON 包裹，或者换行符被转义，直接读成乱码。这些小问题在单文档测试阶段最容易暴露，越早发现越省事。

4.2 批量任务必须处理的四个点

单文档跑通后，批量任务要额外考虑四件事：

• 输入清单：不要直接遍历文件夹，先列出待处理文件清单，确认路径、格式、页数都符合要求。
• 输出命名：每个文档对应一个 .md 文件，命名要可追溯，最好保留原文件名。比如sample.pdf对应sample.md。
• 失败重试：网络请求一定会遇到超时和限流，要做重试机制。重试间隔用指数退避，比如第一次等 2 秒、第二次等 4 秒、第三次等 8 秒。
• 日志记录：每条任务处理成功还是失败、耗时多少、返回了多少字符，都要记下来。不要等跑完再回头看，中途就要能观察到异常。

import time from pathlib import Path inputs = list(Path("./docs").glob("*.pdf")) for path in inputs: output_path = Path("./output") / (path.stem + ".md") if output_path.exists(): continue # 已经处理过，跳过，方便断点续跑 for attempt in range(3): try: markdown_text = parse_file(path) # 封装好的解析调用 output_path.write_text(markdown_text, encoding="utf-8") break except TimeoutError: time.sleep(2 ** attempt) # 指数退避 else: log_failure(path)

上面这段代码里有一个很实用的细节：先检查输出文件是否已存在，再做任务，天然支持断点续跑。中途断了，重新执行脚本，已经处理完的文件会被跳过，不会浪费调用次数。批量任务最怕的就是跑到一半崩了，前功尽弃。这个“先判断再处理”的习惯，在所有需要调用外部 API 的场景都值得保留。

5. 拿到 Markdown 之后，怎么判断质量合不合格

很多人在这一步会犯同一个错误：用肉眼扫一眼，觉得“好像没问题”，就直接接进下游。但实际上，Markdown 质量需要用一套固定标准来验收，否则下游的检索质量、模型回答质量都会莫名其妙地变差，而且很难定位到解析环节。

这里也提醒一句，Markdown 的换行规则在不同编辑器里表现不一致。Typora 里按一次回车是一个软换行，普通文本查看器里可能就是一段连续文字。验收时不要因为换行符的显示差异，就把一个正常结果误判成异常。

5.1 用编辑器预览和渲染检查

拿到 Markdown 后，第一件事是用编辑器打开，而不是直接看纯文本。Typora、VSCode 上装一个 Markdown 插件，或者用 markdown 渲染 HTML 的工具，都能把表格、标题、列表结构可视化。这一步能快速发现纯文本里看不出来的问题。

如果你遇到 Typora 里打开了新文件但没反应，先看是不是已经有一个实例在运行。这个问题和解析模型完全无关，但在验收流程里很容易出现，容易让人误以为是文件有问题。我一般会同时在 VSCode 的预览窗口里再开一次，两台编辑器交叉确认，基本能排除工具层面的干扰。

如果是 markdown 转 Word 的工作流，建议在转换后检查页面的标题层级是否保留。很多时候表格复制到 Word 里会变形，这不是解析模型的错，而是转换流程的兼容性问题，但你要能区分出来。否则很容易白白去调模型参数，最后发现瓶颈在转换工具。

5.2 质量维度和常见问题

我习惯用一个简单表格来做验收，每份文档测完逐项打勾：

如果一个模型在六七个维度上都能稳定通过，这个解析质量才算够用。如果只是偶尔一次表现好，不能算数，要连续测试多份文档。我建议把验收结果记下来，形成一个简单的质量记录表。这样后面不管换了模型版本还是调整了输入文档，都能对照历史结果，知道质量是变好了还是变差了。

6. 常见报错和排查顺序

接入 parse-v5.0 这类模型时，报错不可怕，可怕的是不知道从哪里查起。我建议按“输入 → 服务 → 输出”的顺序排查，这个顺序覆盖了绝大多数情况，而且每一步都不依赖外部工具，自己就能做判断。

6.1 直接按这个链路查

先看输入。文件是不是真的存在？格式是不是接口支持的？PDF 是不是加密的？扫描件分辨率够不够？如果脚本报路径不存在、文件被拒绝，90% 的问题在输入环节。这一步不要急着怀疑模型，先在本地把文件打开看一眼，很多问题就消失了。

再看服务。API Key 是否正确？请求是否超时？是否触发限流？如果返回 401，大概率是鉴权问题；如果返回 429，是并发太高，需要降速或重试；如果超时，先确认文档是不是太大，是不是需要换异步接口。服务端错误一般都会有响应码，把响应码和响应体完整记下来，排查效率会高很多。

最后看输出。返回内容为空，先确认上传的文件是不是空文件；Markdown 被截断，先看是不是触发了页数或字符上限；内容有乱码，先看文件编码和传输方式。输出阶段的问题，大多数都能通过打印原始返回内容找到原因，而不是靠猜。

6.2 几个容易误判的坑

有些问题看起来很像是模型能力问题，实际上不是。

• 空输出：先检查输入文档是否正常。我之前遇到过脚本传了个损坏的 PDF，模型正常返回了空文本，查了半天才发现是源文件坏了。
• Markdown 渲染异常：文件本身没问题，但编辑器没识别。这时候换一个 markdown 编辑器再打开，别急着怀疑模型。
• 文本顺序错乱：如果原文是双栏扫描件，可能是扫描分辨率太低，导致视觉模型误判阅读顺序。先把 PDF 按 300 DPI 重新导出，再跑一次。
• 表格数据缺失：可能是表格带了底色、水印或者有跨页情况，先确认表格在原文档里的完整性。

排查的时候，我一般会保留一份原始解析结果和一份“人工修正后的结果”做对比。这个对照集不仅能帮你定位问题，后面换模型版本时也能用来做回归测试。文档解析的很多问题，不是靠看单个报错能发现的，而是要有一个对比基线。

7. 生产化落地还要补的几块内容

如果 parse-v5.0 只是拿来偶尔转几个文件，前面六节的内容基本够了。但如果是把它接入企业文档处理流程，要长期运行，那还需要把工程化的事情补齐。

7.1 建立一个小规模评估集

不要靠感觉判断模型质量。挑 20 到 50 份覆盖不同场景的典型文档，做成固定测试集，每份文档标注出关键结构：标题层级、表格数量、列表嵌套关系。每次模型升级、参数调整、输入格式变化，都用这套测试集跑一遍，对比输出是否退化。

评估集不需要很大，但一定要稳定。它解决的是一个很棘手的问题：模型好像在变好，但你不知道它是不是在另一个文档上变差了。有了评估集，任何变化都能量化，而不是停留在“感觉还行”这个模糊判断上。

7.2 成本、速度和失败率怎么权衡

批量处理到一定程度，成本可能比性能更值得关注。几个建议：

• 处理过的结果落盘缓存，避免重复调用。比如同一份 PDF 已经转出 Markdown，就直接读取缓存，不用再请求一次。
• 并发数不要直接拉满。先跑 5 个并发，看失败率和响应时间，再逐步加到 10、20。限流报错比串行处理更浪费时间。
• 对失败任务做分类统计。是超时、鉴权、还是格式问题，分类信息比“失败 100 条”这样的数字有用得多。
• 企业文档可能包含敏感信息，接入前后要确认数据存储位置、传输加密和访问权限，不要等到出了问题再回头补。

如果自建应用需要把解析结果直接展示给用户，可以复用前端那些成熟的 Markdown 渲染组件，尤其是流式输出场景里用过的渲染器，很多开源实现都能直接用。核心思路依然是：模型只负责产出 Markdown，展示端做好渲染适配即可，不要让业务逻辑依赖某一种固定渲染方式。

最后一件事，也是最容易被忽略的：解析模型输出的 Markdown 只是中间产物，不是最终交付。真正稳定的流程应该是“原始文档 → 解析 → 校验 → 入库”，每个环节都要有日志和回滚方案。这样即使模型突然换了版本，你也能快速定位是哪个环节出了问题。

我个人更建议先把单文档跑稳，再做小批量验证，最后才谈并发和接口化。文档解析这个领域，真正卡住项目的从来都不是模型能不能跑，而是输入准备、输出校验和失败重试这三点有没有做扎实。