アノテーションサーバーのデプロイ

研究の期間、費用を払う人、手元にあるサーバーをもとにアノテーション研究のホストを選び、potato deployでHTTPS、バックアップ、データの取得を行います。

実際の研究に使うアノテーションサーバーには、公開のHTTPSアドレス、自分のアノテーターだけを受け入れるサインイン、再起動しても残るストレージ、そして研究の終了時にアノテーションを取り戻す手段が必要です。Potatoでは、potato deploy upがパイロットで使った設定からホストと証明書を作成し、ディスクが消去されるホストではバックアップを設定し、リンクを知っている人が誰でもサインインできる状態ならデプロイの前に警告します。

ここでいうアノテーションサーバーとは、アノテーターがブラウザで開くウェブアプリケーションのことです。研究が続く数週間アノテーターがアクセスできるように、ノートPC以外の場所で動かします。パイロットを終えたタスクをそこに移すと、アドレス、サインイン、データの保存場所、そしてマシンの面倒を見る人が変わります。

研究用サーバーに必要な4つの条件

以下の条件は、それぞれアノテーターかデータのどちらかを守るためのものです。

公開のHTTPSアドレス。 アノテーターはタスクにパスワードとラベルを入力するため、接続はHTTPSで暗号化する必要があります。Let's Encryptの証明書は無料で、取得するにはサーバーに公開アドレスが必要です。
自分のアノテーターだけを受け入れるサインイン。 公開アドレスは他人にも見つけられます。公開登録を有効にしたタスクは、見つけた人を誰でも受け入れます。名前付きアカウントの名簿（パスワード管理）、Google、GitHub、所属機関によるサインイン（SSOとOAuth認証）、クラウドソーシングの研究ならプラットフォームがワーカーに渡すリンク（クラウドソーシング統合）を使ってください。
再起動しても残るストレージ。 ホストによっては、サーバーが再起動するたびにディスクが消去されます。そうしたホストで研究を行うには自動で復元されるバックアップが必要で、それがないと、戻ってきたアノテーターが目にするのは空のタスクです。
データを取り戻す手段。 Potatoは各アノテーターの作業をファイルに保存し、プロジェクトのデータをSQLiteデータベースに保持します。サーバーの実行中にSQLiteファイルをコピーすると直近の作業が抜け落ちることがあるため、取得にはSQLite自身のバックアップコマンドを使う必要があります。

よくある研究の状況に合うホスト

適したホストは、研究の期間、費用を払う人、所属機関がすでにサーバーを運用しているかどうかで決まります。次の表は、よくある状況ごとに合うホストを、各デプロイ先のデフォルトのサイズについてPotatoが表示する月額費用とともに示したものです。

状況	ホスト	月額費用	ガイド
AWSアカウントで行う研究	AWS Lightsail、2 GB	$12	AWS Lightsail
予算のない米国の機関での研究	Jetstream2	ACCESSの割り当てがあれば無料	Jetstream2
できるだけ安く行う研究	Hetzner Cloud、4 GB	約€6	Hetzner、Vultr、Linode
公開デモ、またはすでにHugging Faceを使っている研究室	Hugging FaceのDocker Space	PROプランまたはTeamプラン	Hugging Face Spaces
数人で半日だけ行うパイロット	`potato share`を使った自分のノートPC	無料	Potatoをローカルまたはクラウドで実行する
所属機関がすでに運用しているサーバー	リバースプロキシの背後に置いたDockerイメージ	Potato側の費用はなし	本番環境のセットアップ

最初の3つは再起動してもディスクが残る仮想マシンなので、数週間続く研究ではこれらが標準の選択肢です。Hugging Face Spaceは再起動のたびにディスクを失うため、Potatoはアノテーションを5分ごとに非公開のHugging Faceデータセットにバックアップし、Spaceの起動時に復元します。Potatoをローカルまたはクラウドで実行するには、Fly、Railway、Render、Herokuを含む13のクラウドデプロイ先がすべて載っています。

新しいホストでの`potato deploy`

potato deploy upは、パイロットで使った設定を受け取り、本来なら人が手作業で行う作業を代わりに行います。VMでは、マシンを作成し、ポート22、80、443だけを開き、DockerとCaddyウェブサーバーをインストールし、Let's Encryptの証明書を取得し、プロジェクトをアップロードし、Potatoをサービスとして起動します。まずホストに対応するpipのextra（そのホストへのデプロイに必要なオプションの依存関係）をインストールし、次にホストが読むのと同じ形で設定を確認します。

bash

pip install 'potato-annotation[deploy-aws]'
potato deploy check myproject/config.yaml --provider aws
potato deploy up myproject/config.yaml --provider aws --dry-run

potato deploy checkは設定のエラーを報告し、自分のマシンでしか解決できないパスを見つけ出します。--dry-runにはクラウドのアカウントが必要なく、デプロイで作成されるすべてのリソース、月額費用、サインインできる人を表示します。公開アドレスで公開登録が有効になっていれば、警告D003として知らせます。デプロイするには、同じコマンドを--dry-runなしで実行します。Potatoは計画をもう一度表示し、確認するまで何も作成せず、最後にアノテーターに送るURLを表示します。

デプロイが変更するのは、ホスティングに関わる設定だけです。デバッグモードをオフにし、再起動をまたいでセッションを維持し、ワーカープロセスを1つで実行します。Potatoはアイテムプールと割り当てキューをメモリに保持しているため、2つ目のプロセスがあると同じアイテムを二重に配ってしまうからです。user_config、authentication、require_passwordは書いたとおりに残します。デプロイ用の管理者キーを生成して設定の隣の.potato/secrets.jsonに保存し、このキーで/adminの管理者ダッシュボードを開けます。

所属機関がすでに運用しているサーバーでのPotato

所属機関がすでにサーバーを運用しているなら、新しいホストを作成する代わりに、公開されているDockerイメージをそのサーバーのリバースプロキシの背後で実行します。nginxなどのリバースプロキシが証明書を保持し、リクエストをPotatoに転送します。本番環境のセットアップに、Docker Composeファイル、nginxの設定、gunicornの設定があります。gunicornはワーカー1つのままにし、同時処理はスレッドを増やして確保してください。2つ目のワーカープロセスは同じアイテムを二重に配ってしまうためです。

Potatoのbackupブロックは、データのコピーをそのサーバーの外に保持します。アノテーションの出力とプロジェクトのデータベースのスナップショットを、デフォルトでは5分ごとにHugging FaceのデータセットまたはS3互換のバケットにコピーし、サーバーが空のディスクで起動したときに復元します。設定にこのブロックを追加し、hosting extraをインストールして、サーバーの環境にHF_TOKENを設定してください。

yaml

backup:
  schedule_minutes: 5
  restore_on_boot: true
  sinks:
    - type: huggingface
      repo_id: lab/pilot-annotations

データセットが存在しなければ、Potatoはそれを非公開リポジトリとして作成します。復元ではアノテーションと一緒にアカウント一覧も戻るため、アノテーターは同じパスワードでサインインできます。復元がディスク上にすでにあるアノテーションを上書きすることはありません。

ステータスの確認とデータの取得

potato deploy statusは、サーバーが動いているかどうかと、証明書が正常かどうかを報告します。ドメイン名のないVMでは証明書はIPアドレスに対して発行され、有効期間は約6日です。証明書は自動で更新されるので、研究を無人で運用する場合は数日おきにステータスを確認するか、サーバーを指すDNSレコードを用意して--domainを指定してください。potato deploy logs myproject/config.yaml -fはサーバーのログを追い続け、管理者ダッシュボードには、アノテーターが作業している間の進捗、スループット、アノテーター間一致度が表示されます。

研究が終わったら、ホストを削除する前にデータをpullします。