Resaltado automático de palabras clave

Potato resalta palabras clave de dos maneras. Un keyword_highlights_file marca una lista fija de términos en cada ítem sin intervención de ningún modelo, y ai_support añade un botón Keyword que el anotador pulsa para que un LLM marque las palabras relacionadas con cada etiqueta.

Los dos mecanismos fallan de forma distinta, así que la elección importa más que la configuración. Una lista fija es determinista, no cuesta nada por ítem y se puede describir en una sección de métodos, pero marca las mismas cadenas diga lo que diga la oración que las rodea. El asistente LLM lee cada ítem y puede marcar una frase que ninguna lista de palabras habría captado, a cambio de una llamada a la API por solicitud y de depender de un modelo que puede cambiar sin que lo sepas.

Para ver cómo están implementados el resaltado de opciones y el de palabras clave, consulta la documentación fuente.

Una lista fija de palabras clave

Recurre al archivo de palabras clave cuando necesites que todos los anotadores vean los mismos resaltados y poder decir después exactamente cuáles fueron. Apunta keyword_highlights_file a un CSV o TSV y Potato marca cada coincidencia en el texto del ítem con un recuadro.

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

Los colores se definen por esquema y por etiqueta, no de forma global, porque un resaltado del mismo color que la etiqueta de span que el anotador está a punto de dibujar es peor que ningún resaltado.

El archivo de palabras clave necesita una columna de encabezado keyword. Una columna label indica a qué categoría pertenece el término, una columna schema indica para qué esquema de anotación es relevante y una columna opcional color sustituye la paleta para esa etiqueta.

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

Un * coincide con cualquier secuencia de caracteres de palabra, así que excel* cubre excellent, excels y excelled en una sola fila. Potato también lee un archivo simple con una palabra clave por línea, y JSON, JSONL o YAML que contengan una lista de palabras clave o un mapa {keyword: label}.

Resaltados aleatorios para un estudio

Si estás midiendo si el resaltado cambia lo que hacen los anotadores, mostrar todas las palabras clave a todo el mundo no te deja nada con qué comparar. keyword_highlight_settings reduce el número de palabras clave mostradas y mezcla señuelos.

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 es el valor que hace funcionar la comparación, ya que así cada anotador ve resaltada la mitad de los términos y sin resaltar la otra mitad dentro del mismo corpus. La elección se guarda en caché por usuario y por instancia, con una semilla derivada de un hash del nombre de usuario y del id de la instancia, de modo que un anotador que vuelve a un ítem ve lo mismo que la primera vez. Qué palabras se mostraron queda registrado en el campo keyword_highlights_shown de los datos de comportamiento, para que el análisis pueda condicionarse a ello.

El asistente LLM de palabras clave

El resaltado de palabras clave con IA es un botón, no un proceso en segundo plano. Con ai_support activado, cada formulario de anotación lleva los botones Hint, Keyword y Rationale, y al pulsar Keyword se pregunta al modelo qué palabras de este ítem se relacionan con cada etiqueta disponible. La respuesta vuelve como recuadros superpuestos sobre el texto.

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 es el valor predeterminado y está cerca del mínimo para este asistente. Los prompts de Keyword y Rationale responden para todas las etiquetas en una sola respuesta, así que con un presupuesto menor la respuesta se trunca y el asistente se muestra vacío sin ningún error.

include.all: true activa los asistentes para todos los esquemas. Para activarlos solo en páginas y esquemas concretos, usa special_include, que asigna a cada índice de página un id de anotación y a este una lista de nombres de asistentes:

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

El resaltado de palabras clave necesita texto que resaltar, así que Potato quita el botón en los ítems de imagen aunque el endpoint sea un modelo de visión. En un ítem de texto, un modelo de visión ofrece los tres asistentes.

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, sin factura de 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 local compensa la pérdida de calidad cuando el corpus no puede salir de tu máquina, o cuando estás resaltando decenas de miles de ítems y el coste por ítem dominaría de otro modo el presupuesto del estudio.

Resaltar en su lugar las etiquetas probables

Cuando el problema es una lista de opciones larga y no un texto largo, option_highlighting es la herramienta más adecuada. Pide al modelo las opciones más probables y las muestra con opacidad completa y una estrella, atenuando el resto. Todas las opciones siguen siendo clicables.

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 encaja con un esquema de ocho a doce etiquetas, donde tres opciones marcadas reducen la lectura sin ocultar la respuesta. Funciona con radio, multiselect, likert y select, y no tiene efecto en spans, texto libre ni sliders.

Caché y precarga

Una llamada a un LLM añade segundos a la carga de una página, y un anotador que tiene que esperar dejará de pulsar el botón. Guardar en caché en disco y precargar por delante del cursor eliminan la mayor parte de esa espera, y la caché también evita que pagues dos veces por un ítem que un anotador vuelve a visitar.

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 frente a on_prev: 2 refleja cómo se mueven los anotadores. La mayor parte de la navegación es hacia delante, así que el presupuesto va hacia delante, con lo suficiente detrás del cursor para cubrir una corrección.

Una configuración completa

Los dos mecanismos se combinan. El archivo de palabras clave da a todos los anotadores los mismos resaltados de base, y los asistentes quedan detrás de botones para los ítems en los que la lista fija no tiene nada que decir.

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

Inicia el servidor y los resaltados aparecen en el primer ítem:

potato start config.yaml -p 8000

Cuando el resaltado de palabras clave con IA está activado, al pulsar el botón Keyword se marcan los términos relevantes en el texto de la anotación:

Palabras clave y entidades marcadas con recuadros superpuestos para guiar la atención del anotador

Lecturas adicionales

• Soporte de IA explica la configuración de endpoints para cada proveedor.
• Resaltado de opciones explica con más detalle la variante que atenúa etiquetas.
• Anotación de segmentos explica el esquema junto al que se muestran los resaltados.
• Funciones de productividad explica el formato del archivo de palabras clave y el resto de ajustes de velocidad para anotadores.