Server avec Docker : démarrage rapide
Lancez InsightFace Server sur CPU ou CUDA avec Docker, installez un modèle sous licence, exécutez une première recherche 1:N exacte et sécurisez le service.
Ce que vous allez mettre en place
InsightFace Server réunit détection, comparaison, enrôlement, recherche exacte 1:N de personnes, interface Web multilingue, API REST, SQLite et inférence locale dans un service auto-hébergé. Images, embeddings, modèles et index peuvent rester dans votre infrastructure.
Ce guide part d'un checkout InsightFace complet et aboutit à une recherche fonctionnelle. Il couvre aussi les limites à traiter avant la production : autorisation du modèle, authentification, HTTPS, persistance, arrêt sûr et diagnostic CUDA à échec immédiat.
Le Server est une solution respectueuse de la confidentialité pour les workflows courants, pas un remplacement compatible AWS Rekognition. Il n'implémente ni AWS IAM, SigV4, sémantique Region, TLS intégré, comptes utilisateurs ou RBAC.
Avant de commencer
- Un checkout InsightFace complet sur Linux x86_64 avec Docker Engine et Docker Compose.
- Pour CUDA 12 : GPU NVIDIA pris en charge, NVIDIA Driver et NVIDIA Container Toolkit. CUDA Toolkit, cuDNN, ONNX Runtime, Python et OpenCV ne sont pas requis sur l'hôte.
- Un accès réseau pour récupérer le conteneur et installer le modèle. Le démarrage normal peut ensuite rester hors ligne.
- L'autorisation de traiter des données biométriques et des règles documentées de consentement, accès, conservation, suppression, sauvegarde et réponse aux incidents.
1. Choisir CPU ou CUDA et installer le modèle
Exécutez les commandes à la racine d'un checkout complet et choisissez une seule pile Compose. CPU est le chemin d'évaluation le plus simple et publie le port 18097. CUDA publie le port 18098 et nécessite un Driver compatible et NVIDIA Container Toolkit ; n'installez ni CUDA ni cuDNN sur l'hôte.
Les commandes utilisent volontairement --accept-license sans interaction, puis vérifient buffalo_l. Ne les lancez qu'après examen et acceptation des conditions par votre organisation. L'outil prend aussi en charge buffalo_m, buffalo_sc et antelopev2.
- Turing, Ampere, Ada et Hopper exigent Driver R535 ou ultérieur ; Blackwell et RTX série 50 exigent 570.26 ou ultérieur. Une version stable R580 ou ultérieure est recommandée.
- Les images publiques ne contiennent ni modèles, données client, clés API ou configuration de production.
- Ne mélangez pas les fichiers Compose CPU et CUDA : images, ports, providers et volumes nommés sont distincts.
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. Comprendre la limite de licence du modèle
Le code source du Server et le SDK Python sont sous licence MIT, mais les fichiers et poids de modèles n'en relèvent pas. Les paquets publics InsightFace, dont buffalo_l, sont généralement réservés à la recherche académique non commerciale sans autorisation commerciale distincte d'InsightFace ; l'auto-hébergement n'accorde aucun droit commercial sur le modèle.
L'installation écrit manifest.json et MODEL.LICENSE signé dans server/.models. verify contrôle identité, signature, validité et autorisation. Cette licence décrit le modèle et l'usage permis : c'est un justificatif de conformité, pas un DRM ni une somme de contrôle des fichiers.
- Sans --accept-license, l'outil affiche les conditions et quitte sans télécharger.
- Conservez modèle, manifest et licence ensemble, et montez /models en lecture seule en fonctionnement normal.
- Contactez InsightFace avant un usage commercial ou si les conditions publiques ne couvrent pas clairement votre périmètre.
3. Démarrer le service et confirmer son état
Démarrez uniquement la pile installée. Ouvrez http://SERVER:18097/ pour CPU ou http://SERVER:18098/ pour CUDA. Après health, vérifiez avant tout enrôlement dans Dashboard ou System que service, base, modèle et provider d'exécution sont prêts.
CUDA doit annoncer CUDAExecutionProvider. Au démarrage, GPU, Driver, CUDA/cuDNN/ONNX Runtime, sessions réelles de détection et reconnaissance, placement du provider et inférence de préchauffage sont validés. Le service s'arrête en cas d'échec au lieu de revenir silencieusement au 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. Réaliser le premier parcours Collection → Person → Search
Dans Collections, créez un ID stable tel que employees. Choisissez un profil annoncé par System, dimensionnez capacity selon la mémoire et commencez au seuil de cosinus brut par défaut 0,4. Une Collection est liée à l'identité et au digest du modèle, à la dimension, au prétraitement et au profil de détection.
Dans People, sélectionnez la Collection et inscrivez une Person avec une ou plusieurs images JPEG, PNG ou WebP nettes. standard review constitue un bon départ : un seul visage exploitable est exigé et taille, confiance, netteté, luminosité et pose sont contrôlées. Un lot peut réussir partiellement ; examinez chaque motif de rejet.
Dans Search, choisissez la même Collection et chargez une autre photo de cette Person. Les résultats sont triés par similarité cosinus brute et le score d'une Person est le meilleur parmi ses FaceSamples. La similarité n'est pas une probabilité. Aucun résultat renvoie normalement une liste vide.
- Les originaux ne sont pas conservés par défaut. Le stockage optionnel garde un crop JPEG 112×112 de la boîte, pas l'original ni l'entrée alignée de reconnaissance.
- Les échantillons acceptés sont validés dans SQLite puis ajoutés à l'index exact en mémoire avant la réponse. L'index est reconstruit depuis SQLite au redémarrage.
- Aucun visage est un résultat vide valide pour Detect ; Compare renvoie 422 face_not_found si un côté n'a pas de visage exploitable.
5. Sécuriser avant toute exposition réseau
Les fichiers Compose désactivent l'authentification pour une évaluation isolée. Avant tout accès externe, activez-la, stockez une longue clé API aléatoire dans l'environnement secret et redémarrez la pile choisie. L'interface Web peut garder la clé uniquement en mémoire dans l'onglet courant.
Terminez HTTPS sur un reverse proxy de confiance, limitez CORS aux origines nécessaires, appliquez limites de débit, corps et délai en périphérie, et protégez Docker, /data, /models et sauvegardes. Ne journalisez jamais images, embeddings, identifiants RTSP ou clés API.
- La phase un dispose d'une clé unique sans rôles ; ce n'est pas une autorisation multi-tenant et il n'existe ni comptes ni RBAC intégrés.
- Redémarrer le même volume avec un autre INSIGHTFACE_API_KEY fait volontairement tourner la clé active.
- Le Server ne fournit ni TLS intégré ni couche de conformité juridique ; traitement licite et contrôles restent à la charge de l'opérateur.
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. Conserver, sauvegarder et arrêter sans risque
SQLite dans /data est la source durable ; les index exacts en mémoire sont jetables. Compose monte les modèles en lecture seule et garde /data dans un volume nommé. Sauvegardez ensemble SQLite et les crops configurés pendant l'arrêt des écritures, ou avec une méthode de snapshot sûre pour SQLite.
Utilisez la commande down complète de la pile démarrée. down normal retire conteneurs et réseau mais conserve le volume. N'ajoutez jamais -v : docker compose down -v supprime définitivement le volume de données.
- Avant mise à niveau, créez un snapshot sûr, gardez /models et ses licences, puis testez la nouvelle image sur une copie.
- Vérifiez ensuite migrations, /v1/health, contrat du modèle et une recherche connue.
- Supprimer un FaceSample efface embedding et crop éventuel ; une Collection non vide exige une confirmation force.
docker compose -f server/deploy/compose.cpu.yml downdocker compose -f server/deploy/compose.cuda12.yml down7. Diagnostiquer les échecs de démarrage et de requête
Commencez par health, puis examinez System, l'état des conteneurs et les logs de la pile. Sous CUDA, l'arrêt au démarrage est volontaire si Driver, GPU, sessions, CUDAExecutionProvider, audit du provider ou préchauffage échouent ; aucun retour silencieux au CPU n'existe.
Chaque réponse porte x-request-id et les erreurs contiennent request_id. Conservez cet identifiant avec les logs correspondants. 401 unauthorized indique souvent une clé absente ou tournée ; 409 collection_model_mismatch un autre contrat ; 422 face_not_found qu'aucun visage exploitable n'a été sélectionné.
- Dans System, confirmez que CPUExecutionProvider ou CUDAExecutionProvider correspond au Compose choisi.
- Vérifiez paquet et licence signée dans server/.models et le montage /models en lecture seule.
- Sous CUDA, corrigez Driver hôte, visibilité GPU ou NVIDIA Container Toolkit au lieu d'attendre un fallback 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 serverBesoin d’aide pour le déploiement en production ?
Contactez InsightFace pour les licences de modèles, l’optimisation runtime et le support de déploiement sur votre matériel cible.
Envoyer une demande entreprise