PaddleOCR TypeScript SDK 实战指南基于官方托管 API 的 OCR 与文档解析客户端【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR导读本文围绕 PaddleOCR 仓库中 TypeScript SDK 展开系统讲解如何用paddleocr/api-sdk在 Node.js 环境中调用 PaddleOCR 官方托管 API完成云端 OCR 识别与文档解析版面解析、表格/公式/图表识别、Markdown 输出等。读完本文你将掌握 SDK 的安装认证、模型选择、参数配置、异步任务轮询、结果资源保存与错误处理的全套实战方法并能在自己的 TypeScript 项目中直接落地使用。需要说明的是该 SDK 是面向官方 API 的客户端只会把任务提交到 PaddleOCR 官方托管服务执行不会在本地运行 PaddleOCR 推理因此适用于无需自建推理服务的快速集成场景。SDK 官方用户文档见 TypeScript SDK 文档 与 英文版。一、SDK 定位与运行环境paddleocr/api-sdk是一个公开发布的 scoped npm 包遵循语义化版本SemVer面向Node.js 18 及以上环境见 package.json 中engines: { node: 18 }。它作为 PaddleOCR 官方 API 的 TypeScript 客户端承担两类任务OCR 识别将图片或 PDF 提交给云端 PP-OCR 系列模型返回逐页的文字识别结果文档解析将文档提交给 PP-StructureV3 / PaddleOCR-VL 系列模型返回版面、表格、公式、图表解析结果与 Markdown 输出。SDK 的源码位于仓库 api_sdk/typescript 目录核心实现分为四部分文件职责src/client.tsPaddleOCRClient客户端主类封装全部公共方法src/models.tsModel枚举、请求与选项的 TypeScript 类型定义src/results.ts结果对象OCRResult、DocParsingResult、Job、JobStatus等类型定义src/errors.ts完整的错误类型体系二、安装与本地开发2.1 安装 npm 包在你的项目中直接安装即可npm install paddleocr/api-sdk该包支持 ESM 与 CommonJS 双模块格式exports中分别指向dist/index.js与dist/index.cjs并提供完整的.d.ts类型声明TypeScript 项目可获得开箱即用的类型提示。2.2 本地开发构建如需基于仓库源码二次开发或调试可进入 api_sdk/typescript 目录执行npm install npm run build构建由tsup完成见 package.json 的build: tsup产物输出到dist/。发布前会依次执行lint、build、test作为质量门禁prepublishOnly钩子。三、认证与客户端初始化调用官方 API 前需要先在 AI Studio 的 Access Token 页面获取访问令牌。SDK 提供两种令牌传入方式二者必须至少提供其一否则构造客户端时会直接抛出AuthError源码见 client.ts方式一环境变量推荐export PADDLEOCR_ACCESS_TOKENyour-access-token方式二构造参数import { PaddleOCRClient } from paddleocr/api-sdk; const client new PaddleOCRClient({ token: process.env.PADDLEOCR_ACCESS_TOKEN, });3.1 客户端配置项ClientOptions定义见 models.ts支持的完整配置项如下配置项默认值说明token环境变量PADDLEOCR_ACCESS_TOKEN访问令牌baseUrl环境变量PADDLEOCR_BASE_URL或官方默认地址自定义服务地址用于代理转发场景timeout—同时作为requestTimeout与pollTimeout的兜底值requestTimeout300000300 秒单次 HTTP 请求提交任务、查询状态、下载资源的超时上限pollTimeout600000600 秒ocr、parseDocument、waitOcrResult、waitDocumentParsingResult的总等待时长clientPlatform—客户端平台标识透传给服务端fetch全局fetch注入自定义 fetch 实现用于代理或自定义网络层源码中默认服务地址为https://paddleocr.aistudio-app.com见 client.ts。当需要通过代理、内网网关或统一网关转发请求时可通过环境变量或参数覆盖// 方式一环境变量 // export PADDLEOCR_BASE_URLhttps://my-proxy.com/paddle // 方式二构造参数 const client new PaddleOCRClient({ baseUrl: https://my-proxy.com/paddle, requestTimeout: 300_000, pollTimeout: 600_000, });需要自定义网络层如加代理、统一打点、mock时可注入fetchconst client new PaddleOCRClient({ fetch: myCustomFetch, });四、快速开始云端 OCR4.1 最小示例URL 方式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);ocr()是最常用的便捷方法内部先调用submitOcr提交任务再调用waitOcrResult轮询直至完成并解析结果返回OCRResult对象调用链见 client.ts。4.2 本地文件方式SDK 支持直接上传本地文件使用filePath字段const result await client.ocr({ model: Model.PPOCRv6, filePath: ./invoice.pdf, });fileUrl与filePath必须二选一且互斥——都不传或同时传入都会抛出InvalidRequestError这一校验在 client.ts 的submit私有方法中完成。4.3 模型选择SDK 提供了Model枚举定义见 models.ts是官方 API 模型名字符串的类型安全写法提交时会转换为对应的实际模型名字符串也可以直接传入字符串例如model: PaddleOCR-VL-1.6。OCR 任务可用的模型枚举值实际模型名说明Model.PPOCRv5PP-OCRv5PP-OCRv5 云端 OCR 模型Model.PPOCRv5LatinPP-OCRv5-latinPP-OCRv5 拉丁语系云端 OCR 模型Model.PPOCRv6PP-OCRv6PP-OCRv6 云端 OCR 模型默认文档解析任务可用的模型枚举值实际模型名说明Model.PPStructureV3PP-StructureV3PP-StructureV3 文档解析模型Model.PaddleOCRVLPaddleOCR-VLPaddleOCR-VL 视觉语言模型Model.PaddleOCRVL15PaddleOCR-VL-1.5PaddleOCR-VL 1.5Model.PaddleOCRVL16PaddleOCR-VL-1.6PaddleOCR-VL 1.6默认SDK 在提交前会做模型与任务匹配校验submitOcr默认使用Model.PPOCRv6并校验模型必须是 OCR 模型submitDocumentParsing默认使用Model.PaddleOCRVL16并校验必须是文档解析模型否则抛出InvalidRequestError见 client.ts 与validateModelForTask方法。isOCRModel、isDocumentParsingModel、isVLModel三个类型守卫函数定义在 models.ts均可从包入口 src/index.ts 直接导入。五、快速开始文档解析文档解析默认使用 PaddleOCR-VL-1.6传入本地文件即可得到逐页 Markdownconst doc await client.parseDocument({ filePath: ./report.pdf, options: { useChartRecognition: true, }, }); console.log(doc.jobId, doc.pages.length);如需切换到 PP-StructureV3 模型传入对应枚举并选择该模型的选项类型const result await client.parseDocument({ model: Model.PPStructureV3, filePath: ./sample.pdf, options: { useChartRecognition: true }, }); for (const page of result.pages) { console.log(page.markdownText); }以上用法与 examples/doc-parsing-file.ts 中的示例一致。六、公共 API 全览SDK 除提供“提交并等待”的便捷方法外还暴露了细粒度的异步控制方法适合批量任务、进度展示、自定义并发等场景。全部公共方法如下对应实现见 client.ts方法作用是否阻塞等待ocr(req)提交 OCR 任务并等待完成返回OCRResult是parseDocument(req)提交文档解析任务并等待完成返回DocParsingResult是submitOcr(req)只提交 OCR 任务返回Job任务对象否submitDocumentParsing(req)只提交文档解析任务返回Job任务对象否getStatus(jobId)单次非阻塞状态查询返回JobStatus否getBatchStatus(batchId)批量任务状态查询返回BatchStatus否waitOcrResult(job)等待 OCR 任务完成并解析结果是waitDocumentParsingResult(job)等待文档解析任务完成并解析结果是saveResource(resourceUrl, destination, options)保存单个资源 URL 到本地否saveOcrResultResources(result, destination, options)保存 OCR 结果对象引用的所有资源否saveDocumentParsingResultResources(result, destination, options)保存文档解析结果对象引用的所有资源否6.1 提交与等待分离模式对于需要并发提交多个任务、统一等待的场景可先批量提交再并发等待// 先提交不等待 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), ]);waitOcrResult/waitDocumentParsingResult既接受Job对象也接受纯jobId字符串传入Job时还会校验任务类型与模型是否匹配见resolveJob方法client.ts。6.2 状态查询与任务对象Job对象包含jobId、model、taskocr或document_parsing、pageRanges、batchId字段见 results.ts。getStatus返回的JobStatus包含statepending|running|done|failedprogresstotalPages、extractedPages、startTime、endTime等进度信息resultUrl任务完成后的结果资源 URL 映射errorMsg失败时的错误信息。状态字段的解析与校验在 internal/poller.ts 的normalizeStatus函数中完成未知的 state 值会抛出ResponseFormatError。6.3 结果资源保存OCR 与文档解析结果中会引用若干远程资源如识别可视化图、预处理图、Markdown 内嵌图片等SDK 提供便捷的本地落盘方法// 保存文档解析结果引用的全部图片到指定目录 const saved await client.saveDocumentParsingResultResources( doc, ./output, { overwrite: true } ); console.log(saved); // 返回保存后的本地文件路径数组SaveResourceOptions支持overwrite是否覆盖已存在文件与filename自定义文件名。保存前 SDK 会做一系列安全检查目标必须是已存在的目录FileNotFoundError/InvalidRequestError、目标文件不存在或允许覆盖、文件名需避免路径穿越等不安全字符safeMapKeyFilename/safeUrlBasename函数见 client.ts。OCR 结果中每一页的可视化图会以ocr-page-{页码}{扩展名}命名保存。七、请求参数详解SDK 参数名使用 camelCase与官方 API 字段名保持一致未设置的字段不会随请求发送由服务端使用默认值。完整字段定义见 models.ts下文列出三类常用选项。7.1 OCROptionsOCR 任务除文档中列出的常用字段外SDK 还提供了文本检测/识别阈值等细粒度控制字段类型说明useDocOrientationClassifyboolean文档方向分类useDocUnwarpingboolean文档扭曲矫正useTextlineOrientationboolean文本行方向分类textDetLimitSideLennumber文本检测输入边长限制textDetLimitTypestring文本检测限制类型如按最长边/短边textDetThreshnumber文本检测二值化阈值textDetBoxThreshnumber文本检测框阈值textDetUnclipRationumber文本检测框扩边比例textRecScoreThreshnumber识别置信度过滤阈值visualizeboolean是否返回可视化结果图7.2 PPStructureV3OptionsPP-StructureV3 文档解析字段类型说明useDocOrientationClassify/useDocUnwarping/useTextlineOrientationboolean文档预处理开关方向分类、扭曲矫正、文本行方向useSealRecognitionboolean印章识别useTableRecognitionboolean表格识别useFormulaRecognitionboolean公式识别useChartRecognitionboolean图表识别useRegionDetectionboolean区域检测layoutThreshold/layoutNms/layoutUnclipRatio/layoutMergeBboxesModenumber/boolean/...版面检测后处理参数formatBlockContentboolean是否格式化版面块内容useWiredTableCellsTransToHtml/useWirelessTableCellsTransToHtmlboolean有线/无线表格转 HTMLuseTableOrientationClassifyboolean表格方向分类useOcrResultsWithTableCellsboolean结合单元格 OCR 结果useE2eWiredTableRecModel/useE2eWirelessTableRecModelboolean端到端有线/无线表格识别模型markdownIgnoreLabelsstring[]生成 Markdown 时忽略的版面标签prettifyMarkdownbooleanMarkdown 美化showFormulaNumberboolean是否显示公式编号returnMarkdownImagesboolean是否返回 Markdown 内嵌图片outputFormatsstring[]输出格式列表visualizeboolean是否返回可视化结果图7.3 PaddleOCRVLOptionsPaddleOCR-VL 系列字段类型说明useLayoutDetectionboolean版面检测useChartRecognitionboolean图表识别useSealRecognitionboolean印章识别useOcrForImageBlockboolean对图片块执行 OCRpromptLabelocr \| formula \| table \| chart \| seal \| spotting提示标签指导 VL 模型聚焦特定任务temperaturenumber采样温度topPnumber采样 top-prepetitionPenaltynumber重复惩罚系数minPixels/maxPixelsnumber图像缩放像素范围maxNewTokensnumber生成最大 token 数vlmExtraArgsRecordstring, unknown透传给 VL 模型的额外参数layoutShapeModerect \| quad \| poly \| auto版面框形状mergeLayoutBlocks/mergeTablesboolean版面块 / 表格合并relevelTitlesboolean标题层级重排restructurePagesboolean页面重排markdownIgnoreLabels/prettifyMarkdown/showFormulaNumber/returnMarkdownImages/outputFormats/visualize—同 PPStructureV3Options 对应字段八、结果对象结构8.1 OCR 结果OCRResult包含jobId、pages数组与dataInfo。每一页OCRPage见 results.ts包含prunedResult精简后的识别结果核心文字/框数据ocrImageUrl该页识别可视化图 URLdocPreprocessingImageUrl文档预处理图 URLinputImageUrl输入原图 URLraw该页的完整原始响应。解析逻辑见 client.tsSDK 会逐行解析服务端返回的 JSONL 数据缺少数关键字段如result.ocrResults、prunedResult时抛出ResultParseError。8.2 文档解析结果DocParsingResult的每一页DocParsingPage包含markdownText该页的 Markdown 文本markdownImagesMarkdown 内嵌图片的键值映射键为文件名值为资源 URLoutputImages输出图片映射prunedResult精简结果inputImageUrl输入原图 URLexports导出数据如表格结构化数据markdown/raw完整原始数据。九、异步轮询机制源码级原理SDK 内部通过 internal/poller.ts 的Poller类实现任务轮询采用指数退避策略const INITIAL_INTERVAL 3000; // 初始轮询间隔 3 秒 const MULTIPLIER 1.5; // 每次间隔乘以 1.5 const MAX_INTERVAL 15000; // 最大轮询间隔 15 秒 const MAX_WAIT_TIME 600000; // 总等待上限 10 分钟轮询流程pollUntilDone每次间隔查询任务状态任务done时从resultUrl.jsonUrl拉取 JSONL 结果任务failed时抛出JobFailedError携带服务端errorMsg等待期间支持AbortSignal主动取消超过pollTimeout仍未完成则抛出PollTimeoutError。所有等待类公共方法ocr、parseDocument、waitOcrResult、waitDocumentParsingResult都可传入{ signal: AbortSignal }以便上层主动取消。这一设计使得 SDK 既能“傻瓜式”一行等待结果也能完全掌控异步流程。十、错误处理体系SDK 的所有错误都继承自PaddleOCRAPIError见 errors.ts因此可以用一个 catch 覆盖全部 SDK 异常再按类型细分处理错误类型触发场景AuthError未提供 token 或认证失败InvalidRequestError请求参数非法如fileUrl/filePath互斥、模型与任务不匹配、目标路径非法APIError通用 HTTP 错误携带statusCodeRateLimitError触发限流HTTP 429ServiceUnavailableError服务不可用NetworkError网络层错误JobFailedError任务执行失败携带jobId与errorMsgRequestTimeoutError单次请求超时PollTimeoutError轮询总时长超限ResponseFormatError服务端响应结构不符合预期ResultParseError结果数据解析失败如缺少关键字段FileNotFoundError本地文件或目录不存在一个完整的健壮调用示例import { PaddleOCRClient, Model, PaddleOCRAPIError, RateLimitError } from paddleocr/api-sdk; const client new PaddleOCRClient(); try { const result await client.ocr({ model: Model.PPOCRv5, filePath: ./invoice.pdf, options: { visualize: true }, }); console.log(result.jobId, result.pages.length); } catch (error) { if (error instanceof RateLimitError) { // 触发限流退避后重试 console.error(Rate limited:, error.message); } else if (error instanceof PaddleOCRAPIError) { console.error(SDK error:, error.name, error.message); } else { console.error(Unexpected error:, error); } }十一、构建与测试SDK 自带完整的工程化脚本见 package.jsonnpm run lint # 类型检查tsc --noEmit npm run build # 使用 tsup 打包到 dist/ npm test # vitest 单元测试 npm audit --audit-levelmoderate # 依赖安全审计测试用例位于 tests/client.test.ts覆盖提交、轮询、结果解析、资源保存等关键路径可直接运行的参考示例见 examples/ocr-url.tsURL 方式 OCR与 examples/doc-parsing-file.ts本地文件文档解析 提交/等待分离模式。十二、适用场景与限制说明适合的场景希望快速接入 PaddleOCR 云端能力、避免自建 GPU 推理服务的 Web 服务、前端工程、脚本工具等需要类型安全、完善的异步控制与错误处理的项目。需要注意的限制SDK 不执行本地推理任务全部在官方托管服务上运行因此依赖网络与官方服务的配额具体配额规则与错误码以官方 API 文档为准单次请求与整体等待均有超时限制默认分别 300 秒 / 600 秒长文档大批量任务建议调整pollTimeout支持 Node.js 18 及以上版本浏览器环境需自行验证兼容性参数名与官方 API 字段保持一致未设置字段使用服务端默认值行为以服务端为准。结合本仓库的 TypeScript SDK 官方文档、英文文档 以及 SDK 源码即可开始用 TypeScript 快速构建云端 OCR 与文档解析应用。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考