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

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

# AI 引擎參考 {#ai-engine-reference}

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

## 架構 {#architecture}

```
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 秒。

## 功能套件包 {#feature-bundles}

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 環境被同時修改。

---

## 去背 {#background-removal}

**工具路由：** `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}

**工具路由：** `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}

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

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

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

## 影像放大 {#image-upscaling}

**工具路由：** `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-text-extraction}

**工具路由：** `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 {#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 模糊 {#face-pii-blur}

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

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

## 人臉增強 {#face-enhancement}

**工具路由：** `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 上色 {#ai-colorization}

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

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

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

## 去雜訊 {#noise-removal}

**工具路由：** `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}

**工具路由：** `red-eye-removal`

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

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

## 相片修復 {#photo-restoration}

**工具路由：** `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}

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

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

### 階段 1：分析 {#phase-1-analyze}

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

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

### 階段 2：產生 {#phase-2-generate}

`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 的影像高度 |

## 物件擦除（影像修補） {#object-erasing-inpainting}

**工具路由：** `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}

**工具路由：** `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}

**工具路由：** `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}

**工具路由：** `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}

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

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

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

## PNG 透明度修復 {#png-transparency-fixer}

**工具路由：** `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 "file=@fake-transparent.png" \
  -F 'settings={"defringe":30,"outputFormat":"png"}'
```

---

## 具備選用 AI 功能的工具 {#tools-with-optional-ai-capabilities}

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

### 影像增強 {#image-enhancement}

**工具路由：** `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-seam-carving}

**工具路由：** `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` | 強制正方形輸出 |