PaddleOCR TypeScript SDK 实战指南：从 Node.js 调用官方托管 OCR 与文档解析服务

PaddleOCR TypeScript SDK 实战指南从 Node.js 调用官方托管 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 TypeScript SDK 包级文档 为主体系统讲解paddleocr/api-sdk的安装配置、云端 OCR 与文档解析两类任务的完整调用方式并结合api_sdk/typescript/src下的源码深入剖析其模型选择、异步任务轮询、结果结构与错误处理机制帮助你在 Node.js 服务或脚本中稳定接入 PaddleOCR 官方 API。一、SDK 定位官方 API 客户端而非本地推理TypeScript SDK 是面向 PaddleOCR 官方 API 的客户端。它的核心行为边界需要首先明确所有 OCR 和文档解析任务都会被提交到 PaddleOCR 官方托管服务执行SDK 本身不会在本地执行 OCR 推理也不加载任何本地模型README 原文。这一设计带来两个直接后果接入成本极低无需安装 PaddlePaddle、无需 GPU 环境只要 Node.jsengines要求node 18见 package.json即可调用任务模型是提交—轮询—取结果的异步模式一次 API 调用只返回jobId最终结果需要轮询任务状态后从结果文件JSONL中读取。该 SDK 与 Python SDK、Go SDK、CLI 属于同一官方 API 接入体系总览见 官方 API 文档TypeScript 专项文档见 typescript.md英文版。二、安装与本地开发生产环境安装只需一行命令包以公开 scoped npm 包形式发布并遵循语义化版本当前仓库内版本为0.2.3见 package.jsonnpm install paddleocr/api-sdk从 package.json 可以看到该包同时提供 ESM 与 CJS 两种入口type: moduleexports字段中import指向dist/index.js、require指向dist/index.cjs类型声明分别为index.d.ts/index.d.cts。也就是说无论你的项目用 ESM现代 Node.js / Deno / 打包器还是 CommonJS都能直接引入并享有完整的 TypeScript 类型提示。如果是基于本仓库做二次开发包内开发流程为npm install npm run build其中build脚本调用 tsup 完成产物打包lint脚本实为tsc --noEmit的类型检查见 package.json 的scripts段。三、客户端配置与鉴权SDK 的入口类是PaddleOCRClientsrc/client.ts通过 src/index.ts 统一导出。3.1 Token环境变量或构造参数二选一最小示例来自 README通过环境变量提供访问令牌export PADDLEOCR_ACCESS_TOKENyour-access-token也可以直接在构造客户端时传入token。二者的优先级在构造函数中明确实现src/client.tsconstructor(options: ClientOptions {}) { const token options.token || process.env.PADDLEOCR_ACCESS_TOKEN || ; if (!token) { throw new AuthError(Token is required. Set PADDLEOCR_ACCESS_TOKEN or pass token option.); } const baseUrl options.baseUrl || process.env.PADDLEOCR_BASE_URL || DEFAULT_BASE_URL; const requestTimeout options.requestTimeout || options.timeout || 300000; const pollTimeout options.pollTimeout || options.timeout || 600000; ... }由此可以确认四条事实构造参数token优先于环境变量未提供两者时构造阶段就抛出AuthError不会等到发请求才失败服务地址可用baseUrl参数或环境变量PADDLEOCR_BASE_URL覆盖默认值为https://paddleocr.aistudio-app.comsrc/client.tsrequestTimeout控制单次 HTTP 请求超时默认 300000 ms5 分钟pollTimeout控制等待任务完成的总时长默认 600000 ms10 分钟。timeout是一个兼容字段同时作为二者的回退默认值。3.2 ClientOptions 全量字段ClientOptions定义于 src/models.ts字段类型说明tokenstring访问令牌缺省时读取PADDLEOCR_ACCESS_TOKENbaseUrlstringAPI 基地址缺省时读取PADDLEOCR_BASE_URL否则用官方默认地址timeoutnumber兼容字段同时作为requestTimeout与pollTimeout的回退值requestTimeoutnumber单次 HTTP 请求超时ms默认 300000pollTimeoutnumber任务轮询总等待时长ms默认 600000clientPlatformstring自定义Client-Platform请求头用于服务端识别调用来源fetchtypeof fetch注入自定义 fetch 实现便于测试或更换底层传输其中fetch注入点在 src/internal/http.ts 中被全程使用这也是 tests/client.test.ts 能够不打真实网络就验证整套提交流程的关键。四、云端 OCRclient.ocr最小示例与模型选择4.1 最小示例README 给出的最小示例完整可复制运行前提是已配置PADDLEOCR_ACCESS_TOKENimport { 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);仓库中还有一个更贴近真实使用姿势的示例 examples/ocr-url.ts它遍历每一页并打印裁剪结果与可视化图片地址for (const page of ocrResult.pages) { console.log(Result:, page.prunedResult); console.log(Image:, page.ocrImageUrl); }4.2 模型参数不传时的默认值README 说明了两种显式指定方式model: Model.PPOCRv6或字符串PP-OCRv6指定 PP-OCRv6 云端 OCR 模型Model.PPOCRv5Latin或PP-OCRv5-latin指定 PP-OCRv5 拉丁语系模型。值得注意的一个细节是不传model时OCR 任务的默认模型是PP-OCRv6这是 src/client.ts 中submitOcr的显式回退逻辑async submitOcr(req: OCRRequest, options?: { signal?: AbortSignal }): PromiseJob { const model req.model ?? Model.PPOCRv6; ... }Model枚举的完整取值定义在 src/models.ts枚举成员实际字符串值任务类别Model.PPOCRv5PP-OCRv5OCRModel.PPOCRv5LatinPP-OCRv5-latinOCRModel.PPOCRv6PP-OCRv6OCRocr()的默认模型Model.PPStructureV3PP-StructureV3文档解析Model.PaddleOCRVLPaddleOCR-VL文档解析Model.PaddleOCRVL15PaddleOCR-VL-1.5文档解析Model.PaddleOCRVL16PaddleOCR-VL-1.6文档解析parseDocument()的默认模型模型与任务的合法性由isOCRModel/isDocumentParsingModel/isVLModel三个类型守卫检查src/models.ts。客户端在提交前会调用validateModelForTask给 OCR 任务传文档解析模型或反向会在本地直接抛出InvalidRequestError不会浪费一次网络请求src/client.ts。4.3 请求参数 OCRRequestOCRRequest的完整定义src/models.ts字段类型说明modelModel \| string模型缺省为PP-OCRv6fileUrlstring文件公网 URL与filePath二选一filePathstring本地文件路径Node.js 环境与fileUrl二选一pageRangesstring页码范围只对支持分页的文档格式生效batchIdstring批次 ID便于用getBatchStatus统一查看进度optionsOCROptions传给服务端的算法可选参数fileUrl与filePath的互斥校验在 src/client.ts 中实现两者都不传、或同时传都会抛出InvalidRequestError。走 URL 提交是 JSON 请求体走本地文件则是 SDK 读取文件后以 multipartFormData上传src/internal/http.ts文件不存在时抛出FileNotFoundError。4.4 OCROptionsOCR 算法可选参数OCROptions定义于 src/models.ts常用字段包括字段类型作用useDocOrientationClassifyboolean是否启用文档方向分类useDocUnwarpingboolean是否启用文档图像扭曲矫正useTextlineOrientationboolean是否启用文本行方向分类textDetLimitSideLennumber文本检测输入图像最长边限制textDetLimitTypestring长边限制的生效方式textDetThreshnumber文本检测二值化阈值textDetBoxThreshnumber文本框置信度过滤阈值textDetUnclipRationumberDB 后处理 unclip 放大比例textRecScoreThreshnumber文本识别结果置信度过滤阈值visualizeboolean是否返回可视化图片接口末尾的[key: string]: unknown索引签名意味着文档中尚未固化的新参数也可以直接透传服务端按实际能力消费。五、文档解析client.parseDocument与 PaddleOCR-VLREADME 中给出文档解析默认使用 PaddleOCR-VL-1.6。最小示例const doc await client.parseDocument({ filePath: ./report.pdf, options: { useChartRecognition: true, }, }); console.log(doc.jobId, doc.pages.length);对应源码中parseDocument的默认模型回退是Model.PaddleOCRVL16src/client.ts。仓库示例 examples/doc-parsing-file.ts 展示了显式选择Model.PPStructureV3并读取每页 Markdown 的写法const result await client.parseDocument({ model: Model.PPStructureV3, filePath: ./sample.pdf, options: { useChartRecognition: true }, }); for (const page of result.pages) { console.log(page.markdownText); }5.1 两类文档解析模型的选项差异DocParsingOptions是PPStructureV3Options | PaddleOCRVLOptions的联合类型src/models.ts。两个接口都包含方向分类、文档矫正、布局阈值layoutThreshold、layoutNms、layoutUnclipRatio、layoutMergeBboxesMode、文本检测/识别阈值、Markdown 输出控制prettifyMarkdown、markdownIgnoreLabels、returnMarkdownImages、outputFormats等公共项差异在于PPStructureV3Optionssrc/models.ts面向传统结构管线提供useTableRecognition、useFormulaRecognition、useChartRecognition、useSealRecognition、useRegionDetection、有/无线表格 HTML 转换useWiredTableCellsTransToHtml/useWirelessTableCellsTransToHtml、端到端表格模型开关useE2eWiredTableRecModel/useE2eWirelessTableRecModel等细粒度能力开关PaddleOCRVLOptionssrc/models.ts面向视觉-语言模型除公共项外还包含useLayoutDetection、promptLabelocr | formula | table | chart | seal | spotting、生成采样参数temperature、topP、repetitionPenalty、视觉输入像素限制minPixels、maxPixels、maxNewTokens、vlmExtraArgs以及版面重构开关restructurePages、mergeTables、relevelTitles等。从接口分组可以推断PaddleOCRVLOptions的生成类参数对应服务端 VLM 推理的采样行为而PPStructureV3Options的开关类参数对应传统检测—识别管线的模块裁剪。六、底层通信API 路径、鉴权头与错误映射SDK 的 HTTP 层集中在 src/internal/http.ts可以直接确认以下实现事实提交任务端点为{baseUrl}/api/v2/ocr/jobsL28-L29URL 提交走 JSON body本地文件走 multipart 表单字段model、optionalPayload、file以及可选pageRanges、batchId所有鉴权请求都携带Authorization: Bearer {token}若设置了clientPlatform还会附加Client-Platform头L185-L193查询状态走GET /api/v2/ocr/jobs/{jobId}批次状态走GET /api/v2/ocr/jobs/batch/{batchId}统一响应封装为{ code, msg, data }code非 0 时抛出APIErrorJSON 解析失败抛出ResponseFormatErrorL155-L176。HTTP 状态码到异常类型的映射逻辑在 src/internal/http.tsHTTP 状态抛出异常401 / 403AuthError400InvalidRequestError429RateLimitError503 / 504ServiceUnavailableError其他非 2xxAPIError携带statusCode超时 / 连接失败RequestTimeoutError/NetworkError七、异步任务模型提交、轮询与等待SDK 把一次调用拿结果拆成了两层 APIexamples/doc-parsing-file.ts 同时演示了两种用法便捷层内部自动完成提交 轮询 解析const result await client.ocr(req); // OCR const doc await client.parseDocument(req); // 文档解析手动层适合并发提交多个任务后统一等待const job1 await client.submitOcr({ fileUrl: https://example.com/f1.pdf }); const job2 await client.submitDocumentParsing({ model: Model.PPStructureV3, filePath: ./sample.pdf, }); const [r1, r2] await Promise.all([ client.waitOcrResult(job1.jobId), client.waitDocumentParsingResult(job2.jobId), ]);手动层返回的Job结构包含jobId、model、taskocr | document_parsing、pageRanges、batchIdsrc/results.ts。waitOcrResult/waitDocumentParsingResult既接受Job对象也接受裸jobId字符串若传入Job对象但任务类型不匹配例如拿 OCR 的 job 去等文档解析结果会抛出InvalidRequestError防止误读src/client.ts。7.1 轮询器指数退避与超时语义轮询逻辑在 src/internal/poller.ts关键参数为编译期常量常量值含义INITIAL_INTERVAL3000 ms首次查询状态前的等待间隔MULTIPLIER1.5每轮间隔放大系数MAX_INTERVAL15000 ms轮询间隔上限MAX_WAIT_TIME600000 ms默认总等待时长可被pollTimeout覆盖状态机语义normalizeStatusL112-L126state只接受pending | running | done | failed四种值否则抛ResponseFormatError任务done时从resultUrl.jsonUrl下载 JSONL 结果并逐行解析failed时抛JobFailedError携带jobId与errorMsg总时长耗尽则抛PollTimeoutError。此外getStatus(jobId)与getBatchStatus(batchId)提供了不阻塞的进度查询JobStatus内含progresstotalPages/extractedPages/startTime/endTimesrc/results.ts适合在长任务中渲染进度条或做批次巡检。7.2 取消机制所有网络方法与轮询都接受{ signal?: AbortSignal }底层通过两个AbortController联动用户信号 超时定时器见 src/internal/http.ts因此可以用AbortController实现请求级或任务级的统一取消。八、结果结构与资源落盘8.1 OCRResult 与 DocParsingResult结果类型定义在 src/results.tsOCRResult { jobId, pages: OCRPage[], dataInfo? }每个OCRPage含prunedResult裁剪后的结构化识别结果、ocrImageUrl可视化图片、docPreprocessingImageUrl、inputImageUrl与原始rawDocParsingResult { jobId, pages: DocParsingPage[], dataInfo? }每个DocParsingPage含markdownText、markdownImages文件名到 URL 的映射、outputImages、exports与raw。SDK 在parseOCRResult/parseDocParsingResultsrc/client.ts中对 JSONL 做了严格结构校验缺少result.ocrResults、缺少prunedResult、缺少markdown.text等都会抛出ResultParseError避免把半结构化数据静默透传给下游。8.2 保存远端资源到本地可视化图片与解析产物都是远端 URL。SDK 提供三个落盘方法src/client.ts// 单个资源 URL 保存到目标路径/目录 await client.saveResource(resourceUrl, ./out); // OCR 结果保存每页的 ocrImageUrl文件名为 ocr-page-1、ocr-page-2... await client.saveOcrResultResources(result, ./out); // 文档解析结果按 markdownImages / outputImages 的 key 保存 await client.saveDocumentParsingResultResources(doc, ./out);落盘安全细节值得了解目标目录必须已存在否则FileNotFoundError未设置overwrite: true时写入使用排他标志wx同名文件、路径冲突..、含/的 key都会被InvalidRequestError/FileNotFoundError拦截src/client.ts、L372-L385。九、错误处理速查完整错误类层次定义于 src/errors.ts全部继承自PaddleOCRAPIError其本身继承Error并保留cause。在业务代码中推荐用instanceof做分类处理异常触发场景可携带字段AuthError未配置 token、401/403—InvalidRequestError参数互斥/缺失、模型与任务不匹配、400—APIError服务端业务code非 0 或其他非 2xxstatusCodeRateLimitError429 限流statusCode 429ServiceUnavailableError503/504statusCodeJobFailedError任务执行失败jobId、errorMsgRequestTimeoutError单次请求超时timeoutMsPollTimeoutError轮询总时长耗尽jobId、timeoutMsNetworkError连接失败—FileNotFoundError本地文件/目标目录不存在pathResponseFormatError/ResultParseError响应结构或 JSONL 解析异常—十、构建、测试与发布校验README 给出的四项质量命令在 api_sdk/typescript 目录下执行npm run lint npm run build npm test npm audit --audit-levelmoderatelint即tsc --noEmit类型检查test使用 vitesttests/client.test.tsbuild由 tsup 产出 ESM CJS 双格式package.json 中定义了prepublishOnly钩子npm run lint npm run build npm test即发布前强制通过类型检查与单测保证paddleocr/api-sdk的0.x版本在语义化版本承诺下不被带病发布。更宏观的三语言 SDK 验证入口Python/TypeScript/Go见 api_sdk/README_cn.md。十一、仓库参考索引内容路径SDK 包级文档本文主体api_sdk/typescript/README_cn.md包元信息与脚本api_sdk/typescript/package.json客户端主类与默认模型逻辑api_sdk/typescript/src/client.ts模型枚举与请求/选项类型api_sdk/typescript/src/models.tsHTTP 层端点、鉴权、错误映射api_sdk/typescript/src/internal/http.ts轮询器退避、状态机api_sdk/typescript/src/internal/poller.ts结果/任务状态类型api_sdk/typescript/src/results.ts错误类层次api_sdk/typescript/src/errors.ts运行示例examples/ocr-url.ts、examples/doc-parsing-file.ts单元测试api_sdk/typescript/tests/client.test.ts官方 API TypeScript 用户文档docs/version3.x/inference_deployment/serving/paddleocr_official_api/typescript.md适用前提小结本 SDK 仅覆盖调用官方托管服务这一部署形态Node.js ≥ 18所有算法能力模型版本、可选参数、配额以 PaddleOCR 官方 API 服务端实际支持为准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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考