6 · 部署与配置（Deployment and Configuration）

部署与配置

部署与配置

相关源文件

本章引用的主要源码文件：

• .dockerignore
• 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

本文档介绍了部署 Argilla 的不同方法以及每种部署方式可用的配置选项。Argilla 是一个自托管工具，可以根据您的需求和技术要求部署在不同的环境中。有关开发 Argilla 本身的信息，请参阅开发环境搭建 Wiki 页面。

部署选项概览

Argilla 提供三种主要的部署方法，每种方法适用于不同的使用场景：

来源： argilla/docs/getting_started/quickstart.md:7-62 argilla/README.md:81-99

Hugging Face Spaces 部署

在 Hugging Face Spaces 上部署 Argilla 是推荐的入门方式。您可以在 5 分钟内完成部署，无需维护服务器或运行复杂命令。

无代码部署方法

1. 从快速入门指南点击部署按钮
2. 按照以下步骤使用默认值：
   • 保留默认的 Space 所有者（您的个人账户）
   • 将 USERNAME 和 PASSWORD 密钥留空，以便使用您的 Hugging Face 用户登录
   • 点击"创建 Space"启动 Argilla
3. 当 Argilla 界面出现后，使用您的 Hugging Face 凭证登录

Python SDK 部署方法

或者，您也可以通过编程方式部署 Argilla：

import argilla as rg

authenticated_client = rg.Argilla.deploy_on_spaces(api_key="<api_key>")

此方法会：

• 在 Hugging Face Hub 上部署一个带有 OAuth 登录功能的 Argilla Space
• 创建一个名为 argilla 的默认工作区，并将您设为所有者
• 返回一个已认证的客户端，可以立即使用

配置选项

持久化存储

强烈建议将持久化存储设置为 SMALL（付费服务）：

• 如果没有持久化存储，Space 重启时所有数据都会丢失
• Space 会因维护、不活动或更改设置而重启
• 仅将 FREE 用于临时测试目的

OAuth 配置

默认情况下，Argilla Spaces 使用 Hugging Face OAuth：

• 任何能看到您 Space 的 Hugging Face 用户都可以作为标注员登录
• 这些用户只能访问 argilla 工作区
• 您可以修改 .oauth.yml 文件来：
  • 更改允许的工作区列表
  • 完全禁用 OAuth 访问

组织与私有 Space

您可以在组织下部署 Argilla 或将 Space 设为私有：

• 将 Space 设为私有，以限制只有您或组织成员可以访问
• 在组织下部署时，在 USERNAME 密钥中设置您的 Hugging Face 用户名
• 要使用 SDK 访问私有 Space，需要指定您的 Hugging Face 令牌：

import argilla as rg

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

来源： argilla/docs/getting_started/quickstart.md:9-57 argilla/docs/getting_started/how-to-configure-argilla-on-huggingface.md:6-128 argilla/docs/reference/argilla/client.md:10-42

Docker 部署

当您希望在本地机器或服务器上运行 Argilla，并对配置有更多控制时，Docker 部署是合适的选择。

部署步骤

1. 为 Argilla 创建一个文件夹：

   mkdir argilla && cd argilla

1. 下载 docker-compose.yaml 文件：

   wget -O docker-compose.yaml https://raw.githubusercontent.com/argilla-io/argilla/main/examples/deployments/docker/docker-compose.yaml

或使用 curl：

   curl https://raw.githubusercontent.com/argilla-io/argilla/main/examples/deployments/docker/docker-compose.yaml -o docker-compose.yaml

1. 启动服务：

   docker compose up -d

1. 访问 http://localhost:6900 进入 Argilla

docker-compose.yaml 文件会设置多个容器：

• argilla-server：后端 API 服务器
• argilla-ui：基于 Web 的用户界面
• elasticsearch：用于存储和查询记录的搜索引擎
• database：用于存储元数据和配置的数据库
• redis：用于任务队列和缓存

来源： argilla/docs/getting_started/how-to-deploy-argilla-with-docker.md:5-40 .dockerignore:1-15

Kubernetes 部署

对于需要可扩展性和高可用性的生产环境部署，推荐使用 Kubernetes。Argilla 仓库包含用于编排所有组件部署的 Kubernetes Helm Chart。

虽然提供的文件中没有详细的 Kubernetes 部署说明，但典型的部署步骤包括：

1. 添加 Argilla Helm 仓库
2. 使用自定义值安装 Chart
3. 配置 Ingress 或端口转发以访问界面

补充说明：目录中提到了 Kubernetes 部署，但当前文件没有提供详细部署文档。

系统架构

了解 Argilla 的架构有助于配置和排查部署问题：

在所有部署方法中，这些组件协同工作：

• argilla-server 提供 FastAPI 后端
• 数据库 存储元数据、用户和配置
• 搜索引擎（Elasticsearch/OpenSearch）索引和搜索记录
• Redis 队列 处理异步任务
• argilla-frontend 提供用于标注数据的 Web 界面

来源： 任务开始时提供的系统架构图 argilla/docs/getting_started/quickstart.md

客户端配置

要从 Python 与 Argilla 服务器交互，可以使用 Argilla 客户端：

import argilla as rg

client = rg.Argilla(
    api_url="<api_url>",
    api_key="<api_key>"
)

对于 Hugging Face Spaces：

• api_url 是您的 Space URL（例如 https://username-spacename.hf.space）
• 在 Argilla 界面的"我的设置"页面中找到您的 api_key
• 对于私有 Space，在请求头中包含您的 Hugging Face 令牌

要验证连接，可以检查您的用户信息：

client.me  # 返回您的用户信息

连接后，您可以管理各种资源：

# 访问数据集
dataset = client.datasets(name="my_dataset")

# 访问工作区
workspace = client.workspaces(name="my_workspace")

# 访问用户
user = client.users(name="my_user")

来源： argilla/docs/reference/argilla/client.md:8-61 argilla/docs/getting_started/quickstart.md:112-150

环境变量与服务器配置

虽然提供的文件中没有详细说明具体环境变量，但 Argilla 服务器支持通过环境变量进行配置，包括：

Hugging Face Spaces 特定变量

• ARGILLA_SHOW_HUGGINGFACE_SPACE_PERSISTENT_STORAGE_WARNING：设置为 false 可以禁用持久化存储警告

认证变量

• USERNAME：对于组织 Space，设置您的 Hugging Face 用户名以授予所有者角色
• PASSWORD：使用 Hugging Face OAuth 时通常留空

OAuth 配置

Argilla Spaces 使用 .oauth.yml 配置文件，默认内容如下：

providers:
  - name: huggingface

# 允许的工作区必须存在
allowed_workspaces:
  - name: argilla

您可以修改此文件来：

• 更改允许的工作区
• 重命名文件以完全禁用 OAuth 访问

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

总结

Argilla 提供灵活的部署选项以满足各种需求：

• Hugging Face Spaces：最简单的选项，推荐入门使用
• Docker：对配置有更多控制，适合本地开发
• Kubernetes：适用于生产环境的可扩展解决方案

部署方法的选择取决于您对以下方面的具体要求：

• 设置简便性
• 配置控制程度
• 可扩展性需求
• 数据隐私考虑

无论选择哪种部署方法，都可以访问 Argilla 的相同核心功能，允许您创建、管理和标注数据集。