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

延伸阅读

有关实现细节，请参阅源文档。