Skip to content

在 Hugging Face Space 上部署 Potato

用 potato deploy 在 Hugging Face Docker Space 中執行 Potato 標註任務，標註每五分鐘備份到一個私有資料集。

potato deploy up --provider huggingface 在 Hugging Face Docker Space 中執行一個標註任務，使用 hf.space 地址上的 HTTPS，不需要在伺服器上做任何配置。它適合任務的公開演示，也適合資料和模型已經放在 Hugging Face Hub 上的實驗室。Space 的磁碟每次重啟都會被清空，所以 Potato 把標註儲存在一個與 Space 一同建立的私有 Hugging Face 資料集中。它每五分鐘把標註備份到這個資料集，並在 Space 啟動時恢復。本頁需要 Potato 2.10 或更高版本，以及一份你已經用 potato start 執行過的配置。

Space 的要求和限制

Potato 的 Space 是 Docker Space，建立 Docker Space 需要 Hugging Face 的付費方案：個人賬號需要 PRO，組織需要 Team 或 Enterprise。處於 Hugging Face 免費層級的賬號或組織最多同時執行三個 Space。第四個會停在 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 secret 傳給 Space，讓備份能夠寫入資料集，但從不把它提交到 Space 的倉庫中。

決定誰可以登入

potato deploy 不會改動你的登入設定，而公開的 Space 任何人拿到地址都能開啟。如果配置允許任何人註冊，下面的試執行會報告警告 D003，“Anyone who finds the URL can register and annotate.”（任何找到這個 URL 的人都能註冊並標註。）開放註冊通常適合演示。對於實名標註者，請把他們列在 user_config.users 下並設定 allow_all_users: false（密碼管理），或者讓他們用自己的 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 secret，並連同 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 狀態，是因為免費層級的賬號已經在執行三個 Space。先暫停另一個，再從這個 Space 的設定頁面重啟它。重啟一個已有的 Space 不需要付費方案。

重新構建後標註丟失，是因為 Space 無法從資料集恢復。恢復成功時 Space 日誌中會出現一行 RESTORED，沒有這一行通常說明 HF_TOKEN 這個 Space secret 缺失或沒有寫入許可權。

BUILD_ERROR 的原因寫在構建日誌中，地址是 https://huggingface.co/spaces/<account>/<name>?logs=build。

延伸閱讀