AI 引擎參考

@snapotter/ai 套件將 Node.js 橋接到一個常駐的 Python sidecar，用於所有 ML 操作。dispatcher 程序在兩次請求之間保持存活，以獲得快速的暖啟動效能。啟動時會自動偵測 NVIDIA CUDA，可用時即加以使用；否則 AI 工具會在 CPU 上執行。

目前不支援透過 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 功能的工具。所有模型都在本機執行，初次下載模型後即不需要網際網路。

架構

Node.js Tool Route
      |
      v
 @snapotter/ai bridge.ts
      | (stdin/stdout JSON + stderr progress events)
      v
 Python dispatcher (persistent process, "ai" profile)
      |
      |-- remove_bg.py        (rembg / BiRefNet)
      |-- upscale.py          (RealESRGAN)
      |-- inpaint.py          (LaMa ONNX)
      |-- outpaint.py         (LaMa canvas expansion)
      |-- ocr.py              (PaddleOCR / Tesseract)
      |-- ocr_pdf.py          (page-by-page document OCR)
      |-- ocr_preprocess.py   (image enhancement for OCR)
      |-- 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_pagecount、doc_health、doc_flatten、doc_redact、doc_text、doc_to_word、doc_metadata、doc_html_pdf）取代 AI 允許清單，並略過大型 ML 匯入。

逾時： 預設 300 秒；OCR 與 BiRefNet 去背則為 600 秒。

功能套件包

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

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

每個 AI 工具在能執行前都需要一個或多個功能套件包。管理員 UI 是依工具透過 POST /api/v1/admin/tools/:toolId/features/install 進行安裝，它會解析完整的套件包清單、略過已安裝的套件包，並只將缺少的下載排入佇列。舉例來說，在全新的執行個體上啟用 Passport Photo 會將 background-removal 與 face-detection 排入佇列；若在 Background Removal 已安裝後才啟用它，則只會將 face-detection 排入佇列。

套件包	大小	共用相依群組	使用它的工具
`background-removal`	4-5 GB	rembg / BiRefNet 背景去背	remove-background、passport-photo、transparency-fixer、background-replace、blur-background
`face-detection`	200-300 MB	MediaPipe 人臉偵測與特徵點	blur-faces、red-eye-removal、smart-crop
`object-eraser-colorize`	1-2 GB	LaMa 影像修補/外延與 DDColor	erase-object、colorize、ai-canvas-expand
`upscale-enhance`	5-6 GB	RealESRGAN、GFPGAN / CodeFormer、去雜訊	upscale、enhance-faces、noise-removal
`photo-restoration`	4-5 GB	刮痕修復與修復流程	restore-photo
`ocr`	5-6 GB	PaddleOCR / Tesseract OCR 堆疊	ocr、ocr-pdf
`transcription`	~600 MB	faster-whisper 語音轉文字模型	transcribe-audio、auto-subtitles

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

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

只有在工具所有必要套件包都已安裝時，該工具才可用。部分安裝是有效的，並以漸進方式處理：已安裝的套件包會重複使用、缺少的套件包顯示為待下載，而排入佇列的安裝會一次執行一個，以免共用的 Python 環境被同時修改。

去背

工具路由： remove-background
模型： rembg 搭配 BiRefNet（預設）或 U2-Net 變體

參數	型別	預設值	說明
`model`	string	-	模型變體（選用覆寫）
`backgroundType`	string	`"transparent"`	其一：`transparent`、`color`、`gradient`、`blur`、`image`
`backgroundColor`	string	-	純色背景的十六進位色碼
`gradientColor1`	string	-	第一個漸層顏色
`gradientColor2`	string	-	第二個漸層顏色
`gradientAngle`	number	-	漸層角度（以度為單位）
`blurEnabled`	boolean	-	啟用背景模糊效果
`blurIntensity`	number (0-100)	-	模糊強度
`shadowEnabled`	boolean	-	為主體啟用陰影
`shadowOpacity`	number (0-100)	-	陰影不透明度
`outputFormat`	string	-	輸出格式：`png`、`webp` 或 `avif`
`edgeRefine`	integer (0-3)	-	邊緣細化等級
`decontaminate`	boolean	-	移除邊緣的顏色滲色

背景替換

工具路由： background-replace
模型： rembg / BiRefNet（與 remove-background 共用）

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

參數	型別	預設值	說明
`backgroundType`	`"color"` \| `"gradient"`	`"color"`	背景模式
`color`	string	`"#ffffff"`	背景十六進位色碼（當 `backgroundType` 為 `color` 時）
`gradientColor1`	string	-	第一個漸層十六進位色碼
`gradientColor2`	string	-	第二個漸層十六進位色碼
`gradientAngle`	integer (0-360)	`180`	漸層角度（以度為單位）
`feather`	integer (0-20)	`0`	邊緣羽化半徑
`format`	`"png"` \| `"webp"`	`"png"`	輸出格式

模糊背景

工具路由： blur-background
模型： rembg / BiRefNet（與 remove-background 共用）

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

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

影像放大

工具路由： upscale
模型： RealESRGAN（不可用時以 Lanczos 備援）

參數	型別	預設值	說明
`scale`	number	`2`	放大倍率
`model`	string	`"auto"`	模型變體
`faceEnhance`	boolean	`false`	套用 GFPGAN 人臉增強處理
`denoise`	number	`0`	去雜訊強度
`format`	string	`"auto"`	輸出格式覆寫
`quality`	number	`95`	輸出品質（1-100）

OCR / 文字擷取

工具路由： ocr
模型： Tesseract（快速）、PaddleOCR PP-OCRv5（均衡）、PaddleOCR-VL 1.5（最佳）

參數	型別	預設值	說明
`quality`	`"fast"` \| `"balanced"` \| `"best"`	`"balanced"`	處理層級
`language`	string	`"auto"`	語言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko`
`enhance`	boolean	`true`	對影像進行前處理以提升 OCR 準確度
`engine`	string	-	已淘汰。將 `tesseract` 對映為 `fast`、`paddleocr` 對映為 `balanced`

傳回結構化結果，包含邊界框、信賴分數與擷取的文字區塊。

PDF OCR

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

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

參數	型別	預設值	說明
`quality`	`"fast"` \| `"balanced"` \| `"best"`	`"balanced"`	處理層級
`language`	string	`"auto"`	語言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko`
`pages`	string	`"all"`	頁面選取：`"all"`、`"1-3"`、`"1,3,5"`

人臉 / PII 模糊

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

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

人臉增強

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

參數	型別	預設值	說明
`model`	`"auto"` \| `"gfpgan"` \| `"codeformer"`	`"auto"`	增強模型
`strength`	number (0-1)	`0.8`	增強強度
`sensitivity`	number (0-1)	`0.5`	人臉偵測門檻
`onlyCenterFace`	boolean	`false`	只增強最靠近中央的人臉

AI 上色

工具路由： colorize
模型： DDColor（以 OpenCV DNN 備援）

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

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

去雜訊

工具路由： noise-removal
模型： SCUNet（分層去雜訊流程）

參數	型別	預設值	說明
`tier`	`"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"`	`"balanced"`	處理層級
`strength`	number (0-100)	`50`	去雜訊強度
`detailPreservation`	number (0-100)	`50`	要保留多少細節；數值越高保留越多紋理
`colorNoise`	number (0-100)	`30`	色彩雜訊降低強度
`format`	string	`"original"`	輸出格式：`original`、`png`、`jpeg`、`webp`、`avif`、`jxl`
`quality`	number (1-100)	`90`	輸出編碼品質

紅眼移除

工具路由： red-eye-removal

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

參數	型別	預設值	說明
`sensitivity`	number (0-100)	`50`	紅色像素偵測門檻
`strength`	number (0-100)	`70`	修正強度
`format`	string	-	輸出格式覆寫（選用）
`quality`	number (1-100)	`90`	輸出品質

相片修復

工具路由： restore-photo

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

參數	型別	預設值	說明
`scratchRemoval`	boolean	`true`	偵測並修復刮痕、撕裂
`faceEnhancement`	boolean	`true`	套用人臉增強處理
`fidelity`	number (0-1)	`0.7`	人臉增強強度（越高越保守）
`denoise`	boolean	`true`	套用去雜訊處理
`denoiseStrength`	number (0-100)	`25`	去雜訊強度
`colorize`	boolean	`false`	修復後進行上色
`colorizeStrength`	number (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 的結果加上產生設定：

參數	型別	預設值	說明
`jobId`	string	（必填）	來自階段 1 的 Job ID
`filename`	string	（必填）	來自階段 1 的原始檔名
`countryCode`	string	（必填）	ISO 國家代碼（例如 `US`、`GB`、`IN`）
`documentType`	string	`"passport"`	文件類型
`bgColor`	string	`"#FFFFFF"`	背景顏色十六進位色碼
`printLayout`	string	`"none"`	列印版面配置：`none`、`4x6`、`a4`、`letter`
`maxFileSizeKb`	number	`0`	檔案大小上限（KB）（0 = 無限制）
`dpi`	number (72-1200)	`300`	輸出 DPI
`customWidthMm`	number	-	自訂寬度（mm）（覆寫國家規格）
`customHeightMm`	number	-	自訂高度（mm）（覆寫國家規格）
`zoom`	number (0.5-3)	`1`	縮放倍率
`adjustX`	number	`0`	水平位置調整
`adjustY`	number	`0`	垂直位置調整
`landmarks`	object	（必填）	來自階段 1 的特徵點
`imageWidth`	number	（必填）	來自階段 1 的影像寬度
`imageHeight`	number	（必填）	來自階段 1 的影像高度

物件擦除（影像修補）

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

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

參數	型別	預設值	說明
`file`	file	（必填）	來源影像（multipart）
`mask`	file	（必填）	遮罩影像（multipart，欄位名稱 `mask`，白色 = 擦除）
`format`	string	`"auto"`	輸出格式：`auto`、`png`、`jpg`、`jpeg`、`webp`、`tiff`、`gif`、`avif`、`heic`、`heif`、`jxl`
`quality`	integer (1-100)	`95`	輸出品質

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

AI 畫布擴展

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

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

參數	型別	預設值	說明
`extendTop`	integer	`0`	上方要延伸的像素數
`extendRight`	integer	`0`	右方要延伸的像素數
`extendBottom`	integer	`0`	下方要延伸的像素數
`extendLeft`	integer	`0`	左方要延伸的像素數
`tier`	`"fast"` \| `"balanced"` \| `"high"`	`"balanced"`	品質層級
`format`	string	`"auto"`	輸出格式：`auto`、`png`、`jpg`、`jpeg`、`webp`、`tiff`、`gif`、`avif`、`heic`、`heif`、`jxl`
`quality`	integer (1-100)	`95`	輸出品質

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

智慧裁切

工具路由： smart-crop
模型： MediaPipe 人臉偵測（僅 face 模式）

參數	型別	預設值	說明
`mode`	string	`"subject"`	裁切策略：`subject`、`face`、`trim`
`strategy`	`"attention"` \| `"entropy"`	`"attention"`	subject 模式的策略
`width`	integer	-	輸出寬度
`height`	integer	-	輸出高度
`padding`	integer (0-50)	`0`	主體周圍的留白百分比
`facePreset`	string	`"head-shoulders"`	當 `mode=face` 時的預設框取
`sensitivity`	number (0-1)	`0.5`	人臉偵測門檻
`threshold`	integer (0-255)	`30`	背景偵測門檻（trim 模式）
`padToSquare`	boolean	`false`	將修剪後的結果補齊為正方形
`padColor`	string	`"#ffffff"`	正方形補齊的背景顏色
`targetSize`	integer	-	補齊輸出的目標尺寸（像素）
`quality`	integer (1-100)	-	輸出品質

舊版 mode 值 attention 與 content 仍被接受，並分別對映為 subject 與 trim。

人臉預設：

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

音訊轉錄

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

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

參數	型別	預設值	說明
`language`	string	`"auto"`	語言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko`、`id`、`th`、`vi`
`outputFormat`	`"txt"` \| `"srt"` \| `"vtt"`	`"txt"`	輸出格式

自動字幕

工具路由： auto-subtitles
模型： faster-whisper（先從影片擷取音訊，再進行轉錄）

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

參數	型別	預設值	說明
`language`	string	`"auto"`	語言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko`、`id`、`th`、`vi`
`format`	`"srt"` \| `"vtt"`	`"srt"`	輸出字幕格式

PNG 透明度修復

工具路由： transparency-fixer
模型： BiRefNet HR-matting（2048x2048 解析度）

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

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

參數	型別	預設值	說明
`defringe`	number (0-100)	`30`	用於移除顏色汙染的邊緣去毛邊強度
`outputFormat`	`"png"` \| `"webp"`	`"png"`	輸出影像格式
`removeWatermark`	boolean	`false`	套用浮水印移除前處理（中值濾波）

bash

curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]" \
  -F 'settings={"defringe":30,"outputFormat":"png"}'

具備選用 AI 功能的工具

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

影像增強

工具路由： image-enhancement
引擎： 以分析為基礎（Sharp 直方圖與統計）

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

參數	型別	預設值	說明
`mode`	`"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"`	`"auto"`	用於調校修正的場景模式
`intensity`	number (0-100)	`50`	整體修正強度
`corrections.exposure`	boolean	`true`	套用曝光修正
`corrections.contrast`	boolean	`true`	套用對比修正
`corrections.whiteBalance`	boolean	`true`	套用白平衡修正
`corrections.saturation`	boolean	`true`	套用飽和度修正
`corrections.sharpness`	boolean	`true`	套用銳利度修正
`corrections.denoise`	boolean	`true`	套用去雜訊
`deepEnhance`	boolean	`false`	透過 SCUNet 啟用 AI 去雜訊（需要 `upscale-enhance` 套件包）

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

內容感知調整大小（接縫裁減）

工具路由： content-aware-resize
引擎： Go caire 二進位檔（非 Python，無 GPU 效益）

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

參數	型別	預設值	說明
`width`	number	-	目標寬度
`height`	number	-	目標高度
`protectFaces`	boolean	`false`	保護偵測到的人臉區域（需要 `face-detection` 套件包）
`blurRadius`	number (0-20)	`4`	能量計算的預先模糊
`sobelThreshold`	number (1-20)	`2`	邊緣敏感度門檻
`square`	boolean	`false`	強制正方形輸出

Essentials

Optimization

Adjustments

Watermark & Overlay

Utilities

Layout

Format

AI Tools

AI 引擎參考

架構

功能套件包

去背

背景替換

模糊背景

影像放大

OCR / 文字擷取

PDF OCR

人臉 / PII 模糊

人臉增強

AI 上色

去雜訊

紅眼移除

相片修復

證件照

階段 1：分析

階段 2：產生

物件擦除（影像修補）

AI 畫布擴展

智慧裁切

音訊轉錄

自動字幕

PNG 透明度修復

具備選用 AI 功能的工具

影像增強

內容感知調整大小（接縫裁減）

AI 引擎參考 ​

架構 ​

功能套件包 ​

去背 ​

背景替換 ​

模糊背景 ​

影像放大 ​

OCR / 文字擷取 ​

PDF OCR ​

人臉 / PII 模糊 ​

人臉增強 ​

AI 上色 ​

去雜訊 ​

紅眼移除 ​

相片修復 ​

證件照 ​

階段 1：分析 ​

階段 2：產生 ​

物件擦除（影像修補） ​

AI 畫布擴展 ​

智慧裁切 ​

音訊轉錄 ​

自動字幕 ​

PNG 透明度修復 ​

具備選用 AI 功能的工具 ​

影像增強 ​

內容感知調整大小（接縫裁減） ​

AI 引擎參考

架構

功能套件包

去背

背景替換

模糊背景

影像放大

OCR / 文字擷取

PDF OCR

人臉 / PII 模糊

人臉增強

AI 上色

去雜訊

紅眼移除

相片修復

證件照

階段 1：分析

階段 2：產生

物件擦除（影像修補）

AI 畫布擴展

智慧裁切

音訊轉錄

自動字幕

PNG 透明度修復

具備選用 AI 功能的工具

影像增強

內容感知調整大小（接縫裁減）