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: 8e9c0c578a2d
+i18n_source_hash: 0d453b49db02
 i18n_provenance: human
-i18n_output_hash: 3b9f7c3af638
 ---

 # 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 編碼和 4000 萬像素解碼；較低的運營商上傳限制仍然適用 |
+| 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 segfault），會自動以下一個較低層級重試。
- 若某層級傳回空白文字但未當機，也會退回至下一個層級。
- 品質層級對應各引擎：`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`。超過 4000 萬像素的圖像和超過其有限輸出限制的 OCR 回應將被拒絕，而不是部分處理。
@@ -1,14 +1,20 @@
 ---
-description: "使用 AI 驅動的 OCR 從 PDF 文件中擷取文字。"
-i18n_source_hash: 1431fcba180b
+description: "使用內建 Tesseract 或可選的高精度 RapidOCR 運行時從本地掃描的 PDF 中提取文字。"
+i18n_output_hash: 01d4565a7e86
+i18n_source_hash: a19ba25a1ca8
 i18n_provenance: human
-i18n_output_hash: afab5ee963b5
 ---

 # 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 端點 {#api-endpoint}

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

 | 參數 | 類型 | 必填 | 預設值 | 說明 |
 |-----------|------|----------|---------|-------------|
-| quality | string | 否 | `"balanced"` | OCR 品質層級：`fast`、`balanced`、`best` |
+| file | file | 是的 | - | PDF 檔案（多部分），最多 512 個 MiB 編碼；較低的運營商上傳限制仍然適用 |
+| quality | string | 不 | 動態的 | OCR 品質等級：`fast`、`balanced` 或 `best` |
 | language | string | 否 | `"auto"` | 文件語言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko` |
 | pages | string | 否 | `"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}

@@ -29,7 +40,7 @@ i18n_output_hash: afab5ee963b5
 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}
@@ -46,8 +57,11 @@ curl -X POST http://localhost:1349/api/v1/tools/pdf/ocr-pdf \
 ## 注意事項 {#notes}

 - 接受的輸入格式：`.pdf`。
- 這是一個需要安裝 **OCR 功能套件包** 的 AI 工具。若未安裝該套件包，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 轉文字](./pdf-to-text) 工具。