此頁面為機器翻譯。發現錯誤了嗎?協助我們改善。
Skip to content

AI 引擎參考

@snapotter/ai 套件協調本機工具和 Python 運行時以進行本機 ML 操作。 大多數 ML 工具使用持久的 Python sidecar 來實現快速熱啟動。 OCR 是故意分開的: fast 呼叫本機 Tesseract 二進位文件, 儘管 balancedbest 使用專用的持久化 JSONL dispatcher 固定到活動的不可變的 RapidOCR 新一代 /data/ai/v3。 每個請求都包含一個 generation lease。 在升級期間,SnapOtter 在啟動之前在候選者上運行 smoke test,自動切換到新的 dispatcher,然後在 garbage collection 之前耗盡舊代。

NVIDIA CUDA 由支援它的運行時自動檢測和使用。 OCR 在每個主機上使用 CPU,包括具有 NVIDIA GPU 的系統,避免 CUDA 和該工具的驅動程式耦合。

目前不支援透過 VA-API、Quick Sync 或 OpenCL 進行 Intel/AMD iGPU 的 AI 推論加速。除非有支援 CUDA 的 NVIDIA GPU 可用,否則將 /dev/dri 對映進容器並不會加速這些 Python sidecar 工具。

19 個 Python sidecar AI 工具,橫跨四種模態(image、audio、video、document),另有 2 個具備選用 AI 功能的工具。所有模型都在本機執行,初次下載模型後即不需要網際網路。

韓語 OCR 相容性

快速 OCR 支援 autoendeesfrzhja,但不支援韓語 (ko)。韓語需要精確 OCR 套件以及 balancedbest。此套件可在官方 Linux amd64 和 arm64 容器上執行;即使是 NVIDIA 主機,OCR 仍使用 CPU。不受支援的系統會傳回明確的相容性錯誤,絕不會靜默回退至 fast。韓語搭配 fast 或舊版 tesseract 別名時,會在排入佇列前以 FEATURE_INCOMPATIBLEfast-korean-unsupported 拒絕。

架構

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)

另有一個獨立的「docs」dispatcher 設定檔,以文件處理指令碼(doc_pagecountdoc_healthdoc_flattendoc_redactdoc_textdoc_to_worddoc_metadatadoc_html_pdf)取代 AI 允許清單,並略過大型 ML 匯入。

逾時: 預設 300 秒;OCR 與 BiRefNet 去背則為 600 秒。

功能套件包

AI 模型是依共用相依堆疊來封裝,而非每個工具一個封存檔。當多個工具使用相同的模型家族、Python wheel 或原生函式庫時,一個功能套件包可同時啟用這些工具。這讓發行的 Docker 映像更小,並避免重複儲存相同的背景去背、人臉偵測、OCR、修復與語音模型。

Docker 映像隨附應用程式加上共用執行環境。大型模型封存檔會在需要時下載到常駐的 /data/ai 磁碟區,之後由所有需要它的工具重複使用。如果某個套件包已因另一個工具的需要而安裝,啟用一個新的相依工具並不會再次下載該套件包。

大多數人工智慧工具都需要一個或多個功能包才能運作。 管理 UI 透過 POST /api/v1/admin/tools/:toolId/features/install 工具安裝這些包,它解析完整的捆綁包列表,跳過已安裝的捆綁包,並僅對缺少的下載進行排隊。 例如,在新實例佇列 background-removalface-detection 上啟用 Passport Photo; 在已安裝背景刪除後啟用它僅排隊 face-detection。 OCR 是例外,因為 fast 不需要包裝; 透過 UI 或 POST /api/v1/admin/features/ocr/install 安裝其選購的精確執行時間。

套件包大小共用相依群組使用它的工具
background-removal4-5 GBrembg / BiRefNet 背景去背remove-background、passport-photo、transparency-fixer、background-replace、blur-background
face-detection200-300 MBMediaPipe 人臉偵測與特徵點blur-faces、red-eye-removal、smart-crop
object-eraser-colorize1-2 GBLaMa 影像修補/外延與 DDColorerase-object、colorize、ai-canvas-expand
upscale-enhance5-6 GBRealESRGAN、GFPGAN / CodeFormer、去雜訊upscale、enhance-faces、noise-removal
photo-restoration4-5 GB刮痕修復與修復流程restore-photo
ocr~208-234 MiB 下載 / ~409-488 MiB 安裝選配 RapidOCR 3.9.1、ONNX Runtime 1.20.1 和固定 PP-OCR 型號ocr、ocr-pdf(僅限 balancedbest
transcription~600 MBfaster-whisper 語音轉文字模型transcribe-audio、auto-subtitles

具有跨套件包相依性的工具:

工具必要套件包原因
passport-photobackground-removalface-detection先移除背景,再用人臉特徵點依護照與身分證照片規則框住裁切範圍。
enhance-facesupscale-enhanceface-detection在對選定的人臉區域執行 GFPGAN 或 CodeFormer 增強之前,先偵測人臉。

只有在安裝了工具所需的所有捆綁包(OCR 除外)後,工具才可用:其內建 fast 層在沒有選購 OCR 包的情況下仍然可用。 部分安裝是有效的,並且是增量處理的:已安裝的捆綁包被重用,丟失的捆綁包顯示為下載,排隊安裝一次運行一個,因此共享的 Python 環境不會同時修改。

準確的 OCR 運行時安裝

準確的 OCR 套件是官方 Linux amd64 或 Linux arm64 容器的特定於平台的運行時。 amd64 建置使用 Python 3.12; arm64 版本使用 Python 3.11。 兩個版本都透過 ONNX Runtime 的 CPUExecutionProvider 運行 RapidOCR, 因此,相同的套件適用於僅 CPU 和 NVIDIA Docker 主機。 準確的運行時需要至少 4 GiB 的有效記憶體:配置的容器 cgroup 限制,否則為主機記憶體。 低於該簽章相容性最低值的系統在下載前會被拒絕。 此要求不適用於內建 Fast OCR。 Bare-metal 建置被拒絕,因為它們的 libc 和 Python ABI 無法安全推斷; 當主機提供 Tesseract 和 Ghostscript 時,快速 OCR 保持可用。

選用工件大約壓縮 208-234 MiB 並提取 409-488 MiB,具體取決於架構。 簽章索引綁定安裝程式強制執行的精確壓縮和提取位元組計數。 內建 Tesseract 在官方鏡像上增加了約25個 MiB,並且不需要/data/ai中的檔案。

線上安裝會取得已簽署的版本索引以及目前平台的精確內容尋址工件。 SnapOtter 在原子啟動新世代之前驗證 Ed25519 索引簽章、工件大小、SHA-256 摘要、模型摘要、路徑、檔案模式和暫存 smoke test。 失敗的安裝會使先前的健康生成保持活動狀態。

對於氣隙安裝,請使用名為 indexarchive 的多部分欄位將版本的 ocr-runtime-index.json 和相符的 OCR 執行時間存檔上傳到 POST /api/v1/admin/features/import。 離線導入應用與線上安裝相同的簽名、哈希、提取、相容性和冒煙測試檢查; 沒有可信任簽名索引的檔案將被拒絕。


去背

工具路由: remove-background
模型: rembg 搭配 BiRefNet(預設)或 U2-Net 變體

參數型別預設值說明
modelstring-模型變體(選用覆寫)
backgroundTypestring"transparent"其一:transparentcolorgradientblurimage
backgroundColorstring-純色背景的十六進位色碼
gradientColor1string-第一個漸層顏色
gradientColor2string-第二個漸層顏色
gradientAnglenumber-漸層角度(以度為單位)
blurEnabledboolean-啟用背景模糊效果
blurIntensitynumber (0-100)-模糊強度
shadowEnabledboolean-為主體啟用陰影
shadowOpacitynumber (0-100)-陰影不透明度
outputFormatstring-輸出格式:pngwebpavif
edgeRefineinteger (0-3)-邊緣細化等級
decontaminateboolean-移除邊緣的顏色滲色

背景替換

工具路由: background-replace
模型: rembg / BiRefNet(與 remove-background 共用)

移除背景並以純色或漸層取代。

參數型別預設值說明
backgroundType"color" | "gradient""color"背景模式
colorstring"#ffffff"背景十六進位色碼(當 backgroundTypecolor 時)
gradientColor1string-第一個漸層十六進位色碼
gradientColor2string-第二個漸層十六進位色碼
gradientAngleinteger (0-360)180漸層角度(以度為單位)
featherinteger (0-20)0邊緣羽化半徑
format"png" | "webp""png"輸出格式

模糊背景

工具路由: blur-background
模型: rembg / BiRefNet(與 remove-background 共用)

在保持主體清晰的同時模糊背景。

參數型別預設值說明
intensityinteger (1-100)50模糊強度
featherinteger (0-20)0邊緣羽化半徑
format"png" | "webp""png"輸出格式

影像放大

工具路由: upscale
模型: RealESRGAN(不可用時以 Lanczos 備援)

參數型別預設值說明
scalenumber2放大倍率
modelstring"auto"模型變體
faceEnhancebooleanfalse套用 GFPGAN 人臉增強處理
denoisenumber0去雜訊強度
formatstring"auto"輸出格式覆寫
qualitynumber95輸出品質(1-100)

OCR / 文字擷取

工具路由: ocr
型號: Tesseract (fast); RapidOCR 和 PP-OCRv6 小型型號(balanced); PP-OCRv6 具有校準變數評分的中等模型(best

參數型別預設值說明
quality"fast" | "balanced" | "best"動態的省略 qualityengine 時,SnapOtter 會依 bestbalancedfast 的順序選擇可用的最高品質層。韓語絕不會選擇 fast;它會使用 best,其次是 balanced,否則傳回精確執行階段的安裝或相容性錯誤。
languagestring"auto"語言:autoendefreszhjako
enhance布林值取決於層級提高局部對比。快速直接應用;僅當校準得分提高 OCR 時,準確的等級才會保留變體。預設為“最佳”
engine細繩-已棄用的兼容性別名。將 tesseract 對應到 fast,並將舊版 paddleocr 值對應到 balanced;它不載入 PaddlePaddle

傳回提取的文字以及來源元資料:引擎、請求的和實際的品質、設備、提供者、降級狀態、警告和準確的運行時/模型版本(如果適用)。 明確的品質要求永遠不會退回到另一層。 如果 balancedbest 不可用,則 API 傳回 FEATURE_NOT_INSTALLEDFEATURE_INCOMPATIBLE,而不是靜默執行 fast

PDF OCR

工具路由: ocr-pdf
模型: 與影像 OCR 相同的層級系統

使用 AI 驅動的 OCR,逐頁從掃描的 PDF 文件擷取文字。

參數型別預設值說明
quality"fast" | "balanced" | "best"動態的省略 qualityengine 時,SnapOtter 會依 bestbalancedfast 的順序選擇可用的最高品質層。韓語絕不會選擇 fast;它會使用 best,其次是 balanced,否則傳回精確執行階段的安裝或相容性錯誤。
languagestring"auto"語言:autoendefreszhjako
pagesstring"all"頁面選取:"all""1-3""1,3,5"
enhance布林值取決於層級提高局部對比。快速直接應用;僅當校準得分提高 OCR 時,準確的等級才會保留變體。預設為“最佳”
engine細繩-已棄用的兼容性別名。將 tesseract 對應到 fast,並將舊版 paddleocr 值對應到 balanced;它不載入 PaddlePaddle

同樣的不降級規則適用於 PDF OCR。 PDF 頁面在辨識前會進行光柵化處理,一次要求最多可以選擇50個頁面。

人臉 / PII 模糊

工具路由: blur-faces
模型: MediaPipe 人臉偵測

參數型別預設值說明
blurRadiusnumber (1-100)30高斯模糊半徑
sensitivitynumber (0-1)0.5偵測信賴度門檻

人臉增強

工具路由: enhance-faces
模型: GFPGAN、CodeFormer

參數型別預設值說明
model"auto" | "gfpgan" | "codeformer""auto"增強模型
strengthnumber (0-1)0.8增強強度
sensitivitynumber (0-1)0.5人臉偵測門檻
onlyCenterFacebooleanfalse只增強最靠近中央的人臉

AI 上色

工具路由: colorize
模型: DDColor(以 OpenCV DNN 備援)

將黑白或灰階相片轉換為全彩。

參數型別預設值說明
intensitynumber (0-1)1.0色彩飽和度強度
model"auto" | "ddcolor" | "opencv""auto"模型變體

去雜訊

工具路由: noise-removal
模型: SCUNet(分層去雜訊流程)

參數型別預設值說明
tier"quick" | "balanced" | "quality" | "maximum""balanced"處理層級
strengthnumber (0-100)50去雜訊強度
detailPreservationnumber (0-100)50要保留多少細節;數值越高保留越多紋理
colorNoisenumber (0-100)30色彩雜訊降低強度
formatstring"original"輸出格式:originalpngjpegwebpavifjxl
qualitynumber (1-100)90輸出編碼品質

紅眼移除

工具路由: red-eye-removal

偵測人臉特徵點、定位眼睛區域,並修正紅色通道的過飽和。

參數型別預設值說明
sensitivitynumber (0-100)50紅色像素偵測門檻
strengthnumber (0-100)70修正強度
formatstring-輸出格式覆寫(選用)
qualitynumber (1-100)90輸出品質

相片修復

工具路由: restore-photo

針對老舊或受損相片的多步驟流程:刮痕/撕裂偵測與修復、人臉增強、去雜訊,以及選用的上色。

參數型別預設值說明
scratchRemovalbooleantrue偵測並修復刮痕、撕裂
faceEnhancementbooleantrue套用人臉增強處理
fidelitynumber (0-1)0.7人臉增強強度(越高越保守)
denoisebooleantrue套用去雜訊處理
denoiseStrengthnumber (0-100)25去雜訊強度
colorizebooleanfalse修復後進行上色
colorizeStrengthnumber (0-100)85上色強度

證件照

工具路由: passport-photo
模型: MediaPipe 人臉特徵點 + BiRefNet 去背

兩階段工作流程:分析(偵測人臉 + 移除背景),接著產生(裁切、調整大小、平舖)。支援橫跨 6 個地區的 37+ 個國家。

階段 1:分析

POST /api/v1/tools/image/passport-photo/analyze

接受一個影像檔(multipart)。傳回人臉特徵點資料、一張 base64 預覽,以及影像尺寸。

階段 2:產生

POST /api/v1/tools/image/passport-photo/generate

接受一個 JSON 主體,內含階段 1 的結果加上產生設定:

參數型別預設值說明
jobIdstring(必填)來自階段 1 的 Job ID
filenamestring(必填)來自階段 1 的原始檔名
countryCodestring(必填)ISO 國家代碼(例如 USGBIN
documentTypestring"passport"文件類型
bgColorstring"#FFFFFF"背景顏色十六進位色碼
printLayoutstring"none"列印版面配置:none4x6a4letter
maxFileSizeKbnumber0檔案大小上限(KB)(0 = 無限制)
dpinumber (72-1200)300輸出 DPI
customWidthMmnumber-自訂寬度(mm)(覆寫國家規格)
customHeightMmnumber-自訂高度(mm)(覆寫國家規格)
zoomnumber (0.5-3)1縮放倍率
adjustXnumber0水平位置調整
adjustYnumber0垂直位置調整
landmarksobject(必填)來自階段 1 的特徵點
imageWidthnumber(必填)來自階段 1 的影像寬度
imageHeightnumber(必填)來自階段 1 的影像高度

物件擦除(影像修補)

工具路由: erase-object
模型: 透過 ONNX Runtime 的 LaMa

遮罩會以第二個檔案部分(欄位名稱 mask)傳送,而非以 base64。遮罩中的白色像素表示要擦除的區域。formatquality 設定會以頂層表單欄位傳送。

參數型別預設值說明
filefile(必填)來源影像(multipart)
maskfile(必填)遮罩影像(multipart,欄位名稱 mask,白色 = 擦除)
formatstring"auto"輸出格式:autopngjpgjpegwebptiffgifavifheicheifjxl
qualityinteger (1-100)95輸出品質

當有 NVIDIA GPU 可用時以 CUDA 加速。

AI 畫布擴展

工具路由: ai-canvas-expand
模型: 以 LaMa 為基礎的外延

朝任何方向擴展影像的畫布,並以與現有影像相符的 AI 生成內容填滿新增區域。

參數型別預設值說明
extendTopinteger0上方要延伸的像素數
extendRightinteger0右方要延伸的像素數
extendBottominteger0下方要延伸的像素數
extendLeftinteger0左方要延伸的像素數
tier"fast" | "balanced" | "high""balanced"品質層級
formatstring"auto"輸出格式:autopngjpgjpegwebptiffgifavifheicheifjxl
qualityinteger (1-100)95輸出品質

至少要有一個延伸方向大於 0。

智慧裁切

工具路由: smart-crop
模型: MediaPipe 人臉偵測(僅 face 模式)

參數型別預設值說明
modestring"subject"裁切策略:subjectfacetrim
strategy"attention" | "entropy""attention"subject 模式的策略
widthinteger-輸出寬度
heightinteger-輸出高度
paddinginteger (0-50)0主體周圍的留白百分比
facePresetstring"head-shoulders"mode=face 時的預設框取
sensitivitynumber (0-1)0.5人臉偵測門檻
thresholdinteger (0-255)30背景偵測門檻(trim 模式)
padToSquarebooleanfalse將修剪後的結果補齊為正方形
padColorstring"#ffffff"正方形補齊的背景顏色
targetSizeinteger-補齊輸出的目標尺寸(像素)
qualityinteger (1-100)-輸出品質

舊版 modeattentioncontent 仍被接受,並分別對映為 subjecttrim

人臉預設:

預設最適用於
closeup大頭照
head-shoulders個人檔案相片
upper-bodyLinkedIn / 正式
half-body完整上半身

音訊轉錄

工具路由: transcribe-audio
模型: faster-whisper

將語音轉換為文字。支援純文字、SRT 與 VTT 輸出格式。

參數型別預設值說明
languagestring"auto"語言:autoendefreszhjakoidthvi
outputFormat"txt" | "srt" | "vtt""txt"輸出格式

自動字幕

工具路由: auto-subtitles
模型: faster-whisper(先從影片擷取音訊,再進行轉錄)

從影片的音軌產生字幕檔。

參數型別預設值說明
languagestring"auto"語言:autoendefreszhjakoidthvi
format"srt" | "vtt""srt"輸出字幕格式

PNG 透明度修復

工具路由: transparency-fixer
模型: BiRefNet HR-matting(2048x2048 解析度)

修復「假透明」的 PNG,也就是背景已被移除但留下毛邊、光暈或半透明瑕疵的情況。使用 BiRefNet 的高解析度去背模型產生乾淨的 alpha 通道,接著套用可設定的去毛邊處理,以移除邊緣沿線的顏色汙染。

OOM 備援鏈: 若 BiRefNet HR-matting 超出可用記憶體,工具會自動退回 birefnet-general,然後退回 u2net

參數型別預設值說明
defringenumber (0-100)30用於移除顏色汙染的邊緣去毛邊強度
outputFormat"png" | "webp""png"輸出影像格式
removeWatermarkbooleanfalse套用浮水印移除前處理(中值濾波)
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"}'

具備選用 AI 功能的工具

以下工具並非 Python sidecar 工具,但在啟用特定選項時會使用 AI 功能。

影像增強

工具路由: image-enhancement
引擎: 以分析為基礎(Sharp 直方圖與統計)

分析影像並自動修正曝光、對比、白平衡、飽和度、銳利度與雜訊。支援特定場景模式。

參數型別預設值說明
mode"auto" | "portrait" | "landscape" | "low-light" | "food" | "document""auto"用於調校修正的場景模式
intensitynumber (0-100)50整體修正強度
corrections.exposurebooleantrue套用曝光修正
corrections.contrastbooleantrue套用對比修正
corrections.whiteBalancebooleantrue套用白平衡修正
corrections.saturationbooleantrue套用飽和度修正
corrections.sharpnessbooleantrue套用銳利度修正
corrections.denoisebooleantrue套用去雜訊
deepEnhancebooleanfalse透過 SCUNet 啟用 AI 去雜訊(需要 upscale-enhance 套件包)

另有一個分析端點位於 POST /api/v1/tools/image/image-enhancement/analyze,它會傳回偵測到的修正而不加以套用。

內容感知調整大小(接縫裁減)

工具路由: content-aware-resize
引擎: Go caire 二進位檔(非 Python,無 GPU 效益)

透過移除低能量接縫來智慧調整影像大小,保留重要內容。

參數型別預設值說明
widthnumber-目標寬度
heightnumber-目標高度
protectFacesbooleanfalse保護偵測到的人臉區域(需要 face-detection 套件包)
blurRadiusnumber (0-20)4能量計算的預先模糊
sobelThresholdnumber (1-20)2邊緣敏感度門檻
squarebooleanfalse強制正方形輸出