做文档解析方案调研时Cohere 推出的 Parse 服务引起了我的注意。它的核心卖点很直接把 PDF、Word、扫描件这类非结构化文档转成结构化数据而定价只有同类产品的零头。对于需要批量处理合同、研究报告、技术手册的团队来说解析成本往往是上线前最容易被低估的一笔开销。这篇文章会从 Cohere Parse 的定位入手讲清楚它的核心能力、调用方式再给出完整的 Python 实战示例和成本对比思路。1. 为什么要关注文档解析与 Cohere Parse1.1 文档解析在业务中的位置先聊一个非常普遍的业务场景。企业内部往往积累了大量的 PDF 合同、Word 技术文档、扫描版发票、财报和研究报告。这些文件内容虽然是“文字”但如果不经过解析它们对系统来说就是一堆无法检索的二进制数据。要把这些内容变成知识库、RAG 检索、数据中台或自动化流程的输入第一步就是把文档内容抽取出来并尽量保留表格、标题层级、图片位置等结构化信息。这就是文档解析服务的核心价值把“给人看的文档”转成“给程序用的数据”。传统做法是自己写解析器用 PDF 库或者正则去抓文本。这种方式在文档格式统一、量级不大时问题不大但一旦遇到多栏排版、扫描件、复杂表格、页眉页脚混排解析效果就会很不稳定而且每个新文档类型都要单独调规则。1.2 Cohere Parse 是什么Cohere Parse 是 Cohere 提供的文档解析 API主要解决“从非结构化文档中提取结构化内容”的问题。它面向的是 RAG、知识库、文档处理流水线这类场景可以直接把 PDF 等文件发送到接口得到包含正文文本、表格信息和图片信息的结构化结果。相比自建解析方案这类托管 API 的好处很明显不需要自己维护 OCR 和文档解析模型。对复杂版式、扫描件、表格的兼容性更好。输出格式统一方便接下游系统。按调用量付费不需要一次性购买 GPU 或部署推理服务。最吸引人的地方在于定价。从目前公开信息看Cohere Parse 的按页价格远低于同类文档解析服务实际成本需要根据官方定价页确认但整体量级确实比其他厂商低很多。这意味着企业内部做文档量级较大的解析需求时可以更从容地控制预算。1.3 与常见解析报错不是一回事在调研过程中我还注意到一个容易混淆的问题。日常开发中“解析失败”这个词出现频率很高但不同技术栈的解析错误含义完全不同。比如 Java 服务里常见的feignclient failed to parse multipart servlet request是文件上传请求体解析失败Android 安装时报INSTALL_PARSE_FAILED_UNEXPECTED_EXCEPTION是安装包解析异常前端打包时报module parse failed: unexpected token是 Webpack 无法理解模块语法还有JSON parse error: cannot deserialize value of type是 JSON 反序列化类型不匹配。这些问题都属于各自技术栈里的“格式解析”问题解决思路和 Cohere Parse 没有直接关系。Cohere Parse 解决的是自然语言文档层面的内容结构化抽取比如从一份 PDF 里提取正文、表格、标题层级。理解这个边界有助于在技术选型时避免拿错工具。2. 环境准备与版本说明在使用 Cohere Parse 之前需要准备环境并确认版本依赖。本文示例环境如下操作系统macOS / Linux / Windows 均可命令差别不大编程语言Python 3.9 及以上HTTP 请求库requests文件类型PDF、DOCX 等常见文档格式需要特别说明的是Cohere 的 API 版本和 SDK 方法名会持续更新本文示例以 REST API 请求为主这样对版本依赖最小。如果你使用官方 Python SDK请以你安装的 SDK 版本对应的文档为准。2.1 获取 API Key使用 Cohere API 需要先注册账号并创建 API Key。创建 Key 后在本地环境设置环境变量不要在代码里硬编码密钥export COHERE_API_KEYyour_cohere_api_keyWindows 环境可以使用set COHERE_API_KEYyour_cohere_api_key2.2 项目结构本文的实战示例项目结构如下cohere-parse-demo/ ├── docs/ # 待解析的文档目录 │ ├── 合同扫描件.pdf │ └── 技术方案.pdf ├── output/ # 解析结果输出目录 ├── parse_single.py # 单文件解析脚本 ├── parse_batch.py # 批量解析脚本 └── requirements.txt创建目录并安装依赖mkdir -p cohere-parse-demo/docs cohere-parse-demo/output cd cohere-parse-demo pip install requests依赖比较轻只需要 requests。3. Cohere Parse 核心能力拆解3.1 支持的文件类型与输出内容Cohere Parse 主要面向文档类文件最常见的输入是 PDF。从实际使用角度看它适合处理以下几类内容内容类型典型来源解析目标合同协议扫描件、电子 PDF合同编号、条款、金额、日期技术文档Word 导出的 PDF正文、标题、代码块研究报告券商研报、行业报告图表标题、段落、结论知识库素材公司内部 wiki 导出可检索的纯文本输出内容通常包括文档正文文本。表格结构化数据。文档中的图片信息。标题或区块信息。具体返回字段取决于 API 版本和请求参数本文会给出一个典型结构供参考。实际开发时要以官方文档和真实响应为准。3.2 计费模型与对比维度Cohere Parse 定价低主要体现在按页计费模式上。和竞品对比时不要只看单价建议从以下几个维度综合评估对比维度说明每千页价格最直观的定价指标免费额度初期测试阶段是否够用批量折扣量大时是否有阶梯价输出结构是否包含表格、图片、标题等结构化字段是否支持 OCR扫描件是否需要额外付费并发限制是否影响大批量处理效率在内部对比时建议先准备 100 页真实业务文档分别用候选服务跑一遍统计总费用。解析成功率。文本抽取准确率。表格还原程度。单页平均耗时。用真实数据算成本比看宣传页上的单价更有参考价值。按目前公开信息来看Cohere Parse 的单页价格在同类型服务中处于非常有竞争力的水平这也是它近期受关注的主要原因。4. 完整实战用 Python 调用 Cohere Parse 解析 PDF下面进入实操环节。我们用 REST API 的方式调用 Cohere Parse完成单文件解析和批量解析两个场景。4.1 单文件解析脚本先写一个最简单的单文件解析脚本parse_single.py。# 文件路径cohere-parse-demo/parse_single.py import os import sys import requests API_KEY os.environ.get(COHERE_API_KEY) API_URL https://api.cohere.com/v1/parse if not API_KEY: print(请先设置 COHERE_API_KEY 环境变量) sys.exit(1) def parse_document(file_path: str) - dict: headers { Authorization: fBearer {API_KEY}, } with open(file_path, rb) as f: files { file: (file_path.split(/)[-1], f, application/pdf), } response requests.post( API_URL, headersheaders, filesfiles, timeout120, ) print(HTTP 状态码:, response.status_code) if response.status_code 200: return response.json() else: print(请求失败错误信息, response.text) return {} if __name__ __main__: file_path ./docs/合同扫描件.pdf if len(sys.argv) 1: file_path sys.argv[1] result parse_document(file_path) print(解析结果) print(result)这段代码做的事情是从环境变量读取 API Key。以 multipart/form-data 方式上传文件。打印 HTTP 状态码。成功时返回 JSON 结果失败时打印服务端错误信息。运行方式python parse_single.py ./docs/合同扫描件.pdf如果文件路径包含中文注意控制台编码建议使用英文文件名或在代码中显式处理编码问题。4.2 解析结果说明成功返回的 JSON 结构与 API 版本相关典型响应如下{ document: { text: 合同编号HT-2025-001\n甲方北京某某科技有限公司\n乙方上海某某信息技术有限公司\n..., tables: [ { title: 付款计划, rows: [ [阶段, 金额, 时间], [预付款, 100000, 2025-03-01] ] } ], images: [ { page: 2, caption: 项目架构图 } ] } }需要注意不同版本的 API 返回字段名可能不同前期联调时一定要先打印真实响应确认字段再写解析逻辑。不要假设字段一定存在建议做空值保护text result.get(document, {}).get(text, ) if not text: print(未提取到正文文本)4.3 批量解析多个文件实际生产场景通常不会只解析一个文件而是需要批量处理某个目录下的所有 PDF。下面是一个批量解析脚本parse_batch.py。# 文件路径cohere-parse-demo/parse_batch.py import json import os import time from pathlib import Path import requests API_KEY os.environ.get(COHERE_API_KEY) API_URL https://api.cohere.com/v1/parse def parse_file(file_path: Path) - dict: headers { Authorization: fBearer {API_KEY}, } with open(file_path, rb) as f: files { file: (file_path.name, f, application/pdf), } response requests.post( API_URL, headersheaders, filesfiles, timeout120, ) if response.status_code 200: return response.json() else: print(f[失败] {file_path.name}: {response.status_code} {response.text}) return {} def main(docs_dir: str, output_dir: str) - None: doc_dir Path(docs_dir) output_path Path(output_dir) output_path.mkdir(parentsTrue, exist_okTrue) pdf_files list(doc_dir.glob(*.pdf)) print(f发现 {len(pdf_files)} 个 PDF 文件) all_results {} for index, pdf_file in enumerate(pdf_files, start1): print(f[{index}/{len(pdf_files)}] 正在解析: {pdf_file.name}) all_results[pdf_file.name] parse_file(pdf_file) # 避免请求过快触发速率限制 time.sleep(0.5) # 保存全部结果到 JSON 文件 output_file output_path / parse_results.json with open(output_file, w, encodingutf-8) as f: json.dump(all_results, f, ensure_asciiFalse, indent2) print(f解析完成结果已保存到: {output_file}) if __name__ __main__: main(./docs, ./output)这段代码比单文件脚本多了几个关键处理使用Path.glob自动发现目录下所有 PDF 文件。每个文件之间加time.sleep(0.5)避免触发并发限制。将所有结果汇总后保存到output/parse_results.json。运行方式python parse_batch.py4.4 将解析结果写入结构化文件拿到 JSON 结果后通常还需要把结果转成更易用的格式。下面是一个简单的处理逻辑把文本和表格写入 Markdown 文件方便直接进入知识库。# 文件路径cohere-parse-demo/convert_to_markdown.py import json from pathlib import Path INPUT_FILE ./output/parse_results.json OUTPUT_DIR Path(./output/markdown) def convert_to_markdown(result: dict, output_dir: Path) - None: output_dir.mkdir(parentsTrue, exist_okTrue) for filename, data in result.items(): doc data.get(document, {}) text doc.get(text, ) tables doc.get(tables, []) md_lines [] # 写入正文文本 md_lines.append(# 文档正文\n) md_lines.append(text) md_lines.append(\n) # 写入表格 if tables: md_lines.append(\n## 表格\n) for table in tables: title table.get(title, 未命名表格) rows table.get(rows, []) md_lines.append(f\n### {title}\n) if rows: header | | .join(rows[0]) | separator | | .join([---] * len(rows[0])) | md_lines.append(header) md_lines.append(separator) for row in rows[1:]: md_lines.append(| | .join(row) |) md_file output_dir / f{Path(filename).stem}.md md_file.write_text(\n.join(md_lines), encodingutf-8) print(f已生成: {md_file}) if __name__ __main__: with open(INPUT_FILE, encodingutf-8) as f: results json.load(f) convert_to_markdown(results, OUTPUT_DIR)这段代码最大的作用是打通“API 返回 JSON → 知识库可用的 Markdown 文件”这条链路。实际操作时你可以根据自己的下游系统调整输出格式比如写入数据库、搭建向量索引、导入 Dify 或 FastGPT。5. 常见问题与排查思路使用 Cohere Parse 时最常遇到的问题集中在认证、文件格式、响应结构、限流和成本控制几个方面。问题现象常见原因解决思路401 UnauthorizedAPI Key 错误或未正确传递检查环境变量确认 Key 未过期400 请求错误文件格式不支持或请求参数有误确认文件类型检查 API 文档请求超时文件过大或网络不稳定拆分文档适当调大 timeout并发受限超过免费额度或速率限制增加请求间隔批量任务串行处理返回文本为空扫描件未启用 OCR 或页面无文字信息确认文档是否包含可提取文本解析结果字段不全API 版本不同导致字段名变化打印完整 JSON按实际字段开发5.1 认证与网络问题如果请求返回 401先检查环境变量是否真的设置成功。echo $COHERE_API_KEY不要在代码里写死 Key。如果你在公司环境还需要确认网络是否能访问api.cohere.com。5.2 文件格式问题Cohere Parse 对文件大小和页数通常有限制。如果文件过大建议先拆分后再上传。拆 PDF 可以用 pypdf 这类工具# 拆分 PDF 示例按需安装 pypdf from pypdf import PdfReader, PdfWriter reader PdfReader(large.pdf) for i in range(len(reader.pages)): writer PdfWriter() writer.add_page(reader.pages[i]) with open(fpage_{i1}.pdf, wb) as f: writer.write(f)5.3 解析质量与超长文档处理扫描件解析效果取决于底层 OCR 能力对于清晰度较低的扫描件解析出的文本可能存在乱码或错字。生产环境建议优先上传电子版 PDF而非扫描件。对扫描件先做图像预处理比如提高对比度。设置解析结果人工抽检比例尤其是合同、法律文书类场景。对于超长文档建议分批上传避免单次请求数据量过大导致超时。每个 API 的页数上限可能不同需要根据实际响应调整批大小。5.4 成本控制与限流Cohere Parse 价格低但批量调用之后费用仍然会累积。建议在调用日志中记录每个文件的页数、token 数或计费单位方便核算成本。如果触发限流增加调用间隔是最简单的缓解方式。也可以使用指数退避策略import time retry_count 3 for attempt in range(retry_count): try: response requests.post(API_URL, headersheaders, filesfiles, timeout120) if response.status_code 200: break elif response.status_code 429: wait_time 2 ** attempt print(f触发限流等待 {wait_time} 秒后重试) time.sleep(wait_time) else: break except requests.RequestException as e: print(f请求异常: {e}) time.sleep(2)6. 最佳实践与工程建议6.1 API Key 管理不要在代码、配置文件或前端代码中暴露 API Key。推荐做法通过环境变量注入。使用云厂商的密钥管理服务。定期轮换 Key。按项目拆分 Key方便追踪调用来源。示例import os API_KEY os.environ.get(COHERE_API_KEY)6.2 文件预处理上传前检查文件是否损坏、是否为空白页、页数是否超限。预处理可以显著提高解析成功率和质量from pypdf import PdfReader try: reader PdfReader(document.pdf) page_count len(reader.pages) print(f页数: {page_count}) if page_count 0: print(文件为空跳过) except Exception as e: print(f文件读取失败: {e})6.3 异步任务与队列大批量解析场景下不建议在请求线程里同步等待解析结果。更合理的方式是上传文件到对象存储。将解析任务写入消息队列。由后台 Worker 调用 Cohere Parse。将结果写回数据库或对象存储。前端通过任务状态查询结果。这样做的好处是避免接口超时同时方便失败重试。6.4 结果缓存同一个文件可能会被多次解析尤其是测试和联调阶段。建议以文件哈希作为缓存 key避免重复调用产生费用import hashlib def file_md5(file_path: str) - str: md5 hashlib.md5() with open(file_path, rb) as f: for chunk in iter(lambda: f.read(4096), b): md5.update(chunk) return md5.hexdigest()解析前先查缓存命中则直接返回结果。6.5 成本观测建议把每次调用的以下信息记录到日志中文件名。文件大小。页数。解析耗时。计费单位页数或其他口径。成功率。有了这些数据就能按业务线拆分成本提前发现异常调用。7. 总结Cohere Parse 把文档解析的门槛和成本都拉到了一个新的位置。对于需要接入 RAG、知识库或文档中台的团队来说它是一个值得认真评估的选项。本文从概念、环境、代码到排查思路做了完整梳理核心内容可以归纳为几点Cohere Parse 解决的是非结构化文档到结构化数据的转换问题。使用 REST API 调用最通用对 SDK 版本依赖最小。批量调用时要考虑限流、缓存和成本观测。文档格式、扫描件质量直接影响解析效果预处理非常重要。定价对比不要只看单价要用真实业务文档做小规模验证。下一步你可以根据自己的业务文档类型先拿 100 页真实样本跑一轮对比测试把成本、准确率和耗时三个指标记录下来。数据比任何宣传都可靠测试通过后再设计正式的解析流水线。如果这篇文章对你有帮助可以收藏备用后续有新的文档解析经验我也会继续补充。
Cohere Parse文档解析实战：低成本提取PDF结构化数据
做文档解析方案调研时Cohere 推出的 Parse 服务引起了我的注意。它的核心卖点很直接把 PDF、Word、扫描件这类非结构化文档转成结构化数据而定价只有同类产品的零头。对于需要批量处理合同、研究报告、技术手册的团队来说解析成本往往是上线前最容易被低估的一笔开销。这篇文章会从 Cohere Parse 的定位入手讲清楚它的核心能力、调用方式再给出完整的 Python 实战示例和成本对比思路。1. 为什么要关注文档解析与 Cohere Parse1.1 文档解析在业务中的位置先聊一个非常普遍的业务场景。企业内部往往积累了大量的 PDF 合同、Word 技术文档、扫描版发票、财报和研究报告。这些文件内容虽然是“文字”但如果不经过解析它们对系统来说就是一堆无法检索的二进制数据。要把这些内容变成知识库、RAG 检索、数据中台或自动化流程的输入第一步就是把文档内容抽取出来并尽量保留表格、标题层级、图片位置等结构化信息。这就是文档解析服务的核心价值把“给人看的文档”转成“给程序用的数据”。传统做法是自己写解析器用 PDF 库或者正则去抓文本。这种方式在文档格式统一、量级不大时问题不大但一旦遇到多栏排版、扫描件、复杂表格、页眉页脚混排解析效果就会很不稳定而且每个新文档类型都要单独调规则。1.2 Cohere Parse 是什么Cohere Parse 是 Cohere 提供的文档解析 API主要解决“从非结构化文档中提取结构化内容”的问题。它面向的是 RAG、知识库、文档处理流水线这类场景可以直接把 PDF 等文件发送到接口得到包含正文文本、表格信息和图片信息的结构化结果。相比自建解析方案这类托管 API 的好处很明显不需要自己维护 OCR 和文档解析模型。对复杂版式、扫描件、表格的兼容性更好。输出格式统一方便接下游系统。按调用量付费不需要一次性购买 GPU 或部署推理服务。最吸引人的地方在于定价。从目前公开信息看Cohere Parse 的按页价格远低于同类文档解析服务实际成本需要根据官方定价页确认但整体量级确实比其他厂商低很多。这意味着企业内部做文档量级较大的解析需求时可以更从容地控制预算。1.3 与常见解析报错不是一回事在调研过程中我还注意到一个容易混淆的问题。日常开发中“解析失败”这个词出现频率很高但不同技术栈的解析错误含义完全不同。比如 Java 服务里常见的feignclient failed to parse multipart servlet request是文件上传请求体解析失败Android 安装时报INSTALL_PARSE_FAILED_UNEXPECTED_EXCEPTION是安装包解析异常前端打包时报module parse failed: unexpected token是 Webpack 无法理解模块语法还有JSON parse error: cannot deserialize value of type是 JSON 反序列化类型不匹配。这些问题都属于各自技术栈里的“格式解析”问题解决思路和 Cohere Parse 没有直接关系。Cohere Parse 解决的是自然语言文档层面的内容结构化抽取比如从一份 PDF 里提取正文、表格、标题层级。理解这个边界有助于在技术选型时避免拿错工具。2. 环境准备与版本说明在使用 Cohere Parse 之前需要准备环境并确认版本依赖。本文示例环境如下操作系统macOS / Linux / Windows 均可命令差别不大编程语言Python 3.9 及以上HTTP 请求库requests文件类型PDF、DOCX 等常见文档格式需要特别说明的是Cohere 的 API 版本和 SDK 方法名会持续更新本文示例以 REST API 请求为主这样对版本依赖最小。如果你使用官方 Python SDK请以你安装的 SDK 版本对应的文档为准。2.1 获取 API Key使用 Cohere API 需要先注册账号并创建 API Key。创建 Key 后在本地环境设置环境变量不要在代码里硬编码密钥export COHERE_API_KEYyour_cohere_api_keyWindows 环境可以使用set COHERE_API_KEYyour_cohere_api_key2.2 项目结构本文的实战示例项目结构如下cohere-parse-demo/ ├── docs/ # 待解析的文档目录 │ ├── 合同扫描件.pdf │ └── 技术方案.pdf ├── output/ # 解析结果输出目录 ├── parse_single.py # 单文件解析脚本 ├── parse_batch.py # 批量解析脚本 └── requirements.txt创建目录并安装依赖mkdir -p cohere-parse-demo/docs cohere-parse-demo/output cd cohere-parse-demo pip install requests依赖比较轻只需要 requests。3. Cohere Parse 核心能力拆解3.1 支持的文件类型与输出内容Cohere Parse 主要面向文档类文件最常见的输入是 PDF。从实际使用角度看它适合处理以下几类内容内容类型典型来源解析目标合同协议扫描件、电子 PDF合同编号、条款、金额、日期技术文档Word 导出的 PDF正文、标题、代码块研究报告券商研报、行业报告图表标题、段落、结论知识库素材公司内部 wiki 导出可检索的纯文本输出内容通常包括文档正文文本。表格结构化数据。文档中的图片信息。标题或区块信息。具体返回字段取决于 API 版本和请求参数本文会给出一个典型结构供参考。实际开发时要以官方文档和真实响应为准。3.2 计费模型与对比维度Cohere Parse 定价低主要体现在按页计费模式上。和竞品对比时不要只看单价建议从以下几个维度综合评估对比维度说明每千页价格最直观的定价指标免费额度初期测试阶段是否够用批量折扣量大时是否有阶梯价输出结构是否包含表格、图片、标题等结构化字段是否支持 OCR扫描件是否需要额外付费并发限制是否影响大批量处理效率在内部对比时建议先准备 100 页真实业务文档分别用候选服务跑一遍统计总费用。解析成功率。文本抽取准确率。表格还原程度。单页平均耗时。用真实数据算成本比看宣传页上的单价更有参考价值。按目前公开信息来看Cohere Parse 的单页价格在同类型服务中处于非常有竞争力的水平这也是它近期受关注的主要原因。4. 完整实战用 Python 调用 Cohere Parse 解析 PDF下面进入实操环节。我们用 REST API 的方式调用 Cohere Parse完成单文件解析和批量解析两个场景。4.1 单文件解析脚本先写一个最简单的单文件解析脚本parse_single.py。# 文件路径cohere-parse-demo/parse_single.py import os import sys import requests API_KEY os.environ.get(COHERE_API_KEY) API_URL https://api.cohere.com/v1/parse if not API_KEY: print(请先设置 COHERE_API_KEY 环境变量) sys.exit(1) def parse_document(file_path: str) - dict: headers { Authorization: fBearer {API_KEY}, } with open(file_path, rb) as f: files { file: (file_path.split(/)[-1], f, application/pdf), } response requests.post( API_URL, headersheaders, filesfiles, timeout120, ) print(HTTP 状态码:, response.status_code) if response.status_code 200: return response.json() else: print(请求失败错误信息, response.text) return {} if __name__ __main__: file_path ./docs/合同扫描件.pdf if len(sys.argv) 1: file_path sys.argv[1] result parse_document(file_path) print(解析结果) print(result)这段代码做的事情是从环境变量读取 API Key。以 multipart/form-data 方式上传文件。打印 HTTP 状态码。成功时返回 JSON 结果失败时打印服务端错误信息。运行方式python parse_single.py ./docs/合同扫描件.pdf如果文件路径包含中文注意控制台编码建议使用英文文件名或在代码中显式处理编码问题。4.2 解析结果说明成功返回的 JSON 结构与 API 版本相关典型响应如下{ document: { text: 合同编号HT-2025-001\n甲方北京某某科技有限公司\n乙方上海某某信息技术有限公司\n..., tables: [ { title: 付款计划, rows: [ [阶段, 金额, 时间], [预付款, 100000, 2025-03-01] ] } ], images: [ { page: 2, caption: 项目架构图 } ] } }需要注意不同版本的 API 返回字段名可能不同前期联调时一定要先打印真实响应确认字段再写解析逻辑。不要假设字段一定存在建议做空值保护text result.get(document, {}).get(text, ) if not text: print(未提取到正文文本)4.3 批量解析多个文件实际生产场景通常不会只解析一个文件而是需要批量处理某个目录下的所有 PDF。下面是一个批量解析脚本parse_batch.py。# 文件路径cohere-parse-demo/parse_batch.py import json import os import time from pathlib import Path import requests API_KEY os.environ.get(COHERE_API_KEY) API_URL https://api.cohere.com/v1/parse def parse_file(file_path: Path) - dict: headers { Authorization: fBearer {API_KEY}, } with open(file_path, rb) as f: files { file: (file_path.name, f, application/pdf), } response requests.post( API_URL, headersheaders, filesfiles, timeout120, ) if response.status_code 200: return response.json() else: print(f[失败] {file_path.name}: {response.status_code} {response.text}) return {} def main(docs_dir: str, output_dir: str) - None: doc_dir Path(docs_dir) output_path Path(output_dir) output_path.mkdir(parentsTrue, exist_okTrue) pdf_files list(doc_dir.glob(*.pdf)) print(f发现 {len(pdf_files)} 个 PDF 文件) all_results {} for index, pdf_file in enumerate(pdf_files, start1): print(f[{index}/{len(pdf_files)}] 正在解析: {pdf_file.name}) all_results[pdf_file.name] parse_file(pdf_file) # 避免请求过快触发速率限制 time.sleep(0.5) # 保存全部结果到 JSON 文件 output_file output_path / parse_results.json with open(output_file, w, encodingutf-8) as f: json.dump(all_results, f, ensure_asciiFalse, indent2) print(f解析完成结果已保存到: {output_file}) if __name__ __main__: main(./docs, ./output)这段代码比单文件脚本多了几个关键处理使用Path.glob自动发现目录下所有 PDF 文件。每个文件之间加time.sleep(0.5)避免触发并发限制。将所有结果汇总后保存到output/parse_results.json。运行方式python parse_batch.py4.4 将解析结果写入结构化文件拿到 JSON 结果后通常还需要把结果转成更易用的格式。下面是一个简单的处理逻辑把文本和表格写入 Markdown 文件方便直接进入知识库。# 文件路径cohere-parse-demo/convert_to_markdown.py import json from pathlib import Path INPUT_FILE ./output/parse_results.json OUTPUT_DIR Path(./output/markdown) def convert_to_markdown(result: dict, output_dir: Path) - None: output_dir.mkdir(parentsTrue, exist_okTrue) for filename, data in result.items(): doc data.get(document, {}) text doc.get(text, ) tables doc.get(tables, []) md_lines [] # 写入正文文本 md_lines.append(# 文档正文\n) md_lines.append(text) md_lines.append(\n) # 写入表格 if tables: md_lines.append(\n## 表格\n) for table in tables: title table.get(title, 未命名表格) rows table.get(rows, []) md_lines.append(f\n### {title}\n) if rows: header | | .join(rows[0]) | separator | | .join([---] * len(rows[0])) | md_lines.append(header) md_lines.append(separator) for row in rows[1:]: md_lines.append(| | .join(row) |) md_file output_dir / f{Path(filename).stem}.md md_file.write_text(\n.join(md_lines), encodingutf-8) print(f已生成: {md_file}) if __name__ __main__: with open(INPUT_FILE, encodingutf-8) as f: results json.load(f) convert_to_markdown(results, OUTPUT_DIR)这段代码最大的作用是打通“API 返回 JSON → 知识库可用的 Markdown 文件”这条链路。实际操作时你可以根据自己的下游系统调整输出格式比如写入数据库、搭建向量索引、导入 Dify 或 FastGPT。5. 常见问题与排查思路使用 Cohere Parse 时最常遇到的问题集中在认证、文件格式、响应结构、限流和成本控制几个方面。问题现象常见原因解决思路401 UnauthorizedAPI Key 错误或未正确传递检查环境变量确认 Key 未过期400 请求错误文件格式不支持或请求参数有误确认文件类型检查 API 文档请求超时文件过大或网络不稳定拆分文档适当调大 timeout并发受限超过免费额度或速率限制增加请求间隔批量任务串行处理返回文本为空扫描件未启用 OCR 或页面无文字信息确认文档是否包含可提取文本解析结果字段不全API 版本不同导致字段名变化打印完整 JSON按实际字段开发5.1 认证与网络问题如果请求返回 401先检查环境变量是否真的设置成功。echo $COHERE_API_KEY不要在代码里写死 Key。如果你在公司环境还需要确认网络是否能访问api.cohere.com。5.2 文件格式问题Cohere Parse 对文件大小和页数通常有限制。如果文件过大建议先拆分后再上传。拆 PDF 可以用 pypdf 这类工具# 拆分 PDF 示例按需安装 pypdf from pypdf import PdfReader, PdfWriter reader PdfReader(large.pdf) for i in range(len(reader.pages)): writer PdfWriter() writer.add_page(reader.pages[i]) with open(fpage_{i1}.pdf, wb) as f: writer.write(f)5.3 解析质量与超长文档处理扫描件解析效果取决于底层 OCR 能力对于清晰度较低的扫描件解析出的文本可能存在乱码或错字。生产环境建议优先上传电子版 PDF而非扫描件。对扫描件先做图像预处理比如提高对比度。设置解析结果人工抽检比例尤其是合同、法律文书类场景。对于超长文档建议分批上传避免单次请求数据量过大导致超时。每个 API 的页数上限可能不同需要根据实际响应调整批大小。5.4 成本控制与限流Cohere Parse 价格低但批量调用之后费用仍然会累积。建议在调用日志中记录每个文件的页数、token 数或计费单位方便核算成本。如果触发限流增加调用间隔是最简单的缓解方式。也可以使用指数退避策略import time retry_count 3 for attempt in range(retry_count): try: response requests.post(API_URL, headersheaders, filesfiles, timeout120) if response.status_code 200: break elif response.status_code 429: wait_time 2 ** attempt print(f触发限流等待 {wait_time} 秒后重试) time.sleep(wait_time) else: break except requests.RequestException as e: print(f请求异常: {e}) time.sleep(2)6. 最佳实践与工程建议6.1 API Key 管理不要在代码、配置文件或前端代码中暴露 API Key。推荐做法通过环境变量注入。使用云厂商的密钥管理服务。定期轮换 Key。按项目拆分 Key方便追踪调用来源。示例import os API_KEY os.environ.get(COHERE_API_KEY)6.2 文件预处理上传前检查文件是否损坏、是否为空白页、页数是否超限。预处理可以显著提高解析成功率和质量from pypdf import PdfReader try: reader PdfReader(document.pdf) page_count len(reader.pages) print(f页数: {page_count}) if page_count 0: print(文件为空跳过) except Exception as e: print(f文件读取失败: {e})6.3 异步任务与队列大批量解析场景下不建议在请求线程里同步等待解析结果。更合理的方式是上传文件到对象存储。将解析任务写入消息队列。由后台 Worker 调用 Cohere Parse。将结果写回数据库或对象存储。前端通过任务状态查询结果。这样做的好处是避免接口超时同时方便失败重试。6.4 结果缓存同一个文件可能会被多次解析尤其是测试和联调阶段。建议以文件哈希作为缓存 key避免重复调用产生费用import hashlib def file_md5(file_path: str) - str: md5 hashlib.md5() with open(file_path, rb) as f: for chunk in iter(lambda: f.read(4096), b): md5.update(chunk) return md5.hexdigest()解析前先查缓存命中则直接返回结果。6.5 成本观测建议把每次调用的以下信息记录到日志中文件名。文件大小。页数。解析耗时。计费单位页数或其他口径。成功率。有了这些数据就能按业务线拆分成本提前发现异常调用。7. 总结Cohere Parse 把文档解析的门槛和成本都拉到了一个新的位置。对于需要接入 RAG、知识库或文档中台的团队来说它是一个值得认真评估的选项。本文从概念、环境、代码到排查思路做了完整梳理核心内容可以归纳为几点Cohere Parse 解决的是非结构化文档到结构化数据的转换问题。使用 REST API 调用最通用对 SDK 版本依赖最小。批量调用时要考虑限流、缓存和成本观测。文档格式、扫描件质量直接影响解析效果预处理非常重要。定价对比不要只看单价要用真实业务文档做小规模验证。下一步你可以根据自己的业务文档类型先拿 100 页真实样本跑一轮对比测试把成本、准确率和耗时三个指标记录下来。数据比任何宣传都可靠测试通过后再设计正式的解析流水线。如果这篇文章对你有帮助可以收藏备用后续有新的文档解析经验我也会继续补充。
)
