Spaces:
Running on Zero
Download README.md from Myz0/CV-Matching: direct link, hf CLI and curl.
- Browser
- Download file 35.8 kB
-
https://huggingface.co/spaces/Myz0/CV-Matching/resolve/main/README.md
- Command line
-
hf download hf://spaces/Myz0/CV-Matching/README.md
-
curl -L -o README.md https://huggingface.co/spaces/Myz0/CV-Matching/resolve/main/README.md
A newer version of the Gradio SDK is available: 6.32.0
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.
- Interface web : http://localhost:7860/
- Documentation de l'API (Swagger) : http://localhost:7860/docs
- Serveur MCP (pour un agent conversationnel) : http://localhost:7860/gradio_api/mcp/ (en ligne : https://myz0-cv-matching.hf.space/gradio_api/mcp/)
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'accessTokendePOST /auth/logindu 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 (
avpReferencedu hub =id_avpdu 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 candidaturesANNULEEsont ignorées (saufinclure_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é
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.
- attendus (
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.
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 deSIM_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.
- la rampe bge-m3 : cosinus avec la phrase du CV la plus proche, 0 sous
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 perdpoids × (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).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).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_adapteLes 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.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éesapp/outils_rome.jsongénérées parscripts/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.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).
- Créer un Space : SDK Gradio, matériel ZeroGPU (compte vérifié de plus de 30 jours, ou PRO).
- Pousser ce dossier dans le dépôt du Space (l'en-tête de ce README configure le Space).
- Settings → Variables :
DATASET_REVISION=1bb92a09a4ff6aa6e9488ee954085019abba7747(24 AVP) etINCLURE_AVP_FERMES=true. - 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.spacecompte 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. - 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 |