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

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
AI 引擎参考，涵盖所有本地 ML 工具。抠图、放大、OCR、人脸检测、照片修复等。	bf13c82eb496	aa9a56cdddc7	human

AI 引擎参考

@snapotter/ai 包协调本机工具和 Python 运行时以进行本地 ML 操作。 大多数 ML 工具使用持久的 Python sidecar 来实现快速热启动。 OCR 是故意分开的： fast 调用本机 Tesseract 二进制文件， 而 balanced 和 best 使用专用的持久性 JSONL dispatcher，固定到 /data/ai/v3 下的活动不可变 RapidOCR 代。 每个请求都包含一个 generation lease。 在升级期间，SnapOtter 在激活之前在候选者上运行 smoke test，自动切换到新的 dispatcher，然后在 garbage collection 之前耗尽旧代。

NVIDIA CUDA 由支持它的运行时自动检测和使用。 OCR 在每个主机上使用 CPU，包括具有 NVIDIA GPU 的系统，避免 CUDA 和该工具的驱动程序耦合。

目前不支持通过 VA-API、Quick Sync 或 OpenCL 使用 Intel/AMD 集成显卡加速 AI 推理。将 /dev/dri 映射到容器中并不会加速这些 Python 边车工具，除非有支持 CUDA 的 NVIDIA GPU 可用。

19 个 Python 边车 AI 工具，覆盖四种模态（图像、音频、视频、文档），另有 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" 调度器配置用文档处理脚本（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
模型： 采用 BiRefNet（默认）或 U2-Net 变体的 rembg

参数	类型	默认值	说明
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 的作业 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	-	自定义宽度（毫米）（覆盖国家/地区规格）
customHeightMm	number	-	自定义高度（毫米）（覆盖国家/地区规格）
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 人脸检测（仅人脸模式）

参数	类型	默认值	说明
mode	string	"subject"	裁剪策略：subject、face、trim
strategy	"attention" | "entropy"	"attention"	主体模式的策略
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 边车工具，但在启用某些选项时会使用 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	强制正方形输出