InsightFace Server con Docker: inicio rápido

Ejecuta uno de los bloques desde la raíz del repositorio. Se usa directamente el archivo Compose incluido, que determina la imagen que se descarga. Si ya tienes el repositorio actualizado, omite git clone.

Abre http://SERVER:18097/ para CPU o http://SERVER:18098/ para CUDA 12. --accept-license acepta las condiciones del modelo; revísalas antes de ejecutar el comando.

En Collections crea un ID estable, por ejemplo employees. Elige un perfil anunciado por System, ajusta capacity al presupuesto de memoria y empieza con el umbral de coseno bruto predeterminado 0,4. Una Collection queda vinculada a identidad y digest del modelo, dimensión, preprocesamiento y perfil de detección.

En People selecciona la Collection y registra una Person con una o más imágenes JPEG, PNG, WebP o BMP nítidas. standard review es un buen inicio: exige exactamente un rostro utilizable y comprueba tamaño, confianza, nitidez, brillo y pose. Los lotes permiten éxito parcial; revisa cada motivo de rechazo.

En Search elige la misma Collection y sube otra foto de esa Person. Los resultados se ordenan por similitud de coseno bruta y la puntuación de una Person es la mejor de sus FaceSamples. La similitud no es probabilidad. Ninguna coincidencia devuelve correctamente una lista vacía.

En una instalación nueva, añade --enable-liveness al comando de instalación del modelo. Verifica los modelos necesarios y guarda la activación antes del primer inicio.

Para un servicio en ejecución, usa el comando correspondiente de abajo y reinícialo después. La instalación normal y models addons install liveness no activan la función.

Reinicia el servicio tras una instalación correcta. up -d por sí solo no recarga la configuración de un contenedor existente. La función está desactivada por defecto y el registro tiene su propio ajuste liveness_on_registration.

El código fuente del Server y el SDK de Python usan la licencia MIT, pero los archivos y pesos de modelos no están cubiertos por ella. Los paquetes públicos de InsightFace, incluido buffalo_l, se limitan generalmente a investigación académica no comercial salvo autorización comercial independiente de InsightFace; autohospedar el Server no concede derechos comerciales sobre el modelo.

La instalación escribe manifest.json y MODEL.LICENSE firmado en server/.models. verify valida identidad, firma, fechas y autorización vigente. La licencia identifica el modelo y su uso permitido: es una credencial de cumplimiento, no DRM ni una suma de comprobación de los archivos.

Se admiten buffalo_l, buffalo_m, buffalo_s, buffalo_sc, antelopev2, raccoon_s y raccoon_l. Server usa solo detección y reconocimiento de Raccoon, sin su verificador de PrivateFrame. Cambiar de modelo exige una Collection compatible y volver a registrar o migrar los datos.

Los archivos Compose desactivan la autenticación para evaluación aislada. Antes de que accedan otras personas o redes, actívala, guarda una clave API larga y aleatoria en el entorno de secretos y reinicia la pila elegida. La interfaz web puede conservar la clave solo en memoria durante la pestaña actual.

Termina HTTPS en un proxy inverso fiable, permite solo los orígenes necesarios en vez de CORS amplio, aplica límites de tasa, cuerpo y tiempo y restringe Docker, /data, /models y copias. Nunca registres imágenes, embeddings, credenciales RTSP ni claves API.

Conserva /data, modelos y server/config. Respalda SQLite y los recortes juntos sin escrituras, o con una instantánea segura para SQLite. Protégelos como datos biométricos y activa autenticación por API key y HTTPS antes de exponer el servicio.

Usa el comando down completo de la pila arrancada. down normal elimina contenedores y red, pero conserva el volumen. Nunca añadas -v: docker compose down -v elimina permanentemente el volumen de datos.

Ambos contenedores se ejecutan como root (0:0), con un único montaje /models y el directorio de configuración escribibles. Los directorios de modelos y addons/ se crean cuando hacen falta. No se requieren UID/GID del equipo ni ajustes manuales de permisos. El sistema de archivos raíz del contenedor sigue siendo de solo lectura.

Detén las escrituras y respalda la base de datos y los recortes. Actualiza los archivos de despliegue e incorpora tus ajustes, conservando server/config/server.toml, modelos, nombres originales del proyecto y volumen, puertos y API key. Usa el archivo Compose correspondiente y añade tus archivos de personalización y nombre de proyecto cuando proceda.

Descarga ambas imágenes y recrea Server. restart no aplica imágenes ni montajes nuevos. Comprueba salud, proveedor, datos existentes y una búsqueda conocida. El mismo modelo y contrato de embeddings conservan las muestras; cambiar de modelo requiere una migración aparte. Actualiza el SDK desde el mismo repositorio actualizado.

Empieza por health y revisa System, estado del contenedor y logs de la pila elegida. En CUDA, el fallo de arranque es deliberado si fallan Driver, GPU, sesiones, CUDAExecutionProvider, auditoría del proveedor o calentamiento; no existe retorno silencioso a CPU.

Cada respuesta lleva x-request-id y los errores incluyen request_id. Conserva ese valor con los logs pertinentes. 401 unauthorized suele indicar clave ausente o rotada; 409 collection_model_mismatch, otro contrato de modelo; 422 face_not_found, que no se seleccionó un rostro utilizable.

CUDA debe informar CUDAExecutionProvider. El arranque valida GPU, Driver, CUDA/cuDNN/ONNX Runtime, sesiones reales de detector y reconocedor, ubicación del proveedor e inferencia de calentamiento. Si algo falla, termina en vez de pasar silenciosamente a CPU.