企业官网建设流程全解析

PaddleOCR 官方 API Go SDK 使用指南：云端 OCR 与文档解析的完整接入方案

【免费下载链接】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）是一套面向云端托管服务的客户端库，通过提交作业（Job）的方式调用 PaddleOCR 官方 API，完成 OCR 文字识别与文档解析（Document Parsing）任务。它不加载本地模型、不做本地推理，而是把 PDF 或图片交给托管服务处理，适合在 Go 服务端把任意 PDF/图片快速转化为可供 AI 与 LLM 消费的结构化数据。读完本文，你将掌握该 SDK 的安装认证、同步/异步两种调用模式、模型选择、客户端与请求级配置、结果解析以及类型化错误处理的全套实战用法。

SDK 定位：云端作业而非本地推理

Go SDK 与仓库中paddleocr、ppocr等本地训练/推理模块有本质区别：SDK 只负责与官方托管 API 通信。从 client.go 可以看到，Client内部只维护token、baseURL、requestTimeout、pollTimeout、httpClient等网络相关字段，没有绑定任何本地模型或推理引擎。

调用链路本质上是"提交作业 → 轮询状态 → 拉取结果"三步：

1. 提交文件（URL 或本地路径）与模型、参数，服务端返回一个jobId；
2. 客户端周期性地查询作业状态（pending/running/done/failed），并附带页面抽取进度；
3. 作业完成后，从结果 JSONL 中解析出每页的 OCR 文本或 Markdown 结构化内容。

因此使用 SDK 的前提是拥有官方 API 的访问令牌，且网络可达托管服务（默认基址为https://paddleocr.aistudio-app.com，见 options.go）。

安装与认证

在 Go 项目中通过go get引入 SDK：

go get github.com/PaddlePaddle/PaddleOCR/api_sdk/go

首次使用前，需要到 AI Studio 的访问令牌页面生成一个 Access Token。SDK 通过两种方式读取令牌：

# 方式一：环境变量（推荐，避免硬编码） export PADDLEOCR_ACCESS_TOKEN="your-access-token"

// 方式二：代码中显式传入 client, err := paddleocr.NewClient( paddleocr.WithToken("your-access-token"), )

NewClient的认证逻辑在 client.go：优先使用WithToken设置的令牌；若为空则读取环境变量PADDLEOCR_ACCESS_TOKEN；两者皆为空时直接返回*AuthError（错误信息为 "Token is required. Set PADDLEOCR_ACCESS_TOKEN or use WithToken()."），避免带病请求发出。

快速开始

基本用法：提交 URL 并同步等待

package main import ( "context" "fmt" "log" paddleocr "github.com/PaddlePaddle/PaddleOCR/api_sdk/go" ) func main() { client, err := paddleocr.NewClient() if err != nil { log.Fatal(err) } ctx := context.Background() result, err := client.OCR(ctx, &paddleocr.OCRRequest{ Model: paddleocr.PPOCRv5, FileURL: "https://example.com/invoice.pdf", }) if err != nil { log.Fatal(err) } for i, page := range result.Pages { fmt.Printf("Page %d: %v\n", i+1, page.PrunedResult) fmt.Printf(" Image URL: %s\n", page.OCRImageURL) } }

OCR(...)是同步便捷方法：内部先调用SubmitOCR提交作业，再调用WaitOCRResult阻塞轮询直到完成（见 ocr.go）。fmt.Println(result.JobID, len(result.Pages))可快速验证是否拿到作业号与页数。

本地文件与"二选一"校验

传入本地文件使用FilePath字段。SDK 在 ocr.go 中做了严格校验：

• FileURL与FilePath都为空 → 返回InvalidRequestError（"Either FileURL or FilePath is required."）；
• 两者同时非空 → 返回InvalidRequestError（"FileURL and FilePath are mutually exclusive."）。

即必须且只能传其中一个。本地文件走 multipart 表单上传，远程 URL 走 JSON body，两种请求的构造见 transport.go。

文档解析示例

文档解析（如把 PDF 转成结构化 Markdown）使用ParseDocument：

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) }

仓库 examples/ocr_url/main.go 与 examples/doc_parsing_file/main.go 提供了可直接运行的完整示例，覆盖 URL OCR、本地文件文档解析以及手动提交作业等场景。

公共 API 全景

SDK 将"提交、等待、取结果、存资源"拆成粒度不同的方法，开发者可按需组合（定义见 ocr.go、operation.go、resource.go）：

异步手动控制模式

适合需要并行提交多任务、自行管理生命周期的场景：

// 手动提交，拿到作业元数据 ocrJob, err := client.SubmitOCR(ctx, &paddleocr.OCRRequest{FileURL: "https://example.com/f1.pdf"}) docJob, err := 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)

此外Submit*返回的Job也可以交给Operation对象做更细粒度的控制（operation.go）：

• op.Wait(ctx)：阻塞到完成并解析结果（按模型类型自动选择 OCR 或文档解析解析器）；
• op.Poll(ctx)：单次非阻塞查询，返回(status, isDone, err)三元组，便于自行实现进度条或调度逻辑。

轮询策略细节

Wait*系列内部使用指数退避轮询（poller.go）：初始间隔3s，每次乘1.5，上限15s；总等待时长受pollTimeout约束，到期未完成返回*PollTimeoutError。GetStatus返回的Progress字段携带TotalPages、ExtractedPages、StartTime、EndTime，可用于向用户展示处理进度。

模型选择

SDK 在 models.go 中定义了类型安全的模型常量，它们是官方 API 模型名字符串的别名，提交请求时会被序列化为对应字符串（如PPOCRv6→"PP-OCRv6"）：

PPOCRv5 = "PP-OCRv5" PPOCRv5Latin = "PP-OCRv5-latin" PPOCRv6 = "PP-OCRv6" PPStructureV3 = "PP-StructureV3" PaddleOCRVL = "PaddleOCR-VL" PaddleOCRVL15 = "PaddleOCR-VL-1.5" PaddleOCRVL16 = "PaddleOCR-VL-1.6"

你也可以直接传字符串，例如Model: "PaddleOCR-VL-1.6"。各任务可用的模型与默认值如下表：

提交时若Model为空，SDK 会自动回退到默认模型（OCR 默认PPOCRv6，文档解析默认PaddleOCRVL16，见 ocr.go）。模型合法性由IsOCRModel/IsDocumentParsingModel校验，非法模型直接返回InvalidRequestError。DocParsingRequest.Options字段类型为DocParsingOptionsProvider接口（models.go），从编译期约束了文档解析只能使用上述两种 Options 结构。

客户端配置

NewClient接受可变数量的ClientOption函数（定义见 options.go）：

超时控制

client, err := paddleocr.NewClient( paddleocr.WithRequestTimeout(30*time.Second), // 单次 HTTP 请求（提交/查状态/下载资源）超时 paddleocr.WithPollTimeout(5*time.Minute), // 轮询等待作业完成的整体超时 )

• WithRequestTimeout限制单次 HTTP 请求，包括提交、状态查询和资源下载；
• WithPollTimeout限制OCR、ParseDocument、WaitOCRResult、WaitDocumentParsingResult的总等待时间；
• 两者未设置时，源码默认值为requestTimeout: 5*time.Minute、pollTimeout: 10*time.Minute（client.go）；
• WithTimeout(d)可同时设置两者；
• 调用方还可以通过context.Context主动取消请求，轮询循环会响应ctx.Done()并返回上下文错误（poller.go）。

服务地址与 HTTP 客户端

覆盖默认服务基址有两种方式：

// 环境变量方式 export PADDLEOCR_BASE_URL="https://my-proxy.com/paddle"

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

NewClient的优先级为：WithBaseURL> 环境变量PADDLEOCR_BASE_URL> 默认值https://paddleocr.aistudio-app.com，并会去除尾部/后拼接 API 路径/api/v2/ocr/jobs。

注入自定义*http.Client可支持代理、自定义 TLS 或重试策略：

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

其余选项：WithClientPlatform(platform)会在请求头中附加Client-Platform字段（client.go）。

请求选项（Request Options）

Options 结构体字段采用 PascalCase 命名，序列化到请求时会自动转为 camelCase（依赖结构体上的 json tag）；所有字段均为指针类型，值为nil时自动省略（omitempty），未设置即使用服务端默认行为。以布尔开关为例，SDK 提供了paddleocr.Bool(v)辅助函数（options.go）来构造指针。

OCROptions 常用字段

完整字段定义见 models.go。ExtraOptions的合并逻辑在 ocr.go：结构体正常序列化后，再把这些键值对覆盖写入 payload，用于对接官方 API 的新增参数。

PPStructureV3Options 常用字段

完整字段定义见 models.go。

PaddleOCRVLOptions 常用字段

完整字段定义见 models.go。

结果结构解析

SDK 从服务端返回的 JSONL 中解析结果（ocr.go、results.go）：

OCR 结果（*OCRResult）：

• JobID：作业号；
• Pages []OCRPage：每页包含PrunedResult（精简后的识别文本/结构化结果）、OCRImageURL、DocPreprocessingImageURL、InputImageURL（各类输出图片 URL）以及Raw（原始数据）。

文档解析结果（*DocParsingResult）：

• JobID；
• Pages []DocParsingPage：每页包含MarkdownText（Markdown 正文）、MarkdownImages（Markdown 引用图片 URL 映射）、OutputImages、PrunedResult、InputImageURL、Exports与Raw。

作业与状态：Job携带JobID、Model、Task（"ocr"或"document_parsing"）、PageRanges、BatchID；JobStatus携带State、Progress、ResultURL、ErrorMsg。PageRanges与BatchID也支持在OCRRequest/DocParsingRequest中直接指定，用于批量任务分组。

结果资源下载

SaveResource(ctx, resourceURL, dest, opts...)把单个资源 URL 下载到本地，具备以下工程化细节（resource.go）：

• dest若是已存在目录，则自动取 URL 路径中的文件名；否则视为完整目标路径；
• 目标父目录必须存在且为目录，否则返回FileNotFoundError；
• 默认不允许覆盖已存在文件（可用WithOverwrite(true)开启）；
• 下载采用"临时文件 + 原子重命名/硬链接"方式，避免写入半截文件；
• 对资源文件名做安全校验（拒绝绝对路径、..、含/或\的名称）。

SaveOCRResultResources会为每页生成ocr-page-N.ext命名的图片；SaveDocumentParsingResultResources会遍历每页的MarkdownImages与OutputImages，按 key 作为文件名、排序后依次下载。

错误处理：类型化错误体系

SDK 提供与errors.As兼容的类型化错误（errors.go），可按类型精确处理不同故障：

错误分类的核心在 transport.go：HTTP 状态码被映射为对应错误类型；网络超时被识别为RequestTimeoutError，其余网络错误归为NetworkError。推荐的处理模式：

result, err := client.OCR(ctx, req) if err != nil { var rate *paddleocr.RateLimitError if errors.As(err, &rate) { // 退避后重试 } var jobErr *paddleocr.JobFailedError if errors.As(err, &jobErr) { log.Printf("job %s failed: %s", jobErr.JobID, jobErr.ErrorMsg) } }

配额与错误码

官方 API 有配额限制与错误码约定（涉及额度耗尽、限流时的行为），建议在实际接入前阅读官方 API 的配额规则与错误码说明文档，并结合本文的错误类型对照处理。配额不足时通常对应RateLimitError或服务端返回的业务错误码，可通过APIError.StatusCode与错误信息进一步定位。

小结与最佳实践

1. 令牌管理：优先使用PADDLEOCR_ACCESS_TOKEN环境变量，避免令牌硬编码进代码仓库；
2. 调用模式取舍：简单场景用OCR/ParseDocument同步等待；高并发批量场景用SubmitOCR/SubmitDocumentParsing配合Operation.Poll或GetStatus自行调度；
3. 超时与取消：根据任务量级设置WithRequestTimeout与WithPollTimeout，并通过context支持优雅取消；
4. 模型与选项：OCR 任务注意区分PPOCRv5/PPOCRv6，文档解析任务按需在PPStructureV3与 PaddleOCR-VL 系列间选择，并善用ExtraOptions透传新参数；
5. 结果落盘：使用Save*ResultResources统一保存结果图片，注意其默认不覆盖、目录必须预先存在的行为；
6. 错误分类处理：用errors.As区分限流、认证、作业失败与超时，分别制定重试与告警策略。

仓库中 api_sdk/go/examples 目录提供了 URL OCR 与本地文件文档解析的可运行示例，api_sdk/go/README_cn.md 与 api_sdk/go/client_test.go 可作为进一步参考，帮助你快速把 PDF/图片接入结构化数据流水线。

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