Evidenziazione automatica delle parole chiave

Potato evidenzia le parole chiave in due modi. Un keyword_highlights_file segna una lista fissa di termini su ogni elemento senza coinvolgere alcun modello, e ai_support aggiunge un pulsante Keyword che l'annotatore preme per far segnare a un LLM le parole pertinenti a ciascuna etichetta.

I due meccanismi sbagliano in modi diversi, quindi la scelta conta più della configurazione. Una lista fissa è deterministica, non costa nulla per elemento e si può riportare in una sezione metodi, ma segna le stesse stringhe qualunque cosa dica la frase che le contiene. L'assistente LLM legge ogni elemento e può segnare un'espressione che nessuna lista di parole avrebbe colto, al prezzo di una chiamata API per richiesta e della dipendenza da un modello che può cambiare a tua insaputa.

Per capire come sono implementate l'evidenziazione delle opzioni e quella delle parole chiave, vedi la documentazione sorgente.

Una lista fissa di parole chiave

Usa il file di parole chiave quando serve che ogni annotatore veda le stesse evidenziazioni e devi poter dire in seguito esattamente quali fossero. Fai puntare keyword_highlights_file a un CSV o a un TSV e Potato segna ogni corrispondenza nel testo dell'elemento con un riquadro bordato.

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

I colori si impostano per schema e per etichetta, non a livello globale, perché un'evidenziazione dello stesso colore dell'etichetta di span che l'annotatore sta per tracciare è peggio di nessuna evidenziazione.

Il file di parole chiave richiede una colonna di intestazione keyword. Una colonna label indica la categoria a cui appartiene il termine, una colonna schema indica lo schema di annotazione a cui si riferisce e una colonna color facoltativa sostituisce la palette per quell'etichetta.

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

Un * corrisponde a qualsiasi sequenza di caratteri di parola, quindi excel* copre excellent, excels ed excelled in una sola riga. Potato legge anche un semplice file con una parola chiave per riga, e JSON, JSONL o YAML contenenti una lista di parole chiave o una mappa {keyword: label}.

Evidenziazioni casuali per uno studio

Se stai misurando se l'evidenziazione cambia il comportamento degli annotatori, mostrare tutte le parole chiave a tutti non ti lascia niente con cui confrontare. keyword_highlight_settings sfoltisce le parole chiave e ci mescola parole esca.

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 è il valore che fa funzionare il confronto, perché così ogni annotatore vede un'evidenziazione su metà dei termini e nessuna sull'altra metà all'interno dello stesso corpus. La scelta viene messa in cache per utente e per istanza, con un seed ricavato da un hash del nome utente e dell'id dell'istanza, così un annotatore che torna su un elemento vede ciò che ha visto la prima volta. Le parole mostrate vengono registrate nel campo keyword_highlights_shown dei dati comportamentali, così l'analisi può tenerne conto.

L'assistente LLM per le parole chiave

L'evidenziazione delle parole chiave con l'AI è un pulsante, non un processo in background. Con ai_support attivo, ogni modulo di annotazione mostra i pulsanti Hint, Keyword e Rationale, e premendo Keyword si chiede al modello quali parole di quell'elemento si riferiscono a ciascuna etichetta disponibile. La risposta torna come riquadri sovrapposti al testo.

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 è il valore predefinito ed è vicino al minimo per questo assistente. I prompt di Keyword e Rationale rispondono per tutte le etichette in un'unica risposta, quindi con un budget più piccolo la risposta viene troncata e l'assistente appare vuoto senza alcun errore.

include.all: true attiva gli assistenti per ogni schema. Per attivarli solo su pagine e schemi specifici, usa special_include, che associa a un indice di pagina un id di annotazione e a questo una lista di nomi di assistenti:

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"]

L'evidenziazione delle parole chiave ha bisogno di testo da evidenziare, quindi Potato toglie il pulsante sugli elementi immagine anche quando l'endpoint è un modello di visione. Su un elemento di testo, un modello di visione offre tutti e tre gli assistenti.

Anthropic

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, senza bolletta API

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 locale vale il calo di qualità quando il corpus non può lasciare la tua macchina, oppure quando evidenzi decine di migliaia di elementi e il costo per elemento finirebbe altrimenti per dominare il budget dello studio.

Evidenziare invece le etichette probabili

Quando il problema è una lunga lista di opzioni e non un testo lungo, lo strumento migliore è option_highlighting. Chiede al modello le opzioni più probabili e le mostra a piena opacità con una stella, attenuando le altre. Tutte le opzioni restano cliccabili.

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 si adatta a uno schema con otto-dodici etichette, dove tre opzioni segnate riducono la lettura senza nascondere la risposta. Funziona con radio, multiselect, likert e select, e non ha effetto su span, testo libero e slider.

Caching e prefetching

Una chiamata a un LLM aggiunge secondi al caricamento di una pagina, e un annotatore costretto ad aspettare smetterà di premere il pulsante. Il caching su disco e il prefetching davanti al cursore eliminano gran parte di quell'attesa, e la cache evita anche di pagare due volte per un elemento che un annotatore rivisita.

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 contro on_prev: 2 riflette il modo in cui si muovono gli annotatori. La navigazione va per lo più in avanti, quindi il budget va in avanti, con abbastanza margine dietro al cursore per coprire una correzione.

Una configurazione completa

I due meccanismi si combinano. Il file di parole chiave dà a ogni annotatore le stesse evidenziazioni di base, e gli assistenti stanno dietro ai pulsanti per gli elementi su cui la lista fissa non ha niente da dire.

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

Avvia il server e le evidenziazioni compaiono sul primo elemento:

potato start config.yaml -p 8000

Quando l'evidenziazione delle parole chiave con l'AI è attiva, premendo il pulsante Keyword si segnano i termini pertinenti nel testo da annotare:

Parole chiave ed entità segnate con riquadri sovrapposti per guidare l'attenzione dell'annotatore

Per approfondire

• Supporto AI tratta la configurazione degli endpoint per ogni provider.
• Evidenziazione delle opzioni descrive più in dettaglio la variante che attenua le etichette.
• Annotazione span tratta lo schema accanto al quale compaiono le evidenziazioni.
• Funzionalità di produttività tratta il formato del file di parole chiave e le altre impostazioni che velocizzano il lavoro degli annotatori.