Skip to content

實例顯示

使用instance_display配置塊將內容顯示與標註分離。

v2.1.0 新增

實例顯示將向標註者展示什麼內容與收集什麼標註分離。這使您可以在任何標註方案（單選按鈕、核取方塊、片段等）旁邊顯示任意組合的內容類型（影像、影片、音訊、文本）。

實例顯示如何對映欄位 — 類型化顯示告訴 Potato 如何渲染條目的每個欄位實例顯示如何對映欄位

為什麼使用實例顯示？

以前，如果您想在影像旁顯示單選按鈕進行分類，您不得不新增一個 image_annotation 方案並設定 min_annotations: 0 來顯示影像。這種做法令人困惑且語義上不正確。

使用 instance_display，您可以明確配置要顯示的內容：

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]

基本配置

在 YAML 配置中新增 instance_display 部分：

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"

支援的顯示類型

類型描述片段目標
text純文本內容是
html經過清理的 HTML 內容否
image帶縮放的影像顯示否
video影片播放器否
audio音訊播放器否
dialogue對話輪次是
pairwise並排比較否
code語法高亮的原始碼是
spreadsheet表格資料（Excel/CSV）是（行/單元格）
document富文件（Word、Markdown、HTML）是
pdf帶頁面控制的 PDF 文件是

顯示類型選項

文本顯示

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

影像顯示

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

影片顯示

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

音訊顯示

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

對話的資料格式（JSONL 檔案中的每一行）：

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

或者使用結構化資料：

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

成對顯示

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

佈局選項

控制多個欄位的排列方式：

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

片段標註支援

基於文本的顯示類型（text、dialogue）可以作為片段標註的目標：

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]

多片段目標

您可以擁有多個支援片段標註的文本欄位：

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]

當使用多個片段目標時，標註會帶有欄位關聯儲存：

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

將標註方案連結到顯示欄位

對於媒體標註方案（image_annotation、video_annotation、audio_annotation），使用 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]

逐輪次對話評分

為單個對話輪次新增內聯評分元件：

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

評分圓圈內聯顯示在每個匹配說話者的輪次下方。評分會填充到選定值，所有逐輪次評分作為單個 JSON 物件儲存：

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

示例：影像分類

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

示例資料檔案（data/images.json），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"}

示例：多模態標註

影片與帶有片段標註的文本稿並排顯示：

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

向後相容性

  • 沒有 instance_display 的現有配置繼續正常工作
  • item_properties 中的 text_key 仍作為後備使用
  • 通過標註方案進行的舊版媒體檢測仍然有效
  • 使用舊的僅顯示模式時，日誌中會出現棄用警告

從僅顯示模式遷移

如果您之前使用標註方案僅僅是為了顯示內容：

之前（已棄用）：

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

之後（推薦）：

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

延伸閱讀

有關實現細節，請參閱源文件。