Suporte de IA

Integre OpenAI, Claude, Gemini, Ollama, HuggingFace, vLLM e OpenRouter ao Potato para sugestões de rótulos, pré-anotação e destaque de palavras-chave com IA.

O Potato 2.0 inclui suporte nativo a Modelos de Linguagem de Grande Porte (LLMs) para auxiliar os anotadores com dicas inteligentes, destaque de palavras-chave e sugestões de rótulos.

Provedores compatíveis

O Potato é compatível com vários provedores de LLM:

Provedores em nuvem:

OpenAI (GPT-4, GPT-4 Turbo, GPT-3.5)
Anthropic (Claude 3, Claude 3.5)
Google (Gemini 1.5 Pro, Gemini 2.0 Flash)
Hugging Face
OpenRouter

Local/auto-hospedado:

Ollama (execute modelos localmente)
vLLM (inferência auto-hospedada de alto desempenho)

Configuração

Configuração básica

Adicione uma seção ai_support ao seu arquivo de configuração:

yaml

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

Configuração específica por provedor

OpenAI

yaml

instance_display:
  fields:
    - {key: body, type: text, label: Ticket}
    - {key: screenshot, type: image, label: Screenshot}

Anthropic Claude

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"]
        "2":
          "0": ["hint", "keyword"]
          "1": ["hint", "keyword"]

Google Gemini

yaml

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

Ollama local

yaml

# config.yaml, committed, no secrets
ai_support:
  enabled: true
  ai_config_file: ai-config.yaml
 
  ai_config:
    temperature: 0.7
    max_tokens: 800
    include:
      all: true

vLLM (auto-hospedado)

yaml

# ai-config.yaml, gitignored
endpoint_type: ollama
model: qwen3:0.6b
base_url: http://localhost:11434

Endpoints de IA visual

Novidade na v2.1.0

Para tarefas de anotação de imagem e vídeo, o Potato é compatível com endpoints de visão dedicados, incluindo YOLO, Ollama Vision, OpenAI Vision e Anthropic Vision. Eles permitem detecção de objetos, pré-anotação e classificação visual.

Consulte Suporte de IA Visual para todos os detalhes de configuração.

Recursos de IA

O suporte de IA do Potato oferece cinco capacidades principais:

1. Dicas inteligentes

Forneça orientação contextual aos anotadores sem revelar a resposta:

yaml

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

2. Destaque de palavras-chave

Destaque automaticamente as palavras-chave relevantes no texto:

yaml

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

3. Sugestões de rótulos

Sugira rótulos para o anotador considerar (exibidos com indicadores de confiança):

yaml

ai_support:
  enabled: true
  endpoint_type: "gemini"
  ai_config:
    model: "gemini-2.0-flash-exp"
    api_key: "${GOOGLE_API_KEY}"
    max_tokens: 800
    include:
      all: true

4. Justificativas de rótulos

Novidade na v2.1.0

Gere explicações equilibradas sobre por que cada rótulo pode se aplicar ao texto, ajudando os anotadores a entender o raciocínio por trás das diferentes classificações:

yaml

ai_support:
  enabled: true
  endpoint_type: "ollama"
  ai_config:
    model: "llama3.2"
    base_url: "http://localhost:11434"
    max_tokens: 800
    include:
      all: true

As justificativas aparecem como uma dica que lista cada rótulo disponível com uma explicação de por que ele pode se aplicar. Isso é útil para treinar anotadores ou quando as decisões de anotação são difíceis.

5. Destaque de opções

Novidade na v2.2.0

Destaque assistido por IA das opções mais prováveis de estarem corretas em tarefas de anotação discretas (radio, multiselect, likert, select). O sistema analisa o conteúdo e destaca as top-k opções mais prováveis, enquanto atenua as menos prováveis, mantendo todas as opções totalmente clicáveis.

yaml

ai_support:
  enabled: true
  endpoint_type: "vllm"
  ai_config:
    model: "meta-llama/Llama-3.2-3B-Instruct"
    base_url: "http://localhost:8000"
    max_tokens: 800
    include:
      all: true

Consulte Destaque de Opções para todos os detalhes de configuração.

Complementar: Ordenação por diversidade

Novidade na v2.2.0

Embora não seja estritamente um recurso de IA, a Ordenação por Diversidade usa embeddings de sentence-transformer para agrupar itens e apresentá-los em uma ordem diversa, reduzindo a fadiga do anotador e melhorando a cobertura. Ela se integra ao suporte de IA buscando automaticamente as dicas de IA dos itens reordenados.

Cache e desempenho

As respostas da IA podem ser armazenadas em cache para melhorar o desempenho e reduzir os custos de API:

yaml

ai_support:
  enabled: true
  endpoint_type: "open_router"
  ai_config:
    model: "openai/gpt-4o-mini"
    api_key: "${OPENROUTER_API_KEY}"
    max_tokens: 800
    include:
      all: true

Estratégias de cache

Aquecimento: Pré-gera dicas de IA para um lote inicial de instâncias quando o servidor inicia (warm_up_page_count)
Pré-busca: Gera dicas para as próximas instâncias à medida que os anotadores navegam para frente (on_next) ou para trás (on_prev)
Persistência em disco: Os caches são salvos em disco e persistem entre reinicializações do servidor

Prompts personalizados

O Potato inclui prompts padrão para cada tipo de anotação, armazenados em potato/ai/prompt/. Você pode personalizá-los para a sua tarefa específica:

Tipo de anotação	Arquivo de prompt
Botões de opção	`radio_prompt.txt`
Escalas Likert	`likert_prompt.txt`
Caixas de seleção	`checkbox_prompt.txt`
Anotação de trecho	`span_prompt.txt`
Controles deslizantes	`slider_prompt.txt`
Listas suspensas	`dropdown_prompt.txt`
Entrada numérica	`number_prompt.txt`
Entrada de texto	`text_prompt.txt`

Os prompts oferecem substituição de variáveis:

{text} - O texto do documento
{labels} - Rótulos disponíveis para o esquema
{description} - A descrição do esquema

Suporte a múltiplos esquemas

Para tarefas com vários esquemas de anotação, você pode ativar o suporte de IA seletivamente:

yaml

ai_support:
  enabled: true
  endpoint_type: "ollama"
  visual_endpoint_type: "ollama_vision"
  ai_config:
    model: "llama3.2"
    include:
      all: true
  visual_ai_config:
    model: "qwen2.5-vl:7b"

Exemplo completo

Configuração completa para análise de sentimento assistida por IA:

yaml

annotation_task_name: "Sentiment Analysis with AI Support"
task_dir: "."
 
data_files:
  - "data/reviews.json"
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"
    labels: ["positive", "negative", "neutral"]
 
  - annotation_type: multiselect
    name: topics
    description: "What topics are discussed?"
    labels: ["product", "service", "price", "quality"]
 
ai_support:
  enabled: true
  endpoint_type: "openai"
  ai_config:
    model: "gpt-4o-mini"
    api_key: "${OPENAI_API_KEY}"
    temperature: 0.7
    max_tokens: 800
    include:
      all: true
  cache_config:
    disk_cache:
      enabled: true
      path: "annotation_output/ai_cache.json"
    prefetch:
      warm_up_page_count: 20
      on_next: 10
      on_prev: 3
 
output_annotation_dir: "output/"
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true

Variáveis de ambiente

Armazene as chaves de API com segurança usando variáveis de ambiente:

bash

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."

Referencie-as na sua configuração com a sintaxe ${VARIABLE_NAME}.

Considerações de custo

As chamadas de IA são feitas por instância por padrão
Ative o cache para reduzir chamadas de API repetidas
Use aquecimento e pré-busca para pré-gerar dicas
Considere usar modelos menores/mais baratos para tarefas simples
Provedores locais (Ollama, vLLM) não têm custos de API

Boas práticas

Use a IA como apoio, não como substituição - Deixe os anotadores tomarem as decisões finais
Ative o cache em produção - Reduz a latência e os custos
Teste os prompts minuciosamente - Prompts personalizados devem ser validados
Monitore os custos de API - Acompanhe o uso, especialmente com provedores em nuvem
Considere provedores locais - Ollama ou vLLM para anotação de alto volume
Proteja as credenciais de API - Use variáveis de ambiente, nunca faça commit de chaves

Leitura adicional

Destaque de Opções - Orientação de opções assistida por IA
Ordenação por Diversidade - Diversificação de itens baseada em embeddings
Suporte de IA Visual - IA para anotação de imagem e vídeo
Rotulagem ICL - Aprendizado em contexto assistido por IA
Aprendizado Ativo - Priorização de instâncias baseada em ML
Recursos de Produtividade - Destaques de palavras-chave e sugestões

Para detalhes de implementação e modelos de prompt personalizados, consulte a documentação de origem.