3 · 数据模型（Data Model）

数据模型（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/argilla-io/argilla/3-data-model

翻译时间：2026-05-27T08:44:49.856Z

翻译模型：deepseek-chat

原文字符数：24511

项目：Argilla (argilla)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，对这份 DeepWiki 技术文档进行全文翻译和润色。

---

数据模型

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• 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 的数据模型围绕几个核心实体构建，这些实体协同工作以支持数据标注工作流：

classDiagram
    class "Dataset" {
        +id: UUID
        +name: string
        +guidelines: string
        +status: DatasetStatus
        +distribution: dict
        +workspace_id: UUID
    }

    class "Record" {
        +id: UUID
        +fields: dict
        +metadata: dict
        +status: RecordStatus
        +external_id: string
        +dataset_id: UUID
    }

    class "Field" {
        +id: UUID
        +name: string
        +title: string
        +required: boolean
        +settings: dict
        +dataset_id: UUID
    }

    class "Question" {
        +id: UUID
        +name: string
        +title: string
        +description: string
        +required: boolean
        +settings: dict
        +dataset_id: UUID
    }

    class "Response" {
        +id: UUID
        +values: dict
        +status: ResponseStatus
        +record_id: UUID
        +user_id: UUID
    }

    class "Suggestion" {
        +id: UUID
        +value: any
        +score: float/list
        +agent: string
        +type: SuggestionType
        +record_id: UUID
        +question_id: UUID
    }

    class "Vector" {
        +id: UUID
        +value: list
        +record_id: UUID
        +vector_settings_id: UUID
    }

    class "VectorSettings" {
        +id: UUID
        +name: string
        +title: string
        +dimensions: int
        +dataset_id: UUID
    }

    class "MetadataProperty" {
        +id: UUID
        +name: string
        +title: string
        +settings: dict
        +allowed_roles: list
        +dataset_id: UUID
    }

    "Dataset" "1" *-- "*" "Record"
    "Dataset" "1" *-- "*" "Field"
    "Dataset" "1" *-- "*" "Question"
    "Dataset" "1" *-- "*" "MetadataProperty"
    "Dataset" "1" *-- "*" "VectorSettings"
    "Record" "1" *-- "*" "Response"
    "Record" "1" *-- "*" "Suggestion"
    "Record" "1" *-- "*" "Vector"
    "Question" "1" <-- "*" "Suggestion"
    "VectorSettings" "1" <-- "*" "Vector"

来源：

• 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 类定义了数据集的配置，包括字段、问题、指导说明等。这主要是一个客户端类，用于指定数据集的结构。

classDiagram
    class "Settings" {
        +fields: SettingsProperties[Field]
        +questions: SettingsProperties[Question]
        +vectors: SettingsProperties[VectorField]
        +metadata: SettingsProperties[MetadataProperty]
        +guidelines: string
        +allow_extra_metadata: boolean
        +distribution: TaskDistribution
        +schema: dict
    }

    class "SettingsProperties" {
        +add(property)
        +remove(property)
        +__getitem__(key)
        +__iter__()
        +serialize()
    }

    class "Field" {
        <<abstract>>
        +name: string
        +title: string
        +required: boolean
    }

    class "Question" {
        <<abstract>>
        +name: string
        +title: string
        +required: boolean
    }

    class "TaskDistribution" {
        +strategy: string
        +min_submitted: int
    }

    "Settings" *-- "1" "SettingsProperties"
    "SettingsProperties" *-- "*" "Field"
    "SettingsProperties" *-- "*" "Question"
    "Settings" *-- "1" "TaskDistribution"

    "Field" <|-- "TextField"
    "Field" <|-- "ImageField"
    "Field" <|-- "ChatField"
    "Field" <|-- "CustomField"

    "Question" <|-- "LabelQuestion"
    "Question" <|-- "MultiLabelQuestion"
    "Question" <|-- "RatingQuestion"
    "Question" <|-- "RankingQuestion"
    "Question" <|-- "TextQuestion"
    "Question" <|-- "SpanQuestion"

来源：

• 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 中从数据集创建到标注和导出的典型数据流：

sequenceDiagram
    participant "Client" as C
    participant "Argilla SDK" as SDK
    participant "Argilla Server" as S
    participant "Database" as DB
    participant "Search Engine" as SE

    C->>SDK: 创建包含字段和问题的 Settings
    SDK->>S: POST /api/v1/datasets
    S->>DB: 存储数据集配置
    S-->>SDK: 返回数据集 ID

    C->>SDK: 向数据集写入记录
    SDK->>S: POST /api/v1/datasets/{id}/records/bulk
    S->>DB: 存储记录
    S->>SE: 索引记录

    C->>S: 访问 UI 进行标注
    S->>DB: 获取待标注记录
    S->>SE: 搜索/过滤记录
    S-->>C: 展示记录

    C->>S: 提交响应
    S->>DB: 存储响应
    S->>SE: 更新记录状态

    C->>SDK: 导出已标注数据
    SDK->>S: GET 获取包含响应的记录
    S->>DB: 检索记录和响应
    S-->>SDK: 返回数据
    SDK-->>C: 格式化数据

来源：

• 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 作为数据库后端。数据库模式直接映射了上述实体关系。

erDiagram
    DATASETS ||--o{ RECORDS : 包含
    DATASETS ||--o{ FIELDS : 定义
    DATASETS ||--o{ QUESTIONS : 包含
    DATASETS ||--o{ METADATA_PROPERTIES : 拥有
    DATASETS ||--o{ VECTORS_SETTINGS : 配置

    RECORDS ||--o{ RESPONSES : 接收
    RECORDS ||--o{ SUGGESTIONS : 拥有
    RECORDS ||--o{ VECTORS : 嵌入

    QUESTIONS ||--o{ SUGGESTIONS : 提供
    VECTORS_SETTINGS ||--o{ VECTORS : 格式化

    USERS ||--o{ RESPONSES : 创建
    DATASETS_USERS }|--|| DATASETS : 追踪
    DATASETS_USERS }|--|| USERS : 记录

    DATASETS {
        UUID id PK
        string name
        text guidelines
        boolean allow_extra_metadata
        enum status
        dict distribution
        UUID workspace_id FK
        datetime last_activity_at
    }

    RECORDS {
        UUID id PK
        dict fields
        dict metadata
        enum status
        string external_id
        UUID dataset_id FK
    }

    FIELDS {
        UUID id PK
        string name
        text title
        boolean required
        dict settings
        UUID dataset_id FK
    }

    QUESTIONS {
        UUID id PK
        string name
        text title
        text description
        boolean required
        dict settings
        UUID dataset_id FK
    }

来源：

• 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 在客户端和服务端都维护了数据模型的表示：

flowchart TB
    subgraph "客户端（Python SDK）"
        CDataset["Dataset"]
        CSettings["Settings"]
        CRecords["Records Collection"]
        CRecord["Record"]
        CResponse["Response"]
        CSuggestion["Suggestion"]
    end

    subgraph "API 通信"
        API["HTTP REST API"]
    end

    subgraph "服务端（FastAPI）"
        SDataset["Dataset Model"]
        SField["Field Model"]
        SQuestion["Question Model"]
        SRecord["Record Model"]
        SResponse["Response Model"]
        SSuggestion["Suggestion Model"]
        SVector["Vector Model"]
        SContext["Dataset Context"]
        SBulk["Records Bulk"]
    end

    CDataset --> API
    CSettings --> API
    CRecords --> API
    CRecord --> API
    CResponse --> API
    CSuggestion --> API

    API --> SDataset
    API --> SField
    API --> SQuestion
    API --> SRecord
    API --> SResponse
    API --> SSuggestion
    API --> SVector
    API --> SContext
    API --> SBulk

来源：

• 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

标注过程中的数据模型流

stateDiagram-v2
    direction LR

    state "数据集创建" as DC
    state "记录入库" as RI
    state "标注" as A
    state "导出" as E

    DC --> RI
    RI --> A
    A --> E

    state DC {
        [*] --> 定义字段
        定义字段 --> 定义问题
        定义问题 --> 设置指导说明
        设置指导说明 --> 创建数据集
        创建数据集 --> [*]
    }

    state RI {
        [*] --> 准备记录
        准备记录 --> 验证结构
        验证结构 --> 存储记录
        存储记录 --> [*]
    }

    state A {
        [*] --> 获取记录
        获取记录 --> 展示UI
        展示UI --> 提交响应
        提交响应 --> 更新状态
        更新状态 --> [*]
    }

    state E {
        [*] --> 查询数据
        查询数据 --> 格式化输出
        格式化输出 --> [*]
    }

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

来源：

• argilla-server/src/argilla_server/contexts/datasets.py:480-457
• argilla-server/src/argilla_server/contexts/datasets.py:480-597

记录状态流

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

flowchart TB
    subgraph "记录状态"
        RPending["待处理"]
        RCompleted["已完成"]
        RPending -->|达到最少响应数| RCompleted
    end

    subgraph "响应状态"
        RespDraft["草稿"]
        RespSubmitted["已提交"]
        RespDiscarded["已废弃"]
        RespDraft -->|用户提交| RespSubmitted
        RespDraft -->|用户废弃| RespDiscarded
    end

来源：

• 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 队列：用于后台任务，如状态更新和批量操作

flowchart TB
    subgraph "服务端组件"
        API["FastAPI Server"]
        DBAccess["数据库访问层"]
        Search["搜索引擎客户端"]
        Queue["后台任务队列"]
    end

    subgraph "存储"
        DB[(数据库)]
        ES[(Elasticsearch/OpenSearch)]
        Redis[(Redis)]
    end

    API --> DBAccess
    API --> Search
    API --> Queue

    DBAccess --> DB
    Search --> ES
    Queue --> Redis

    DB -- "同步" --> ES

来源：

• argilla-server/src/argilla_server/database.py:30-97

DatasetUser 追踪

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

classDiagram
    class "DatasetUser" {
        +dataset_id: UUID
        +user_id: UUID
        +inserted_at: datetime
        +updated_at: datetime
    }

    "Dataset" "1" <-- "*" "DatasetUser"
    "User" "1" <-- "*" "DatasetUser"

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

来源：

• 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 工作流。