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

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
AI 引擎參考，涵蓋所有本機 ML 工具。去背、放大、OCR、人臉偵測、相片修復等。	4e37d784676e	aa9a56cdddc7	human

AI 引擎參考

@snapotter/ai 套件協調本機工具和 Python 運行時以進行本機 ML 操作。 大多數 ML 工具使用持久的 Python sidecar 來實現快速熱啟動。 OCR 是故意分開的： fast 呼叫本機 Tesseract 二進位文件， 儘管 balanced 和 best 使用專用的持久化 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 功能的工具。所有模型都在本機執行，初次下載模型後即不需要網際網路。

::: info 韓語 OCR 相容性 快速 OCR 支援 auto、en、de、es、fr、zh 和 ja，但不支援韓語 (ko)。韓語需要精確 OCR 套件以及 balanced 或 best。此套件可在官方 Linux amd64 和 arm64 容器上執行；即使是 NVIDIA 主機，OCR 仍使用 CPU。不受支援的系統會傳回明確的相容性錯誤，絕不會靜默回退至 fast。韓語搭配 fast 或舊版 tesseract 別名時，會在排入佇列前以 FEATURE_INCOMPATIBLE 和 fast-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_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 磁碟區，之後由所有需要它的工具重複使用。如果某個套件包已因另一個工具的需要而安裝，啟用一個新的相依工具並不會再次下載該套件包。

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

套件包	大小	共用相依群組	使用它的工具
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	~208-234 MiB 下載 / ~409-488 MiB 安裝	選配 RapidOCR 3.9.1、ONNX Runtime 1.20.1 和固定 PP-OCR 型號	ocr、ocr-pdf（僅限 balanced 和 best）
transcription	~600 MB	faster-whisper 語音轉文字模型	transcribe-audio、auto-subtitles

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

工具	必要套件包	原因
passport-photo	background-removal、face-detection	先移除背景，再用人臉特徵點依護照與身分證照片規則框住裁切範圍。
enhance-faces	upscale-enhance、face-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。 失敗的安裝會使先前的健康生成保持活動狀態。

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

---

去背

工具路由： 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 （fast）； RapidOCR 和 PP-OCRv6 小型型號（balanced）； PP-OCRv6 具有校準變數評分的中等模型（best）

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

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

PDF OCR

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

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

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

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

人臉 / 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	強制正方形輸出