Usare l'AI Visiva per Accelerare l'Annotazione di Immagini e Video

Potato 2.1 introduce il supporto AI visivo che porta l'assistenza AI direttamente nei flussi di lavoro di annotazione di immagini e video. Invece di annotare ogni bounding box da zero, puoi far rilevare automaticamente gli oggetti a YOLO e poi revisionare i suoi suggerimenti, oppure chiedere a un modello vision-language di classificare le immagini e spiegare il suo ragionamento.

Questa guida illustra la configurazione di ciascun endpoint AI visivo, la configurazione delle diverse modalità di assistenza e la combinazione dell'AI visiva con le funzionalità AI basate su testo di Potato.

Cosa Imparerai

Configurare YOLO per il rilevamento rapido di oggetti in locale
Eseguire modelli Ollama Vision per la comprensione locale delle immagini
Usare le API vision cloud di OpenAI e Anthropic
Configurare le modalità di rilevamento, pre-annotazione, classificazione e hint
Combinare endpoint AI visivi e testuali in un unico progetto
Il flusso di lavoro accept/reject per revisionare i suggerimenti AI

Prerequisiti

Ti servirà Potato 2.1.0 o versione successiva:

bash

pip install --upgrade potato-annotation

E a seconda dell'endpoint scelto, ti servirà uno di questi:

YOLO: pip install ultralytics opencv-python
Ollama: Installa da ollama.ai e scarica un modello vision
OpenAI: Una API key con accesso a GPT-4o
Anthropic: Una API key con accesso ai modelli vision di Claude

Opzione 1: YOLO per il Rilevamento di Oggetti

YOLO è la scelta migliore quando hai bisogno di un rilevamento preciso di bounding box che gira interamente sulla tua macchina locale. Eccelle nel rilevare oggetti comuni (persone, auto, animali, mobili) e può elaborare le immagini in millisecondi.

Configurazione

bash

pip install ultralytics opencv-python

Configurazione del Progetto

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 dei Dati

Crea data/images.json in formato JSONL (un oggetto JSON per riga):

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

Scegliere un Modello YOLO

Modello	Dimensione	Velocità	Accuratezza	Ideale Per
`yolov8n.pt`	6 MB	Massima	Inferiore	Prototipazione rapida
`yolov8s.pt`	22 MB	Rapida	Buona	Carichi di lavoro bilanciati
`yolov8m.pt`	50 MB	Media	Migliore	Uso generale
`yolov8l.pt`	84 MB	Più lenta	Alta	Quando l'accuratezza è importante
`yolov8x.pt`	131 MB	Più lenta	Massima	Precisione massima

Per rilevare oggetti non nelle classi predefinite di YOLO, usa YOLO-World per il rilevamento open-vocabulary:

yaml

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

Ottimizzare il Rilevamento

Se YOLO non rileva gli oggetti, abbassa la soglia di confidenza:

yaml

ai_config:
  confidence_threshold: 0.3  # Più rilevamenti, più falsi positivi

Se ottieni troppi falsi positivi, alzala:

yaml

ai_config:
  confidence_threshold: 0.7  # Meno rilevamenti, precisione più alta

Opzione 2: Ollama Vision per VLLM Locali

Ollama Vision ti dà la potenza dei modelli vision-language che girano in locale. A differenza di YOLO, questi modelli possono comprendere il contesto dell'immagine, classificare scene e generare spiegazioni testuali -- tutto senza inviare dati a un'API cloud.

Configurazione

bash

# Installa Ollama
curl -fsSL https://ollama.ai/install.sh | sh
 
# Scarica un modello vision
ollama pull llava
 
# O per prestazioni migliori:
ollama pull qwen2.5-vl:7b

Configurazione del Progetto

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

Modelli Supportati

Modello	Parametri	Punti di Forza
`llava:7b`	7B	Veloce, buona comprensione generale
`llava:13b`	13B	Migliore accuratezza
`llava-llama3`	8B	Ragionamento robusto
`bakllava`	7B	Buon dettaglio visivo
`llama3.2-vision:11b`	11B	Ultimo modello vision Llama
`qwen2.5-vl:7b`	7B	Forte supporto multilingue + vision
`moondream`	1.8B	Molto veloce, leggero

Opzione 3: OpenAI Vision

OpenAI Vision fornisce una comprensione delle immagini di alta qualità attraverso GPT-4o. È la scelta migliore quando hai bisogno del modello vision più capace e non ti preoccupi dei costi dell'API cloud.

Configurazione del Progetto

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" per maggiore velocità/risparmio, "high" per i dettagli

Imposta la tua API key:

bash

export OPENAI_API_KEY="sk-..."

Il parametro detail controlla la risoluzione dell'immagine inviata all'API:

low — Più veloce ed economico, adatto per la classificazione
high — Risoluzione piena, migliore per trovare oggetti piccoli
auto — Lascia che l'API decida

Opzione 4: Anthropic Vision

Le capacità vision di Claude sono forti nella comprensione del contesto delle immagini e nel fornire spiegazioni dettagliate.

Configurazione del Progetto

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

Modalità di Assistenza AI

Ogni endpoint AI visivo supporta diverse modalità di assistenza. Abilita solo quelle di cui hai bisogno per ogni schema di annotazione.

Modalità Rilevamento

Trova gli oggetti corrispondenti alle tue etichette configurate e li mostra come overlay con bounding box tratteggiati:

yaml

ai_support:
  enabled: true
  features:
    detection: true

L'annotatore clicca "Detect", e i suggerimenti AI appaiono come overlay tratteggiati sull'immagine. Doppio clic per accettare, clic destro per rifiutare.

Modalità Pre-annotazione (Auto)

Rileva automaticamente tutti gli oggetti e crea suggerimenti in un solo passaggio. Ideale per l'avvio di dataset di grandi dimensioni:

yaml

ai_support:
  enabled: true
  features:
    pre_annotate: true

Modalità Classificazione

Classifica una regione selezionata o l'intera immagine, restituendo un'etichetta suggerita con un punteggio di confidenza:

yaml

ai_support:
  enabled: true
  features:
    classification: true

Modalità Hint

Fornisce testo guida senza rivelare la risposta. Adatto per la formazione di nuovi annotatori:

yaml

ai_support:
  enabled: true
  features:
    hint: true

Il Flusso di Lavoro Accept/Reject

Quando un annotatore clicca un pulsante di assistenza AI, i suggerimenti appaiono come overlay tratteggiati:

Accetta un suggerimento — Doppio clic sull'overlay tratteggiato per convertirlo in un'annotazione reale
Rifiuta un suggerimento — Clic destro sull'overlay per rimuoverlo
Accetta tutti — Clicca "Accept All" nella barra degli strumenti per accettare tutti i suggerimenti in una volta
Cancella tutti — Clicca "Clear" per rimuovere tutti i suggerimenti

Questo mantiene gli annotatori in controllo riducendo il lavoro manuale di disegnare box da zero.

Annotazione Video con AI Visiva

L'AI visiva funziona anche con i task di annotazione video. Puoi abilitare il rilevamento di scene, il rilevamento di keyframe e il tracciamento di oggetti:

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  # Numero di frame da campionare

Il parametro max_frames controlla quanti frame l'AI campiona dal video per l'analisi. Più frame significa una migliore accuratezza ma un'elaborazione più lenta.

Combinare Endpoint AI Visivi e Testuali

Se il tuo progetto ha sia annotazioni testuali che di immagini, puoi configurare endpoint separati per ciascuno. Usa un modello ottimizzato per il testo per hint e parole chiave, e un modello vision per il rilevamento:

yaml

ai_support:
  enabled: true
 
  # AI testuale per radio button, schemi di testo, ecc.
  endpoint_type: "ollama"
  ai_config:
    model: "llama3.2"
    include:
      all: true
 
  # AI visiva per schemi di immagini/video
  visual_endpoint_type: "yolo"
  visual_ai_config:
    model: "yolov8m.pt"
    confidence_threshold: 0.5

Oppure usa un modello vision cloud insieme a un modello testuale locale:

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"

Esempio Completo: Annotazione di Foto di Prodotti

Ecco una configurazione pronta per la produzione per annotare foto di prodotti con rilevamento YOLO e hint AI basati su testo:

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/"
output_annotation_format: "json"
user_config:
  allow_all_users: true

Dati di esempio (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"}

Suggerimenti per l'Annotazione AI Visiva

Inizia con la pre-annotazione per dataset grandi — Usa il pulsante Auto per generare suggerimenti per tutti gli oggetti, poi lascia che gli annotatori revisionino e correggano invece di disegnare da zero
Abbina l'endpoint al tuo task — YOLO per il rilevamento preciso, VLLM per la classificazione e la comprensione
Ottimizza le soglie di confidenza — Inizia con 0.5 e regola in base al bilanciamento falsi positivi/negativi che osservi
Usa gli hint per la formazione degli annotatori — La modalità hint guida gli annotatori senza orientarli verso una risposta specifica
Combina gli endpoint — Un endpoint visivo YOLO per il rilevamento più un endpoint testuale Ollama per gli hint ti dà il meglio di entrambi i mondi
Memorizza i risultati AI nella cache — Abilita la cache su disco per evitare di ri-eseguire il rilevamento sulle stesse immagini

Risoluzione dei Problemi

"No visual AI endpoint configured"

Assicurati che ai_support.enabled sia true e di aver impostato un endpoint_type che supporta la vision: yolo, ollama_vision, openai_vision o anthropic_vision.

YOLO non rileva i tuoi oggetti

Le classi predefinite di YOLO coprono 80 oggetti comuni. Se le tue etichette non corrispondono ai nomi delle classi di YOLO, prova YOLO-World per il rilevamento open-vocabulary, oppure abbassa il confidence_threshold.

Ollama restituisce errori

Verifica che Ollama stia girando e che tu abbia scaricato un modello vision:

bash

curl http://localhost:11434/api/tags  # Verifica che Ollama sia in esecuzione
ollama list                           # Controlla i modelli installati

Risposta lenta dalle API cloud

Abilita la cache in modo che la stessa immagine non venga analizzata due volte:

yaml

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

Prossimi Passi

Leggi la documentazione completa del Visual AI Support per i dettagli di riferimento dell'API
Configura l'instance display per mostrare le immagini insieme ad altri tipi di contenuto
Esplora il supporto AI basato su testo per hint ed evidenziazione di parole chiave

Documentazione completa su /docs/features/visual-ai-support.