Destaque automático de palavras-chave

O Potato destaca palavras-chave de duas formas. Um keyword_highlights_file marca uma lista fixa de termos em todo item sem envolver nenhum modelo, e o ai_support adiciona um botão Keyword que o anotador pressiona para que um LLM marque as palavras relacionadas a cada rótulo.

Os dois mecanismos falham de jeitos diferentes, então a escolha importa mais do que a configuração. Uma lista fixa é determinística, não custa nada por item e pode ser relatada em uma seção de métodos, mas marca as mesmas strings não importa o que diga a frase ao redor. O assistente LLM lê cada item e pode marcar uma expressão que nenhuma lista de palavras teria capturado, ao custo de uma chamada de API por solicitação e da dependência de um modelo que pode mudar sem você saber.

Para ver como o destaque de opções e o de palavras-chave são implementados, consulte a documentação-fonte.

Uma lista fixa de palavras-chave

Use o arquivo de palavras-chave quando você precisa que todos os anotadores vejam os mesmos destaques e precisa poder dizer depois exatamente quais foram. Aponte keyword_highlights_file para um CSV ou TSV e o Potato marca cada ocorrência no texto do item com uma caixa com borda.

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

As cores são definidas por esquema e por rótulo, e não globalmente, porque um destaque da mesma cor do rótulo de span que o anotador está prestes a desenhar é pior do que nenhum destaque.

O arquivo de palavras-chave precisa de uma coluna de cabeçalho keyword. Uma coluna label diz a qual categoria o termo pertence, uma coluna schema diz para qual esquema de anotação ele é relevante, e uma coluna opcional color substitui a paleta para aquele rótulo.

text

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

Um * corresponde a qualquer sequência de caracteres de palavra, então excel* cobre excellent, excels e excelled em uma única linha. O Potato também lê um arquivo simples com uma palavra-chave por linha, e JSON, JSONL ou YAML com uma lista de palavras-chave ou um mapa {keyword: label}.

Destaques aleatórios para um estudo

Se você está medindo se o destaque muda o que os anotadores fazem, mostrar todas as palavras-chave para todo mundo não deixa nada para comparar. keyword_highlight_settings reduz as palavras-chave exibidas e mistura iscas a elas.

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 é o valor que faz a comparação funcionar, já que assim cada anotador vê destaque em metade dos termos e nenhum destaque na outra metade, dentro do mesmo corpus. A escolha fica em cache por usuário e por instância, com semente derivada de um hash do nome de usuário e do id da instância, de modo que um anotador que volta a um item vê o que viu da primeira vez. Quais palavras foram exibidas fica registrado no campo keyword_highlights_shown dos dados comportamentais, para que a análise possa condicionar a isso.

O assistente LLM de palavras-chave

O destaque de palavras-chave com IA é um botão, e não um processo em segundo plano. Com ai_support ativado, cada formulário de anotação traz os botões Hint, Keyword e Rationale, e pressionar Keyword pergunta ao modelo quais palavras deste item se relacionam a cada rótulo disponível. A resposta volta como caixas sobrepostas ao texto.

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 é o padrão e fica perto do mínimo para este assistente. Os prompts de Keyword e Rationale respondem para todos os rótulos em uma única resposta, então um orçamento menor corta a resposta e o assistente aparece vazio, sem nenhum erro.

include.all: true ativa os assistentes para todos os esquemas. Para ativá-los apenas em páginas e esquemas específicos, use special_include, que associa um índice de página a um id de anotação e este a uma lista de nomes de assistentes:

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

O destaque de palavras-chave precisa de texto para destacar, então o Potato remove o botão em itens de imagem mesmo quando o endpoint é um modelo de visão. Em um item de texto, um modelo de visão oferece os três assistentes.

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, sem conta de 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

Um endpoint local compensa a perda de qualidade quando o corpus não pode sair da sua máquina, ou quando você está destacando dezenas de milhares de itens e o custo por item dominaria o orçamento do estudo.

Em vez disso, destacar os rótulos prováveis

Quando o problema é uma lista longa de opções e não um texto longo, option_highlighting é a ferramenta mais adequada. Ele pede ao modelo as opções mais prováveis e as exibe com opacidade total e uma estrela, esmaecendo as demais. Todas as opções continuam clicáveis.

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 serve para um esquema com oito a doze rótulos, em que três opções marcadas reduzem a leitura sem esconder a resposta. Funciona em radio, multiselect, likert e select, e não tem efeito em spans, texto livre ou sliders.

Cache e pré-carregamento

Uma chamada a um LLM acrescenta segundos ao carregamento de uma página, e um anotador que precisa esperar vai parar de pressionar o botão. O cache em disco e o pré-carregamento à frente do cursor eliminam a maior parte dessa espera, e o cache também evita que você pague duas vezes por um item que um anotador revisita.

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 contra on_prev: 2 reflete como os anotadores se movem. A maior parte da navegação é para a frente, então o orçamento vai para a frente, com o suficiente atrás do cursor para cobrir uma correção.

Uma configuração completa

Os dois mecanismos se combinam. O arquivo de palavras-chave dá a todos os anotadores os mesmos destaques de base, e os assistentes ficam atrás de botões para os itens em que a lista fixa não tem nada a dizer.

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

Inicie o servidor e os destaques aparecem no primeiro item:

bash

potato start config.yaml -p 8000

Quando o destaque de palavras-chave com IA está ativado, pressionar o botão Keyword marca os termos relevantes no texto da anotação:

Destaque de palavras-chave com IA na interface de anotação Palavras-chave e entidades marcadas com caixas sobrepostas para guiar a atenção do anotador

Leitura adicional

Suporte de IA cobre a configuração de endpoints para todos os provedores.
Destaque de opções cobre em mais detalhe a variante que esmaece rótulos.
Anotação de spans cobre o esquema ao lado do qual os destaques aparecem.
Recursos de produtividade cobre o formato do arquivo de palavras-chave e as demais configurações que aceleram o trabalho do anotador.