description:"Referencia del motor de IA con todas las herramientas de ML locales. Eliminación de fondo, escalado, OCR, detección de rostros, restauración de fotos y más."
El paquete `@snapotter/ai` coordina herramientas nativas y tiempos de ejecución de Python para operaciones locales de ML. La mayoría de las herramientas ML utilizan un Python sidecar persistente para arranques rápidos y en caliente. OCR está intencionalmente separado: `fast` invoca el binario nativo Tesseract, mientras que `balanced` y `best` usan un JSONL persistente dedicado dispatcher anclado a la generación RapidOCR activa e inmutable bajo `/data/ai/v3`. Cada solicitud contiene un generation lease. Durante una actualización, SnapOtter ejecuta un smoke test en el candidato antes de la activación, cambia atómicamente al nuevo dispatcher y luego drena la generación anterior anterior a garbage collection.
NVIDIA CUDA se detecta automáticamente y lo utilizan los tiempos de ejecución que lo admiten. OCR utiliza CPU en todos los hosts, incluidos los sistemas con GPU NVIDIA, evitando CUDA y el acoplamiento de controladores para esta herramienta.
La aceleración con iGPU de Intel/AMD a través de VA-API, Quick Sync u OpenCL no es compatible hoy con la inferencia de IA. Mapear `/dev/dri` dentro de un contenedor no acelera estas herramientas del sidecar de Python a menos que haya disponible una GPU NVIDIA compatible con CUDA.
19 herramientas de IA del sidecar de Python en cuatro modalidades (imagen, audio, video, documento), más 2 herramientas con capacidades de IA opcionales. Todos los modelos se ejecutan localmente: no se requiere internet tras la descarga inicial del modelo.
OCR rápido admite `auto`, `en`, `de`, `es`, `fr`, `zh` y `ja`, pero no coreano (`ko`). El coreano requiere el paquete OCR preciso y `balanced` o `best`. El paquete funciona en los contenedores oficiales Linux amd64 y arm64, incluidos hosts NVIDIA, donde el OCR sigue usando la CPU. Los sistemas no compatibles reciben un error explícito y nunca vuelven silenciosamente a `fast`. Coreano con `fast` o el alias heredado `tesseract` se rechaza antes de encolarse con `FEATURE_INCOMPATIBLE` y `fast-korean-unsupported`.
Un perfil de despachador "docs" independiente reemplaza la lista de permitidos de IA con scripts de procesamiento de documentos (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) y omite las importaciones pesadas de ML.
**Tiempos de espera:** 300 s por defecto; OCR y la eliminación de fondo con BiRefNet obtienen 600 s.
## Paquetes de funciones {#feature-bundles}
Los modelos de IA se empaquetan por pila de dependencias compartida, no un archivo por herramienta. Un paquete de funciones puede habilitar varias herramientas cuando estas usan la misma familia de modelos, los mismos wheels de Python o las mismas librerías nativas. Esto mantiene la imagen Docker de la versión más pequeña y evita almacenar copias duplicadas de los mismos modelos de matting de fondo, detección de rostros, OCR, restauración y voz.
La imagen Docker incluye la aplicación más el entorno de ejecución común. Los archivos de modelos grandes se descargan bajo demanda en el volumen persistente `/data/ai`, y luego los reutiliza cada herramienta que los necesite. Si un paquete ya está instalado porque otra herramienta lo necesitó, habilitar una nueva herramienta dependiente no vuelve a descargar ese paquete.
La mayoría de las herramientas de IA requieren uno o más paquetes de funciones antes de poder ejecutarse. La interfaz de usuario del administrador los instala por herramienta a través de `POST /api/v1/admin/tools/:toolId/features/install`, que resuelve la lista completa de paquetes, omite los paquetes que ya están instalados y pone en cola solo las descargas que faltan. Por ejemplo, habilitar Passport Photo en una instancia nueva pone en cola `background-removal` y `face-detection`; habilitarlo después de que la eliminación de fondo ya esté instalada pone en cola solo `face-detection`. OCR es la excepción porque `fast` no necesita paquete; instale su tiempo de ejecución preciso opcional a través de la interfaz de usuario o `POST /api/v1/admin/features/ocr/install`.
| `transcription` | ~600 MB | modelos de voz a texto faster-whisper | transcribe-audio, auto-subtitles |
Herramientas con dependencias entre paquetes:
| Herramienta | Paquetes requeridos | Motivo |
|------|------------------|-----|
| `passport-photo` | `background-removal`, `face-detection` | Elimina el fondo y luego usa los puntos de referencia del rostro para encuadrar el recorte según las reglas de fotos de pasaporte y de identificación. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Detecta rostros antes de ejecutar la mejora con GFPGAN o CodeFormer en las regiones de rostro seleccionadas. |
Una herramienta está disponible solo cuando todos los paquetes requeridos están instalados, excepto OCR: su nivel `fast` integrado permanece disponible sin el paquete OCR opcional. Las instalaciones parciales son válidas y se manejan de forma incremental: los paquetes instalados se reutilizan, los paquetes faltantes se muestran como descargas y las instalaciones en cola se ejecutan una a la vez para que el entorno Python compartido no se modifique al mismo tiempo.
### Instalación precisa del tiempo de ejecución de OCR {#accurate-ocr-runtime-installation}
El paquete OCR preciso es un tiempo de ejecución específico de la plataforma para el contenedor oficial Linux amd64 o Linux arm64. La compilación amd64 utiliza Python 3.12; la compilación arm64 utiliza Python 3.11. Ambas compilaciones ejecutan RapidOCR a través de `CPUExecutionProvider` de ONNX Runtime, por lo que el mismo paquete funciona solo en hosts de CPU y NVIDIA Docker. El tiempo de ejecución preciso requiere al menos 4 GiB de memoria efectiva: el límite cgroup del contenedor configurado; de lo contrario, la memoria del host. Un sistema por debajo de ese mínimo de compatibilidad firmado se rechaza antes de la descarga. Este requisito no se aplica al Fast OCR integrado. Las compilaciones de Bare-metal se rechazan porque sus libc y Python ABI no se pueden inferir de forma segura; Fast OCR permanece disponible cuando el host proporciona Tesseract y Ghostscript.
El artefacto opcional tiene aproximadamente 208-234 MiB comprimidos y 409-488 MiB extraídos, según la arquitectura. El índice firmado vincula los recuentos exactos de bytes comprimidos y extraídos aplicados por el instalador. El Tesseract integrado agrega aproximadamente 25 MiB a la imagen oficial y no necesita archivos en `/data/ai`.
La instalación en línea obtiene un índice de versión firmado y el artefacto de contenido exacto para la plataforma actual. SnapOtter verifica la firma del índice Ed25519, el tamaño del artefacto, el resumen de SHA-256, los resúmenes de modelos, las rutas, los modos de archivo y el smoke test preparado antes de activar atómicamente la nueva generación. Una instalación fallida deja activa la generación anterior en buen estado.
Para una instalación aislada, cargue tanto el archivo `ocr-runtime-index.json` de la versión como el archivo de tiempo de ejecución OCR coincidente en `POST /api/v1/admin/features/import` utilizando campos de varias partes denominados `index` y `archive`. La importación sin conexión aplica las mismas comprobaciones de firma, hash, extracción, compatibilidad y prueba de humo que la instalación en línea; se rechaza un archivo sin su índice firmado confiable.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinámica | Si se omiten `quality` y `engine`, SnapOtter elige el mejor nivel disponible en este orden: `best`, `balanced`, `fast`. Para coreano nunca elige `fast`: usa `best`, luego `balanced`, o devuelve el error de instalación o compatibilidad del entorno preciso. |
| `enhance` | booleano | Dependiente del nivel | Mejorar el contraste local. Fast lo aplica directamente; Los niveles precisos mantienen la variante solo cuando la puntuación calibrada mejora OCR. Valor predeterminado activado para Mejor |
| `engine` | cadena | - | Alias de compatibilidad obsoleto. Asigna `tesseract` a `fast` y el valor heredado de `paddleocr` a `balanced`; no carga PaddlePaddle |
Devuelve el texto extraído más metadatos de procedencia: motor, calidad solicitada y real, dispositivo, proveedor, estado de degradación, advertencias y versiones de modelo/tiempo de ejecución preciso cuando corresponda. Las solicitudes de calidad explícitas nunca recaen en otro nivel. Si `balanced` o `best` no están disponibles, API devuelve `FEATURE_NOT_INSTALLED` o `FEATURE_INCOMPATIBLE` en lugar de ejecutar `fast` de forma silenciosa.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinámica | Si se omiten `quality` y `engine`, SnapOtter elige el mejor nivel disponible en este orden: `best`, `balanced`, `fast`. Para coreano nunca elige `fast`: usa `best`, luego `balanced`, o devuelve el error de instalación o compatibilidad del entorno preciso. |
| `enhance` | booleano | Dependiente del nivel | Mejorar el contraste local. Fast lo aplica directamente; Los niveles precisos mantienen la variante solo cuando la puntuación calibrada mejora OCR. Valor predeterminado activado para Mejor |
| `engine` | cadena | - | Alias de compatibilidad obsoleto. Asigna `tesseract` a `fast` y el valor heredado de `paddleocr` a `balanced`; no carga PaddlePaddle |
La misma regla de no degradación se aplica a PDF OCR. Las páginas PDF se rasterizan antes del reconocimiento y una solicitud puede seleccionar como máximo 50 páginas.
| `quality` | number (1-100) | `90` | Calidad de codificación de salida |
## Eliminación de ojos rojos {#red-eye-removal}
**Ruta de la herramienta:**`red-eye-removal`
Detecta los puntos de referencia del rostro, localiza las regiones de los ojos y corrige la sobresaturación del canal rojo.
| Parámetro | Tipo | Por defecto | Descripción |
|-----------|------|---------|-------------|
| `sensitivity` | number (0-100) | `50` | Umbral de detección de píxeles rojos |
| `strength` | number (0-100) | `70` | Intensidad de la corrección |
| `format` | string | - | Anulación del formato de salida (opcional) |
| `quality` | number (1-100) | `90` | Calidad de salida |
## Restauración de fotos {#photo-restoration}
**Ruta de la herramienta:**`restore-photo`
Pipeline de varios pasos para fotos antiguas o dañadas: detección y reparación de arañazos/roturas, mejora de rostros, reducción de ruido y coloración opcional.
| `faceEnhancement` | boolean | `true` | Aplicar una pasada de mejora de rostros |
| `fidelity` | number (0-1) | `0.7` | Intensidad de la mejora de rostros (mayor = más conservador) |
| `denoise` | boolean | `true` | Aplicar una pasada de reducción de ruido |
| `denoiseStrength` | number (0-100) | `25` | Intensidad de la reducción de ruido |
| `colorize` | boolean | `false` | Colorizar tras la restauración |
| `colorizeStrength` | number (0-100) | `85` | Intensidad de la coloración |
## Foto de pasaporte {#passport-photo}
**Ruta de la herramienta:**`passport-photo`
**Modelos:** puntos de referencia del rostro de MediaPipe + eliminación de fondo con BiRefNet
Flujo de trabajo en dos fases: analizar (detectar rostro + eliminar fondo) y luego generar (recortar, redimensionar, mosaico). Admite más de 37 países en 6 regiones.
### Fase 1: Analizar {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
Acepta un archivo de imagen (multipart). Devuelve los datos de puntos de referencia del rostro, una vista previa en base64 y las dimensiones de la imagen.
| `maxFileSizeKb` | number | `0` | Tamaño máximo de archivo en KB (0 = sin límite) |
| `dpi` | number (72-1200) | `300` | DPI de salida |
| `customWidthMm` | number | - | Ancho personalizado en mm (anula la especificación del país) |
| `customHeightMm` | number | - | Alto personalizado en mm (anula la especificación del país) |
| `zoom` | number (0.5-3) | `1` | Factor de zoom |
| `adjustX` | number | `0` | Ajuste de la posición horizontal |
| `adjustY` | number | `0` | Ajuste de la posición vertical |
| `landmarks` | object | (requerido) | Puntos de referencia de la Fase 1 |
| `imageWidth` | number | (requerido) | Ancho de imagen de la Fase 1 |
| `imageHeight` | number | (requerido) | Alto de imagen de la Fase 1 |
## Borrado de objetos (inpainting) {#object-erasing-inpainting}
**Ruta de la herramienta:**`erase-object`
**Modelo:** LaMa vía ONNX Runtime
La máscara se envía como una **segunda parte de archivo** (nombre de campo `mask`), no como base64. Los píxeles blancos en la máscara indican las áreas a borrar. Los ajustes `format` y `quality` se envían como campos de formulario de nivel superior.
| Parámetro | Tipo | Por defecto | Descripción |
|-----------|------|---------|-------------|
| `file` | file | (requerido) | Imagen de origen (multipart) |
| `mask` | file | (requerido) | Imagen de máscara (multipart, nombre de campo `mask`, blanco = borrar) |
| `format` | `"srt"` \| `"vtt"` | `"srt"` | Formato de subtítulos de salida |
## Corrector de transparencia PNG {#png-transparency-fixer}
**Ruta de la herramienta:**`transparency-fixer`
**Modelo:** matting HR de BiRefNet (resolución 2048x2048)
Corrige los PNG con "falsa transparencia", donde se eliminó el fondo pero quedaron bordes irregulares, halos o artefactos semitransparentes. Usa el modelo de matting de alta resolución de BiRefNet para producir un canal alfa limpio y luego aplica un procesamiento de eliminación de bordes configurable para quitar la contaminación de color a lo largo de los bordes.
**Cadena de respaldo ante OOM:** Si el matting HR de BiRefNet supera la memoria disponible, la herramienta recurre automáticamente a `birefnet-general`, y luego a `u2net`.
| Parámetro | Tipo | Por defecto | Descripción |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Intensidad de la eliminación de bordes para quitar la contaminación de color |
| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Formato de imagen de salida |
| `removeWatermark` | boolean | `false` | Aplicar preprocesamiento de eliminación de marca de agua (filtro de mediana) |
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
## Herramientas con capacidades de IA opcionales {#tools-with-optional-ai-capabilities}
Las siguientes herramientas no son herramientas del sidecar de Python, pero usan funciones de IA cuando se activan ciertas opciones.
### Mejora de imagen {#image-enhancement}
**Ruta de la herramienta:**`image-enhancement`
**Motor:** Basado en análisis (histograma y estadísticas de Sharp)
Analiza la imagen y aplica correcciones automáticas de exposición, contraste, balance de blancos, saturación, nitidez y ruido. Admite modos específicos de escena.
| Parámetro | Tipo | Por defecto | Descripción |
|-----------|------|---------|-------------|
| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Modo de escena para ajustar las correcciones |
| `intensity` | number (0-100) | `50` | Intensidad general de la corrección |
| `deepEnhance` | boolean | `false` | Activar la eliminación de ruido con IA vía SCUNet (requiere el paquete `upscale-enhance`) |
Hay disponible un endpoint de análisis adicional en `POST /api/v1/tools/image/image-enhancement/analyze` que devuelve las correcciones detectadas sin aplicarlas.
### Redimensionado con reconocimiento de contenido (seam carving) {#content-aware-resize-seam-carving}
**Ruta de la herramienta:**`content-aware-resize`
**Motor:** binario `caire` de Go (no Python: sin beneficio de GPU)
Redimensiona imágenes de forma inteligente eliminando costuras de baja energía, preservando el contenido importante.
| Parámetro | Tipo | Por defecto | Descripción |
|-----------|------|---------|-------------|
| `width` | number | - | Ancho objetivo |
| `height` | number | - | Alto objetivo |
| `protectFaces` | boolean | `false` | Proteger las regiones de rostro detectadas (requiere el paquete `face-detection`) |
| `blurRadius` | number (0-20) | `4` | Predesenfoque para el cálculo de energía |
| `sobelThreshold` | number (1-20) | `2` | Umbral de sensibilidad de bordes |
