Codebooks pour annotateurs IA : transformer un schéma de codage en étiqueteur LLM fiable

Pendant des décennies, un codebook était un document qu'on remettait à des gens. Il disait à une équipe de codeurs ce que signifiait chaque code, quels cas comptaient et où se situaient les frontières délicates. Aujourd'hui, le codeur qui le lit est souvent un modèle de langue, et un codebook écrit pour un doctorant à sa troisième séance de formation ne se transpose pas proprement à un modèle qui lira le tout une seule fois et ne posera jamais de question de clarification.

Un codebook est le contrat entre vos étiquettes et le monde : pour chaque code, ce qu'il signifie, ce qui compte, ce qui ne compte pas, et un exemple ou deux. Pour utiliser un LLM comme annotateur, vous réécrivez ce contrat de sorte qu'un modèle puisse l'exécuter sans allers-retours, puis vous contrôlez sa sortie contre des codeurs humains avant de lui faire confiance.

Ce qu'est vraiment un codebook

En analyse de contenu et en recherche qualitative, un codebook est la définition partagée de chaque code d'une étude. La référence canonique est le modèle de MacQueen et ses collègues (1998), qui donne à chaque code un nom, une courte définition, une description plus complète des cas où il s'applique et de ceux où il ne s'applique pas, et des passages d'exemple. Le but de tout écrire, c'est la fiabilité : deux codeurs qui lisent le même codebook devraient aboutir à la même étiquette sur le même texte, et vous pouvez mesurer si c'est le cas.

Les codebooks se déclinent en deux tempéraments. Un codebook fixe est arrêté avant le début du codage, ce qui est le cas de la plupart des jeux d'étiquettes en apprentissage automatique et des tâches de foule. Un codebook vivant grandit au fil de la lecture, dans la tradition de la théorie ancrée : vous remarquez une idée récurrente, vous la nommez, et plus tard vous fusionnez deux codes en constatant qu'ils recouvrent la même chose. Les deux peuvent piloter un annotateur LLM, même si un codebook vivant doit cesser de bouger à un moment avant le passage à l'échelle.

Pourquoi un codebook conçu pour des humains met un LLM en échec

Un codeur humain comble les trous d'un codebook avec son jugement et avec la séance de formation où vous avez discuté des cas difficiles. Un modèle n'a ni l'un ni l'autre. Il lit les mots sur la page, et les endroits que vous avez laissés implicites sont ceux où il se trompe.

• Frontières non définies. « Codez préoccupations de coût quand le participant mentionne l'argent » laisse de côté la question de savoir si un « ce n'était pas donné » lâché en passant compte. Une personne demande ; un modèle devine, et devine de façon inconstante sur tout un corpus.
• Exemples négatifs manquants. Les codeurs humains apprennent autant de « ça ressemble à X mais ce n'en est pas » que des cas positifs. Les codebooks les consignent rarement, parce que le formateur les fournit à l'oral.
• Littéralisme des instructions. Dites à un modèle « appliquez jusqu'à trois codes » et il en appliquera souvent trois, que le texte le justifie ou non, en remplissant jusqu'au plafond. Les humains lisent cela comme un plafond ; les modèles le lisent comme une cible.
• Absence d'étape de segmentation. Une personne découpe naturellement une transcription en unités codables. Il faut dire à un modèle de segmenter d'abord, puis de coder chaque unité, sinon il codera le passage entier d'un bloc et vous perdrez la granularité voulue.

Ces quatre points se corrigent en éditant le codebook, et ce sont ces retouches qui transforment un codebook humain en codebook exécutable par un modèle.

Rédiger un codebook qu'un LLM peut suivre

La réécriture est mécanique une fois que vous savez quoi ajouter. Pour chaque code, explicitez les quatre choses qu'un humain aurait autrement déduites :

1. Une définition en une ligne en langage clair, pas un synonyme du nom du code.
2. Des règles d'inclusion : les signaux qui indiquent que le code s'applique.
3. Des règles d'exclusion : les cas voisins qui ne comptent pas, avec un court exemple de chacun.
4. Deux ou trois exemples réels, idéalement dont un qu'un lecteur naïf coderait de travers.

Ensuite, traitez la structure séparément des étiquettes. Demandez au modèle de segmenter d'abord le texte en unités, de coder chaque unité contre le codebook, et de s'abstenir quand rien ne convient plutôt que d'attraper le code le plus proche. Une option explicite « aucun de ceux-ci » fait plus pour la qualité des données qu'un paragraphe d'instructions supplémentaire, car elle donne au modèle un endroit où placer les cas que votre codebook ne couvre pas, au lieu de les forcer dans un code qui ne leur convient pas.

La question de la fiabilité

On contrôle un annotateur LLM parce qu'on ne peut pas savoir d'avance comment il s'en sortira. Sur plusieurs tâches établies, il s'en sort bien : Gilardi, Alizadeh et Kubli (2023) ont trouvé que ChatGPT égalait ou dépassait les travailleurs de foule sur la pertinence, la prise de position et la détection de cadrage, avec un meilleur accord intercodeurs et un coût par étiquette inférieur au centime. Mais « bon sur ces tâches-là » ne dit rien de votre tâche, et le seul moyen de le savoir est de mesurer.

La mesure est la même que celle que vous feriez sur deux codeurs humains. Faites étiqueter un échantillon par des personnes, faites étiqueter le même échantillon par le modèle, et calculez une statistique d'accord corrigée du hasard telle que le kappa de Cohen ou l'alpha de Krippendorff. Là où l'accord est élevé, le modèle peut porter le gros du corpus. Là où il est faible, vous avez trouvé un code dont la définition travaille moins que vous ne le pensiez, et le correctif est en général dans le codebook, pas dans le modèle.

Du codebook humain à l'annotateur LLM, avec la boucle d'affinage

Deux modes d'échec méritent la vigilance. Les modèles sur-appliquent les codes quand vous leur donnez un plafond sans raison de rester en dessous : l'accord peut donc sembler bon sur la présence et s'effondrer sur le nombre. Et quand un humain vérifie le modèle au lieu d'étiqueter à neuf, le biais d'automatisation s'installe : accepter un code plausible va plus vite que le contester, si bien que le vérificateur finit par entériner les erreurs du modèle. Deux raisons de garder une tranche d'étiquettes véritablement aveugles, purement humaines, comme étalon.

Garder un humain dans la boucle

Le montage praticable est une répartition entre le modèle et les gens, que vous décidez à partir du chiffre d'accord.

Aiguillez selon l'accord : acceptez les codes sûrs, renvoyez le reste

Faites tourner le modèle sur un échantillon de référence étiqueté, regardez où il rejoint les humains, et aiguillez en conséquence. Les codes que le modèle réussit de façon fiable passent avec un contrôle par sondage léger. Ceux qu'il rate, et les unités où il s'est abstenu ou a semblé hésitant, vont aux codeurs humains. À mesure que les gens tranchent ces cas, les désaccords remontent dans le codebook, et la passe suivante s'en trouve améliorée. C'est l'idée de l'humain dans la boucle derrière la pré-annotation, portée d'une étiquette unique à tout un schéma de codage.

Le faire dans Potato

Potato exécute cette boucle dans un seul outil : un schéma de codage adossé à un codebook, un LLM qui pré-annote, des codeurs humains qui vérifient, et des métriques de fiabilité sur le résultat. Le codebook vit dans un schéma span marqué comme adossé à un codebook, ce qui transforme un simple jeu d'étiquettes en schéma de codage hiérarchique et modifiable.

annotation_schemes:
- annotation_type: span
  name: codes
  description: Highlight a passage and apply a code from the codebook
  labels: [access barriers, cost concerns, provider trust]

En mode QDA, le codebook est open par défaut : les codeurs peuvent ajouter, renommer ou fusionner des codes pendant que le schéma se stabilise. Une fois le codebook stable, passez-le en fixed avant de monter en charge, pour que le schéma partagé cesse de bouger sous le modèle et sous les codeurs.

Pour qu'un modèle applique les codes à l'avance, activez le support IA et pointez-le vers l'endpoint que vous utilisez :

ai_support:
  enabled: true
  endpoint_type: anthropic     # or openai, gemini, ollama, ...
  ai_config:
    model: claude-opus-4-8
    api_key: ${ANTHROPIC_API_KEY}
    temperature: 0.2

Le modèle propose des codes ; l'annotateur les confirme ou les corrige. Pour que le biais d'automatisation reste mesurable, ne pré-remplissez pas les éléments que vous réservez à l'accord. Laissez une tranche aveugle réservée aux humains et comparez-vous à elle, comme le décrit le guide de pré-annotation.

Quand une passe est terminée, deux exports vous donnent les livrables et la piste d'audit :

python -m potato.export config.yaml --format codebook -o codebook.csv
python -m potato.export config.yaml --format quotation_report \
  --option include_memos=true -o quotations.csv

L'export codebook donne une ligne par code, avec sa description et son nombre d'usages : vous voyez sur quels codes le modèle s'est appuyé et lesquels n'ont jamais servi. Le quotation_report donne une ligne par span codé, et c'est le fichier avec lequel vous contrôlez réellement le modèle. Potato rapporte le kappa de Cohen et de Fleiss sur les codes, si bien que la comparaison modèle contre humain sort sous forme d'un chiffre publiable.

Où aller ensuite

• Rédiger des consignes d'annotation efficaces, le versant humain du même métier.
• Pré-annotation par LLM et modèles de vision, pour la mécanique des suggestions du modèle et les garde-fous contre le biais d'automatisation.
• L'accord inter-annotateurs expliqué, pour les statistiques de fiabilité qui décident de la répartition.
• Le codage qualitatif dans Potato, pour le codebook, les mémos et les cas sur lesquels ce flux s'appuie.

Des jeux de données à codebook dense montrent à quoi ressemble un schéma bien spécifié en pratique : les codes d'émotion fins de GoEmotions, les jugements de règles sociales de Social Chemistry, et les étiquettes de cadrage de Media Frames.