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。

延伸阅读