本页面由机器翻译。发现错误了吗?帮助改进它。
Skip to content

AI 引擎参考

@snapotter/ai 包协调本机工具和 Python 运行时以进行本地 ML 操作。 大多数 ML 工具使用持久的 Python sidecar 来实现快速热启动。 OCR 是故意分开的: fast 调用本机 Tesseract 二进制文件, 而 balancedbest 使用专用的持久性 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 能力的工具。所有模型均在本地运行,首次下载模型后无需联网。

韩语 OCR 兼容性

快速 OCR 支持 autoendeesfrzhja,但不支持韩语 (ko)。韩语需要精确 OCR 包以及 balancedbest。该包可在官方 Linux amd64 和 arm64 容器上运行;即使是 NVIDIA 主机,OCR 仍使用 CPU。不受支持的系统会返回明确的兼容性错误,绝不会静默回退到 fast。韩语与 fast 或旧版 tesseract 别名的组合会在入队前以 FEATURE_INCOMPATIBLEfast-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_pagecountdoc_healthdoc_flattendoc_redactdoc_textdoc_to_worddoc_metadatadoc_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-removalface-detection 上启用 Passport Photo; 在已安装后台删除后启用它仅排队 face-detection。 OCR 是例外,因为 fast 不需要包装; 通过 UI 或 POST /api/v1/admin/features/ocr/install 安装其可选的精确运行时。

功能包大小共享依赖组使用它的工具
background-removal4-5 GBrembg / BiRefNet 抠图remove-background、passport-photo、transparency-fixer、background-replace、blur-background
face-detection200-300 MBMediaPipe 人脸检测与关键点blur-faces、red-eye-removal、smart-crop
object-eraser-colorize1-2 GBLaMa 图像修复/外扩与 DDColorerase-object、colorize、ai-canvas-expand
upscale-enhance5-6 GBRealESRGAN、GFPGAN / CodeFormer、降噪upscale、enhance-faces、noise-removal
photo-restoration4-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(仅限 balancedbest
transcription~600 MBfaster-whisper 语音转文本模型transcribe-audio、auto-subtitles

具有跨包依赖的工具:

工具所需功能包原因
passport-photobackground-removalface-detection先移除背景,然后使用人脸关键点将裁剪对齐到护照和证件照规则。
enhance-facesupscale-enhanceface-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。 失败的安装会使之前的健康生成保持活动状态。

对于气隙安装,请使用名为 indexarchive 的多部分字段将版本的 ocr-runtime-index.json 和匹配的 OCR 运行时存档上传到 POST /api/v1/admin/features/import。 离线导入应用与在线安装相同的签名、哈希、提取、兼容性和冒烟测试检查; 没有可信签名索引的存档将被拒绝。


抠图

工具路由: remove-background
模型: 采用 BiRefNet(默认)或 U2-Net 变体的 rembg

参数类型默认值说明
modelstring-模型变体(可选覆盖)
backgroundTypestring"transparent"其一:transparentcolorgradientblurimage
backgroundColorstring-纯色背景的十六进制颜色
gradientColor1string-第一个渐变颜色
gradientColor2string-第二个渐变颜色
gradientAnglenumber-渐变角度(度)
blurEnabledboolean-启用背景模糊效果
blurIntensitynumber (0-100)-模糊强度
shadowEnabledboolean-为主体启用投影
shadowOpacitynumber (0-100)-阴影不透明度
outputFormatstring-输出格式:pngwebpavif
edgeRefineinteger (0-3)-边缘细化级别
decontaminateboolean-移除边缘的颜色溢出

背景替换

工具路由: background-replace
模型: rembg / BiRefNet(与 remove-background 共享)

移除背景并将其替换为纯色或渐变。

参数类型默认值说明
backgroundType"color" | "gradient""color"背景模式
colorstring"#ffffff"背景十六进制颜色(当 backgroundTypecolor 时)
gradientColor1string-第一个渐变十六进制颜色
gradientColor2string-第二个渐变十六进制颜色
gradientAngleinteger (0-360)180渐变角度(度)
featherinteger (0-20)0边缘羽化半径
format"png" | "webp""png"输出格式

背景模糊

工具路由: blur-background
模型: rembg / BiRefNet(与 remove-background 共享)

在保持主体清晰的同时模糊背景。

参数类型默认值说明
intensityinteger (1-100)50模糊强度
featherinteger (0-20)0边缘羽化半径
format"png" | "webp""png"输出格式

图像放大

工具路由: upscale
模型: RealESRGAN(不可用时回退到 Lanczos)

参数类型默认值说明
scalenumber2放大倍数
modelstring"auto"模型变体
faceEnhancebooleanfalse应用 GFPGAN 人脸增强处理
denoisenumber0降噪强度
formatstring"auto"输出格式覆盖
qualitynumber95输出质量(1-100)

OCR / 文本提取

工具路由: ocr
型号: Tesseract (fast); RapidOCR 与 PP-OCRv6 小型号(balanced);具有校准变体评分的 PP-OCRv6 中型模型 (best)

参数类型默认值说明
quality"fast" | "balanced" | "best"动态的省略 qualityengine 时,SnapOtter 会按 bestbalancedfast 的顺序选择可用的最高质量层。韩语绝不会选择 fast;它会使用 best,其次是 balanced,否则返回精确运行时的安装或兼容性错误。
languagestring"auto"语言:autoendefreszhjako
enhance布尔值取决于层级提高局部对比度。快速直接应用;仅当校准得分提高 OCR 时,准确的等级才会保留变体。默认为“最佳”
engine细绳-已弃用的兼容性别名。将 tesseract 映射到 fast,并将旧版 paddleocr 值映射到 balanced;它不加载 PaddlePaddle

返回提取的文本以及来源元数据:引擎、请求的和实际的质量、设备、提供商、降级状态、警告和准确的运行时/模型版本(如果适用)。 明确的质量要求永远不会退回到另一层。 如果 balancedbest 不可用,则 API 返回 FEATURE_NOT_INSTALLEDFEATURE_INCOMPATIBLE,而不是静默运行 fast

PDF OCR

工具路由: ocr-pdf
模型: 与图像 OCR 相同的档次体系

使用 AI 驱动的 OCR 逐页从扫描的 PDF 文档中提取文本。

参数类型默认值说明
quality"fast" | "balanced" | "best"动态的省略 qualityengine 时,SnapOtter 会按 bestbalancedfast 的顺序选择可用的最高质量层。韩语绝不会选择 fast;它会使用 best,其次是 balanced,否则返回精确运行时的安装或兼容性错误。
languagestring"auto"语言:autoendefreszhjako
pagesstring"all"页面选择:"all""1-3""1,3,5"
enhance布尔值取决于层级提高局部对比度。快速直接应用;仅当校准得分提高 OCR 时,准确的等级才会保留变体。默认为“最佳”
engine细绳-已弃用的兼容性别名。将 tesseract 映射到 fast,并将旧版 paddleocr 值映射到 balanced;它不加载 PaddlePaddle

同样的不降级规则适用于 PDF OCR。 PDF 页面在识别前会进行光栅化处理,一次请求最多可以选择50个页面。

人脸 / PII 模糊

工具路由: blur-faces
模型: MediaPipe 人脸检测

参数类型默认值说明
blurRadiusnumber (1-100)30高斯模糊半径
sensitivitynumber (0-1)0.5检测置信度阈值

人脸增强

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

参数类型默认值说明
model"auto" | "gfpgan" | "codeformer""auto"增强模型
strengthnumber (0-1)0.8增强强度
sensitivitynumber (0-1)0.5人脸检测阈值
onlyCenterFacebooleanfalse仅增强最居中的人脸

AI 上色

工具路由: colorize
模型: DDColor(回退到 OpenCV DNN)

将黑白或灰度照片转换为全彩。

参数类型默认值说明
intensitynumber (0-1)1.0色彩饱和度强度
model"auto" | "ddcolor" | "opencv""auto"模型变体

噪点去除

工具路由: noise-removal
模型: SCUNet(分档降噪流水线)

参数类型默认值说明
tier"quick" | "balanced" | "quality" | "maximum""balanced"处理档次
strengthnumber (0-100)50降噪强度
detailPreservationnumber (0-100)50保留多少细节;数值越高保留的纹理越多
colorNoisenumber (0-100)30彩色噪点抑制强度
formatstring"original"输出格式:originalpngjpegwebpavifjxl
qualitynumber (1-100)90输出编码质量

红眼消除

工具路由: red-eye-removal

检测人脸关键点,定位眼部区域,并校正红色通道过饱和。

参数类型默认值说明
sensitivitynumber (0-100)50红色像素检测阈值
strengthnumber (0-100)70校正强度
formatstring-输出格式覆盖(可选)
qualitynumber (1-100)90输出质量

照片修复

工具路由: restore-photo

针对老旧或受损照片的多步流水线:划痕/撕裂检测与修复、人脸增强、降噪,以及可选的上色。

参数类型默认值说明
scratchRemovalbooleantrue检测并修复划痕、撕裂
faceEnhancementbooleantrue应用人脸增强处理
fidelitynumber (0-1)0.7人脸增强强度(越高越保守)
denoisebooleantrue应用降噪处理
denoiseStrengthnumber (0-100)25降噪强度
colorizebooleanfalse修复后进行上色
colorizeStrengthnumber (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 的结果加上生成设置:

参数类型默认值说明
jobIdstring(必填)来自阶段 1 的作业 ID
filenamestring(必填)来自阶段 1 的原始文件名
countryCodestring(必填)ISO 国家/地区代码(例如 USGBIN
documentTypestring"passport"证件类型
bgColorstring"#FFFFFF"背景颜色十六进制
printLayoutstring"none"打印排版:none4x6a4letter
maxFileSizeKbnumber0最大文件大小(KB)(0 = 无限制)
dpinumber (72-1200)300输出 DPI
customWidthMmnumber-自定义宽度(毫米)(覆盖国家/地区规格)
customHeightMmnumber-自定义高度(毫米)(覆盖国家/地区规格)
zoomnumber (0.5-3)1缩放系数
adjustXnumber0水平位置调整
adjustYnumber0垂直位置调整
landmarksobject(必填)来自阶段 1 的关键点
imageWidthnumber(必填)来自阶段 1 的图像宽度
imageHeightnumber(必填)来自阶段 1 的图像高度

对象擦除(图像修复)

工具路由: erase-object
模型: 通过 ONNX Runtime 运行的 LaMa

蒙版作为第二个文件部分发送(字段名 mask),而不是作为 base64。蒙版中的白色像素表示要擦除的区域。formatquality 设置作为顶层表单字段发送。

参数类型默认值说明
filefile(必填)源图像(multipart)
maskfile(必填)蒙版图像(multipart,字段名 mask,白色 = 擦除)
formatstring"auto"输出格式:autopngjpgjpegwebptiffgifavifheicheifjxl
qualityinteger (1-100)95输出质量

当有 NVIDIA GPU 可用时启用 CUDA 加速。

AI 画布扩展

工具路由: ai-canvas-expand
模型: 基于 LaMa 的外扩

向任意方向扩展图像画布,并用与现有图像相匹配的 AI 生成内容填充新增区域。

参数类型默认值说明
extendTopinteger0顶部扩展的像素数
extendRightinteger0右侧扩展的像素数
extendBottominteger0底部扩展的像素数
extendLeftinteger0左侧扩展的像素数
tier"fast" | "balanced" | "high""balanced"质量档次
formatstring"auto"输出格式:autopngjpgjpegwebptiffgifavifheicheifjxl
qualityinteger (1-100)95输出质量

至少有一个扩展方向必须大于 0。

智能裁剪

工具路由: smart-crop
模型: MediaPipe 人脸检测(仅人脸模式)

参数类型默认值说明
modestring"subject"裁剪策略:subjectfacetrim
strategy"attention" | "entropy""attention"主体模式的策略
widthinteger-输出宽度
heightinteger-输出高度
paddinginteger (0-50)0主体周围的内边距百分比
facePresetstring"head-shoulders"mode=face 时的预设取景
sensitivitynumber (0-1)0.5人脸检测阈值
thresholdinteger (0-255)30背景检测阈值(trim 模式)
padToSquarebooleanfalse将裁剪结果补齐为正方形
padColorstring"#ffffff"正方形补齐的背景颜色
targetSizeinteger-补齐输出的目标尺寸(像素)
qualityinteger (1-100)-输出质量

旧版 modeattentioncontent 仍被接受,并分别映射到 subjecttrim

人脸预设:

预设最适合
closeup头像特写
head-shoulders个人资料照片
upper-bodyLinkedIn / 正式照
half-body完整上半身

音频转写

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

将语音转换为文本。支持纯文本、SRT 和 VTT 输出格式。

参数类型默认值说明
languagestring"auto"语言:autoendefreszhjakoidthvi
outputFormat"txt" | "srt" | "vtt""txt"输出格式

自动字幕

工具路由: auto-subtitles
模型: faster-whisper(从视频中提取音频,然后转写)

从视频的音轨生成字幕文件。

参数类型默认值说明
languagestring"auto"语言:autoendefreszhjakoidthvi
format"srt" | "vtt""srt"输出字幕格式

PNG 透明度修复

工具路由: transparency-fixer
模型: BiRefNet HR-matting(2048x2048 分辨率)

修复"伪透明"PNG,即背景已被移除但残留了毛边、光晕或半透明杂影。使用 BiRefNet 的高分辨率抠图模型生成干净的 alpha 通道,然后应用可配置的去边处理以移除边缘的颜色污染。

OOM 回退链: 如果 BiRefNet HR-matting 超出可用内存,工具会自动回退到 birefnet-general,然后回退到 u2net

参数类型默认值说明
defringenumber (0-100)30边缘去边强度,用于移除颜色污染
outputFormat"png" | "webp""png"输出图像格式
removeWatermarkbooleanfalse应用水印移除预处理(中值滤波)
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 能力的工具

以下工具并非 Python 边车工具,但在启用某些选项时会使用 AI 功能。

图像增强

工具路由: image-enhancement
引擎: 基于分析(Sharp 直方图与统计)

分析图像并对曝光、对比度、白平衡、饱和度、锐度和噪点应用自动校正。支持特定场景模式。

参数类型默认值说明
mode"auto" | "portrait" | "landscape" | "low-light" | "food" | "document""auto"用于微调校正的场景模式
intensitynumber (0-100)50整体校正强度
corrections.exposurebooleantrue应用曝光校正
corrections.contrastbooleantrue应用对比度校正
corrections.whiteBalancebooleantrue应用白平衡校正
corrections.saturationbooleantrue应用饱和度校正
corrections.sharpnessbooleantrue应用锐度校正
corrections.denoisebooleantrue应用降噪
deepEnhancebooleanfalse通过 SCUNet 启用 AI 噪点去除(需要 upscale-enhance 功能包)

POST /api/v1/tools/image/image-enhancement/analyze 处还提供一个额外的分析端点,它返回检测到的校正而不实际应用它们。

内容感知缩放(接缝裁剪)

工具路由: content-aware-resize
引擎: Go caire 二进制文件(非 Python,无 GPU 收益)

通过移除低能量接缝智能地缩放图像,保留重要内容。

参数类型默认值说明
widthnumber-目标宽度
heightnumber-目标高度
protectFacesbooleanfalse保护检测到的人脸区域(需要 face-detection 功能包)
blurRadiusnumber (0-20)4用于能量计算的预模糊
sobelThresholdnumber (1-20)2边缘敏感度阈值
squarebooleanfalse强制正方形输出