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
---
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": "<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é.
```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": "<clé>"}}}}
```
```bash
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
```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/<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.
```bash
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 |