Skip to content
Guides7 min de lecture

Surlignage automatique de mots-clés

Configurez le surlignage de mots-clés dans Potato avec un fichier de mots-clés fixe ou un assistant LLM de mots-clés, avec couleurs par label, distracteurs aléatoires et mise en cache des réponses.

Potato Team

Potato surligne les mots-clés de deux façons. Un keyword_highlights_file marque une liste fixe de termes sur chaque item sans faire intervenir de modèle, et ai_support ajoute un bouton Keyword sur lequel l'annotateur appuie pour qu'un LLM marque les mots liés à chaque label.

Les deux mécanismes échouent de manière différente, donc le choix compte davantage que la configuration. Une liste fixe est déterministe, ne coûte rien par item et peut être décrite dans une section méthodes, mais elle marque les mêmes chaînes quel que soit le sens de la phrase qui les entoure. L'assistant LLM lit chaque item et peut marquer une expression qu'aucune liste de mots n'aurait repérée, au prix d'un appel d'API par requête et d'une dépendance à un modèle qui peut changer à votre insu.

Pour la façon dont le surlignage des options et des mots-clés est implémenté, consultez la documentation source.

Une liste de mots-clés fixe

Utilisez le fichier de mots-clés quand tous les annotateurs doivent voir les mêmes surlignages et que vous devez pouvoir dire plus tard exactement lesquels. Faites pointer keyword_highlights_file vers un CSV ou un TSV, et Potato encadre chaque correspondance dans le texte de l'item.

yaml
annotation_task_name: "Sentiment with keyword highlights"
task_dir: .
output_annotation_dir: annotation_output
export_annotation_format: jsonl
 
data_files:
  - data/reviews.json
 
item_properties:
  id_key: id
  text_key: text
 
keyword_highlights_file: data/sentiment_keywords.tsv
 
ui:
  label_colors:
    sentiment:
      positive: "(22, 163, 74)"
      negative: "(239, 68, 68)"
 
annotation_schemes:
  - annotation_type: span
    name: sentiment
    description: "Mark the phrases that carry sentiment. Highlighted keywords are suggestions, not answers."
    labels:
      - name: positive
        tooltip: "Phrases expressing a positive opinion"
      - name: negative
        tooltip: "Phrases expressing a negative opinion"
 
user_config:
  allow_all_users: true

Les couleurs sont définies par schéma et par label, et non globalement, car un surlignage de la même couleur que le label de span que l'annotateur s'apprête à tracer est pire que l'absence de surlignage.

Le fichier de mots-clés doit avoir une colonne d'en-tête keyword. Une colonne label indique la catégorie à laquelle appartient le terme, une colonne schema indique le schéma d'annotation concerné, et une colonne color facultative remplace la palette pour ce label.

text
keyword,label,schema,color
excellent,positive,sentiment,(34, 197, 94)
terrible,negative,sentiment,#ef4444
excel*,positive,sentiment,

Un * correspond à toute suite de caractères de mot, donc excel* couvre excellent, excels et excelled en une seule ligne. Potato lit aussi un simple fichier avec un mot-clé par ligne, ainsi que du JSON, du JSONL ou du YAML contenant une liste de mots-clés ou une table {keyword: label}.

Surlignages aléatoires pour une étude

Si vous mesurez l'effet du surlignage sur ce que font les annotateurs, montrer tous les mots-clés à tout le monde ne vous laisse rien à quoi comparer. keyword_highlight_settings réduit le nombre de mots-clés affichés et y mêle des leurres.

yaml
keyword_highlights_file: data/keywords.csv
 
keyword_highlight_settings:
  keyword_probability: 0.5        # show half the matched keywords
  random_word_probability: 0.05   # highlight about 5% of other words
  random_word_label: "distractor"
  random_word_schema: "keyword"

keyword_probability: 0.5 est la valeur qui rend la comparaison possible, puisque chaque annotateur voit alors un surlignage sur la moitié des termes et aucun sur l'autre moitié, au sein du même corpus. Le choix est mis en cache par utilisateur et par instance, avec une graine tirée d'un hachage du nom d'utilisateur et de l'id de l'instance, si bien qu'un annotateur qui revient sur un item voit ce qu'il a vu la première fois. Les mots affichés sont enregistrés dans le champ keyword_highlights_shown des données comportementales, ce qui permet à l'analyse d'en tenir compte.

L'assistant LLM de mots-clés

Le surlignage de mots-clés par IA est un bouton, et non un processus en arrière-plan. Avec ai_support activé, chaque formulaire d'annotation porte les boutons Hint, Keyword et Rationale, et un appui sur Keyword demande au modèle quels mots de cet item se rapportent à chaque label disponible. La réponse revient sous forme de cadres superposés au texte.

yaml
ai_support:
  enabled: true
  endpoint_type: openai
 
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    temperature: 0.3
    max_tokens: 800
    include:
      all: true

max_tokens: 800 est la valeur par défaut et se situe près du minimum pour cet assistant. Les prompts Keyword et Rationale répondent pour tous les labels en une seule réponse, donc un budget plus faible tronque la réponse et l'assistant s'affiche vide sans aucune erreur.

include.all: true active les assistants pour tous les schémas. Pour les activer seulement sur certaines pages et certains schémas, utilisez special_include, qui associe un index de page à un id d'annotation, puis à une liste de noms d'assistants :

yaml
ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    include:
      all: false
      special_include:
        "0":
          "0": ["hint", "keyword"]
        "1":
          "1": ["hint"]

Le surlignage de mots-clés a besoin de texte à surligner, donc Potato retire le bouton sur les items image même quand l'endpoint est un modèle de vision. Sur un item texte, un modèle de vision propose les trois assistants.

Anthropic

yaml
ai_support:
  enabled: true
  endpoint_type: anthropic
 
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    temperature: 0.3
    max_tokens: 800
    include:
      all: true

Ollama, sans facture d'API

yaml
ai_support:
  enabled: true
  endpoint_type: ollama
 
  ai_config:
    model: qwen3:0.6b
    base_url: http://localhost:11434
    temperature: 0.3
    max_tokens: 800
    include:
      all: true

Un endpoint local vaut la perte de qualité quand le corpus ne peut pas quitter votre machine, ou quand vous surlignez des dizaines de milliers d'items et que le coût par item pèserait sinon plus que tout le reste dans le budget de l'étude.

Surligner plutôt les labels probables

Quand le problème est une longue liste d'options plutôt qu'un long texte, option_highlighting est l'outil le plus adapté. Il demande au modèle les options les plus probables et les affiche en pleine opacité avec une étoile, en atténuant les autres. Toutes les options restent cliquables.

yaml
ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    temperature: 0.3
    max_tokens: 800
 
  option_highlighting:
    enabled: true
    top_k: 3
    dim_opacity: 0.4
    auto_apply: true
    schemas: null
    prefetch_count: 10

top_k: 3 convient à un schéma de huit à douze labels, où trois options marquées réduisent la lecture sans masquer la réponse. Il fonctionne avec radio, multiselect, likert et select, et n'a aucun effet sur les spans, le texte libre ou les sliders.

Mise en cache et préchargement

Un appel à un LLM ajoute des secondes au chargement d'une page, et un annotateur qui doit attendre cessera d'appuyer sur le bouton. La mise en cache sur disque et le préchargement en avance sur le curseur suppriment l'essentiel de cette attente, et le cache vous évite aussi de payer deux fois pour un item qu'un annotateur revisite.

yaml
ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    max_tokens: 800
    include:
      all: true
 
  cache_config:
    disk_cache:
      enabled: true
      path: annotation_output/ai_cache.json
 
    prefetch:
      warm_up_page_count: 10
      on_next: 5
      on_prev: 2

on_next: 5 contre on_prev: 2 reflète la façon dont les annotateurs se déplacent. La navigation se fait surtout vers l'avant, donc le budget va vers l'avant, avec assez de marge derrière le curseur pour couvrir une correction.

Une configuration complète

Les deux mécanismes se combinent. Le fichier de mots-clés donne à tous les annotateurs les mêmes surlignages de base, et les assistants restent derrière des boutons pour les items sur lesquels la liste fixe n'a rien à dire.

yaml
annotation_task_name: "Entity annotation with keyword support"
task_dir: .
output_annotation_dir: annotation_output
export_annotation_format: jsonl
 
data_files:
  - data/documents.json
 
item_properties:
  id_key: id
  text_key: text
 
keyword_highlights_file: data/entity_keywords.csv
 
annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Mark people, organizations and locations."
    labels:
      - name: PERSON
        color: "#FECACA"
      - name: ORG
        color: "#BBF7D0"
      - name: LOCATION
        color: "#BFDBFE"
 
ai_support:
  enabled: true
  endpoint_type: openai
 
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    temperature: 0.3
    max_tokens: 800
    include:
      all: true
 
  cache_config:
    disk_cache:
      enabled: true
      path: annotation_output/ai_cache.json
    prefetch:
      warm_up_page_count: 10
      on_next: 5
      on_prev: 2
 
user_config:
  allow_all_users: true

Lancez le serveur et les surlignages apparaissent sur le premier item :

bash
potato start config.yaml -p 8000

Quand le surlignage de mots-clés par IA est activé, un appui sur le bouton Keyword marque les termes pertinents dans le texte à annoter :

Surlignage de mots-clés par IA dans l'interface d'annotationMots-clés et entités marqués par des cadres superposés pour guider l'attention de l'annotateur

Pour aller plus loin