企业官网建设流程全解析

PaddleOCR 官方 API TypeScript SDK 集成指南：Node.js 云端 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 官方 API TypeScript SDK（@paddleocr/api-sdk）面向 Node.js 18+ 环境，通过调用 PaddleOCR 官方云端服务完成 OCR 识别与文档解析，无需在本地安装飞桨推理环境。本文基于该 SDK 的官方文档与仓库源码（api_sdk/typescript），系统讲解安装认证、异步任务提交/轮询模型、模型选择、客户端与请求级配置、结果结构与资源下载、错误处理等完整链路，帮助你直接用 TypeScript/JavaScript 接入 PP-OCRv5、PP-OCRv6 识别与 PP-StructureV3、PaddleOCR-VL 系列文档解析能力。

SDK 定位与适用场景

官方 API TypeScript SDK 是一个云端服务客户端，而非本地推理框架：它调用托管在 AI Studio 上的 PaddleOCR 官方 API，由服务端负责模型加载与计算，客户端只负责提交任务、轮询状态、拉取结果与下载资源。因此：

• 不需要本地安装 PaddlePaddle、PaddleOCR 推理依赖或下载模型权重；
• 适合在 Node.js 服务端、无头脚本、CI 流水线等场景中集成 OCR 与文档解析能力；
• 网络层基于标准fetch，天然可运行在支持 Node.js 18+ 的各类运行环境。

从仓库源码看，SDK 的默认服务地址为https://paddleocr.aistudio-app.com（见 client.ts 与 internal/http.ts），请求路径为/api/v2/ocr/jobs，因此所有调用都需要有效的云端访问令牌。

安装与认证

安装 SDK

npm install @paddleocr/api-sdk

SDK 打包入口见 src/index.ts，统一导出PaddleOCRClient、Model枚举、全部请求/结果类型以及各类错误类。

获取与配置 Access Token

使用前需要先从 AI Studio 官网的账号设置中获取 Access Token（官方文档称为 AI Studio Access Token 页面）。SDK 默认从环境变量PADDLEOCR_ACCESS_TOKEN读取令牌：

export PADDLEOCR_ACCESS_TOKEN="your-access-token"

也可以在构造客户端时显式传入token：

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

从源码看，构造时令牌解析顺序为options.token优先、其次是process.env.PADDLEOCR_ACCESS_TOKEN；两者都缺失时会直接抛出AuthError（见 client.ts）。仓库测试 tests/client.test.ts 也明确覆盖了这一行为：无令牌构造必抛AuthError，设置环境变量后即可正常构造。

实际请求时令牌会以Authorization: Bearer <token>请求头携带（见 internal/http.ts），因此请务必通过安全方式（环境变量、密钥管理服务）保存令牌，不要硬编码进代码或提交到仓库。

快速开始

通过文件 URL 提交 OCR

import { 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);

通过本地文件路径提交

将fileUrl换成filePath即可上传本地文件：

const result = await client.ocr({ filePath: "./invoice.pdf", model: Model.PPOCRv6, });

源码明确规定：fileUrl与filePath必须恰好二选一——两者都缺失会抛出InvalidRequestError("Either fileUrl or filePath is required.")，同时传入则会抛出“互斥”错误（见 client.ts）。使用filePath时，SDK 通过FormData以 multipart 方式上传文件（见 internal/http.ts），文件不存在会抛出FileNotFoundError。

完整的可运行示例见仓库 examples/ocr-url.ts 与 examples/doc-parsing-file.ts。

公共 API 总览

SDK 提供的公共方法分为“一站式便捷方法”“手动控制方法”“状态查询”“资源保存”四类：

提交 + 轮询的两阶段模型

理解 SDK 的调用模型是正确使用它的关键。从源码看，ocr与parseDocument都是“提交 + 等待”的语法糖（见 client.ts）：

async ocr(req: OCRRequest, options?: { signal?: AbortSignal }): Promise<OCRResult> { const job = await this.submitOcr(req, options); return this.waitOcrResult(job, options); }

waitOcrResult/waitDocumentParsingResult内部由轮询器（internal/poller.ts）驱动：以3 秒为初始间隔、按1.5 倍指数退避、最长15 秒间隔轮询任务状态，直到状态变为done（拉取 JSONL 结果）或failed（抛JobFailedError），超过总等待时间则抛PollTimeoutError。轮询器的默认最大等待时间为600000ms（10 分钟）。

因此，当你有多个文件需要处理时，推荐先用submitOcr/submitDocumentParsing批量提交拿到全部jobId，再并发等待结果，充分利用云端异步处理能力——examples/doc-parsing-file.ts 就展示了这种“提交后Promise.all并发等待”的写法。

选择模型

Model 枚举

Model枚举值是官方 API 模型名字符串的类型安全别名（定义见 models.ts），提交请求时会序列化为对应的模型名。你也可以直接传官方 API 模型名字符串，例如model: "PaddleOCR-VL-1.6"。

export enum Model { 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", }

任务与模型的对应关系

注意两点实现细节：

1. 默认模型在提交时按任务自动填充：OCR 任务默认Model.PPOCRv6，文档解析任务默认Model.PaddleOCRVL16（见 client.ts）；
2. 模型与任务强校验：SDK 内置了isOCRModel/isDocumentParsingModel判定集合（见 models.ts），提交前会校验模型是否属于对应任务，不匹配即抛InvalidRequestError，例如对文档解析任务传入 OCR 模型会直接报错（见 client.ts）。

配置详解

客户端配置

const client = new PaddleOCRClient({ requestTimeout: 300_000, pollTimeout: 600_000, });

• requestTimeout：单次 HTTP 请求的超时上限，覆盖提交、状态查询、资源下载等所有请求，默认300000ms（5 分钟）；
• pollTimeout：ocr、parseDocument、waitOcrResult、waitDocumentParsingResult的总等待时间上限，默认600000ms（10 分钟）；
• 二者同时传入时也兼容旧字段timeout（见 client.ts）。

公共方法还支持传入AbortSignal实现调用方主动取消，例如配合AbortController在用户取消操作或请求超时场景下中断等待。

覆盖服务地址：通过环境变量PADDLEOCR_BASE_URL或baseUrl选项覆盖默认服务地址，适合自建代理或私有化网关场景：

const client = new PaddleOCRClient({ baseUrl: "https://my-proxy.com/paddle", });

从源码看，baseUrl优先级高于PADDLEOCR_BASE_URL，且会去掉末尾斜杠后再拼接/api/v2/ocr/jobs（见 internal/http.ts）。

注入自定义 fetch：对于代理、自定义网络层、测试打桩等需求，可以注入自己的fetch实现：

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

仓库单元测试正是通过注入 mockfetch来模拟各类响应与错误场景（见 tests/client.test.ts）。

请求选项

TS SDK 的字段命名采用camelCase，与官方 API 直接对应；未显式设置的字段不会随请求发送。所有选项对象都带有索引签名（[key: string]: unknown），即官方 API 新增字段但 SDK 尚未显式声明时，也可以直接透传。完整字段定义可查看 models.ts。

OCROptions 公共字段

PPStructureV3Options 公共字段

PaddleOCRVLOptions 公共字段

结果结构解析

SDK 把原始 JSONL 响应解析为类型化结果（类型定义见 results.ts），核心结构如下：

• OCRResult：{ jobId, pages: OCRPage[], dataInfo? }，其中每个OCRPage包含prunedResult（精简识别结果）、ocrImageUrl（可视化图 URL）、docPreprocessingImageUrl（预处理图 URL）、inputImageUrl（输入图 URL）与raw（原始响应）；
• DocParsingResult：{ jobId, pages: DocParsingPage[], dataInfo? }，每个DocParsingPage包含markdownText（Markdown 正文）、markdownImages（Markdown 引用图片 URL 映射）、outputImages（输出图片映射）、prunedResult、exports与raw；
• Job：{ jobId, model, task: "ocr" | "document_parsing", pageRanges?, batchId? }，由submit*系列方法返回；
• JobStatus：{ jobId, state: "pending" | "running" | "done" | "failed", progress?, resultUrl?, errorMsg? }；
• Progress：{ totalPages, extractedPages, startTime?, endTime? }，用于展示多页任务的进度。

资源保存：把云端结果落到本地

saveResource系列方法用于把结果引用的图片等资源下载到本地磁盘：

// 保存单个资源到指定路径（destination 为文件路径时直接写入该文件） await client.saveResource(result.pages[0].ocrImageUrl, "./output/"); // 保存 OCR 结果引用的全部资源 await client.saveOcrResultResources(result, "./output/"); // 保存文档解析结果引用的全部资源（markdownImages + outputImages） await client.saveDocumentParsingResultResources(result, "./output/");

从源码看（client.ts）有以下行为值得注意：

• 当destination是已存在目录时，文件名取自资源 URL 的 basename；OCR 结果资源会命名为ocr-page-<页码><扩展名>；
• SaveResourceOptions.overwrite控制是否覆盖已存在的目标文件，默认不覆盖，目标已存在会抛InvalidRequestError；
• 目标目录不存在会抛FileNotFoundError；结果资源文件名会做安全校验（拒绝.、..、含路径分隔符或以点开头的文件名），防止路径穿越。

错误处理

SDK 的所有错误都继承自PaddleOCRAPIError（错误类定义见 errors.ts），因此可以统一捕获：

try { const result = await client.ocr({ fileUrl }); } catch (e) { if (e instanceof RateLimitError) { // 触发限流，建议退避重试 } else if (e instanceof JobFailedError) { console.error(`任务 ${e.jobId} 失败: ${e.errorMsg}`); } else if (e instanceof PaddleOCRAPIError) { // 其他 SDK 错误 } }

常用错误类型及其含义：

HTTP 状态码到错误类型的映射实现在 internal/http.ts：401/403 →AuthError，400 →InvalidRequestError，429 →RateLimitError，503/504 →ServiceUnavailableError，其余 →APIError。

官方 API 参考与配额

• 官方 API 文档：PP-OCRv5 API、PP-StructureV3 API、PaddleOCR-VL API、PaddleOCR-VL-1.5 API 的完整字段定义与请求/响应格式，可在 AI Studio 官方文档站对应页面查阅；SDK 字段与官方 API 一一对应（camelCase），需要查看完整字段列表时可对照官方 API Reference 或直接阅读 models.ts 中的接口定义；
• 配额与错误码：API 配额规则与错误码说明同样收录在 AI Studio 官方文档中，接入前建议先阅读，了解免费/付费额度、并发限制及 429 限流语义，以便正确设计重试与降级策略。

小结与实战建议

从“两阶段异步模型”到“类型安全的结果解析”，PaddleOCR 官方 API TypeScript SDK 为 Node.js 开发者提供了一条零本地依赖的 OCR/文档解析接入路径。实战中的几个关键建议：

1. 先提交后等待：批量处理多个文件时，先用submitOcr/submitDocumentParsing一次性提交全部任务，再并发wait*等待，吞吐更高；
2. 显式设置超时：根据业务对耗时与稳定性的要求调整requestTimeout与pollTimeout，并配合AbortSignal支持用户侧取消；
3. 统一错误处理：用PaddleOCRAPIError兜底捕获，对RateLimitError、ServiceUnavailableError做指数退避重试，对PollTimeoutError保留jobId以便稍后恢复查询；
4. 善用资源保存：saveOcrResultResources与saveDocumentParsingResultResources可一键把可视化图、Markdown 图片等云端资源落盘，注意overwrite语义与目录存在性检查；
5. 类型安全：优先使用Model枚举与OCROptions/PPStructureV3Options/PaddleOCRVLOptions类型，借助编译期检查避免模型名拼写错误与字段名不一致问题。

更完整的可运行示例与接口文档可继续阅读仓库中的 api_sdk/typescript/README.md、examples/ocr-url.ts、examples/doc-parsing-file.ts，以及同名中文文档 docs/version3.x/inference_deployment/serving/paddleocr_official_api/typescript.md。

【免费下载链接】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