feat: add multi-language API SDK (Python/Go/TypeScript)#18049
Open
Rander7 wants to merge 2 commits into
Open
Conversation
Add Python/Go/TypeScript SDKs that wrap the PaddleOCR async job API (submit → poll → fetch result) into simple blocking interfaces. Python SDK: - Integrated into paddleocr/_api_client/ as internal subpackage - APIClient (sync) + AsyncAPIClient (asyncio) dual interfaces - CLI subcommand: paddleocr api --model_type ocr/doc_parsing - Supports PP-OCRv5, PP-StructureV3, PaddleOCR-VL, PaddleOCR-VL-1.5 Go SDK (api_sdk/go/): - Zero dependencies (stdlib only) - Functional options pattern + context.Context cancellation - Operation object with Wait(ctx)/Poll(ctx) methods TypeScript SDK (api_sdk/typescript/): - Zero dependencies (native fetch, Node>=18) - AbortSignal cancellation support - ESM + CJS dual output All SDKs share: - Exponential backoff polling (3s initial, 1.5x, 15s max, configurable timeout) - Typed error hierarchy (Auth/API/JobFailed/Timeout/Network/FileNotFound) - URL and local file upload support - Convenience methods + manual control (submit/wait/poll) interfaces
|
|
|
Thanks for your contribution! |
Bobholamovic
requested changes
May 19, 2026
| @@ -0,0 +1,73 @@ | |||
| // Copyright (c) 2025 PaddlePaddle Authors. All Rights Reserved. | |||
| # limitations under the License. | ||
|
|
||
|
|
||
| class PaddleOCRError(Exception): |
Member
There was a problem hiding this comment.
考虑到这是在paddleocr主库中，叫这个名字是否有些范围太大。建议可以考虑 PaddleOCRAPIError 之类的
| """Network connection failure.""" | ||
|
|
||
|
|
||
| class FileNotFoundError(PaddleOCRError): |
Member
There was a problem hiding this comment.
需要评估是否更适合直接使用Python builtin的FileNotFoundError
|
|
||
|
|
||
| @dataclass | ||
| class OCROptions: |
Member
There was a problem hiding this comment.
这里缺少了很多配置，建议参考官方文档补全：https://ai.baidu.com/ai-doc/AISTUDIO/Kmfl2ycs0
| "--model", | ||
| type=str, | ||
| default=None, | ||
| help="Model name (required for doc_parsing): PP-StructureV3, PaddleOCR-VL, PaddleOCR-VL-1.5", |
Member
There was a problem hiding this comment.
这里建议为未来预留，不限定死doc_parsing任务；以后OCR任务也可能会有PP-OCRv6等不同版本模型。
| choices=["ocr", "doc_parsing"], | ||
| help="Task type: ocr or doc_parsing", | ||
| ) | ||
| subparser.add_argument( |
Member
There was a problem hiding this comment.
另外，我注意到底层定义了枚举，那么这里建议复用枚举值，而不是在字符串里把名字再硬编码一次
|
|
||
|
|
||
| def _resolve_model(model_str: str) -> Model: | ||
| mapping = { |
- Rename PaddleOCRError to PaddleOCRAPIError across all three SDKs - Replace custom FileNotFoundError with Python builtin in Python SDK - Expand OCROptions/DocParsingOptions with all API parameters (Python/Go/TS) - CLI: use Model enum values instead of hardcoded strings - CLI: allow --model for both ocr and doc_parsing tasks - Update license header year to 2026 - Simplify TypeScript defaultPayload to empty object
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What problem does this PR solve?
PaddleOCR 下游集成目前使用同步 API 直调方式，缺少统一的多语言 SDK 封装。本 PR 新增 Python/Go/TypeScript 三语言 API SDK，将异步任务 API（提交→轮询→获取结果）封装为简单的阻塞式调用接口，用户调用一个方法即可直接拿到解析结果。
主要功能：
paddleocr/_api_client/，提供APIClient（同步）+AsyncAPIClient（异步）+ CLI 子命令paddleocr apiapi_sdk/go/，零依赖，Functional Options + context.Context 取消支持api_sdk/typescript/，零依赖，原生 fetch + AbortSignal 取消支持Type of change