Guía de InsightFace 1.0: reconocimiento facial local, GUI de escritorio y evaluación empresarial
Instala el paquete InsightFace 1.0 más ligero, abre Evaluation Studio multiplataforma y ejecuta reconocimiento local, organización de álbumes, evaluación de datasets por identidad, pruebas de face swap y revisión de licencias y privacidad.
Qué vas a construir
InsightFace 1.0 conserva la API Python FaceAnalysis y al mismo tiempo reduce el peso del paquete base. La extensión opcional face3d Cython/C++ ya no se compila por defecto, por lo que la mayoría de usuarios puede instalar el core package sin una toolchain local de compilación.
La versión también introduce InsightFace Evaluation Studio, una GUI de escritorio PySide6 multiplataforma disponible mediante el package extra. Desarrolladores, investigadores y evaluadores empresariales obtienen un workspace local para reconocimiento facial, clustering de álbumes, evaluación de datasets y pruebas de face swap.
La versión 1.0 también elimina algunas dependencias innecesarias.
Antes de empezar
- Python 3.9+ con virtual environment. Usa el GUI extra solo en equipos donde las dependencias de escritorio sean aceptables.
- Un model cache local o permiso para descargar model packs en el directorio de modelos de InsightFace.
- Imágenes representativas o datasets con identity folders para el workflow que quieras probar.
- Políticas claras de consentimiento, retención y autorización de despliegue antes de procesar datos biométricos o ejecutar experimentos de face swap.
1. Qué cambió en InsightFace 1.0
El paquete base de Python ahora es más fácil de instalar porque la extensión opcional face3d no se compila por defecto. Esto no significa que se haya eliminado todo el código C++ del repositorio; significa que quienes solo necesitan detección, alineamiento y reconocimiento no pagan el coste de compilación por defecto.
La nueva GUI demo se entrega como extra opcional, no como instalador de escritorio independiente. Instala insightface[gui] cuando quieras la experiencia de escritorio y lánzala desde la línea de comandos en macOS, Windows o Linux.
- Face Recognition mode: una query image más una o varias gallery images para verificación 1:1 o búsqueda local 1:N.
- Album Management mode: importa carpetas locales, extrae features, agrupa rostros con DBSCAN y revisa grupos de personas.
- Enterprise Evaluation mode: evaluación local 1:1 y 1:N con identity folders, validación, métricas y salida de reportes.
- Face Swap mode: workflow source plus target para pruebas con imagen o video cuando hay un swap model compatible configurado.
- Models, License y Settings dialogs: controlan runtime provider, model roots, descargas manuales, autorización, tema e idioma.
2. Instalar el paquete Python más ligero
Para servicios Python, notebooks y experimentos de línea de comandos, empieza por el base package. Mantiene la API FaceAnalysis y el comportamiento de modelos por defecto sin instalar todo el stack de escritorio.
Una smoke test mínima debe crear una FaceAnalysis app, prepararla en CPU, cargar el modelo buffalo_l si ya está disponible en la cache de InsightFace y devolver face boxes, landmarks y embeddings de reconocimiento de 512 dimensiones. Por defecto se usa detección SCRFD y el tamaño de detección es Auto: 128x128 más 640x640.
pip install insightfaceimport insightface
from insightface.app import FaceAnalysis
from insightface.data import get_image
app = FaceAnalysis(providers=["CPUExecutionProvider"])
app.prepare(ctx_id=-1)
faces = app.get(get_image("t1"))
print(len(faces), faces[0].embedding.shape)3. Instalar y lanzar la GUI demo
Instala las dependencias GUI solo cuando necesites Evaluation Studio de escritorio. El workspace de la GUI usa por defecto ~/.insightface/gui, donde settings, indexes, thumbnails, reportes generados y resultados guardados pueden quedar separados del código del proyecto.
La GUI debería abrir incluso si faltan modelos. Usa el Models dialog para refrescar model URLs, descargar model packs manualmente, elegir ONNX Runtime providers o apuntar la app a un custom model directory.
- La GUI no descarga modelos automáticamente.
- Images, videos, embeddings, thumbnails y reports se procesan localmente por defecto y no se suben automáticamente.
- Las capturas de esta guía están en inglés, pero la GUI app soporta varios idiomas; cambia el idioma de la interfaz desde Settings.
- Usa un virtual environment para que PySide6 y las dependencias solo-GUI no afecten despliegues de servidor.
pip install "insightface[gui]"
insightface-guiinsightface-eval-studio
insightface-desktop
python -m insightface.gui4. Ejecutar Face Recognition mode
Usa Face Recognition mode cuando quieras probar identity matching rápido sin escribir código. Sube una query image y añade una gallery image para comparación 1:1, o varias gallery images y folders para búsqueda local 1:N.
Los gallery embeddings se mantienen en memoria hasta que cambia la gallery. Si una imagen contiene varios rostros, elige la multi-face handling policy adecuada para la prueba; el valor práctico por defecto es largest centered face. Mantén visible y configurable el recognition threshold, porque los umbrales de producción deben elegirse con tus propios datos de validación.
5. Organizar fotos locales con Album Management
Album Management está pensado como organizador local inteligente de fotos. Añade uno o más local album directories y ejecuta Import / Refresh para reescanear carpetas y extraer features de nuevas imágenes. Rebuild All borra features indexados y recalcula los clusters desde cero.
El workflow de clustering usa DBSCAN con un cosine similarity threshold. Face thumbnails y photo thumbnails se guardan localmente en SQLite como blobs WebP comprimidos, y al seleccionar un cluster se muestran las fotos originales de ese grupo de persona.
6. Evaluar datasets empresariales localmente
Enterprise Evaluation mode ayuda a los equipos a probar InsightFace con sus propios datos antes de decisiones de despliegue o compra. Soporta evaluación 1:1 y 1:N desde identity folders, y Auto Split puede derivar gallery/probe splits desde cada identity folder cuando el dataset aún no está separado.
Antes de calcular métricas, usa dataset validation para detectar problemas de layout y critical face validity issues. Los reportes deberían incluir model/runtime, dataset summary, thresholds, best-threshold accuracy, Top-1, TAR@FAR cuando los sample counts lo permitan, errors, latency, license status, responsible-use notes y recommended next steps.
- Usa carpetas gallery, probe y unknown explícitas cuando necesites una evaluación open-set 1:N controlada.
- Usa Auto Split para exploración temprana y luego congela un dedicated test split antes de comparar modelos.
- Los reportes se generan localmente y no se suben automáticamente.
dataset_1n/
gallery/
0001__Alice/
enroll_001.jpg
enroll_002.jpg
0002__Bob/
enroll_001.jpg
probe/
0001__Alice/
test_001.jpg
0002__Bob/
test_001.jpg
unknown/
unknown_001.jpgdataset/
identities/
0001__Alice/
img001.jpg
img002.jpg
img003.jpg
0002__Bob/
img001.jpg
img002.jpg7. Probar Face Swap mode con cautela
Face Swap mode es un workflow local source plus target. El target puede ser una imagen o un video, el swap model configurado se carga solo cuando se ejecuta el swap, y los resultados se guardan en el local workspace.
El post-processing opcional GFPGAN puede activarse después de descargar el third-party model. Trata las pruebas de face swap como una ruta de autorización separada: necesitas derechos, consentimiento y model permission adecuados antes de usar source identities o publicar resultados generados.
8. Configurar modelos, ajustes, licencia y privacidad
En Models eliges runtime model, provider, detection size, swap model, GFPGAN setting, download location y custom model root. También es el lugar donde evaluadores pueden separar commercial o private model artifacts de public model packs.
En License revisas la diferencia entre code licenses y model licenses. Los model files pueden tener derechos distintos del package code, y el commercial deployment exige la model authorization correcta. InsightFace 1.0.1 elimina el PyPI package metadata license field, pero la README license guidance sigue siendo la fuente a leer.
Todo el procesamiento es local por defecto. No se suben automáticamente images, videos, embeddings ni reports. Los usuarios son responsables de consent, privacy, retention y cumplimiento con biometric regulations aplicables; esta guía es documentación práctica de producto, no asesoría legal.
9. Siguientes pasos comerciales
Contacta con InsightFace cuando necesites commercial model licensing, private model evaluation, SDK/API access, compromisos SLA, entrega on-prem o custom training. Evaluation Studio es útil para un technical screening inicial, pero la autorización de producción depende del model, data, use case y deployment contract.
- Usa open-source packs para experiments, prototypes y deployments permitidos dentro de su license scope.
- Usa private evaluation cuando necesites comparar commercial recognition models más fuertes en tus propios identity-folder datasets.
- No trates la disponibilidad de la GUI como permiso para desplegar un modelo comercialmente; verifica la model authorization por separado.
¿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