企业官网建设流程全解析

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 目录，核心实现分为四部分：

二、安装与本地开发

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_TOKEN="your-access-token"

方式二：构造参数

import { PaddleOCRClient } from "@paddleocr/api-sdk"; const client = new PaddleOCRClient({ token: process.env.PADDLEOCR_ACCESS_TOKEN, });

3.1 客户端配置项

ClientOptions（定义见 models.ts）支持的完整配置项如下：

源码中默认服务地址为https://paddleocr.aistudio-app.com（见 client.ts）。当需要通过代理、内网网关或统一网关转发请求时，可通过环境变量或参数覆盖：

// 方式一：环境变量 // export PADDLEOCR_BASE_URL="https://my-proxy.com/paddle" // 方式二：构造参数 const client = new PaddleOCRClient({ baseUrl: "https://my-proxy.com/paddle", requestTimeout: 300_000, pollTimeout: 600_000, });

需要自定义网络层（如加代理、统一打点、mock）时，可注入fetch：

const client = new PaddleOCRClient({ fetch: myCustomFetch, });

四、快速开始：云端 OCR

4.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 任务可用的模型：

文档解析任务可用的模型：

SDK 在提交前会做模型与任务匹配校验：submitOcr默认使用Model.PPOCRv6，并校验模型必须是 OCR 模型；submitDocumentParsing默认使用Model.PaddleOCRVL16，并校验必须是文档解析模型，否则抛出InvalidRequestError（见 client.ts 与validateModelForTask方法）。isOCRModel、isDocumentParsingModel、isVLModel三个类型守卫函数定义在 models.ts，均可从包入口 src/index.ts 直接导入。

五、快速开始：文档解析

文档解析默认使用 PaddleOCR-VL-1.6，传入本地文件即可得到逐页 Markdown：

const 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）：

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、task（"ocr"或"document_parsing"）、pageRanges、batchId字段（见 results.ts）。getStatus返回的JobStatus包含：

• state："pending"|"running"|"done"|"failed"；
• progress：totalPages、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 OCROptions（OCR 任务）

除文档中列出的常用字段外，SDK 还提供了文本检测/识别阈值等细粒度控制：

7.2 PPStructureV3Options（PP-StructureV3 文档解析）

7.3 PaddleOCRVLOptions（PaddleOCR-VL 系列）

八、结果对象结构

8.1 OCR 结果

OCRResult包含jobId、pages数组与dataInfo。每一页OCRPage（见 results.ts）包含：

• prunedResult：精简后的识别结果（核心文字/框数据）；
• ocrImageUrl：该页识别可视化图 URL；
• docPreprocessingImageUrl：文档预处理图 URL；
• inputImageUrl：输入原图 URL；
• raw：该页的完整原始响应。

解析逻辑见 client.ts：SDK 会逐行解析服务端返回的 JSONL 数据，缺少数关键字段（如result.ocrResults、prunedResult）时抛出ResultParseError。

8.2 文档解析结果

DocParsingResult的每一页DocParsingPage包含：

• markdownText：该页的 Markdown 文本；
• markdownImages：Markdown 内嵌图片的键值映射（键为文件名，值为资源 URL）；
• outputImages：输出图片映射；
• prunedResult：精简结果；
• inputImageUrl：输入原图 URL；
• exports：导出数据（如表格结构化数据）；
• 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）：

1. 每次间隔查询任务状态；任务done时，从resultUrl.jsonUrl拉取 JSONL 结果；
2. 任务failed时抛出JobFailedError（携带服务端errorMsg）；
3. 等待期间支持AbortSignal主动取消；
4. 超过pollTimeout仍未完成则抛出PollTimeoutError。

所有等待类公共方法（ocr、parseDocument、waitOcrResult、waitDocumentParsingResult）都可传入{ signal: AbortSignal }以便上层主动取消。这一设计使得 SDK 既能“傻瓜式”一行等待结果，也能完全掌控异步流程。

十、错误处理体系

SDK 的所有错误都继承自PaddleOCRAPIError（见 errors.ts），因此可以用一个 catch 覆盖全部 SDK 异常，再按类型细分处理：

一个完整的健壮调用示例：

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.json）：

npm run lint # 类型检查（tsc --noEmit） npm run build # 使用 tsup 打包到 dist/ npm test # vitest 单元测试 npm audit --audit-level=moderate # 依赖安全审计

测试用例位于 tests/client.test.ts，覆盖提交、轮询、结果解析、资源保存等关键路径；可直接运行的参考示例见 examples/ocr-url.ts（URL 方式 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