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

apps/docs/vi/api/rest.md

@@ -1,8 +1,8 @@
 ---
 description: "Tài liệu tham khảo REST API đầy đủ. Endpoint công cụ, xử lý hàng loạt, pipeline, thư viện tệp, xác thực, nhóm và các thao tác quản trị."
-i18n_source_hash: 8646977f7cc9
-i18n_provenance: machine
 i18n_output_hash: a2d3795ef769
+i18n_source_hash: b89b5df16af5
+i18n_provenance: human
 ---
 
 # Tài liệu tham khảo REST API {#rest-api-reference}
@@ -178,7 +178,7 @@ Mọi công cụ AI đều chạy trên phần cứng của bạn: mặc định
 | `remove-background` | Xóa nền | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
 | `upscale` | Phóng to ảnh | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
 | `erase-object` | Xóa vật thể | LaMa (ONNX) | Mặt nạ được gửi làm phần tệp thứ hai (tên trường `mask`), `format`, `quality` |
-| `ocr` | OCR / Trích xuất văn bản | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
+| `ocr` | OCR / Trích xuất văn bản | Tesseract (nhanh); RapidOCR + PP-OCR ONNX (cân bằng/tốt nhất) | `quality` (nhanh/cân bằng/tốt nhất), `language`, `enhance` |
 | `blur-faces` | Làm mờ khuôn mặt / PII | MediaPipe | `blurRadius`, `sensitivity` |
 | `smart-crop` | Cắt thông minh | MediaPipe + Sharp | `mode` (subject/face/trim), `strategy` (attention/entropy), `width`, `height`, `padding`, `facePreset` (closeup/head-shoulders/upper-body/half-body), `sensitivity`, `threshold`, `padToSquare`, `padColor`, `targetSize`, `quality` |
 | `image-enhancement` | Nâng cao ảnh | Dựa trên phân tích | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
@@ -425,7 +425,9 @@ Một số công cụ cung cấp thêm endpoint ngoài `POST /api/v1/tools/<sect
 
 ## Xử lý hàng loạt {#batch-processing}
 
-Áp dụng một công cụ hỗ trợ hàng loạt tổng quát cho nhiều tệp cùng lúc. Trả về một kho lưu trữ ZIP. Các route đa tệp hoặc nhiều bước tùy chỉnh, chẳng hạn ký PDF, OCR PDF và các route cấu hình PDF-sang-ảnh, dùng hợp đồng endpoint riêng thay vì route `/batch` tổng quát.
+Áp dụng một công cụ hỗ trợ hàng loạt tổng quát cho nhiều tệp cùng lúc. Trả về một kho lưu trữ ZIP. Các route đa tệp hoặc nhiều bước tùy chỉnh, chẳng hạn ký PDF và các route cấu hình PDF-sang-ảnh, dùng hợp đồng endpoint riêng thay vì route `/batch` tổng quát.
+
+Công cụ `ocr-pdf` hỗ trợ route `/batch` tổng quát này.
 
 ```bash
 curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
@@ -594,6 +596,8 @@ Các tham số truy vấn:
 
 Quản lý các bundle tính năng AI (cài đặt/gỡ cài đặt các gói mô hình AI trong môi trường Docker). Ưu tiên endpoint cài đặt ở cấp công cụ khi bật một công cụ từ tự động hóa tùy chỉnh: một số công cụ AI cần nhiều hơn một bundle dùng chung, và endpoint này bỏ qua các bundle đã cài đặt trong khi chỉ xếp hàng những bundle còn thiếu.
 
+OCR là một cải tiến tùy chọn thay vì phụ thuộc cứng. Cấp `fast` Tesseract của nó hoạt động mà không cần gói; `POST /api/v1/admin/features/ocr/install` cài đặt gói RapidOCR đã ký cho `balanced` và `best` trên Linux amd64 hoặc arm64. Thời gian chạy OCR chính xác sử dụng CPU trên máy chủ chỉ dành cho CPU và NVIDIA, đồng thời yêu cầu ít nhất 4 GiB bộ nhớ hiệu dụng (giới hạn vùng chứa cgroup được định cấu hình, nếu không thì bộ nhớ máy chủ). SnapOtter báo cáo lý do tương thích `requiredMemoryBytes`, `effectiveMemoryBytes` và `insufficient-memory`, đồng thời từ chối cài đặt không tương thích trước khi tải xuống. Yêu cầu bộ nhớ này không áp dụng cho `fast`. Gói này có khoảng 208-234 MiB để tải xuống và 409-488 MiB được cài đặt, tùy thuộc vào mục tiêu; chỉ mục đã ký liên kết các kích thước chính xác được thực thi trong quá trình cài đặt.
+
 | Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
 |--------|------|--------|-------------|
 | `GET` | `/api/v1/features` | Xác thực | Liệt kê tất cả bundle tính năng và trạng thái cài đặt của chúng |
@@ -601,7 +605,18 @@ Quản lý các bundle tính năng AI (cài đặt/gỡ cài đặt các gói m
 | `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Cài đặt mọi bundle mà một công cụ cần; trả về trạng thái đã xếp hàng/đã bỏ qua theo từng bundle |
 | `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Gỡ cài đặt một bundle tính năng và dọn dẹp các tệp mô hình |
 | `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Lấy tổng dung lượng đĩa của các mô hình AI |
-| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Nhập một kho lưu trữ bundle AI ngoại tuyến |
+| `POST` | `/api/v1/admin/features/import` | Quản trị viên (`features:manage`) | Nhập gói AI kế thừa (`file`) hoặc bản phát hành OCR ngoại tuyến đã ký (`index` cộng với `archive`) |
+
+Quá trình nhập OCR được air-gapped phải bao gồm `ocr-runtime-index.json` đã ký của bản phát hành và kho lưu trữ nền tảng phù hợp. SnapOtter áp dụng cùng chữ ký Ed25519, hàm băm giả, khả năng tương thích, trích xuất và kiểm tra khói được sử dụng trong quá trình cài đặt trực tuyến:
+
+```bash
+curl -X POST http://localhost:1349/api/v1/admin/features/import \
+  -H "Authorization: Bearer <admin-token>" \
+  -F "index=@ocr-runtime-index.json" \
+  -F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
+```
+
+Sử dụng kho lưu trữ `linux-arm64-cpu-py311` trên arm64. Một tạo phẩm đã được ký cho một mục tiêu khác sẽ bị từ chối thay vì được cài đặt.
 
 ## Thao tác quản trị {#admin-operations}