Skip to content

資料格式

支援的資料格式及如何構建標註資料。

Potato 開箱即用地支援多種資料格式。本指南介紹如何構建您的標註資料。

How data flows through Potato: input files become instances with an id and text plus metadata, get annotated, and are exported to many formatsFrom input file to exported labels

支援的格式

格式副檔名描述
JSON.json物件陣列
JSON Lines.jsonl每行一個 JSON 物件
CSV.csv逗號分隔值
TSV.tsv製表符分隔值

JSON 格式

最常用的格式。您的資料應該是一個物件陣列：

json
[
  {
    "id": "doc_001",
    "text": "This is the first document to annotate.",
    "source": "twitter",
    "date": "2024-01-15"
  },
  {
    "id": "doc_002",
    "text": "This is the second document.",
    "source": "reddit",
    "date": "2024-01-16"
  }
]

JSON Lines 格式

每行是一個單獨的 JSON 物件。適用於大型資料集：

jsonl
{"id": "doc_001", "text": "First document"}
{"id": "doc_002", "text": "Second document"}
{"id": "doc_003", "text": "Third document"}

CSV/TSV 格式

帶標題的表格資料：

csv
id,text,source
doc_001,"This is the first document",twitter
doc_002,"This is the second document",reddit

配置

基本設定

在 YAML 中配置資料檔案和欄位對映：

yaml
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id      # Field name for unique ID
  text_key: text  # Field name for content to annotate

多資料檔案

組合多個數據源：

yaml
data_files:
  - "data/batch_1.json"
  - "data/batch_2.json"
  - "data/batch_3.jsonl"

檔案按順序處理併合並。

資料類型

純文本

簡單的文本內容：

json
{
  "id": "1",
  "text": "The product arrived quickly and works great!"
}

媒體檔案

引用影像、影片或音訊：

json
{
  "id": "1",
  "image_path": "images/photo_001.jpg"
}
yaml
item_properties:
  id_key: id
  image_key: image_path

對話/列表

列表會自動以水平方式顯示：

json
{
  "id": "1",
  "text": "Option A,Option B,Option C"
}

文本對

用於比較任務：

json
{
  "id": "pair_001",
  "text": {
    "A": "Response from Model A",
    "B": "Response from Model B"
  }
}

HTML 檔案

引用儲存在資料夾中的 HTML 檔案：

json
{
  "id": "1",
  "html_file": "html/document_001.html"
}

上下文標註

在主文本旁包含上下文：

json
{
  "id": "1",
  "text": "This is great!",
  "context": "Previous message: How do you like the new feature?"
}
yaml
item_properties:
  id_key: id
  text_key: text
  context_key: context

顯示配置

列表顯示選項

控制列表和字典的顯示方式：

yaml
list_as_text:
  # Add prefixes to items
  text_prefix: "A"  # A., B., C. (or "1" for 1., 2., 3.)
 
  # Display orientation
  horizontal: true  # Side-by-side (false for vertical)
 
  # Randomization
  randomize_values: true   # Shuffle list items
  randomize_keys: true     # Shuffle dictionary keys

HTML 內容

在文本中啟用 HTML 渲染：

yaml
html_content: true
json
{
  "id": "1",
  "text": "<p>This is <strong>formatted</strong> text.</p>"
}

輸出配置

輸出目錄

指定標註儲存位置：

yaml
output_annotation_dir: "output/"

輸出格式

選擇輸出格式：

yaml
output_annotation_format: "json"  # json, jsonl, csv, or tsv

輸出結構

標註包含文件 ID 和回覆：

json
{
  "id": "doc_001",
  "user": "annotator_1",
  "annotations": {
    "sentiment": "Positive",
    "confidence": 4
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

特殊資料類型

最佳-最差縮放

用於排名任務，使用逗號分隔的項目：

json
{
  "id": "1",
  "text": "Item A,Item B,Item C,Item D"
}

自定義參數

包含額外欄位用於顯示或篩選：

json
{
  "id": "1",
  "text": "Document content",
  "category": "news",
  "priority": "high",
  "custom_field": "any value"
}

資料庫後端

對於大型資料集，使用 MySQL：

yaml
database:
  type: mysql
  host: localhost
  database: potato_db
  user: ${DB_USER}
  password: ${DB_PASSWORD}

Potato 在首次啟動時自動建立所需的表。

資料驗證

Potato 在啟動時驗證您的資料：

  • 缺少 ID 欄位 - 所有項目都需要唯一識別符號
  • 缺少文本欄位 - 項目需要標註內容
  • 重複 ID - 所有 ID 必須唯一
  • 檔案未找到 - 驗證資料檔案路徑

完整示例

yaml
task_name: "Document Classification"
task_dir: "."
port: 8000
 
# Data configuration
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id
  text_key: text
  context_key: metadata
 
# Display settings
list_as_text:
  text_prefix: "1"
  horizontal: false
 
# Output
output_annotation_dir: "output/"
output_annotation_format: "json"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "Select the document category"
    labels:
      - News
      - Opinion
      - Tutorial
      - Other
 
allow_all_users: true

最佳實踐

1. 使用有意義的 ID

使跟蹤和除錯更加容易：

json
{"id": "twitter_2024_001", "text": "..."}

2. 保持文本簡潔

過長的文本會減慢標註速度。考慮：

  • 擷取關鍵部分
  • 提供摘要
  • 使用滾動容器

3. 包含後設資料

有助於篩選和分析：

json
{
  "id": "1",
  "text": "Content",
  "source": "twitter",
  "date": "2024-01-15",
  "language": "en"
}

4. 載入前進行驗證

離線檢查您的資料：

python
import json
 
with open('data.json') as f:
    data = json.load(f)
 
# Check for required fields
for item in data:
    assert 'id' in item, f"Missing id: {item}"
    assert 'text' in item, f"Missing text: {item}"
 
# Check for duplicates
ids = [item['id'] for item in data]
assert len(ids) == len(set(ids)), "Duplicate IDs found"
 
print(f"Validated {len(data)} items")

5. 備份原始資料

將原始資料與標註分開儲存，以確保可重複性。

6. 大檔案使用 JSON Lines

比 JSON 陣列更節省記憶體：

bash
# Convert JSON array to JSON Lines
cat data.json | jq -c '.[]' > data.jsonl

延伸閱讀

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