Search K
Tài liệu tham khảo Engine AI
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.
Khả năng tương thích OCR tiếng Hàn
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.
Kiến trúc
Node.js Tool Route
|
v
@snapotter/ai bridge.ts
| (stdin/stdout JSON + stderr progress events)
v
+-- Native Tesseract + Ghostscript (fast image/PDF OCR)
|
+-- Isolated OCR runtime (persistent JSONL dispatcher)
| `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
|
`-- Python dispatcher (persistent process, "ai" profile)
|
|-- remove_bg.py (rembg / BiRefNet)
|-- upscale.py (RealESRGAN)
|-- inpaint.py (LaMa ONNX)
|-- outpaint.py (LaMa canvas expansion)
|-- detect_faces.py (MediaPipe)
|-- face_landmarks.py (MediaPipe landmarks)
|-- enhance_faces.py (GFPGAN / CodeFormer)
|-- colorize.py (DDColor)
|-- noise_removal.py (SCUNet / tiered denoising)
|-- red_eye_removal.py (landmark + color analysis)
|-- restore.py (scratch repair + enhancement + denoising)
|-- transcribe.py (faster-whisper speech-to-text)
+-- install_feature.py (on-demand bundle installer)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
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.
| Gói | Kích thước | Nhóm phụ thuộc dùng chung | Công cụ sử dụng |
|---|---|---|---|
background-removal | 4-5 GB | matting nền rembg / BiRefNet | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
face-detection | 200-300 MB | phát hiện khuôn mặt và mốc điểm MediaPipe | blur-faces, red-eye-removal, smart-crop |
object-eraser-colorize | 1-2 GB | inpainting/outpainting LaMa và DDColor | erase-object, colorize, ai-canvas-expand |
upscale-enhance | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, khử nhiễu | upscale, enhance-faces, noise-removal |
photo-restoration | 4-5 GB | quy trình sửa vết xước và phục chế | restore-photo |
ocr | ~208-234 Tải xuống MiB / ~409-488 MiB đã cài đặt | Tùy chọn RapidOCR 3.9.1, ONNX Runtime 1.20.1 và các mẫu PP-OCR được ghim | ocr, ocr-pdf (chỉ balanced và best) |
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
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.
Xóa nền
Đường dẫn công cụ: remove-background
Mô hình: rembg với BiRefNet (mặc định) hoặc các biến thể U2-Net
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
model | string | - | Biến thể mô hình (ghi đè tùy chọn) |
backgroundType | string | "transparent" | Một trong: transparent, color, gradient, blur, image |
backgroundColor | string | - | Mã màu hex cho nền đơn sắc |
gradientColor1 | string | - | Màu gradient thứ nhất |
gradientColor2 | string | - | Màu gradient thứ hai |
gradientAngle | number | - | Góc gradient tính bằng độ |
blurEnabled | boolean | - | Bật hiệu ứng làm mờ nền |
blurIntensity | number (0-100) | - | Cường độ làm mờ |
shadowEnabled | boolean | - | Bật đổ bóng lên chủ thể |
shadowOpacity | number (0-100) | - | Độ mờ đục của bóng |
outputFormat | string | - | Định dạng đầu ra: png, webp hoặc avif |
edgeRefine | integer (0-3) | - | Mức độ tinh chỉnh cạnh |
decontaminate | boolean | - | Loại bỏ lem màu ở cạnh |
Thay nền
Đường dẫn công cụ: background-replace
Mô hình: rembg / BiRefNet (dùng chung với remove-background)
Xóa nền và thay bằng màu đơn sắc hoặc gradient.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
backgroundType | "color" | "gradient" | "color" | Chế độ nền |
color | string | "#ffffff" | Màu nền hex (khi backgroundType là color) |
gradientColor1 | string | - | Màu hex gradient thứ nhất |
gradientColor2 | string | - | Màu hex gradient thứ hai |
gradientAngle | integer (0-360) | 180 | Góc gradient tính bằng độ |
feather | integer (0-20) | 0 | Bán kính làm mềm cạnh |
format | "png" | "webp" | "png" | Định dạng đầu ra |
Làm mờ nền
Đường dẫn công cụ: blur-background
Mô hình: rembg / BiRefNet (dùng chung với remove-background)
Làm mờ nền trong khi giữ chủ thể sắc nét.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
intensity | integer (1-100) | 50 | Cường độ làm mờ |
feather | integer (0-20) | 0 | Bán kính làm mềm cạnh |
format | "png" | "webp" | "png" | Định dạng đầu ra |
Upscale ảnh
Đường dẫn công cụ: upscale
Mô hình: RealESRGAN (dự phòng Lanczos khi không có sẵn)
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
scale | number | 2 | Hệ số upscale |
model | string | "auto" | Biến thể mô hình |
faceEnhance | boolean | false | Áp dụng lượt tăng cường khuôn mặt GFPGAN |
denoise | number | 0 | Cường độ khử nhiễu |
format | string | "auto" | Ghi đè định dạng đầu ra |
quality | number | 95 | Chất lượng đầu ra (1-100) |
OCR / Trích xuất văn bản
Đường dẫn công cụ: ocr
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)
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
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. |
language | string | "auto" | Ngôn ngữ: auto, en, de, fr, es, zh, ja, ko |
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.
OCR PDF
Đường dẫn công cụ: ocr-pdf
Mô hình: Cùng hệ thống bậc như OCR ảnh
Trích xuất văn bản từ tài liệu PDF đã quét bằng OCR chạy trên AI, theo từng trang.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
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. |
language | string | "auto" | Ngôn ngữ: auto, en, de, fr, es, zh, ja, ko |
pages | string | "all" | Chọn trang: "all", "1-3", "1,3,5" |
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.
Làm mờ khuôn mặt / PII
Đường dẫn công cụ: blur-faces
Mô hình: phát hiện khuôn mặt MediaPipe
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
blurRadius | number (1-100) | 30 | Bán kính làm mờ Gaussian |
sensitivity | number (0-1) | 0.5 | Ngưỡng tin cậy phát hiện |
Tăng cường khuôn mặt
Đường dẫn công cụ: enhance-faces
Mô hình: GFPGAN, CodeFormer
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
model | "auto" | "gfpgan" | "codeformer" | "auto" | Mô hình tăng cường |
strength | number (0-1) | 0.8 | Cường độ tăng cường |
sensitivity | number (0-1) | 0.5 | Ngưỡng phát hiện khuôn mặt |
onlyCenterFace | boolean | false | Chỉ tăng cường khuôn mặt ở trung tâm nhất |
Tô màu bằng AI
Đường dẫn công cụ: colorize
Mô hình: DDColor (dự phòng OpenCV DNN)
Chuyển ảnh đen trắng hoặc thang xám thành ảnh màu đầy đủ.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
intensity | number (0-1) | 1.0 | Cường độ bão hòa màu |
model | "auto" | "ddcolor" | "opencv" | "auto" | Biến thể mô hình |
Khử nhiễu
Đường dẫn công cụ: noise-removal
Mô hình: SCUNet (quy trình khử nhiễu phân bậc)
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
tier | "quick" | "balanced" | "quality" | "maximum" | "balanced" | Bậc xử lý |
strength | number (0-100) | 50 | Cường độ khử nhiễu |
detailPreservation | number (0-100) | 50 | Mức chi tiết cần giữ lại; cao hơn thì giữ nhiều kết cấu hơn |
colorNoise | number (0-100) | 30 | Cường độ giảm nhiễu màu |
format | string | "original" | Định dạng đầu ra: original, png, jpeg, webp, avif, jxl |
quality | number (1-100) | 90 | Chất lượng mã hóa đầu ra |
Xóa mắt đỏ
Đường dẫn công cụ: red-eye-removal
Phát hiện mốc điểm khuôn mặt, xác định vùng mắt và chỉnh việc kênh đỏ bị bão hòa quá mức.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
sensitivity | number (0-100) | 50 | Ngưỡng phát hiện điểm ảnh đỏ |
strength | number (0-100) | 70 | Cường độ chỉnh sửa |
format | string | - | Ghi đè định dạng đầu ra (tùy chọn) |
quality | number (1-100) | 90 | Chất lượng đầu ra |
Phục chế ảnh
Đường dẫn công cụ: restore-photo
Quy trình nhiều bước cho ảnh cũ hoặc hư hỏng: phát hiện và sửa vết xước/rách, tăng cường khuôn mặt, khử nhiễu và tô màu tùy chọn.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
scratchRemoval | boolean | true | Phát hiện và sửa vết xước, vết rách |
faceEnhancement | boolean | true | Áp dụng lượt tăng cường khuôn mặt |
fidelity | number (0-1) | 0.7 | Cường độ tăng cường khuôn mặt (cao hơn = thận trọng hơn) |
denoise | boolean | true | Áp dụng lượt khử nhiễu |
denoiseStrength | number (0-100) | 25 | Cường độ khử nhiễu |
colorize | boolean | false | Tô màu sau khi phục chế |
colorizeStrength | number (0-100) | 85 | Cường độ tô màu |
Ảnh hộ chiếu
Đường dẫn công cụ: passport-photo
Mô hình: mốc điểm khuôn mặt MediaPipe + xóa nền BiRefNet
Quy trình hai giai đoạn: phân tích (phát hiện khuôn mặt + xóa nền) rồi tạo (cắt, đổi kích thước, xếp lưới). Hỗ trợ hơn 37 quốc gia trên 6 khu vực.
Giai đoạn 1: Phân tích
POST /api/v1/tools/image/passport-photo/analyze
Nhận một tệp ảnh (multipart). Trả về dữ liệu mốc điểm khuôn mặt, bản xem trước base64 và kích thước ảnh.
Giai đoạn 2: Tạo
POST /api/v1/tools/image/passport-photo/generate
Nhận một body JSON gồm kết quả Giai đoạn 1 cộng với các thiết lập tạo:
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
jobId | string | (bắt buộc) | ID công việc từ Giai đoạn 1 |
filename | string | (bắt buộc) | Tên tệp gốc từ Giai đoạn 1 |
countryCode | string | (bắt buộc) | Mã quốc gia ISO (ví dụ US, GB, IN) |
documentType | string | "passport" | Loại giấy tờ |
bgColor | string | "#FFFFFF" | Mã hex màu nền |
printLayout | string | "none" | Bố cục in: none, 4x6, a4, letter |
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)
Đườ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.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
file | file | (bắt buộc) | Ảnh nguồn (multipart) |
mask | file | (bắt buộc) | Ảnh mask (multipart, tên trường mask, trắng = xóa) |
format | string | "auto" | Định dạng đầu ra: auto, png, jpg, jpeg, webp, tiff, gif, avif, heic, heif, jxl |
quality | integer (1-100) | 95 | Chất lượng đầu ra |
Tăng tốc CUDA khi có GPU NVIDIA.
Mở rộng khung ảnh bằng AI
Đường dẫn công cụ: ai-canvas-expand
Mô hình: outpainting dựa trên LaMa
Mở rộng khung của một ảnh theo bất kỳ hướng nào và điền vào các vùng mới bằng nội dung do AI tạo ra khớp với ảnh hiện có.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
extendTop | integer | 0 | Số điểm ảnh mở rộng ở phía trên |
extendRight | integer | 0 | Số điểm ảnh mở rộng ở phía phải |
extendBottom | integer | 0 | Số điểm ảnh mở rộng ở phía dưới |
extendLeft | integer | 0 | Số điểm ảnh mở rộng ở phía trái |
tier | "fast" | "balanced" | "high" | "balanced" | Bậc chất lượng |
format | string | "auto" | Định dạng đầu ra: auto, png, jpg, jpeg, webp, tiff, gif, avif, heic, heif, jxl |
quality | integer (1-100) | 95 | Chất lượng đầu ra |
Ít nhất một hướng mở rộng phải lớn hơn 0.
Cắt thông minh
Đường dẫn công cụ: smart-crop
Mô hình: phát hiện khuôn mặt MediaPipe (chỉ ở chế độ khuôn mặt)
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
mode | string | "subject" | Chiến lược cắt: subject, face, trim |
strategy | "attention" | "entropy" | "attention" | Chiến lược cho chế độ chủ thể |
width | integer | - | Chiều rộng đầu ra |
height | integer | - | Chiều cao đầu ra |
padding | integer (0-50) | 0 | Phần trăm đệm quanh chủ thể |
facePreset | string | "head-shoulders" | Khung định sẵn khi mode=face |
sensitivity | number (0-1) | 0.5 | Ngưỡng phát hiện khuôn mặt |
threshold | integer (0-255) | 30 | Ngưỡng phát hiện nền (chế độ cắt viền) |
padToSquare | boolean | false | Đệm kết quả đã cắt viền thành hình vuông |
padColor | string | "#ffffff" | Màu nền cho phần đệm vuông |
targetSize | integer | - | Kích thước đích cho đầu ra đã đệm (điểm ảnh) |
quality | integer (1-100) | - | Chất lượng đầu ra |
Các giá trị mode cũ attention và content vẫn được chấp nhận và ánh xạ lần lượt sang subject và trim.
Khung định sẵn cho khuôn mặt:
| Định sẵn | Phù hợp nhất cho |
|---|---|
closeup | Ảnh chân dung cận |
head-shoulders | Ảnh hồ sơ |
upper-body | LinkedIn / trang trọng |
half-body | Toàn bộ nửa thân trên |
Chuyển âm thanh thành văn bản
Đường dẫn công cụ: transcribe-audio
Mô hình: faster-whisper
Chuyển giọng nói thành văn bản. Hỗ trợ định dạng đầu ra văn bản thuần, SRT và VTT.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
language | string | "auto" | Ngôn ngữ: auto, en, de, fr, es, zh, ja, ko, id, th, vi |
outputFormat | "txt" | "srt" | "vtt" | "txt" | Định dạng đầu ra |
Phụ đề tự động
Đường dẫn công cụ: auto-subtitles
Mô hình: faster-whisper (trích âm thanh từ video, rồi chuyển thành văn bản)
Tạo tệp phụ đề từ track âm thanh của video.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
language | string | "auto" | Ngôn ngữ: auto, en, de, fr, es, zh, ja, ko, id, th, vi |
format | "srt" | "vtt" | "srt" | Định dạng phụ đề đầu ra |
Sửa độ trong suốt PNG
Đườ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 \
-H "Authorization: Bearer <token>" \
-F "file=@fake-transparent.png" \
-F 'settings={"defringe":30,"outputFormat":"png"}'Công cụ có khả năng AI tùy chọn
Các công cụ sau không phải công cụ sidecar Python nhưng dùng tính năng AI khi bật một số tùy chọn.
Tăng cường ảnh
Đường dẫn công cụ: image-enhancement
Engine: Dựa trên phân tích (biểu đồ histogram và thống kê Sharp)
Phân tích ảnh và áp dụng chỉnh sửa tự động cho phơi sáng, tương phản, cân bằng trắng, độ bão hòa, độ nét và nhiễu. Hỗ trợ các chế độ theo cảnh cụ thể.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
mode | "auto" | "portrait" | "landscape" | "low-light" | "food" | "document" | "auto" | Chế độ cảnh để tinh chỉnh việc chỉnh sửa |
intensity | number (0-100) | 50 | Cường độ chỉnh sửa tổng thể |
corrections.exposure | boolean | true | Áp dụng chỉnh phơi sáng |
corrections.contrast | boolean | true | Áp dụng chỉnh tương phản |
corrections.whiteBalance | boolean | true | Áp dụng chỉnh cân bằng trắng |
corrections.saturation | boolean | true | Áp dụng chỉnh độ bão hòa |
corrections.sharpness | boolean | true | Áp dụng chỉnh độ nét |
corrections.denoise | boolean | true | Áp dụng khử nhiễu |
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)
Đườ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 |