Skip to content

本地開發

在本地安裝並執行 Potato，用於開發和測試。內容涵蓋 pip 安裝、配置檔案、啟動伺服器，以及排查常見的啟動問題。

讓 Potato 在你自己的機器上跑起來，用於開發和測試。

前置條件

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

安裝

使用 pip（推薦）

bash
pip install potato-annotation

從原始碼安裝

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

帶可選依賴安裝

bash
# Local speech-to-text and diarization for transcript projects
pip install "potato-annotation[transcribe]"
 
# Hosted model providers for AI support and active learning
pip install "potato-annotation[ai]"
 
# Everything except the multi-gigabyte server-side vision stack
pip install "potato-annotation[all]"

給額外依賴名加引號，這樣 shell 不會把方括號當成萬用字元。all 特意不包含 vision，因為那一組會裝上 torch，而預設體驗裡沒有任何功能用得到它。

快速開始

1. 建立配置檔案

建立 config.yaml：

yaml
annotation_task_name: "My First Annotation Task"
task_dir: "."
port: 8000
 
data_files:
  - data.json
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels:
      - Positive
      - Negative
      - Neutral
 
output_annotation_dir: "annotations/"

task_dir 是其他所有相對路徑的解析根目錄，Potato 不會讀取它之外的內容。把它設成 .，配置檔案、資料檔案和輸出目錄就都在同一個資料夾裡，項目之後才能整體搬到伺服器上。

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

開發模式

除錯模式

除錯模式會開啟詳細日誌，關掉會話空閒超時，並讓來自你自己機器的請求不用金鑰就能開啟管理頁面。登入頁面仍然保留，--debug-phase（見下文）會跳過它：

bash
potato start config.yaml --debug

已經部署的伺服器上絕不能開啟除錯模式。同一臺機器上不新增轉發請求頭的隧道或反向代理會讓每個呼叫方看起來都來自本機，而 --debug-phase 會讓每個訪問者都以同一個 debug_user 身份登入。Potato 2.8.2 到 2.11.0 在預設的 0.0.0.0 地址上拒絕以除錯模式啟動，所以在這些版本上要加上 --host 127.0.0.1。

除錯日誌

選擇由應用的哪一側輸出日誌：

bash
potato start config.yaml --debug-log server

可取的值是 all、ui、server 和 none。標註頁面表現異常時用 ui，某個條目載入不出來時用 server。

詳細輸出

檢視伺服器的全部活動：

bash
potato start config.yaml --verbose

直接跳到某個階段

開啟 --debug 後，可以跳過登入，直接跳到你正在調整的階段，不必每次重啟都點過知情同意和說明頁：

bash
potato start config.yaml --debug --debug-phase annotation

目錄結構

推薦的項目佈局：

text
my-annotation-project/
├── config.yaml           # Main configuration, inside task_dir
├── data/
│   ├── training.json     # Practice items for the training phase
│   └── main.json         # Annotation data
├── annotations/          # output_annotation_dir
├── media/                # media_directory, served at /media/
└── templates/            # site_dir, if you override the default templates

必需的只有 config.yaml 和資料檔案。Potato 自帶模板，所以只有在要替換模板時才需要設定 site_dir 並加一個 templates/ 資料夾，再用 site_file 指向渲染標註頁面所用的那個檔案。

測試配置

校驗配置

用伺服器啟動時所用的同一套檢查來查配置，省得為此白啟動一次：

bash
potato validate config.yaml

加上 --strict，警告（比如出現無法識別的鍵）就會讓這次執行失敗，而不是打印出來後照樣通過。

預覽模式

檢視一份配置聲明瞭什麼，並在瀏覽器裡渲染出來，不用啟動完整伺服器：

bash
potato preview config.yaml

截圖需要無頭瀏覽器那組額外依賴，pip install "potato-annotation[preview]"：

bash
potato preview config.yaml --screenshot preview.png

常見問題

埠已被佔用

bash
# Use a different port
potato start config.yaml -p 8080

也可以寫在 config.yaml 裡，-p 參數會覆蓋它：

yaml
port: 8080

找不到資料檔案

確認路徑是相對於配置檔案所在位置的：

yaml
# If data is in a subdirectory
data_files:
  - data/main.json

路徑相對 task_dir 解析，Potato 不會載入它之外的檔案，所以要把資料挪到任務目錄下，而不是指向機器上別處的絕對路徑。

許可權被拒絕

檢查檔案許可權：

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

在本地模擬多個使用者

用於測試多使用者場景：

yaml
user_config:
  allow_all_users: true
 
login:
  type: url_direct
  url_argument: user_id

url_direct 直接從 URL 裡讀使用者名稱，不要求密碼，於是你可以開兩個瀏覽器配置，不註冊賬號就以兩個人的身份標註：

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

重置標註

Potato 在 output_annotation_dir 下給每個標註者寫一個目錄，裡面放著這個人的 user_state.json：

bash
# Remove one annotator's work
rm -rf annotations/annotator1
 
# Or clear every annotator
rm -rf annotations/*
 
# Restart server
potato start config.yaml

刪掉某個使用者的目錄，會連同答案一起刪掉分配給他的任務，所以重新執行時條目會從頭分配。

環境變數

通過環境變數配置：

bash
# Keeps sessions valid across restarts; required for OAuth
export POTATO_SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
 
# Fixes the shared admin key instead of letting Potato generate one per task
export POTATO_ADMIN_API_KEY="your-admin-key"
 
potato start config.yaml

沒有 POTATO_SECRET_KEY，Potato 每次啟動都會生成一個隨機簽名金鑰，每次重啟都會把所有人登出。

配合虛擬環境使用

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://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json": "config.yaml"
  }
}

從研究設計器下載的配置已經在 # yaml-language-server: 那一行帶上了這個 schema，不做這項設定也能在編輯器裡校驗。

PyCharm

建立一個執行配置：

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

下一步