文档解析这个环节过去很长一段时间都是“能做但做得不彻底”。尤其是企业内部大量 PDF、扫描件、表格和多栏排版的文档传统文本抽取和 OCR 方案往往要么丢掉层级结构要么把表格拆得稀碎数据一旦进入大模型或知识库问题就会被下游无限放大。Cohere 这次发布的 Parse 5parse-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: fBearer {api_key}, } with open(sample.pdf, rb) as f: resp requests.post( endpoint, headersheaders, files{file: f}, data{version: parse-v5.0}, timeout60, ) 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跑通了也没什么参考价值。接着执行四步用上面的脚本调用一次确认鉴权和请求路径没问题。把返回的 Markdown 保存成 .md 文件。用 Markdown 编辑器打开人工检查标题、表格、列表是否完整。如果这一步通过再换第二份文档验证不同类型文件的兼容性。判断标准不是“接口返回了内容”而是“返回的 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, encodingutf-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 质量维度和常见问题我习惯用一个简单表格来做验收每份文档测完逐项打勾检查维度通过标准常见不通过表现标题层级H1/H2/H3 关系与原文一致所有标题被压成同一级表格结构行列数、合并单元格基本保留表格被拆成多段文本列表嵌套缩进和层级关系正确子列表丢失缩进代码块原文代码块有明确围栏代码被当成普通段落特殊字符货币符号、单位、转义符不丢失出现乱码或缺失内容顺序多栏文档阅读顺序正确左右栏内容交叉混排如果一个模型在六七个维度上都能稳定通过这个解析质量才算够用。如果只是偶尔一次表现好不能算数要连续测试多份文档。我建议把验收结果记下来形成一个简单的质量记录表。这样后面不管换了模型版本还是调整了输入文档都能对照历史结果知道质量是变好了还是变差了。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 只是中间产物不是最终交付。真正稳定的流程应该是“原始文档 → 解析 → 校验 → 入库”每个环节都要有日志和回滚方案。这样即使模型突然换了版本你也能快速定位是哪个环节出了问题。我个人更建议先把单文档跑稳再做小批量验证最后才谈并发和接口化。文档解析这个领域真正卡住项目的从来都不是模型能不能跑而是输入准备、输出校验和失败重试这三点有没有做扎实。 Cohere Parse 5：用视觉语言模型把文档解析成Markdown
文档解析这个环节过去很长一段时间都是“能做但做得不彻底”。尤其是企业内部大量 PDF、扫描件、表格和多栏排版的文档传统文本抽取和 OCR 方案往往要么丢掉层级结构要么把表格拆得稀碎数据一旦进入大模型或知识库问题就会被下游无限放大。Cohere 这次发布的 Parse 5parse-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: fBearer {api_key}, } with open(sample.pdf, rb) as f: resp requests.post( endpoint, headersheaders, files{file: f}, data{version: parse-v5.0}, timeout60, ) 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跑通了也没什么参考价值。接着执行四步用上面的脚本调用一次确认鉴权和请求路径没问题。把返回的 Markdown 保存成 .md 文件。用 Markdown 编辑器打开人工检查标题、表格、列表是否完整。如果这一步通过再换第二份文档验证不同类型文件的兼容性。判断标准不是“接口返回了内容”而是“返回的 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, encodingutf-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 质量维度和常见问题我习惯用一个简单表格来做验收每份文档测完逐项打勾检查维度通过标准常见不通过表现标题层级H1/H2/H3 关系与原文一致所有标题被压成同一级表格结构行列数、合并单元格基本保留表格被拆成多段文本列表嵌套缩进和层级关系正确子列表丢失缩进代码块原文代码块有明确围栏代码被当成普通段落特殊字符货币符号、单位、转义符不丢失出现乱码或缺失内容顺序多栏文档阅读顺序正确左右栏内容交叉混排如果一个模型在六七个维度上都能稳定通过这个解析质量才算够用。如果只是偶尔一次表现好不能算数要连续测试多份文档。我建议把验收结果记下来形成一个简单的质量记录表。这样后面不管换了模型版本还是调整了输入文档都能对照历史结果知道质量是变好了还是变差了。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 只是中间产物不是最终交付。真正稳定的流程应该是“原始文档 → 解析 → 校验 → 入库”每个环节都要有日志和回滚方案。这样即使模型突然换了版本你也能快速定位是哪个环节出了问题。我个人更建议先把单文档跑稳再做小批量验证最后才谈并发和接口化。文档解析这个领域真正卡住项目的从来都不是模型能不能跑而是输入准备、输出校验和失败重试这三点有没有做扎实。