Skip to content

Hugging Face SpaceへのPotatoのデプロイ

potato deployを使ってHugging FaceのDocker SpaceでPotatoのアノテーションタスクを実行し、アノテーションを5分ごとに非公開のデータセットへバックアップします。

potato deploy up --provider huggingfaceは、アノテーションタスクをHugging FaceのDocker Spaceで実行します。hf.spaceのアドレスでHTTPSが使え、サーバー側で設定することは何もありません。タスクの公開デモや、データとモデルをすでにHugging Face Hubに置いている研究室に向いています。Spaceのディスクは再起動のたびに消去されるため、PotatoはSpaceと一緒に作成する非公開のHugging Faceデータセットにアノテーションを保持します。アノテーションを5分ごとにデータセットへバックアップし、Spaceの起動時に復元します。このページの手順にはPotato 2.10以降と、すでにpotato startで実行したことのある設定が必要です。

Spaceの要件と制限

PotatoのSpaceはDocker Spaceで、Docker Spaceを作成するにはHugging Faceの有料プランが必要です。個人アカウントならPRO、組織ならTeamかEnterpriseです。また、Hugging Faceの無料枠のアカウントや組織が同時に実行できるSpaceは3つまでです。4つ目はPAUSEDのままになり、スリープ中のSpaceと違って、一時停止したSpaceは訪問者が開いても起動しません。

名前の決まったアノテーターと数週間続ける研究なら、AWS Lightsail、Jetstream2、Hetznerなどの仮想マシンは再起動してもディスクが残るので、データがバックアップに依存しません。Spaceが最も合うのは、届けたい相手がすでにHugging Faceのアカウントを持っている場合や、失っても困らないアノテーションを集めるデモのタスクの場合です。

Hugging Faceのトークンを設定する

PotatoはHugging Faceのトークンを使ってSpaceとデータセットを作成します。Hugging Faceの設定で書き込み権限のあるトークンを作成し、Hugging Faceのextraをインストールして、トークンを環境に設定します。

bash
pip install 'potato-annotation[huggingface]'
export HF_TOKEN=hf_...
potato deploy providers --verify

providers --verifyは、トークンがどのアカウントのものかを表示します。Potatoはバックアップがデータセットに書き込めるよう、トークンをSpaceのシークレットとしてSpaceに渡し、Spaceのリポジトリにコミットすることはありません。

サインインできる人を決める

potato deployはサインインの設定を変更せず、公開Spaceはアドレスを知っている人なら誰でも開けます。設定で誰でも登録できるようになっていれば、下のドライランが警告D003「Anyone who finds the URL can register and annotate.」（URLを見つけた人は誰でも登録してアノテーションできます）を表示します。デモには通常は公開登録が合います。名前の決まったアノテーターの場合は、allow_all_users: falseを設定してuser_config.usersの下に一覧を書くか（パスワード管理）、Hugging Faceのアカウントでサインインしてもらうようにしてください。Hugging Faceは、Potatoがauthentication.providersの下で組み込みプロバイダーとしてサポートしています（SSOとOAuth認証）。

計画を確認してデプロイする

ドライランは何も作成せず、デプロイで作成されるものを表示します。

bash
potato deploy up myproject/config.yaml --provider huggingface --dry-run

計画では、まず非公開のデータセット<account>/<name>-annotationsを作成し、次にDocker Space <account>/<name>を作成して、セッションキー、管理者キー、トークンをSpaceのシークレットとして設定し、プロジェクトをDockerfileとREADMEと一緒にアップロードします。Dockerfileはインストール済みのバージョンの公開Potatoイメージをもとにビルドするので、Spaceに置かれるのはプロジェクトのファイルだけです。--ownerは組織の下にデプロイし、--privateはSpace自体を非公開にし、--nameはタスクから取った名前を上書きします。

コマンドを--dry-runなしで実行し、計画を確認します。

bash
potato deploy up myproject/config.yaml --provider huggingface

デプロイはSpaceが動き出すまで待ち、そのアドレスhttps://<account>-<name>.hf.spaceと、設定の隣にある管理者キーファイル.potato/secrets.jsonのパスを表示します。管理者キーで/adminの管理者ダッシュボードを開けます。無料のハードウェアで動くSpaceは訪問者がないまま48時間たつとスリープし、誰かが開くと起動します。そのたびに、アノテーションはデータセットから戻ってきます。

研究を終える

potato deploy pullは、Space自体を読むのではなく、Spaceが保存したものをすべて保持しているバックアップのデータセットをダウンロードします。

bash
potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yaml

destroyはSpaceを削除し、データセットは残します。Spaceの削除はもう一度デプロイすれば元に戻せますが、アノテーションの削除は元に戻せないためです。データセットが不要になったら、Hub上のその設定ページから削除してください。

バックアップなしでデプロイする

--demoは、アノテーションが重要でないデモ向けに、データセットなしでSpaceをデプロイします。その場合、ドライランは集めたものが次の再起動で失われると警告します。データセットがない場合、pullは管理者用エクスポートを通じて動作中のSpaceを読むため、Spaceが動いている間しか使えません。

トラブルシューティング

作成時の支払いエラーは、アカウントや組織に有料プランがないことを意味します。Docker Spaceには、個人アカウントならPRO、組織ならTeamかEnterpriseが必要です。

SpaceがPAUSEDになるのは、無料枠のアカウントがすでに3つのSpaceを実行している場合です。別のSpaceを一時停止してから、このSpaceをその設定ページから再起動してください。既存のSpaceの再起動には有料プランは必要ありません。

再ビルド後にアノテーションがないのは、Spaceがデータセットから復元できなかった場合です。復元に成功するとSpaceのログにRESTOREDの行が出ます。この行がない場合、たいていはHF_TOKENのSpaceシークレットがないか、書き込み権限がありません。

**BUILD_ERROR**の原因は、https://huggingface.co/spaces/<account>/<name>?logs=buildのビルドログで確認できます。

関連