3.2 · 记录与响应（Records and Responses）

记录与响应（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/argilla-io/argilla/3.2-records-and-responses

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

翻译模型：deepseek-chat

原文字符数：22135

项目：Argilla (argilla)

---

记录与响应

相关源文件

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

• argilla-server/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/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
• argilla/docs/reference/argilla/records/responses.md
• argilla/docs/reference/argilla/records/suggestions.md
• argilla/docs/reference/argilla/settings/fields.md
• argilla/docs/tutorials/image_classification.ipynb
• argilla/docs/tutorials/image_preference.ipynb
• argilla/docs/tutorials/index.md
• argilla/docs/tutorials/text_classification.ipynb
• argilla/docs/tutorials/token_classification.ipynb
• argilla/mkdocs.yml
• argilla/src/argilla/_models/_record/_record.py
• argilla/src/argilla/records/_dataset_records.py
• argilla/src/argilla/records/_io/_datasets.py
• argilla/src/argilla/records/_io/_generic.py
• argilla/src/argilla/records/_io/_json.py
• argilla/src/argilla/records/_resource.py
• argilla/src/argilla/records/_search.py
• argilla/tests/integration/test_export_dataset.py
• argilla/tests/integration/test_export_records.py
• argilla/tests/integration/test_list_records.py
• argilla/tests/integration/test_query_records.py
• argilla/tests/integration/test_search_records.py
• argilla/tests/unit/export/test_record_export_import_compatibillity.py
• argilla/tests/unit/test_io/test_generic.py
• argilla/tests/unit/test_io/test_hf_datasets.py
• argilla/tests/unit/test_record_fields.py
• argilla/tests/unit/test_resources/test_records.py

本文档描述了 Argilla 中的核心数据实体：记录（Record）和响应（Response）。记录是需要标注的单个数据项，而响应是用户提供的标注。本页面将解释这些实体的数据模型、生命周期和操作。

关于创建数据集以及配置字段和问题的信息，请参阅数据集与设置。

数据模型

记录和响应构成了 Argilla 中数据管理的基础，分别代表需要标注的内容和收集到的反馈。

classDiagram
    class "数据集" {
        +id: UUID
        +name: string
        +workspace_id: UUID
        +status: DatasetStatus
    }

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

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

    class "用户" {
        +id: UUID
        +username: string
        +role: UserRole
    }

    class "建议" {
        +id: UUID
        +value: Any
        +score: float
        +agent: string
        +record_id: UUID
        +question_id: UUID
    }

    class "向量" {
        +id: UUID
        +value: List[float]
        +record_id: UUID
        +vector_settings_id: UUID
    }

    "数据集" "1" *-- "*" "记录": 包含
    "记录" "1" *-- "*" "响应": 拥有
    "记录" "1" *-- "*" "建议": 拥有
    "记录" "1" *-- "*" "向量": 拥有
    "用户" "1" -- "*" "响应": 提交

来源：

• argilla-server/src/argilla_server/models/database.py:144-228
• argilla-server/src/argilla_server/models/database.py:219-291
• argilla-server/src/argilla_server/models/database.py:117-139

记录结构

Argilla 中的一条记录包含以下组成部分：

1. 字段（Fields）：需要标注的主要内容（文本、图像、聊天或自定义内容）
2. 元数据（Metadata）：关于记录的附加信息，可用于过滤
3. 向量（Vectors）：向量嵌入，支持相似性搜索
4. 建议（Suggestions）：预计算的问题答案，通常来自模型
5. 响应（Responses）：用户标注，提供对记录的反馈

在 Python SDK 中，一条记录表示如下：

classDiagram
    class "记录" {
        +id: string
        +fields: RecordFields
        +metadata: RecordMetadata
        +vectors: RecordVectors
        +responses: RecordResponses
        +suggestions: RecordSuggestions
        +status: string
        +_server_id: UUID
        +get()
        +api_model()
        +to_dict()
    }

    class "RecordFields" {
        +to_dict()
    }

    class "RecordMetadata" {
        +to_dict()
        +api_models()
    }

    class "RecordVectors" {
        +to_dict()
        +api_models()
    }

    class "RecordResponses" {
        +add(response)
        +to_dict()
        +api_models()
    }

    class "RecordSuggestions" {
        +add(suggestion)
        +to_dict()
        +api_models()
    }

    "记录" "1" *-- "1" "RecordFields"
    "记录" "1" *-- "1" "RecordMetadata"
    "记录" "1" *-- "1" "RecordVectors"
    "记录" "1" *-- "1" "RecordResponses"
    "记录" "1" *-- "1" "RecordSuggestions"

来源：

• argilla/src/argilla/records/_resource.py:41-91
• argilla/src/argilla/records/_resource.py:292-328
• argilla/src/argilla/records/_resource.py:330-356
• argilla/src/argilla/records/_resource.py:358-430
• argilla/src/argilla/records/_resource.py:433-487

响应结构

Argilla 中的一条响应代表用户为特定记录提供的标注。每条响应包含：

1. 值（Values）：实际的标注数据（问题的答案）
2. 状态（Status）：响应的状态（已提交、草稿或已丢弃）
3. 记录 ID（Record ID）：被标注记录的引用
4. 用户 ID（User ID）：提供标注的用户的引用

响应由记录 ID 和用户 ID 的组合唯一标识，这意味着一个用户最多只能为一条记录提供一条响应。

来源：

• argilla-server/src/argilla_server/models/database.py:117-139
• argilla-server/src/argilla_server/contexts/datasets.py:480-517

使用记录

创建和添加记录

可以使用 Python SDK 中的 Dataset.records.log() 方法向数据集添加记录。创建记录有几种方式：

1. 作为 Record 对象：

   record = rg.Record(
       fields={"text": "This is a sample text."},
       metadata={"source": "example"},
       suggestions=[rg.Suggestion("category", "positive", score=0.9)]
   )
   dataset.records.log([record])

1. 从字典创建：

   data = [
       {
           "text": "This is a sample text.",
           "category": "positive",
           "source": "example"
       }
   ]
   dataset.records.log(data)

1. 从 Hugging Face 数据集创建：

   from datasets import load_dataset
   hf_dataset = load_dataset("imdb", split="train[:100]")
   dataset.records.log(hf_dataset)

当你记录（log）记录时，它们会被分批发送到服务器，存储在数据库中，并在搜索引擎中建立索引。SDK 会处理数据到 Argilla 记录的映射，包括转换字段、建议、响应和元数据。

来源：

• argilla/src/argilla/records/_dataset_records.py:247-302
• argilla/src/argilla/records/_resource.py:56-98
• argilla-server/src/argilla_server/bulk/records_bulk.py:47-155

查询和搜索记录

你可以使用 Dataset.records() 方法查询记录，该方法返回一个记录迭代器：

# 获取所有记录
records = list(dataset.records())

# 使用查询获取记录
records = list(dataset.records(query="positive"))

# 使用过滤器获取记录
from argilla import Query, Filter
records = list(dataset.records(query=Query(filters=[Filter(name="metadata.source", value="example")])))

# 使用向量搜索获取记录
records = list(dataset.records(query=Query(similar="This is a query text", vector_name="embeddings")))

记录可以附带或不附带额外信息进行获取：

# 获取带有建议的记录
records = list(dataset.records(with_suggestions=True))

# 获取带有响应的记录
records = list(dataset.records(with_responses=True))

# 获取带有向量的记录
records = list(dataset.records(with_vectors=True))

来源：

• argilla/src/argilla/records/_dataset_records.py:195-239
• argilla/src/argilla/records/_search.py

导出记录

记录可以以多种格式导出：

1. 导出为字典：

   data_dict = dataset.records.to_dict(flatten=False)

1. 导出为列表：

   data_list = dataset.records.to_list(flatten=False)

1. 导出为 JSON：

   dataset.records.to_json("path/to/file.json")

1. 导出为 Hugging Face 数据集：

   hf_dataset = dataset.records.to_datasets()

来源：

• argilla/src/argilla/records/_dataset_records.py:348-415
• argilla/src/argilla/records/_io/_datasets.py
• argilla/src/argilla/records/_io/_generic.py

删除记录

可以使用 Dataset.records.delete() 方法删除记录：

dataset.records.delete(records)

来源：

• argilla/src/argilla/records/_dataset_records.py:304-346

使用响应

添加响应

可以通过几种方式向记录添加响应：

1. 在创建记录时：

   record = rg.Record(
       fields={"text": "This is a sample text."},
       responses=[rg.Response("category", "positive", user_id=user_id)]
   )
   dataset.records.log([record])

1. 通过更新现有记录：

   record = dataset.records(limit=1)[0]
   record.responses.add(rg.Response("category", "positive", user_id=user_id))
   dataset.records.log([record])

响应由记录 ID 和用户 ID 的组合唯一标识。如果用户尝试为同一条记录添加多条响应，会引发错误。

来源：

• argilla/src/argilla/records/_resource.py:358-430
• argilla-server/src/argilla_server/contexts/datasets.py:480-517

响应工作流

添加响应的典型工作流如下：

sequenceDiagram
    participant "客户端" as Argilla SDK
    participant "API" as Argilla Server
    participant "数据库" as Database
    participant "搜索引擎" as Search Engine

    "客户端"->>+"API": 创建/更新响应
    "API"->>+"数据库": 存储响应
    "数据库"-->>-"API": 确认存储
    "API"->>+"数据库": 更新 DatasetUser
    "数据库"-->>-"API": 确认更新
    "API"->>+"搜索引擎": 更新记录索引
    "搜索引擎"-->>-"API": 确认更新
    "API"-->>-"客户端": 返回响应

    "客户端"->>+"API": 获取带有响应的记录
    "API"->>+"搜索引擎": 搜索记录
    "搜索引擎"-->>-"API": 返回记录 ID
    "API"->>+"数据库": 获取带有响应的记录
    "数据库"-->>-"API": 返回记录详情
    "API"-->>-"客户端": 返回带有响应的记录

当添加一条响应时：

1. 响应被存储在数据库中
2. 用户被添加到数据集的用户列表中
3. 记录的状态会根据需要更新
4. 搜索引擎索引会被更新

来源：

• argilla-server/src/argilla_server/contexts/datasets.py:480-578
• argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.py:147-162

响应状态

响应可以具有以下状态之一：

• 已提交（Submitted）：标注已完成并确认
• 已丢弃（Discarded）：标注被拒绝或标记为不可用
• 草稿（Draft）：标注正在进行中但尚未完成

状态会影响记录在标注工作流和指标中的处理方式。

来源：

• argilla-server/src/argilla_server/models/database.py:114
• argilla-server/src/argilla_server/contexts/datasets.py:387-423

记录生命周期

记录具有一个反映其在标注工作流中进度的状态：

stateDiagram-v2
    [*] --> "待处理（Pending）"
    "待处理（Pending）" --> "已完成（Completed）": 收集到足够的响应
    "已完成（Completed）" --> "待处理（Pending）": 响应被移除或更改
    "待处理（Pending）" --> [*]: 记录被删除
    "已完成（Completed）" --> [*]: 记录被删除

从"待处理"到"已完成"的转换取决于数据集的分布设置，特别是 min_submitted 参数，该参数指定了一条记录被视为完成所需的最少已提交响应数量。

来源：

• argilla-server/src/argilla_server/models/database.py:224-226
• argilla-server/src/argilla_server/contexts/distribution.py

记录状态计算

记录的状态基于以下因素计算：

1. 它收到的已提交响应数量
2. 数据集分布配置中的 min_submitted 设置

当添加、更新或删除响应时，记录的状态会被重新计算。这个计算在查询记录和修改响应时都会进行。

来源：

• argilla-server/src/argilla_server/bulk/records_bulk.py:198
• argilla-server/src/argilla_server/contexts/datasets.py:508
• argilla-server/src/argilla_server/contexts/datasets.py:534
• argilla-server/src/argilla_server/contexts/datasets.py:569

API 流程

下图展示了在使用记录和响应时，数据在 Argilla 系统中的流动过程：

flowchart TD
    subgraph "客户端"
        SDK["Argilla SDK"]
        Record["记录对象"]
        Response["响应对象"]
    end

    subgraph "服务端"
        API["RESTful API"]
        DB[(数据库)]
        SE[("搜索引擎")]
    end

    SDK -- "1. 创建/更新记录" --> API
    API -- "2. 存储记录" --> DB
    API -- "3. 索引记录" --> SE

    SDK -- "4. 添加响应" --> API
    API -- "5. 存储响应" --> DB
    API -- "6. 更新记录状态" --> DB
    API -- "7. 更新搜索索引" --> SE

    SDK -- "8. 查询记录" --> API
    API -- "9. 搜索记录" --> SE
    SE -- "10. 返回记录 ID" --> API
    API -- "11. 获取带有响应的记录" --> DB
    DB -- "12. 返回带有响应的记录" --> API
    API -- "13. 返回记录" --> SDK

此图展示了从创建记录到添加响应再到查询数据的完整周期，说明了系统各组件之间的交互方式。

来源：

• argilla-server/src/argilla_server/contexts/datasets.py:329-667
• argilla-server/src/argilla_server/bulk/records_bulk.py:47-245
• argilla/src/argilla/records/_dataset_records.py:164-485

数据集进度与指标

Argilla 提供了几种跟踪数据集标注进度的方法：

1. 数据集进度：显示数据集中记录的整体完成状态

   progress = client.api.datasets.get_progress(dataset_id)

1. 用户指标：显示特定用户的标注进度

   metrics = client.api.datasets.get_user_metrics(dataset_id)

1. 用户进度：显示数据集中所有用户的标注进度

   users_progress = client.api.datasets.get_users_progress(dataset_id)

这些指标跟踪处于待处理、已完成或具有特定响应状态的记录数量。

来源：

• argilla-server/src/argilla_server/contexts/datasets.py:387-457
• argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.py:147-193

总结

记录和响应是 Argilla 中的核心数据实体。记录包含需要标注的数据，而响应包含用户提供的标注。记录与响应之间的关系驱动着标注工作流，记录在收到足够的响应后会从待处理状态转换为已完成状态。

Python SDK 提供了一个高级接口，用于处理记录和响应，允许你创建、查询、更新和导出数据。服务器负责处理记录和响应的存储、索引和状态管理，确保高效的数据访问和工作流管理。