Skip to content

本地開發

設定 Potato 用於本地開發和測試。

在本地機器上執行 Potato 進行開發和測試。

前提條件

  • Python 3.7 或更高版本
  • pip 包管理器
  • Git（可選，用於克隆示例）

安裝

使用 pip（推薦）

bash
pip install potato-annotation

從原始碼安裝

bash
git clone https://github.com/davidjurgens/potato.git
cd potato
pip install -e .

安裝可選依賴

bash
# For audio annotation support
pip install potato-annotation[audio]
 
# For all optional features
pip install potato-annotation[all]

快速開始

1. 建立配置檔案

建立 config.yaml：

yaml
task_name: "My First Annotation Task"
 
server:
  port: 8000
 
data_files:
  - path: data.json
    text_field: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels:
      - Positive
      - Negative
      - Neutral
 
output:
  path: annotations/

2. 準備示例資料

建立 data.json：

json
[
  {"id": "1", "text": "I love this product!"},
  {"id": "2", "text": "This is terrible."},
  {"id": "3", "text": "It's okay, nothing special."}
]

3. 啟動伺服器

bash
potato start config.yaml

4. 訪問介面

在瀏覽器中開啟 http://localhost:8000

開發模式

熱過載

啟用配置變更時的自動重啟：

bash
potato start config.yaml --reload

除錯模式

啟用詳細日誌記錄：

bash
potato start config.yaml --debug

詳細輸出

檢視所有伺服器活動：

bash
potato start config.yaml --verbose

目錄結構

推薦的項目佈局：

text
my-annotation-project/
├── config.yaml           # Main configuration
├── data/
│   ├── train.json        # Training data
│   └── main.json         # Annotation data
├── annotations/          # Output directory
├── templates/            # Custom HTML templates
└── static/               # Custom CSS/JS

測試你的配置

驗證配置

檢查語法錯誤：

bash
potato validate config.yaml

預覽模式

啟動但不儲存標註：

bash
potato start config.yaml --preview

使用測試資料

生成測試資料：

bash
potato generate-data --count 10 --output test_data.json

常見問題

埠已被佔用

bash
# Use a different port
potato start config.yaml --port 8080
 
# Or in config.yaml
server:
  port: 8080

資料檔案未找到

確保路徑相對於配置檔案位置：

yaml
# If data is in subdirectory
data_files:
  - path: data/main.json
 
# Or use absolute path
data_files:
  - path: /full/path/to/data.json

許可權被拒絕

檢查檔案許可權：

bash
chmod 755 annotations/
chmod 644 data/*.json

本地多使用者

用於測試多使用者場景：

yaml
allow_all_users: true
url_user_id_param: user_id

使用不同使用者訪問：

  • http://localhost:8000/?user_id=annotator1
  • http://localhost:8000/?user_id=annotator2

重置標註

清除所有標註並重新開始：

bash
# Remove annotation files
rm -rf annotations/*
 
# Restart server
potato start config.yaml

環境變數

通過環境配置：

bash
export POTATO_PORT=8000
export POTATO_DEBUG=true
export POTATO_DATA_PATH=/path/to/data
 
potato start config.yaml

使用虛擬環境

venv

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

Conda

bash
conda create -n potato python=3.10
conda activate potato
pip install potato-annotation

IDE 整合

VS Code

安裝 YAML 擴充套件以支援配置檔案：

json
// settings.json
{
  "yaml.schemas": {
    "https://potato-annotation.com/schema.json": "config.yaml"
  }
}

PyCharm

設定執行配置：

  1. 新增 → Python
  2. 指令碼：potato
  3. 參數：start config.yaml
  4. 工作目錄：你的項目路徑

下一步