企业官网建设流程全解析

PaddleOCR 官方 API Go SDK 实战指南：从任务提交到结果解析与资源下载

【免费下载链接】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 的 Go SDK（位于仓库 api_sdk/go），它用于把 OCR 或文档解析任务提交到官方托管服务，适合需要快速把"图片/PDF → 结构化文本（含 Markdown、表格、公式）"能力接入 Go 后端的场景。读完本文，你将掌握 SDK 的安装认证、同步/异步两种调用模式、三类模型的选择与参数配置、类型化错误处理，以及结果资源的批量下载，并能直接参考 examples 写出可运行代码。

需要先明确一点：Go SDK不运行本地 PaddleOCR 推理，也不加载本地模型，所有计算都在官方托管服务上完成，SDK 只负责认证、提交任务、轮询状态、拉取并解析结果，因此业务侧无需关心 GPU 与模型权重部署。

安装与认证

获取访问令牌

使用前需先在 AI Studio Access Token 页面获取访问令牌（Access Token），它是 SDK 调用官方 API 的身份凭证，请妥善保管。

安装 SDK 与配置令牌

go get github.com/PaddlePaddle/PaddleOCR/api_sdk/go export PADDLEOCR_ACCESS_TOKEN="your-access-token"

NewClient默认从环境变量PADDLEOCR_ACCESS_TOKEN读取令牌，也可以通过WithToken显式传入。从 client.go 的实现可以看到完整的初始化逻辑：

• 若未传入 token 且环境变量为空，直接返回AuthError，提示Token is required. Set PADDLEOCR_ACCESS_TOKEN or use WithToken().；
• 服务地址依次取自WithBaseURL选项、环境变量PADDLEOCR_BASE_URL，最后回落到 options.go 中定义的DefaultBaseURL = "https://paddleocr.aistudio-app.com"，路径后缀为/api/v2/ocr/jobs；
• 未显式注入 HTTP 客户端时，会基于requestTimeout构造默认*http.Client。

也就是说，即使不写任何配置，只要设置了令牌环境变量，paddleocr.NewClient()即可直接使用。

快速开始：提交 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))

这里ctx是一个context.Context，用于控制取消与超时。任务输入有两种方式：

• FileURL：传入可公开访问的文件 URL（示例见 ocr_url/main.go）；
• FilePath：传入本地文件路径，SDK 会以 multipart 表单上传（见 transport.go 的submitFile实现）。

FileURL与FilePath必须二选一。这一约束在源码 ocr.go 的submit方法中强制校验：两者都为空或同时非空都会返回InvalidRequestError。

公共 API 一览

Go SDK 的公共方法分为"提交即等待"的同步便利方法和"先提交、后轮询"的异步控制方法两组：

从源码 ocr.go 可以看到，OCR与ParseDocument本质上是SubmitOCR/SubmitDocumentParsing加WaitOCRResult/WaitDocumentParsingResult的组合，方便在结果立即可用时直接同步等待。

除上述方法外，SDK 还提供了两个进阶能力（见 operation.go 与 ocr.go）：

• Operation任务句柄：可通过op.Wait(ctx)阻塞等待并解析结果，或op.Poll(ctx)单次查询状态并返回"是否完成"布尔值，适合嵌入自定义轮询循环；
• GetBatchStatus(ctx, batchID)批量状态查询：提交任务时可传入BatchID对多个任务分组，随后按批次统一查询状态（底层调用GET /api/v2/ocr/jobs/batch/{batchID}）。

同步与异步调用模式对比

以文档解析为例，两种模式在 doc_parsing_file/main.go 中有完整对照：

// 模式一：同步便利方法（阻塞直到完成） result, 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", i+1, page.MarkdownText) } // 模式二：先提交，后手动等待（可并发提交多个任务） 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)

异步模式适合批量场景：先一次性提交所有任务拿到JobID，再统一轮询，避免长任务串行排队。

模型选择

表中的模型常量是官方 API 模型名字符串的类型安全写法，提交请求时会转换为对应的实际模型名（常量定义见 models.go）。也可以直接传入官方 API 模型名字符串，例如Model: "PaddleOCR-VL-1.6"。

源码层面的模型约束体现在两方面：

• 默认值回落：SubmitOCR中Model为空时默认PPOCRv6，SubmitDocumentParsing中默认PaddleOCRVL16（见 ocr.go）；
• 合法性校验：提交前通过IsOCRModel/IsDocumentParsingModel校验模型名，非法模型直接返回InvalidRequestError；同时IsVLModel用于区分 PaddleOCR-VL 系列（影响默认 Options 的构造，见 ocr.go）。

从源码可见还有一个文档未展开的 OCR 模型常量PPOCRv5Latin（PP-OCRv5 拉丁语系变体），同样属于IsOCRModel的合法取值，可按需使用。

配置与参数

客户端配置

client, err := paddleocr.NewClient( paddleocr.WithRequestTimeout(30*time.Second), paddleocr.WithPollTimeout(5*time.Minute), )

• WithRequestTimeout限制一次 HTTP 请求，包括提交、查询状态和下载资源；
• WithPollTimeout限制OCR、ParseDocument、WaitOCRResult与WaitDocumentParsingResult的总等待时间。

未显式配置时，client.go 给出的默认值是requestTimeout = 5 * time.Minute、pollTimeout = 10 * time.Minute。调用方也可以通过context.Context取消请求，取消时 SDK 会立即返回context.Canceled。

轮询行为由 poller.go 控制：初始间隔3s，每次递增乘数1.5，最大间隔15s，直到任务进入done或failed状态，或达到pollTimeout截止时间。任务done后 SDK 会从resultUrl.jsonUrl拉取 JSONL 结果文件（fetchJSONL，见 transport.go）。

通过环境变量PADDLEOCR_BASE_URL或WithBaseURL指定自定义服务地址，适用于私有化网关或代理转发场景：

client, err := paddleocr.NewClient( paddleocr.WithBaseURL("https://my-proxy.com/paddle"), )

通过WithHTTPClient注入自定义*http.Client，适用于需要代理、自定义 TLS 或重试策略的场景：

client, err := paddleocr.NewClient( paddleocr.WithHTTPClient(myHTTPClient), )

其余可用选项（见 options.go）还包括：WithToken（显式传令牌）、WithTimeout（同时设置 request 与 poll 两个超时）、WithClientPlatform（附加Client-Platform请求头，用于标识调用方平台）。另注意 options.go 提供了paddleocr.Bool(v)辅助函数，用于构造*bool指针字段。

请求参数

Go SDK 的 Options 结构体字段使用 PascalCase，序列化时自动转换为 camelCase（通过jsontag 完成，见 models.go）。指针类型字段传nil表示不设置。此外每个 Options 结构体都带一个ExtraOptions map[string]interface{}透传字段，序列化时会合并进请求体（实现见 ocr.go），用于传递 SDK 尚未封装的新参数。完整字段定义见结构体源码或官方 API 参考。

OCROptions（常用字段）

除上述常用字段外，models.go 中该结构体还包含完整的检测/识别调参项：UseTextlineOrientation（文本行方向分类）、TextDetLimitSideLen/TextDetLimitType（检测边长限制）、TextDetThresh/TextDetBoxThresh/TextDetUnclipRatio（检测后处理阈值）、TextRecScoreThresh（识别置信度阈值），适合需要精细调节 OCR 精度的场景。

PPStructureV3Options（常用字段）

models.go 中该结构体还提供了大量进阶开关：UseSealRecognition（印章识别）、UseRegionDetection（区域检测）、FormatBlockContent（块内容格式化）、MarkdownIgnoreLabels（忽略指定版面标签）、ShowFormulaNumber（公式编号）、ReturnMarkdownImages（返回 Markdown 图片）、OutputFormats（导出格式列表），以及有线/无线表格 HTML 转换、表格方向分类、端到端表格识别模型等一组Use*开关，可按实际版面解析需求组合启用。

PaddleOCRVLOptions（常用字段）

models.go 中该结构体还包含 LLM/VLM 类参数与版面控制参数：RepetitionPenalty（重复惩罚）、TopP、MaxNewTokens（生成上限）、MinPixels/MaxPixels（图像像素范围）、PromptLabel（提示标签）、LayoutShapeMode、MergeLayoutBlocks、MergeTables、RelevelTitles（标题层级重排）、RestructurePages（页面重构）等，适合对 VL 模型的输出行为做精细控制。

结果数据结构

理解结果结构有助于正确消费输出（定义见 results.go）：

• OCRResult：包含JobID、Pages []OCRPage与DataInfo。每个OCRPage暴露PrunedResult（精简后的文本结果，解析自服务端 JSONL 的ocrResults）、OCRImageURL（OCR 可视化图）、DocPreprocessingImageURL（文档预处理图）、InputImageURL（输入图）以及Raw（原始 JSON，见 ocr.go）；
• DocParsingResult：每个DocParsingPage暴露MarkdownText（Markdown 正文）、MarkdownImages（Markdown 内图片 URL 映射）、OutputImages（输出图片映射）、PrunedResult、InputImageURL、Exports与Markdown（原始 markdown 对象），解析逻辑见 ocr.go；
• JobStatus：包含State（pending/running/done/failed，见 ocr.go 的状态归一化逻辑）、Progress（TotalPages/ExtractedPages/StartTime/EndTime）、ResultURL与ErrorMsg；
• BatchStatus：包含BatchID与Jobs []*JobStatus，对应批量查询结果。

保存结果资源

服务端返回的图片等资源是 URL，需调用保存方法下载到本地：

• SaveResource(ctx, resourceURL, dest, ...)：dest可以是完整文件路径，也可以是已存在的目录（此时自动以 URL 文件名命名）；默认目标已存在时报错，可通过WithOverwrite(true)覆盖（实现见 resource.go）；
• SaveOCRResultResources(ctx, result, destDir, ...)：遍历 OCR 结果的每一页，把OCRImageURL下载为ocr-page-{n}{ext}文件；
• SaveDocumentParsingResultResources(ctx, result, destDir, ...)：遍历文档解析结果的每一页，把MarkdownImages与OutputImages两张映射里的所有资源下载到目标目录。

注意 resource.go 对文件名做了安全校验（拒绝空名、..、绝对路径与含分隔符的名字），目标目录不存在时返回FileNotFoundError。

错误处理

Go SDK 暴露可与errors.As配合使用的类型化错误（定义见 errors.go），覆盖以下情况：

HTTP 状态码到错误类型的映射集中在 transport.go 的raiseForResponse中；网络错误由classifyHTTPError区分超时与一般网络错误（transport.go）。所有错误都内嵌PaddleOCRAPIError，可通过errors.As精确捕获分支处理，例如：

var pollTimeout *paddleocr.PollTimeoutError if errors.As(err, &pollTimeout) { // 任务超时未完成，可重试或记录 JobID 稍后查询 }

另外FileNotFoundError会在本地文件不存在或目标目录缺失时返回（errors.go）。

官方 API 参考与配额

• 官方 API 参考文档按模型分别提供：PP-OCRv5 API、PP-StructureV3 API、PaddleOCR-VL API、PaddleOCR-VL-1.5 API，字段的完整语义以官方 API 参考为准（SDK 结构体字段与之对应，见 models.go）；
• API 配额规则和错误码说明详见官方配额文档，涉及并发限制、调用频率与计费相关内容，上线前务必核对；
• 服务端任务状态机（pending→running→done/failed）与 JSONL 结果格式的定义见 transport.go 与 ocr.go 的解析实现，可据此自行扩展 SDK 未覆盖的逻辑。

小结

PaddleOCR 官方 API Go SDK 以"任务提交 + 状态轮询 + 结果解析"为核心模型，通过同步/异步两套方法、类型安全的模型常量与 Options 结构体，把官方托管服务的能力封装成了简洁的 Go API。实际落地时建议：用Submit*批量提交任务并以BatchID分组，用WithPollTimeout与context控制总等待时长，用errors.As对限流、超时、任务失败分别处理，最后用Save*ResultResources统一落盘结果图片。完整的可运行示例可在 ocr_url 与 doc_parsing_file 中查看。

【免费下载链接】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