--- 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](https://jsonresume.org/schema)) des avis de vacance de poste (AVP) de l'OPT-NC publiĂ©s en open data ([`opt-nc/odata-avps`](https://huggingface.co/datasets/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 ```bash 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/) ```bash 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). ```bash # 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": "", "password": ""}' # 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: " -H "X-Hub-Token: " ``` 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Ă©. ```bash 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. ```json {"mcpServers": {"cv-matching": {"url": "https://myz0-cv-matching.hf.space/gradio_api/mcp/", "headers": {"X-API-Key": ""}}}} ``` ```bash curl -X POST "https://myz0-cv-matching.hf.space/v1/score" -H "X-API-Key: " \ -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 ```bash 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) ```bash pip install -r requirements-dev.txt && python -m playwright install chromium python -m scripts.mesurer_performances --device gpu # qualitĂ© + durĂ©es -> resultats// python -m scripts.mesurer_performances --device cpu # durĂ©es sans carte graphique (~20 min) python -m scripts.captures resultats/ # service lancĂ© : copies d'Ă©cran python -m scripts.graphiques resultats/ # graphiques PNG ``` Chaque dossier `resultats//` 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. ```bash docker build -t cv-matching . docker run -p 7860:7860 -e API_KEY= 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 |