数据集管理¶

本指南概述了数据集，解释了如何在 Argilla 中设置和管理数据集的基础知识。

数据集是记录的集合，您可以配置它以供标注员使用 UI 提供反馈。根据您任务的具体要求，您可能需要各种类型的反馈。您可以自定义数据集以包含不同类型的问题，因此第一步是定义您项目的目标以及您将需要的数据和反馈类型。有了这些信息，您可以通过设置定义字段、问题、元数据、向量和指南来开始配置数据集。

问题：谁可以管理数据集？

只有具有 owner 角色的用户才能管理（创建、检索、更新和删除）所有数据集。

具有 admin 角色的用户可以管理（创建、检索、更新和删除）他们有权访问的工作区中的数据集。

主要类

rg.Datasetrg.Settings

rg.Dataset(
    name="name",
    workspace="workspace",
    settings=settings,
    client=client
)

查看 Dataset - Python 参考以详细了解 Dataset 类的属性、参数和方法。

rg.Settings(
    fields=[rg.TextField(name="text")],
    questions=[
        rg.LabelQuestion(
            name="label",
            labels=["label_1", "label_2", "label_3"]
        )
    ],
    metadata=[rg.TermsMetadataProperty(name="metadata")],
    vectors=[rg.VectorField(name="vector", dimensions=10)],
    guidelines="guidelines",
    allow_extra_metadata=True,
    distribution=rg.TaskDistribution(min_submitted=2),
)

查看 Settings - Python 参考以详细了解 Settings 类的属性、参数和方法。

创建数据集¶

要创建数据集，您可以在 Dataset 类中定义它，然后调用 create 方法，该方法会将数据集发送到服务器，以便可以在 UI 中可视化它。如果数据集未出现在 UI 中，您可能需要单击刷新按钮以更新视图。有关数据集的进一步配置，您可以参考设置部分。

信息

如果您已使用 Hugging Face Spaces 和 HF 登录部署了 Argilla，则可以使用 argilla 作为工作区名称。否则，您可能需要按照本指南创建一个工作区。

import argilla as rg

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

settings = rg.Settings(
    guidelines="These are some guidelines.",
    fields=[
        rg.TextField(
            name="text",
        ),
    ],
    questions=[
        rg.LabelQuestion(
            name="label",
            labels=["label_1", "label_2", "label_3"]
        ),
    ],
)

dataset = rg.Dataset(
    name="my_dataset",
    workspace="my_workspace",
    settings=settings,
)

dataset.create()

创建的数据集将为空，要添加记录，请转到此操作指南。

访问属性

通过直接在 dataset 对象上调用数据集的属性来访问它们。例如，dataset.id、dataset.name 或 dataset.settings。您可以类似地访问字段、问题、元数据、向量和指南。例如，dataset.fields 或 dataset.questions。

使用相同设置创建多个数据集¶

要使用相同设置创建多个数据集，请定义一次设置并将其传递给每个数据集。

import argilla as rg

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

settings = rg.Settings(
    guidelines="These are some guidelines.",
    fields=[rg.TextField(name="text", use_markdown=True)],
    questions=[
        rg.LabelQuestion(name="label", labels=["label_1", "label_2", "label_3"])
    ],
    distribution=rg.TaskDistribution(min_submitted=3),
)

dataset1 = rg.Dataset(name="my_dataset_1", settings=settings)
dataset2 = rg.Dataset(name="my_dataset_2", settings=settings)

# Create the datasets on the server
dataset1.create()
dataset2.create()

从现有数据集创建数据集¶

要从现有数据集创建新数据集，请从现有数据集中获取设置并将其传递给新数据集。

import argilla as rg

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

existing_dataset = client.datasets("my_dataset")

new_dataset = rg.Dataset(name="my_dataset_copy", settings=existing_dataset.settings)

new_dataset.create()

信息

您还可以将原始数据集中的记录复制到新数据集中

records = list(existing_dataset.records)
new_dataset.records.log(records)

定义数据集设置¶

提示

您可以直接使用我们针对文本分类、排名和评分的一些预构建模板，而无需定义您自己的自定义设置。了解更多此处。

字段¶

数据集中的字段由一个或多个需要标注的数据项组成。目前，Argilla 通过 TextField 支持纯文本和 Markdown，通过 ImageField 支持图像，通过 ChatField 支持聊天格式数据，以及通过 CustomField 支持完全自定义模板。

注意

UI 中字段的顺序遵循将这些字段添加到 Python SDK 中字段属性的顺序。

查看 Field - Python 参考以详细了解字段类。

文本图像聊天自定义

rg.TextField(
    name="text",
    title="Text",
    use_markdown=False,
    required=True,
    description="Field description",
)

rg.ImageField(
    name="image",
    title="Image",
    required=True,
    description="Field description",
)

rg.ChatField(
    name="chat",
    title="Chat",
    use_markdown=True,
    required=True,
    description="Field description",
)

CustomField 允许您为字段使用自定义模板。如果您想为字段使用自定义 UI，这将非常有用。您可以使用 template 参数传递一个字符串，该字符串将呈现为字段的 UI。

默认情况下，advanced_mode=False，这将为模板使用括号语法引擎。此引擎将 {{record.fields.field.key}} 转换为记录字段对象的值。您也可以使用 advanced_mode=True，这将停用上述括号语法引擎，并允许您将自定义 javascript 添加到模板以呈现字段。

rg.CustomField(
    name="custom",
    title="Custom",
    template="<div>{{record.fields.custom.key}}</div>",
    advanced_mode=False,
    required=True,
    description="Field description",
)

提示

要了解有关如何使用 HTML 和 CSS 模板创建自定义字段的更多信息，请查看此操作指南。

问题¶

要收集数据集的反馈，您需要制定问题，要求标注员回答。

查看 Questions - Python 参考以详细了解问题类。

标签多标签排名评分Span文本

LabelQuestion 要求标注员从选项列表中选择一个唯一标签。此类型适用于文本分类任务。在 UI 中，它们将具有圆形形状。

rg.LabelQuestion(
    name="label",
    labels={"YES": "Yes", "NO": "No"}, # or ["YES", "NO"]
    title="Is the response relevant for the given prompt?",
    description="Select the one that applies.",
    required=True,
    visible_labels=10
)

MultiLabelQuestion 要求标注员从选项列表中选择所有适用的标签。此类型适用于多标签文本分类任务。在 UI 中，它们将具有方形形状。

rg.MultiLabelQuestion(
    name="multi_label",
    labels={
        "hate": "Hate Speech",
        "sexual": "Sexual content",
        "violent": "Violent content",
        "pii": "Personal information",
        "untruthful": "Untruthful info",
        "not_english": "Not English",
        "inappropriate": "Inappropriate content"
    }, # or ["hate", "sexual", "violent", "pii", "untruthful", "not_english", "inappropriate"]
    title="Does the response include any of the following?",
    description="Select all that apply.",
    required=True,
    visible_labels=10,
    labels_order="natural"
)

RankingQuestion 要求标注员对选项列表进行排序。它对于收集有关一组选项的偏好或相关性的信息很有用。

rg.RankingQuestion(
    name="ranking",
    values={
        "reply-1": "Reply 1",
        "reply-2": "Reply 2",
        "reply-3": "Reply 3"
    } # or ["reply-1", "reply-2", "reply-3"]
    title="Order replies based on your preference",
    description="1 = best, 3 = worst. Ties are allowed.",
    required=True,
)

RankingQuestion

RatingQuestion 要求标注员从整数值列表中选择一个选项。此类型对于收集数值分数很有用。

rg.RatingQuestion(
    name="rating",
    values=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    title="How satisfied are you with the response?",
    description="1 = very unsatisfied, 10 = very satisfied",
    required=True,
)

RatingQuestion

SpanQuestion 要求标注员选择特定字段的文本部分并对其应用标签。这种类型的问题对于命名实体识别或信息提取任务很有用。

rg.SpanQuestion(
    name="span",
    field="text",
    labels={
        "PERSON": "Person",
        "ORG": "Organization",
        "LOC": "Location",
        "MISC": "Miscellaneous"
    }, # or ["PERSON", "ORG", "LOC", "MISC"]
    title="Select the entities in the text",
    description="Select the entities in the text",
    required=True,
    allow_overlapping=False,
    visible_labels=10
)

SpanQuestion

TextQuestion 为标注员提供了一个自由文本区域，他们可以在其中输入任何文本。此类型对于收集自然语言数据（例如更正或解释）很有用。

rg.TextQuestion(
    name="text",
    title="Please provide feedback on the response",
    description="Please provide feedback on the response",
    required=True,
    use_markdown=True
)

TextQuestion

元数据¶

元数据属性允许您配置元数据信息的使用，以用于 UI 和 Python SDK 中可用的过滤和排序功能。

查看 Metadata - Python 参考以详细了解元数据类。

术语整数浮点数

TermsMetadataProperty 允许添加字符串列表作为元数据选项。

rg.TermsMetadataProperty(
    name="terms",
    options=["group-a", "group-b", "group-c"],
    title="Annotation groups",
    visible_for_annotators=True,
)

IntegerMetadataProperty 允许添加整数值作为元数据。

rg.IntegerMetadataProperty(
    name="integer",
    title="length-input",
    min=42,
    max=1984,
)

FloatMetadataProperty 允许添加浮点数值作为元数据。

rg.FloatMetadataProperty(
    name="float",
    title="Reading ease",
    min=-92.29914,
    max=119.6975,
)

注意

您还可以在数据集中将 allow_extra_metadata 参数设置为 True，以指定数据集是否允许记录中存在除元数据下指定的元数据字段。请注意，这些字段对任何用户都无法从 UI 访问，只能使用 Python SDK 检索。

向量¶

要在 UI 和 Python SDK 中使用相似性搜索，您需要使用 VectorField 类配置向量。

查看 Vector - Python 参考以详细了解 VectorField 类。

rg.VectorField(
    name="my_vector",
    title="My Vector",
    dimensions=768
)

指南¶

一旦您确定了要显示的数据和要提出的问题，向标注员提供清晰的指南非常重要。这些指南帮助他们理解任务并一致地回答问题。您可以通过两种方式提供指南

在数据集指南中：在 Python SDK 中创建数据集时，将其作为参数添加。它们将出现在标注界面中。

guidelines = "In this dataset, you will find a collection of records that show a category, an instruction, a context and a response to that instruction. [...]"

作为问题描述：在 Python SDK 中创建问题时，将它们作为参数添加。此文本将显示在 UI 中问题旁边的工具提示中。

最佳实践是至少使用数据集指南，如果不是两种方法都使用。问题描述应该简短，并为特定问题提供上下文。它们可以是该问题指南的摘要，但通常不足以协调整个标注团队。在指南中，您可以包括项目描述、如何回答每个问题的详细信息和示例、何时丢弃记录的说明等。

提示

如果您想进一步了解项目开发期间指南的最佳实践，请查看我们的博客文章。

分布¶

当作为一个团队工作时，您可能希望分配标注任务以确保效率和质量。您可以使用 TaskDistribution 设置来配置每个记录预期的最少提交响应数。Argilla 将使用此设置自动处理您团队成员待处理队列中的记录。

查看 Task Distribution - Python 参考以详细了解 TaskDistribution 类。

rg.TaskDistribution(
    min_submitted = 2
)

要了解有关如何在分配标注指南中在团队成员之间分配任务的更多信息。

列出数据集¶

您可以使用 Workspace 类的 datasets 属性列出工作区中所有可用的数据集。您还可以使用 len(workspace.datasets) 获取工作区中数据集的数量。

import argilla as rg

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

workspace = client.workspaces("my_workspace")

datasets = workspace.datasets

for dataset in datasets:
    print(dataset)

当您列出数据集时，数据集设置不会预加载，因为这可能会向服务器引入额外的请求。如果您想在列出数据集时使用设置，则需要加载它们

import argilla as rg

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

for dataset in client.datasets:
    dataset.settings.get() # this will get the dataset settings from the server
    print(dataset.settings)

Notebooks

当使用 notebook 时，执行 client.datasets 将显示一个表格，其中包含现有数据集的 name、id、它们所属的 workspace_id 以及上次更新时间 updated_at。

检索数据集¶

您可以通过调用 Argilla 类上的 datasets 方法并传递数据集的 name 或 id 作为参数来检索数据集。如果数据集不存在，将引发警告消息并返回 None。

按名称按 ID

默认情况下，此方法尝试从第一个工作区检索数据集。如果数据集位于不同的工作区中，您必须指定工作区或工作区名称作为参数。

import argilla as rg

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

# Retrieve the dataset from the first workspace
retrieved_dataset = client.datasets(name="my_dataset")

# Retrieve the dataset from the specified workspace
retrieved_dataset = client.datasets(name="my_dataset", workspace="my_workspace")

import argilla as rg

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

dataset = client.datasets(id="<uuid-or-uuid-string>")

检查数据集是否存在¶

您可以检查数据集是否存在。如果未找到数据集，client.datasets 方法将返回 None。

import argilla as rg

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

dataset = client.datasets(name="my_dataset")

if dataset is not None:
    pass

更新数据集¶

一旦数据集发布，您可以更新的内容就有限了。以下是您可以为每个设置更改的属性摘要

字段问题元数据向量指南分布

属性	来自 SDK	来自 UI
名称	❌	❌
标题	✅	✅
必需	❌	❌
使用 markdown	✅	✅
模板	✅	❌

属性	来自 SDK	来自 UI
名称	❌	❌
标题	❌	✅
描述	❌	✅
必需	❌	❌
标签	❌	❌
值	❌	❌
标签顺序	❌	✅
建议优先	❌	✅
可见标签	❌	✅
字段	❌	❌
允许重叠	❌	❌
使用 markdown	❌	✅

属性	来自 SDK	来自 UI
名称	❌	❌
标题	✅	✅
选项	❌	❌
最小值	❌	❌
最大值	❌	❌
对标注员可见	✅	✅
允许额外元数据	✅	✅

属性	来自 SDK	来自 UI
名称	❌	❌
标题	✅	✅
维度	❌	❌

来自 SDK	来自 UI
✅	✅

属性	来自 SDK	来自 UI
最少提交数	✅	✅

要修改这些属性，您只需设置您希望更改的属性的新值，然后在 Dataset 对象上调用 update 方法。

import argilla as rg

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

dataset = client.datasets("my_dataset")

dataset.settings.fields["text"].use_markdown = True
dataset.settings.metadata["my_metadata"].visible_for_annotators = False

dataset.update()

您还可以使用 add 和 delete 方法添加和删除元数据属性和向量字段。

添加删除

import argilla as rg

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

dataset = client.datasets("my_dataset")

dataset.settings.vectors.add(rg.VectorField(name="my_new_vector", dimensions=123))
dataset.settings.metadata.add(
    rg.TermsMetadataProperty(
        name="my_new_metadata",
        options=["option_1", "option_2", "option_3"],
    ),
)
dataset.update()

import argilla as rg

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

dataset = client.datasets("my_dataset")

dataset.settings.vectors["my_old_vector"].delete()
dataset.settings.metadata["my_old_metadata"].delete()

dataset.update()

删除数据集¶

您可以通过调用 Dataset 类上的 delete 方法来删除现有数据集。

import argilla as rg

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

dataset_to_delete = client.datasets(name="my_dataset")

dataset_deleted = dataset_to_delete.delete()