PaddleOCR Go SDK 实战指南接入官方 API、提交异步任务与结果解析【免费下载链接】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本文以 PaddleOCR 仓库中api_sdk/go目录下的官方 Go 客户端为核心完整讲解其安装、鉴权配置、OCR 与文档解析两类任务的调用方式、请求参数结构、异步任务的提交/轮询/等待模型以及如何下载结果资源与处理类型化错误帮助你在 Go 服务中直接对接 PaddleOCR 官方托管 API把 PDF/图片文档转换为结构化数据。一、SDK 定位与能力边界根据 api_sdk/go/README.md 的明确说明这个 Go 客户端的定位是调用 PaddleOCR 官方托管 API向远端服务提交 OCR 和文档解析任务不运行本地 PaddleOCR 推理也不加载任何本地模型。也就是说它是纯 API 客户端适合把 OCR 能力嵌入 Go 后端服务、批处理程序或 CLI 工具模型推理本身发生在 PaddleOCR 官方托管服务上。完整的官方用户文档位于 Go SDK 中文文档 与 Go SDK 英文文档SDK 代码与文档相互印证。SDK 由单一 Go 包组成包名为paddleocr见 doc.go 的包注释模块路径与安装命令一致go get github.com/PaddlePaddle/PaddleOCR/api_sdk/go版本化的 release 使用子模块 tag例如api_sdk/go/v0.1.0。从 go.mod 可以看到模块要求 Go 1.21且没有任何第三方依赖——实现仅使用net/http、multipart、json等标准库这对生产环境的依赖审计非常友好。二、鉴权与客户端构造SDK 的鉴权只有一条主线Access Token。README 给出了两种方式export PADDLEOCR_ACCESS_TOKENyour-access-token或者在构造客户端时通过WithToken显式传入。结合 client.go 中NewClient的实现客户端初始化逻辑可以归纳为一张优先级表配置项来源与优先级默认值Access TokenWithToken(...) 环境变量PADDLEOCR_ACCESS_TOKEN无两者皆空则返回AuthError服务地址 Base URLWithBaseURL(...) 环境变量PADDLEOCR_BASE_URL 内置默认地址https://paddleocr.aistudio-app.com定义于 options.go 的DefaultBaseURL请求超时WithTimeout(...)/WithRequestTimeout(...)5 分钟轮询超时WithTimeout(...)/WithPollTimeout(...)10 分钟值得注意的几个实现细节Token 缺失会在构造阶段就失败NewClient会在返回前检查 token缺失时直接返回带有 Token is required. Set PADDLEOCR_ACCESS_TOKEN or use WithToken(). 消息的AuthError避免运行到提交任务时才暴露配置问题client.go。Base URL 会被统一做TrimRight(/)处理并拼接固定 API 路径/api/v2/ocr/jobsapiPath常量最终任务接口为{baseURL}/api/v2/ocr/jobs。超时可以分开配置WithRequestTimeout只影响单次 HTTP 请求提交、查状态、下载结果WithPollTimeout只影响等待任务完成的总时长。WithTimeout则是同时设置两者。此外还支持WithHTTPClient注入自定义*http.Client便于挂接连接池、代理等以及WithClientPlatform用于在请求头中附加Client-Platform标识见 options.go。三、最小可用示例OCR 识别README 给出的最小用法如下它演示了 URL 输入方式的 OCR 调用client, 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))其中OCRRequest的结构定义在 options.gotype OCRRequest struct { Model string FileURL string FilePath string PageRanges string BatchID string Options *OCROptions }各字段的语义与约束由 ocr.go 的SubmitOCR校验逻辑印证FileURL/FilePath二选一且互斥——两者都为空报 Either FileURL or FilePath is required.同时提供报 FileURL and FilePath are mutually exclusive.ocr.go 的submit方法Model可选缺省为PP-OCRv6见SubmitOCR中model PPOCRv6的兜底逻辑传入的值必须是 OCR 模型否则返回InvalidRequestErrorPageRanges页范围控制非空时才写入请求体BatchID批次 ID非空时随任务提交之后可用GetBatchStatus按批次查询Options可选的*OCROptions未提供时 SDK 会用一个空的OCROptions作为默认 payloaddefaultPayloadocr.go。仓库中的示例 examples/ocr_url/main.go 在此基础上演示了如何遍历结果页for i, page : range result.Pages { fmt.Printf(Page %d: %v\n, i1, page.PrunedResult) fmt.Printf( Image URL: %s\n, page.OCRImageURL) }模型常量与选择SDK 在 models.go 中定义了全部模型常量并按用途划分了白名单常量取值适用 APIPPOCRv5PP-OCRv5OCRPPOCRv5LatinPP-OCRv5-latinOCR拉丁文字PPOCRv6PP-OCRv6OCR默认PPStructureV3PP-StructureV3文档解析PaddleOCRVLPaddleOCR-VL文档解析PaddleOCRVL15PaddleOCR-VL-1.5文档解析PaddleOCRVL16PaddleOCR-VL-1.6文档解析默认判断函数IsOCRModel与IsDocumentParsingModel在提交前做白名单校验防止把 OCR 模型传给文档解析接口。README 特别提示设置Model: paddleocr.PPOCRv6或字符串PP-OCRv6使用 PP-OCRv6 托管模型Model: paddleocr.PPOCRv5Latin或PP-OCRv5-latin使用 PP-OCRv5 拉丁文字模型。四、文档解析ParseDocument 与 PaddleOCR-VL 默认模型文档解析同样是一行便捷方法README 中的示例SDK 默认使用 PaddleOCR-VL-1.6 模型doc, err : client.ParseDocument(ctx, paddleocr.DocParsingRequest{ FilePath: ./report.pdf, Options: paddleocr.PaddleOCRVLOptions{ UseChartRecognition: paddleocr.Bool(true), }, }) if err ! nil { return err } fmt.Println(doc.JobID, len(doc.Pages))对应 ocr.go 中ParseDocument的实现先SubmitDocumentParsing提交任务再WaitDocumentParsingResult阻塞等待结果与 OCR 完全同构。本地文件路径FilePath走的是multipart/form-data 上传SDK 会先os.Stat检查文件存在不存在则抛FileNotFoundError然后把model、optionalPayloadJSON 字符串、可选的pageRanges、batchId与文件本体写入 multipart body 提交transport.go 的submitFile。URL 方式则是 JSON body 提交fileUrlsubmitURL。两种方式的响应统一为{code, msg, data}结构data中提取jobIdcode ! 0时直接转为APIErrortransport.go 的decodeAPIResponse。DocParsingRequest.Options的类型是DocParsingOptionsProvider接口options.go目前有两个实现*PPStructureV3Options与*PaddleOCRVLOptions。示例 examples/doc_parsing_file/main.go 演示了用PPStructureV3模型解析本地 PDF 并打印每页 Markdownresult, err : client.ParseDocument(ctx, paddleocr.DocParsingRequest{ Model: paddleocr.PPStructureV3, FilePath: ./sample.pdf, Options: paddleocr.PPStructureV3Options{UseChartRecognition: paddleocr.Bool(true)}, }) if err ! nil { log.Fatal(err) } for i, page : range result.Pages { fmt.Printf(Page %d:\n%s\n, i1, page.MarkdownText) }三类 Options 结构请求参数全集三个 Options 结构options.go是 SDK 暴露的全部请求参数。字段统一采用*bool/*int/*float64指针加omitempty即不设置就不下发因此仓库提供了包级辅助函数paddleocr.Bool(v)来构造布尔指针。核心字段摘录如下OCROptionsOCR 任务预处理开关UseDocOrientationClassify文档方向分类、UseDocUnwarping文档去畸变、UseTextlineOrientation文本行方向检测参数TextDetLimitSideLen、TextDetLimitType、TextDetThresh、TextDetBoxThresh、TextDetUnclipRatio识别与输出TextRecScoreThresh、Visualize逃生舱ExtraOptionsmap[string]interface{}JSON 标签为-——其中的键值会被展平合并进请求的optionalPayloadpayloadWithExtraOptionsocr.go用于覆盖 SDK 尚未建模的服务端参数。PPStructureV3OptionsPP-StructureV3 文档解析在 OCR 同款检测参数之上增加了UseSealRecognition印章识别、UseTableRecognition、UseFormulaRecognition、UseChartRecognition、UseRegionDetection等能力开关布局参数LayoutThreshold、LayoutNms、LayoutUnclipRatio、LayoutMergeBboxesMode表格转 HTML 相关开关UseWiredTableCellsTransToHtml、UseWirelessTableCellsTransToHtml、UseTableOrientationClassify、UseE2eWiredTableRecModel等以及 Markdown 输出控制MarkdownIgnoreLabels、PrettifyMarkdown、ShowFormulaNumber、ReturnMarkdownImages、OutputFormats。PaddleOCRVLOptionsPaddleOCR-VL 系列文档解析包含布局检测开关UseLayoutDetection、PromptLabel、VLM 生成参数RepetitionPenalty、Temperature、TopP、MinPixels、MaxPixels、MaxNewTokens、VlmExtraArgs以及页面重构开关MergeLayoutBlocks、RestructurePages、MergeTables、RelevelTitles和 Markdown 输出控制字段。五、异步任务模型提交、轮询与等待PaddleOCR 官方 API 是异步任务模型提交后立即得到jobId任务在pending → running → done/failed状态机中推进。SDK 围绕它提供了三层 APIocr.go 与 operation.go一键式client.OCR/client.ParseDocument——提交并阻塞到完成适合简单脚本手动式client.SubmitOCR/client.SubmitDocumentParsing返回*Job含JobID、Model、Task、PageRanges、BatchID见 results.go之后可以client.GetStatus(ctx, jobID)非阻塞查询状态返回*JobStatus含State、Progress、ResultURL、ErrorMsgclient.GetBatchStatus(ctx, batchID)按批次查询所有子任务状态请求GET {jobsURL}/batch/{batchID}transport.go;client.WaitOCRResult(ctx, jobID)/client.WaitDocumentParsingResult(ctx, jobID)阻塞等待Operation 泛化式Operation类型封装JobID与模型信息Wait(ctx)阻塞等待并按模型类型自动选择 OCR 或文档解析的结果解析器Poll(ctx)返回(状态, 是否完成, 错误)适合自己实现重试/并发编排operation.go。examples/doc_parsing_file/main.go 的后半段同时演示了先并行提交两个任务、再分别等待的手动模式ocrJob, _ : client.SubmitOCR(ctx, paddleocr.OCRRequest{FileURL: https://example.com/f1.pdf}) docJob, _ : client.SubmitDocumentParsing(ctx, paddleocr.DocParsingRequest{ Model: paddleocr.PPStructureV3, FilePath: ./sample.pdf, }) ocrResult, err : client.WaitOCRResult(ctx, ocrJob.JobID) docResult, err : client.WaitDocumentParsingResult(ctx, docJob.JobID)轮询策略与结果拉取阻塞等待的底层是 poller.go 中的pollUntilDone其退避策略值得在集成时了解初始间隔3 秒每次未完成后按1.5 倍递增上限15 秒总等待时间受pollTimeout默认 10 分钟可用WithPollTimeout调整约束超时返回PollTimeoutError携带JobID与已耗时支持context取消ctx取消时返回ctx.Err()任务状态为done时从resultUrl.jsonUrl拉取JSONL 结果每行一个 JSON 对象解析失败返回ResponseFormatError状态为failed时返回JobFailedError携带服务端errorMsg。状态归一化逻辑normalizeStatusocr.go对state做白名单校验pending/running/done/failed并解析extractProgress为Progress{TotalPages, ExtractedPages, StartTime, EndTime}可用于向前端展示进度条。六、结果结构OCRResult 与 DocParsingResult结果解析发生在 ocr.go 的parseOCRResult/parseDocParsingResult对应类型定义在 results.goOCROCRResult{JobID, Pages []OCRPage, DataInfo}。每页OCRPage包含PrunedResult文本检测识别的裁剪结果原始结构原样保留为interface{}、OCRImageURL、DocPreprocessingImageURL、InputImageURL与完整的Raw原始页数据。解析器会校验每页必须含prunedResult缺失即ResultParseError。文档解析DocParsingResult{JobID, Pages []DocParsingPage, DataInfo}。每页DocParsingPage的MarkdownTextmarkdown.text解析器校验其非空否则报 document parsing result page is missing markdown.text、MarkdownImagesMarkdown 中引用的图片名到 URL 的映射、OutputImages、Exports、PrunedResult与Raw。这种类型化字段 Raw全量原始数据的设计让常用字段有类型安全访问同时保留了访问服务端未来新增字段的能力。七、结果资源下载SaveResource 系列OCR 结果中的ocrImage等只是 URL。SDK 在 resource.go 提供三个下载方法SaveResource(ctx, resourceURL, dest, ...)下载单个资源。dest为目录时自动取 URL 末段作为文件名默认覆盖关闭目标已存在时返回InvalidRequestError可通过WithOverwrite(true)覆盖。写入采用同目录临时文件 os.Link/Rename的原子方式避免留下半截文件SaveOCRResultResources(ctx, result, destDir, ...)批量下载 OCR 结果中每页的ocrImage命名为ocr-page-N扩展名扩展名从 URL 安全提取SaveDocumentParsingResultResources(ctx, result, destDir, ...)批量下载文档解析页的MarkdownImages与OutputImages文件名来自资源键并做路径安全校验拒绝绝对路径与分隔符resource.go。三者都要求目标目录预先存在否则返回FileNotFoundError。八、类型化错误处理SDK 的所有错误都实现自公共基类PaddleOCRAPIError含Message与Cause支持errors.Unwrap定义在 errors.go与 HTTP 语义一一映射映射逻辑在 transport.go错误类型触发场景AuthError构造时缺 tokenHTTP 401/403InvalidRequestError请求参数非法模型不在白名单、FileURL/FilePath 冲突、空批 ID 等HTTP 400APIError带StatusCode服务端code ! 0或其他非 2xx 响应RateLimitErrorHTTP 429ServiceUnavailableErrorHTTP 503/504JobFailedError带JobID、ErrorMsg轮询到任务状态failedRequestTimeoutError/NetworkError网络层错误网络超时会区分两者PollTimeoutError带JobID、Elapsed等待任务超过轮询超时FileNotFoundError带Path本地输入文件不存在、目标目录不存在等ResponseFormatError/ResultParseError服务端响应结构异常或结果内容缺字段错误类型按errors.As设计见 doc.go 包注释业务代码可以精确分支例如仅对RateLimitError做指数退避重试、对JobFailedError记录服务端ErrorMsg并告警。九、构建与测试README 给出的标准质量门禁在api_sdk/go目录下执行go test ./... go vet ./... go test -race ./...README 特别建议公开发布前运行go test -race ./...做竞态检测。SDK 自带测试文件 client_test.go配合上文提到的零第三方依赖特性集成成本非常低。十、小结与延伸阅读PaddleOCR Go SDK 的设计可以概括为三点标准库实现的零依赖客户端、一键式 / 手动式 / Operation三层异步任务 API、面向errors.As的类型化错误体系。它默认把 OCR 指向 PP-OCRv6、文档解析指向 PaddleOCR-VL-1.6并通过ExtraOptions与 Options 结构中的大量开关把服务端能力完整暴露给 Go 代码。想继续深入时建议按以下路径阅读仓库源码与文档SDK 入口与鉴权api_sdk/go/client.go、api_sdk/go/options.go提交/等待/结果解析api_sdk/go/ocr.go、api_sdk/go/transport.go、api_sdk/go/poller.go可运行示例OCR URL 示例、文档解析示例官方文档Go SDK 中文文档、Go SDK 英文文档、官方 API 总览同族语言实现可对照阅读TypeScript SDK。需要注意的前提与限制该 SDK 仅适用于 PaddleOCR 官方托管 API默认地址https://paddleocr.aistudio-app.com可通过PADDLEOCR_BASE_URL或WithBaseURL指向自建网关需要有效的 Access Token它不执行本地推理因此对文档隐私敏感的场景应评估数据外发策略后再集成。【免费下载链接】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），仅供参考