4.1 · 创建与管理数据集（Creating and Managing Datasets）

人工复核与反馈数据 · 聚焦本章的模块关系、源码依据与实现要点。

项目Argilla 章节4.1 状态全文译文模块检索、召回与索引、接口与服务契约、测试、发布与运维、界面与交互

项目要点页2.5 参考项目项目章节目录Argilla DeepWiki 原始章节Creating and Managing Datasets 上一章4 下一章4.2

源码线索

README.md
argilla-server/src/argilla_server/api/schemas/v1/suggestions.py
argilla-server/tests/unit/validators/test_records_bulk.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

模块标签

检索、召回与索引
接口与服务契约
测试、发布与运维
界面与交互
配置治理

章节正文

创建与管理数据集

原始 DeepWiki 页面https://deepwiki.com/argilla-io/argilla/4.1-creating-and-managing-datasets

创建和管理数据集

Argilla 中的数据集结构

Argilla 中的数据集包含以下几个关键组件，这些组件定义了数据集的结构和行为：

Argilla · Argilla 中的数据集结构 · 图 1

来源： argilla/src/argilla/datasets/_resource.py argilla/src/argilla/settings/_resource.py argilla/src/argilla/settings/_field.py argilla/src/argilla/settings/_question.py

创建数据集

创建数据集的过程包括初始化客户端、定义设置以及执行创建操作：

Argilla · 创建数据集 · 图 2

来源： argilla/docs/getting_started/quickstart.md:85-142 argilla/tests/integration/test_create_datasets.py:33-47

1. 初始化客户端

首先，连接到 Argilla 服务器：

import argilla as rg

client = rg.Argilla(
    api_url="https://[your-owner-name]-[your_space_name].hf.space",
    api_key="your_api_key"
)

2. 定义数据集设置

创建一个包含字段和问题的设置对象：

settings = rg.Settings(
    guidelines="将评论分类为正面或负面。",
    fields=[
        rg.TextField(
            name="review",
            title="评论文本",
            use_markdown=False,
        ),
    ],
    questions=[
        rg.LabelQuestion(
            name="sentiment",
            title="情感倾向",
            labels=["positive", "negative"],
        )
    ],
)

3. 创建并发布数据集

使用设置初始化数据集，并在服务器上创建它：

dataset = rg.Dataset(
    name="sentiment_analysis",
    settings=settings,
    client=client,
)
dataset.create()

来源： argilla/README.md:106-138 argilla/docs/getting_started/quickstart.md:85-142

管理数据集

检索数据集

你可以使用客户端检索数据集：

# 按名称获取特定数据集
dataset = client.datasets(name="sentiment_analysis")

# 列出所有数据集
for dataset in client.datasets:
    print(dataset.name)

更新数据集设置

数据集创建后，某些设置可以更新：

# 更新字段属性
dataset.settings.fields["review"].title = "客户评论"

# 更新指南
dataset.settings.guidelines = "新的标注指南"

# 更新任务分配
dataset.settings.distribution.min_submitted = 3

# 应用更新
dataset.update()

删除数据集

你可以按如下方式删除数据集：

dataset.delete()

来源： argilla/tests/integration/test_update_dataset_settings.py:45-97

自定义数据集设置

字段

字段定义了标注时显示的数据。Argilla 支持多种字段类型：

TextField

用于显示文本数据：

rg.TextField(
    name="text",
    title="文本字段",
    use_markdown=False,  # 是否渲染为 Markdown
    required=True,
    description="这是一个文本字段",
)

ImageField

用于显示图片：

rg.ImageField(
    name="image",
    title="图片字段",
    required=True,
    description="这是一个图片字段",
)

ChatField

用于显示聊天对话：

rg.ChatField(
    name="chat",
    title="聊天字段",
    use_markdown=True,
    required=True,
    description="这是一个聊天字段",
)

CustomField

用于显示自定义 HTML 模板：

rg.CustomField(
    name="custom",
    title="自定义字段",
    template="<div>{{field}}</div>",
    advanced_mode=False,  # 是否使用自定义 JavaScript
    required=True,
    description="这是一个自定义字段",
)

来源： argilla/src/argilla/settings/_field.py:98-279 argilla/docs/how_to_guides/custom_fields.md:9-22

问题

问题定义了要收集的标注内容。Argilla 支持多种问题类型：

LabelQuestion

用于单标签分类：

rg.LabelQuestion(
    name="label",
    title="标签问题",
    labels=["positive", "negative", "neutral"],
    required=True,
    description="这是一个标签问题",
)

MultiLabelQuestion

用于多标签分类：

rg.MultiLabelQuestion(
    name="multi_label",
    title="多标签问题",
    labels=["action", "drama", "comedy"],
    required=True,
    description="这是一个多标签问题",
)

RatingQuestion

用于按评分等级打分：

rg.RatingQuestion(
    name="rating",
    title="评分问题",
    values=[1, 2, 3, 4, 5],
    required=True,
    description="这是一个评分问题",
)

RankingQuestion

用于对选项进行排序：

rg.RankingQuestion(
    name="ranking",
    title="排序问题",
    values=["option1", "option2", "option3"],
    required=True,
    description="这是一个排序问题",
)

TextQuestion

用于自由文本回答：

rg.TextQuestion(
    name="text_question",
    title="文本问题",
    use_markdown=False,
    required=True,
    description="这是一个文本问题",
)

SpanQuestion

用于识别文本中的片段：

rg.SpanQuestion(
    name="span",
    title="片段问题",
    field="text_field",  # 要突出显示片段的字段
    labels=["Person", "Organization", "Location"],
    visible_labels=3,
    required=True,
    description="这是一个片段问题",
)

来源： argilla/src/argilla/settings/_question.py argilla/tests/unit/test_settings/test_settings.py:103-106

向量

向量支持在数据集中进行语义搜索：

rg.VectorField(
    name="text_embedding",
    dimensions=384,  # 向量的维度
    title="文本嵌入向量",
)

元数据

元数据属性有助于组织和筛选数据集：

# 用于分类元数据
rg.TermsMetadataProperty(
    name="source",
    title="来源",
    description="数据来源",
)

# 用于浮点数元数据
rg.FloatMetadataProperty(
    name="confidence",
    title="置信度",
    description="置信度分数",
)

# 用于整数元数据
rg.IntegerMetadataProperty(
    name="age",
    title="年龄",
    description="人员年龄",
)

指南

指南为标注人员提供说明：

settings = rg.Settings(
    guidelines="以下是标注指南...",
    # ...
)

你也可以从文件加载指南：

settings = rg.Settings(
    guidelines="path/to/guidelines.md",
    # ...
)

来源： argilla/src/argilla/settings/_resource.py:447-471

任务分配

任务分配定义了标注任务如何在用户之间分配：

from argilla.settings._task_distribution import TaskDistribution

# 每条记录至少需要 3 个已提交的响应
distribution = TaskDistribution(min_submitted=3)

settings = rg.Settings(
    distribution=distribution,
    # ...
)

来源： argilla/src/argilla/settings/_task_distribution.py argilla/tests/integration/test_create_datasets.py:196-208

从外部来源导入数据集

Argilla 支持从多种来源导入数据集，包括 Hugging Face Hub：

# 使用自动设置推断导入
dataset = rg.Dataset.from_hub(
    repo_id="huggingface/dataset-name",
    name="my_dataset",
    with_records=True,
    settings="auto",
)

# 使用 UI 配置导入——这会返回一个用于配置数据集的 URL
dataset_url = rg.Dataset.from_hub(
    repo_id="huggingface/dataset-name",
    with_records=True,
    settings="ui",
)

来源： argilla/src/argilla/datasets/_io/_hub.py:114-211 argilla/docs/getting_started/quickstart.md:84-104

处理数据集记录

创建数据集后，你可以向其中添加记录：

# 逐个添加记录
dataset.records.log([
    {"text": "I love this product!", "sentiment": "positive"},
    {"text": "This is terrible.", "sentiment": "negative"},
    {"text": "It's okay.", "sentiment": "neutral"},
])

# 从 Hugging Face 数据集添加记录
from datasets import load_dataset
data = load_dataset("imdb", split="train[:100]").to_list()
dataset.records.log(records=data, mapping={"text": "review"})

来源： argilla/README.md:139-142 argilla/docs/getting_started/quickstart.md:139-142

示例：创建完整的数据集

以下是一个创建情感分析数据集的完整示例：

import argilla as rg

# 初始化客户端
client = rg.Argilla(api_url="https://your-argilla-instance.com", api_key="your_api_key")

# 定义设置
settings = rg.Settings(
    guidelines="对客户评论的情感进行分类。",
    fields=[
        rg.TextField(name="review", title="客户评论"),
    ],
    questions=[
        rg.LabelQuestion(name="sentiment", title="情感倾向", labels=["positive", "negative", "neutral"]),
        rg.RatingQuestion(name="helpfulness", title="有用性", values=[1, 2, 3, 4, 5]),
    ],
    metadata=[
        rg.TermsMetadataProperty(name="source", title="来源"),
        rg.FloatMetadataProperty(name="confidence", title="置信度分数"),
    ],
    vectors=[
        rg.VectorField(name="embeddings", dimensions=384),
    ],
    distribution=rg.TaskDistribution(min_submitted=2),
)

# 创建数据集
dataset = rg.Dataset(
    name="customer_reviews",
    settings=settings,
    client=client,
)
dataset.create()

# 添加记录
dataset.records.log([
    {
        "review": "This product exceeded my expectations!",
        "sentiment": "positive",
        "helpfulness": 5,
        "metadata": {"source": "amazon", "confidence": 0.95},
    },
    {
        "review": "Disappointed with the quality.",
        "sentiment": "negative",
        "helpfulness": 2,
        "metadata": {"source": "website", "confidence": 0.85},
    },
])

print(f"已创建数据集，ID 为：{dataset.id}")

来源： argilla/tests/integration/test_create_datasets.py:33-101 argilla/tests/integration/test_create_datasets.py:148-195

常见数据集操作

向记录添加建议

建议是模型预测结果，可以帮助标注人员：

from argilla.suggestions import Suggestion

record = dataset.records[0]
record.suggestions.add(Suggestion(
    question_name="sentiment",
    value="positive",
    score=0.95,
    agent="gpt-4",
))
dataset.records.update([record])

来源： argilla/src/argilla/suggestions.py:41-65

处理响应

响应是记录的人工标注结果：

from argilla.responses import Response, ResponseStatus
from uuid import UUID

record = dataset.records[0]
record.responses.add(Response(
    question_name="sentiment",
    value="positive",
    user_id=UUID("user-uuid-here"),
    status=ResponseStatus.submitted,
))
dataset.records.update([record])

来源： argilla/src/argilla/responses.py:39-109

跟踪进度

你可以监控标注进度：

# 获取总体进度
progress = dataset.progress()
print(f"总计：{progress['total']}，已完成：{progress['completed']}")

# 获取每个用户的进度
user_progress = dataset.progress(with_users_distribution=True)
for user, stats in user_progress["users"].items():
    print(f"用户 {user}：已完成 {stats['completed']['submitted']} 条记录")

来源： argilla/src/argilla/datasets/_resource.py:191-236

最佳实践

在创建之前仔细规划数据集结构，因为某些设置在创建后无法更改。

为字段和问题使用有意义的名称，使标注界面更直观。

提供清晰的指南，确保标注结果一致。

先创建一个小型测试数据集，在创建更大数据集之前验证设置。

根据标注需求使用合适的问题类型（例如，分类使用 LabelQuestion，实体识别使用 SpanQuestion）。

根据标注质量要求适当设置任务分配。

根据需要添加向量以支持语义搜索功能。

使用元数据属性有效组织和筛选数据集。

来源：

argilla/tests/unit/test_settings/test_settings.py:28-107
argilla/docs/how_to_guides/annotate.md:4-132