Potato の研究をオンラインに公開する

IT 部門に依頼する、用意されたデプロイボタンをクリックする、ノートPCから共有する、サーバーを借りるのいずれかで、Potato のタスクをアノテーターに届けます。

Potato の研究をオンラインに公開するには、アノテーターが Web アドレスでアクセスできるコンピューターでタスクを実行し、研究の間はアノテーションを安全に保管し、終了時にアノテーションをダウンロードします。所属機関の IT チームに依頼する方法と、同僚が用意したデプロイボタンをクリックする方法は、自分側でターミナルが不要な2つの方法です。

研究をデプロイするとは、自分のコンピューターで作った Potato のタスクを、サーバーに移すことです。サーバーとは、電源を入れたままインターネットに接続されているコンピューターのことです。アノテーターはどこからでも Web ブラウザーでタスクを開き、Potato は作業のたびに各回答をサーバーに保存します。Study Designer のプレビューは、自分のブラウザーの中で Potato を動かしているだけなので、他の人がそのコピーにアクセスすることはできません。Designer で作った研究も、以下のいずれかの方法が必要です。

どの方法も、同じプロジェクトフォルダーから始まります。Study Designer の Download project (.zip) ボタンは、config.yaml（タスクを記述するファイル）、サンプルデータファイル、README を保存します。サンプルファイルには3つの仮の項目が入っています。デプロイする前に、サンプルファイルを自分の項目に置き換えてください。形式はデータ形式で説明しています。

公開方法の選び方

方法ごとに、技術的な作業をする人、サーバーの費用、研究を公開しておける期間が異なります。以下の費用は2026-11-04時点のホストの料金表と Potato 自身の見積もりによるもので、待ち時間は測定値ではなく目安です。

方法	向いている場面	費用	ターミナル	待ち時間の目安
IT または研究計算チームに依頼する	機微なデータ、機関のサインイン、数か月続く研究	所属機関が決める	自分では不要	数日から数週間
同僚が用意したデプロイボタンをクリックする	git を使う人が1人いるラボ	Render は無料、Heroku は月 $7	自分では不要	当日
自分のコンピューターからリンクを共有する	午後だけのパイロットやラボのミーティング	無料	必要（数個のコマンド）	1〜2時間
コマンド1つでサーバーを借りる	数週間続く、自分で運用する研究	月額約 €6〜$12、Jetstream2 では無料	必要（加えてクラウドのアカウント）	半日

迷ったら、まず IT チームに相談してください。所属機関内のサーバーなら、データは機関がすでに管理している機器に置かれ、セキュリティ更新とバックアップは IT チームに任せられます。

IT または研究計算チームに依頼する

多くの大学や病院には、研究のために Web アプリケーションをホストする研究計算サービスがあります。そのようなチームにとって、Potato は普通の Web アプリケーションです。チームは、Potato に必要なものを1ページにまとめた概要から始められます。

Study Designer からプロジェクトをダウンロードし、サンプルデータファイルを自分の項目に置き換えます。
プロジェクトフォルダーと、IT チーム向け Potato サーバー要件へのリンクを IT チームに送ります。
アノテーターが誰か、何人参加するか、研究がどのくらいの期間続くかをチームに伝えます。
アノテーターがどのようにサインインするかを伝えます。機関のアカウントを持つ同僚はシングルサインオン（所属機関がすでに運用しているログイン）を使え、外部のアノテーターは、自分が一覧にしたユーザー名を使えます。
項目や回答に個人情報や機微な情報が含まれるかどうかを伝え、研究が従う倫理審査の承認を伝えます。
研究の Web アドレス、Potato の管理ダッシュボードを開く管理者キー、そして研究の終了時にバックアップを取りデータを渡す計画を、チームに依頼します。

アドレスが届いたら、誰かにアドレスを送る前に、アノテーターを招待する前にを最後まで確認してください。

同僚が用意したデプロイボタンをクリックする

デプロイボタンとは、コードリポジトリのページにあるリンクで、ブラウザー上のフォームだけで、Potato のタスクのコピーをホスティング会社のサーバーに設定します。git とターミナルを使う同僚が、プロジェクトフォルダーが入ったリポジトリから、potato deploy button コマンドでボタンを一度だけ作ります。その同僚に送るページは Potato をローカルまたはクラウドで実行するです。

このボタンは3つのホストで使え、料金はそれぞれ異なります。

Render は、支払い方法なしの無料プランで研究を実行します。無料の Render サービスは、訪問者がいない状態が15分続くとスリープし、次のアノテーターが来たときに復帰するまで約1分かかります。
Heroku では、ボタンが作成するサーバーに月 $7 かかります。Heroku では、アプリを作成する前に、通常はクレジットカードによる確認済みのアカウントが必要です。
AWS は、月 $12 で Lightsail サーバーを動かします。AWS のボタンは公開リポジトリからタスクを読み取るため、公開しても差し支えない項目にだけ向いています。

Render と Heroku は、サーバーが再起動するたびにサーバーのディスクを消去します。そのためボタンは、5分ごとにアノテーションを、データやモデルを共有するサイトである Hugging Face の非公開データセットにコピーし、サーバーが起動するたびにアノテーションを書き戻します。そのデータセットはクリックするときに名前をつけ、あなたのアカウントのものになります。

クリックする前に、次の3つを用意してください。

ホスト（Render または Heroku）のアカウント。
書き込み権限を持つアクセストークンを作った無料の Hugging Face アカウント。トークンは huggingface.co/settings/tokens で作ります。
リポジトリが非公開の場合は、そのリポジトリへのアクセス権。非公開リポジトリの場合、Heroku は GitHub アカウントのリンクを求めます。

次の手順でデプロイします。

リポジトリの README にあるボタンをクリックし、ホストにサインインします。
アプリに名前をつけます。この名前は研究の Web アドレスの一部になります。
POTATO_BACKUP_HF_REPO に、Hugging Face のユーザー名と研究の名前でできたデータセット名（your-username/my-study-annotations など）を入力します。名前が新しい場合、Potato はデータセットを作成し、非公開にします。
Hugging Face のトークンを HF_TOKEN に貼り付けます。その他の欄は、ボタンが入力した値のままにします。
デプロイを開始し、ホストがアプリの実行中と報告するまで待ちます。ホストが表示する Web アドレスを開きます。
管理者キーを見つけます。これは、デプロイ中にホストが生成したパスワードです。Heroku ではアプリの Settings タブの POTATO_ADMIN_API_KEY の項目にあり、Render ではサービスの Environment ページの同じ項目にあります。
研究のアドレスの末尾に /admin を付けて開き、管理者キーを貼り付けて管理ダッシュボードを開きます。

タスク、項目、アノテーターの一覧は、リポジトリで固定されます。後からの変更はボタンを作った同僚を通すことになるため、クリックする前にタスクを完成させてください。項目を公開してよい場合を除き、リポジトリは非公開にしておいてください。

自分のコンピューターからリンクを共有する

自分のコンピューターで、午後だけのパイロットを配信できます。アノテーターは一時的な Web リンクを開き、アノテーションはプロジェクトフォルダーに保存され、コマンドを閉じるとリンクは使えなくなります。この方法にはターミナルが必要です。ターミナルとは、コマンドを入力するためのプログラムで、Mac では Terminal（「アプリケーション」の「ユーティリティ」にあります）、Windows では PowerShell（スタートメニューで「PowerShell」を検索します）です。

python.org/downloads から Python 3.9 以降をインストールします。Windows でのダウンロードは Python install manager で、Mac でのダウンロードは macOS インストーラーです。
ターミナルを開いて、Potato をインストールします。Mac では次のように入力します。
bash
```
python3 -m pip install potato-annotation
```
Windows では次のように入力します。
powershell
```
py -m pip install potato-annotation
```
Study Designer からダウンロードしたプロジェクトを展開します。Mac では .zip ファイルをダブルクリックします。Windows ではファイルを右クリックして すべて展開 を選びます。サンプルデータファイルを自分の項目に置き換えます。
ターミナルでプロジェクトフォルダーに移動し、Potato を起動します。以下のフォルダー名は例なので、自分のフォルダーの名前を使ってください。Mac では次のようにします。
bash
```
cd ~/Downloads/my-task
python3 -m potato start config.yaml
```
Windows では次のようにします。
powershell
```
cd $HOME\Downloads\my-task
py -m potato start config.yaml
```
ブラウザーで http://localhost:8000 を開きます。このアドレスにアクセスできるのは、自分のコンピューターだけです。Potato を停止するには、ターミナルで Ctrl-C を押します。
他の人が入れるようにするには、cloudflared をインストールします。これは Cloudflare の無料プログラムで、アカウントは不要です。Homebrew を使っている Mac では、brew install cloudflared を実行します。Windows では、Cloudflare のダウンロードページから Windows 用のインストーラーをダウンロードします。
potato start の代わりに potato share を実行します。
bash
```
python3 -m potato share config.yaml
```
Windows では py -m potato share config.yaml と入力します。Potato は、サインインできる人を表示し、何かを公開する前に確認を求めます。y と入力すると、Potato はアノテーターに送るための https:// のリンクを表示します。

このリンクは、コマンドが動いている間だけ使えます。ターミナルを閉じる、コンピューターをスリープさせる、ネットワークを変えるのいずれかでリンクは終了し、再び実行すると新しいリンクが表示されます。大学のネットワークによっては、cloudflared が作る trycloudflare.com のリンクをブロックします。アノテーターからリンクがブロックされたと報告があった場合は、potato share config.yaml --backend tailscale で代わりに Tailscale を使えます。Tailscale には無料のアカウントが必要です。potato share が No tunnel backend found と報告した場合、Potato はコンピューター上で cloudflared を見つけられておらず、メッセージにインストールのコマンドが一覧されています。

仮想環境とオプション機能についてはインストールで、potato share の詳細については Potato をローカルまたはクラウドで実行するで説明しています。

コマンド1つでサーバーを借りる

potato deploy up は、クラウド会社からサーバーを借り、HTTPS 証明書（ブラウザーのアドレスバーの鍵マーク）を取得し、プロジェクトフォルダーをアップロードし、研究を起動して、Web アドレスを表示します。このコマンドには、上の手順1〜3のターミナルの準備と、クラウド会社のアカウント、そして API トークンが必要です。API トークンとは、プログラムが自分のアカウントとして操作できるようにする、パスワードのようなキーです。アカウントとトークンについては、各ホストのガイドが最初から説明しています。

ホスト	月額費用	ガイド
AWS Lightsail	$12	AWS Lightsail
Hetzner、Vultr、Linode	約 €6〜$12	Hetzner、Vultr、Linode
Jetstream2（米国の研究者向け）	ACCESS の割り当てがあれば無料	Jetstream2
Hugging Face Space	Hugging Face PRO プラン、$9	Hugging Face Spaces

どのホストでも同じ2つのコマンドを使い、各ホストのガイドにプロバイダー名とそのホストのインストールコマンドが載っています。1つ目のコマンドはプランと月額費用を表示するだけで何も作成せず、2つ目のコマンドは、確認の後にサーバーを作成します。

bash

potato deploy up config.yaml --provider aws --dry-run
potato deploy up config.yaml --provider aws

Hugging Face 自身の Duplicate this Space ボタンは、ブラウザー上で Space をコピーします。ただし、Potato の Space のコピーは元の所有者のバックアップ設定を引き継ぎ、元のシークレットは失われます。Potato の Space は、代わりに potato deploy up --provider huggingface でデプロイしてください。

アノテーターを招待する前に

どの方法を取った場合でも、研究に Web アドレスができたら、次の一覧を一度確認してください。

誰がサインインできるかを決める。 限定する設定のうち最も簡単なのは、ユーザー名の一覧です。Study Designer で Allow All Users をオフにし、Authorized Users の下に各アノテーターを追加します。一覧にあるアノテーターは、最初の訪問時の登録でパスワードを選び、Potato は一覧にない人を拒否します。一覧にあるユーザー名を最初に登録した人がそのアカウントを所有するため、ユーザー名は各アノテーターに直接送ってください。機関のアカウントについては SSOとOAuth認証を、クラウドワーカーについてはクラウドソーシング統合を参照してください。Allow All Users をオンにすると、アドレスを見つけた人は誰でもアカウントを作成できます。この設定は、公開デモにだけ使ってください。
アノテーションの保存場所を知っておく。 Potato は、アノテーターが作業するたびに、そのアノテーターの回答を、アノテーターごとに1つあるフォルダー内の user_state.json というファイルに保存します。フォルダーは、設定が指定する出力フォルダーの中にあり、Study Designer ではこのフォルダーを output と呼びます。自分のコンピューターでは、このフォルダーはプロジェクトフォルダーの中にあります。ボタンでデプロイした場合は、再起動後も残るコピーを Hugging Face データセットが保持します。借りたサーバーでは、potato deploy pull がこのフォルダーをダウンロードします。機関のサーバーでは、サーバーがどのようにバックアップされるかを IT に尋ねてください。
2つ目のブラウザーでテストする。 プライベートウィンドウ（Chrome ではシークレットウィンドウ、Safari と Firefox ではプライベートウィンドウ、Edge では InPrivate）で、研究のアドレスを開きます。pilot-test のようなユーザー名を一覧に追加し、その名前で登録して、3つの項目に回答します。ウィンドウを閉じ、もう一度サインインして、回答が残っていることを確認します。次に管理ダッシュボードを開き、テスト用のアノテーターが表示されていることを確認します。アノテーターがスマートフォンで作業する可能性があるなら、スマートフォンでもアドレスを試してください。
管理者キーを非公開にする。 管理者キーで、/admin の管理ダッシュボードが開きます。ダッシュボードには、すべてのアノテーターの回答が表示されます。自分のコンピューターでは、最初に /admin を開いたときに、Potato がキーをプロジェクトフォルダーの admin_api_key.txt に保存します。
招待状を書く。 各アノテーターに、アドレス、ユーザー名、タスクにかかる時間、問題が起きたときの連絡先を送ります。

結果を受け取る

管理ダッシュボードを使えば、ターミナルなしで結果を自分のコンピューターにダウンロードできます。/admin を開き、管理者キーを入力して、Publish Dataset を選びます。Target で Local archive を選び、Data format を、スプレッドシート用の CSV にして、Publish をクリックします。アーカイブの準備ができたら、Download archive をクリックします。

アーカイブには、各アノテーターの回答、項目、多数決で統合したラベルが入っています。アーカイブの README には、ラベル数とアノテーター間の一致度が報告されています。Anonymize annotators のチェックを外さない限り、アノテーターの名前は A1、A2 のように置き換えられます。アンケートの回答には個人情報が含まれることがあるため、Include survey / phase responses にチェックを入れない限り、アーカイブには含まれません。

ターミナルからは、python -m potato.export が、Potato のエクスポート形式のいずれかで、同じアノテーションをフォルダーに書き出します。

bash

python -m potato.export --config config.yaml --format csv --output results

potato deploy up で作ったサーバーでは、potato deploy pull config.yaml が、データベースを含め、サーバーが集めたものをすべてダウンロードします。

研究を終了してサーバーの課金を止める

何かを削除する前に結果をダウンロードし、最後のアノテーターの回答が入っていることをダウンロードしたものを開いて確認してください。そのうえで、方法に応じてサーバーを停止します。

自分のコンピューター。 ターミナルで Ctrl-C を押します。課金はありません。
IT チーム。 研究が終了したことをチームに伝え、出力フォルダーのコピーを依頼し、サーバー上のコピーがどのくらいの期間保持されるかを尋ねます。
デプロイボタン。 Heroku ではアプリの Settings タブからアプリを削除し、Render ではサービスの Settings ページからサービスを削除します。Hugging Face データセットには、アノテーションの完全なコピーがあります。バックアップが不要になったら、データセットの設定ページからデータセットを削除します。
借りたサーバー。 potato deploy pull config.yaml を実行し、取得したフォルダーを確認してから、potato deploy destroy config.yaml を実行します。データを一度も取得していないサーバーは、Potato が破棄を拒否します。

よくある質問

研究用の Potato サーバーはどうやって作りますか？

自分のタスクを、アノテーターが Web アドレスでアクセスできるコンピューターで実行すれば、Potato サーバーになります。所属機関の IT チームにタスクの実行を任せることも、同僚がデプロイボタンを用意してそれをクリックすることも、potato share でノートPCからパイロットを配信することも、potato deploy up でサーバーを借りることもできます。方法の選び方の表は、費用と、各方法に必要なターミナル作業で、これらを比較しています。

Potato を自分の PC にインストールするには？

python.org から Python 3.9 以降をインストールし、Windows では PowerShell で py -m pip install potato-annotation を、Mac では Terminal で python3 -m pip install potato-annotation を入力します。インストール後は、Windows では py -m potato start config.yaml、Mac では python3 -m potato start config.yaml でタスクが起動します。オプション機能についてはインストールで説明しています。

このページで使う言葉

サーバー。 サーバーとは、電源を入れたままインターネットに接続されているコンピューターで、他の人が Web ブラウザーを通して、そのコンピューター上のプログラムを使えるようにします。
URL（Web アドレス）。 URL は、アノテーターが入力またはクリックするアドレスで、https://my-study.example.edu のようなものです。ドメインは、アドレスの名前の部分で、ここでは my-study.example.edu です。
HTTPS。 HTTPS は、アノテーターのブラウザーとサーバーの間のすべてを暗号化します。パスワードと回答も含まれます。ブラウザーは、HTTPS のアドレスに鍵マークを表示します。
ポート。 ポートとは、コンピューター上の番号付きの入口です。設定が別のポートを指定しない限り、Potato はポート 8000 で待ち受け、ローカルアドレス http://localhost:8000 はその番号で終わります。
ターミナル。 ターミナルとは、コマンドを入力するためのプログラムで、Mac では Terminal、Windows では PowerShell と呼ばれます。
管理者キー。 管理者キーは、Potato の管理ダッシュボードを開く長いパスワードです。
API トークン。 API トークンとは、Potato のデプロイコマンドなどのプログラムが、ホスティング会社の自分のアカウントとして操作できるようにする、パスワードのようなキーです。