跳转至

PaddleOCR 官方 API Go SDK

Go SDK 调用 PaddleOCR 官方 API，把 OCR 或文档解析任务提交到官方托管服务。它不运行本地 PaddleOCR 推理，也不加载本地模型。

安装与认证

请先在 AI Studio Access Token 页面 获取访问令牌。

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

NewClient 默认读取 PADDLEOCR_ACCESS_TOKEN，也可以通过 WithToken 显式传入 token。

快速开始

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

本地文件使用 FilePath。FileURL 与 FilePath 必须二选一。

公共 API

Go SDK 常用公共方法包括：

  • OCR(...)：提交 OCR 任务，等待完成并返回 OCR 结果。
  • ParseDocument(...)：提交文档解析任务，等待完成并返回文档解析结果。
  • SubmitOCR(...)：只提交 OCR 任务，返回任务对象。
  • SubmitDocumentParsing(...)：只提交文档解析任务，返回任务对象。
  • GetStatus(ctx, jobID)：执行一次非阻塞状态查询。
  • WaitOCRResult(ctx, job)：等待 OCR 任务完成并解析结果。
  • WaitDocumentParsingResult(ctx, job)：等待文档解析任务完成并解析结果。
  • SaveResource(...)：保存单个资源 URL。
  • SaveOCRResultResources(...)：保存 OCR 结果对象引用的资源。
  • SaveDocumentParsingResultResources(...)：保存文档解析结果对象引用的资源。

模型选择

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

任务 适用接口 默认模型 可选模型 参数类型
OCR OCR、SubmitOCR、WaitOCRResult PPOCRv5 PPOCRv5 *OCROptions
文档解析 ParseDocument、SubmitDocumentParsing、WaitDocumentParsingResult PaddleOCRVL16 PPStructureV3、PaddleOCRVL、PaddleOCRVL15、PaddleOCRVL16 选择 PPStructureV3 时传入 *PPStructureV3Options；选择 PaddleOCR-VL 系列模型时传入 *PaddleOCRVLOptions。

常用对应关系：PPOCRv5 对应 PP-OCRv5，PPStructureV3 对应 PP-StructureV3，PaddleOCRVL 对应 PaddleOCR-VL，PaddleOCRVL15 对应 PaddleOCR-VL-1.5，PaddleOCRVL16 对应 PaddleOCR-VL-1.6。

配置与参数

客户端配置

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

WithRequestTimeout 限制一次 HTTP 请求，包括提交、查询状态和下载资源。WithPollTimeout 限制 OCR、ParseDocument、WaitOCRResult 与 WaitDocumentParsingResult 的总等待时间。调用方也可以通过 context.Context 取消请求。

通过环境变量 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),
)

请求参数

Go SDK 的 Options 结构体字段使用 PascalCase，序列化时自动转换为 camelCase。指针类型字段传 nil 表示不设置。完整字段定义见结构体源码或「官方 API 参考」。

OCROptions（常用字段）

字段 类型 说明
UseDocOrientationClassify *bool 文档方向分类
UseDocUnwarping *bool 文档扭曲矫正
Visualize *bool 是否返回可视化结果图

PPStructureV3Options（常用字段）

字段 类型 说明
UseTableRecognition *bool 表格识别
UseFormulaRecognition *bool 公式识别
UseChartRecognition *bool 图表识别
PrettifyMarkdown *bool Markdown 美化

PaddleOCRVLOptions（常用字段）

字段 类型 说明
UseLayoutDetection *bool 版面检测
UseChartRecognition *bool 图表识别
Temperature *float64 采样温度
PrettifyMarkdown *bool Markdown 美化

错误处理

Go SDK 暴露可与 errors.As 配合使用的类型化错误，覆盖 AuthError、InvalidRequestError、RateLimitError、ServiceUnavailableError、APIError、NetworkError、JobFailedError、RequestTimeoutError、PollTimeoutError、ResponseFormatError 和 ResultParseError 等情况。

官方 API 参考

配额与错误码

评论