PaddleOCR 官方 API SDK 全解析Python / TypeScript / Go 多语言客户端与paddleocr apiCLI 使用指南【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCRPaddleOCR 官方 API SDK 是面向 PaddleOCR 官方托管服务的多语言客户端封装它将本地文件或文件 URL 提交到云端轮询异步任务并解析类型化结果全程不运行本地推理、不加载本地模型。本文以官方总览文档 overview.md 为骨架结合仓库内 Python 客户端源码、TypeScript SDK、Go SDK 与 CLI 实现系统讲解安装认证、模型选择、三组请求参数、错误处理与批量任务查询帮助你为 OCR 和文档解析场景快速选定接入方式并写出可运行的调用代码。一、架构与核心理念异步任务驱动的云上 OCRPaddleOCR 官方 API 的调用模型与本地推理截然不同本地部署时PaddleOCR类直接加载模型执行推理而官方 API SDK 采用「提交 → 轮询 → 解析」的异步任务模型客户端把file_url文件 URL或file_path本地文件上传提交到官方托管服务服务端返回一个任务 IDjob_id任务在云端异步执行SDK 按配置的轮询间隔查询任务状态直至完成完成后再拉取结果数据解析为类型化结果对象OCR 结果或文档解析结果。从源码看这一流程在 client.py 的PaddleOCRClient类注释中被明确概括为Wraps the async job API internally: submit → poll → fetch result其ocr()方法内部依次调用_submit()、self._poller.poll_until_done(job_id)和parse_ocr_result(...)client.pyparse_document()则对应调用parse_doc_parsing_result(...)client.py。官方默认服务地址在 _http.py 中定义为DEFAULT_BASE_URL https://paddleocr.aistudio-app.com可通过环境变量或构造参数覆盖见下文「客户端配置」。适用场景适合不想管理 GPU、模型权重与推理环境的服务端项目SDK 只负责网络通信与结果解析返回值结构统一便于与 LLM、RAG 等下游应用对接。二、安装与认证一个 Token 走遍所有 SDK所有 SDK 与 CLI 都默认读取环境变量PADDLEOCR_ACCESS_TOKEN。请先在 AI Studio Access Token 页面获取访问令牌然后按语言设置环境变量export PADDLEOCR_ACCESS_TOKENyour-access-token各语言的安装与认证方式对比如下语言安装命令客户端 / 入口Token 传入方式Python安装paddleocr包本体即可无需额外依赖组PaddleOCRClient/AsyncPaddleOCRClient环境变量或PaddleOCRClient(token...)TypeScriptnpm install paddleocr/api-sdkNode.js 18new PaddleOCRClient({ token })环境变量或构造参数tokenGogo get github.com/PaddlePaddle/PaddleOCR/api_sdk/gopaddleocr.NewClient()环境变量或WithToken选项CLI安装paddleocr包本体paddleocr api子命令环境变量或--token参数认证失败行为Python 客户端在构造时若既没有环境变量也没有传入token会立即抛出AuthError源码见 client.py缺失或无效凭证在各语言 SDK 中均以类型化认证错误上报。Python 包级导出位于 paddleocr/init.pyPaddleOCRClient、AsyncPaddleOCRClient、Model以及全部错误类型均可直接从paddleocr顶层导入。三、快速开始四种接入方式对比3.1 Python同步from paddleocr import PaddleOCRClient, Model client PaddleOCRClient() result client.ocr( file_urlhttps://example.com/invoice.pdf, modelModel.PP_OCRV5, ) print(result.job_id, len(result.pages)) client.close()file_url与file_path必须二选一传入本地文件时改用file_pathSDK 会上传该文件到服务端。若两者都未传或同时传入validate_input_source()会抛出InvalidRequestError见 _core.py。3.2 TypeScriptimport { Model, PaddleOCRClient } from paddleocr/api-sdk; const client new PaddleOCRClient(); const result await client.ocr({ fileUrl: https://example.com/invoice.pdf, model: Model.PPOCRv5, }); console.log(result.jobId, result.pages.length);本地文件使用filePath与fileUrl同样互斥。3.3 Goclient, err : paddleocr.NewClient() if err ! nil { return err } result, err : client.OCR(ctx, paddleocr.OCRRequest{ Model: paddleocr.PPOCRv5, FileURL: https://example.com/invoice.pdf, }) if err ! nil { return err } fmt.Println(result.JobID, len(result.Pages))本地文件使用FilePath。Go 版本天然支持context.Context取消与静态类型检查适合二进制化部署的服务端项目。3.4 CLI无代码验证paddleocr api \ --model_type ocr \ --file_url https://example.com/invoice.pdf--model_type为必填参数取值只能是ocr或doc_parsing--file_url与--file_path二选一参数定义见 cli.py。CLI 子命令通过 paddleocr/_cli.py 注册到paddleocr主命令下。四、模型选择任务类型与模型家族的对应关系Model枚举是官方 API 模型名字符串的类型安全写法提交请求时自动转换为实际模型名Python 枚举定义见 models.py。你也可以直接传入模型名字符串例如modelPaddleOCR-VL-1.6。任务适用接口默认模型可选模型参数类型OCRocr、submit_ocr、wait_ocr_resultModel.PP_OCRV6Model.PP_OCRV5、Model.PP_OCRV6OCROptions文档解析parse_document、submit_document_parsing、wait_document_parsing_resultModel.PADDLE_OCR_VL_16Model.PP_STRUCTURE_V3、Model.PADDLE_OCR_VL、Model.PADDLE_OCR_VL_15、Model.PADDLE_OCR_VL_16选择PP-StructureV3时传PPStructureV3Options选择 PaddleOCR-VL 系列时传PaddleOCRVLOptionsCLI 侧的模型表与 SDK 一致但额外提供拉丁文 OCR 模型任务--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 中的三个 frozenset 约束_OCR_MODELS仅含 PP-OCRv5/PP-OCRv5-latin/PP-OCRv6_DOCUMENT_PARSING_MODELS含 PP-StructureV3 与三个 PaddleOCR-VL 版本_VL_MODELS专指 PaddleOCR-VL 系列。resolve_ocr_model()/resolve_document_model()_core.py会校验模型与任务是否匹配不匹配即抛InvalidRequestError。CLI 在_execute_api中同样校验OCR 任务传入了非 OCR 模型会打印错误并以退出码 2 结束cli.py。五、客户端配置超时、自定义服务地址与底层注入5.1 超时控制request_timeout/requestTimeout/WithRequestTimeout限制一次 HTTP 请求的超时包括提交任务、查询状态和下载结果资源。Python 默认300.0秒。poll_timeout/pollTimeout/WithPollTimeout限制ocr、parse_document、wait_ocr_result、wait_document_parsing_result的总等待时间。Python 默认600.0秒。Python 与 TypeScript 示例client PaddleOCRClient( request_timeout300.0, poll_timeout600.0, )const client new PaddleOCRClient({ requestTimeout: 300_000, pollTimeout: 600_000, });Go 示例client, err : paddleocr.NewClient( paddleocr.WithRequestTimeout(30*time.Second), paddleocr.WithPollTimeout(5*time.Minute), )从源码看Python 的Poller被构造时传入max_wait_timepoll_timeoutclient.py而HTTPClient接收request_timeoutclient.py。5.2 自定义服务地址通过环境变量PADDLEOCR_BASE_URL或客户端参数指定代理 / 自建网关地址client PaddleOCRClient(base_urlhttps://my-proxy.com/paddle)const client new PaddleOCRClient({ baseUrl: https://my-proxy.com/paddle, });client, err : paddleocr.NewClient( paddleocr.WithBaseURL(https://my-proxy.com/paddle), )Python 的地址解析优先级为base_url参数 PADDLEOCR_BASE_URL环境变量 DEFAULT_BASE_URLclient.py。5.3 底层网络层注入TypeScript通过fetch选项注入自定义 fetch 实现适用于代理或自定义网络层const client new PaddleOCRClient({ fetch: myCustomFetch, });Go通过WithHTTPClient注入自定义*http.Client适用于代理、自定义 TLS 或重试策略client, err : paddleocr.NewClient( paddleocr.WithHTTPClient(myHTTPClient), )TypeScript公共方法还支持接收AbortSignal上层可主动取消Go则通过context.Context取消请求。六、请求参数三组 Options 详解6.1 命名转换约定三种 SDK 的参数命名与官方 API 的 camelCase 对齐方式不同Python使用 snake_case提交时自动转换为 camelCase。_build_payload()只发送非None字段未设置的字段使用服务端默认值extra_options字典会被直接合并进 payloadmodels.py。TypeScript直接使用 camelCase与官方 API 字段名一致。Go结构体字段使用 PascalCase序列化时自动转 camelCase指针类型字段传nil表示不设置。这一行为有测试用例直接验证tests/api_client/test_core.py断言snake_to_camel(top_p) topP、snake_to_camel(use_e2e_wired_table_rec_model) useE2eWiredTableRecModel并验证PPStructureV3Options(...).to_payload()输出的正是useE2eWiredTableRecModel、formatBlockContent、markdownIgnoreLabels、textDetLimitSideLen等官方键名test_core.py。6.2 OCROptions常用字段字段类型说明use_doc_orientation_classifybool文档方向分类use_doc_unwarpingbool文档扭曲矫正visualizebool是否返回可视化结果图结合 models.py 的完整定义OCR 场景还支持以下字段同样可传给 CLI 对应参数use_textline_orientation文本行方向检测、text_det_limit_side_len文本检测图像边长限制整数、text_det_limit_type边长限制类型min或max、text_det_thresh/text_det_box_thresh/text_det_unclip_ratio文本检测阈值类参数、text_rec_score_thresh文本识别置信度阈值以及用于扩展的extra_options。6.3 PPStructureV3Options常用字段字段类型说明use_table_recognitionbool表格识别use_formula_recognitionbool公式识别use_chart_recognitionbool图表识别prettify_markdownboolMarkdown 美化完整定义models.py还包含版面与表格的细粒度控制use_region_detection、use_seal_recognition、layout_threshold、layout_nms、layout_unclip_ratio、layout_merge_bboxes_mode、format_block_content、use_wired_table_cells_trans_to_html、use_wireless_table_cells_trans_to_html、use_table_orientation_classify、use_ocr_results_with_table_cells、use_e2e_wired_table_rec_model、use_e2e_wireless_table_rec_model以及 Markdown 输出控制markdown_ignore_labels、show_formula_number、return_markdown_images、output_formats。6.4 PaddleOCRVLOptions常用字段字段类型说明use_layout_detectionbool版面检测use_chart_recognitionbool图表识别temperaturefloat采样温度prettify_markdownboolMarkdown 美化PaddleOCR-VL 是视觉语言模型其完整参数集models.py还包括采样与生成控制repetition_penalty、top_p、min_pixels、max_pixels、max_new_tokens、vlm_extra_args、prompt_label以及版面结构控制layout_shape_mode、merge_layout_blocks、restructure_pages、merge_tables、relevel_titles还有use_ocr_for_image_block图像块内 OCR、show_formula_number、output_formats等。参数校验PaddleOCRVLOptions提交前会经过_validate_vl_options()models.py本地校验top_p必须满足0 top_p 1temperature 0repetition_penalty 0min_pixels、max_pixels均大于 0 且min_pixels max_pixels。违反任一条都会抛出InvalidRequestError避免无效请求白白消耗配额。七、公共 API 与任务编排模式7.1 方法总览三类 SDK 的公共方法一一对应功能PythonTypeScriptGo提交并等待 OCR 结果ocr(...)ocr(...)OCR(...)提交并等待文档解析结果parse_document(...)parseDocument(...)ParseDocument(...)仅提交 OCR 任务submit_ocr(...)submitOcr(...)SubmitOCR(...)仅提交文档解析任务submit_document_parsing(...)submitDocumentParsing(...)SubmitDocumentParsing(...)非阻塞查询状态get_status(job_id)getStatus(jobId)GetStatus(ctx, jobID)等待并解析 OCR 结果wait_ocr_result(job)waitOcrResult(job)WaitOCRResult(ctx, job)等待并解析文档解析结果wait_document_parsing_result(job)waitDocumentParsingResult(job)WaitDocumentParsingResult(ctx, job)保存单个资源save_resource(url, dest)saveResource(url, dest, opts)SaveResource(...)保存 OCR 结果资源save_ocr_result_resources(result, dest)saveOcrResultResources(result, dest, opts)SaveOCRResultResources(...)保存文档解析结果资源save_document_parsing_result_resources(result, dest)saveDocumentParsingResultResources(result, dest, opts)SaveDocumentParsingResultResources(...)AsyncPaddleOCRClient提供上述任务操作与资源保存方法的异步版本Python。7.2 任务编排模式先提交后等待批量或异步场景推荐「先submit_*拿到Job对象稍后再wait_*拉取结果」的两段式写法from paddleocr import PaddleOCRClient, Model client PaddleOCRClient() job client.submit_ocr( file_path./invoice.pdf, modelModel.PP_OCRV6, ) # ... 中间可执行其他逻辑 ... result client.wait_ocr_result(job) print(result.job_id, len(result.pages)) client.close()submit_*系列只返回携带job_id与任务类型的Job对象client.py真正的阻塞等待发生在wait_*与ocr/parse_document内部。八、批量任务查询提交任务时可传入batch_id给一批相关任务打标之后调用get_batch_status(batch_id)查询该批次下各任务的状态、进度与结果 URLjob client.submit_ocr( file_path./a.pdf, batch_idbatch-2026-01, ) status client.get_batch_status(batch-2026-01)CLI 侧对应--batch_id参数cli.py便于在脚本中把多份文件归组管理。九、CLI 完整参数手册paddleocr api常用参数如下定义见 cli.py参数说明--model_type任务类型必填ocr或doc_parsing--model模型名称--file_url待处理文件 URL--file_path待上传并处理的本地文件路径--base_urlPaddleOCR API 服务 base URL缺省使用官方服务地址也可用PADDLEOCR_BASE_URL环境变量--token访问令牌或设置PADDLEOCR_ACCESS_TOKEN--request_timeout单次 HTTP 请求超时秒默认 300.0--poll_timeout等待远端任务完成的总超时秒默认 600.0--output输出 JSON 文件路径省略时打印到标准输出--save_resources保存结果对象引用资源的目录--overwrite_resources保存资源时覆盖已有文件--page_ranges页码范围例如2,4-6--batch_id批量任务标识--use_doc_orientation_classify文档方向分类True/False--use_doc_unwarping文档扭曲矫正True/False--use_textline_orientation文本行方向检测True/False--text_det_limit_side_len文本检测图像边长限制--text_det_limit_type边长限制类型min或max--text_rec_score_thresh文本识别置信度阈值--use_layout_detection版面检测True/False--use_seal_recognition印章识别True/False--use_table_recognition表格识别True/False--use_formula_recognition公式识别True/False--use_chart_recognition图表识别True/False--visualize可视化结果图True/False--prettify_markdownMarkdown 美化True/False9.1 OCR 完整示例paddleocr api \ --model_type ocr \ --model PP-OCRv5 \ --file_path ./invoice.pdf \ --request_timeout 300 \ --poll_timeout 600 \ --output ocr-result.json9.2 文档解析完整示例paddleocr api \ --model_type doc_parsing \ --file_url https://example.com/report.pdf \ --use_chart_recognition True \ --save_resources ./doc-assets \ --output doc-result.json9.3 输出行为命令成功时输出格式化 JSONOCR 结果包含jobId和每页的prunedResult、ocrImageUrl文档解析结果包含jobId和每页的markdownText、markdownImages、outputImages。指定--output时写入该文件并打印保存位置否则打印到标准输出。指定--save_resources时CLI 会把结果对象引用的资源保存到目标目录资源落盘由save_ocr_result_resources/save_document_parsing_result_resources完成见 client.py。错误输出到标准错误并返回非零退出码。常见原因缺少PADDLEOCR_ACCESS_TOKEN、模型与--model_type不匹配、请求超时、轮询超时、远端任务失败或响应格式异常。十、错误处理体系从基类到类型化异常Python SDK 的所有错误都继承自PaddleOCRAPIError基类errors.py并可从paddleocr顶层导入。完整异常层级与触发条件异常触发条件AuthErrorToken 缺失、无效或过期HTTP 401/403InvalidRequestError参数非法HTTP 400或本地参数校验失败RateLimitError配额超限HTTP 429ServiceUnavailableError服务过载或网关超时HTTP 503/504APIError服务端返回非 2xx携带status_codeNetworkError网络层故障JobFailedError远端任务执行失败携带job_id与error_msgRequestTimeoutError单次 HTTP 请求超时PollTimeoutError轮询等待超时携带job_id与已等待时长elapsedResponseFormatError成功响应不符合文档化 schemaResultParseError结果解析失败其中APIError构造时携带 HTTP 状态码fHTTP {status_code}: {message}JobFailedError与PollTimeoutError分别暴露job_id、error_msg、elapsed等诊断字段方便上层日志与告警errors.py。TypeScript SDK 的错误类型与 Python 一一对应统一继承PaddleOCRAPIErrorGo SDK 则暴露可与errors.As配合使用的类型化错误覆盖同样的十一种情形。实战中建议对RateLimitError做退避重试对PollTimeoutError先调用get_status确认任务仍在运行再决定是否继续等待。十一、源码级调用链与命名转换原理一次client.ocr(file_url...)调用的完整链路Python 为例PaddleOCRClient.ocr()调用resolve_ocr_model()校验模型属于 OCR 家族_core.py_submit()先执行validate_input_source()校验输入源唯一性再options.to_payload()把 snake_case 字段转换为 camelCase 并剔除Noneclient.py有file_url走HTTPClient.submit_url(...)有file_path走HTTPClient.submit_file(...)上传文件Poller.poll_until_done(job_id)按轮询间隔查询状态直至完成Poller构造时接收max_wait_timepoll_timeoutparse_ocr_result(job_id, jsonl_data)把服务端 JSONL 解析为OCRResult文档解析则走parse_doc_parsing_resultclient.py。命名转换工具snake_to_camel位于 paddleocr/_utils/naming.py其正确性由 tests/api_client/test_core.py 覆盖。类型化结果对象OCRResult、DocParsingResult、Job、JobStatus、BatchStatus、Progress定义在 paddleocr/_api_client/results.py。十二、选型建议与最佳实践已在使用paddleocrPython 包的项目优先 Python SDKPaddleOCRClient与AsyncPaddleOCRClient可无缝衔接无需新增语言运行时。Node.js 18 服务端项目TypeScript SDK 的 camelCase 参数与官方 API 一致AbortSignal便于对接上层超时控制。需要静态类型、上下文取消与二进制部署的服务端项目Go SDK 的context.Context、errors.As与WithHTTPClient注入能力更适合微服务与网关场景。脚本、调试与无代码快速验证直接用paddleocr api子命令一个命令行即可完成 OCR 或文档解析配合--output落盘 JSON 便于后续程序消费。实践要点Token 只通过环境变量注入、绝不硬编码根据文件大小与服务负载合理设置request_timeout与poll_timeout对RateLimitError与ServiceUnavailableError做指数退避重试需要批量处理时用batch_id归组、用get_batch_status统一查询进度解析类任务默认开启use_layout_detection与prettify_markdown可获得更干净的 Markdown 输出。相关文档与源码索引官方 API 总览overview.mdPython SDK 文档python.mdTypeScript SDK 文档typescript.mdGo SDK 文档go.mdCLI 文档cli.md安装指引installation.mdPython 客户端实现client.py、async_client.py模型枚举与 Options 定义models.py错误类型定义errors.pyCLI 实现cli.pyHTTP 层与默认服务地址http.py参数校验与模型解析core.py客户端测试用例tests/api_client/test_core.py、tests/api_client/test_cli.pyTypeScript SDK 源码api_sdk/typescriptGo SDK 源码api_sdk/go【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考