Skip to content

部署標註伺服器

根據研究持續多久、由誰付費、手頭有哪些伺服器為標註研究選擇主機，再用 potato deploy 完成 HTTPS、備份和資料取回。

用於正式研究的標註伺服器需要一個公開的 HTTPS 地址、只放你的標註者進來的登入方式、重啟後不會丟失的儲存，以及研究結束時取回標註的辦法。在 Potato 中，potato deploy up 會根據你試執行過的配置建立主機和證書，在會清空磁碟的主機上設定備份，並在任何拿到連結的人都能登入時，於部署之前發出警告。

這裡說的標註伺服器，是標註者在瀏覽器中開啟的 Web 應用。它執行在你的筆記型電腦以外的地方，這樣在研究持續的幾週裡標註者都能訪問。把試執行過的任務搬到這樣的伺服器上，會改變它的地址、登入方式、資料存放的位置，以及由誰來照看這臺機器。

研究伺服器的四項要求

下面每項要求保護的不是標註者，就是資料：

  • 公開的 HTTPS 地址。 標註者要在任務中輸入密碼和標籤，所以連線必須用 HTTPS 加密。Let's Encrypt 的證書免費，但伺服器需要一個公開地址才能獲取。
  • 只放你的標註者進來的登入方式。 公開地址是可以被找到的，開放註冊的任務會接受任何找到它的人。請使用實名賬號名單（密碼管理）、通過 Google、GitHub 或你所在機構登入（SSO 與 OAuth 認證），如果是眾包研究，則使用平臺發給工作者的連結（眾包整合）。
  • 重啟後不會丟失的儲存。 有些主機每次重啟伺服器都會清空磁碟。在這類主機上做研究，需要一份能自動恢復的備份，否則回來的標註者會看到一個空白的任務。
  • 取回資料的辦法。 Potato 把每位標註者的工作存放在檔案中，把項目資料儲存在 SQLite 資料庫裡。伺服器執行時直接複製 SQLite 檔案可能會漏掉最近的工作，所以取回資料時必須使用 SQLite 自帶的備份命令。

常見研究情形對應的主機

哪種主機合適，取決於研究持續多久、由誰付費，以及你所在機構是否已經在執行伺服器。下表把常見情形對應到主機，並列出 Potato 為每個目標的預設規格列印的每月費用：

情形主機每月費用指南
一項研究，已有 AWS 賬號AWS Lightsail，2 GB$12AWS Lightsail
美國機構的一項研究，沒有預算Jetstream2有 ACCESS 分配額度時免費Jetstream2
一項研究，價格最低Hetzner Cloud，4 GB約 €6Hetzner、Vultr 和 Linode
公開演示，或已經在用 Hugging Face 的實驗室Hugging Face Docker SpacePRO 或 Team 方案Hugging Face Spaces
和幾個人做一個下午的試點你的筆記型電腦，通過 potato share免費在本地或雲端執行 Potato
你所在機構已經在執行的伺服器放在反向代理後面的 Docker 映像Potato 本身不產生費用生產部署

前三種是磁碟在重啟後保留的虛擬機器，所以是持續數週的研究的預設選擇。Hugging Face Space 每次重啟都會丟失磁碟，因此 Potato 每五分鐘把標註備份到一個私有的 Hugging Face 資料集，並在 Space 啟動時恢復。在本地或雲端執行 Potato 列出了全部十三個雲端目標，包括 Fly、Railway、Render 和 Heroku。

在新主機上使用 potato deploy

potato deploy up 接過你試執行過的配置，完成原本需要人手動去做的事。在虛擬機器上，它會建立機器，只開放 22、80 和 443 埠，安裝 Docker 和 Caddy Web 伺服器，獲取 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。

部署只改動與託管有關的設定。它會關閉除錯模式，讓會話在重啟後保留，並且只執行一個 worker 程序，因為 Potato 把項目池和分配佇列放在記憶體裡，第二個程序會把同樣的項目分發兩次。user_config、authentication 和 require_password 則保持你寫的樣子。它會為這次部署生成一個管理員金鑰，存放在配置旁邊的 .potato/secrets.json 中，用這個金鑰可以開啟 /admin 上的管理儀表板。

在你所在機構已經執行的伺服器上部署 Potato

如果你所在機構已經在執行伺服器，就把官方釋出的 Docker 映像放在它的反向代理後面執行，而不必新建主機。nginx 之類的反向代理持有證書，並把請求轉發給 Potato。生產部署提供了 Docker Compose 檔案、nginx 配置和 gunicorn 設定。gunicorn 請保持一個 worker，用增加執行緒來提高併發，因為第二個 worker 程序會把同樣的項目分發兩次。

Potato 的 backup 塊會在那臺伺服器之外保留一份資料副本。它預設每五分鐘把標註輸出和項目資料庫的快照複製到一個 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 報告伺服器是否在執行、證書是否正常。在沒有域名的虛擬機器上，證書是為 IP 地址簽發的，有效期約六天。它會自動續期，所以如果研究在無人看管的情況下執行，請每隔幾天檢查一次狀態，或者傳入 --domain 並配好指向伺服器的 DNS 記錄。potato deploy logs myproject/config.yaml -f 會持續輸出伺服器日誌，管理儀表板則在標註者工作期間顯示進度、吞吐量和標註者間一致性。

研究結束時，先拉取資料，再刪除主機：

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

pull 把標註輸出和項目資料庫複製到一個新的 potato-pull-<name>-<timestamp> 目錄，並檢查收到了什麼。destroy 不會刪除從未拉取過的部署，沒有拉回任何檔案的拉取也不算數，所以在銷燬任何東西之前，請開啟拉取下來的目錄，確認最後的標註都在裡面。

延伸閱讀