CV-Matching / README.md
Myz0's picture
Deuxième avis IA (gpt-oss-120b) : bouton sur la page
c76923f verified
|
Raw History Blame Contribute Delete
35.8 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade
metadata
title: HackAVP Matching CV AVP
emoji: 🔎
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.30.0
python_version: '3.10'
app_file: app_zerogpu.py
pinned: false
short_description: Matching explicable entre CV et AVP de l'OPT-NC

HackAVP — Microservice de matching CV ↔ AVP

Rapproche des CV (JSON Resume) des avis de vacance de poste (AVP) de l'OPT-NC publiés en open data (opt-nc/odata-avps), avec le modèle d'embeddings open source BAAI/bge-m3. Le résultat est explicable : chaque point fort cite la ligne du CV qui répond à l'attendu de l'AVP.

Deux sens, un seul moteur de score :

Sens Question Route
Candidat « Quels AVP me correspondent ? » POST /v1/match
Recruteur « Qui, dans mon vivier, correspond le mieux à cet AVP ? » POST /v1/avps/{id_avp}/candidats
Candidature « Ce CV, pour cette offre ? » POST /v1/score

⚠️ Utilisez uniquement des CV fictifs ou le vôtre (règle du HackAVP). Le service ne lit jamais le nom, l'e-mail ni le téléphone, et n'enregistre aucun CV.

Lancer en local

python -m venv .venv
.venv\Scripts\activate            # Windows   (Linux/Mac : source .venv/bin/activate)
pip install -r requirements.txt
uvicorn app.main:app --port 7860

Les versions des bibliothèques (requirements.txt) et des modèles (MODEL_REVISION, RERANKER_REVISION) sont figées : celles avec lesquelles le service a été évalué. Une mise à jour se fait exprès, puis on relance les tests et scripts.evaluer_classement.

Le premier démarrage télécharge bge-m3 (~2 Go), puis encode tous les AVP : compter quelques minutes sur CPU. Le GPU est utilisé automatiquement s'il est disponible.

curl -X POST "http://localhost:7860/v1/match?top=3" \
     -H "Content-Type: application/json" -d @exemples/cv_juriste_fictif.json

Endpoints

Méthode Route Rôle
GET /v1/health Modèle, appareil (CPU/GPU), nombre d'AVP et d'AVP ouverts
GET /v1/avps AVP chargés : ouvert ou clos, date limite, attendus, prérequis, conditions
POST /v1/match?top=10&tri=qualite|couverture&inclure_fermes=false CV → AVP classés + explications
POST /v1/avps/{id_avp}/candidats?top=20 Corps {"cvs": [CV, ...]} (50 CV au plus) → vivier classé + explications
POST /v1/score Corps {"reference": "3134-26-1419/SR", "cv": CV} → score, pourcentage, libellé, preuves pour UN AVP
POST /v1/avps/refresh Relit le dataset (nouveaux AVP, AVP modifiés ou retirés). Clé principale seulement (403 avec une clé d'équipe)
POST /v1/hub/avps/{id_avp}/candidatures?top=20&inclure_annulees=false Classe les candidats qui ont postulé à cet AVP sur le hub de la promo (CV lus sur le hub)
POST /v1/hub/profils/{user_id}/match?top=10 Les AVP qui correspondent au CV d'un profil du hub

Interopérabilité avec le hub de la promotion

Le hub (API HACKAVP, https://hackavp-api.duckdns.org/swagger-ui) garde les profils des candidats, leur CV (saisi, ou généré par n8n à partir du document déposé) et leurs candidatures. Les deux routes /v1/hub/... vont y chercher les CV : un recruteur classe les candidats d'une offre sans rien copier.

Recruteur ──(X-API-Key + X-Hub-Token)──> CV-Matching ──(son jeton)──> Hub : GET /candidatures, GET /profils/{id}
                                             │
                                             └─> classement expliqué, relié aux candidatures du hub
  • Pas de compte du service sur le hub : l'appelant envoie, en plus de la clé du service, son jeton hub (X-Hub-Token : l'accessToken de POST /auth/login du hub, valable 1 heure), que le service transmet tel quel. C'est le hub qui vérifie les droits : un recruteur ou un admin lit les candidatures et les profils, un candidat seulement son propre profil (403 sinon). Le service ne garde ni jeton, ni mot de passe, ni CV.
  • Clé commune : la référence de l'AVP (avpReference du hub = id_avp du service, ex. 3134-26-1419/SR).
  • Format : le CV du hub est « à structure libre ». Un CV au format JSON Resume est lu comme d'habitude ; sinon, le service lit tous ses textes, sauf l'identité (nom, prénom, e-mail, téléphone, adresse, date de naissance, nationalité…) et les valeurs sans mots (dates, numéros).
  • Réponse : le classement habituel, plus candidatures_hub (pour chaque candidat : identifiant et statut de sa candidature sur le hub, identifiant du profil). Ni nom ni e-mail ne sont renvoyés. Les candidatures ANNULEE sont ignorées (sauf inclure_annulees=true) ; un profil sans CV est écarté.
  • Erreurs : 401 (jeton hub absent, invalide ou expiré), 403 (le compte hub n'a pas les droits), 404 (AVP ou profil inconnu), 502 (hub injoignable).
# 1. Jeton hub (compte recruteur), valable 1 heure
curl -X POST "https://hackavp-api.duckdns.org/auth/login" -H "Content-Type: application/json" \
     -d '{"email": "<e-mail>", "password": "<mot de passe>"}'
# 2. Classement des candidats d'une offre
curl -X POST "https://myz0-cv-matching.hf.space/v1/hub/avps/3134-26-1419/SR/candidatures" \
     -H "X-API-Key: <clé du service>" -H "X-Hub-Token: <accessToken>"

Documentation interactive : /docs (en ligne : https://myz0-cv-matching.hf.space/docs).

Version de l'API. Les routes portent leur version (/v1/...). Un changement incompatible (champ retiré, sens d'un champ modifié) passera par /v2, et /v1 restera en place le temps que les équipes qui l'appellent migrent. Les anciennes adresses sans /v1 (/match, /score…) répondent toujours, à l'identique, mais n'apparaissent plus dans /docs.

Limites. Un vivier compte au plus 50 CV (MAX_CV_VIVIER), un CV au plus 50 000 caractères de texte (MAX_CARACTERES_CV, un CV en compte en général moins de 10 000) : au-delà, réponse 422 avec la raison (dans un vivier, seul le CV trop long est écarté). Une requête de plus de 5 Mo (MAX_OCTETS_REQUETE) est refusée (413) avant d'être lue. Ces limites valent aussi pour l'API Gradio, le MCP et la page web.

Clé API. Dès qu'une clé est configurée (API_KEY ou des clés d'équipe), les routes de calcul (/v1/match, /v1/score, /v1/avps/{id_avp}/candidats, /v1/avps/refresh) et les outils de l'API Gradio et du MCP (matcher_cv, classer_candidats) exigent l'en-tête X-API-Key (sinon 401, ou une erreur Gradio) ; /v1/health et /v1/avps restent publiques. La clé est vérifiée avant de demander la carte graphique : un appel refusé ne consomme pas de quota. La page web reste ouverte à tous. Sur le Space, la clé est un secret ; elle se transmet par privatebin « burn after reading », jamais par e-mail ni dans le code.

Une clé par équipe. La clé principale (API_KEY) reste celle du responsable du service ; chaque équipe qui appelle l'API reçoit sa propre clé, qu'on peut révoquer seule, et le journal indique quelle équipe appelle. Le service ne garde que l'empreinte SHA-256 de chaque clé (secret API_KEYS_HASH) : même ce secret ne permet pas de retrouver une clé.

python -m scripts.cles_api nouvelle equipe-hub --space   # clé écrite dans cles_api/equipe-hub.txt (jamais affichée)
python -m scripts.cles_api revoquer equipe-hub --space   # l'équipe n'a plus accès
python -m scripts.cles_api liste

La clé créée est à envoyer par privatebin, puis son fichier à supprimer (cles_api/ est ignoré par git). --space met à jour le secret du Space, qui redémarre (~1-2 min).

Client MCP (ex. configuration JSON d'un agent) : l'outil déclare l'en-tête qu'il attend.

{"mcpServers": {"cv-matching": {"url": "https://myz0-cv-matching.hf.space/gradio_api/mcp/",
                                "headers": {"X-API-Key": "<clé>"}}}}
curl -X POST "https://myz0-cv-matching.hf.space/v1/score" -H "X-API-Key: <clé>" \
     -H "Content-Type: application/json" \
     -d '{"reference": "3134-26-1419/SR", "cv": {...}}'

Comment le score est calculé

  1. Chaque AVP est découpé en trois groupes :

    • attendus (responsibilities, skills, educationRequirements.competencyRequired, experienceRequirements) : les seuls notés ;
    • prérequis (qualifications, credentialCategory, et les années d'experienceRequirements) : jamais notés ni éliminatoires, vérifiés par des règles (app/prerequis.py) car ce sont des niveaux et des équivalences, pas du sens : diplôme (Master = Bac+5 ≥ Bac+3 ; BTS = Bac+2 < Bac+3), permis (VL = B, PL = C, A2, CACES pour « cariste », deux-roues), années d'expérience (dates des postes ou « 6 ans en… »), « obligatoire » ou « apprécié ». Statut affiché avec sa preuve : ✓ rempli, ✗ niveau inférieur, ? non indiqué (un permis absent du CV reste « ? »). Le recruteur décide ;
    • conditions du poste (durée de résidence, contraintes horaires, conditions physiques) : un CV ne peut pas les prouver ; affichées dans la fiche et renvoyées par /avps, jamais notées ;
    • contexte (titre, famille de métier, description…) : sert au score_global.
  2. Poids de chaque attendu = poids du champ × spécificité. La spécificité est calculée sur l'ensemble des AVP, comme l'IDF d'un moteur de recherche : « Maîtrise de soi », présent dans presque tous les AVP, pèse presque 0 ; « Routage BGP et OSPF », présent dans un seul, pèse 1. Aucune liste écrite à la main : la méthode s'applique à n'importe quelle administration.

  3. Pour chaque attendu, on calcule un degré de couverture entre 0 et 1, en gardant la meilleure de deux notes :

    • la rampe bge-m3 : cosinus avec la phrase du CV la plus proche, 0 sous SIM_BAS, 1 au-dessus de SIM_HAUT, linéaire entre les deux. bge-m3 donne ~0,45 pour deux phrases sans rapport : la rampe étale la plage utile sur 0..1. Elle repère bien les reformulations ;
    • le reranker bge-reranker-v2-m3 : il relit l'attendu avec les 3 phrases du CV les plus proches (choisies par bge-m3) et juge si la phrase correspond vraiment à l'attendu (~0 sans rapport, ~1 correspond). Il écarte le bruit que la rampe laisse passer. Il ne vérifie ni la véracité ni le niveau : c'est le rôle de l'entretien.
  4. Score de classement (ou adéquation, /100) = moyenne pondérée des degrés sur tous les attendus, savoir-être compris : chaque attendu rapporte poids × degré points et en perd poids × (1 − degré) ; obtenus + perdus = 100. C'est lui qui trie les AVP et les candidats (sortir les savoir-être du tri dégrade le classement).

  5. Pourcentage affiché (pourcentage_competences) = le même calcul sur les seules compétences (savoir-faire), sans les savoir-être qu'un CV écrit rarement, avec le décompte « x / N compétences du poste » (attendus de degré ≥ SEUIL_COUVERTURE). Exemple : un auditeur à 45/100 couvre 56 % des compétences du poste (8/15).

  6. Avis (libelle, niveau) : ce qu'un recruteur ferait de ce profil, lu sur le pourcentage affiché (entier) :

    Pourcentage affiché Avis niveau
    ≥ 22 % Profil adapté (à convoquer) adapte
    ≥ 17 % Profil à étudier a_etudier
    < 17 % Profil peu adapté peu_adapte

    Les seuils (SEUILS_LIBELLE) sont réglés sur des notes humaines (jeu d'évaluation n° 2, ci-dessous), pas lus comme une fraction du poste : même un CV qui fait exactement le métier ne prouve mot pour mot qu'une partie des compétences d'un AVP (13 à 46 %, médiane 27 %). Les anciens libellés (« Bonne adéquation » dès 33 %…) ne reconnaissaient aucun des 21 profils à convoquer, et en marquaient 7 « faible ». La page web affiche l'échelle sous l'avis. Le front (app/front/) affiche aussi la décomposition, et pour chaque attendu la similarité bge-m3, la note du reranker, le degré retenu et la ligne du CV qui y répond.

  7. Outils cités dans le CV (Excel, SAP, ITIL…) : une phrase qui cite un outil connu du ROME 4.0 (France Travail) est complétée, pour le calcul seulement, par les savoirs ROME qui le citent : « Excel, Word, PowerPoint » est lue « Excel, Word, PowerPoint (Maîtrise du pack Office (…) ; Maîtrise des outils informatiques et bureautiques (Word, Excel, PowerPoint)) ». Elle rejoint ainsi l'attendu « Maîtriser les outils de bureautique » (24 % -> 84 %). Les phrases sans outil ne sont pas touchées et la fiche affiche toujours la phrase d'origine (app/outils.py, données app/outils_rome.json générées par scripts/generer_outils_rome.py). Comparer chaque phrase à tout ESCO ou tout le ROME par similarité a été testé et rejeté : toutes les phrases s'allongent, le classement baisse.

  8. Savoir-être (« Autonomie », « Être rigoureux »…) : ils comptent dans le score (les retirer dégrade le classement), mais sont affichés à part, à vérifier en entretien : un CV les écrit rarement.

Mesures sur 24 AVP et 23 CV fictifs (scripts/evaluer_classement.py) :

Méthode Bon AVP 1er (candidat) Bon AVP dans le top 3 Bon CV 1er (recruteur) Faux positifs
bge-m3 seul, rampe 0,45/0,70 (avant) 78,6 % 85,7 % 68,4 % 0
bge-m3 seul, rampe 0,55/0,75 92,9 % 100 % 73,7 % 0
bge-m3 seul, rampe 0,575/0,775 85,7 % 100 % 68,4 % 0
reranker seul 78,6 % 100 % 78,9 % 1
bge-m3 0,55/0,75 + reranker 85,7 % 100 % 73,7 % 0
bge-m3 0,575/0,775 + reranker (retenu) 85,7 % 100 % 84,2 % 0

Avec 14 CV étiquetés, un écart d'un CV (~7 points) n'est pas significatif. Mesures du 2026-10-11 sur RTX 3050 (bge-m3 en float16) : graphiques et données dans resultats/2026-10-11/.

Côté recruteur, chaque candidat a aussi :

  • une spécificité : son score sur cet AVP moins son score médian sur les autres AVP. Proche de 0 : le CV obtient le même score partout (profil vague, ou fait de savoir-être) ;
  • le rang de cet AVP pour lui : 1 = c'est l'AVP qui lui correspond le mieux ;
  • un indicateur ex aequo quand l'écart avec le précédent est inférieur à 1 point.

Le score_global (CV entier contre AVP entier) suit la recette de champs de l'OPT-NC, encodée avec bge-m3 et sans la troncature à 7 000 caractères du modèle Google (bge-m3 accepte 8 192 tokens). C'est une information d'ensemble, non utilisée pour le tri.

Évaluation : ce que le score vaut vraiment

Deux jeux séparés, pour ne pas conclure sur les CV qui ont servi à régler :

  • réglage : exemples/cv_list.json (23 CV, 14 avec un bon poste connu, 6 hors domaine) ; la rampe et les seuils des libellés y ont été réglés, le résultat est donc optimiste ;
  • test : exemples/cv_banc.json (18 CV écrits avec leurs propres mots, dont 6 profils de développeur ; parfaits, bons, partiels, hors domaine), jamais utilisés pour régler.

Le service contre des systèmes plus simples (scripts/comparer_systemes.py, bon poste en tête) :

Système Réglage (candidat / recruteur) Test (1er / top 3) CV reformulés : bon poste 1er
Mots-clés TF-IDF, CV entier (ATS classique) 86 % / 84 % 79 % / 86 % 4 / 7
Mots-clés TF-IDF par compétence 79 % / 74 % 86 % / 93 % 1 / 7
Embeddings, CV entier (recette OPT-NC) 79 % / 95 % 57 % / 86 % 3 / 7
Embeddings par compétence 86 % / 63 % 64 % / 64 % 7 / 7
Service (embeddings + reranker) 86 % / 84 % 71 % / 71 % 7 / 7
  • Sur des CV qui reprennent les mots des AVP, les mots-clés font aussi bien que le service (et mieux sur le jeu de test, où les écarts ne portent que sur 4 CV « partiels » au bon poste discutable ; tous les systèmes mettent en tête les 7 CV parfaits ou bons).
  • Test de reformulation (scripts/tester_robustesse.py, exemples/cv_reformules.json) : les 7 CV parfaits ou bons réécrits avec d'autres mots, même parcours. Les mots-clés s'effondrent (7/7 -> 1/7), le service garde le bon poste en tête pour les 7 : c'est ce que les embeddings apportent. Mais le score sur ce poste baisse de 58 % : le pourcentage dépend des mots, pas le rang.
  • Ordre des sections du CV inversé : score du service identique.
  • Combiner le service et les mots-clés (meilleure note ou moyenne) ne gagne pas sur les deux jeux.
  • Juge LLM local (Qwen3-4B, Ministral 3B) sur les compétences refusées : il corrige des refus injustes (auditeur 56 % -> 87 %) mais, sur le classement complet, rapproche les postes voisins (bon poste 1er : 84 % -> 74-79 %). Rejeté pour le score (donnees/evaluer_avec_juge.py).

Avec 14 CV par jeu, un CV fait varier un taux d'environ 7 points : aucun écart de cette taille n'est significatif.

Jeu d'évaluation n° 2 (exemples/cv_eval.json, python -m scripts.evaluer_jeu). Les jeux précédents ne notent qu'un bon AVP par CV, sur 14 à 18 CV : trop peu pour comparer deux réglages. Celui-ci regroupe les 31 AVP en 20 postes types et compte 68 CV fictifs : pour chaque poste, un CV fort (il fait le métier), un partiel (métier voisin) et un piège qui partage le vocabulaire sans faire le métier (facteur d'orgues pour le facteur, architecte DPLG pour l'architecte SI, animateur radio pour le chef de cellule radio, community manager pour l'administrateur réseaux…), plus 8 hors domaine ; styles variés (récit, liste, CV court, sigles). Chaque CV est noté de 0 à 3 sur chaque poste type (3 = à convoquer, 2 = à étudier, 1 = lien faible, 0 = hors sujet) : 1 360 couples. Notes proposées à la construction (scripts/construire_jeu_eval.py), à vérifier par un humain (exemples/grille_jeu_eval.csv).

Mesure (service actuel, IC 95 % par bootstrap sur les CV) Résultat
Un CV noté ≥ 2 passe devant un CV noté 0 sur le même AVP (AUC) 0,92 [0,88 ; 0,96]
Candidat : l'AVP en tête est pertinent (noté ≥ 2) 73 % [59 ; 85]
Candidat : qualité des 5 premiers AVP (nDCG@5) 0,78 [0,71 ; 0,85]
Recruteur : qualité des 10 premiers CV (nDCG@10) 0,76 [0,62 ; 0,80]
Pièges qui passent devant le CV partiel de leur poste 4 / 20 (aucun au-delà de « à étudier »)

Avis contre notes humaines (python -m scripts.calibrer_libelles, validation « poste mis de côté » : seuils réglés sur 19 postes, appliqués au 20e, pour chacun) :

Anciens libellés (≥ 50 % / ≥ 20 %) Avis calibré (≥ 22 % / ≥ 17 %)
Accord avec la note humaine (kappa pondéré) 0,42 0,69
Profils « à convoquer » reconnus 0 / 21 14 / 21
Hors sujet annoncés adaptés 0 / 1 298 3 / 1 298
Profils « à étudier » reconnus 4 / 41 8 / 41

Chiffres avec les seuils retenus ; en validation « poste mis de côté », mêmes résultats à une unité près (kappa 0,69, 14 / 21 reconnus, 2 hors sujet annoncés adaptés). Les CV « à étudier » restent mal reconnus (médiane 10 %) : un profil voisin prouve peu de compétences mot pour mot. Les seuils sont choisis identiques sur les 20 plis, mais sur des notes encore à vérifier : à refaire après vérification de la grille.

Deuxième avis IA (app/juge.py, scripts/juge_llm.py, Space privé Myz0/CV-Matching-juge). Un grand LLM ouvert, gpt-oss-120b (65 Go en 4 bits, ZeroGPU 96 Go), relit comme un recruteur les meilleurs résultats du service (6 postes pour un CV, 8 candidats pour un poste) : note 0 à 3 et une phrase de justification, sans voir ni le score ni les notes humaines. Le score est revu de ±5 points (score + 0,1 x (note / 3 - 0,5)). Sur le jeu n° 2 (444 couples relus, comparaison appariée) :

Mesure Service seul Service + deuxième avis IA
Candidat : qualité des 5 premiers postes (nDCG@5) 0,78 0,83 (+0,05, démontré)
Recruteur : qualité des 10 premiers CV (nDCG@10) 0,76 0,83 (+0,07, démontré)
Candidat : 1er poste pertinent / recruteur : bon CV en tête 73 % / 85 % 80 % / 90 % (non démontré)

Le LLM reconnaît les 21 profils à convoquer (l'avis calibré : 14) mais il est généreux (« à étudier » pour beaucoup de profils transférables) : sur la décision convoquer / étudier / non, il est un peu moins proche des notes humaines (kappa 0,62) que l'avis calibré (0,67). D'où son rôle : revoir l'ordre et justifier, pas décider. Sur la page, bouton « Deuxième avis IA » (à la demande, environ 30 s, quota GPU du visiteur). Poids choisi parmi 4 essais sur ce même jeu ; le gain côté recruteur se retrouve avec les 4 poids. Juges plus petits (Qwen3-4B, Ministral 3B, octobre) : rejetés. Configuration : JUGE_SPACE, et JUGE_TOKEN (jeton en lecture seule sur ce Space, en secret) ; sans jeton, pas de bouton.

Vérité terrain humaine (exemples/grille_etiquetage.csv, python -m scripts.accord_humain). Deux évaluateurs ont jugé seuls, à l'aveugle (sans score, codes neutres CV-01…), les 36 couples du jeu de test, en lisant le CV et le poste complets (exemples/grille_etiquetage.md) : convoquer, peut-être ou écarter, avec une justification chacun.

Mesure Résultat
Accord entre les deux évaluateurs (le plafond) 28 / 36, kappa 0,67 (correct à partir de 0,6) ; désaccords toujours entre cases voisines
Ordre : le score suit-il la décision humaine ? (Spearman, sans seuil) service 0,80 ; mots-clés CV entier 0,80, par compétence 0,83 ; embeddings CV entier 0,81, par compétence 0,81 ; reranker seul 0,75 ; service + mots-clés 0,84-0,85
Décision tirée du libellé (convoquer = très bonne ou excellente, peut-être = bonne ou partielle, écarter = faible), contre l'évaluateur 1 56 % de décisions identiques, kappa 0,31
« Convoquer » du service précision 100 %, rappel 15 % (2 des 13 « convoquer » humains)
  • Le service classe comme les humains (0,80), au niveau des autres systèmes : sur 36 couples, les écarts de 0,75 à 0,85 ne sont pas significatifs.
  • Ses libellés sont trop sévères : sur les 16 désaccords, le service est toujours plus strict que l'humain, jamais l'inverse. Les profils que les évaluateurs convoqueraient obtiennent 9 à 44 % (facteur pour le poste de préposé 25 %, contrôleur KYC pour le poste KYC 42 %) : écrits avec leurs propres mots, ils perdent des points sans perdre leur rang (voir le test de reformulation). Les humains convoquent aussi des profils voisins ou transférables (développeur Java pour l'administration d'applications, contrôleur de gestion pour l'audit) que le service note bas, faute de preuve pour chaque compétence du poste.
  • Correspondance libellé -> décision et seuils fixés avant la grille, et non recalés dessus : c'est le jeu de test, s'y régler fausserait la mesure. Ce constat a conduit à l'avis calibré (réglé sur le jeu n° 2, voir plus haut) : cette grille, jamais utilisée pour le régler, sert de contrôle indépendant.

Limites, biais et cadre légal

Ce que le service fait. Il classe les postes pour un CV et les CV pour un poste, avec un score expliqué compétence par compétence et la ligne du CV qui sert de preuve. Il propose, le recruteur décide : aucun candidat n'est écarté automatiquement, les prérequis ne sont jamais éliminatoires.

Ce qu'il ne fait pas. Un CV est déclaratif : le score mesure ce qui est écrit, pas ce qui est maîtrisé ; il ne détecte ni l'exagération ni le mensonge, ne mesure pas le potentiel, et ne remplace ni l'entretien ni une commission. Les résultats valent pour nos 24 AVP et nos CV fictifs.

Biais mesurés (et ce qu'il faut en faire) :

  • Formulation : un CV « parfait » qui reprend les mots de l'AVP obtient 91 %, des CV « parfaits » écrits avec leurs propres mots 25 à 60 % ; un même parcours réécrit autrement perd 58 % de ses points, mais garde son rang. La grille humaine le confirme : le classement suit les évaluateurs (0,80), mais 2 seulement des 13 profils qu'ils convoqueraient atteignent « très bonne ». Le pourcentage est donc présenté comme un ordre de grandeur ; se fier au rang et aux preuves.
  • CV courts : un CV de 10 lignes ne peut pas couvrir un AVP de 40 exigences ; environ 10 % des compétences refusées le sont à tort (le CV le dit avec d'autres mots : « négociation » pour « argumenter »), le reste est vraiment absent du CV (donnees/analyse_competences.txt).
  • Vocabulaire interne de l'OPT (SIDO, LCBFT, CAFAT…) : inconnu des modèles ; un glossaire tenu par l'OPT serait plus fiable qu'un dictionnaire national (testé : SIDO y devient « Société interprofessionnelle des oléagineux »).
  • Parcours atypiques (reconversion, études à l'étranger) et CV en anglais : non mesurés ; bge-m3 est multilingue, mais nos tests sont en français.
  • Données personnelles : le nom, l'e-mail, le téléphone, l'adresse et la photo du CV ne sont jamais lus (seuls l'intitulé, le résumé, les postes, formations, compétences, projets et certificats le sont ; vérifié par un test : changer le nom ne change rien). Le service n'enregistre aucun CV (ni fichier, ni journal).

Cadre légal (principes ; leur application exacte en Nouvelle-Calédonie est à faire confirmer par un juriste ou l'enseignant) :

  • RGPD et loi Informatique et Libertés : un CV est une donnée personnelle (finalité claire, minimisation, durée de conservation, droits d'accès). Les tests n'utilisent que des CV fictifs ; le Space de démonstration est public et hébergé par Hugging Face : de vrais CV ne doivent y être envoyés que sur une installation maîtrisée (Docker sur site, voir « Déployer »).
  • Règlement européen sur l'IA : les systèmes d'aide au recrutement y sont classés à haut risque (supervision humaine, documentation, tests de biais, traçabilité).
  • Décision automatisée : une décision de recrutement ne doit pas reposer uniquement sur un traitement automatisé ; d'où le rôle de simple proposition, les preuves affichées et l'absence d'écart automatique.

Configuration (variables d'environnement)

Variable Défaut Rôle
DATASET_REPO opt-nc/odata-avps Dataset Hugging Face
DATASET_REVISION (vide = dernière) Version d'archive du dataset (commit), qui garde les AVP clos. Depuis le 2026-10-10, la dernière ne contient que les AVP ouverts ; la version complète (24 AVP) est 1bb92a09a4ff6aa6e9488ee954085019abba7747
DATASET_DERNIERE true Avec une archive : y fusionner aussi la dernière version (nouveaux AVP, mises à jour), par identifiant. false = archive seule, pour une évaluation reproductible
MODEL_NAME BAAI/bge-m3 Modèle d'embeddings
MODEL_REVISION 5617a9f6… Version figée de bge-m3 (commit Hugging Face). Vide = dernière publiée
RERANKER_MODEL BAAI/bge-reranker-v2-m3 Reranker. Vide = bge-m3 seul (bien plus rapide sur CPU)
RERANKER_REVISION 953dc6f6… Version figée du reranker. Vide = dernière publiée
RERANKER_TOP_K 3 Phrases du CV relues par le reranker, par attendu
SIM_BAS / SIM_HAUT 0.575 / 0.775 Rampe du score (à calibrer)
SEUIL_COUVERTURE 0.50 Degré de couverture au-dessus duquel un attendu est « couvert »
SEUILS_LIBELLE [22, 17] Seuils du pourcentage affiché pour les avis « Profil adapté » / « Profil à étudier » (réglés sur des notes humaines)
JUGE_SPACE Myz0/CV-Matching-juge Space du deuxième avis IA (gpt-oss-120b)
JUGE_TOKEN (secret) Jeton Hugging Face en lecture seule sur le Space juge ; absent = pas de bouton
MODEL_PROMPT (vide) Instruction devant chaque texte, pour les modèles qui en attendent une (Qwen3-Embedding, e5-instruct)
SIM_PREREQUIS 0.70 Cosinus pour signaler comme « mention probable » un prérequis qu'aucune règle ne reconnaît
SEUIL_QUASI_IDENTIQUE 0.80 Deux compétences au-dessus = la même (spécificité)
INCLURE_AVP_FERMES false Inclure les AVP dont la date limite est dépassée
OUTILS_ROME true Compléter les outils cités dans le CV par les savoirs ROME (app/outils.py)
API_KEY (vide = pas de clé) Clé principale, exigée dans l'en-tête X-API-Key par les routes de calcul, l'API Gradio et le MCP. Sur le Space : un secret
API_KEYS_HASH {} Clés par équipe : {"équipe": "empreinte SHA-256"}, jamais les clés. Gérées par scripts/cles_api.py. Sur le Space : un secret
MAX_CV_VIVIER 50 Nombre de CV au plus dans un classement
MAX_CARACTERES_CV 50000 Texte au plus dans un CV
MAX_OCTETS_REQUETE 5242880 Taille au plus d'une requête (5 Mo), refusée avant lecture (413)
HUB_URL https://hackavp-api.duckdns.org Adresse du hub de la promotion (routes /v1/hub/...)
HUB_DELAI 15 Secondes au plus par appel au hub
NIVEAU_JOURNAL INFO Journal du service : démarrage, durée de chaque calcul, refus (clé, taille), GPU refusé. Jamais le contenu d'un CV ni la clé. Sur le Space : onglet Logs

Tests et calibration

python -m tests.test_scoring          # moteur de score, sans modèle ni réseau
python -m tests.test_api              # application complète, sans modèle ni réseau
python -m scripts.inspecter_dataset   # AVP ouverts/clos, compétences les plus fréquentes
python -m scripts.evaluer_classement  # mesure top-1 / MRR / faux positifs et calibre la rampe
python -m scripts.verifier_embeddings # bge-m3 range-t-il les AVP comme le modèle officiel ?
python -m scripts.generer_outils_rome # régénère app/outils_rome.json depuis le ROME (open data)
python -m scripts.comparer_systemes   # service contre mots-clés et embeddings seuls, réglage et test
python -m scripts.tester_robustesse   # CV reformulés sans les mots de l'AVP, ordre des sections
python -m scripts.preparer_grille     # grille d'étiquetage humaine à l'aveugle (jeu de test)
python -m scripts.accord_humain       # grille remplie : kappa entre humains, accord du service, Spearman
python -m scripts.cles_api liste      # clés API par équipe (nouvelle / revoquer <équipe> --space)

scripts/evaluer_classement.py utilise les 23 CV fictifs de exemples/cv_list.json et les réponses attendues de exemples/attendus.json.

Tests automatiques : à chaque envoi sur GitHub (.github/workflows/tests.yml), les deux suites de tests ci-dessus et la vérification de la syntaxe du front (node --check) tournent sur une machine propre (Python 3.10, torch processeur). Résultat dans l'onglet Actions du dépôt.

Traces des mesures (vitesse, qualité, captures)

pip install -r requirements-dev.txt && python -m playwright install chromium
python -m scripts.mesurer_performances --device gpu   # qualité + durées -> resultats/<date>/
python -m scripts.mesurer_performances --device cpu   # durées sans carte graphique (~20 min)
python -m scripts.captures resultats/<date>           # service lancé : copies d'écran
python -m scripts.graphiques resultats/<date>         # graphiques PNG

Chaque dossier resultats/<date>/ garde la fiche de la machine (GPU, pilote, versions, pip_freeze.txt), les mesures brutes (JSON/CSV), les graphiques et les captures.

Déployer

Un seul code (app/), deux points d'entrée :

Où Lancement Ce qui est servi
Local, Docker, serveur uvicorn app.main:app --port 7860 API REST complète (/v1/match, /v1/avps/...), interface, MCP
Hugging Face Spaces + ZeroGPU app_zerogpu.py (SDK Gradio) la même API REST, l'interface, l'API Gradio et MCP (matcher_cv, classer_candidats)

Hugging Face Spaces (ZeroGPU)

En ligne : https://huggingface.co/spaces/Myz0/CV-Matching (recherche candidat ~2 s, classement de 23 CV ~40 s, après ~20 s d'attribution du GPU au premier appel).

Le reranker a besoin d'une carte graphique : sur CPU, un /v1/match prend ~4 minutes (resultats/2026-10-11/). ZeroGPU prête un GPU pendant chaque appel (SDK Gradio uniquement).

  1. Créer un Space : SDK Gradio, matériel ZeroGPU (compte vérifié de plus de 30 jours, ou PRO).
  2. Pousser ce dossier dans le dépôt du Space (l'en-tête de ce README configure le Space).
  3. Settings → Variables : DATASET_REVISION=1bb92a09a4ff6aa6e9488ee954085019abba7747 (24 AVP) et INCLURE_AVP_FERMES=true.
  4. Quota : chaque visiteur dispose d'un temps de GPU quotidien, compté sur son compte Hugging Face (très faible sans compte, plus large avec un compte, encore plus en PRO ; les montants exacts sont fixés par Hugging Face). Ouvrir la page depuis huggingface.co en étant connecté ; le lien direct *.hf.space compte comme anonyme. Une analyse de CV réserve 60 s, un classement de 23 CV jusqu'à 2 min. Mode de secours : si le GPU est refusé, la page web refait le calcul sur le processeur avec bge-m3 seul (sans reranker, ~2 s, un peu moins précis) dans un processus séparé (app/secours_cpu.py) et l'indique par un bandeau « Mode simplifié ». Les routes REST et MCP n'ont pas ce secours : elles répondent 503.
  5. Les secrets (API_KEY, HF_TOKEN…) vont dans Settings → Variables and secrets, jamais dans le code.

Docker (serveur sans ZeroGPU, ou sur site)

Le Dockerfile (uvicorn app.main:app) reprend les réglages du Space : Python 3.10, les mêmes AVP (DATASET_REVISION, INCLURE_AVP_FERMES=true), les mêmes versions de bibliothèques et de modèles, donc les mêmes scores. Modèles inclus dans l'image, aucun appel à une IA externe.

docker build -t cv-matching .
docker run -p 7860:7860 -e API_KEY=<clé> cv-matching
docker run -p 7860:7860 -e RERANKER_MODEL= cv-matching   # sans carte graphique : bge-m3 seul

Sans carte graphique, le reranker rend /v1/match très lent (~4 min) : RERANKER_MODEL= (vide) donne des réponses en quelques secondes, avec un classement un peu moins bon.

Licences de la pile

Composant Licence
BAAI/bge-m3 MIT
BAAI/bge-reranker-v2-m3 Apache-2.0
FastAPI, Pydantic MIT
Gradio, sentence-transformers Apache-2.0
PyTorch, NumPy, SciPy, pandas BSD
Dataset opt-nc/odata-avps à préciser par l'OPT-NC
ROME 4.0 (France Travail), extrait app/outils_rome.json Licence Ouverte