Hugging Face Spaces#

Argilla 与 Hugging Face 技术栈（datasets、transformers、hub 和 setfit）良好集成，现在也可以使用 Hub 的 Spaces 进行部署。

警告

Hugging Face Spaces 现在具有持久存储，Argilla 1.11.0 及更高版本支持此功能，但您需要通过 Hugging Face Spaces 设置手动激活它。否则，除非您升级到付费空间，否则空间将在不活动 48 小时后关闭，您将丢失所有数据。为了避免数据丢失，我们强烈建议使用 Hugging Face 提供的持久存储层。有关更多信息，请查看“设置持久存储”部分。

在本指南中，您将学习如何部署自己的 Argilla 应用程序，并直接从 Hub 使用它进行数据标注工作流程。

你的第一个 Argilla Space#

在本节中，你将学习如何部署 Argilla Space，并使用它进行数据标注和训练情感分类器，使用 SetFit，一个出色的少样本学习库。

在 Spaces 上部署 Argilla#

你只需点击几下即可在 Spaces 上部署 Argilla

你需要定义所有者（你的个人帐户或组织）、Space 名称和可见性（Public 或 Private，如果是 Private，则需要设置 HF_TOKEN）。如果您计划频繁使用 Space 或处理用于数据标注和反馈收集的大型数据集，升级硬件以获得更强大的 CPU 和更大的 RAM 可以提高性能。

HF_Spaces

提示

如果您想自定义您的 Space 的标题、表情符号和颜色，请转到“文件和版本”，并编辑 README.md 文件的元数据。

您将看到 Building 状态，一旦它变为 Running，您的 Space 就可以使用了。如果您没有看到 Argilla 登录 UI，请刷新页面。

提示

您将看到登录屏幕，您需要使用 admin 或 argilla 以及默认密码 (12345678)。请记住，您可以使用密钥环境变量更改密码。如果您在输入凭据时收到 500 错误，请确保您已输入正确的密码。

提示

为了快速实验，您可以直接跳到下一节。如果您想添加访问限制，请转到本文档末尾的“设置密钥环境变量”。此外，如果您希望启用持久存储，请转到以下部分。建议长期使用时设置密钥变量和持久存储。

你的 Argilla Space URL#

Argilla 运行后，您可以使用 Direct URL 使用 UI。此 URL 使您可以访问全屏、稳定的 Argilla 实例，并且是使用 Argilla Python 库读取和写入数据集的 api_url。

  • 如果您有公共 Space，您将在“嵌入此 Space”选项（右上角）中找到 Direct URL。您将看到如下 URL：https://dvilasuero-argilla-setfit.hf.space

HF_Space_Direct_URL

  • 如果您使用的是私有 Space，则应按如下方式构建 Direct URL：https://[your-owner-name]-[your_space_name].hf.space。例如，如果 Space 的所有者是 dvilasuero，并且您的 Space 名称是 argilla-setfit，则您的 Direct URL 将是 https://dvilasuero-argilla-setfit.hf.space。

创建你的第一个数据集#

要创建您的第一个数据集，您需要在 Colab 或本地机器上 pip 安装 argilla

pip install argilla

然后，您必须连接到您的 Argilla HF Space。获取如前所述的 api_url，并从“我的设置”（UI）复制 api_key

import argilla as rg

# If you connect to your public HF Space
rg.init(
  api_url="[your_space_url]",
  api_key="admin.apikey" # this is the default API key, don't change it if you didn't set up one during the Space creation
  )

# If you connect to your private HF Space
rg.init(
  api_url="[your_space_url]",
  api_key="admin.apikey", # this is the default API key, don't change it if you didn't set up one during the Space creation
  extra_headers={"Authorization": f"Bearer {os.environ['HF_TOKEN']}"}
  )

现在，创建一个用于文本分类的数据集。我们将使用任务模板，查看文档以创建自定义数据集。指示将在其中创建数据集的工作区。您可以在“我的设置”（UI）中查看它们。

dataset = rg.FeedbackDataset.for_text_classification(
    labels=["sadness", "joy"],
    multi_label=False,
    use_markdown=True,
    guidelines=None,
    metadata_properties=None,
    vectors_settings=None,
)
# Create the dataset to be visualized in the UI (uses default workspace)
dataset.push_to_argilla(name="my-first-dataset", workspace="admin")

要添加记录，请创建一个包含要添加的记录的列表。将字段与之前指定的字段匹配。您还可以使用 pandas 或 load_dataset 读取现有数据集并从中创建记录。

records = [
    rg.FeedbackRecord(
        fields={
            "text": "I am so happy today",
        },
    ),
    rg.FeedbackRecord(
        fields={
            "text": "I feel sad today",
        },
    )
]
dataset.add_records(records)

恭喜！您现在在 Argilla UI 中拥有一个可用的数据集，可以开始浏览和标注。标注完成后，您还可以轻松地将其推送回 Hub。

dataset = rg.FeedbackDataset.from_argilla("my-first-dataset", workspace="admin")
dataset.push_to_huggingface("my-repo/my-first-dataset")

作为下一步，您可以查看Argilla 教程部分。所有教程都可以在 Colab 或本地 Jupyter Notebook 中运行，因此您可以开始使用 Argilla 和 Spaces 构建数据集！

反馈和支持#

如果您有改进建议或需要特定支持，请加入 Argilla Slack 社区 或在 Argilla 的 GitHub 存储库 上联系。

设置持久存储#

Hugging Face Spaces 最近引入了持久存储功能，必须通过 Hugging Face Spaces 设置手动启用。如果不激活此功能，并且您没有订阅付费空间升级，则空间将在不活动 48 小时后自动关闭，并在重新启动时执行恢复出厂设置，这意味着空间中的所有数据都将丢失，包括所有创建的用户、工作区和数据集。为了防止这种情况发生，我们强烈建议使用 Hugging Face 提供的持久存储层。

要启用持久存储，请转到您创建的 Space 上的“设置”选项卡，然后在“持久存储”部分单击所需的计划。这将为您的 Space 启用持久存储，您将能够使用它进行数据标注和反馈收集。

Alt text

警告

启用持久存储后，Space 将重新启动，并且 Space 中的所有数据都将丢失。请确保在创建任何资产之前启用存储，或者保存您希望保留的数据集，并在 Space 重新启动后重新创建您的资产。

注意

如果您尚未启用持久存储，Argilla 默认会显示警告消息。如果您不需要您的 Space 的持久存储，并且希望阻止警告消息出现，您可以将环境变量 ARGILLA_SHOW_HUGGINGFACE_SPACE_PERSISTENT_STORAGE_WARNING 设置为 false。即使 Space 未启用持久存储，这也将抑制警告消息。

设置密钥环境变量#

Space 模板提供了一种设置不同可选设置的方法，重点是保护您的 Argilla Space。

要设置这些密钥，您可以转到您创建的 Space 上的“设置”选项卡。请务必将这些值保存在某处以供以后使用。

模板 Space 有三个用户：owner、admin 和 argilla。用户名 owner 对应于 root 用户，他可以在您的 Argilla Space 中创建用户、工作区和上传数据集。用户名 admin 可以在其工作区中上传数据集。并且，用户名 argilla 是一个标注员用户，可以访问 argilla 工作区以及上传到那里的数据集。

可以使用以下密钥配置用于上传、读取、更新和删除数据集的用户名、密码和 API 密钥

  • OWNER_USERNAME：用于登录 Argilla 的所有者用户名。默认所有者用户名是 owner。通过设置自定义用户名，您可以使用自己的用户名登录应用程序。

  • OWNER_PASSWORD：这设置了一个自定义密码，用于使用 owner 用户名登录应用程序。默认密码是 12345678。通过设置自定义密码，您可以使用自己的密码登录应用程序。

  • OWNER_API_KEY：Argilla 提供了一个 Python 库来与应用程序交互（读取、写入和更新数据，记录模型预测等）。如果您未设置此变量，则库和您的应用程序将使用默认 API 密钥，即 owner.apikey。如果您想保护您的应用程序以进行数据读取和写入，我们建议您设置此变量。您选择的 API 密钥可以是您选择的任何字符串，如果您愿意，可以查看在线生成器。

  • ADMIN_USERNAME：用于登录 Argilla 的管理员用户名。默认管理员用户名是 admin。通过设置自定义用户名，您可以使用自己的用户名登录应用程序。

  • ADMIN_PASSWORD：这设置了一个自定义密码，用于使用 admin 用户名登录应用程序。默认密码是 12345678。通过设置自定义密码，您可以使用自己的密码登录应用程序。

  • ADMIN_API_KEY：Argilla 提供了一个 Python 库来与应用程序交互（读取、写入和更新数据，记录模型预测等）。如果您未设置此变量，则库和您的应用程序将使用默认 API 密钥，即 admin.apikey。如果您想保护您的应用程序以进行数据读取和写入，我们建议您设置此变量。您选择的 API 密钥可以是您选择的任何字符串，如果您愿意，可以查看在线生成器。

  • ANNOTATOR_USERNAME：用于登录 Argilla 的标注员用户名。默认标注员用户名是 argilla。通过设置自定义用户名，您可以使用自己的用户名登录应用程序。

  • ANNOTATOR_PASSWORD：这设置了一个自定义密码，用于使用 argilla 用户名登录应用程序。默认密码是 12345678。通过设置自定义密码，您可以使用自己的密码登录应用程序。

这些密钥变量的组合为您提供了以下设置选项

  1. 我想避免任何没有 API 密钥的人使用 Python 客户端添加、删除或更新数据集：您需要设置 ADMIN_PASSWORD 和 ADMIN_API_KEY。

  2. 此外，我想避免 argilla 用户名从 UI 中删除数据集：您需要设置 ANNOTATOR_PASSWORD，并在 Python 客户端中使用 argilla 生成的 API 密钥（检查您的 Space 日志）。如果您想控制数据集管理，但希望任何人都可以使用 argilla 用户浏览您的数据集，则此选项可能很有趣。

  3. 此外，我想避免任何没有密码的人使用 argilla 用户浏览我的数据集：您需要设置 ANNOTATOR_PASSWORD。在这种情况下，您可以根据您对数据集删除权限的需求，将 argilla 生成的 API 密钥和/或 ADMIN_API_KEY 值与 Python 客户端一起使用。

此外，LOAD_DATASETS 将允许您配置将预加载的示例数据集。默认值是 single，此变量的受支持值是：1. single：加载用于文本分类任务的单个数据集。2. full：加载用于 NLP 任务（TokenClassification、TextClassification、Text2Text）的所有示例数据集 3. none：不加载数据集。

设置 HF 身份验证#

从 1.23.0 版本开始，您可以为您的 Argilla Space 启用 Hugging Face 身份验证。此功能允许您向已登录 Hugging Face Hub 的用户授予对您的 Argilla Space 的访问权限。

注意

此功能对于公共众包项目特别有用。如果您想更好地控制谁可以登录 Space，您可以在私有 Space 上进行设置，以便只有您的组织的成员可以登录。或者，您可能想要创建用户并改用他们的凭据。

要启用此功能，您首先需要在 Hugging Face 中创建一个 OAuth 应用程序。为此，请转到您的 Hugging Face 用户设置，然后选择连接的应用程序 > 创建应用程序。进入后，为您的应用程序选择一个名称，并使用以下信息完成表单

  • 主页 URL： 您的 Argilla Space Direct URL。

  • 徽标 URL： [您的 Argilla Space Direct URL]/favicon.ico

  • 范围： openid 和 profile。

  • 重定向 URL： [您的 Argilla Space Direct URL]/oauth/huggingface/callback

这将创建一个客户端 ID 和一个应用程序密钥，您需要将其添加为您的 Space 的变量。为此，请转到 Space 设置 > 变量和密钥，并将客户端 ID 和应用程序密钥保存为环境变量密钥，如下所示

  1. 名称： OAUTH2_HUGGINGFACE_CLIENT_ID - 值： [您的客户端 ID]

  2. 名称： OAUTH2_HUGGINGFACE_CLIENT_SECRET - 值： [您的应用程序密钥]

或者，您可以在 .oauth.yaml 文件中提供环境变量，如下所示

# This attribute will enable or disable the Hugging Face authentication
enabled: true

providers:
# The OAuth provider setup
# For now, only Hugging Face is supported
  - name: huggingface
    # This is the client ID of the OAuth app. You can find it in your Hugging Face settings.
    # see https://hugging-face.cn/docs/hub/oauth#creating-an-oauth-app for more info.
    # You can also provide it by using the env variable `OAUTH2_HUGGINGFACE_CLIENT_ID`
    client_id: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX

    # This is the client secret of the OAuth app. You can find it in your Hugging Face settings.
    # See https://hugging-face.cn/docs/hub/oauth#creating-an-oauth-app for more info.
    # We encourage you to provide it by using the env variable `OAUTH2_HUGGINGFACE_CLIENT_SECRET`
    client_secret: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX

    # The scope of the OAuth app. At least `openid` and `profile` are required.
    scope: openid profile

# This section defines the allowed workspaces for the oauth users.
# Workspaces defined here must exist in Argilla.
allowed_workspaces:
    - name: admin

警告

请注意，在公共 Space 的情况下，.oauth.yaml 文件是公开的，或者如果是私有 Space，则您的组织的其他成员可以访问它。

因此，我们建议将这些变量设置为环境变量密钥。

现在检查 enabled 参数在您的 .oauth.yaml 文件中是否设置为 true，然后返回到设置执行Factory rebuild。Space 重新启动后，您和您的协作者可以使用他们的 Hugging Face 帐户登录到您的 Space。