description:"Tài liệu tham khảo engine AI với tất cả công cụ ML chạy cục bộ. Xóa nền, upscale, OCR, phát hiện khuôn mặt, phục chế ảnh và nhiều tính năng khác."
Gói `@snapotter/ai` điều phối các công cụ gốc và thời gian chạy Python cho các hoạt động ML cục bộ. Hầu hết các công cụ ML đều sử dụng Python sidecar bền bỉ để khởi động ấm nhanh. OCR được cố ý tách biệt: `fast` gọi mã nhị phân Tesseract gốc, trong khi `balanced` và `best` sử dụng JSONL dispatcher liên tục chuyên dụng được ghim vào thế hệ RapidOCR bất biến đang hoạt động trong `/data/ai/v3`. Mỗi yêu cầu chứa một generation lease. Trong quá trình nâng cấp, SnapOtter chạy smoke test trên ứng viên trước khi kích hoạt, chuyển nguyên tử sang dispatcher mới, sau đó loại bỏ thế hệ cũ trước garbage collection.
NVIDIA CUDA được tự động phát hiện và sử dụng bởi các thời gian chạy hỗ trợ nó. OCR sử dụng CPU trên mọi máy chủ, bao gồm cả các hệ thống có GPU NVIDIA, tránh CUDA và khớp nối trình điều khiển cho công cụ này.
Hiện chưa hỗ trợ tăng tốc iGPU Intel/AMD qua VA-API, Quick Sync hay OpenCL cho suy luận AI. Việc ánh xạ `/dev/dri` vào container không tăng tốc các công cụ sidecar Python này trừ khi có một GPU NVIDIA hỗ trợ CUDA.
19 công cụ AI sidecar Python trên bốn phương thức (ảnh, âm thanh, video, tài liệu), cộng thêm 2 công cụ có khả năng AI tùy chọn. Mọi mô hình đều chạy cục bộ, không cần internet sau khi tải mô hình lần đầu.
OCR Nhanh hỗ trợ `auto`, `en`, `de`, `es`, `fr`, `zh` và `ja`, nhưng không hỗ trợ tiếng Hàn (`ko`). Tiếng Hàn cần gói OCR Chính xác và `balanced` hoặc `best`. Gói chạy trên container Linux amd64 và arm64 chính thức, kể cả máy chủ NVIDIA nơi OCR vẫn chạy bằng CPU. Hệ thống không được hỗ trợ sẽ trả về lỗi tương thích rõ ràng và không âm thầm chuyển về `fast`. Tiếng Hàn với `fast` hoặc bí danh cũ `tesseract` bị từ chối trước khi xếp hàng với `FEATURE_INCOMPATIBLE` và `fast-korean-unsupported`.
Một hồ sơ dispatcher "docs" riêng thay thế danh sách cho phép AI bằng các script xử lý tài liệu (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) và bỏ qua việc import các thư viện ML nặng.
**Thời gian chờ:** mặc định 300 giây; OCR và xóa nền BiRefNet được cấp 600 giây.
## Gói tính năng {#feature-bundles}
Các mô hình AI được đóng gói theo ngăn xếp phụ thuộc dùng chung, không phải một kho lưu trữ cho mỗi công cụ. Một gói tính năng có thể bật nhiều công cụ khi chúng dùng cùng họ mô hình, wheel Python hoặc thư viện native. Điều này giúp image Docker phát hành nhỏ hơn và tránh lưu trữ các bản sao trùng lặp của cùng một mô hình matting nền, phát hiện khuôn mặt, OCR, phục chế và giọng nói.
Image Docker đi kèm ứng dụng cộng với runtime chung. Các kho lưu trữ mô hình lớn được tải theo yêu cầu vào volume `/data/ai` thường trực, rồi được tái sử dụng bởi mọi công cụ cần đến. Nếu một gói đã được cài vì công cụ khác cần, thì việc bật một công cụ phụ thuộc mới sẽ không tải lại gói đó.
Hầu hết các công cụ AI đều yêu cầu một hoặc nhiều gói tính năng trước khi chúng có thể chạy. Giao diện người dùng quản trị viên cài đặt chúng theo công cụ thông qua `POST /api/v1/admin/tools/:toolId/features/install`, giải quyết danh sách gói đầy đủ, bỏ qua các gói đã được cài đặt và chỉ xếp hàng các bản tải xuống bị thiếu. Ví dụ: bật Ảnh hộ chiếu trên hàng đợi phiên bản mới `background-removal` và `face-detection`; kích hoạt nó sau khi loại bỏ nền đã được cài đặt chỉ xếp hàng `face-detection`. OCR là ngoại lệ vì `fast` không cần gói; cài đặt thời gian chạy chính xác tùy chọn thông qua UI hoặc `POST /api/v1/admin/features/ocr/install`.
| `transcription` | ~600 MB | mô hình chuyển giọng nói thành văn bản faster-whisper | transcribe-audio, auto-subtitles |
Các công cụ có phụ thuộc chéo giữa nhiều gói:
| Công cụ | Gói yêu cầu | Lý do |
|------|------------------|-----|
| `passport-photo` | `background-removal`, `face-detection` | Xóa nền, rồi dùng mốc điểm khuôn mặt để căn khung cắt theo quy tắc ảnh hộ chiếu và ảnh thẻ. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Phát hiện khuôn mặt trước khi chạy tăng cường GFPGAN hoặc CodeFormer trên các vùng khuôn mặt đã chọn. |
Một công cụ chỉ khả dụng khi tất cả các gói yêu cầu của nó được cài đặt, ngoại trừ OCR: tầng `fast` tích hợp của nó vẫn khả dụng mà không cần gói OCR tùy chọn. Các lượt cài đặt một phần là hợp lệ và được xử lý tăng dần: các gói đã cài đặt được sử dụng lại, các gói bị thiếu được hiển thị dưới dạng tải xuống và các lượt cài đặt trong hàng đợi chạy lần lượt để môi trường Python dùng chung không bị sửa đổi đồng thời.
### Cài đặt thời gian chạy OCR chính xác {#accurate-ocr-runtime-installation}
Gói OCR chính xác là thời gian chạy dành riêng cho nền tảng cho vùng chứa Linux amd64 hoặc Linux arm64 chính thức. Bản dựng amd64 sử dụng Python 3.12; bản dựng arm64 sử dụng Python 3.11. Cả hai bản dựng đều chạy RapidOCR thông qua `CPUExecutionProvider` của ONNX Runtime, do đó, gói tương tự chỉ hoạt động trên các máy chủ chỉ dành cho CPU và NVIDIA Docker. Thời gian chạy chính xác yêu cầu ít nhất 4 GiB bộ nhớ hiệu dụng: giới hạn cgroup của vùng chứa được định cấu hình, nếu không thì bộ nhớ máy chủ. Hệ thống có mức độ tương thích tối thiểu đã được ký sẽ bị từ chối trước khi tải xuống. Yêu cầu này không áp dụng cho OCR nhanh được tích hợp sẵn. Các bản dựng Bare-metal bị từ chối vì libc và Python ABI của chúng không thể được suy ra một cách an toàn; OCR nhanh vẫn khả dụng khi máy chủ cung cấp Tesseract và Ghostscript.
Tạo phẩm tùy chọn có khoảng 208-234 MiB được nén và 409-488 MiB được trích xuất, tùy thuộc vào kiến trúc. Chỉ mục đã ký liên kết số byte được nén và trích xuất chính xác được thực thi bởi trình cài đặt. Tesseract tích hợp thêm khoảng 25 MiB vào hình ảnh chính thức và không cần tệp trong `/data/ai`.
Cài đặt trực tuyến tìm nạp chỉ mục phát hành đã ký và tạo phẩm có địa chỉ nội dung chính xác cho nền tảng hiện tại. SnapOtter xác minh chữ ký chỉ mục Ed25519, kích thước tạo phẩm, thông báo SHA-256, thông báo mô hình, đường dẫn, chế độ tệp và smoke test theo giai đoạn trước khi kích hoạt thế hệ mới một cách nguyên tử. Cài đặt không thành công sẽ khiến thế hệ khỏe mạnh trước đó hoạt động.
Để cài đặt air-gapped, hãy tải cả `ocr-runtime-index.json` của bản phát hành và kho lưu trữ thời gian chạy OCR phù hợp lên `POST /api/v1/admin/features/import` bằng cách sử dụng các trường nhiều phần có tên `index` và `archive`. Nhập ngoại tuyến áp dụng các kiểm tra chữ ký, hàm băm, trích xuất, tính tương thích và kiểm tra khói giống như cài đặt trực tuyến; một kho lưu trữ không có chỉ mục được ký đáng tin cậy sẽ bị từ chối.
**Mẫu mã:** Tesseract (`fast`); RapidOCR với các mẫu nhỏ PP-OCRv6 (`balanced`); Các mô hình trung bình PP-OCRv6 có tính năng chấm điểm biến thể đã hiệu chỉnh (`best`)
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Năng động | Khi bỏ qua `quality` và `engine`, SnapOtter chọn cấp tốt nhất hiện có theo thứ tự `best`, `balanced`, `fast`. Với tiếng Hàn, hệ thống không bao giờ chọn `fast`; hệ thống dùng `best`, sau đó `balanced`, hoặc trả về lỗi cài đặt hay tương thích của runtime chính xác. |
| `enhance` | boolean | Phụ thuộc vào cấp bậc | Cải thiện độ tương phản cục bộ Nhanh chóng áp dụng nó trực tiếp; các cấp chính xác chỉ giữ lại biến thể khi tính điểm đã hiệu chỉnh cải thiện OCR. Bật mặc định cho Tốt nhất |
| `engine` | sợi dây | - | Bí danh tương thích không được dùng nữa. Ánh xạ `tesseract` tới `fast` và giá trị `paddleocr` kế thừa thành `balanced`; nó không tải PaddlePaddle |
Trả về văn bản được trích xuất cùng với siêu dữ liệu xuất xứ: công cụ, chất lượng thực tế và được yêu cầu, thiết bị, nhà cung cấp, trạng thái xuống cấp, cảnh báo và phiên bản mô hình/thời gian chạy chính xác khi có thể. Yêu cầu chất lượng rõ ràng không bao giờ rơi vào cấp độ khác. Nếu `balanced` hoặc `best` không khả dụng thì API trả về `FEATURE_NOT_INSTALLED` hoặc `FEATURE_INCOMPATIBLE` thay vì chạy `fast` âm thầm.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Năng động | Khi bỏ qua `quality` và `engine`, SnapOtter chọn cấp tốt nhất hiện có theo thứ tự `best`, `balanced`, `fast`. Với tiếng Hàn, hệ thống không bao giờ chọn `fast`; hệ thống dùng `best`, sau đó `balanced`, hoặc trả về lỗi cài đặt hay tương thích của runtime chính xác. |
| `enhance` | boolean | Phụ thuộc vào cấp bậc | Cải thiện độ tương phản cục bộ Nhanh chóng áp dụng nó trực tiếp; các cấp chính xác chỉ giữ lại biến thể khi tính điểm đã hiệu chỉnh cải thiện OCR. Bật mặc định cho Tốt nhất |
| `engine` | sợi dây | - | Bí danh tương thích không được dùng nữa. Ánh xạ `tesseract` tới `fast` và giá trị `paddleocr` kế thừa thành `balanced`; nó không tải PaddlePaddle |
Quy tắc không hạ cấp tương tự áp dụng cho PDF OCR. Các trang PDF được rasterized trước khi nhận dạng và một yêu cầu có thể chọn tối đa 50 trang.
| `maxFileSizeKb` | number | `0` | Kích thước tệp tối đa tính bằng KB (0 = không giới hạn) |
| `dpi` | number (72-1200) | `300` | DPI đầu ra |
| `customWidthMm` | number | - | Chiều rộng tùy chỉnh tính bằng mm (ghi đè thông số quốc gia) |
| `customHeightMm` | number | - | Chiều cao tùy chỉnh tính bằng mm (ghi đè thông số quốc gia) |
| `zoom` | number (0.5-3) | `1` | Hệ số thu phóng |
| `adjustX` | number | `0` | Điều chỉnh vị trí ngang |
| `adjustY` | number | `0` | Điều chỉnh vị trí dọc |
| `landmarks` | object | (bắt buộc) | Mốc điểm từ Giai đoạn 1 |
| `imageWidth` | number | (bắt buộc) | Chiều rộng ảnh từ Giai đoạn 1 |
| `imageHeight` | number | (bắt buộc) | Chiều cao ảnh từ Giai đoạn 1 |
## Xóa vật thể (Inpainting) {#object-erasing-inpainting}
**Đường dẫn công cụ:**`erase-object`
**Mô hình:** LaMa qua ONNX Runtime
Mask được gửi dưới dạng **phần tệp thứ hai** (tên trường `mask`), không phải base64. Điểm ảnh trắng trong mask cho biết vùng cần xóa. Các thiết lập `format` và `quality` được gửi dưới dạng trường form cấp trên cùng.
| `format` | `"srt"` \| `"vtt"` | `"srt"` | Định dạng phụ đề đầu ra |
## Sửa độ trong suốt PNG {#png-transparency-fixer}
**Đường dẫn công cụ:**`transparency-fixer`
**Mô hình:** BiRefNet HR-matting (độ phân giải 2048x2048)
Sửa các PNG "trong suốt giả", nơi nền đã được xóa nhưng để lại viền tua, quầng sáng hoặc phần dư bán trong suốt. Dùng mô hình matting độ phân giải cao của BiRefNet để tạo kênh alpha sạch, rồi áp dụng xử lý khử viền có thể cấu hình để loại bỏ nhiễm màu dọc theo cạnh.
**Chuỗi dự phòng khi hết bộ nhớ:** Nếu BiRefNet HR-matting vượt quá bộ nhớ khả dụng, công cụ tự động chuyển sang dự phòng `birefnet-general`, rồi đến `u2net`.
| Tham số | Kiểu | Mặc định | Mô tả |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Cường độ khử viền để loại bỏ nhiễm màu ở cạnh |
| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Định dạng ảnh đầu ra |
| `removeWatermark` | boolean | `false` | Áp dụng tiền xử lý xóa hình mờ (bộ lọc trung vị) |
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
| `deepEnhance` | boolean | `false` | Bật khử nhiễu AI qua SCUNet (yêu cầu gói `upscale-enhance`) |
Một endpoint phân tích bổ sung có tại `POST /api/v1/tools/image/image-enhancement/analyze`, trả về các chỉnh sửa được phát hiện mà không áp dụng chúng.
### Đổi kích thước theo nội dung (Seam Carving) {#content-aware-resize-seam-carving}
**Đường dẫn công cụ:**`content-aware-resize`
**Engine:** binary Go `caire` (không phải Python, không hưởng lợi từ GPU)
Đổi kích thước ảnh một cách thông minh bằng cách loại bỏ các đường nối năng lượng thấp, giữ lại nội dung quan trọng.
| Tham số | Kiểu | Mặc định | Mô tả |
|-----------|------|---------|-------------|
| `width` | number | - | Chiều rộng đích |
| `height` | number | - | Chiều cao đích |
| `protectFaces` | boolean | `false` | Bảo vệ vùng khuôn mặt đã phát hiện (yêu cầu gói `face-detection`) |
| `blurRadius` | number (0-20) | `4` | Làm mờ trước để tính năng lượng |
| `sobelThreshold` | number (1-20) | `2` | Ngưỡng độ nhạy cạnh |
| `square` | boolean | `false` | Buộc đầu ra vuông |
