PaddleOCR TypeScript SDK：基于官方托管 API 的 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）为 Node.js 18+ 环境提供了一组类型安全的客户端接口，通过调用 PaddleOCR 官方托管 API 完成 OCR 识别与版面解析，无需在本地运行任何 PaddleOCR 推理。本文将以 官方 TypeScript 文档 为骨架，结合 api_sdk/typescript 下的源码实现，系统讲解 SDK 的安装认证、快速上手、模型选择、客户端配置、请求参数、结果处理与错误处理，帮助你在十分钟内把图片/PDF 转成可供 AI 与 LLM 直接消费的结构化数据。
一、SDK 是什么：托管推理，零本地部署
TypeScript SDK 面向 Node.js 18+ 设计，核心定位是调用 PaddleOCR 官方 API完成 OCR 与文档解析。它依赖 PaddleOCR 托管的云端服务，不执行本地 PaddleOCR 推理——这意味着你不需要安装 PaddlePaddle、下载模型权重或配置 GPU，只要持有访问令牌（Access Token）即可发起任务。
从 源码结构 可以看到 SDK 的分层设计：
| 文件 | 职责 |
|---|---|
| client.ts | 对外主类PaddleOCRClient，封装全部公开方法 |
| models.ts | Model枚举、请求/客户端选项类型定义 |
| results.ts | 结果、任务（Job）、状态等返回类型 |
| errors.ts | 类型化错误体系，统一继承自PaddleOCRAPIError |
| internal/http.ts | HTTP 传输层：提交任务、查询状态、拉取结果 |
| internal/poller.ts | 轮询器：指数退避等待任务完成 |
| internal/abort.ts | AbortSignal取消支持 |
SDK 默认服务地址为https://paddleocr.aistudio-app.com，任务提交路径为/api/v2/ocr/jobs（见 http.ts）。
二、安装与认证
安装依赖与配置令牌只需两步：
npm install @paddleocr/api-sdk export PADDLEOCR_ACCESS_TOKEN="your-access-token"访问令牌需要先在 AI Studio 的 Access Token 页面申请获取。客户端默认从环境变量PADDLEOCR_ACCESS_TOKEN读取令牌，也可以显式传入token选项：
import { PaddleOCRClient } from "@paddleocr/api-sdk"; const client = new PaddleOCRClient({ token: process.env.PADDLEOCR_ACCESS_TOKEN, });从 client.ts 的实现看，令牌解析顺序为options.token→process.env.PADDLEOCR_ACCESS_TOKEN，两者都缺失时会直接抛出AuthError，提示 "Token is required."。这一行为也在 tests/client.test.ts 中有明确测试覆盖：未设置令牌构造客户端抛AuthError，仅设置环境变量则构造成功。
本地开发构建方式见 api_sdk/typescript/README.md：npm install后执行npm run build，之后可通过npm run lint、npm test、npm audit --audit-level=moderate完成质量检查。
三、快速开始：一行代码完成 OCR
3.1 识别远程文件（URL）
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);client.ocr(...)是一个便捷方法：内部先提交 OCR 任务，再自动轮询等待完成，最后解析返回OCRResult。result.pages按页存放识别结果，result.jobId为任务 ID。
3.2 识别本地文件（filePath）
const result = await client.ocr({ filePath: "./invoice.png", });fileUrl与filePath二选一、互斥。SDK 在 client.ts 中做了强制校验：两者都未提供或同时提供都会抛出InvalidRequestError。本地文件场景下，SDK 会通过FormData以multipart/form-data上传文件，并携带model、optionalPayload、可选的pageRanges与batchId字段（见 http.ts）；文件不存在时抛出FileNotFoundError。
3.3 文档解析：输出结构化 Markdown
const doc = await client.parseDocument({ filePath: "./report.pdf", options: { useChartRecognition: true, }, }); console.log(doc.jobId, doc.pages.length); // 每页的 markdownText 即结构化结果parseDocument返回DocParsingResult，每一页包含markdownText（Markdown 文本）、markdownImages、outputImages（图片资源映射）等字段。文档解析默认使用 PaddleOCR-VL-1.6 模型。
四、公开 API 总览
SDK 公开方法分为三类：便捷方法（提交 + 等待合并）、手动控制方法（提交与等待分离）和资源保存方法：
| 方法 | 说明 |
|---|---|
ocr(...) | 提交 OCR 任务、等待完成并返回OCRResult |
parseDocument(...) | 提交文档解析任务、等待完成并返回DocParsingResult |
submitOcr(...) | 仅提交 OCR 任务，返回Job对象 |
submitDocumentParsing(...) | 仅提交文档解析任务，返回Job对象 |
getStatus(jobId) | 执行一次非阻塞的状态查询，返回JobStatus |
waitOcrResult(job) | 等待 OCR 任务完成并解析结果 |
waitDocumentParsingResult(job) | 等待文档解析任务完成并解析结果 |
saveResource(resourceUrl, destination, options) | 将单个资源 URL 下载保存到本地 |
saveOcrResultResources(result, destination, options) | 保存 OCR 结果引用的全部资源 |
saveDocumentParsingResultResources(result, destination, options) | 保存文档解析结果引用的全部资源 |
此外还有getBatchStatus(batchId)用于批量任务状态查询。
4.1 手动提交与并发等待
当需要并行提交多个任务时，可以拆分提交与等待两个阶段，例如 doc-parsing-file.ts 中的模式：
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、task（"ocr" | "document_parsing"）以及可选的pageRanges、batchId（见 results.ts）。wait*方法也接受纯字符串 jobId；若传入的Job任务类型与方法不匹配，会抛出InvalidRequestError（见 client.ts）。
4.2 资源保存与overwrite语义
saveResource的destination既可以是已存在的目录（自动按 URL 文件名命名），也可以是目标文件路径（见 client.ts）。saveOcrResultResources/saveDocumentParsingResultResources则要求destination必须是已存在的目录：
- 文档解析结果：保存每页
markdownImages与outputImages中引用的资源，文件名取自资源映射的 key，并进行路径安全校验（拒绝含/、\或..等危险 key，见 client.ts）； - OCR 结果：保存每页的
ocrImageUrl，自动命名为ocr-page-{n}{扩展名}； - 默认不允许覆盖已存在文件（会抛
InvalidRequestError），传入options: { overwrite: true }可启用覆盖。
五、模型选择：Model 枚举与官方模型名
Model枚举是官方 API 模型名字符串的类型安全别名，提交请求时会被序列化为对应的模型名；你也可以直接传字符串，例如model: "PaddleOCR-VL-1.6"。枚举定义见 models.ts。
| 任务 | 相关接口 | 默认模型 | 支持的模型 | 选项类型 |
|---|---|---|---|---|
| OCR | ocr、submitOcr、waitOcrResult | Model.PPOCRv6 | Model.PPOCRv5、Model.PPOCRv5Latin、Model.PPOCRv6 | OCROptions |
| 文档解析 | parseDocument、submitDocumentParsing、waitDocumentParsingResult | Model.PaddleOCRVL16 | Model.PPStructureV3、Model.PaddleOCRVL、Model.PaddleOCRVL15、Model.PaddleOCRVL16 | PPStructureV3用PPStructureV3Options；PaddleOCR-VL 系列用PaddleOCRVLOptions |
关于模型名与校验，有两点值得注意：
Model.PPOCRv5Latin（"PP-OCRv5-latin"）专门用于拉丁文体系的托管 OCR 模型（见 README.md）；- 任务-模型匹配校验：SDK 内部通过
isOCRModel、isDocumentParsingModel集合（见 models.ts）校验模型与任务是否匹配。例如把PaddleOCRVL16传给submitOcr，或把PPOCRv6传给submitDocumentParsing，都会抛出InvalidRequestError（见 client.ts）。这与测试文件中对公共契约的断言一致（client.test.ts）。
六、客户端配置：超时、代理与自定义网络层
6.1 超时控制
const client = new PaddleOCRClient({ requestTimeout: 300_000, // 单次 HTTP 请求上限，默认 300000ms pollTimeout: 600_000, // 总等待上限，默认 600000ms });requestTimeout约束单次 HTTP 请求，包括提交任务、查询状态、下载资源；pollTimeout约束ocr、parseDocument、waitOcrResult、waitDocumentParsingResult的总等待时间。
从 client.ts 看，还兼容旧字段timeout：当requestTimeout/pollTimeout未设置时，两者都回退到options.timeout。所有公开方法还可接收AbortSignal实现调用方主动取消。
6.2 覆盖服务地址
const client = new PaddleOCRClient({ baseUrl: "https://my-proxy.com/paddle", });也可通过环境变量PADDLEOCR_BASE_URL覆盖（优先级低于baseUrl选项）。baseUrl 末尾的斜杠会被自动去除（http.ts）。这一能力便于对接代理或私有网关。
6.3 注入自定义 fetch
const client = new PaddleOCRClient({ fetch: myCustomFetch, });注入自定义fetch实现可用于代理、日志、mock 或自定义网络层。测试代码正是利用这一机制注入vi.fnmock 的 fetch 来验证请求体与错误映射（client.test.ts）。
6.4 其他客户端选项
ClientOptions还包含clientPlatform，设置后会在请求头附加Client-Platform（见 models.ts 与 http.ts）。
七、请求参数详解：camelCase 字段与三大选项类型
SDK 字段名采用 camelCase，与官方 API 直接对应；未设置的字段不会随请求发送。完整字段定义以接口源码或官方 API 参考为准。下面结合 models.ts 中的接口定义，给出三大选项类型的完整字段说明。
7.1 OCROptions（OCR 通用字段）
| 字段 | 类型 | 说明 |
|---|---|---|
useDocOrientationClassify | boolean | 文档方向分类 |
useDocUnwarping | boolean | 文档展开（去透视畸变） |
useTextlineOrientation | boolean | 文本行方向分类 |
textDetLimitSideLen | number | 检测端输入边长限制 |
textDetLimitType | string | 检测端限制类型（如 min/max） |
textDetThresh | number | 检测二值化阈值 |
textDetBoxThresh | number | 检测框阈值 |
textDetUnclipRatio | number | 检测框扩张比例 |
textRecScoreThresh | number | 识别分数阈值 |
visualize | boolean | 返回可视化图片 |
7.2 PPStructureV3Options（文档解析-结构模型通用字段）
| 字段 | 类型 | 说明 |
|---|---|---|
useTableRecognition | boolean | 表格识别 |
useFormulaRecognition | boolean | 公式识别 |
useChartRecognition | boolean | 图表识别 |
prettifyMarkdown | boolean | Markdown 美化 |
useDocOrientationClassify/useDocUnwarping/useTextlineOrientation | boolean | 文档预处理三项 |
useSealRecognition | boolean | 印章识别 |
useRegionDetection | boolean | 区域检测 |
layoutThreshold | number | Record<string, number> | 版面分类阈值（支持按类别细分） |
layoutNms | boolean | 版面 NMS |
layoutUnclipRatio | number | number[] | Record<string, number> | 版面框扩张比例 |
layoutMergeBboxesMode | string | Record<string, string> | 版面框合并模式 |
formatBlockContent | boolean | 块内容格式化 |
textDet*/textRecScoreThresh | number/string | 文本检测/识别参数（同 OCR） |
useWiredTableCellsTransToHtml/useWirelessTableCellsTransToHtml | boolean | 有线/无线表格转 HTML |
useTableOrientationClassify | boolean | 表格方向分类 |
useOcrResultsWithTableCells | boolean | 表格单元附带 OCR 结果 |
useE2eWiredTableRecModel/useE2eWirelessTableRecModel | boolean | 端到端表格识别模型 |
markdownIgnoreLabels | string[] | 忽略的 Markdown 标签列表 |
showFormulaNumber | boolean | 公式编号显示 |
returnMarkdownImages | boolean | 返回 Markdown 图片 |
outputFormats | string[] | 输出格式列表 |
visualize | boolean | 返回可视化图片 |
7.3 PaddleOCRVLOptions（PaddleOCR-VL 系列通用字段）
| 字段 | 类型 | 说明 |
|---|---|---|
useLayoutDetection | boolean | 版面检测 |
useChartRecognition | boolean | 图表识别 |
temperature | number | 采样温度 |
prettifyMarkdown | boolean | Markdown 美化 |
useDocOrientationClassify/useDocUnwarping | boolean | 文档预处理 |
useSealRecognition | boolean | 印章识别 |
useOcrForImageBlock | boolean | 对图片块执行 OCR |
layoutThreshold/layoutNms/layoutUnclipRatio/layoutMergeBboxesMode | 同 PPStructureV3 | 版面控制参数 |
layoutShapeMode | "rect" \| "quad" \| "poly" \| "auto" | 版面形状模式 |
promptLabel | "ocr" \| "formula" \| "table" \| "chart" \| "seal" \| "spotting" | 提示标签 |
formatBlockContent | boolean | 块内容格式化 |
repetitionPenalty | number | 重复惩罚 |
topP | number | top-p 采样 |
minPixels/maxPixels | number | 图像像素范围 |
maxNewTokens | number | 生成最大 token 数 |
vlmExtraArgs | Record<string, unknown> | VLM 附加参数 |
mergeLayoutBlocks | boolean | 合并版面块 |
markdownIgnoreLabels | string[] | 忽略的 Markdown 标签 |
showFormulaNumber | boolean | 公式编号 |
restructurePages | boolean | 页面重构 |
mergeTables | boolean | 合并表格 |
relevelTitles | boolean | 标题层级重排 |
returnMarkdownImages/outputFormats/visualize | 同 PPStructureV3 | 输出控制 |
说明：
DocParsingOptions是PPStructureV3Options | PaddleOCRVLOptions的联合类型，实际可用字段取决于所选模型（见 models.ts）。
八、结果结构与轮询机制：从提交到拿到结构化数据
8.1 结果对象
OCR 结果OCRResult与文档解析结果DocParsingResult都包含jobId、pages数组与可选的dataInfo（见 results.ts）：
OCRPage：prunedResult（精简后的识别结果）、ocrImageUrl、docPreprocessingImageUrl（预处理可视化图）、inputImageUrl（输入图）、raw（原始数据）；DocParsingPage：markdownText、markdownImages、outputImages、prunedResult、inputImageUrl、exports、markdown、raw。
任务状态JobStatus包含state（pending/running/done/failed）、progress（totalPages/extractedPages等进度信息）、resultUrl与errorMsg（results.ts）。
8.2 结果解析：JSONL 逐行还原
任务完成后，SDK 从状态响应中的resultUrl.jsonUrl拉取 JSONL 结果并按行解析（poller.ts）：
- OCR：校验
result.ocrResults数组，每页必须有prunedResult，并提取ocrImage、docPreprocessingImage、inputImage等 URL（client.ts）； - 文档解析：校验
result.layoutParsingResults，每页必须有markdown.text，并映射markdown.images与outputImages（client.ts）。
解析失败会抛出ResultParseError。
8.3 轮询策略：指数退避
Poller的默认参数为：初始间隔3000ms、退避倍数1.5、最大间隔15000ms、最大等待600000ms（poller.ts）。轮询循环中，done即拉取结果，failed抛JobFailedError，超过pollTimeout抛PollTimeoutError。sleep期间监听AbortSignal以支持调用方取消。
九、错误处理：类型化异常体系
SDK 所有错误统一继承自PaddleOCRAPIError（见 errors.ts）：
| 错误类型 | 触发场景 |
|---|---|
AuthError | 令牌缺失或认证失败（HTTP 401/403） |
InvalidRequestError | 参数校验失败（如 fileUrl/filePath 互斥、模型不匹配）、HTTP 400 |
RateLimitError | 触发限流（HTTP 429） |
ServiceUnavailableError | 服务不可用（HTTP 503/504） |
APIError | 其他 HTTP 错误，携带statusCode |
NetworkError | 网络连接失败 |
JobFailedError | 任务执行失败，携带jobId与errorMsg |
RequestTimeoutError | 单次请求超时 |
PollTimeoutError | 总轮询等待超时，携带jobId |
ResponseFormatError | 响应结构不符合预期 |
ResultParseError | 结果数据解析失败 |
FileNotFoundError | 本地文件不存在 |
HTTP 状态到类型化错误的映射实现在 http.ts：401/403 → AuthError、400 → InvalidRequestError、429 → RateLimitError、503/504 → ServiceUnavailableError，其余归入APIError；业务响应体中code !== 0同样抛APIError。所有请求默认携带Authorization: Bearer <token>头。实践建议：对RateLimitError做退避重试，对PollTimeoutError保存jobId以便稍后通过getStatus恢复查询。
十、测试与示例：验证公共契约
仓库为该 SDK 提供了完整的测试与可运行示例：
- tests/client.test.ts：覆盖令牌要求、公共方法存在性、请求体契约、状态轮询、JSONL 解析、错误映射与资源保存等 703 行测试；
- examples/ocr-url.ts：远程 URL 的 OCR 完整示例；
- examples/doc-parsing-file.ts：本地文件文档解析 + 手动提交并发等待示例。
SDK 遵循 SemVer 语义化版本，以公共 scoped npm 包发布。除 TypeScript 外，官方 API 还提供 Python、Go 与 CLI 等语言/工具变体文档，以及中文版 typescript.md，可按需查阅。配额规则与错误码说明请以官方 API 的 Quota and Error Codes 文档为准。
总结
@paddleocr/api-sdk将「提交任务 → 轮询状态 → 拉取 JSONL → 结构化解析」的完整链路封装为十余个类型安全的方法：ocr/parseDocument适合串行便捷调用，submit*+wait*适合批量并发，save*系列则一键落盘可视化图片与 Markdown 资源。配合Model枚举、camelCase 请求选项与类型化错误体系，你可以快速把 PDF/图片转成文本、表格、公式与 Markdown 结构化数据，直接对接下游 AI 应用与 LLM 工作流。
【免费下载链接】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），仅供参考
