O Potato 2.1 adiciona suporte a IA visual, que coloca a assistência de IA diretamente dentro da anotação de imagens e vídeos. Em vez de desenhar cada caixa delimitadora à mão, você pode deixar o YOLO detectar objetos e revisar o que ele encontrou, ou entregar uma imagem a um modelo de visão e linguagem e fazer com que ele classifique a imagem e explique o motivo.

Este guia mostra como configurar cada endpoint de IA visual, os modos de assistência e como combinar a IA visual com a IA baseada em texto do Potato. A documentação de origem da IA visual traz a referência completa da API.

O que você vai aprender

Como configurar o YOLO para detecção rápida e local de objetos
Como executar modelos Ollama Vision para compreensão local de imagens
Como usar as APIs de visão na nuvem da OpenAI e da Anthropic
Como configurar os modos de detecção, pré-anotação, classificação e dica
Como combinar endpoints de IA visual e de texto em um único projeto
O fluxo de aceitar/rejeitar para revisar as sugestões da IA

Pré-requisitos

Você vai precisar do Potato 2.1.0 ou posterior:

bash

pip install --upgrade potato-annotation

E, dependendo do endpoint que você escolher, vai precisar de um destes:

YOLO: pip install ultralytics opencv-python
Ollama: Instale em ollama.ai e baixe um modelo de visão
OpenAI: Uma chave de API com acesso ao GPT-4o
Anthropic: Uma chave de API com acesso aos modelos de visão do Claude

Opção 1: YOLO para detecção de objetos

Recorra ao YOLO quando quiser uma detecção de caixas delimitadoras rápida e precisa, que roda inteiramente na sua própria máquina. Ele é bom com objetos comuns (pessoas, carros, animais, móveis) e processa imagens em milissegundos.

Configuração

bash

pip install ultralytics opencv-python

Configuração

yaml

annotation_task_name: "Object Detection with YOLO"
 
data_files:
  - data/images.json
 
item_properties:
  id_key: id
  text_key: image_url
 
instance_display:
  fields:
    - key: image_url
      type: image
      display_options:
        max_width: 800
        zoomable: true
 
annotation_schemes:
  - annotation_type: image_annotation
    name: objects
    description: "Detect and label objects"
    source_field: "image_url"
    tools:
      - bbox
    labels:
      - name: "person"
        color: "#FF6B6B"
      - name: "car"
        color: "#4ECDC4"
      - name: "dog"
        color: "#45B7D1"
      - name: "cat"
        color: "#96CEB4"
 
    ai_support:
      enabled: true
      features:
        detection: true
        pre_annotate: true
        hint: true
 
ai_support:
  enabled: true
  endpoint_type: "yolo"
  ai_config:
    model: "yolov8m.pt"
    confidence_threshold: 0.5
    iou_threshold: 0.45
 
output_annotation_dir: "annotation_output/"
user_config:
  allow_all_users: true

Formato dos dados

Crie data/images.json no formato JSONL (um objeto JSON por linha):

json

{"id": "img_001", "image_url": "images/street_scene_1.jpg"}
{"id": "img_002", "image_url": "images/park_photo.jpg"}
{"id": "img_003", "image_url": "https://example.com/images/office.jpg"}

Escolhendo um modelo YOLO

Modelo	Tamanho	Velocidade	Precisão	Melhor para
`yolov8n.pt`	6 MB	A mais rápida	Mais baixa	Prototipagem rápida
`yolov8s.pt`	22 MB	Rápida	Boa	Cargas equilibradas
`yolov8m.pt`	50 MB	Média	Melhor	Uso geral
`yolov8l.pt`	84 MB	Mais lenta	Alta	Quando a precisão importa
`yolov8x.pt`	131 MB	A mais lenta	A mais alta	Precisão máxima

Para detectar objetos que não estão nas classes integradas do YOLO, use o YOLO-World para detecção de vocabulário aberto:

yaml

ai_config:
  model: "yolo-world"
  confidence_threshold: 0.3

Ajustando a detecção

Se o YOLO estiver deixando objetos passar, reduza o limiar de confiança:

yaml

ai_config:
  confidence_threshold: 0.3  # More detections, more false positives

Se você estiver obtendo muitos falsos positivos, aumente-o:

yaml

ai_config:
  confidence_threshold: 0.7  # Fewer detections, higher precision

Opção 2: Ollama Vision para VLLMs locais

O Ollama Vision executa modelos de visão e linguagem localmente. Diferentemente do YOLO, esses modelos leem o contexto da imagem, classificam cenas e escrevem explicações, e nenhum dos seus dados sai da máquina.

Configuração

bash

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
 
# Pull a vision model
ollama pull llava
 
# Or for better performance:
ollama pull qwen2.5-vl:7b

Configuração

yaml

annotation_task_name: "Image Classification with Ollama Vision"
 
data_files:
  - data/images.json
 
item_properties:
  id_key: id
  text_key: image_url
 
instance_display:
  fields:
    - key: image_url
      type: image
      display_options:
        max_width: 600
        zoomable: true
 
annotation_schemes:
  - annotation_type: radio
    name: scene_type
    description: "What type of scene is shown?"
    labels:
      - indoor
      - outdoor_urban
      - outdoor_nature
      - aerial
      - underwater
 
    ai_support:
      enabled: true
      features:
        hint: true
        classification: true
 
ai_support:
  enabled: true
  endpoint_type: "ollama_vision"
  ai_config:
    model: "llava:latest"
    base_url: "http://localhost:11434"
    max_tokens: 500
    temperature: 0.1
 
output_annotation_dir: "annotation_output/"
user_config:
  allow_all_users: true

Modelos suportados

Modelo	Parâmetros	Pontos fortes
`llava:7b`	7B	Rápido, boa compreensão geral
`llava:13b`	13B	Precisão melhor
`llava-llama3`	8B	Raciocínio forte
`bakllava`	7B	Bom em detalhes visuais
`llama3.2-vision:11b`	11B	A visão mais recente do Llama
`qwen2.5-vl:7b`	7B	Forte em multilíngue + visão
`moondream`	1.8B	Muito rápido, leve

Opção 3: OpenAI Vision

O OpenAI Vision dá compreensão de imagens por meio do GPT-4o. Use-o quando quiser o modelo de visão mais forte e não se importar em pagar pelas chamadas de API na nuvem.

Configuração

yaml

ai_support:
  enabled: true
  endpoint_type: "openai_vision"
  ai_config:
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o"
    max_tokens: 1000
    detail: "auto"  # "low" for faster/cheaper, "high" for detail

Defina sua chave de API:

bash

export OPENAI_API_KEY="sk-..."

O parâmetro detail controla a resolução da imagem enviada à API:

low, mais rápido e mais barato, bom para classificação
high, resolução total, melhor para encontrar objetos pequenos
auto, deixa a API decidir

Opção 4: Anthropic Vision

Os modelos de visão do Claude são bons em ler o contexto da imagem e escrever explicações detalhadas.

Configuração

yaml

ai_support:
  enabled: true
  endpoint_type: "anthropic_vision"
  ai_config:
    api_key: "${ANTHROPIC_API_KEY}"
    model: "claude-sonnet-4-20250514"
    max_tokens: 1024

bash

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

Modos de assistência da IA

Cada endpoint de IA visual oferece alguns modos de assistência. Ative apenas os que você precisa, por esquema de anotação.

Modo de detecção

Encontra objetos que correspondem aos rótulos configurados e os exibe como sobreposições de caixas delimitadoras tracejadas:

yaml

ai_support:
  enabled: true
  features:
    detection: true

O anotador clica em "Detect" e as sugestões da IA aparecem como sobreposições tracejadas na imagem. Dê um duplo clique para aceitar, clique com o botão direito para rejeitar.

Modo de pré-anotação (automático)

Detecta todos os objetos e cria sugestões em uma única passagem. Ideal para dar partida em grandes conjuntos de dados:

yaml

ai_support:
  enabled: true
  features:
    pre_annotate: true

Modo de classificação

Classifica uma região selecionada ou a imagem inteira e retorna um rótulo sugerido com uma pontuação de confiança:

yaml

ai_support:
  enabled: true
  features:
    classification: true

Modo de dica

Fornece um texto de orientação sem entregar a resposta. Bom para treinar novos anotadores:

yaml

ai_support:
  enabled: true
  features:
    hint: true

O fluxo de aceitar/rejeitar

Quando um anotador clica em um botão de assistência de IA, as sugestões aparecem como sobreposições tracejadas:

Aceitar uma sugestão: dê um duplo clique na sobreposição tracejada para convertê-la em uma anotação real
Rejeitar uma sugestão: clique com o botão direito na sobreposição para descartá-la
Aceitar todas: clique em "Accept All" na barra de ferramentas para aceitar todas as sugestões de uma vez
Limpar todas: clique em "Clear" para descartar todas as sugestões

O anotador continua no controle, mas desenha bem menos caixas à mão.

Anotação de vídeo com IA visual

A IA visual também funciona em tarefas de vídeo. Você pode ativar detecção de cenas, detecção de quadros-chave e rastreamento de objetos:

yaml

annotation_schemes:
  - annotation_type: video_annotation
    name: scenes
    description: "Segment this video into scenes"
    mode: segment
    labels:
      - name: "intro"
        color: "#4ECDC4"
      - name: "main_content"
        color: "#FF6B6B"
      - name: "outro"
        color: "#45B7D1"
 
    ai_support:
      enabled: true
      features:
        scene_detection: true
        pre_annotate: true
        hint: true
 
ai_support:
  enabled: true
  endpoint_type: "ollama_vision"
  ai_config:
    model: "llava:latest"
    max_frames: 10  # Number of frames to sample

O parâmetro max_frames define quantos quadros a IA amostra do vídeo. Mais quadros significam precisão melhor e processamento mais lento.

Combinando endpoints de IA visual e de texto

Se o seu projeto mistura anotação de texto e de imagem, você pode configurar um endpoint separado para cada um: um modelo de texto para dicas e palavras-chave, e um modelo de visão para detecção.

yaml

ai_support:
  enabled: true
 
  # Text AI for radio buttons, text schemes, etc.
  endpoint_type: "ollama"
  ai_config:
    model: "llama3.2"
    include:
      all: true
 
  # Visual AI for image/video schemes
  visual_endpoint_type: "yolo"
  visual_ai_config:
    model: "yolov8m.pt"
    confidence_threshold: 0.5

Ou use um modelo de visão na nuvem ao lado de um modelo de texto local:

yaml

ai_support:
  enabled: true
  endpoint_type: "ollama"
  visual_endpoint_type: "openai_vision"
  ai_config:
    model: "llama3.2"
  visual_ai_config:
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o"

Exemplo completo: anotação de fotos de produtos

Aqui está uma configuração que você poderia colocar em produção para anotar fotos de produtos, com detecção do YOLO e dicas de IA baseadas em texto:

yaml

annotation_task_name: "Product Photo Annotation"
 
data_files:
  - data/product_photos.json
 
item_properties:
  id_key: sku
  text_key: photo_url
 
instance_display:
  layout:
    direction: horizontal
    gap: 24px
  fields:
    - key: photo_url
      type: image
      label: "Product Photo"
      display_options:
        max_width: 600
        zoomable: true
    - key: product_description
      type: text
      label: "Product Details"
 
annotation_schemes:
  - annotation_type: image_annotation
    name: product_regions
    description: "Draw boxes around products and defects"
    source_field: "photo_url"
    tools:
      - bbox
    labels:
      - name: "product"
        color: "#4ECDC4"
      - name: "defect"
        color: "#FF6B6B"
      - name: "label"
        color: "#45B7D1"
      - name: "packaging"
        color: "#96CEB4"
 
    ai_support:
      enabled: true
      features:
        detection: true
        pre_annotate: true
 
  - annotation_type: radio
    name: photo_quality
    description: "Is this photo suitable for the product listing?"
    labels:
      - Approved
      - Needs editing
      - Reshoot required
 
  - annotation_type: multiselect
    name: quality_issues
    description: "Select any issues present"
    labels:
      - Blurry
      - Poor lighting
      - Wrong angle
      - Background clutter
      - Color inaccurate
 
ai_support:
  enabled: true
  endpoint_type: "ollama"
  visual_endpoint_type: "yolo"
 
  ai_config:
    model: "llama3.2"
    include:
      all: true
 
  visual_ai_config:
    model: "yolov8m.pt"
    confidence_threshold: 0.5
 
output_annotation_dir: "annotation_output/"
export_annotation_format: "json"
user_config:
  allow_all_users: true

Dados de exemplo (data/product_photos.json):

json

{"sku": "SKU-001", "photo_url": "images/products/laptop_front.jpg", "product_description": "15-inch laptop, silver finish"}
{"sku": "SKU-002", "photo_url": "images/products/headphones_side.jpg", "product_description": "Over-ear wireless headphones, black"}
{"sku": "SKU-003", "photo_url": "images/products/backpack_full.jpg", "product_description": "40L hiking backpack, navy blue"}

Dicas para anotação com IA visual

Comece com a pré-anotação em grandes conjuntos de dados: aperte o botão Auto para gerar sugestões para tudo e, em seguida, peça aos anotadores que revisem e corrijam em vez de desenhar do zero
Combine o endpoint com a sua tarefa: YOLO para detecção precisa, VLLMs para classificação e compreensão
Ajuste os limiares de confiança: comece em 0,5 e mova conforme o equilíbrio entre falsos positivos e falsos negativos que você estiver vendo
Use dicas para treinar anotadores: o modo de dica orienta os anotadores sem direcioná-los a uma resposta específica
Combine endpoints: um endpoint YOLO para detecção mais um endpoint de texto Ollama para dicas cobre os dois lados
Armazene em cache os resultados da IA: ative o cache em disco para não reexecutar a detecção nas mesmas imagens

Solução de problemas

"No visual AI endpoint configured"

Verifique se ai_support.enabled está como true e se você definiu um endpoint_type compatível com visão: yolo, ollama_vision, openai_vision ou anthropic_vision.

O YOLO não está detectando seus objetos

As classes integradas do YOLO cobrem 80 objetos comuns. Se seus rótulos não corresponderem aos nomes de classe do YOLO, experimente o YOLO-World para detecção de vocabulário aberto, ou reduza o confidence_threshold.

O Ollama está retornando erros

Verifique se o Ollama está em execução e se você baixou um modelo de visão:

bash

curl http://localhost:11434/api/tags  # Check Ollama is running
ollama list                           # Check installed models

Resposta lenta das APIs na nuvem

Ative o cache para que a mesma imagem não seja analisada duas vezes:

yaml

ai_support:
  cache_config:
    disk_cache:
      enabled: true
      path: "ai_cache/visual_cache.json"

Próximos passos

Leia a documentação completa do Suporte a IA Visual para detalhes da referência da API
Configure o instance display para mostrar imagens ao lado de outros tipos de conteúdo
Explore o suporte a IA baseada em texto para dicas e destaque de palavras-chave

Documentação completa em /docs/features/visual-ai-support.