SnapOtter/apps/docs/zh-TW/api/ai.md

description, i18n_source_hash, i18n_provenance, i18n_output_hash

description	i18n_source_hash	i18n_provenance	i18n_output_hash
AI 引擎參考，涵蓋所有本機 ML 工具。去背、放大、OCR、人臉偵測、相片修復等。	14728c1dcd05	machine	36207813ccb8

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	套用浮水印移除前處理（中值濾波）

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"	用於調校修正的場景模式
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	強制正方形輸出