Server con Docker: inicio rápido
Inicia InsightFace Server en CPU o CUDA con Docker, instala un modelo con licencia, ejecuta la primera búsqueda 1:N exacta y protege el servicio.
Qué vas a construir
InsightFace Server reúne detección, comparación, registro, búsqueda exacta 1:N de personas, una interfaz web multilingüe, REST API, SQLite e inferencia local en un único servicio autohospedado. Las imágenes, embeddings, modelos e índices pueden permanecer en tu propia infraestructura.
Este inicio rápido parte de un checkout completo de InsightFace y termina con una búsqueda funcional. También cubre los límites previos a producción: autorización del modelo, autenticación, HTTPS, persistencia, parada segura y diagnóstico CUDA con fallo inmediato.
El Server es una alternativa orientada a la privacidad para flujos habituales de reconocimiento facial, no un reemplazo compatible con AWS Rekognition. No implementa AWS IAM, SigV4, semántica de Region, TLS integrado, cuentas de usuario ni RBAC.
Antes de empezar
- Un checkout completo de InsightFace en Linux x86_64 con Docker Engine y Docker Compose.
- Para CUDA 12: GPU NVIDIA compatible, NVIDIA Driver y NVIDIA Container Toolkit. El host no necesita CUDA Toolkit, cuDNN, ONNX Runtime, Python ni OpenCV.
- Acceso de red para descargar el contenedor e instalar el modelo. Después, el arranque normal puede mantenerse sin conexión.
- Autorización para tratar datos biométricos y políticas documentadas de consentimiento, acceso, retención, eliminación, copia de seguridad y respuesta a incidentes.
1. Elegir CPU o CUDA e instalar el modelo
Ejecuta los comandos desde la raíz de un checkout completo y elige una sola pila Compose. CPU es la vía de evaluación más sencilla y publica el puerto 18097. CUDA publica el 18098 y necesita un Driver compatible y NVIDIA Container Toolkit; no instales CUDA ni cuDNN en el host para este contenedor.
Los comandos usan deliberadamente --accept-license sin interacción y verifican buffalo_l inmediatamente. Ejecútalos solo tras revisar y aceptar los términos del modelo en tu organización. El instalador también admite buffalo_m, buffalo_sc y antelopev2.
- Turing, Ampere, Ada y Hopper requieren Driver R535 o posterior; Blackwell y RTX serie 50 requieren 570.26 o posterior. Para instalaciones nuevas se recomienda una versión estable R580 o posterior.
- Las imágenes públicas no contienen modelos, datos de clientes, claves API ni configuración de producción.
- No mezcles los archivos Compose de CPU y CUDA: usan imágenes, puertos, proveedores y volúmenes de datos con nombre diferentes.
mkdir -p server/.models
docker compose -f server/deploy/compose.cpu.yml pull
docker compose -f server/deploy/compose.cpu.yml \
run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cpu.yml \
run --rm models verify buffalo_lmkdir -p server/.models
docker compose -f server/deploy/compose.cuda12.yml pull
docker compose -f server/deploy/compose.cuda12.yml \
run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cuda12.yml \
run --rm models verify buffalo_l2. Entender el límite de la licencia del modelo
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.
- Sin --accept-license, la herramienta muestra los términos y sale sin descargar.
- Conserva juntos modelo, manifest y licencia, y monta /models en modo de solo lectura durante el servicio normal.
- Consulta con InsightFace antes de uso comercial o si el alcance no está claramente cubierto por los términos públicos.
3. Arrancar el servicio y confirmar que está listo
Arranca solo la pila instalada. Abre http://SERVER:18097/ para CPU o http://SERVER:18098/ para CUDA. Después de comprobar health, revisa Dashboard o System antes de registrar datos y confirma que servicio, base de datos, modelo y proveedor de ejecución estén listos.
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.
docker compose -f server/deploy/compose.cpu.yml up -d
curl -fsS http://127.0.0.1:18097/v1/healthdocker compose -f server/deploy/compose.cuda12.yml up -d
curl -fsS http://127.0.0.1:18098/v1/health4. Completar el primer flujo Collection → Person → Search
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 o WebP 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.
- Los originales no se conservan por defecto. El almacenamiento opcional guarda un recorte JPEG 112×112 del cuadro, no el original ni la entrada alineada de reconocimiento.
- Las muestras aceptadas se confirman en SQLite y se añaden al índice exacto en memoria antes de responder con éxito. Tras reiniciar, se reconstruye desde SQLite.
- Detect sin rostro es un resultado vacío válido; Compare devuelve 422 face_not_found si un lado no tiene un rostro utilizable.
5. Proteger el servicio antes de exponerlo a la red
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.
- La primera fase tiene una única clave sin roles; no es autorización multiinquilino y no incluye cuentas ni RBAC.
- Arrancar después el mismo volumen con otro INSIGHTFACE_API_KEY rota intencionadamente la clave activa.
- El Server no ofrece TLS integrado ni una capa de cumplimiento legal; el tratamiento lícito y los controles son responsabilidad del operador.
export INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cpu.yml up -dexport INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cuda12.yml up -d6. Conservar datos, hacer copias y detener con seguridad
SQLite en /data es la fuente duradera; los índices exactos en memoria son desechables. Compose monta los modelos en solo lectura y guarda /data en un volumen con nombre. Copia SQLite y el almacenamiento de recortes juntos con las escrituras detenidas o mediante una instantánea segura para SQLite.
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.
- Antes de actualizar, crea una instantánea segura, conserva /models y las licencias y prueba la nueva imagen primero con una copia de los datos.
- Después comprueba migraciones, /v1/health, contrato del modelo y una búsqueda conocida.
- Eliminar un FaceSample borra embedding y recorte opcional; una Collection no vacía exige confirmación force.
docker compose -f server/deploy/compose.cpu.yml downdocker compose -f server/deploy/compose.cuda12.yml down7. Diagnosticar fallos de arranque y solicitudes
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.
- Confirma en System que CPUExecutionProvider o CUDAExecutionProvider coincide con el Compose elegido.
- Comprueba el paquete verificado y la licencia firmada en server/.models y que /models sea de solo lectura.
- En CUDA corrige Driver, visibilidad de GPU o NVIDIA Container Toolkit; no esperes un fallback a CPU.
curl -fsS http://127.0.0.1:18097/v1/health
docker compose -f server/deploy/compose.cpu.yml ps
docker compose -f server/deploy/compose.cpu.yml logs --tail=200 servercurl -fsS http://127.0.0.1:18098/v1/health
docker compose -f server/deploy/compose.cuda12.yml ps
docker compose -f server/deploy/compose.cuda12.yml logs --tail=200 server¿Necesitas ayuda con el despliegue en producción?
Contacta con InsightFace para licencias de modelos, optimización de runtime y soporte de despliegue en tu hardware objetivo.
Enviar consulta empresarial