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_TOKENyour-access-tokenNewClient默认从环境变量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.goFilePath传入本地文件路径SDK 会以 multipart 表单上传见 transport.go 的submitFile实现。FileURL与FilePath必须二选一。这一约束在源码 ocr.go 的submit方法中强制校验两者都为空或同时非空都会返回InvalidRequestError。公共 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(...)保存文档解析结果对象引用的资源阻塞下载从源码 ocr.go 可以看到OCR与ParseDocument本质上是SubmitOCR/SubmitDocumentParsing加WaitOCRResult/WaitDocumentParsingResult的组合方便在结果立即可用时直接同步等待。除上述方法外SDK 还提供了两个进阶能力见 operation.go 与 ocr.goOperation任务句柄可通过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, i1, 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。任务适用接口默认模型可选模型参数类型OCROCR、SubmitOCR、WaitOCRResultPPOCRv6PPOCRv5、PPOCRv6*OCROptions文档解析ParseDocument、SubmitDocumentParsing、WaitDocumentParsingResultPaddleOCRVL16PPStructureV3、PaddleOCRVL、PaddleOCRVL15、PaddleOCRVL16选择PPStructureV3时传入*PPStructureV3Options选择 PaddleOCR-VL 系列模型时传入*PaddleOCRVLOptions。源码层面的模型约束体现在两方面默认值回落SubmitOCR中Model为空时默认PPOCRv6SubmitDocumentParsing中默认PaddleOCRVL16见 ocr.go合法性校验提交前通过IsOCRModel/IsDocumentParsingModel校验模型名非法模型直接返回InvalidRequestError同时IsVLModel用于区分 PaddleOCR-VL 系列影响默认 Options 的构造见 ocr.go。从源码可见还有一个文档未展开的 OCR 模型常量PPOCRv5LatinPP-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常用字段字段类型说明UseDocOrientationClassify*bool文档方向分类UseDocUnwarping*bool文档扭曲矫正Visualize*bool是否返回可视化结果图除上述常用字段外models.go 中该结构体还包含完整的检测/识别调参项UseTextlineOrientation文本行方向分类、TextDetLimitSideLen/TextDetLimitType检测边长限制、TextDetThresh/TextDetBoxThresh/TextDetUnclipRatio检测后处理阈值、TextRecScoreThresh识别置信度阈值适合需要精细调节 OCR 精度的场景。PPStructureV3Options常用字段字段类型说明UseTableRecognition*bool表格识别UseFormulaRecognition*bool公式识别UseChartRecognition*bool图表识别PrettifyMarkdown*boolMarkdown 美化models.go 中该结构体还提供了大量进阶开关UseSealRecognition印章识别、UseRegionDetection区域检测、FormatBlockContent块内容格式化、MarkdownIgnoreLabels忽略指定版面标签、ShowFormulaNumber公式编号、ReturnMarkdownImages返回 Markdown 图片、OutputFormats导出格式列表以及有线/无线表格 HTML 转换、表格方向分类、端到端表格识别模型等一组Use*开关可按实际版面解析需求组合启用。PaddleOCRVLOptions常用字段字段类型说明UseLayoutDetection*bool版面检测UseChartRecognition*bool图表识别Temperature*float64采样温度PrettifyMarkdown*boolMarkdown 美化models.go 中该结构体还包含 LLM/VLM 类参数与版面控制参数RepetitionPenalty重复惩罚、TopP、MaxNewTokens生成上限、MinPixels/MaxPixels图像像素范围、PromptLabel提示标签、LayoutShapeMode、MergeLayoutBlocks、MergeTables、RelevelTitles标题层级重排、RestructurePages页面重构等适合对 VL 模型的输出行为做精细控制。结果数据结构理解结果结构有助于正确消费输出定义见 results.goOCRResult包含JobID、Pages []OCRPage与DataInfo。每个OCRPage暴露PrunedResult精简后的文本结果解析自服务端 JSONL 的ocrResults、OCRImageURLOCR 可视化图、DocPreprocessingImageURL文档预处理图、InputImageURL输入图以及Raw原始 JSON见 ocr.goDocParsingResult每个DocParsingPage暴露MarkdownTextMarkdown 正文、MarkdownImagesMarkdown 内图片 URL 映射、OutputImages输出图片映射、PrunedResult、InputImageURL、Exports与Markdown原始 markdown 对象解析逻辑见 ocr.goJobStatus包含Statepending/running/done/failed见 ocr.go 的状态归一化逻辑、ProgressTotalPages/ExtractedPages/StartTime/EndTime、ResultURL与ErrorMsgBatchStatus包含BatchID与Jobs []*JobStatus对应批量查询结果。保存结果资源服务端返回的图片等资源是 URL需调用保存方法下载到本地SaveResource(ctx, resourceURL, dest, ...)dest可以是完整文件路径也可以是已存在的目录此时自动以 URL 文件名命名默认目标已存在时报错可通过WithOverwrite(true)覆盖实现见 resource.goSaveOCRResultResources(ctx, result, destDir, ...)遍历 OCR 结果的每一页把OCRImageURL下载为ocr-page-{n}{ext}文件SaveDocumentParsingResultResources(ctx, result, destDir, ...)遍历文档解析结果的每一页把MarkdownImages与OutputImages两张映射里的所有资源下载到目标目录。注意 resource.go 对文件名做了安全校验拒绝空名、..、绝对路径与含分隔符的名字目标目录不存在时返回FileNotFoundError。错误处理Go SDK 暴露可与errors.As配合使用的类型化错误定义见 errors.go覆盖以下情况错误类型触发场景AuthError令牌缺失、401/403 鉴权失败InvalidRequestError请求参数非法如 FileURL/FilePath 同时设置、模型名非法RateLimitErrorHTTP 429 限流ServiceUnavailableErrorHTTP 503/504 服务不可用APIError其他非 2xx 响应携带StatusCodeNetworkError网络层错误JobFailedError任务进入failed状态携带JobID与ErrorMsgRequestTimeoutError单次 HTTP 请求超时PollTimeoutError轮询超过WithPollTimeout上限携带JobID与ElapsedResponseFormatError响应结构不符合预期缺失state/jobId/data等ResultParseError结果 JSONL 解析失败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.goAPI 配额规则和错误码说明详见官方配额文档涉及并发限制、调用频率与计费相关内容上线前务必核对服务端任务状态机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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考