agentic_huge_data_base / wiki
页面 Argilla · 3.2 记录与响应·DeepWiki 中文全文译文
DeepWiki 中文译文 / Argilla / 3.2

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

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

项目Argilla 章节3.2 状态全文译文 模块检索、召回与索引、接口与服务契约、评测、反馈与人工复核、文档对象与元数据
项目要点页2.5 参考项目 项目章节目录Argilla DeepWiki 原始章节Records and Responses 上一章3.1 下一章3.3
源码线索
  • 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
模块标签
  • 检索、召回与索引
  • 接口与服务契约
  • 评测、反馈与人工复核
  • 文档对象与元数据
  • 测试、发布与运维

章节正文

记录与响应

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

记录与响应

相关源文件

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

  • 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 中数据管理的基础，分别代表需要标注的内容和收集到的反馈。

Argilla · 数据模型 · 图 1
Argilla · 数据模型 · 图 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 中，一条记录表示如下：

Argilla · 记录结构 · 图 2
Argilla · 记录结构 · 图 2

来源： 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

响应工作流

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

Argilla · 响应工作流 · 图 3
Argilla · 响应工作流 · 图 3

当添加一条响应时：

  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

记录生命周期

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

Argilla · 记录生命周期 · 图 4
Argilla · 记录生命周期 · 图 4

从"待处理"到"已完成"的转换取决于数据集的分布设置，特别是 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 系统中的流动过程：

Argilla · API 流程 · 图 5
Argilla · API 流程 · 图 5

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

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