PaddleOCR 官方 API SDKPython / TypeScript / Go 三语言客户端的目录组织、调用模型与源码级验证【免费下载链接】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本篇基于仓库中 api_sdk 维护文档 及其指向的源码系统讲解 PaddleOCR 官方 API SDK 的定位与目录布局三语言 SDK 分别位于何处、如何安装、最小调用示例是什么、客户端底层采用何种“提交任务 轮询结果”的异步模型以及如何在仓库根目录执行完整的测试验证。读完后你可以快速在 Python、TypeScript 或 Go 项目中接入 PaddleOCR 官方托管 OCR / 文档解析服务并理解 SDK 的鉴权、超时、错误处理等实现细节。核心定位调用官方托管 API而非本地推理api_sdk/README_cn.md 开宗明义地说明了本目录的性质本目录包含 PaddleOCR 官方 API SDK 的源码相邻维护文档。SDK 调用 PaddleOCR 官方 API 托管服务它们不在本地执行 PaddleOCR 推理也不加载本地模型。这意味着 API SDK 与仓库中ppocr/、tools/等本地训练/推理模块是两条完全不同的使用路径API SDK 路径本文主题把 OCR 与文档解析任务提交到 PaddleOCR 官方托管服务适合服务端集成、多语言技术栈、不想部署模型的场景本地推理路径使用paddleocr主包直接加载模型做本地推理适合数据不出域的离线场景。选择 API SDK 时需要申请 Access Token 并保证网络可达托管服务选择本地推理则无需 Token。目录组织与包位置API SDK 的三语言实现分散在不同目录api_sdk/README_cn.md 给出了完整的“包位置”映射表语言源码位置用户文档Pythonpaddleocr/主包的一部分Python SDKTypeScriptapi_sdk/typescript/TypeScript SDKGoapi_sdk/go/Go SDK其中需要特别注意两点Python SDK 不是独立包它是主paddleocr包的一部分实现集中在 paddleocr/_api_client/ 目录包含同步客户端client.py、异步客户端async_client.py、CLI 入口cli.py、HTTP 传输层_http.py、任务轮询器_poller.py与结果模型models.py等模块api_sdk/目录本身是“源码相邻维护文档”api_sdk/typescript/README_cn.md 与 api_sdk/go/README_cn.md 分别是 TypeScript 和 Go SDK 的包级 README与各自包目录内的 api_sdk/typescript/README_cn.md、api_sdk/go/README_cn.md 配套维护。正式的用户级文档统一放在docs/version3.x/inference_deployment/serving/paddleocr_official_api/下共五篇总览、Python SDK、TypeScript SDK、Go SDK 和 CLI。三语言 SDK 快速上手Go SDKGo SDK 是一个独立的 Go module模块路径为github.com/PaddlePaddle/PaddleOCR/api_sdk/go见 api_sdk/go/go.mod要求 Go 1.21。安装方式go get github.com/PaddlePaddle/PaddleOCR/api_sdk/go版本化发布使用api_sdk/go/v0.1.0这类子目录 module tagapi_sdk/go/README_cn.md。最小示例——先设置PADDLEOCR_ACCESS_TOKEN环境变量或在构造客户端时传入WithTokenexport PADDLEOCR_ACCESS_TOKENyour-access-tokenclient, 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))模型选择上Model字段可设为paddleocr.PPOCRv6或字符串PP-OCRv6使用 PP-OCRv6 云端 OCR 模型设为paddleocr.PPOCRv5Latin或PP-OCRv5-latin使用 PP-OCRv5 拉丁语系云端 OCR 模型。文档解析默认使用 PaddleOCR-VL-1.6doc, err : client.ParseDocument(ctx, paddleocr.DocParsingRequest{ FilePath: ./report.pdf, Options: paddleocr.PaddleOCRVLOptions{ UseChartRecognition: paddleocr.Bool(true), }, }) if err ! nil { return err } fmt.Println(doc.JobID, len(doc.Pages))TypeScript SDKTypeScript SDK 以 scoped npm 包paddleocr/api-sdk发布遵循语义化版本当前仓库内版本为 0.2.3见 api_sdk/typescript/package.json要求 Node.js 18同时提供 ESMdist/index.js与 CJSdist/index.cjs双格式入口。安装npm install paddleocr/api-sdk本地开发需先安装依赖并构建npm install npm run build最小示例import { Model, PaddleOCRClient } from paddleocr/api-sdk; const client new PaddleOCRClient(); const result await client.ocr({ model: Model.PPOCRv5, fileUrl: https://example.com/invoice.pdf, }); console.log(result.jobId, result.pages.length);同样地model: Model.PPOCRv6或PP-OCRv6可指定 PP-OCRv6 云端 OCR 模型Model.PPOCRv5Latin或PP-OCRv5-latin可指定拉丁语系模型。文档解析默认使用 PaddleOCR-VL-1.6const doc await client.parseDocument({ filePath: ./report.pdf, options: { useChartRecognition: true, }, }); console.log(doc.jobId, doc.pages.length);Python SDKPython SDK 随主paddleocr包一起安装pip install paddleocr即可无需额外安装独立包其实现位于 paddleocr/_api_client/同时提供同步client.py与异步async_client.py客户端并附带 CLI 工具cli.py可直接在命令行发起任务。详细用法参见 Python SDK 用户文档 与 CLI 用户文档。客户端实现要点从源码看 API 的工作模型鉴权与环境变量以 Go SDK 的 api_sdk/go/client.go 为例NewClient的初始化逻辑清晰地展示了鉴权与地址解析的优先级Token优先使用WithToken(token)显式传入的值若未设置回退读取环境变量PADDLEOCR_ACCESS_TOKEN两者都为空时直接返回AuthError提示“Token is required. Set PADDLEOCR_ACCESS_TOKEN or use WithToken().”Base URL优先使用WithBaseURL(url)其次读取环境变量PADDLEOCR_BASE_URL最后回退到默认托管地址常量DefaultBaseURL https://paddleocr.aistudio-app.comapi_sdk/go/options.go。最终请求路径固定拼接为baseURL /api/v2/ocr/jobsapiPath常量api_sdk/go/options.go表明三语言 SDK 共用同一套 v2 Jobs REST API。此外WithClientPlatform选项会在每个请求上附加Client-Platform头api_sdk/go/client.go便于服务端区分调用来源WithHTTPClient允许注入自定义*http.Client方便对接代理或自定义传输策略。异步任务模型与超时配置从 api_sdk/go/doc.go 的包文档可以推断官方 API 采用异步作业Job模型阻塞式入口OCR/ParseDocument提交任务后内部轮询直到出结果非阻塞入口SubmitOCR/SubmitDocumentParsing立即返回一个Operation之后可手动Poll查询状态或调用WaitOCR/WaitDocumentParsing做带类型的等待结果资源下载SaveResource下载单个资源 URLSaveOCRResultResources/SaveDocumentParsingResultResources将类型化结果对象中的资源批量保存到既有目录。超时被拆分为两个独立配置api_sdk/go/client.go配置项默认值含义requestTimeout5 分钟单次 HTTP 请求提交任务、查询状态、下载资源的超时pollTimeout10 分钟轮询等待任务完成的总时长上限对应的选项函数为WithRequestTimeout/WithPollTimeout单独调整以及WithTimeout同时设置两者api_sdk/go/options.go。Python 侧的轮询逻辑同样独立成模块见 paddleocr/_api_client/_poller.py 与异步版 paddleocr/_api_client/_async_poller.py说明“提交 轮询”是三语言 SDK 统一的底层设计。模型常量与请求选项Go 的 api_sdk/go/models.go 定义了云端模型常量与三个判别函数const ( 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 )IsOCRModel判定模型是否用于 OCR 接口当前为 PP-OCRv5、PP-OCRv5-latin、PP-OCRv6IsDocumentParsingModel判定模型是否用于文档解析接口PP-StructureV3 及 PaddleOCR-VL 系列IsVLModel判定是否属于 PaddleOCR-VL 视觉语言模型家族。请求体方面OCRRequest与DocParsingRequest共享Model / FileURL / FilePath / PageRanges / BatchID字段——即同一任务接口同时支持远程 URL 直传FileURL与本地文件上传FilePath如示例中的./report.pdf并可用PageRanges指定页范围、BatchID标记批次。选项结构体则按能力分层字段以*bool/*float64等指针类型实现“省略即不下发”OCROptions文档方向分类useDocOrientationClassify、文档扭曲矫正useDocUnwarping、文本行方向分类、文本检测的limit_side_len/thresh/box_thresh/unclip_ratio、识别置信度阈值textRecScoreThresh、visualize等PPStructureV3Options在 OCR 选项之上增加印章识别、表格识别含有线/无线表格转 HTML、表格方向分类、端到端表格模型开关、公式识别、图表识别、版面参数layoutThreshold、layoutNms、layoutUnclipRatio等、Markdown 输出控制markdownIgnoreLabels、prettifyMarkdown、showFormulaNumber、outputFormats等PaddleOCRVLOptions面向视觉语言模型除版面检测、图表/印章识别外还暴露了生成式参数——repetitionPenalty、temperature、topP、minPixels/maxPixels、maxNewTokens以及promptLabel、mergeLayoutBlocks、restructurePages、mergeTables、relevelTitles等后处理开关并提供VlmExtraArgs透传额外 VLM 参数两个文档解析选项结构体均实现了DocParsingOptionsProvider标记接口api_sdk/go/models.go并都保留ExtraOptionsjson:-不参与序列化用于扩展。类型化错误体系api_sdk/go/doc.go 指出错误以类型化值暴露AuthError、InvalidRequestError、APIError、ResponseFormatError、ResultParseError并适配errors.As断言。实现见 api_sdk/go/errors.go这意味着调用方可以精确区分“Token 无效”应检查凭据、“请求参数不合法”应修参数、“服务端 API 错误”应看错误码与“响应格式/结果解析失败”客户端解析问题而不是笼统地捕获err。Python 侧对应 paddleocr/_api_client/errors.pyTypeScript 侧对应 api_sdk/typescript/src/errors.ts三语言保持了一致的错误分类思路。验证与本地开发流程api_sdk/README_cn.md 的“验证”一节给出了从仓库根目录出发的标准验证命令这也是贡献者在修改 SDK 后必须跑通的检查集# Python python -m pytest tests/api_client/ # TypeScript cd api_sdk/typescript npm run lint npm test # Go cd ../go go test ./...对应关系说明Python测试位于 tests/api_client/包含 test_core.py核心逻辑、test_http.pyHTTP 传输层、test_resources.py资源下载与 test_cli.pyCLI 行为TypeScriptnpm run lint实际执行tsc --noEmit做类型检查npm test执行vitest run测试位于 api_sdk/typescript/tests/client.test.ts包发布前还会触发prepublishOnly钩子自动串联lint → build → test三步api_sdk/typescript/package.jsonGoapi_sdk/go/client_test.go 覆盖客户端行为api_sdk/go/README_cn.md 额外建议公开发布前运行go vet ./...和go test -race ./...竞态检测go test ./... go vet ./... go test -race ./...小结如何选择合适的 SDK 与文档入口只想知道“能不能用、怎么配 Token、支持哪些模型”先看 官方 API 总览按语言接入Python 用 python.mdTypeScript 用 typescript.mdGo 用 go.md命令行场景用 cli.md想深入实现细节或提交贡献Python 读 paddleocr/_api_client/TypeScript 读 api_sdk/typescript/src/client.tsGo 读 api_sdk/go/ocr.go 与 api_sdk/go/transport.go并遵循上文“验证”一节跑通全部测试。需要再次强调的边界是以上所有 SDK 均为官方托管 API 的客户端任务在服务端执行本地不加载任何模型因此可用性前提是你已申请 Access Token、网络可达https://paddleocr.aistudio-app.com或通过PADDLEOCR_BASE_URL/WithBaseURL指向其他服务端点。【免费下载链接】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），仅供参考