3.1 · 数据集与设置（Datasets and Settings）

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

项目Argilla 章节3.1 状态全文译文模块检索、召回与索引、测试、发布与运维、工作流与编排、接口与服务契约

项目要点页2.5 参考项目项目章节目录Argilla DeepWiki 原始章节Datasets and Settings 上一章3 下一章3.2

源码线索

README.md
argilla-server/tests/unit/validators/test_records_bulk.py
argilla/docs/community/adding_language.md
argilla/docs/how_to_guides/dataset.md
argilla/docs/how_to_guides/import_export.md
argilla/docs/how_to_guides/index.md
argilla/docs/how_to_guides/record.md
argilla/docs/reference/argilla/datasets/dataset_records.md
argilla/docs/reference/argilla/records/metadata.md
argilla/docs/reference/argilla/records/records.md

模块标签

检索、召回与索引
测试、发布与运维
工作流与编排
接口与服务契约
界面与交互

章节正文

数据集与设置

原始 DeepWiki 页面https://deepwiki.com/argilla-io/argilla/3.1-datasets-and-settings

数据集与设置

用途与组件

数据集和设置组件构成了 Argilla 数据标注系统的基础：

数据集：用户可以标注的记录集合
设置：定义数据集结构的配置，包括字段（显示什么）、问题（问什么）、元数据属性、用于语义搜索的向量、指南以及标注任务分配

它们共同提供了一种灵活的方式来为各种标注任务（如文本分类、命名实体识别（NER）、图像标注等）构建数据。

来源：argilla/src/argilla/datasets/_resource.py:36-149，argilla/src/argilla/settings/_resource.py:40-147

数据集类

Dataset 类是在 Argilla 中处理记录集合的主要接口。它提供了创建、更新和删除数据集以及导入/导出数据的方法。

dataset = rg.Dataset(
    name="my_dataset",       # 唯一名称标识符
    workspace="workspace",   # 创建数据集的工作空间
    settings=settings,       # 数据集配置
    client=client            # 可选的 Argilla 客户端
)
dataset.create()            # 将数据集持久化到服务器

关键属性：

name：数据集的字符串标识符
id：创建后数据集的 UUID
workspace：数据集所属的工作空间
settings：数据集配置对象
records：添加、更新和访问记录的接口
schema：来自字段、问题等的组合模式信息

关键方法：

create()：在服务器上创建数据集
update()：在服务器上更新配置
get()：从服务器刷新数据
delete()：删除数据集
progress()：获取标注进度统计信息
to_hub()：导出到 Hugging Face Hub
from_hub()：从 Hugging Face Hub 导入
to_disk()：导出到本地文件系统
from_disk()：从本地文件系统导入

来源：argilla/src/argilla/datasets/_resource.py:37-289，argilla/docs/how_to_guides/dataset.md:16-45

设置类

Settings 类定义了数据集的结构，包括显示哪些数据以及询问哪些问题。它通过 SettingsProperties 辅助类管理多个属性集合。

settings = rg.Settings(
    guidelines="标注者指南",
    fields=[rg.TextField(name="text")],
    questions=[rg.LabelQuestion(name="sentiment", labels=["positive", "negative"])],
    metadata=[rg.TermsMetadataProperty(name="source", options=["web", "news"])],
    vectors=[rg.VectorField(name="embeddings", dimensions=768)],
    allow_extra_metadata=False,
    distribution=rg.TaskDistribution(min_submitted=2)
)

关键属性：

fields：字段集合（显示什么）
questions：问题集合（问什么）
metadata：元数据属性集合（用于过滤）
vectors：向量字段集合（用于相似性搜索）
guidelines：标注者说明
allow_extra_metadata：是否允许未声明的元数据
distribution：标注任务分配的配置
schema：按名称组织的所有数据集组件的字典

关键方法：

validate()：验证设置的正确性
create()：在服务器上创建设置
update()：在服务器上更新设置
get()：从服务器刷新设置
to_json()：将设置导出到 JSON 文件
from_json()：从 JSON 文件导入设置
from_hub()：从 Hugging Face Hub 导入设置
add()：向设置添加属性

来源：argilla/src/argilla/settings/_resource.py:40-470，argilla/docs/how_to_guides/dataset.md:52-147

字段

字段定义了向标注者显示哪些数据。所有字段类型都继承自抽象类 FieldBase，并包含以下选项：

字段类型	描述	属性
`TextField`	纯文本或 Markdown	`use_markdown`：启用 Markdown 格式
`ImageField`	图像（URL、文件路径或 PIL 对象）	-
`ChatField`	结构化的对话消息	`use_markdown`：在消息中启用 Markdown
`CustomField`	自定义 HTML/CSS 模板	`template`：HTML 内容<br>`advanced_mode`：启用 JavaScript

所有字段都有公共属性：

name：字段的唯一标识符
title：显示标题（默认为名称）
required：字段是否为必填
description：附加字段描述

示例：

rg.TextField(
    name="review",
    title="客户评论",
    use_markdown=True,
    required=True,
    description="客户的评论文本"
)

来源：argilla/src/argilla/settings/_field.py:45-301，argilla/docs/how_to_guides/dataset.md:148-211

问题

问题定义了从标注者那里收集哪些反馈。所有问题类型都继承自抽象类 QuestionBase，并包含：

问题类型	描述	关键属性
`LabelQuestion`	单标签选择	`labels`：可用选项
`MultiLabelQuestion`	多标签选择	`labels`：可用选项
`RatingQuestion`	数值评分	`values`：可能值的列表
`RankingQuestion`	按偏好排序项目	`values`：待排序的项目
`TextQuestion`	自由文本响应	`use_markdown`：启用 Markdown
`SpanQuestion`	文本跨度选择	`field`：要标注的文本字段<br>`labels`：跨度类别

所有问题都有公共属性：

name：唯一标识符
title：显示标题
required：答案是否为必填
description：附加说明

示例：

rg.LabelQuestion(
    name="sentiment",
    title="评论情感",
    labels=["positive", "negative", "neutral"],
    required=True,
    description="选择评论中表达的情感"
)

来源：argilla/docs/how_to_guides/dataset.md:214-327

元数据属性

元数据属性定义了可用于过滤和搜索的附加记录信息。可用类型：

元数据类型	描述	属性
`TermsMetadataProperty`	字符串选项	`options`：允许的术语列表
`IntegerMetadataProperty`	整数值	`min`，`max`：范围约束
`FloatMetadataProperty`	浮点数值	`min`，`max`：范围约束

所有元数据属性都包含：

name：唯一标识符
title：显示标题
visible_for_annotators：是否在 UI 中可见

示例：

rg.TermsMetadataProperty(
    name="category",
    title="产品类别",
    options=["electronics", "clothing", "home"],
    visible_for_annotators=True
)

来源：argilla/docs/how_to_guides/dataset.md:329-376

向量

向量字段支持数据集中的相似性搜索。定义方式如下：

rg.VectorField(
    name="embeddings",
    title="文本嵌入向量",
    dimensions=768
)

属性：

name：唯一标识符
title：显示标题
dimensions：向量大小（必须与记录向量匹配）

来源：argilla/docs/how_to_guides/dataset.md:377-391

指南与任务分配

指南

指南为标注者提供说明。可以通过两种方式指定：

数据集级别的指南，显示在标注界面顶部
每个问题的描述，显示在工具提示中

指南可以作为字符串提供，也可以从文件加载：

guidelines = "标注者说明..."
# 或
guidelines = "/path/to/guidelines.md"  # 文件将被加载

任务分配

任务分配配置了标注工作如何在标注者之间分配：

rg.TaskDistribution(min_submitted=2)

min_submitted 参数指定每条记录应由多少个不同的标注者提交响应，从而实现基于共识的标注。

来源：argilla/docs/how_to_guides/dataset.md:392-426，argilla/src/argilla/settings/_task_distribution.py

数据集与设置关系图

下图展示了数据集、设置及其组件之间的核心类关系：

Argilla · 数据集与设置关系图 · 图 1

来源：argilla/src/argilla/datasets/_resource.py:36-289，argilla/src/argilla/settings/_resource.py:40-570

创建和使用数据集的工作流

下图展示了创建和使用数据集的典型工作流：

Argilla · 创建和使用数据集的工作流 · 图 2

来源：argilla/src/argilla/datasets/_resource.py:149-211，argilla/src/argilla/settings/_resource.py:196-229，argilla/docs/how_to_guides/dataset.md:51-86

导入与导出

Argilla 提供了多种导入和导出数据集的方法：

Hugging Face Hub

# 导出到 Hub
dataset.to_hub(
    repo_id="organization/dataset-name",
    with_records=True,  # 在导出中包含记录
    generate_card=True  # 创建数据集卡片
)

# 从 Hub 导入
rg.Dataset.from_hub(
    repo_id="organization/dataset-name",
    name="my_local_name",  # 可选的自定义名称
    workspace="my_workspace",
    with_records=True
)

本地磁盘

# 导出到磁盘
dataset.to_disk(
    path="/path/to/directory",
    with_records=True
)

# 从磁盘导入
rg.Dataset.from_disk(
    path="/path/to/directory",
    name="my_dataset",
    workspace="my_workspace",
    with_records=True
)

数据集的配置和记录以结构化格式保存，可以稍后重新加载或与他人共享。

来源：argilla/docs/how_to_guides/import_export.md:11-128，argilla/src/argilla/datasets/_io/_hub.py:43-358，argilla/src/argilla/datasets/_io/_disk.py:33-201

内置模板

除了手动配置设置外，您还可以使用针对常见用例的内置模板：

# 文本分类模板
settings = rg.Settings.for_text_classification(
    guidelines="对这些评论进行情感分类",
    labels=["positive", "negative", "neutral"]
)

# 文本排序模板
settings = rg.Settings.for_text_ranking(
    guidelines="按质量对这些响应进行排序",
    num_texts=4  # 要排序的文本数量
)

# 图像分类模板
settings = rg.Settings.for_image_classification(
    guidelines="对这些图像进行分类",
    labels=["cat", "dog", "other"]
)

这些模板提供了合理的默认值，同时仍然允许自定义。

来源：argilla/docs/how_to_guides/dataset.md:143-144，argilla/docs/reference/argilla/settings/settings.md:102-166