尧图网站建设 
Argilla 记录Record管理完全指南添加、更新、列出与删除【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla本文是 Argilla 中记录Record的实战操作指南。Record 是 Argilla 数据集的最小数据单元承载待标注的字段、元数据、向量以及模型预测suggestions和人工标注responses。读完本文你将掌握通过rg.Record对象、通用字典结构和 Hugging Face Dataset 三种方式向数据集写入记录学会按字段/元数据/向量/建议/响应五个维度组织数据并能够熟练完成记录的批量更新、按查询过滤删除等日常管理操作。Record 是什么在 Argilla 中一条record是需要标注的一个数据项由一个或多个fields字段组成。字段是标注任务中展示给用户在 UI 上的信息主体每条记录还关联标注者需要回答的questions问题并可选地携带用于辅助标注的suggestions建议和responses响应同时可以附加指南guidelines帮助标注者高效完成任务。Record 归属于 dataset因此添加记录前必须先创建数据集具体见 如何创建数据集。一条完整 Record 的核心形态如下摘自文档主类示例rg.Record( external_id1234, fields{ question: Do you need oxygen to breathe?, answer: Yes }, metadata{ category: A }, vectors{ my_vector: [0.1, 0.2, 0.3], }, suggestions[ rg.Suggestion(my_label, positive, score0.9, agentmodel_name) ], responses[ rg.Response(label, positive, user_iduser_id) ], )关于Record类的全部属性、参数与方法参见 Record - Python Reference。从源码层面看Record在 records/_resource.py 中被实现为一个Resource子类内部将五个维度的数据分别包装为RecordFields、RecordMetadata、RecordVectors、RecordResponses、RecordSuggestions五个容器对象并通过api_model()/serialize()/to_dict()完成与服务端 API 的序列化交互。构造时还包含若干校验fields、metadata、vectors、responses、suggestions至少提供一个若不提供fields或fields为空字典则必须提供id见同文件 L85-L90。添加记录记录通过Dataset.records.log方法添加支持三种输入形态Record对象列表、字典结构列表、Hugging Face Dataset。无论哪种方式字段fields、元数据metadata和向量vectors都必须与数据集设置dataset settings中预先配置的内容保持一致。记录一旦写入即可在 Argilla UI 中看到若未显示可点击刷新按钮更新视图。!!! tip 在向数据集写入前务必花时间检查数据以免触发questions或fields的变更。!!! note 如果计划使用公开数据Hugging Face Hub 的 Datasets 页面是不错的起点但请始终检查许可证确保你的使用场景合法合规。方式一作为Record对象当需要在定义记录前对数据施加额外逻辑时直接初始化Record对象最为合适若数据已是结构化形态则优先考虑字典或 Hugging Face Dataset 方式。import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset) records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, ), # (1) ] dataset.records.log(records)这是定义的示意。真实场景中你会遍历某个数据结构为每次迭代创建Record对象。方式二从通用数据结构字典可以直接以类字典结构添加数据字典的键对应数据集中的 fields、questions、metadata 或 vectors 名称值为要添加的数据。如果源数据的键名与 Argilla 数据集命名不一致可以用mapping参数指定源数据键到数据集字段、元数据、向量、建议或响应的对应关系需要将同一份数据映射到多个属性时可用列表同时给出多个属性名。import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset) # Add records to the dataset with the fields question and answer data [ { question: Do you need oxygen to breathe?, answer: Yes, }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, }, # (1) ] dataset.records.log(data) # Add records to the dataset with a mapping of the fields question and answer data [ { query: Do you need oxygen to breathe?, response: Yes, }, { query: What is the boiling point of water?, response: 100 degrees Celsius, }, ] dataset.records.log(data, mapping{query: question, response: answer}) # (2)数据结构的键必须与 Argilla 数据集的 fields 或 questions 匹配。本例中存在名为question和answer的字段。数据结构的键是query和response而 Argilla 数据集的字段是question和answer可用mapping将前者映射到后者。方式三从 Hugging Face Dataset当希望直接复用 Hugging Face Hub 上的数据集时可以将其整体写入 Argilla 数据集。列名需与 Argilla 数据集的字段、元数据或向量名称对应。import argilla as rg from datasets import load_dataset client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset) # (1) hf_dataset load_dataset(imdb, splittrain[:100]) # (2) dataset.records.log(recordshf_dataset)这里使用 Argilla workspace 中的my_dataset其含有一个text字段和一个label问题。本例中 Hugging Face 数据集与 Argilla 数据集 schema 一致若不一致可用datasets库的.map先预处理数据再写入。若 Hugging Face 数据集的 schema 与 Argilla 字段名不匹配同样使用mapping指定对应关系键为 Hugging Face 数据集的列名值为 Argilla 数据集的字段名。dataset.records.log( recordshf_dataset, mapping{text: review, label: sentiment} ) # (1)本例中 Hugging Face 数据集的text列对应 Argilla 数据集的review字段label列对应sentiment字段。mapping 机制的源码实现mapping并非简单替换字符串而是由IngestedRecordMapper见 records/_mapping/_mapper.py解析执行的它依据数据集 schemafields、questions、metadata、vectors与用户提供的 mapping 构建一张RecordAttributesMap路由表records/_mapping/_routes.py把源数据键路由到field、metadata、vector、suggestion、response、id六类属性之一。路由支持点分语法attribute[.type[.parameter]]例如my_label.suggestion.score表示将某列映射为问题my_label建议的score参数ParameterType定义了value、score、agent三种参数类型见 routes 定义。这也是下文“从字典添加建议/响应”示例中score: my_label.suggestion.score写法的底层依据。记录的五大组成部分Fields字段字段是记录的主要信息载体在 UI 上与问题表单一同首先展示。只能包含你在 dataset settings 中预先配置的字段。不同字段类型对数据格式要求不同Text 字段期望字符串输入。record rg.Record( fields{text: Hello World, how are you?} )Image 字段接受远程 URL、本地图片路径字符串或 PIL 对象。带图片的记录如何添加参见 Dataset.records - Python Reference。records [ rg.Record( fields{image: https://example.com/image.jpg} ), rg.Record( fields{image: path/to/image.jpg} ), rg.Record( fields{image: Image.open(path/to/image.jpg)} ), ]Chat 字段期望包含role和content键的字典列表role标识对话者类型如 user、assistant、model 等content为消息文本。record rg.Record( fields{ chat: [ {role: user, content: What is Argilla?}, {role: assistant, content: Argilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets}, ] } )Custom 字段期望与 dataset settings 中定义一致的字典且需与CustomField.template对齐才能在 UI 中正常渲染。record rg.Record( fields{custom: {key: value}} )从源码看RecordFields容器在to_dict()时会按数据集 schema 判断字段类型image 字段经cast_image/uncast_image序列化chat 字段将消息对象统一转换为字典见 records/_resource.py#L301-L327。Metadata元数据记录元数据以字典形式携带字段之外的任意信息。要让元数据可被用于过滤和排序字典键必须与 metadata property 的name一致键不对应时只要数据集开启了allow_extra_metadata该键仍会作为额外元数据随记录存储但无法用于过滤与排序。!!! note 要在数据集中使用元数据必须先在该数据集的 dataset settings 中定义 metadata property。元数据的使用细节参见 Metadata - Python Reference。作为Record对象添加# Add records to the dataset with the metadata category records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, metadata{my_metadata: option_1}, ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, metadata{my_metadata: option_1}, ), ] dataset.records.log(records)从通用数据结构添加# Add records to the dataset with the metadata category data [ { question: Do you need oxygen to breathe?, answer: Yes, my_metadata: option_1, }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, my_metadata: option_1, }, ] dataset.records.log(data)元数据键是否被识别为已配置属性由映射器对照dataset.settings.metadata判断默认映射中只有与 metadata propertyname完全一致的键才会进入可过滤的元数据路由见 mapper 默认映射构建。Vectors向量可以为记录关联向量如文本嵌入用于在 UI 与 Python SDK 中进行语义检索。列表长度必须与向量设置中声明的维度dimensions一致。!!! note 要在数据集中使用向量必须先在该数据集的 dataset settings 中定义向量设置。Vector类的属性、参数与方法参见 Vector - Python Reference。作为Record对象添加# Add records to the dataset with the vector my_vector and dimension3 records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, vectors{ my_vector: [0.1, 0.2, 0.3] }, ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, vectors{ my_vector: [0.2, 0.5, 0.3] }, ), ] dataset.records.log(records)从通用数据结构添加# Add records to the dataset with the vector my_vector and dimension3 data [ { question: Do you need oxygen to breathe?, answer: Yes, my_vector: [0.1, 0.2, 0.3], }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, my_vector: [0.2, 0.5, 0.3], }, ] dataset.records.log(data)向量对象由 vectors.py 中的Vector类封装其values必须为浮点数列表服务端会校验其长度与数据集 vector settings 中声明的维度一致。Suggestions建议Suggestions 指建议性响应典型如模型预测用于加速标注流程。可以在创建记录时添加也可以在之后补充。每个问题只能有一个 suggestion且建议值必须符合对应问题的约束——例如对 1~5 分的RatingQuestion建议值必须是该范围内的合法值。不同Question类型对应的 suggestion 取值格式参见 Suggestions - Python Reference。作为Record对象添加# Add records to the dataset with the label my_label records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, suggestions[ rg.Suggestion( my_label, positive, score0.9, agentmodel_name ) ], ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, suggestions[ rg.Suggestion( my_label, negative, score0.9, agentmodel_name ) ], ), ] dataset.records.log(records)从通用数据结构添加# Add records to the dataset with the label question my_label data [ { question: Do you need oxygen to breathe?, answer: Yes, label: positive, score: 0.9, agent: model_name, }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, label: negative, score: 0.9, agent: model_name, }, ] dataset.records.log( datadata, mapping{ label: my_label, score: my_label.suggestion.score, agent: my_label.suggestion.agent, }, )suggestion是数据集中问题的默认映射目标——映射器中默认将问题名对应的源键路由为SUGGESTION类型见 mapper 类型推断。Suggestion类suggestions.py持有value、score、agent、typemodel或human等属性并在服务端往返时针对RankingQuestion等特殊题型自动转换值格式。Responses响应如果数据集已有标注结果可以在创建记录时一并写入。响应格式必须与 Argilla 的输出格式一致且满足对应问题类型的 schema 要求。若同一问题要写入多条响应必须携带user_id否则响应将作用于所有标注者。不同Question类型对应的响应取值格式参见 Responses - Python Reference。!!! note 请注意带响应的记录在 UI 中会显示为 Draft 状态。作为Record对象添加# Add records to the dataset with the label my_label records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, responses[ rg.Response(my_label, positive, user_iduser.id) ] ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, responses[ rg.Response(my_label, negative, user_iduser.id) ] ), ] dataset.records.log(records)从通用数据结构添加若需指定添加响应的用户可使用user_id参数。# Add records to the dataset with the label my_label data [ { question: Do you need oxygen to breathe?, answer: Yes, label: positive, }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, label: negative, }, ] dataset.records.log(data, user_iduser.id, mapping{label: my_label.response})Response类responses.py要求question_name、value、user_id均非空并支持draft、submitted、discarded三种状态ResponseStatus枚举其中submitted状态下value必填。同一问题同一用户只能有一条响应RecordResponses容器在add时会做去重校验见 records/_resource.py#L407-L425。列出记录在数据集对象上调用records方法即可列出记录返回可迭代的Record对象列表for record in dataset.records( with_suggestionsTrue, with_responsesTrue, with_vectorsTrue ): # Access the record properties print(record.metadata) print(record.vectors) print(record.suggestions) print(record.responses) # Access the responses of the record for response in record.responses: print(response.value)DatasetRecords.__call__见 records/_dataset_records.py#L195-L238返回一个DatasetRecordsIterator支持batch_size默认 256、start_offset、limit、query等参数服务端按批拉取避免一次性加载全量数据。with_vectors可以是布尔值或向量名称列表传True拉取全部向量传列表则只拉取指定向量_validate_vector_names会校验向量名是否存在于数据集 schema见 L477-L484。集成测试 test_list_records.py 覆盖了start_offset、limit、带响应列出等场景。更新记录更新记录同样通过Dataset对象的log方法完成只需提供记录的id及新的数据即可log内部按 id 判断是新增还是更新见 log 方法签名。data dataset.records.to_list(flattenTrue) updated_data [ { text: sample[text], label: positive, id: sample[id], } for sample in data ] dataset.records.log(recordsupdated_data)更新元数据Record的metadata是一个 Python 字典可迭代记录后按键更新再写回数据集!!! tip 不同MetadataProperty类型的取值格式参见 Metadata - Python Reference。updated_records [] for record in dataset.records(): record.metadata[my_metadata] new_value record.metadata[my_new_metadata] new_value updated_records.append(record) dataset.records.log(recordsupdated_records)更新向量当数据集设置中新增了向量字段或需更新已有记录的向量值时可迭代记录按键更新向量updated_records [] for record in dataset.records(with_vectorsTrue): record.vectors[my_vector] [ 0, 1, 2, 3, 4, 5 ] record.vectors[my_new_vector] [ 0, 1, 2, 3, 4, 5 ] updated_records.append(record) dataset.records.log(recordsupdated_records)更新建议可迭代记录按键更新已有 suggestion也可用add方法新增 suggestion!!! tip 不同Question类型的取值格式参见 Suggestions - Python Reference。updated_records [] for record in dataset.records(with_suggestionsTrue): # We can update existing suggestions record.suggestions[label].value new_value record.suggestions[label].score 0.9 record.suggestions[label].agent model_name # We can also add new suggestions with the add method: if not record.suggestions[label]: record.suggestions.add( rg.Suggestion(value, label, score0.9, agentmodel_name) ) updated_records.append(record) dataset.records.log(recordsupdated_records)注意RecordSuggestions.add会以问题名为键覆盖旧 suggestion每问题仅一条而RecordResponses.add则按「问题名 user_id」追加去重见 records/_resource.py#L476-L483 与 L407-L425。相关行为在集成测试 test_update_records.py 中有覆盖例如test_update_records_fields与test_update_records_suggestions_from_data。更新响应可迭代记录按键更新已有 response也可用add方法新增 response!!! tip 不同Question类型的取值格式参见 Responses - Python Reference。updated_records [] for record in dataset.records(with_responsesTrue): for response in record.responses[label]: if response: response.value new_value response.user_id existing_user_id else: record.responses.add(rg.Response(label, YES, user_iduser.id)) updated_records.append(record) dataset.records.log(recordsupdated_records)删除记录删除记录通过Dataset对象上的delete方法完成先按需检索服务端记录得到待删列表后批量删除。records_to_delete list(dataset.records)[:5] dataset.records.delete(recordsrecords_to_delete)delete内部会先经_ingest_records将Record列表解析为模型再按批默认批大小 64见DEFAULT_DELETE_BATCH_SIZE调用服务端批量删除接口见 delete 方法实现集成测试 test_delete_records.py 覆盖了批量删除、单条删除及批大小支持等场景。基于查询删除记录基于查询删除非常实用——例如可以借此避免误删已带响应的记录。关于查询语法参见 查询 how-to 指南。status_filter rg.Query( filter rg.Filter((response.status, , pending)) ) records_to_delete list(dataset.records(status_filter)) dataset.records.delete(records_to_delete)该示例中dataset.records(status_filter)返回一个带查询的DatasetRecordsIterator迭代器在_fetch_from_server_with_search中通过服务端搜索接口拉取满足response.status pending未提交响应的记录从而只删除这些尚未有正式标注的记录。小结本文完整梳理了 Argilla 记录的生命周期管理从理解 Record 的字段/元数据/向量/建议/响应五维结构到用Record对象、字典、Hugging Face Dataset 三种方式写入数据含mapping点分语法的源码原理再到列出、更新元数据/向量/建议/响应四类局部更新和按查询删除。核心 API 集中在Dataset.records的log/delete/records三个入口records/_dataset_records.py记录数据模型与容器实现在 records/_resource.py映射逻辑在 records/_mapping/_mapper.py。配合 test_add_records.py、test_update_records.py、test_delete_records.py 等集成测试可以进一步验证各类操作的实际行为。【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Argilla 记录（Record）管理完全指南：添加、更新、列出与删除
Argilla 记录Record管理完全指南添加、更新、列出与删除【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla本文是 Argilla 中记录Record的实战操作指南。Record 是 Argilla 数据集的最小数据单元承载待标注的字段、元数据、向量以及模型预测suggestions和人工标注responses。读完本文你将掌握通过rg.Record对象、通用字典结构和 Hugging Face Dataset 三种方式向数据集写入记录学会按字段/元数据/向量/建议/响应五个维度组织数据并能够熟练完成记录的批量更新、按查询过滤删除等日常管理操作。Record 是什么在 Argilla 中一条record是需要标注的一个数据项由一个或多个fields字段组成。字段是标注任务中展示给用户在 UI 上的信息主体每条记录还关联标注者需要回答的questions问题并可选地携带用于辅助标注的suggestions建议和responses响应同时可以附加指南guidelines帮助标注者高效完成任务。Record 归属于 dataset因此添加记录前必须先创建数据集具体见 如何创建数据集。一条完整 Record 的核心形态如下摘自文档主类示例rg.Record( external_id1234, fields{ question: Do you need oxygen to breathe?, answer: Yes }, metadata{ category: A }, vectors{ my_vector: [0.1, 0.2, 0.3], }, suggestions[ rg.Suggestion(my_label, positive, score0.9, agentmodel_name) ], responses[ rg.Response(label, positive, user_iduser_id) ], )关于Record类的全部属性、参数与方法参见 Record - Python Reference。从源码层面看Record在 records/_resource.py 中被实现为一个Resource子类内部将五个维度的数据分别包装为RecordFields、RecordMetadata、RecordVectors、RecordResponses、RecordSuggestions五个容器对象并通过api_model()/serialize()/to_dict()完成与服务端 API 的序列化交互。构造时还包含若干校验fields、metadata、vectors、responses、suggestions至少提供一个若不提供fields或fields为空字典则必须提供id见同文件 L85-L90。添加记录记录通过Dataset.records.log方法添加支持三种输入形态Record对象列表、字典结构列表、Hugging Face Dataset。无论哪种方式字段fields、元数据metadata和向量vectors都必须与数据集设置dataset settings中预先配置的内容保持一致。记录一旦写入即可在 Argilla UI 中看到若未显示可点击刷新按钮更新视图。!!! tip 在向数据集写入前务必花时间检查数据以免触发questions或fields的变更。!!! note 如果计划使用公开数据Hugging Face Hub 的 Datasets 页面是不错的起点但请始终检查许可证确保你的使用场景合法合规。方式一作为Record对象当需要在定义记录前对数据施加额外逻辑时直接初始化Record对象最为合适若数据已是结构化形态则优先考虑字典或 Hugging Face Dataset 方式。import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset) records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, ), # (1) ] dataset.records.log(records)这是定义的示意。真实场景中你会遍历某个数据结构为每次迭代创建Record对象。方式二从通用数据结构字典可以直接以类字典结构添加数据字典的键对应数据集中的 fields、questions、metadata 或 vectors 名称值为要添加的数据。如果源数据的键名与 Argilla 数据集命名不一致可以用mapping参数指定源数据键到数据集字段、元数据、向量、建议或响应的对应关系需要将同一份数据映射到多个属性时可用列表同时给出多个属性名。import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset) # Add records to the dataset with the fields question and answer data [ { question: Do you need oxygen to breathe?, answer: Yes, }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, }, # (1) ] dataset.records.log(data) # Add records to the dataset with a mapping of the fields question and answer data [ { query: Do you need oxygen to breathe?, response: Yes, }, { query: What is the boiling point of water?, response: 100 degrees Celsius, }, ] dataset.records.log(data, mapping{query: question, response: answer}) # (2)数据结构的键必须与 Argilla 数据集的 fields 或 questions 匹配。本例中存在名为question和answer的字段。数据结构的键是query和response而 Argilla 数据集的字段是question和answer可用mapping将前者映射到后者。方式三从 Hugging Face Dataset当希望直接复用 Hugging Face Hub 上的数据集时可以将其整体写入 Argilla 数据集。列名需与 Argilla 数据集的字段、元数据或向量名称对应。import argilla as rg from datasets import load_dataset client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset) # (1) hf_dataset load_dataset(imdb, splittrain[:100]) # (2) dataset.records.log(recordshf_dataset)这里使用 Argilla workspace 中的my_dataset其含有一个text字段和一个label问题。本例中 Hugging Face 数据集与 Argilla 数据集 schema 一致若不一致可用datasets库的.map先预处理数据再写入。若 Hugging Face 数据集的 schema 与 Argilla 字段名不匹配同样使用mapping指定对应关系键为 Hugging Face 数据集的列名值为 Argilla 数据集的字段名。dataset.records.log( recordshf_dataset, mapping{text: review, label: sentiment} ) # (1)本例中 Hugging Face 数据集的text列对应 Argilla 数据集的review字段label列对应sentiment字段。mapping 机制的源码实现mapping并非简单替换字符串而是由IngestedRecordMapper见 records/_mapping/_mapper.py解析执行的它依据数据集 schemafields、questions、metadata、vectors与用户提供的 mapping 构建一张RecordAttributesMap路由表records/_mapping/_routes.py把源数据键路由到field、metadata、vector、suggestion、response、id六类属性之一。路由支持点分语法attribute[.type[.parameter]]例如my_label.suggestion.score表示将某列映射为问题my_label建议的score参数ParameterType定义了value、score、agent三种参数类型见 routes 定义。这也是下文“从字典添加建议/响应”示例中score: my_label.suggestion.score写法的底层依据。记录的五大组成部分Fields字段字段是记录的主要信息载体在 UI 上与问题表单一同首先展示。只能包含你在 dataset settings 中预先配置的字段。不同字段类型对数据格式要求不同Text 字段期望字符串输入。record rg.Record( fields{text: Hello World, how are you?} )Image 字段接受远程 URL、本地图片路径字符串或 PIL 对象。带图片的记录如何添加参见 Dataset.records - Python Reference。records [ rg.Record( fields{image: https://example.com/image.jpg} ), rg.Record( fields{image: path/to/image.jpg} ), rg.Record( fields{image: Image.open(path/to/image.jpg)} ), ]Chat 字段期望包含role和content键的字典列表role标识对话者类型如 user、assistant、model 等content为消息文本。record rg.Record( fields{ chat: [ {role: user, content: What is Argilla?}, {role: assistant, content: Argilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets}, ] } )Custom 字段期望与 dataset settings 中定义一致的字典且需与CustomField.template对齐才能在 UI 中正常渲染。record rg.Record( fields{custom: {key: value}} )从源码看RecordFields容器在to_dict()时会按数据集 schema 判断字段类型image 字段经cast_image/uncast_image序列化chat 字段将消息对象统一转换为字典见 records/_resource.py#L301-L327。Metadata元数据记录元数据以字典形式携带字段之外的任意信息。要让元数据可被用于过滤和排序字典键必须与 metadata property 的name一致键不对应时只要数据集开启了allow_extra_metadata该键仍会作为额外元数据随记录存储但无法用于过滤与排序。!!! note 要在数据集中使用元数据必须先在该数据集的 dataset settings 中定义 metadata property。元数据的使用细节参见 Metadata - Python Reference。作为Record对象添加# Add records to the dataset with the metadata category records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, metadata{my_metadata: option_1}, ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, metadata{my_metadata: option_1}, ), ] dataset.records.log(records)从通用数据结构添加# Add records to the dataset with the metadata category data [ { question: Do you need oxygen to breathe?, answer: Yes, my_metadata: option_1, }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, my_metadata: option_1, }, ] dataset.records.log(data)元数据键是否被识别为已配置属性由映射器对照dataset.settings.metadata判断默认映射中只有与 metadata propertyname完全一致的键才会进入可过滤的元数据路由见 mapper 默认映射构建。Vectors向量可以为记录关联向量如文本嵌入用于在 UI 与 Python SDK 中进行语义检索。列表长度必须与向量设置中声明的维度dimensions一致。!!! note 要在数据集中使用向量必须先在该数据集的 dataset settings 中定义向量设置。Vector类的属性、参数与方法参见 Vector - Python Reference。作为Record对象添加# Add records to the dataset with the vector my_vector and dimension3 records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, vectors{ my_vector: [0.1, 0.2, 0.3] }, ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, vectors{ my_vector: [0.2, 0.5, 0.3] }, ), ] dataset.records.log(records)从通用数据结构添加# Add records to the dataset with the vector my_vector and dimension3 data [ { question: Do you need oxygen to breathe?, answer: Yes, my_vector: [0.1, 0.2, 0.3], }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, my_vector: [0.2, 0.5, 0.3], }, ] dataset.records.log(data)向量对象由 vectors.py 中的Vector类封装其values必须为浮点数列表服务端会校验其长度与数据集 vector settings 中声明的维度一致。Suggestions建议Suggestions 指建议性响应典型如模型预测用于加速标注流程。可以在创建记录时添加也可以在之后补充。每个问题只能有一个 suggestion且建议值必须符合对应问题的约束——例如对 1~5 分的RatingQuestion建议值必须是该范围内的合法值。不同Question类型对应的 suggestion 取值格式参见 Suggestions - Python Reference。作为Record对象添加# Add records to the dataset with the label my_label records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, suggestions[ rg.Suggestion( my_label, positive, score0.9, agentmodel_name ) ], ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, suggestions[ rg.Suggestion( my_label, negative, score0.9, agentmodel_name ) ], ), ] dataset.records.log(records)从通用数据结构添加# Add records to the dataset with the label question my_label data [ { question: Do you need oxygen to breathe?, answer: Yes, label: positive, score: 0.9, agent: model_name, }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, label: negative, score: 0.9, agent: model_name, }, ] dataset.records.log( datadata, mapping{ label: my_label, score: my_label.suggestion.score, agent: my_label.suggestion.agent, }, )suggestion是数据集中问题的默认映射目标——映射器中默认将问题名对应的源键路由为SUGGESTION类型见 mapper 类型推断。Suggestion类suggestions.py持有value、score、agent、typemodel或human等属性并在服务端往返时针对RankingQuestion等特殊题型自动转换值格式。Responses响应如果数据集已有标注结果可以在创建记录时一并写入。响应格式必须与 Argilla 的输出格式一致且满足对应问题类型的 schema 要求。若同一问题要写入多条响应必须携带user_id否则响应将作用于所有标注者。不同Question类型对应的响应取值格式参见 Responses - Python Reference。!!! note 请注意带响应的记录在 UI 中会显示为 Draft 状态。作为Record对象添加# Add records to the dataset with the label my_label records [ rg.Record( fields{ question: Do you need oxygen to breathe?, answer: Yes }, responses[ rg.Response(my_label, positive, user_iduser.id) ] ), rg.Record( fields{ question: What is the boiling point of water?, answer: 100 degrees Celsius }, responses[ rg.Response(my_label, negative, user_iduser.id) ] ), ] dataset.records.log(records)从通用数据结构添加若需指定添加响应的用户可使用user_id参数。# Add records to the dataset with the label my_label data [ { question: Do you need oxygen to breathe?, answer: Yes, label: positive, }, { question: What is the boiling point of water?, answer: 100 degrees Celsius, label: negative, }, ] dataset.records.log(data, user_iduser.id, mapping{label: my_label.response})Response类responses.py要求question_name、value、user_id均非空并支持draft、submitted、discarded三种状态ResponseStatus枚举其中submitted状态下value必填。同一问题同一用户只能有一条响应RecordResponses容器在add时会做去重校验见 records/_resource.py#L407-L425。列出记录在数据集对象上调用records方法即可列出记录返回可迭代的Record对象列表for record in dataset.records( with_suggestionsTrue, with_responsesTrue, with_vectorsTrue ): # Access the record properties print(record.metadata) print(record.vectors) print(record.suggestions) print(record.responses) # Access the responses of the record for response in record.responses: print(response.value)DatasetRecords.__call__见 records/_dataset_records.py#L195-L238返回一个DatasetRecordsIterator支持batch_size默认 256、start_offset、limit、query等参数服务端按批拉取避免一次性加载全量数据。with_vectors可以是布尔值或向量名称列表传True拉取全部向量传列表则只拉取指定向量_validate_vector_names会校验向量名是否存在于数据集 schema见 L477-L484。集成测试 test_list_records.py 覆盖了start_offset、limit、带响应列出等场景。更新记录更新记录同样通过Dataset对象的log方法完成只需提供记录的id及新的数据即可log内部按 id 判断是新增还是更新见 log 方法签名。data dataset.records.to_list(flattenTrue) updated_data [ { text: sample[text], label: positive, id: sample[id], } for sample in data ] dataset.records.log(recordsupdated_data)更新元数据Record的metadata是一个 Python 字典可迭代记录后按键更新再写回数据集!!! tip 不同MetadataProperty类型的取值格式参见 Metadata - Python Reference。updated_records [] for record in dataset.records(): record.metadata[my_metadata] new_value record.metadata[my_new_metadata] new_value updated_records.append(record) dataset.records.log(recordsupdated_records)更新向量当数据集设置中新增了向量字段或需更新已有记录的向量值时可迭代记录按键更新向量updated_records [] for record in dataset.records(with_vectorsTrue): record.vectors[my_vector] [ 0, 1, 2, 3, 4, 5 ] record.vectors[my_new_vector] [ 0, 1, 2, 3, 4, 5 ] updated_records.append(record) dataset.records.log(recordsupdated_records)更新建议可迭代记录按键更新已有 suggestion也可用add方法新增 suggestion!!! tip 不同Question类型的取值格式参见 Suggestions - Python Reference。updated_records [] for record in dataset.records(with_suggestionsTrue): # We can update existing suggestions record.suggestions[label].value new_value record.suggestions[label].score 0.9 record.suggestions[label].agent model_name # We can also add new suggestions with the add method: if not record.suggestions[label]: record.suggestions.add( rg.Suggestion(value, label, score0.9, agentmodel_name) ) updated_records.append(record) dataset.records.log(recordsupdated_records)注意RecordSuggestions.add会以问题名为键覆盖旧 suggestion每问题仅一条而RecordResponses.add则按「问题名 user_id」追加去重见 records/_resource.py#L476-L483 与 L407-L425。相关行为在集成测试 test_update_records.py 中有覆盖例如test_update_records_fields与test_update_records_suggestions_from_data。更新响应可迭代记录按键更新已有 response也可用add方法新增 response!!! tip 不同Question类型的取值格式参见 Responses - Python Reference。updated_records [] for record in dataset.records(with_responsesTrue): for response in record.responses[label]: if response: response.value new_value response.user_id existing_user_id else: record.responses.add(rg.Response(label, YES, user_iduser.id)) updated_records.append(record) dataset.records.log(recordsupdated_records)删除记录删除记录通过Dataset对象上的delete方法完成先按需检索服务端记录得到待删列表后批量删除。records_to_delete list(dataset.records)[:5] dataset.records.delete(recordsrecords_to_delete)delete内部会先经_ingest_records将Record列表解析为模型再按批默认批大小 64见DEFAULT_DELETE_BATCH_SIZE调用服务端批量删除接口见 delete 方法实现集成测试 test_delete_records.py 覆盖了批量删除、单条删除及批大小支持等场景。基于查询删除记录基于查询删除非常实用——例如可以借此避免误删已带响应的记录。关于查询语法参见 查询 how-to 指南。status_filter rg.Query( filter rg.Filter((response.status, , pending)) ) records_to_delete list(dataset.records(status_filter)) dataset.records.delete(records_to_delete)该示例中dataset.records(status_filter)返回一个带查询的DatasetRecordsIterator迭代器在_fetch_from_server_with_search中通过服务端搜索接口拉取满足response.status pending未提交响应的记录从而只删除这些尚未有正式标注的记录。小结本文完整梳理了 Argilla 记录的生命周期管理从理解 Record 的字段/元数据/向量/建议/响应五维结构到用Record对象、字典、Hugging Face Dataset 三种方式写入数据含mapping点分语法的源码原理再到列出、更新元数据/向量/建议/响应四类局部更新和按查询删除。核心 API 集中在Dataset.records的log/delete/records三个入口records/_dataset_records.py记录数据模型与容器实现在 records/_resource.py映射逻辑在 records/_mapping/_mapper.py。配合 test_add_records.py、test_update_records.py、test_delete_records.py 等集成测试可以进一步验证各类操作的实际行为。【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考