Skip to content

快速入門

在 5 分鐘內跑起 Potato。用 pip 安裝、寫一份 YAML 配置、啟動伺服器，無需寫程式碼就能標註第一個資料集。

本指南帶你從全新安裝到開始標註資料，用時不到 5 分鐘。它介紹如何自己編寫任務。另一種開始方式是把研究描述給程式設計智慧體，讓 potato-skill 來設計和構建，見使用程式設計智慧體快速入門。

Potato 的五個步驟：安裝、配置、啟動伺服器、在瀏覽器中標註、匯出Potato 的五個步驟

前提條件

  • Python 3.9 或更高版本
  • pip 包管理器
  • 一個終端

安裝

建議把 Potato 裝到虛擬環境裡，以免與系統 Python 衝突：

bash
python -m venv potato-env
source potato-env/bin/activate   # Windows: potato-env\Scripts\activate
pip install potato-annotation

驗證安裝：

bash
python -c "import potato; print(potato.__version__)"

應該會打印出 2.11.1。從 2.9 版開始，potato --version 報告同樣的版本號，並且在從程式碼庫執行時會附帶 commit。

建立你的第一個項目

1. 建立項目目錄

bash
mkdir my-annotation-task
cd my-annotation-task

2. 建立資料檔案

建立一個 data 資料夾，並在其中放一個名為 data.json 的檔案：

bash
mkdir data
json
[
  {"id": "1", "text": "I love this product! It's amazing."},
  {"id": "2", "text": "This is the worst experience ever."},
  {"id": "3", "text": "It's okay, nothing special."}
]

data_files 還接受 .jsonl（每行一個 JSON 物件）、.csv 和 .tsv。指向帶相應副檔名的檔案，Potato 會據此選擇讀取器。

3. 建立配置檔案

在項目目錄中建立一個名為 config.yaml 的檔案：

路徑沙箱：配置裡的所有相對路徑（例如 data_files 或 output_annotation_dir）都相對 task_dir 解析，並且必須留在其內部。解析後落在 task_dir 之外的路徑會被拒絕，以防止路徑穿越。

yaml
annotation_task_name: "Sentiment Analysis"
 
# All relative paths below are resolved against task_dir.
task_dir: "."
 
# Data configuration
data_files:
  - "data/data.json"
 
# Tell Potato which fields in each record to use.
# id_key = unique identifier; text_key = the text shown to annotators.
item_properties:
  id_key: id
  text_key: text
 
# Where per-user annotation state is stored (relative to task_dir).
output_annotation_dir: "annotation_output/"
 
# Also write a periodic flat export, because the per-user state files are
# awkward to analyze. No exporter is named "json", so use "jsonl".
export_annotation_format: "jsonl"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"   # required for radio schemes
    labels:
      - Positive
      - Negative
      - Neutral
 
# Skip password authentication so anyone can log in with just a username.
require_password: false

提示：你可以用預覽 CLI 在不啟動完整伺服器的情況下校驗配置。這是開始標註前發現拼寫錯誤的最快方式。

4. 啟動伺服器

bash
potato start config.yaml -p 8000

等價的完整寫法：

bash
python -m potato start config.yaml -p 8000

如果 8000 埠已被佔用，用 -p 8001 換一個。要停止伺服器，在終端中按 Ctrl+C。

讓首次執行更快：試驗階段可以加上 --debug --debug-phase=annotation，跳過登入和知情同意頁面：potato start config.yaml --debug --debug-phase=annotation。這樣每個訪問者都會以同一個共享的 debug_user 身份登入，所以只在你自己的機器上使用。

5. 開啟瀏覽器

訪問 http://localhost:8000。你會看到一個只有 username 欄位的登入頁面。隨便輸入（例如 alice）並點選 Continue，就可以開始標註了。

每次選擇標籤並點選 Next，標註都會自動儲存。沒有單獨的"儲存"按鈕。

標註儲存在哪裡

Potato 在你標註的同時寫入每個使用者的狀態：

text
my-annotation-task/
├── config.yaml
├── data/
│   └── data.json
└── annotation_output/              # created automatically
    └── alice/
        └── user_state.json         # one folder per username

user_state.json 儲存該使用者的完整標註狀態。要生成一個跨所有標註者的合併平鋪檔案，請執行 Potato 的匯出 CLI，匯出文件對此有說明。執行 python -m potato.export --list-formats 可以檢視它註冊的所有格式。

首次執行的常見問題

  • Address already in use —— 8000 埠被佔用。用 -p 8001（或任何空閒埠）。
  • KeyError: 'description' —— 某個 radio（或類似）方案缺少必填的 description 欄位。每個方案都需要它。
  • Path ... is outside the task directory —— 某個 data_files 或 output_annotation_dir 路徑跑到了 task_dir 之外。把所有內容放在項目資料夾內，或者把 task_dir 設為包含它們的絕對路徑。
  • 登入頁面出現密碼欄位 —— 你忘了 require_password: false，或者瀏覽器標籤頁有快取。重啟伺服器並強制重新整理。

常見問題

下面的問題涉及安裝 Potato、在 Docker 中執行它，以及在標註者看到配置之前檢查配置。

如何安裝 Potato？

在 Python 3.9 或更高版本上，用 pip install potato-annotation 從 PyPI 安裝。裝在虛擬環境裡可以讓 Potato 的依賴與系統 Python 分開，potato --version 會列印版本號，以此確認安裝成功。

Potato 能在 Docker 中執行嗎？

能。Potato 在 GitHub Container Registry 上釋出了一個預構建映像 ghcr.io/davidjurgens/potato。項目資料夾掛載到容器內的 /app，伺服器在容器內監聽 7860 埠，因此一個映像可以執行所有任務。設定 POTATO_SECRET_KEY，標註者的會話在重啟後才能保留。完整的 docker run 命令見在伺服器上部署 Potato。

如何在標註者看到之前檢查 Potato 配置？

執行 potato validate config.yaml --strict。它按伺服器啟動時的方式檢查配置，並把警告（例如無法識別的鍵）當作失敗處理。接著，potato preview config.yaml 會顯示配置宣告的內容，並在瀏覽器中渲染介面，這樣在任何人登入之前，你就能看到標註者將會看到的任務。

下一步

工具與實用程式

熟悉基礎之後，可以看看這些實用工具：