PaddleOCR 官方 API 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导读本文面向需要在 Node.js 服务端程序中接入 OCR 与文档解析能力的开发者系统讲解 PaddleOCR 官方 API 的 TypeScript SDKnpm 包paddleocr/api-sdk的安装、认证、任务提交、结果等待、资源保存与错误处理。PaddleOCR 官方 API 走官方托管服务本机不运行 PaddleOCR 推理、不加载本地模型因此适合将 PDF/图片转结构化数据的能力以极低成本嵌入到 AI 应用、RAG 管道或微服务中。读完本文你将掌握完整的 TypeScript 集成方案包括同步等待与手动控制两种任务模式、模型选择、参数调优以及健壮的异常处理。关联文档docs/version3.x/inference_deployment/serving/paddleocr_official_api/typescript.mdSDK 源码位于 api_sdk/typescript。一、SDK 概览与定位TypeScript SDK 是 PaddleOCR 官方 API 的客户端封装面向Node.js 18 及以上环境。它与仓库中其他官方 API SDKPython SDK、Go SDK以及集成在 CLI 中的paddleocr api命令见 CLI 文档并列共同构成 PaddleOCR 官方 API 的接入矩阵总览见 overview.md。其核心工作方式是把本地文件filePath或文件 URLfileUrl提交到官方托管服务轮询异步任务最后拉取并解析 JSONL 结果。整个过程不会在本地执行推理SDK 扮演的只是提交—轮询—解析—保存资源的客户端角色。从源码结构看api_sdk/typescript/srcSDK 内部由三层协作完成上述流程client.tsPaddleOCRClient公开 API面向业务调用internal/http.tsHttpClient负责 HTTP 提交、状态查询与资源下载默认服务地址为https://paddleocr.aistudio-app.com任务接口路径为/api/v2/ocr/jobsinternal/poller.tsPoller实现带指数退避的轮询初始间隔 3 秒、倍率 1.5、最大间隔 15 秒默认最长等待 600 秒。包本身以 ESM/CJS 双格式发布见 package.json 的exports字段并声明engines.node 18。二、安装与认证1. 获取访问令牌首先在 AI Studio Access Token 页面获取访问令牌access token。该令牌用于在每次请求时以Authorization: Bearer token头进行认证见 internal/http.ts。2. 安装 npm 包npm install paddleocr/api-sdk export PADDLEOCR_ACCESS_TOKENyour-access-token包按语义化版本发布为公开 scoped npm 包paddleocr/api-sdk当前仓库中版本为 0.2.3。若需本地开发构建可执行npm install与npm run build。3. 客户端初始化与令牌注入优先级客户端默认从环境变量PADDLEOCR_ACCESS_TOKEN读取令牌也可以显式传入tokenimport { PaddleOCRClient } from paddleocr/api-sdk; const client new PaddleOCRClient({ token: process.env.PADDLEOCR_ACCESS_TOKEN, });从 client.ts 的构造函数可以看到令牌解析顺序为options.token优先其次process.env.PADDLEOCR_ACCESS_TOKEN。若两者都为空构造函数会直接抛出AuthErrorToken is required...。这一行为在 tests/client.test.ts 中有对应测试删除环境变量后new PaddleOCRClient()抛AuthError设置环境变量后构造成功。三、快速开始两种任务类型1. OCR 任务远程 URLimport { Model, PaddleOCRClient } from paddleocr/api-sdk; const client new PaddleOCRClient(); const result await client.ocr({ fileUrl: https://example.com/invoice.pdf, model: Model.PPOCRv5, }); console.log(result.jobId, result.pages.length);2. 本地文件与二选一约束本地文件使用filePath。fileUrl与filePath必须二选一——同时缺失会抛InvalidRequestErrorEither fileUrl or filePath is required.同时提供也会抛错fileUrl and filePath are mutually exclusive.校验逻辑见 client.ts。底层实现中filePath会走 multipart/form-data 上传FormData携带model、optionalPayload、file等字段fileUrl则走 JSON POST两者都会先检查本地文件是否存在不存在抛FileNotFoundError见 internal/http.ts。3. 文档解析任务本地 PDF 示例仓库示例 examples/doc-parsing-file.ts 展示了文档解析的标准用法import { PaddleOCRClient, Model } from paddleocr/api-sdk; const client new PaddleOCRClient(); // 文档解析本地文件 图表识别 const result await client.parseDocument({ model: Model.PPStructureV3, filePath: ./sample.pdf, options: { useChartRecognition: true }, }); for (const page of result.pages) { console.log(page.markdownText); }每个page.markdownText即该页解析出的 Markdown 结构化文本可直接喂给 LLM 或入库。四、公共 API同步等待与手动控制两套模式TypeScript SDK 的常用公共方法分为两组client.ts同步等待Convenience模式一步提交并等待完成。ocr(...)提交 OCR 任务等待完成并返回 OCR 结果parseDocument(...)提交文档解析任务等待完成并返回文档解析结果。手动控制Manual模式先提交拿到Job自行决定何时等待便于并发提交多个任务后统一收尾。submitOcr(...)只提交 OCR 任务返回任务对象submitDocumentParsing(...)只提交文档解析任务返回任务对象getStatus(jobId)执行一次非阻塞状态查询waitOcrResult(job)等待 OCR 任务完成并解析结果waitDocumentParsingResult(job)等待文档解析任务完成并解析结果saveResource(resourceUrl, destination, options)保存单个资源 URLsaveOcrResultResources(result, destination, options)保存 OCR 结果对象引用的资源saveDocumentParsingResultResources(result, destination, options)保存文档解析结果对象引用的资源。ocr与parseDocument在实现上就是submitwait的组合见 client.ts。waitOcrResult/waitDocumentParsingResult接受Job对象或裸的jobId字符串传入字符串时会按任务类型推断默认模型。并发提交的经典写法同样来自 examples/doc-parsing-file.tsconst 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与batchId类型定义见 results.ts。任务状态机为pending → running → done | failedgetStatus返回的状态中还可能携带progresstotalPages/extractedPages/起止时间与resultUrl。五、模型选择Model枚举是官方 API 模型名字符串的类型安全写法定义见 models.ts提交请求时转换为对应的实际模型名也可以直接传入字符串例如model: PaddleOCR-VL-1.6。任务适用接口默认模型可选模型参数类型OCRocr、submitOcr、waitOcrResultModel.PPOCRv6Model.PPOCRv5、Model.PPOCRv6OCROptions文档解析parseDocument、submitDocumentParsing、waitDocumentParsingResultModel.PaddleOCRVL16Model.PPStructureV3、Model.PaddleOCRVL、Model.PaddleOCRVL15、Model.PaddleOCRVL16选择PPStructureV3时传入PPStructureV3Options选择 PaddleOCR-VL 系列模型时传入PaddleOCRVLOptions。补充两点源码层面的细节OCR 模型集合除 PP-OCRv5/PP-OCRv6 外还包括Model.PPOCRv5LatinPP-OCRv5-latin用于拉丁语系场景模型与任务强绑定校验submitOcr若未指定模型默认PPOCRv6submitDocumentParsing默认PaddleOCRVL16且 SDK 内部通过isOCRModel/isDocumentParsingModel校验模型是否属于对应任务集合传错会抛InvalidRequestError见 models.ts 与 client.ts。六、配置与参数1. 客户端配置超时、服务地址与自定义 fetchconst client new PaddleOCRClient({ requestTimeout: 300_000, pollTimeout: 600_000, });requestTimeout限制一次 HTTP 请求提交、查询状态、下载资源默认 300000mspollTimeout限制ocr、parseDocument、waitOcrResult与waitDocumentParsingResult的总等待时间默认 600000ms两者也可通过timeout统一设置公共方法还可接收AbortSignal以便上层主动取消见 client.ts。指定自定义服务地址如自建代理环境变量PADDLEOCR_BASE_URL与baseUrl参数均可const client new PaddleOCRClient({ baseUrl: https://my-proxy.com/paddle, });通过fetch选项注入自定义 fetch 实现适用于需要代理或自定义网络层的场景const client new PaddleOCRClient({ fetch: myCustomFetch, });注意 SDK 默认服务地址为https://paddleocr.aistudio-app.com构造时会自动去除baseUrl尾部多余的斜杠见 internal/http.ts。此外clientPlatform选项会以Client-Platform请求头随请求发送。2. 请求参数camelCase 命名与未设置即用服务端默认TypeScript SDK 的参数名使用 camelCase与官方 API 字段名一致。未设置的字段不会发送服务端将使用其默认值。完整字段定义见 models.ts 中对应的*Options接口以下为常用字段。OCROptions常用字段字段类型说明useDocOrientationClassifyboolean文档方向分类useDocUnwarpingboolean文档扭曲矫正visualizeboolean是否返回可视化结果图此外接口还定义了useTextlineOrientation文本行方向、textDetLimitSideLen、textDetLimitType、textDetThresh、textDetBoxThresh、textDetUnclipRatio、textRecScoreThresh等检测/识别阈值类参数并有[key: string]: unknown兜底以便透传官方 API 新增字段。PPStructureV3Options常用字段字段类型说明useTableRecognitionboolean表格识别useFormulaRecognitionboolean公式识别useChartRecognitionboolean图表识别prettifyMarkdownbooleanMarkdown 美化该选项集还包含版面与文本处理类参数useDocOrientationClassify、useDocUnwarping、useTextlineOrientation、useSealRecognition、useRegionDetection、layoutThreshold、layoutNms、layoutUnclipRatio、layoutMergeBboxesMode、formatBlockContent、表格 HTML 转换useWiredTableCellsTransToHtml/useWirelessTableCellsTransToHtml、useTableOrientationClassify、useOcrResultsWithTableCells、端到端表格模型开关useE2eWiredTableRecModel/useE2eWirelessTableRecModel、markdownIgnoreLabels、showFormulaNumber、returnMarkdownImages、outputFormats、visualize等。PaddleOCRVLOptions常用字段字段类型说明useLayoutDetectionboolean版面检测useChartRecognitionboolean图表识别temperaturenumber采样温度prettifyMarkdownbooleanMarkdown 美化VLM 系列还提供生成侧控制参数promptLabelocr | formula | table | chart | seal | spotting、layoutShapeModerect | quad | poly | auto、repetitionPenalty、topP、minPixels、maxPixels、maxNewTokens、vlmExtraArgs、useOcrForImageBlock、mergeLayoutBlocks、restructurePages、mergeTables、relevelTitles等。3. 分页与批量OCRRequest/DocParsingRequest均支持可选的pageRanges如1-2与batchId会在提交时随请求发送见 client.ts。使用相同batchId的任务可通过getBatchStatus(batchId)一次性查询批量状态results.ts 中BatchStatus由jobs: JobStatus[]构成。七、结果对象与资源保存1. OCR 结果OCRResultresults.ts包含jobId、pages与dataInfo。每个OCRPage提供prunedResult核心识别结果含文本、置信度、坐标等、ocrImageUrl可视化图、docPreprocessingImageUrl预处理图、inputImageUrl输入图与原始数据raw。解析逻辑见 client.ts。2. 文档解析结果DocParsingResult的每个DocParsingPageresults.ts包含markdownText该页 Markdown 文本、markdownImages与outputImages资源 URL 映射、prunedResult、inputImageUrl、exports与原始markdown对象。3. 资源落盘三个保存方法将结果引用的远程资源下载到本地saveResource(resourceUrl, destination, options)保存单个资源 URL若destination是已存在目录则自动以 URL 文件名命名否则视为完整目标文件路径saveOcrResultResources(result, destination, options)将 OCR 结果中每页的ocrImageUrl保存为ocr-page-N.extsaveDocumentParsingResultResources(result, destination, options)将文档解析结果每页的markdownImages与outputImages映射全部保存文件名取自映射 key并经过安全校验拒绝..、含路径分隔符或以.开头的 key。SaveResourceOptions支持overwrite默认 false目标已存在时抛InvalidRequestError与filename。目标目录不存在时抛FileNotFoundError。实现细节见 client.ts。八、错误处理所有 SDK 错误都继承自PaddleOCRAPIError定义见 errors.ts因此可用一个catch统一捕获。常见类型错误类型触发场景AuthError未提供令牌构造时抛出或服务端返回 401/403InvalidRequestError参数不合法fileUrl/filePath二选一被违反、模型与任务不匹配、目标文件已存在等RateLimitError服务端返回 429限流statusCode固定为 429ServiceUnavailableError服务端返回 503/504APIError通用 API 错误携带statusCodeNetworkError网络连接失败JobFailedError任务进入failed状态携带jobId与errorMsgRequestTimeoutError单次 HTTP 请求超时PollTimeoutError轮询总等待超时携带jobId与timeoutMsResponseFormatError响应结构不符合预期如缺少jobId、状态缺失或状态未知ResultParseErrorJSONL 结果解析失败、页面缺少prunedResult/markdown.text等关键字段典型处理示例import { AuthError, JobFailedError, PaddleOCRAPIError, PollTimeoutError, RateLimitError, } from paddleocr/api-sdk; try { const result await client.parseDocument({ filePath: ./sample.pdf, }); console.log(result.pages[0].markdownText); } catch (err) { if (err instanceof AuthError) { console.error(认证失败请检查访问令牌); } else if (err instanceof RateLimitError) { console.error(触发限流请稍后重试); } else if (err instanceof JobFailedError) { console.error(任务失败${err.jobId} - ${err.errorMsg}); } else if (err instanceof PollTimeoutError) { console.error(等待超时${err.jobId}); } else if (err instanceof PaddleOCRAPIError) { console.error(SDK 错误${err.message}); } }从实现看HTTP 层会先尝试解析响应体中的msg/message/errorMsg作为错误信息再按状态码映射到具体异常类型internal/http.ts业务层code ! 0时也会抛APIErrorinternal/http.ts。请求被上层AbortSignal主动取消时抛出的原因会被透传为用户取消userAbortReason。九、官方 API 参考与配额PP-OCRv5 APIPP-StructureV3 APIPaddleOCR-VL APIPaddleOCR-VL-1.5 APIAPI 配额规则和错误码说明配额规则与错误码以上述官方页面为准。若部署在受网络限制的环境中可通过baseUrl指向代理网关如需与仓库内其他语言方案对比选型可参考 Python SDK 与 Go SDK 文档。十、进一步阅读SDK 中文 READMEapi_sdk/typescript/README_cn.md含最小示例与本地构建方式可运行示例examples/ocr-url.ts、examples/doc-parsing-file.ts类型与接口定义src/models.ts、src/results.ts客户端实现与内部机制src/client.ts、src/internal/http.ts、src/internal/poller.ts单元测试覆盖认证、契约方法、提交报文、超时与错误映射tests/client.test.ts官方 API 总览含各语言 SDK 定位对比docs/version3.x/inference_deployment/serving/paddleocr_official_api/overview.md【免费下载链接】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），仅供参考