fix: make OCR portable and reliable across AMD64 and ARM64 (#519)

* fix: make OCR portable and reliable * fix: harden OCR installation portability * fix: pin OCR partials across downloads * fix: make OCR execution reliably asynchronous * fix: harden OCR portability and docs routes * fix: preserve decoder and docs safeguards
2026-08-03 07:46:42 +02:00 · 2026-07-15 03:34:24 +08:00
parent 58121f205f
commit 991c981529
409 changed files with 67151 additions and 8076 deletions
@@ -1,31 +1,39 @@
 ---
-description: "使用基于 AI 的光学字符识别从图片中提取文本。"
-i18n_source_hash: 3d85d423b82c
+description: "使用内置 Tesseract 或可选的高精度 RapidOCR 运行时从本地图像中提取文本。"
+i18n_output_hash: b452e084e28a
+i18n_source_hash: 0d453b49db02
 i18n_provenance: human
-i18n_output_hash: ae14f7fe10d3
 ---

 # OCR / 文本提取 {#ocr-text-extraction}

-使用基于 AI 的光学字符识别从图片中提取文本。支持多种语言和质量档位。
+从图像中提取文本，而不将图像发送到外部服务。内置 `fast` 层使用 Tesseract。可选的 `balanced` 和 `best` 层使用 RapidOCR 和固定的 PP-OCR ONNX 模型。

+
+<!-- korean-ocr-contract:start -->
+::: info 韩语 OCR 兼容性
+快速 OCR 支持 `auto`、`en`、`de`、`es`、`fr`、`zh` 和 `ja`，但不支持韩语 (`ko`)。韩语需要精确 OCR 包以及 `balanced` 或 `best`。该包可在官方 Linux amd64 和 arm64 容器上运行；即使是 NVIDIA 主机，OCR 仍使用 CPU。不受支持的系统会返回明确的兼容性错误，绝不会静默回退到 `fast`。韩语与 `fast` 或旧版 `tesseract` 别名的组合会在入队前以 `FEATURE_INCOMPATIBLE` 和 `fast-korean-unsupported` 拒绝。
+:::
+<!-- korean-ocr-contract:end -->
 ## API 端点 {#api-endpoint}

 `POST /api/v1/tools/image/ocr`

-**处理方式：** 同步 JSON 响应。若提供了 `clientJobId`，则进度也会通过 SSE 上报。
+**处理：** OCR 始终异步运行。验证并加入队列后，端点会立即返回带有 `jobId` 的 `202 Accepted`。请通过作业的 SSE 进度流跟踪至最终的 `complete` 或 `failed` 事件；成功事件的 `result` 包含 OCR 字段。

-**模型包：** `ocr`（5-6 GB）
+**准确的 OCR 包：** 可选的 `ocr` 运行时（大约下载 208-234 MiB 并安装 409-488 MiB，具体取决于目标）。 `fast` 不需要此包；安装程序会验证签名索引所限制的确切大小。

 ## 参数 {#parameters}

 | 参数 | 类型 | 是否必填 | 默认值 | 说明 |
 |-----------|------|----------|---------|-------------|
-| file | file | 是 | - | 图片文件（multipart） |
-| quality | string | 否 | `"balanced"` | 质量档位：`fast`（Tesseract）、`balanced`（PaddleOCR v5）、`best`（PaddleOCR VL） |
+| file | file | 是的 | - | 图像文件（多部分），最多 512 MiB 编码和 40 兆像素解码；较低的运营商上传限制仍然适用 |
+| quality | string | 不 | 动态的 | 质量等级：`fast` (Tesseract)、`balanced`（带有小型 PP-OCRv6 模型的 RapidOCR）或 `best`（具有校准变量评分的更高精度中型 PP-OCRv6 模型） |
 | language | string | 否 | `"auto"` | 语言提示：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko` |
-| enhance | boolean | 否 | `true` | 对图片进行预处理以提高 OCR 准确度 |
-| engine | string | 否 | - | 已弃用。请改用 `quality`。将 `tesseract` 映射为 `fast`，将 `paddleocr` 映射为 `balanced` |
+| enhance | boolean | 不 | 取决于层级 | 提高识别前的局部对比度。快速直接应用；仅当校准评分改善结果时，平衡和最佳才会保留变体。对于 `best` 默认为 `true`，对于 `fast`/`balanced` 默认为 `false` |
+| engine | string | 不 | - | 已弃用的兼容性别名。请改用 `quality`。 `tesseract` 映射到 `fast`；旧版 `paddleocr` 值映射到 `balanced` 但不加载 PaddlePaddle |
+
+省略 `quality` 和 `engine` 时，SnapOtter 会按 `best`、`balanced`、`fast` 的顺序选择可用的最高质量层。韩语绝不会选择 `fast`；它会使用 `best`，其次是 `balanced`，否则返回精确运行时的安装或兼容性错误。

 ## 请求示例 {#example-request}

@@ -35,31 +43,55 @@ curl -X POST http://localhost:1349/api/v1/tools/image/ocr \
  -F 'settings={"quality":"best","language":"en","enhance":true}'
 ```

-## 响应（200 OK） {#response-200-ok}
+## 已接受的响应（202） {#accepted-response-202}

 ```json
 {
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "filename": "document.png",
-  "text": "Extracted text content from the image...",
-  "engine": "paddleocr-vl"
+  "async": true
 }
 ```

-### 进度（SSE，可选） {#progress-sse-optional}
+### 进度和结果（SSE） {#progress-sse-optional}

-若提供了 `clientJobId` 表单字段，则会流式传输进度事件：
+使用 `202` 响应返回的 `jobId`（或已提供的 `clientJobId`）连接到 `GET /api/v1/jobs/{jobId}/progress`。请保持流连接，直至收到最终的 `complete` 或 `failed` 事件。成功的最终帧会在 `result` 中包含 OCR 输出：

+```json
+{
+  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "type": "single",
+  "phase": "complete",
+  "stage": "complete",
+  "percent": 100,
+  "result": {
+    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/document_ocr.txt",
+    "originalSize": 12345,
+    "processedSize": 47,
+    "text": "Extracted text content from the image...",
+    "engine": "rapidocr-onnx",
+    "requestedQuality": "best",
+    "actualQuality": "best",
+    "device": "cpu",
+    "provider": "CPUExecutionProvider",
+    "degraded": false,
+    "warnings": [],
+    "runtimeVersion": "2.1.0",
+    "modelVersion": "PP-OCRv6-best-v1-medium"
+  }
+}
 ```
-event: progress
-data: {"phase":"processing","stage":"Recognizing text...","percent":50}
-```
+
+处理失败会通过最终 `failed` 事件的 `error` 字段传递；加入队列后不会以 HTTP `422` 响应返回。

 ## 说明 {#notes}

- 需要安装 `ocr` 模型包（5-6 GB）。
- OCR 直接返回提取的文本，而不是图片下载 URL。
- 采用回退链：若某个较高质量的档位崩溃（例如 PaddleOCR 段错误），会自动使用下一个较低档位重试。
- 若某个档位未崩溃但返回了空文本，也会回退到下一个档位。
- 质量档位对应引擎：`fast` = Tesseract，`balanced` = PaddleOCR v5，`best` = PaddleOCR VL。
+- `fast` 在支持的 SnapOtter 映像中始终可用。 `balanced` 和 `best` 需要可选的精确 OCR 包。
+- 内置 Tesseract 在官方镜像上增加了约25个 MiB。准确的包存储在 `/data/ai` 中，而不是烘焙到映像中。
+- 官方 Linux amd64 和 arm64 容器的准确包装已发布。 它特意使用 ONNX Runtime 的 CPU 提供程序（包括在 NVIDIA 主机上），因此它不依赖于 CUDA 库或 GPU 兼容性。 源和预构建的 bare-metal 安装使用 Fast OCR，除非它们提供自己的兼容运行时。
+- 成功的最终 `result` 同时包含 `text` 中的提取文本和 `downloadUrl` 中可下载的 `.txt` 产物。
+- SnapOtter 遵循明确要求的等级。如果`balanced`或`best`不可用，则 API 返回`501`和`FEATURE_NOT_INSTALLED`或`FEATURE_INCOMPATIBLE`；它永远不会默默地将请求降级到另一层。
+- 成功的空结果仍然是空结果。运行时失败会返回错误，而不是使用较低质量的引擎重试。
+- 成功的最终 `result` 会报告 `requestedQuality` 和 `actualQuality`，以及引擎、设备、提供程序、运行时和模型版本及所有警告。
 - 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
+- 超大编码输入返回 `413`。超过 40 兆像素的图像和超过其有限输出限制的 OCR 响应将被拒绝，而不是部分处理。
@@ -1,14 +1,20 @@
 ---
-description: "使用 AI 驱动的 OCR 从 PDF 文档中提取文本。"
-i18n_source_hash: 1431fcba180b
+description: "使用内置 Tesseract 或可选的高精度 RapidOCR 运行时从本地扫描的 PDF 中提取文本。"
+i18n_output_hash: e2437a0ab8cf
+i18n_source_hash: a19ba25a1ca8
 i18n_provenance: human
-i18n_output_hash: 3bb9f4bd9334
 ---

 # PDF OCR {#pdf-ocr}

-使用 AI 驱动的光学字符识别从 PDF 文档中提取文本。支持多种质量层级和语言。需要安装 OCR 功能包。
+从扫描的 PDF 文档中逐页提取文本，无需将 PDF 发送到外部服务。内置 `fast` 层使用 Tesseract。可选的 `balanced` 和 `best` 层使用 RapidOCR 和固定的 PP-OCR ONNX 模型。

+
+<!-- korean-ocr-contract:start -->
+::: info 韩语 OCR 兼容性
+快速 OCR 支持 `auto`、`en`、`de`、`es`、`fr`、`zh` 和 `ja`，但不支持韩语 (`ko`)。韩语需要精确 OCR 包以及 `balanced` 或 `best`。该包可在官方 Linux amd64 和 arm64 容器上运行；即使是 NVIDIA 主机，OCR 仍使用 CPU。不受支持的系统会返回明确的兼容性错误，绝不会静默回退到 `fast`。韩语与 `fast` 或旧版 `tesseract` 别名的组合会在入队前以 `FEATURE_INCOMPATIBLE` 和 `fast-korean-unsupported` 拒绝。
+:::
+<!-- korean-ocr-contract:end -->
 ## API Endpoint {#api-endpoint}

 `POST /api/v1/tools/pdf/ocr-pdf`
@@ -19,9 +25,14 @@ i18n_output_hash: 3bb9f4bd9334

 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| quality | string | No | `"balanced"` | OCR 质量层级：`fast`、`balanced`、`best` |
+| file | file | 是的 | - | PDF 文件（多部分），最多 512 个 MiB 编码；较低的运营商上传限制仍然适用 |
+| quality | string | 不 | 动态的 | OCR 质量等级：`fast`、`balanced` 或 `best` |
 | language | string | No | `"auto"` | 文档语言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko` |
 | pages | string | No | `"all"` | 页面选择，例如 `"all"`、`"1-3"`、`"1,3,5"` |
+| enhance | boolean | 不 | 取决于层级 | 提高识别前的局部对比度。快速直接应用；仅当校准评分改善结果时，平衡和最佳才会保留变体。对于 `best` 默认为 `true`，对于 `fast`/`balanced` 默认为 `false` |
+| engine | string | 不 | - | 已弃用的兼容性别名。请改用 `quality`。 `tesseract` 映射到 `fast`；旧版 `paddleocr` 值映射到 `balanced` 但不加载 PaddlePaddle |
+
+省略 `quality` 和 `engine` 时，SnapOtter 会按 `best`、`balanced`、`fast` 的顺序选择可用的最高质量层。韩语绝不会选择 `fast`；它会使用 `best`，其次是 `balanced`，否则返回精确运行时的安装或兼容性错误。

 ## Example Request {#example-request}

@@ -29,7 +40,7 @@ i18n_output_hash: 3bb9f4bd9334
 curl -X POST http://localhost:1349/api/v1/tools/pdf/ocr-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@scanned.pdf" \
-  -F 'settings={"quality": "best", "language": "en", "pages": "1-5"}'
+  -F 'settings={"quality": "best", "language": "en", "pages": "1-5", "enhance": true}'
 ```

 ## Example Response {#example-response}
@@ -46,8 +57,11 @@ curl -X POST http://localhost:1349/api/v1/tools/pdf/ocr-pdf \
 ## Notes {#notes}

 - 接受的输入格式：`.pdf`。
- 这是一个 AI 工具，需要安装 **OCR 功能包**。如果未安装该功能包，API 将返回 `501 Not Implemented`。
- `fast` 质量层级使用较轻量的模型以加快处理速度；`best` 使用更精确的模型，但以速度为代价。
- `auto` 语言设置会尝试自动检测文档语言。
+- 内置`fast`，并在官方镜像中添加了约25个 MiB。 `balanced` 和 `best` 需要可选的精确 OCR 包（大约下载 208-234 MiB 并安装 409-488 MiB，具体取决于目标）。
+- 准确包支持 Linux amd64 和 arm64，并在 CPU（包括 NVIDIA 主机）上使用 ONNX Runtime。
+- 明确请求的等级绝不会默默降级。如果 `balanced` 或 `best` 不可用，则 API 返回 `501` 和 `FEATURE_NOT_INSTALLED` 或 `FEATURE_INCOMPATIBLE`。
+- PDF 页面在 OCR 之前以高分辨率进行光栅化。 `best` 运行更高精度的中型 PP-OCRv6 模型，并对方向和增强变体进行评分，以速度为代价提高识别能力。
+- `auto` 语言设置可以跨支持的脚本集进行识别；明确的提示可以改善已知文档语言的结果。
 - 你可以使用范围（`"1-3"`）、逗号分隔的列表（`"1,3,5"`）或 `"all"` 来针对特定页面处理所有页面。
+- 一个请求最多可以处理 50 个页面。光栅化暂存数据的上限为 512 MiB，聚合 UTF-8 OCR 响应的上限为 1,000,000 字节；超出限制的作业失败而不是返回部分文本。
 - 对于已经包含可选择文本的 PDF，请考虑改用更快的 [PDF to Text](./pdf-to-text) 工具。