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/PaddleOCRPaddleOCR 官方 TypeScript SDKpaddleocr/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.tsModel枚举、请求/客户端选项类型定义results.ts结果、任务Job、状态等返回类型errors.ts类型化错误体系统一继承自PaddleOCRAPIErrorinternal/http.tsHTTP 传输层提交任务、查询状态、拉取结果internal/poller.ts轮询器指数退避等待任务完成internal/abort.tsAbortSignal取消支持SDK 默认服务地址为https://paddleocr.aistudio-app.com任务提交路径为/api/v2/ocr/jobs见 http.ts。二、安装与认证安装依赖与配置令牌只需两步npm install paddleocr/api-sdk export PADDLEOCR_ACCESS_TOKENyour-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.mdnpm install后执行npm run build之后可通过npm run lint、npm test、npm audit --audit-levelmoderate完成质量检查。三、快速开始一行代码完成 OCR3.1 识别远程文件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);client.ocr(...)是一个便捷方法内部先提交 OCR 任务再自动轮询等待完成最后解析返回OCRResult。result.pages按页存放识别结果result.jobId为任务 ID。3.2 识别本地文件filePathconst 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 文档解析输出结构化 Markdownconst doc await client.parseDocument({ filePath: ./report.pdf, options: { useChartRecognition: true, }, }); console.log(doc.jobId, doc.pages.length); // 每页的 markdownText 即结构化结果parseDocument返回DocParsingResult每一页包含markdownTextMarkdown 文本、markdownImages、outputImages图片资源映射等字段。文档解析默认使用 PaddleOCR-VL-1.6 模型。四、公开 API 总览SDK 公开方法分为三类便捷方法提交 等待合并、手动控制方法提交与等待分离和资源保存方法方法说明ocr(...)提交 OCR 任务、等待完成并返回OCRResultparseDocument(...)提交文档解析任务、等待完成并返回DocParsingResultsubmitOcr(...)仅提交 OCR 任务返回Job对象submitDocumentParsing(...)仅提交文档解析任务返回Job对象getStatus(jobId)执行一次非阻塞的状态查询返回JobStatuswaitOcrResult(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、taskocr | 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.tsOCR 结果保存每页的ocrImageUrl自动命名为ocr-page-{n}{扩展名}默认不允许覆盖已存在文件会抛InvalidRequestError传入options: { overwrite: true }可启用覆盖。五、模型选择Model 枚举与官方模型名Model枚举是官方 API 模型名字符串的类型安全别名提交请求时会被序列化为对应的模型名你也可以直接传字符串例如model: PaddleOCR-VL-1.6。枚举定义见 models.ts。任务相关接口默认模型支持的模型选项类型OCRocr、submitOcr、waitOcrResultModel.PPOCRv6Model.PPOCRv5、Model.PPOCRv5Latin、Model.PPOCRv6OCROptions文档解析parseDocument、submitDocumentParsing、waitDocumentParsingResultModel.PaddleOCRVL16Model.PPStructureV3、Model.PaddleOCRVL、Model.PaddleOCRVL15、Model.PaddleOCRVL16PPStructureV3用PPStructureV3OptionsPaddleOCR-VL 系列用PaddleOCRVLOptions关于模型名与校验有两点值得注意Model.PPOCRv5LatinPP-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 注入自定义 fetchconst 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 OCROptionsOCR 通用字段字段类型说明useDocOrientationClassifyboolean文档方向分类useDocUnwarpingboolean文档展开去透视畸变useTextlineOrientationboolean文本行方向分类textDetLimitSideLennumber检测端输入边长限制textDetLimitTypestring检测端限制类型如 min/maxtextDetThreshnumber检测二值化阈值textDetBoxThreshnumber检测框阈值textDetUnclipRationumber检测框扩张比例textRecScoreThreshnumber识别分数阈值visualizeboolean返回可视化图片7.2 PPStructureV3Options文档解析-结构模型通用字段字段类型说明useTableRecognitionboolean表格识别useFormulaRecognitionboolean公式识别useChartRecognitionboolean图表识别prettifyMarkdownbooleanMarkdown 美化useDocOrientationClassify/useDocUnwarping/useTextlineOrientationboolean文档预处理三项useSealRecognitionboolean印章识别useRegionDetectionboolean区域检测layoutThresholdnumber | Recordstring, number版面分类阈值支持按类别细分layoutNmsboolean版面 NMSlayoutUnclipRationumber | number[] | Recordstring, number版面框扩张比例layoutMergeBboxesModestring | Recordstring, string版面框合并模式formatBlockContentboolean块内容格式化textDet*/textRecScoreThreshnumber/string文本检测/识别参数同 OCRuseWiredTableCellsTransToHtml/useWirelessTableCellsTransToHtmlboolean有线/无线表格转 HTMLuseTableOrientationClassifyboolean表格方向分类useOcrResultsWithTableCellsboolean表格单元附带 OCR 结果useE2eWiredTableRecModel/useE2eWirelessTableRecModelboolean端到端表格识别模型markdownIgnoreLabelsstring[]忽略的 Markdown 标签列表showFormulaNumberboolean公式编号显示returnMarkdownImagesboolean返回 Markdown 图片outputFormatsstring[]输出格式列表visualizeboolean返回可视化图片7.3 PaddleOCRVLOptionsPaddleOCR-VL 系列通用字段字段类型说明useLayoutDetectionboolean版面检测useChartRecognitionboolean图表识别temperaturenumber采样温度prettifyMarkdownbooleanMarkdown 美化useDocOrientationClassify/useDocUnwarpingboolean文档预处理useSealRecognitionboolean印章识别useOcrForImageBlockboolean对图片块执行 OCRlayoutThreshold/layoutNms/layoutUnclipRatio/layoutMergeBboxesMode同 PPStructureV3版面控制参数layoutShapeModerect \| quad \| poly \| auto版面形状模式promptLabelocr \| formula \| table \| chart \| seal \| spotting提示标签formatBlockContentboolean块内容格式化repetitionPenaltynumber重复惩罚topPnumbertop-p 采样minPixels/maxPixelsnumber图像像素范围maxNewTokensnumber生成最大 token 数vlmExtraArgsRecordstring, unknownVLM 附加参数mergeLayoutBlocksboolean合并版面块markdownIgnoreLabelsstring[]忽略的 Markdown 标签showFormulaNumberboolean公式编号restructurePagesboolean页面重构mergeTablesboolean合并表格relevelTitlesboolean标题层级重排returnMarkdownImages/outputFormats/visualize同 PPStructureV3输出控制说明DocParsingOptions是PPStructureV3Options | PaddleOCRVLOptions的联合类型实际可用字段取决于所选模型见 models.ts。八、结果结构与轮询机制从提交到拿到结构化数据8.1 结果对象OCR 结果OCRResult与文档解析结果DocParsingResult都包含jobId、pages数组与可选的dataInfo见 results.tsOCRPageprunedResult精简后的识别结果、ocrImageUrl、docPreprocessingImageUrl预处理可视化图、inputImageUrl输入图、raw原始数据DocParsingPagemarkdownText、markdownImages、outputImages、prunedResult、inputImageUrl、exports、markdown、raw。任务状态JobStatus包含statepending/running/done/failed、progresstotalPages/extractedPages等进度信息、resultUrl与errorMsgresults.ts。8.2 结果解析JSONL 逐行还原任务完成后SDK 从状态响应中的resultUrl.jsonUrl拉取 JSONL 结果并按行解析poller.tsOCR校验result.ocrResults数组每页必须有prunedResult并提取ocrImage、docPreprocessingImage、inputImage等 URLclient.ts文档解析校验result.layoutParsingResults每页必须有markdown.text并映射markdown.images与outputImagesclient.ts。解析失败会抛出ResultParseError。8.3 轮询策略指数退避Poller的默认参数为初始间隔3000ms、退避倍数1.5、最大间隔15000ms、最大等待600000mspoller.ts。轮询循环中done即拉取结果failed抛JobFailedError超过pollTimeout抛PollTimeoutError。sleep期间监听AbortSignal以支持调用方取消。九、错误处理类型化异常体系SDK 所有错误统一继承自PaddleOCRAPIError见 errors.ts错误类型触发场景AuthError令牌缺失或认证失败HTTP 401/403InvalidRequestError参数校验失败如 fileUrl/filePath 互斥、模型不匹配、HTTP 400RateLimitError触发限流HTTP 429ServiceUnavailableError服务不可用HTTP 503/504APIError其他 HTTP 错误携带statusCodeNetworkError网络连接失败JobFailedError任务执行失败携带jobId与errorMsgRequestTimeoutError单次请求超时PollTimeoutError总轮询等待超时携带jobIdResponseFormatError响应结构不符合预期ResultParseError结果数据解析失败FileNotFoundError本地文件不存在HTTP 状态到类型化错误的映射实现在 http.ts401/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），仅供参考
PaddleOCR TypeScript SDK：基于官方托管 API 的 OCR 与文档解析客户端完整指南
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/PaddleOCRPaddleOCR 官方 TypeScript SDKpaddleocr/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.tsModel枚举、请求/客户端选项类型定义results.ts结果、任务Job、状态等返回类型errors.ts类型化错误体系统一继承自PaddleOCRAPIErrorinternal/http.tsHTTP 传输层提交任务、查询状态、拉取结果internal/poller.ts轮询器指数退避等待任务完成internal/abort.tsAbortSignal取消支持SDK 默认服务地址为https://paddleocr.aistudio-app.com任务提交路径为/api/v2/ocr/jobs见 http.ts。二、安装与认证安装依赖与配置令牌只需两步npm install paddleocr/api-sdk export PADDLEOCR_ACCESS_TOKENyour-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.mdnpm install后执行npm run build之后可通过npm run lint、npm test、npm audit --audit-levelmoderate完成质量检查。三、快速开始一行代码完成 OCR3.1 识别远程文件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);client.ocr(...)是一个便捷方法内部先提交 OCR 任务再自动轮询等待完成最后解析返回OCRResult。result.pages按页存放识别结果result.jobId为任务 ID。3.2 识别本地文件filePathconst 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 文档解析输出结构化 Markdownconst doc await client.parseDocument({ filePath: ./report.pdf, options: { useChartRecognition: true, }, }); console.log(doc.jobId, doc.pages.length); // 每页的 markdownText 即结构化结果parseDocument返回DocParsingResult每一页包含markdownTextMarkdown 文本、markdownImages、outputImages图片资源映射等字段。文档解析默认使用 PaddleOCR-VL-1.6 模型。四、公开 API 总览SDK 公开方法分为三类便捷方法提交 等待合并、手动控制方法提交与等待分离和资源保存方法方法说明ocr(...)提交 OCR 任务、等待完成并返回OCRResultparseDocument(...)提交文档解析任务、等待完成并返回DocParsingResultsubmitOcr(...)仅提交 OCR 任务返回Job对象submitDocumentParsing(...)仅提交文档解析任务返回Job对象getStatus(jobId)执行一次非阻塞的状态查询返回JobStatuswaitOcrResult(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、taskocr | 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.tsOCR 结果保存每页的ocrImageUrl自动命名为ocr-page-{n}{扩展名}默认不允许覆盖已存在文件会抛InvalidRequestError传入options: { overwrite: true }可启用覆盖。五、模型选择Model 枚举与官方模型名Model枚举是官方 API 模型名字符串的类型安全别名提交请求时会被序列化为对应的模型名你也可以直接传字符串例如model: PaddleOCR-VL-1.6。枚举定义见 models.ts。任务相关接口默认模型支持的模型选项类型OCRocr、submitOcr、waitOcrResultModel.PPOCRv6Model.PPOCRv5、Model.PPOCRv5Latin、Model.PPOCRv6OCROptions文档解析parseDocument、submitDocumentParsing、waitDocumentParsingResultModel.PaddleOCRVL16Model.PPStructureV3、Model.PaddleOCRVL、Model.PaddleOCRVL15、Model.PaddleOCRVL16PPStructureV3用PPStructureV3OptionsPaddleOCR-VL 系列用PaddleOCRVLOptions关于模型名与校验有两点值得注意Model.PPOCRv5LatinPP-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 注入自定义 fetchconst 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 OCROptionsOCR 通用字段字段类型说明useDocOrientationClassifyboolean文档方向分类useDocUnwarpingboolean文档展开去透视畸变useTextlineOrientationboolean文本行方向分类textDetLimitSideLennumber检测端输入边长限制textDetLimitTypestring检测端限制类型如 min/maxtextDetThreshnumber检测二值化阈值textDetBoxThreshnumber检测框阈值textDetUnclipRationumber检测框扩张比例textRecScoreThreshnumber识别分数阈值visualizeboolean返回可视化图片7.2 PPStructureV3Options文档解析-结构模型通用字段字段类型说明useTableRecognitionboolean表格识别useFormulaRecognitionboolean公式识别useChartRecognitionboolean图表识别prettifyMarkdownbooleanMarkdown 美化useDocOrientationClassify/useDocUnwarping/useTextlineOrientationboolean文档预处理三项useSealRecognitionboolean印章识别useRegionDetectionboolean区域检测layoutThresholdnumber | Recordstring, number版面分类阈值支持按类别细分layoutNmsboolean版面 NMSlayoutUnclipRationumber | number[] | Recordstring, number版面框扩张比例layoutMergeBboxesModestring | Recordstring, string版面框合并模式formatBlockContentboolean块内容格式化textDet*/textRecScoreThreshnumber/string文本检测/识别参数同 OCRuseWiredTableCellsTransToHtml/useWirelessTableCellsTransToHtmlboolean有线/无线表格转 HTMLuseTableOrientationClassifyboolean表格方向分类useOcrResultsWithTableCellsboolean表格单元附带 OCR 结果useE2eWiredTableRecModel/useE2eWirelessTableRecModelboolean端到端表格识别模型markdownIgnoreLabelsstring[]忽略的 Markdown 标签列表showFormulaNumberboolean公式编号显示returnMarkdownImagesboolean返回 Markdown 图片outputFormatsstring[]输出格式列表visualizeboolean返回可视化图片7.3 PaddleOCRVLOptionsPaddleOCR-VL 系列通用字段字段类型说明useLayoutDetectionboolean版面检测useChartRecognitionboolean图表识别temperaturenumber采样温度prettifyMarkdownbooleanMarkdown 美化useDocOrientationClassify/useDocUnwarpingboolean文档预处理useSealRecognitionboolean印章识别useOcrForImageBlockboolean对图片块执行 OCRlayoutThreshold/layoutNms/layoutUnclipRatio/layoutMergeBboxesMode同 PPStructureV3版面控制参数layoutShapeModerect \| quad \| poly \| auto版面形状模式promptLabelocr \| formula \| table \| chart \| seal \| spotting提示标签formatBlockContentboolean块内容格式化repetitionPenaltynumber重复惩罚topPnumbertop-p 采样minPixels/maxPixelsnumber图像像素范围maxNewTokensnumber生成最大 token 数vlmExtraArgsRecordstring, unknownVLM 附加参数mergeLayoutBlocksboolean合并版面块markdownIgnoreLabelsstring[]忽略的 Markdown 标签showFormulaNumberboolean公式编号restructurePagesboolean页面重构mergeTablesboolean合并表格relevelTitlesboolean标题层级重排returnMarkdownImages/outputFormats/visualize同 PPStructureV3输出控制说明DocParsingOptions是PPStructureV3Options | PaddleOCRVLOptions的联合类型实际可用字段取决于所选模型见 models.ts。八、结果结构与轮询机制从提交到拿到结构化数据8.1 结果对象OCR 结果OCRResult与文档解析结果DocParsingResult都包含jobId、pages数组与可选的dataInfo见 results.tsOCRPageprunedResult精简后的识别结果、ocrImageUrl、docPreprocessingImageUrl预处理可视化图、inputImageUrl输入图、raw原始数据DocParsingPagemarkdownText、markdownImages、outputImages、prunedResult、inputImageUrl、exports、markdown、raw。任务状态JobStatus包含statepending/running/done/failed、progresstotalPages/extractedPages等进度信息、resultUrl与errorMsgresults.ts。8.2 结果解析JSONL 逐行还原任务完成后SDK 从状态响应中的resultUrl.jsonUrl拉取 JSONL 结果并按行解析poller.tsOCR校验result.ocrResults数组每页必须有prunedResult并提取ocrImage、docPreprocessingImage、inputImage等 URLclient.ts文档解析校验result.layoutParsingResults每页必须有markdown.text并映射markdown.images与outputImagesclient.ts。解析失败会抛出ResultParseError。8.3 轮询策略指数退避Poller的默认参数为初始间隔3000ms、退避倍数1.5、最大间隔15000ms、最大等待600000mspoller.ts。轮询循环中done即拉取结果failed抛JobFailedError超过pollTimeout抛PollTimeoutError。sleep期间监听AbortSignal以支持调用方取消。九、错误处理类型化异常体系SDK 所有错误统一继承自PaddleOCRAPIError见 errors.ts错误类型触发场景AuthError令牌缺失或认证失败HTTP 401/403InvalidRequestError参数校验失败如 fileUrl/filePath 互斥、模型不匹配、HTTP 400RateLimitError触发限流HTTP 429ServiceUnavailableError服务不可用HTTP 503/504APIError其他 HTTP 错误携带statusCodeNetworkError网络连接失败JobFailedError任务执行失败携带jobId与errorMsgRequestTimeoutError单次请求超时PollTimeoutError总轮询等待超时携带jobIdResponseFormatError响应结构不符合预期ResultParseError结果数据解析失败FileNotFoundError本地文件不存在HTTP 状态到类型化错误的映射实现在 http.ts401/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），仅供参考
