Exibição de Instâncias

Configure o bloco instance_display para controlar como texto, imagens, áudio e vídeo aparecem ao lado dos controles de anotação na sua tarefa do Potato.

Novo na v2.1.0

A exibição de instâncias separa qual conteúdo mostrar aos anotadores de quais anotações coletar. Isso permite exibir qualquer combinação de tipos de conteúdo (imagens, vídeos, áudio, texto) ao lado de qualquer esquema de anotação (botões de rádio, caixas de seleção, spans etc.).

Por Que Usar a Exibição de Instâncias?

Anteriormente, se você quisesse mostrar uma imagem com botões de rádio para classificação, precisava adicionar um esquema image_annotation com min_annotations: 0 apenas para exibir a imagem. Isso era confuso e semanticamente incorreto.

Com instance_display, você configura explicitamente qual conteúdo exibir:

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]

Configuração Básica

Adicione uma seção instance_display à sua configuração 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"

Tipos de Exibição Suportados

Tipo	Descrição	Alvo de Span
`text`	Conteúdo de texto simples	Sim
`html`	Conteúdo HTML sanitizado	Não
`image`	Exibição de imagem com zoom	Não
`video`	Reprodutor de vídeo	Não
`audio`	Reprodutor de áudio	Não
`dialogue`	Turnos de conversa	Sim
`pairwise`	Comparação lado a lado	Não
`code`	Código-fonte com destaque de sintaxe	Sim
`spreadsheet`	Dados tabulares (Excel/CSV)	Sim (linha/célula)
`document`	Documentos ricos (Word, Markdown, HTML)	Sim
`pdf`	Documentos PDF com controles de página	Sim

Opções de Tipo de Exibição

Exibição de Texto

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

Exibição de Imagem

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

Exibição de Vídeo

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

Exibição de Áudio

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

Exibição de Diálogo

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 de dados para diálogo (cada linha no arquivo JSONL):

json

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

Ou com dados estruturados:

json

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

Exibição Pareada

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

Opções de Layout

Controle como vários campos são organizados:

yaml

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

Suporte à Anotação de Span

Os tipos de exibição baseados em texto (text, dialogue) podem ser alvos de anotação de 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]

Vários Alvos de Span

Você pode ter vários campos de texto que oferecem suporte à anotação de 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 vários alvos de span são usados, as anotações são armazenadas com associação de campo:

json

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

Vinculando Esquemas de Anotação a Campos de Exibição

Para esquemas de anotação de mídia (image_annotation, video_annotation, audio_annotation), vincule-os a campos de exibição 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]

Avaliações de Diálogo por Turno

Adicione widgets de avaliação inline a turnos individuais do diálogo:

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

Círculos de avaliação aparecem inline abaixo do turno de cada falante correspondente. As avaliações são preenchidas até o valor selecionado, e todas as avaliações por turno são armazenadas como um único objeto JSON:

json

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

Exemplo: Classificação de Imagens

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

Arquivo de dados de amostra (data/images.json) no 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"}

Exemplo: Anotação Multimodal

Vídeo ao lado de uma transcrição com anotação de 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

Compatibilidade com Versões Anteriores

Configurações existentes sem instance_display continuam funcionando sem alterações
O text_key de item_properties ainda é usado como fallback
A detecção de mídia legada via esquemas de anotação ainda funciona
Um aviso de descontinuação aparece nos logs ao usar o antigo padrão somente de exibição

Migração de Padrões Somente de Exibição

Se você estava usando esquemas de anotação apenas para exibir conteúdo:

Antes (descontinuado):

yaml

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

Depois (recomendado):

yaml

instance_display:
  fields:
    - key: image_url
      type: image

Leitura Complementar

Formatos de Dados - Formatos de dados de entrada suportados
Configuração da Interface - Personalização da interface
Personalização de Layout - Templates HTML personalizados
Anotação de Imagem - Ferramentas de anotação de imagem

Para detalhes de implementação, consulte a documentação de origem.