把你的 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 的部署命令这样的程序可以代表你操作托管公司的账号。