 实战指南：云端 OCR 与文档解析的命令行调用)
PaddleOCR Official API CLI (paddleocr api) 实战指南云端 OCR 与文档解析的命令行调用【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCRPaddleOCR 官方 API CLI 是 PaddleOCR 提供的paddleocr api子命令用于将本地文件或文件 URL 提交到托管的 PaddleOCR 云服务异步等待任务完成后输出解析结果全程不加载本地模型、不执行本地推理。本文将基于仓库中的 cli.en.md 文档结合paddleocr/_api_client/的源码实现完整讲解从安装鉴权、参数配置、任务模型选择到输出与错误处理的端到端使用方式。一、工作原理与适用场景paddleocr api是对 PaddleOCR 官方 API 的命令行封装其调用链与 Python SDK 完全一致见 client.py提交任务将file_url远程文件地址或file_path本地文件上传为 multipart 表单连同模型名、optionalPayload参数提交到任务接口轮询等待以指数退避方式轮询任务状态pending→running→done/failed见 poller.py拉取结果任务完成后从resultUrl指向的 JSONL 地址下载结果并解析为结构化对象OCR 或文档解析两类见 poller.py。因此它的典型使用场景是脚本化批量 OCR、快速验证云端模型效果、无需本地 GPU 与模型下载的文档解析流水线。官方默认服务地址定义在 http.pyDEFAULT_BASE_URL https://paddleocr.aistudio-app.com接口路径为/api/v2/ocr/jobs。二、安装与鉴权2.1 安装先按 Install paddleocr 安装核心paddleocrPython 包。安装完成后api子命令开箱即用——它属于核心包自带能力无需安装任何额外的依赖分组。从代码看api子命令由 _cli.py 中的_register_api_command注册真正实现位于 paddleocr/_api_client/cli.py使用标准argparse定义参数。2.2 获取 Access Token需要先在 AI Studio Access Token 页面获取访问令牌。CLI 默认从环境变量PADDLEOCR_ACCESS_TOKEN读取export PADDLEOCR_ACCESS_TOKENyour-access-token也可以显式通过--token传入。底层 client.py 的优先级是--token参数 PADDLEOCR_ACCESS_TOKEN环境变量两者都缺失时抛出AuthErrorToken is required. Set PADDLEOCR_ACCESS_TOKEN or pass token.CLI 会将错误打印到 stderr 并以非零退出码结束。说明认证采用Authorization: Bearer token请求头见 http.py。请求头中还可通过--client_platform自定义Client-Platform头。三、基础用法paddleocr api \ --model_type ocr \ --file_url https://example.com/invoice.pdf两个强制约束由源码 cli.py 与 _core.py 共同保证--model_type必填只能取ocr或doc_parsing--file_url与--file_path二选一同时省略或同时提供都会抛出InvalidRequestError。--file_url提交时走submit_urlJSON body--file_path走submit_filemultipart 文件上传且会先校验本地文件存在见 http.py。四、常用参数详解以下为paddleocr api的完整参数清单默认值以 cli.py 源码为准参数类型默认值说明--model_typestr必填任务类型ocr或doc_parsing--modelstr随任务类型而定模型名取值见第五节不传时按model_type使用默认模型--file_urlstrNone待处理文件的远程 URL--file_pathstrNone待处理文件的本地路径上传到服务端--base_urlstr官方服务地址PaddleOCR API 服务基础地址也可通过环境变量PADDLEOCR_BASE_URL设置--tokenstrNone访问令牌或用PADDLEOCR_ACCESS_TOKEN环境变量--request_timeoutfloat300.0单次 HTTP 请求的超时秒数--poll_timeoutfloat600.0等待远端任务完成的总体超时秒数--outputstrNoneJSON 输出文件路径省略则打印到 stdout--save_resourcesstrNone保存结果对象引用的资源图片等的目录--overwrite_resourcesflagFalse保存资源时是否覆盖已存在的文件--page_rangesstrNone页范围例如2,4-6--batch_idstrNone可选批标识用于查询相关任务--use_doc_orientation_classifyboolNone文档方向分类True/False--use_doc_unwarpingboolNone文档矫正/去弯曲True/False--use_textline_orientationboolNone文本行方向检测True/False--text_det_limit_side_lenintNone文本检测的图像边长限制--text_det_limit_typestrNone边长限制类型min或max--text_rec_score_threshfloatNone文本识别结果的分数阈值--use_layout_detectionboolNone版面检测doc_parsing 用--use_seal_recognitionboolNone印章识别doc_parsing 用--use_table_recognitionboolNone表格识别PP-StructureV3 用--use_formula_recognitionboolNone公式识别PP-StructureV3 用--use_chart_recognitionboolNone图表识别doc_parsing 用--visualizeboolNone生成结果可视化图片--prettify_markdownboolNoneMarkdown 美化doc_parsing 用参数按功能分组与 SDK 中的选项数据类一一对应OCR 任务使用OCROptions见 models.pydoc_parsing中 PaddleOCR-VL 系列使用PaddleOCRVLOptionsPP-StructureV3 使用PPStructureV3Options其中还包含layout_threshold、temperature、top_p、max_new_tokens等更细粒度参数models.py 中有完整字段。布尔参数在命令行中使用True/False字符串由str2bool解析top_p、temperature、min_pixels/max_pixels等在提交前会经过校验如top_p必须满足0 top_p 1见 models.py非法值会以InvalidRequestError拒绝。五、两种任务的实战示例5.1 OCR 示例本地文件paddleocr api \ --model_type ocr \ --model PP-OCRv5 \ --file_path ./invoice.pdf \ --request_timeout 300 \ --poll_timeout 600 \ --output ocr-result.json要点--file_path上传本地invoice.pdf--request_timeout 300与--poll_timeout 600分别控制单次 HTTP 请求与整体轮询的等待上限多页大文件建议按需调大--output ocr-result.json将格式化 JSON 写入文件并打印保存路径不写则直接打印到 stdout。5.2 文档解析示例远程文件 URLpaddleocr api \ --model_type doc_parsing \ --file_url https://example.com/report.pdf \ --use_chart_recognition True \ --save_resources ./doc-assets \ --output doc-result.json要点输入走--file_url服务端直接拉取无需本地下载--use_chart_recognition True开启图表识别--save_resources ./doc-assets会把结果中引用的 Markdown 图片与输出图片下载到本地目录注意目标目录必须已存在见 resources.py。资源保存的命名规则可在 resources.py 中确认OCR 结果图片按ocr-page-{页号}.{扩展名}命名文档解析结果按结果对象中的资源名markdown_images与output_images的 key保存。默认遇到同名文件会报错加--overwrite_resources可覆盖。六、模型选择任务--model_type默认模型可选模型OCRocrPP-OCRv6PP-OCRv5,PP-OCRv5-latin,PP-OCRv6文档解析doc_parsingPaddleOCR-VL-1.6PP-StructureV3,PaddleOCR-VL,PaddleOCR-VL-1.5,PaddleOCR-VL-1.6以上模型集合定义在 models.py 的Model枚举与_OCR_MODELS/_DOCUMENT_PARSING_MODELS/_VL_MODELS三个集合中。需要注意两点对应 cli.py 的调度逻辑模型与任务必须匹配例如对--model_type ocr传入PP-StructureV3CLI 会打印Error: OCR task does not support PP-StructureV3.并以退出码 2 结束不同模型走不同的参数集合doc_parsing任务中PaddleOCR-VL 系列使用PaddleOCRVLOptions支持use_layout_detection、use_chart_recognition等PP-StructureV3 使用PPStructureV3Options额外支持use_table_recognition、use_formula_recognition等选择不当会在提交前被resolve_document_options拒绝见 _core.py。七、输出行为与结果结构7.1 标准输出结构成功时命令输出格式化 JSONensure_asciiFalse, indent2两种任务的字段由 cli.py 定义OCR 输出jobId 每页的prunedResult裁剪后的识别结果与ocrImageUrl识别可视化图地址{ jobId: xxx, pages: [ { prunedResult: ..., ocrImageUrl: https://... } ] }文档解析输出jobId 每页的markdownTextMarkdown 文本、markdownImagesMarkdown 中引用的图片映射、outputImages输出图片映射{ jobId: xxx, pages: [ { markdownText: ..., markdownImages: {}, outputImages: {} } ] }7.2 输出落盘行为--output path写入该文件并打印Result saved to: path省略则直接向 stdout 打印 JSON--save_resources dir将结果引用的资源下载到指定目录并打印Resources saved to: dir (N files)此提示输出到 stderr二者可同时使用。从源码看这些结构对应 results.py 中的OCRResult/OCRPage与DocParsingResult/DocParsingPage数据类服务端返回的是 JSONL 格式由parse_ocr_result/parse_doc_parsing_result逐行解析poller.py。八、错误处理与排错指南错误统一打印到 stderr并以非零退出码返回。常见原因与对应的错误类型定义见 errors.py场景错误类型说明缺少PADDLEOCR_ACCESS_TOKEN或令牌无效/过期AuthError对应 HTTP 401/403--model与--model_type不匹配InvalidRequestErrorCLI 层直接拒绝退出码 2参数校验失败如file_url/file_path同时提供InvalidRequestError对应 HTTP 400请求超时 / 连接失败RequestTimeoutError/NetworkError--request_timeout内未完成轮询超过--poll_timeoutPollTimeoutError等待任务完成的总超时远端任务执行失败JobFailedError任务状态为failed携带服务端errorMsg响应不符合约定 schema / 结果 JSONL 无法解析ResponseFormatError/ResultParseError一般属服务端异常或版本不匹配每日配额超限HTTP 429RateLimitError见官方配额规则服务过载或网关超时HTTP 503/504ServiceUnavailableError可稍后重试排错建议顺序先确认环境变量PADDLEOCR_ACCESS_TOKEN是否已导出 → 再确认--model与--model_type匹配 → 检查--request_timeout/--poll_timeout是否对大文件过小 → 最后核对本地文件路径是否存在--file_path不存在会抛FileNotFoundError。九、相关资源官方 API 总览overview.en.md介绍 Python / TypeScript / Go SDK 与 CLI 四种客户端形态CLI 实现源码paddleocr/_api_client/cli.py、paddleocr/_api_client/client.py底层通信与轮询paddleocr/_api_client/_http.py、paddleocr/_api_client/_poller.py参数与结果模型paddleocr/_api_client/models.py、paddleocr/_api_client/results.py测试用例tests/api_client/test_cli.py、tests/api_client/test_http.py各模型的 API 参考文档PP-OCRv5、PP-StructureV3、PaddleOCR-VL、PaddleOCR-VL-1.5以及 API 配额规则与错误码说明可在 AI Studio 官方文档区查阅以获取最新的模型能力、配额限制与错误码定义。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
