添加、更新和删除记录

本指南概述了记录，解释了如何在 Argilla 中定义和管理记录的基础知识。

Argilla 中的记录是一个需要标注的数据项，由一个或多个字段组成。这些是在 UI 中向用户显示的信息片段，以方便完成标注任务。每个记录还包括标注者需要回答的问题，并可选择添加建议和回应以帮助他们。还提供了指南，以帮助标注者有效地完成其任务。

记录是数据集的一部分，因此您需要在添加记录之前创建数据集。查看本指南以了解如何创建数据集。

主要类

rg.Record(
    external_id="1234",
    fields={
        "question": "Do you need oxygen to breathe?",
        "answer": "Yes"
    },
    metadata={
        "category": "A"
    },
    vectors={
        "my_vector": [0.1, 0.2, 0.3],
    },
    suggestions=[
        rg.Suggestion("my_label", "positive", score=0.9, agent="model_name")
    ],
    responses=[
        rg.Response("label", "positive", user_id=user_id)
    ],
)

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

添加记录

您可以通过两种不同的方式向数据集添加记录：使用字典或直接初始化 Record 对象。您应确保字段、元数据和向量与数据集设置中配置的相匹配。在这两种情况下，都是通过 Dataset.records.log 方法添加的。添加记录后，这些记录将立即在 Argilla UI 中可用。如果它们未出现在 UI 中，您可能需要单击刷新按钮以更新视图。

提示

在将数据添加到数据集之前，请花一些时间检查数据，以防这触发 questions 或 fields 中的更改。

注意

如果您计划使用公共数据，Hugging Face Hub 的 Datasets 页面 是一个不错的起点。请务必检查许可证，以确保您可以合法地将其用于您的特定用例。

作为 Record 对象从通用数据结构从 Hugging Face 数据集

您可以通过直接初始化 Record 对象来向数据集添加记录。如果您需要在定义记录之前对数据应用逻辑，这非常理想。如果数据已经结构化，则应考虑直接将其作为字典或 Hugging Face 数据集添加。

import argilla as rg

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

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

records = [
    rg.Record(
        fields={
            "question": "Do you need oxygen to breathe?",
            "answer": "Yes"
        },
    ),
    rg.Record(
        fields={
            "question": "What is the boiling point of water?",
            "answer": "100 degrees Celsius"
        },
    ), # (1)
]

dataset.records.log(records)

1. 这是一个定义的说明。在实际场景中，您将迭代数据结构并为每次迭代创建 Record 对象。

您可以直接将数据添加为类似字典的结构，其中键对应于数据集中的字段、问题、元数据或向量的名称，值是要添加的数据。

如果您的数据结构与您的 Argilla 数据集名称不对应，您可以使用 mapping 来指示源数据中的哪些键对应于数据集字段、元数据、向量、建议或回应。如果您需要将相同的数据添加到多个属性，您还可以使用包含属性名称的列表。

我们用 Python 字典来说明代表您数据的情况，但我们不建议您定义字典。相反，请使用 Record 对象来实例化记录。

import argilla as rg

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

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

# Add records to the dataset with the fields 'question' and 'answer'
data = [
    {
        "question": "Do you need oxygen to breathe?",
        "answer": "Yes",
    },
    {
        "question": "What is the boiling point of water?",
        "answer": "100 degrees Celsius",
    }, # (1)
]
dataset.records.log(data)

# Add records to the dataset with a mapping of the fields 'question' and 'answer'
data = [
    {
        "query": "Do you need oxygen to breathe?",
        "response": "Yes",
    },
    {
        "query": "What is the boiling point of water?",
        "response": "100 degrees Celsius",
    },
]
dataset.records.log(data, mapping={"query": "question", "response": "answer"}) # (2)

1. 数据结构的键必须与 Argilla 数据集中的字段或问题匹配。在本例中，有名为 question 和 answer 的字段。
2. 数据结构具有键 query 和 response，而 Argilla 数据集具有字段 question 和 answer。您可以使用 mapping 参数将数据结构中的键映射到 Argilla 数据集中的字段。

您还可以使用 Hugging Face 数据集向数据集添加记录。当您想使用来自 Hugging Face Hub 的数据集并将其添加到您的 Argilla 数据集时，这非常有用。

您可以添加数据集，其中列名对应于 Argilla 数据集中字段、元数据或向量的名称。

import argilla as rg
from datasets import load_dataset

client = rg.Argilla(api_url="<api_url>", api_key="<api_key>")
dataset = client.datasets(name="my_dataset") # (1)

hf_dataset = load_dataset("imdb", split="train[:100]") # (2)

dataset.records.log(records=hf_dataset)

1. 在本例中，我们正在使用来自 Argilla 工作区的 my_dataset 数据集。该数据集具有 text 字段和 label 问题。

2. 在本例中，Hugging Face 数据集与 Argilla 数据集架构匹配。如果情况并非如此，您可以使用 datasets 库的 .map 来准备数据，然后再将其添加到 Argilla 数据集。

如果 Hugging Face 数据集的架构与您的 Argilla 数据集字段名称不对应，您可以使用 mapping 来指定关系。您应将 Hugging Face 数据集的列名指定为键，并将 Argilla 数据集的字段名称指定为值。

dataset.records.log(
    records=hf_dataset, mapping={"text": "review", "label": "sentiment"}
) # (1)

1. 在本例中，Hugging Face 数据集中的 text 键将对应于 Argilla 数据集中的 review 字段，Hugging Face 数据集中的 label 键将对应于 Argilla 数据集中的 sentiment 字段。

字段

字段是记录的主要信息片段。这些字段首先在 UI 中与问题表单一起显示。您可能只包含先前在数据集设置中配置的字段。根据数据集中包含的字段类型，数据格式可能会略有不同

文本图像聊天自定义

文本字段期望以 string 形式输入。

record = rg.Record(
    fields={"text": "Hello World, how are you?"}
)

图像字段期望以 string 形式的远程 URL 或本地图像文件路径，或 PIL 对象。

查看 Dataset.records - Python 参考 以详细了解如何添加带有图像的记录。

records = [
    rg.Record(
        fields={"image": "https://example.com/image.jpg"}
    ),
    rg.Record(
        fields={"image": "path/to/image.jpg"}
    ),
    rg.Record(
        fields={"image": Image.open("path/to/image.jpg")}
    ),
]

聊天字段期望包含键 role 和 content 的字典列表，其中 role 标识对话者类型（例如，用户、助手、模型等），而 content 包含消息的文本。

record = rg.Record(
    fields={
        "chat": [
            {"role": "user", "content": "What is Argilla?"},
            {"role": "assistant", "content": "Argilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets"},
        ]
    }
)

自定义字段期望一个字典，其中包含您在数据集设置中定义的键和值。您需要确保这些与 CustomField.template 对齐，以便在 UI 中呈现它们。

record = rg.Record(
    fields={"custom": {"key": "value"}}
)

元数据

记录元数据可以包含任何关于记录的信息，这些信息不是字段的一部分，而是以字典的形式存在。要使用元数据来过滤和排序记录，请确保字典的键与元数据属性 name 相对应。当键不对应时，这将视为额外的元数据，将与记录一起存储（只要数据集的 allow_extra_metadata 设置为 True），但不能用于过滤和排序。

注意

请记住，要在数据集内使用元数据，您必须在数据集设置中定义元数据属性。

查看 Metadata - Python 参考 以详细了解使用元数据的属性、参数和方法。

作为 Record 对象从通用数据结构

您可以将元数据添加到已初始化的 Record 对象中的记录。

# Add records to the dataset with the metadata 'category'
records = [
    rg.Record(
        fields={
            "question": "Do you need oxygen to breathe?",
            "answer": "Yes"
        },
        metadata={"my_metadata": "option_1"},
    ),
    rg.Record(
        fields={
            "question": "What is the boiling point of water?",
            "answer": "100 degrees Celsius"
        },
        metadata={"my_metadata": "option_1"},
    ),
]
dataset.records.log(records)

您可以直接将元数据作为字典结构添加到记录中，其中键对应于数据集中元数据属性的名称，值是要添加的元数据。请记住，您还可以使用 mapping 参数来指定数据结构。

# Add records to the dataset with the metadata 'category'
data = [
    {
        "question": "Do you need oxygen to breathe?",
        "answer": "Yes",
        "my_metadata": "option_1",
    },
    {
        "question": "What is the boiling point of water?",
        "answer": "100 degrees Celsius",
        "my_metadata": "option_1",
    },
]
dataset.records.log(data)

向量

您可以将向量（如文本嵌入）与您的记录关联。它们可用于 UI 和 Python SDK 中的语义搜索。请确保列表的长度与向量设置中设置的维度相对应。

注意

请记住，要在数据集内使用向量，您必须在数据集设置中定义它们。

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

作为 Record 对象从通用数据结构

您还可以将向量添加到已初始化的 Record 对象中的记录。

# Add records to the dataset with the vector 'my_vector' and dimension=3
records = [
    rg.Record(
        fields={
            "question": "Do you need oxygen to breathe?",
            "answer": "Yes"
        },
        vectors={
            "my_vector": [0.1, 0.2, 0.3]
        },
    ),
    rg.Record(
        fields={
            "question": "What is the boiling point of water?",
            "answer": "100 degrees Celsius"
        },
        vectors={
            "my_vector": [0.2, 0.5, 0.3]
        },
    ),
]
dataset.records.log(records)

您可以从类似字典的结构添加向量，其中键对应于为您的数据集配置的向量设置的 name，值是浮点数列表。请记住，您还可以使用 mapping 参数来指定数据结构。

# Add records to the dataset with the vector 'my_vector' and dimension=3
data = [
    {
        "question": "Do you need oxygen to breathe?",
        "answer": "Yes",
        "my_vector": [0.1, 0.2, 0.3],
    },
    {
        "question": "What is the boiling point of water?",
        "answer": "100 degrees Celsius",
        "my_vector": [0.2, 0.5, 0.3],
    },
]
dataset.records.log(data)

建议

建议是指您可以添加到记录中的建议回应（例如，模型预测），以加快标注过程。这些可以在创建记录期间或稍后阶段添加。每个问题只能提供一个建议，并且建议值必须符合预定义的问题，例如，如果我们有一个介于 1 到 5 之间的 RatingQuestion，则建议应具有该范围内的有效值。

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

提示

查看 Suggestions - Python 参考 以了解每种 Question 类型的不同格式。

作为 Record 对象从通用数据结构

您还可以将建议添加到已初始化的 Record 对象中的记录。

# Add records to the dataset with the label 'my_label'
records = [
    rg.Record(
        fields={
            "question": "Do you need oxygen to breathe?",
            "answer": "Yes"
        },
        suggestions=[
            rg.Suggestion(
                "my_label",
                "positive",
                score=0.9,
                agent="model_name"
            )
        ],
    ),
    rg.Record(
        fields={
            "question": "What is the boiling point of water?",
            "answer": "100 degrees Celsius"
        },
        suggestions=[
            rg.Suggestion(
                "my_label",
                "negative",
                score=0.9,
                agent="model_name"
            )
        ],
    ),
]
dataset.records.log(records)

您可以将建议添加为字典，其中键对应于为您的数据集配置的标签的 name。请记住，您还可以使用 mapping 参数来指定数据结构。

# Add records to the dataset with the label question 'my_label'
data =  [
    {
        "question": "Do you need oxygen to breathe?",
        "answer": "Yes",
        "label": "positive",
        "score": 0.9,
        "agent": "model_name",
    },
    {
        "question": "What is the boiling point of water?",
        "answer": "100 degrees Celsius",
        "label": "negative",
        "score": 0.9,
        "agent": "model_name",
    },
]
dataset.records.log(
    data=data,
    mapping={
        "label": "my_label",
        "score": "my_label.suggestion.score",
        "agent": "my_label.suggestion.agent",
    },
)

回应

如果您的数据集包含一些标注，您可以在创建记录时将这些标注添加到记录中。确保回应符合与 Argilla 输出相同的格式，并满足所回答的特定问题类型的架构要求。如果您计划为同一问题添加多个回应，请务必包含 user_id，否则回应将应用于所有标注者。

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

注意

请记住，带有回应的记录将在 UI 中显示为“草稿”。

提示

查看 Responses - Python 参考 以了解每种 Question 类型的不同格式。

作为 Record 对象从通用数据结构

您还可以将建议添加到已初始化的 Record 对象中的记录。

# Add records to the dataset with the label 'my_label'
records = [
    rg.Record(
        fields={
            "question": "Do you need oxygen to breathe?",
            "answer": "Yes"
        },
        responses=[
            rg.Response("my_label", "positive", user_id=user.id)
        ]
    ),
    rg.Record(
        fields={
            "question": "What is the boiling point of water?",
            "answer": "100 degrees Celsius"
        },
        responses=[
            rg.Response("my_label", "negative", user_id=user.id)
        ]
    ),
]
dataset.records.log(records)

您可以将建议添加为字典，其中键对应于为您的数据集配置的标签的 name。请记住，您还可以使用 mapping 参数来指定数据结构。如果您想指定添加回应的用户，可以使用 user_id 参数。

# Add records to the dataset with the label 'my_label'
data = [
    {
        "question": "Do you need oxygen to breathe?",
        "answer": "Yes",
        "label": "positive",
    },
    {
        "question": "What is the boiling point of water?",
        "answer": "100 degrees Celsius",
        "label": "negative",
    },
]
dataset.records.log(data, user_id=user.id, mapping={"label": "my_label.response"})

列出记录

要列出数据集中的记录，您可以使用 Dataset 对象上的 records 方法。此方法返回一个 Record 对象列表，可以迭代该列表以访问记录属性。

for record in dataset.records(
    with_suggestions=True,
    with_responses=True,
    with_vectors=True
):

    # Access the record properties
    print(record.metadata)
    print(record.vectors)
    print(record.suggestions)
    print(record.responses)

    # Access the responses of the record
    for response in record.responses:
        print(response.value)

更新记录

您可以通过在 Dataset 对象上调用 log 方法来更新数据集中的记录。要更新记录，您需要提供记录 id 和要更新的新数据。

data = dataset.records.to_list(flatten=True)

updated_data = [
    {
        "text": sample["text"],
        "label": "positive",
        "id": sample["id"],
    }
    for sample in data
]
dataset.records.log(records=updated_data)

更新元数据更新向量更新建议更新回应

Record 对象的 metadata 是一个 Python 字典。要更新它，您可以迭代记录并通过键更新元数据。之后，您应该更新数据集中的记录。

提示

查看 Metadata - Python 参考 以了解每种 MetadataProperty 类型的不同格式。

updated_records = []

for record in dataset.records():

    record.metadata["my_metadata"] = "new_value"
    record.metadata["my_new_metadata"] = "new_value"

    updated_records.append(record)

dataset.records.log(records=updated_records)

如果向数据集设置添加了新的向量字段，或者必须更新现有记录向量的某些值，您可以迭代记录并通过键更新向量。之后，您应该更新数据集中的记录。

updated_records = []

for record in dataset.records(with_vectors=True):

    record.vectors["my_vector"] = [ 0, 1, 2, 3, 4, 5 ]
    record.vectors["my_new_vector"] = [ 0, 1, 2, 3, 4, 5 ]

    updated_records.append(record)

dataset.records.log(records=updated_records)

如果必须更新现有记录建议的某些值，您可以迭代记录并通过键更新建议。您还可以使用 add 方法添加建议。之后，您应该更新数据集中的记录。

提示

查看 Suggestions - Python 参考 以了解每种 Question 类型的不同格式。

updated_records = []

for record in dataset.records(with_suggestions=True):

    # We can update existing suggestions
    record.suggestions["label"].value = "new_value"
    record.suggestions["label"].score = 0.9
    record.suggestions["label"].agent = "model_name"

    # We can also add new suggestions with the `add` method:
    if not record.suggestions["label"]:
        record.suggestions.add(
            rg.Suggestion("value", "label", score=0.9, agent="model_name")
        )

    updated_records.append(record)

dataset.records.log(records=updated_records)

如果必须更新现有记录回应的某些值，您可以迭代记录并通过键更新回应。您还可以使用 add 方法添加回应。之后，您应该更新数据集中的记录。

提示

查看 Responses - Python 参考 以了解每种 Question 类型的不同格式。

updated_records = []

for record in dataset.records(with_responses=True):

    for response in record.responses["label"]:

        if response:
                response.value = "new_value"
                response.user_id = "existing_user_id"

        else:
            record.responses.add(rg.Response("label", "YES", user_id=user.id))

    updated_records.append(record)

dataset.records.log(records=updated_records)

删除记录

您可以通过在 Dataset 对象上调用 delete 方法来删除数据集中的记录。要删除记录，您需要从服务器检索它们，并获取包含您要删除的记录的列表。

records_to_delete = list(dataset.records)[:5]
dataset.records.delete(records=records_to_delete)

根据查询删除记录

避免删除带有回应的记录可能非常有用。

有关查询语法的更多信息，请查看此操作指南。

status_filter = rg.Query(
    filter = rg.Filter(("response.status", "==", "pending"))
)
records_to_delete = list(dataset.records(status_filter))

dataset.records.delete(records_to_delete)