6.3 · Hugging Face Spaces 集成（Hugging Face Spaces Integration）

Hugging Face Spaces 集成

Hugging Face Spaces 集成

相关源文件

以下文件为本维基页面的生成提供了上下文：

• README.md
• argilla-server/src/argilla_server/api/schemas/v1/suggestions.py
• argilla/README.md
• argilla/docs/assets/images/getting_started/dataset_configurator.png
• argilla/docs/assets/images/how_to_guides/custom_field/3d_object_viewer.png
• argilla/docs/assets/images/how_to_guides/custom_field/images_in_two_columns.png
• argilla/docs/assets/images/how_to_guides/custom_field/metadata_table.png
• argilla/docs/getting_started/faq.md
• argilla/docs/getting_started/how-to-configure-argilla-on-huggingface.md
• argilla/docs/getting_started/how-to-deploy-argilla-with-docker.md
• argilla/docs/getting_started/quickstart.md
• argilla/docs/how_to_guides/annotate.md
• argilla/docs/how_to_guides/custom_fields.md
• argilla/docs/how_to_guides/distribution.md
• argilla/docs/how_to_guides/query.md
• argilla/docs/index.md
• argilla/docs/reference/argilla/client.md
• argilla/docs/reference/argilla/search.md
• argilla/src/argilla/_models/_dataset_progress.py
• argilla/src/argilla/settings/_question.py

本页面提供了在 Hugging Face Spaces 上部署和配置 Argilla 的技术指南。内容涵盖部署方法、配置选项、认证流程，以及如何与部署在 Spaces 上的 Argilla 实例进行交互。

关于基于 Docker 的部署，请参见 Docker 部署。关于 Kubernetes 部署，请参见 Kubernetes 部署。

部署方法

Argilla 可以通过以下两种方式部署到 Hugging Face Spaces：

无代码部署

最快速的部署方法是使用"部署到 Spaces"按钮：

1. 从 Argilla 仓库点击"部署到 Spaces"按钮
2. 使用以下推荐设置配置你的 Space：
   • 名称：任意名称（例如"my-argilla"）
   • 持久化存储："小型"（付费选项，推荐用于非测试用途）
   • USERNAME/PASSWORD 密钥：留空（如果你想使用 Hugging Face OAuth）

1. 点击"创建 Space"启动 Argilla（大约需要 2-3 分钟）

Python SDK 部署

如需通过编程方式部署，可以使用 deploy_on_spaces 方法：

import argilla as rg

# 创建一个 Space 并返回已认证的客户端
authenticated_client = rg.Argilla.deploy_on_spaces(api_key="<api_key>")

该方法会：

• 使用 Argilla 模板创建一个 Space
• 设置 Hugging Face OAuth 认证
• 创建一个默认的"argilla"工作区
• 返回一个预配置的客户端，可立即使用

来源：argilla/docs/getting_started/quickstart.md:30-50, argilla/docs/reference/argilla/client.md:12-19

部署架构

Space 部署将整个 Argilla 技术栈（服务器、数据库、搜索引擎、消息队列）封装在一个托管环境中，可通过 Web UI 或 Python SDK 进行访问。

来源：README.md:22-33, 系统架构总览图（来自提示）

配置选项

持久化存储

Spaces 会因多种原因重启（维护、不活动、设置变更）。重启时：

• 使用持久化存储：所有数据集、用户和配置都会保留
• 不使用持久化存储：所有数据都会丢失，Argilla 会重置为默认状态

来源：argilla/docs/getting_started/how-to-configure-argilla-on-huggingface.md:16-28

OAuth 配置

默认情况下，Spaces 通过 .oauth.yml 文件使用 Hugging Face OAuth：

providers:
  - name: huggingface

allowed_workspaces:
  - name: argilla

该配置会：

• 允许使用 Hugging Face 账户登录
• 仅授予用户在"argilla"工作区中的"标注者"角色
• 阻止标注者创建或修改数据集

如需自定义访问权限：

• 编辑文件以添加更多工作区
• 重命名或删除文件以禁用 OAuth
• 将 Space 设置为私有，以仅限组织成员访问

来源：argilla/docs/getting_started/how-to-configure-argilla-on-huggingface.md:40-74

私有 Spaces

对于私有 Space，SDK 客户端需要你的 Hugging Face 令牌：

import argilla as rg

HF_TOKEN = "..."  # 来自 https://huggingface.co/settings/tokens

client = rg.Argilla(
    api_url="<api_url>",
    api_key="<api_key>",
    headers={"Authorization": f"Bearer {HF_TOKEN}"}
)

来源：argilla/docs/getting_started/how-to-configure-argilla-on-huggingface.md:90-111

认证流程

该 OAuth 流程提供了无缝的认证体验，无需为 Argilla 单独设置凭据。

来源：argilla/docs/getting_started/quickstart.md:64-82

使用 Python SDK 连接

要连接到 Spaces 上的 Argilla 实例：

import argilla as rg

client = rg.Argilla(
    api_url="https://[your-username]-[your_space_name].hf.space",
    api_key="<api_key>"
)

# 验证连接
client.me  # 应返回你的用户信息

你的 API 密钥可以在以所有者身份登录后，在 Argilla Space 的"我的设置"页面中找到。

如果找不到 API URL：

1. 查看 Argilla 首页上的"从 SDK 导入"部分
2. 通过"嵌入此 Space"选项打开直接的 Space URL
3. 使用模式：https://[your-username]-[your_space_name].hf.space

来源：argilla/docs/getting_started/quickstart.md:112-147, README.md:97-99

部署方式对比

Hugging Face Spaces 非常适合快速启动、演示或小型团队。对于资源需求更高的生产部署，建议考虑 Docker 或 Kubernetes。

来源：argilla/docs/getting_started/quickstart.md:6-13

限制与注意事项

使用 Hugging Face Spaces 时，需要注意以下限制：

1. 资源限制：Spaces 的计算资源是固定的
2. 存储限制：持久化存储有容量限制
3. 不活动超时：Spaces 在长时间无访问后可能变为不活动状态
4. 环境定制：灵活性低于 Docker/Kubernetes 选项
5. 可见性：默认公开（可设置为私有）

对于包含大型数据集或大量用户的生产用例，建议考虑 Docker 或 Kubernetes 部署选项，以获得更好的控制力和可扩展性。

来源：argilla/docs/getting_started/how-to-configure-argilla-on-huggingface.md:20-28