Skip to content
Cette page n'est pas encore disponible dans votre langue. La version anglaise est affichée.

Visualizzazione delle Istanze

Separa la visualizzazione del contenuto dall'annotazione con il blocco di configurazione instance_display.

Visualizzazione delle Istanze

Novità nella v2.1.0

La visualizzazione delle istanze separa il contenuto da mostrare agli annotatori dalle annotazioni da raccogliere. Questo consente di visualizzare qualsiasi combinazione di tipi di contenuto (immagini, video, audio, testo) insieme a qualsiasi schema di annotazione (pulsanti radio, caselle di controllo, span, ecc.).

Perché Usare la Visualizzazione delle Istanze?

In precedenza, per mostrare un'immagine con pulsanti radio per la classificazione, era necessario aggiungere uno schema image_annotation con min_annotations: 0 solo per visualizzare l'immagine. Questo era confuso e semanticamente scorretto.

Con instance_display, si configura esplicitamente il contenuto da visualizzare:

yaml
# OLD (deprecated workaround)
annotation_schemes:
  - annotation_type: image_annotation
    name: image_display
    min_annotations: 0  # Just to show the image
    tools: [bbox]
    labels: [unused]
  - annotation_type: radio
    name: category
    labels: [A, B, C]
 
# NEW (recommended)
instance_display:
  fields:
    - key: image_url
      type: image
 
annotation_schemes:
  - annotation_type: radio
    name: category
    labels: [A, B, C]

Configurazione Base

Aggiungi una sezione instance_display alla tua configurazione YAML:

yaml
instance_display:
  fields:
    - key: "image_url"           # Field name in your data JSON
      type: "image"              # Content type
      label: "Image to classify" # Optional header
      display_options:
        max_width: 600
        zoomable: true
 
  layout:
    direction: "vertical"        # vertical or horizontal
    gap: "20px"

Tipi di Visualizzazione Supportati

TipoDescrizioneTarget Span
textContenuto testuale sempliceSì
htmlContenuto HTML sanificatoNo
imageVisualizzazione immagine con zoomNo
videoLettore videoNo
audioLettore audioNo
dialogueTurni di conversazioneSì
pairwiseConfronto affiancatoNo
codeCodice sorgente con evidenziazione della sintassiSì
spreadsheetDati tabulari (Excel/CSV)Sì (riga/cella)
documentDocumenti ricchi (Word, Markdown, HTML)Sì
pdfDocumenti PDF con controlli di paginaSì

Opzioni per i Tipi di Visualizzazione

Visualizzazione Testo

yaml
- key: "text"
  type: "text"
  label: "Document"
  display_options:
    collapsible: false        # Make content collapsible
    max_height: 400           # Max height in pixels before scrolling
    preserve_whitespace: true # Preserve line breaks and spacing

Visualizzazione Immagine

yaml
- key: "image_url"
  type: "image"
  label: "Image"
  display_options:
    max_width: 800            # Max width (number or CSS string)
    max_height: 600           # Max height
    zoomable: true            # Enable zoom controls
    alt_text: "Description"   # Alt text for accessibility
    object_fit: "contain"     # CSS object-fit property

Visualizzazione Video

yaml
- key: "video_url"
  type: "video"
  label: "Video"
  display_options:
    max_width: 800
    max_height: 450
    controls: true            # Show video controls
    autoplay: false           # Auto-play on load
    loop: false               # Loop playback
    muted: false              # Start muted

Visualizzazione Audio

yaml
- key: "audio_url"
  type: "audio"
  label: "Audio"
  display_options:
    controls: true            # Show audio controls
    autoplay: false
    loop: false
    show_waveform: false      # Show waveform visualization
yaml
- key: "conversation"
  type: "dialogue"
  label: "Conversation"
  display_options:
    alternating_shading: true    # Alternate background colors
    speaker_extraction: true     # Extract "Speaker:" from text
    show_turn_numbers: false     # Show turn numbers

Formato dei dati per il dialogo (ogni riga in un file JSONL):

json
{"id": "conv_001", "conversation": ["Speaker A: Hello there!", "Speaker B: Hi, how are you?"]}

Oppure con dati strutturati:

json
{"id": "conv_001", "conversation": [{"speaker": "Alice", "text": "Hello there!"}, {"speaker": "Bob", "text": "Hi, how are you?"}]}

Visualizzazione a Coppie

yaml
- key: "comparison"
  type: "pairwise"
  label: "Compare Options"
  display_options:
    cell_width: "50%"           # Width of each cell
    show_labels: true           # Show A/B labels
    labels: ["Option A", "Option B"]
    vertical_on_mobile: true    # Stack vertically on mobile

Opzioni di Layout

Controlla come vengono disposti più campi:

yaml
instance_display:
  layout:
    direction: horizontal  # horizontal or vertical
    gap: 24px              # Space between fields

Supporto per l'Annotazione di Span

I tipi di visualizzazione basati su testo (text, dialogue) possono essere target per l'annotazione di span:

yaml
instance_display:
  fields:
    - key: "document"
      type: "text"
      span_target: true  # Enable span annotation on this field
 
annotation_schemes:
  - annotation_type: span
    name: entities
    labels: [PERSON, LOCATION, ORG]

Target Span Multipli

Puoi avere più campi di testo che supportano l'annotazione di span:

yaml
instance_display:
  fields:
    - key: "source_text"
      type: "text"
      label: "Source Document"
      span_target: true
 
    - key: "summary"
      type: "text"
      label: "Summary"
      span_target: true
 
annotation_schemes:
  - annotation_type: span
    name: factual_errors
    labels: [contradiction, unsupported, fabrication]

Quando si usano più target span, le annotazioni vengono memorizzate con l'associazione al campo:

json
{
  "factual_errors": {
    "source_text": [],
    "summary": [
      {"start": 45, "end": 67, "label": "unsupported"}
    ]
  }
}

Collegamento degli Schemi di Annotazione ai Campi di Visualizzazione

Per gli schemi di annotazione multimediali (image_annotation, video_annotation, audio_annotation), collegali ai campi di visualizzazione usando source_field:

yaml
instance_display:
  fields:
    - key: "image_url"
      type: "image"
 
annotation_schemes:
  - annotation_type: image_annotation
    source_field: "image_url"  # Links to display field
    tools: [bbox]
    labels: [person, car]

Valutazioni Per-Turno nei Dialoghi

Aggiungi widget di valutazione inline ai singoli turni del dialogo:

yaml
instance_display:
  fields:
    - key: conversation
      type: dialogue
      label: "Conversation"
      display_options:
        show_turn_numbers: true
        per_turn_ratings:
          speakers: ["Agent"]          # Only show ratings for these speakers
          schema_name: "turn_quality"  # Name for the stored annotation data
          scheme:
            type: likert
            size: 5
            labels: ["Poor", "Excellent"]

I cerchi di valutazione appaiono inline sotto il turno di ogni parlante corrispondente. Le valutazioni si riempiono fino al valore selezionato e tutte le valutazioni per turno vengono memorizzate come un singolo oggetto JSON:

json
{
  "turn_quality": "{\"0\": 4, \"2\": 5, \"4\": 3}"
}

Esempio: Classificazione di Immagini

yaml
annotation_task_name: "Image Classification"
 
data_files:
  - data/images.json
 
item_properties:
  id_key: id
  text_key: image_url
 
task_dir: .
output_annotation_dir: annotation_output
 
instance_display:
  fields:
    - key: image_url
      type: image
      label: "Image to Classify"
      display_options:
        max_width: 600
        zoomable: true
 
    - key: context
      type: text
      label: "Additional Context"
      display_options:
        collapsible: true
 
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "What category best describes this image?"
    labels:
      - nature
      - urban
      - people
      - objects
 
user_config:
  allow_all_users: true

File di dati di esempio (data/images.json) in formato JSONL:

json
{"id": "img_001", "image_url": "https://example.com/image1.jpg", "context": "Taken in summer 2023"}
{"id": "img_002", "image_url": "https://example.com/image2.jpg", "context": "Winter landscape"}

Esempio: Annotazione Multi-Modale

Video affiancato a una trascrizione con annotazione di span:

yaml
annotation_task_name: "Video Analysis"
 
instance_display:
  layout:
    direction: horizontal
    gap: 24px
 
  fields:
    - key: video_url
      type: video
      label: "Video"
      display_options:
        max_width: "45%"
 
    - key: transcript
      type: text
      label: "Transcript"
      span_target: true
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    labels: [positive, neutral, negative]
 
  - annotation_type: span
    name: highlights
    labels:
      - key_point
      - question
      - supporting_evidence

Compatibilità con le Versioni Precedenti

  • Le configurazioni esistenti senza instance_display continuano a funzionare senza modifiche
  • Il text_key di item_properties viene ancora usato come fallback
  • Il rilevamento legacy dei media tramite schemi di annotazione funziona ancora
  • Nei log appare un avviso di deprecazione quando si usa il vecchio pattern di sola visualizzazione

Migrazione dai Pattern di Sola Visualizzazione

Se stavi usando schemi di annotazione solo per visualizzare contenuti:

Prima (deprecato):

yaml
annotation_schemes:
  - annotation_type: image_annotation
    name: image_display
    min_annotations: 0
    tools: [bbox]
    labels: [unused]

Dopo (raccomandato):

yaml
instance_display:
  fields:
    - key: image_url
      type: image

Approfondimenti

Per i dettagli implementativi, consulta la documentazione sorgente.