3 · 数据模型（Data Model）

数据模型

数据模型

相关源文件

本章引用的主要源码文件：

• README.md
• argilla-server/src/argilla_server/alembic/versions/580a6553186f_add_datasets_users_table.py
• argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.py
• argilla-server/src/argilla_server/api/schemas/v1/datasets.py
• argilla-server/src/argilla_server/bulk/records_bulk.py
• argilla-server/src/argilla_server/contexts/datasets.py
• argilla-server/src/argilla_server/database.py
• argilla-server/src/argilla_server/models/database.py
• argilla-server/tests/factories.py
• argilla-server/tests/unit/api/handlers/v1/datasets/records/records_bulk/test_create_dataset_records_bulk.py
• argilla-server/tests/unit/api/handlers/v1/datasets/records/records_bulk/test_dataset_records_bulk_with_responses.py
• argilla-server/tests/unit/api/handlers/v1/datasets/test_get_dataset_progress.py
• argilla-server/tests/unit/api/handlers/v1/responses/test_create_current_user_responses_bulk.py
• argilla-server/tests/unit/api/handlers/v1/test_datasets.py
• argilla-server/tests/unit/api/handlers/v1/test_records.py
• argilla-server/tests/unit/database/models/test_dataset_user_model.py
• argilla-server/tests/unit/test_database.py
• argilla-server/tests/unit/validators/test_records_bulk.py
• argilla/docs/reference/argilla/settings/settings.md
• argilla/docs/reference/argilla/settings/task_distribution.md
• argilla/src/argilla/_exceptions/__init__.py
• argilla/src/argilla/_exceptions/_hub.py
• argilla/src/argilla/_exceptions/_responses.py
• argilla/src/argilla/_exceptions/_suggestions.py
• argilla/src/argilla/datasets/_io/_disk.py
• argilla/src/argilla/datasets/_io/_hub.py
• argilla/src/argilla/datasets/_resource.py
• argilla/src/argilla/responses.py
• argilla/src/argilla/settings/_common.py
• argilla/src/argilla/settings/_field.py
• argilla/src/argilla/settings/_io/_hub.py
• argilla/src/argilla/settings/_resource.py
• argilla/src/argilla/settings/_task_distribution.py
• argilla/src/argilla/suggestions.py
• argilla/tests/integration/test_create_datasets.py
• argilla/tests/integration/test_import_features.py
• argilla/tests/integration/test_update_dataset_settings.py
• argilla/tests/unit/test_resources/test_datasets.py
• argilla/tests/unit/test_resources/test_responses.py
• argilla/tests/unit/test_settings/test_settings.py
• argilla/tests/unit/test_settings/test_settings_from_features.py
• argilla/tests/unit/test_settings/test_settings_mapping_record_ingestion.py

本文档解释了 Argilla 中的核心数据结构、它们之间的相互关系，以及它们在服务端和客户端组件中的表示方式。理解此数据模型对于有效使用 Argilla（无论是创建自定义集成还是扩展平台）至关重要。

关于创建和管理数据集的信息，请参阅创建和管理数据集。有关标注工作流的详细信息，请参阅标注工作流。

数据模型概览

Argilla 的数据模型围绕几个核心实体构建，这些实体协同工作以支持数据标注工作流：

来源： argilla-server/src/argilla_server/models/database.py:414-606 argilla-server/src/argilla_server/models/database.py:73-111 argilla-server/src/argilla_server/models/database.py:219-270 argilla-server/src/argilla_server/models/database.py:273-334 argilla-server/src/argilla_server/models/database.py:117-140 argilla-server/src/argilla_server/models/database.py:145-166 argilla-server/src/argilla_server/models/database.py:169-188 argilla-server/src/argilla_server/models/database.py:191-213 argilla-server/src/argilla_server/models/database.py:337-382

核心实体

数据集（数据集）

Dataset 是 Argilla 数据模型的核心。数据集充当记录（Record）、字段（Field）、问题（Question）和其他配置元素的容器。

关键属性：

• id：唯一标识符
• name：人类可读的名称
• guidelines：给标注人员的指导说明
• allow_extra_metadata：是否允许超出已定义属性的额外元数据
• status：草稿或就绪（已发布）
• distribution：标注任务如何分配的设置
• workspace_id：拥有此数据集的工作空间

来源： argilla-server/src/argilla_server/models/database.py:414-606 argilla/src/argilla/datasets/_resource.py:37-288

设置（设置）

Settings 类定义了数据集的配置，包括字段、问题、指导说明等。这主要是一个客户端类，用于指定数据集的结构。

来源： argilla/src/argilla/settings/_resource.py:40-470 argilla/src/argilla/settings/_resource.py:477-569

记录（记录）

Record 代表数据集中的一个数据点。记录包含字段的值、元数据，并与响应（标注）和建议（模型预测）相关联。

关键属性：

• id：唯一标识符
• fields：字段值的字典
• metadata_：元数据值的字典
• status：记录的状态（待处理或已完成）
• external_id：可选的外部标识符
• dataset_id：此记录所属数据集的 ID

来源： argilla-server/src/argilla_server/models/database.py:219-270

字段（字段）

字段定义了记录中数据的结构。Argilla 支持以下几种字段类型：

• TextField：用于文本内容
• ImageField：用于图像内容（URL 或 data URI）
• ChatField：用于对话数据
• CustomField：用于自定义 HTML/CSS 模板

每种字段类型都有特定的设置来控制其行为和外观。

来源： argilla/src/argilla/settings/_field.py:45-283 argilla-server/src/argilla_server/models/database.py:73-111

问题项（问题）

问题定义了标注任务。Argilla 支持多种问题类型：

• LabelQuestion：用于单标签分类
• MultiLabelQuestion：用于多标签分类
• RatingQuestion：用于数值评分
• RankingQuestion：用于对选项进行排序
• TextQuestion：用于自由文本回复
• SpanQuestion：用于文本片段高亮

与字段类似，每种问题类型都有特定的设置。

来源： argilla-server/src/argilla_server/models/database.py:273-334

响应（响应）

响应是用户创建的标注。每个响应对应特定记录上的特定问题。

关键属性：

• values：响应值的字典
• status：可以是已提交、草稿或已废弃
• record_id：被标注记录的 ID
• user_id：创建响应的用户的 ID

来源： argilla-server/src/argilla_server/models/database.py:117-140 argilla/src/argilla/responses.py:39-105

Suggestions（建议）

建议是针对问题的预计算答案，通常来自模型。它们可以帮助指导标注人员。

关键属性：

• value：建议的答案
• score：建议的置信度分数（可以是单个值或列表）
• agent：标识创建此建议的来源
• type：建议的类型（模型或人工）
• record_id：相关记录的 ID
• question_id：相关问题的 ID

来源： argilla-server/src/argilla_server/models/database.py:145-166 argilla/src/argilla/suggestions.py:27-45

向量（向量）

向量存储记录的嵌入向量，可用于语义搜索或聚类。

关键属性：

• value：向量值的数组
• record_id：相关记录的 ID
• vector_settings_id：相关向量设置的 ID

来源： argilla-server/src/argilla_server/models/database.py:169-188

VectorSettings（向量设置）

VectorSettings 定义了数据集中向量的配置。

关键属性：

• name：向量设置的名称
• title：显示标题
• dimensions：向量的维度数
• dataset_id：数据集的 ID

来源： argilla-server/src/argilla_server/models/database.py:191-213

MetadataProperty（元数据属性）

MetadataProperties 定义了记录的附加属性。类型包括术语（分类）、整数和浮点数。

关键属性：

• name：属性名称
• title：显示标题
• settings：配置设置
• allowed_roles：可以查看此属性的用户角色
• dataset_id：数据集的 ID

来源： argilla-server/src/argilla_server/models/database.py:337-382

数据流

下图展示了 Argilla 中从数据集创建到标注和导出的典型数据流：

来源： argilla-server/src/argilla_server/contexts/datasets.py:80-170 argilla-server/src/argilla_server/bulk/records_bulk.py:47-244 argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.py:75-363

TaskDistribution（任务分配）

TaskDistribution 类控制标注任务如何在标注人员之间分配。目前，Argilla 支持重叠（overlap）策略，即多个标注人员可以处理同一条记录。

关键属性：

• strategy：分配策略（目前仅支持 "overlap"）
• min_submitted：将记录标记为“已完成”所需的最少已提交响应数

来源： argilla-server/src/argilla_server/api/schemas/v1/datasets.py:49-72

数据库模式

Argilla 使用 SQLAlchemy 配合 PostgreSQL 或 SQLite 作为数据库后端。数据库模式直接映射了上述实体关系。

来源： argilla-server/src/argilla_server/database.py:64-97 argilla-server/src/argilla_server/alembic/versions/580a6553186f_add_datasets_users_table.py:1-35

客户端-服务端表示

Argilla 在客户端和服务端都维护了数据模型的表示：

来源： argilla/src/argilla/datasets/_resource.py:37-288 argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.py:75-363

示例：使用设置创建数据集

以下示例展示了创建数据集时数据模型是如何协同工作的：

import argilla as rg

# 创建包含字段和问题的设置
settings = rg.Settings(
    fields=[
        rg.TextField(name="text", title="文本内容"),
        rg.ImageField(name="image", title="图片", required=False)
    ],
    questions=[
        rg.LabelQuestion(name="sentiment", title="情感倾向",
                        labels=["正面", "负面", "中性"]),
        rg.RatingQuestion(name="quality", title="质量评分",
                         values=[1, 2, 3, 4, 5])
    ],
    guidelines="请标注情感倾向并评价内容质量。"
)

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

# 写入记录
dataset.records.log([
    {"text": "我非常喜欢这个产品！", "image": "https://example.com/image1.jpg"},
    {"text": "与我的预期不符", "image": "https://example.com/image2.jpg"}
])

当此代码运行时：

1. SDK 创建一个包含字段和问题的 Settings 对象
2. 通过 API 使用这些设置创建 Dataset
3. 创建记录并将其添加到数据集中
4. 服务端根据设置验证记录
5. 记录被存储在数据库中并建立索引

来源： argilla/src/argilla/settings/_resource.py:196-216 argilla/src/argilla/datasets/_resource.py:153-181 argilla-server/src/argilla_server/bulk/records_bulk.py:52-78

标注过程中的数据模型流

此图展示了在标注生命周期中数据如何在系统中流动。

来源： argilla-server/src/argilla_server/contexts/datasets.py:480-457 argilla-server/src/argilla_server/contexts/datasets.py:480-597

记录状态流

Argilla 中的记录和响应遵循特定的状态流转：

来源： argilla-server/src/argilla_server/models/database.py:224-226 argilla-server/src/argilla_server/models/database.py:121-122 argilla/src/argilla/responses.py:31-37

存储层详情

Argilla 的数据模型通过以下方式实现：

1. 数据库存储：通过 SQLAlchemy 使用 PostgreSQL 或 SQLite 存储结构化数据
2. 搜索引擎：使用 Elasticsearch/OpenSearch 进行搜索、过滤和向量相似度计算
3. Redis 队列：用于后台任务，如状态更新和批量操作

来源： argilla-server/src/argilla_server/database.py:30-97

DatasetUser 追踪

Argilla 使用一个特殊的关联表来追踪哪些用户标注了哪些数据集：

这允许追踪哪些用户在哪些数据集上工作过，并支持诸如按数据集统计用户进度等功能。

来源： argilla-server/src/argilla_server/models/database.py:392-413 argilla-server/src/argilla_server/contexts/datasets.py:425-438

总结

Argilla 的数据模型提供了一个灵活、全面的系统，用于管理数据集、记录和标注。核心实体（Dataset、Record、Field、Question、Response、Suggestion、Vector）及其关系支持了广泛的标注工作流。

客户端和服务端表示的分离，使得在保持清晰 API 的同时，能够在服务端执行所有必要的验证和数据完整性检查。向量、元数据属性和建议等功能的加入，将模型从基本的标注扩展到了支持高级 AI 工作流。