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/PaddleOCRPaddleOCR 官方 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等网络相关字段没有绑定任何本地模型或推理引擎。调用链路本质上是提交作业 → 轮询状态 → 拉取结果三步提交文件URL 或本地路径与模型、参数服务端返回一个jobId客户端周期性地查询作业状态pending/running/done/failed并附带页面抽取进度作业完成后从结果 JSONL 中解析出每页的 OCR 文本或 Markdown 结构化内容。因此使用 SDK 的前提是拥有官方 API 的访问令牌且网络可达托管服务默认基址为https://paddleocr.aistudio-app.com见 options.go。安装与认证在 Go 项目中通过go get引入 SDKgo get github.com/PaddlePaddle/PaddleOCR/api_sdk/go首次使用前需要到 AI Studio 的访问令牌页面生成一个 Access Token。SDK 通过两种方式读取令牌# 方式一环境变量推荐避免硬编码 export PADDLEOCR_ACCESS_TOKENyour-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, i1, 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都为空 → 返回InvalidRequestErrorEither FileURL or FilePath is required.两者同时非空 → 返回InvalidRequestErrorFileURL and FilePath are mutually exclusive.。即必须且只能传其中一个。本地文件走 multipart 表单上传远程 URL 走 JSON body两种请求的构造见 transport.go。文档解析示例文档解析如把 PDF 转成结构化 Markdown使用ParseDocumentresult, 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) }仓库 examples/ocr_url/main.go 与 examples/doc_parsing_file/main.go 提供了可直接运行的完整示例覆盖 URL OCR、本地文件文档解析以及手动提交作业等场景。公共 API 全景SDK 将提交、等待、取结果、存资源拆成粒度不同的方法开发者可按需组合定义见 ocr.go、operation.go、resource.go方法行为OCR(ctx, req)提交 OCR 作业并阻塞等待完成返回*OCRResultParseDocument(ctx, req)提交文档解析作业并阻塞等待完成返回*DocParsingResultSubmitOCR(ctx, req)仅提交 OCR 作业立即返回*Job含JobIDSubmitDocumentParsing(ctx, req)仅提交文档解析作业返回*JobGetStatus(ctx, jobID)发起一次非阻塞的状态查询返回*JobStatusGetBatchStatus(ctx, batchID)按批次号查询一组作业的状态返回*BatchStatusWaitOCRResult(ctx, jobID)阻塞等待指定 OCR 作业完成并解析结果WaitDocumentParsingResult(ctx, jobID)阻塞等待指定文档解析作业完成并解析结果SaveResource(ctx, url, dest)下载单个结果资源图片等到本地SaveOCRResultResources(ctx, result, dir)下载 OCR 结果引用的所有图片资源SaveDocumentParsingResultResources(ctx, result, dir)下载文档解析结果引用的全部图片资源异步手动控制模式适合需要并行提交多任务、自行管理生命周期的场景// 手动提交拿到作业元数据 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.goop.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-OCRv6PPOCRv5 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。各任务可用的模型与默认值如下表任务接口默认模型支持的模型选项类型OCROCR,SubmitOCR,WaitOCRResultPPOCRv6PPOCRv5,PPOCRv6PPOCRv5Latin也通过IsOCRModel校验见源码*OCROptions文档解析ParseDocument,SubmitDocumentParsing,WaitDocumentParsingResultPaddleOCRVL16PPStructureV3,PaddleOCRVL,PaddleOCRVL15,PaddleOCRVL16PPStructureV3用*PPStructureV3OptionsPaddleOCR-VL 系列用*PaddleOCRVLOptions提交时若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.Minuteclient.goWithTimeout(d)可同时设置两者调用方还可以通过context.Context主动取消请求轮询循环会响应ctx.Done()并返回上下文错误poller.go。服务地址与 HTTP 客户端覆盖默认服务基址有两种方式// 环境变量方式 export PADDLEOCR_BASE_URLhttps://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 OptionsOptions 结构体字段采用 PascalCase 命名序列化到请求时会自动转为 camelCase依赖结构体上的 json tag所有字段均为指针类型值为nil时自动省略omitempty未设置即使用服务端默认行为。以布尔开关为例SDK 提供了paddleocr.Bool(v)辅助函数options.go来构造指针。OCROptions 常用字段字段类型说明UseDocOrientationClassify*bool文档方向分类UseDocUnwarping*bool文档畸变矫正展开UseTextlineOrientation*bool文本行方向分类TextDetLimitSideLen*int文本检测输入边长限制TextDetLimitType*string边长限制模式如min/maxTextDetThresh*float64检测二值化阈值TextDetBoxThresh*float64检测框阈值TextDetUnclipRatio*float64检测框扩张比例TextRecScoreThresh*float64识别置信度阈值Visualize*bool是否返回可视化结果图ExtraOptionsmap[string]interface{}透传的额外参数不参与序列化直接合并进 payload完整字段定义见 models.go。ExtraOptions的合并逻辑在 ocr.go结构体正常序列化后再把这些键值对覆盖写入 payload用于对接官方 API 的新增参数。PPStructureV3Options 常用字段字段类型说明UseTableRecognition*bool表格识别UseFormulaRecognition*bool公式识别UseChartRecognition*bool图表识别UseSealRecognition*bool印章识别UseRegionDetection*bool区域检测UseDocOrientationClassify/UseDocUnwarping/UseTextlineOrientation*bool文档预处理三件套LayoutThreshold/LayoutNms/LayoutUnclipRatio/LayoutMergeBboxesMode混合版面分析后处理参数FormatBlockContent*bool是否格式化块级内容PrettifyMarkdown*boolMarkdown 美化ShowFormulaNumber*bool显示公式编号ReturnMarkdownImages*bool返回 Markdown 引用的图片OutputFormats[]string输出格式列表MarkdownIgnoreLabels[]string生成 Markdown 时忽略的版面标签UseE2eWiredTableRecModel/UseE2eWirelessTableRecModel*bool有线/无线表格端到端识别模型Visualize/ExtraOptions—可视化与透传参数完整字段定义见 models.go。PaddleOCRVLOptions 常用字段字段类型说明UseLayoutDetection*bool版面检测UseChartRecognition*bool图表识别UseSealRecognition*bool印章识别UseOcrForImageBlock*bool对图片块执行 OCRTemperature*float64采样温度TopP/RepetitionPenalty*float64采样参数与重复惩罚MinPixels/MaxPixels*int输入图像像素范围约束MaxNewTokens*int生成最大 token 数PromptLabel*string提示词标签VlmExtraArgsmap[string]interface{}VLM 额外参数MergeLayoutBlocks/MergeTables/RelevelTitles/RestructurePages*bool块合并、表格合并、标题重分级、页面重排PrettifyMarkdown/ShowFormulaNumber/ReturnMarkdownImages/OutputFormats—Markdown 相关输出控制完整字段定义见 models.go。结果结构解析SDK 从服务端返回的 JSONL 中解析结果ocr.go、results.goOCR 结果*OCRResultJobID作业号Pages []OCRPage每页包含PrunedResult精简后的识别文本/结构化结果、OCRImageURL、DocPreprocessingImageURL、InputImageURL各类输出图片 URL以及Raw原始数据。文档解析结果*DocParsingResultJobIDPages []DocParsingPage每页包含MarkdownTextMarkdown 正文、MarkdownImagesMarkdown 引用图片 URL 映射、OutputImages、PrunedResult、InputImageURL、Exports与Raw。作业与状态Job携带JobID、Model、Taskocr或document_parsing、PageRanges、BatchIDJobStatus携带State、Progress、ResultURL、ErrorMsg。PageRanges与BatchID也支持在OCRRequest/DocParsingRequest中直接指定用于批量任务分组。结果资源下载SaveResource(ctx, resourceURL, dest, opts...)把单个资源 URL 下载到本地具备以下工程化细节resource.godest若是已存在目录则自动取 URL 路径中的文件名否则视为完整目标路径目标父目录必须存在且为目录否则返回FileNotFoundError默认不允许覆盖已存在文件可用WithOverwrite(true)开启下载采用临时文件 原子重命名/硬链接方式避免写入半截文件对资源文件名做安全校验拒绝绝对路径、..、含/或\的名称。SaveOCRResultResources会为每页生成ocr-page-N.ext命名的图片SaveDocumentParsingResultResources会遍历每页的MarkdownImages与OutputImages按 key 作为文件名、排序后依次下载。错误处理类型化错误体系SDK 提供与errors.As兼容的类型化错误errors.go可按类型精确处理不同故障错误类型触发场景AuthError令牌缺失、401/403 认证失败InvalidRequestError请求参数非法如 URL 与路径同传、目标文件已存在、非法模型名RateLimitErrorHTTP 429触发限流ServiceUnavailableErrorHTTP 503/504服务暂不可用APIError其他 HTTP 错误或 API 业务错误码含StatusCodeNetworkError网络层故障RequestTimeoutError单次 HTTP 请求超时PollTimeoutError轮询等待超时含JobID与ElapsedJobFailedError作业状态为failed含JobID与ErrorMsgResponseFormatError响应结构不符合预期ResultParseErrorJSONL 结果解析失败缺result、ocrResults、markdown.text等关键字段FileNotFoundError本地文件或目标目录不存在错误分类的核心在 transport.goHTTP 状态码被映射为对应错误类型网络超时被识别为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与错误信息进一步定位。小结与最佳实践令牌管理优先使用PADDLEOCR_ACCESS_TOKEN环境变量避免令牌硬编码进代码仓库调用模式取舍简单场景用OCR/ParseDocument同步等待高并发批量场景用SubmitOCR/SubmitDocumentParsing配合Operation.Poll或GetStatus自行调度超时与取消根据任务量级设置WithRequestTimeout与WithPollTimeout并通过context支持优雅取消模型与选项OCR 任务注意区分PPOCRv5/PPOCRv6文档解析任务按需在PPStructureV3与 PaddleOCR-VL 系列间选择并善用ExtraOptions透传新参数结果落盘使用Save*ResultResources统一保存结果图片注意其默认不覆盖、目录必须预先存在的行为错误分类处理用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考