把你的 Potato 研究放到網上

把 Potato 任務從你的電腦交到標註者手中：請 IT 團隊代辦、點選準備好的部署按鈕、從筆記型電腦分享連結，或者租用一臺伺服器。

要把 Potato 研究放到網上，你需要把任務執行在一臺標註者能通過網址訪問的計算機上，在研究進行期間妥善儲存標註，並在研究結束時下載標註。請所在機構的 IT 團隊代辦，以及點選同事準備好的部署按鈕，是你這邊不需要使用終端的兩條路線。

部署一項研究，是指把你構建好的 Potato 任務從自己的電腦搬到一臺伺服器上。伺服器是一臺始終開機、始終連著網際網路的計算機。標註者隨後可以在任何地方用網路瀏覽器開啟任務，標註者作答時，Potato 會把每個答案儲存在伺服器上。研究設計器的預覽是在你自己的瀏覽器裡執行 Potato，別人無法訪問那一份副本。在設計器中構建的研究仍需要走下面的某一條路線。

每條路線都從同一個項目資料夾開始。在研究設計器中，Download project (.zip) 按鈕會儲存 config.yaml（描述任務的檔案）、一個示例資料檔案和一份 README。示例檔案裡有三個佔位條目。部署之前，請按資料格式描述的格式，把示例檔案換成你自己的條目。

選擇路線

這些路線的區別在於由誰來做技術工作、伺服器花多少錢，以及研究能保持線上多久。下面的費用來自 2026-11-04 各主機的價目表和 Potato 自己的估算，等待時間只是粗略的參考，並非實測：

路線	適合	費用	是否需要終端	通常等待
請 IT 或科研計算團隊代辦	敏感資料、機構統一登入、持續數月的研究	由你所在機構決定	你不需要	幾天到幾週
點選同事準備好的部署按鈕	有一個人會用 git 的實驗室	Render 免費，Heroku 每月 $7	你不需要	當天
從你自己的電腦分享	試點或組會，持續一個下午	免費	需要，幾條命令	一兩個小時
用一條命令租用伺服器	持續數週、由你自己負責執行的研究	每月約 €6 到 $12，Jetstream2 上免費	需要，還要有云賬號	一個下午

如果拿不準，就先找你的 IT 團隊。機構內部的伺服器會把資料放在機構本來就在管理的裝置上，IT 團隊還可以負責安全更新和備份。

請 IT 或科研計算團隊代辦

許多大學和醫院都有科研計算服務，可以為研究託管網路應用。對這樣的團隊來說，Potato 就是一個普通的網路應用，團隊可以從一頁關於 Potato 需求的摘要入手。

從研究設計器下載項目，並把示例資料檔案換成你的條目。
把項目資料夾，連同給 IT 團隊的 Potato 伺服器要求的連結，一起發給你的 IT 團隊。
告訴團隊你的標註者是誰、有多少人參加，以及研究持續多久。
說明標註者應當如何登入。有機構賬號的同事可以使用單點登入，也就是你所在機構已經在執行的登入方式，外部標註者則可以使用你列出的使用者名稱。
說明條目或答案中是否含有個人資訊或敏感資訊，並寫出研究所依據的倫理批准。
請團隊提供研究的網址、能開啟 Potato 管理面板的管理員金鑰，以及一份備份計劃和研究結束時把資料交給你的安排。

地址發來之後，先按邀請標註者之前逐項檢查，再把地址發給任何人。

點選同事準備好的部署按鈕

部署按鈕是程式碼倉庫頁面上的一個連結，它完全通過你瀏覽器裡的表單，在託管公司的伺服器上建立一份 Potato 任務的副本。會用 git 和終端的同事，用 potato deploy button 命令，基於存放你項目資料夾的倉庫製作一次這個按鈕。應當發給這位同事的頁面是在本地或雲端執行 Potato。

這個按鈕適用於三個主機，它們的收費方式各不相同：

Render 在免費方案上執行研究，不需要繫結付款方式。免費的 Render 服務在 15 分鐘沒有訪問者後會進入休眠，下一位標註者到來時大約需要一分鐘才能喚醒。
Heroku 對按鈕建立的伺服器每月收費 $7。Heroku 要求先有經過驗證的賬號（通常要通過信用卡），才能建立應用。
AWS 執行一臺每月 $12 的 Lightsail 伺服器。AWS 按鈕從公開倉庫讀取任務，所以只適合條目可以公開的情形。

Render 和 Heroku 在伺服器重啟時都會清空伺服器的磁碟。因此按鈕每五分鐘把標註複製到 Hugging Face（一個分享資料和模型的網站）上的一個私有資料集裡，並在伺服器啟動時把標註複製回來。你在點選時為這個資料集命名，資料集屬於你的賬號。

點選之前，請準備好三樣東西：

主機（Render 或 Heroku）上的一個賬號；
一個免費的 Hugging Face 賬號，以及一個具有寫許可權的訪問令牌，在 huggingface.co/settings/tokens 建立；
如果倉庫是私有的，還要有訪問該倉庫的許可權。對私有倉庫，Heroku 會要求你關聯自己的 GitHub 賬號。

然後開始部署：

點選倉庫 README 裡的按鈕，並登入主機。
給應用起一個名字。這個名字會成為研究網址的一部分。
在 POTATO_BACKUP_HF_REPO 中填寫由你的 Hugging Face 使用者名稱和研究名稱組成的資料集名稱，例如 your-username/my-study-annotations。名稱是新的時，Potato 會建立這個資料集並把它設為私有。
把你的 Hugging Face 令牌貼上到 HF_TOKEN。其餘每個欄位都保持按鈕已經填好的值。
開始部署，等待主機報告應用已在執行。開啟主機顯示的網址。
找到管理員金鑰，也就是主機在部署時生成的一個密碼。在 Heroku 上，金鑰是應用 Settings 選項卡中的 POTATO_ADMIN_API_KEY 條目，在 Render 上，同一個條目位於服務的 Environment 頁面。
在研究網址末尾加上 /admin 並開啟，貼上管理員金鑰即可進入管理面板。

任務、條目和標註者名單都固定在倉庫裡。請在點選之前把任務定稿，因為之後的任何改動都要經過製作按鈕的那位同事。除非條目可以公開，否則請保持倉庫為私有。

從你自己的電腦分享連結

你自己的電腦可以為一場持續一個下午的試點提供服務。標註者開啟一個臨時網頁連結，標註落在你的項目資料夾裡，關閉命令後連結就失效。這條路線需要終端，也就是用來輸入命令的程式，在 Mac 上是 Terminal（在“應用程式”的“實用工具”裡），在 Windows 上是 PowerShell（在開始選單中搜索“PowerShell”）。

從 python.org/downloads 安裝 Python 3.9 或更新版本。在 Windows 上，下載的是 Python 安裝管理器。在 Mac 上，下載的是 macOS 安裝程式。
開啟終端並安裝 Potato。在 Mac 上，輸入：
bash
```
python3 -m pip install potato-annotation
```
在 Windows 上，輸入：
powershell
```
py -m pip install potato-annotation
```
解壓你從研究設計器下載的項目。在 Mac 上，雙擊 .zip 檔案。在 Windows 上，右鍵單擊該檔案並選擇 Extract All。把示例資料檔案換成你的條目。
讓終端進入項目資料夾並啟動 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。只有你自己的電腦能訪問這個地址。在終端中按 Ctrl-C 即可停止 Potato。
要讓其他人進來，請安裝 cloudflared，這是 Cloudflare 的一個免費程式，不需要賬號。在裝有 Homebrew 的 Mac 上，執行 brew install cloudflared。在 Windows 上，從 Cloudflare 的下載頁面下載 Windows 安裝程式。
用 potato share 取代 potato start：
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更詳細地介紹 potato share。

用一條命令租用伺服器

potato deploy up 會向雲服務公司租用一臺伺服器，申請 HTTPS 證書（瀏覽器位址列裡的掛鎖），上傳你的項目資料夾，啟動研究，並列印網址。這條命令需要上面第 1 到 3 步的終端設定、雲服務公司的賬號，以及一個 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

每個主機都使用同樣的兩條命令，每個主機的指南會給出該主機的提供商名稱和安裝命令。第一條命令顯示方案和每月費用，不建立任何東西，第二條命令在你確認後建立伺服器：

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 的副本會沿用原所有者的備份設定，並丟失原 Space 的金鑰。請改用 potato deploy up --provider huggingface 部署 Potato Space。

邀請標註者之前

無論你走的是哪條路線，研究有了網址之後，請把下面這份清單走一遍：

決定誰能登入。 最簡單的封閉方案是一份使用者名稱名單。在研究設計器中，關閉 Allow All Users，並在 Authorized Users 下新增每位標註者。名單上的每位標註者在第一次訪問時註冊並自己選擇密碼，Potato 會拒絕不在名單上的人。請把使用者名稱直接發給每位標註者，因為第一個註冊某個名單使用者名稱的人就擁有該賬號。機構賬號請見 SSO 與 OAuth，眾包工作者請見眾包整合。開啟 Allow All Users 時，任何找到這個地址的人都可以建立賬號。這個設定只應留給公開演示。
知道標註存放在哪裡。 Potato 在標註者作答時就儲存其答案，儲存在名為 user_state.json 的檔案裡，每位標註者有一個資料夾。這些資料夾位於配置所指定的輸出資料夾中，研究設計器把它叫作 output。在你自己的電腦上，這個資料夾位於項目資料夾之內。通過按鈕部署時，Hugging Face 資料集儲存著重啟後仍然存在的副本。在租用的伺服器上，potato deploy pull 會下載該資料夾。在機構的伺服器上，請向 IT 詢問伺服器是如何備份的。
用第二個瀏覽器測試。 在隱私視窗中開啟研究地址，也就是 Chrome 的無痕模式（Incognito）、Safari 和 Firefox 的隱私視窗（Private Window），以及 Edge 的 InPrivate。在名單中新增一個 pilot-test 這樣的使用者名稱，用該名字註冊，並回答三個條目。關閉視窗後重新登入，檢查答案是否還在。然後開啟管理面板，檢查測試標註者是否出現。如果標註者可能用手機作答，也請在手機上試一下這個地址。
保管好管理員金鑰。 管理員金鑰能開啟 /admin 的管理面板。儀表板會顯示每位標註者的答案。在你自己的電腦上，你第一次開啟 /admin 時，Potato 會把金鑰儲存在項目資料夾的 admin_api_key.txt 中。
寫好邀請信。 向每位標註者傳送地址、使用者名稱、任務需要多長時間，以及出了問題時該聯絡誰。

獲取結果

管理面板可以不用終端就把結果下載到你的電腦。開啟 /admin，輸入管理員金鑰，然後選擇 Publish Dataset。在 Target 下選擇 Local archive，把 Data format 設為 CSV（便於用電子表格開啟），然後點選 Publish。壓縮包準備好後，點選 Download archive。

壓縮包裡有每位標註者的答案、條目，以及按多數投票合併的標籤。壓縮包中的 README 會報告各標籤的數量和標註者之間的一致性。標註者的姓名會被替換成 A1、A2 等，除非你取消勾選 Anonymize annotators。調查問卷的答案不會進入壓縮包，除非你勾選 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 伺服器？

你建立 Potato 伺服器的辦法，是把任務執行在一臺標註者能通過網址訪問的計算機上。你所在機構的 IT 團隊可以替你執行任務，同事可以準備好一個供你點選的部署按鈕，potato share 可以從你的筆記型電腦為一次試點提供服務，potato deploy up 則可以替你租用伺服器。選擇路線下的表格按費用和每條路線所需的終端操作對這些路線做了比較。

如何在我的電腦上安裝 Potato？

從 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，即可啟動任務。可選功能見安裝。

本頁用到的詞

伺服器。 伺服器是一臺始終開機、始終連著網際網路的計算機，其他人可以通過網路瀏覽器使用這臺計算機上的程式。
URL，即網址。 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 的部署命令這樣的程式可以代表你操作託管公司的賬號。