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]"

シェルが角括弧をglobとして解釈しないよう、extraは引用符で囲んでください。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はその外側にあるファイルを読み込みません。.に設定すると、設定ファイル、データファイル、出力ディレクトリが1つのフォルダにまとまるので、後でプロジェクトをそのままサーバーに移せます。

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

スクリーンショットにはヘッドレスブラウザ用のextra、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から直接ユーザー名を読み取り、パスワードを求めません。そのため、2つのブラウザプロファイルを開けば、アカウントを登録せずに2人としてアノテーションできます。

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

アノテーションのリセット

Potatoはoutput_annotation_dirの下にアノテーターごとのディレクトリを1つずつ作成し、それぞれにその人の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:行でこのスキーマがすでに指定されているため、この設定がなくてもエディタで検証されます。

PyCharm

実行構成をセットアップします。

  1. 追加 → Python
  2. スクリプト：potato
  3. パラメータ：start config.yaml
  4. 作業ディレクトリ：プロジェクトのパス

次のステップ