Argilla 记录检索指南使用 rg.Query、rg.Filter 与 rg.Similar 构建数据集搜索与过滤【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argillaArgilla 提供了一套声明式的 Python 检索 API用于按文本词条、结构化条件与向量相似度从数据集中获取记录。本文以 search.md 为骨架结合 查询实操指南 与 Python 客户端源码完整讲解rg.Query、rg.Filter、rg.Similar三大类的用法、支持的字段与操作符、底层请求模型并给出可直接复制运行的代码示例。读完本文你将掌握在 Argilla 中组合全文搜索、条件过滤与向量相似度检索的完整实战方案。核心类概览Query、Filter 与 Similar在 Argilla 的 Python SDK 中记录检索由三个类协作完成rg.Query定义一次检索的完整条件。它既可以只携带一个文本查询串query也可以携带一个Filter对象filter还可以携带一个Similar向量检索对象similar三者可以任意组合。rg.Filter定义结构化的过滤条件集合每个条件是一个(字段, 操作符, 值)三元组。Filter会被传入Query多个条件之间按AND与关系组合。rg.Similar定义基于向量字段的相似度检索支持最相似与最不相似两种排序方向。三者最终都会被转换为内部的 Pydantic 模型见 argilla/src/argilla/_models/_search.py并通过Dataset.records(query...)发送到 Argilla Server 执行。Query 的构造参数从 Query 源码 可以看到Query支持三个关键字参数参数类型说明queryUnion[str, None]文本查询串用于在记录文本字段中搜索词条similarUnion[Similar, None]相似度检索对象基于向量字段查找相似记录filterUnion[Filter, Conditions, None]过滤条件可以是Filter对象、单个(字段, 操作符, 值)元组或元组列表其中filter参数非常灵活直接传一个元组(label, , positive)或一个元组列表[(a, , 1), (b, in, [2, 3])]都会被自动包装成Filter对象。Filter 的构造方式Filter接受单个条件元组或条件元组列表import argilla as rg # 单个条件 single rg.Filter((label, , positive)) # 多个条件AND 组合 multiple rg.Filter( [ (metadata.count, , 10), (metadata.count, , 20), ] )每个条件的结构为(field, operator, value)其中field支持点号dot notation语法可以深入到记录的 metadata、suggestion 或 response 属性详见下文支持的过滤字段。按搜索词检索记录最直接的检索方式是向Dataset.records传入一个查询字符串。该字符串会在记录的文本字段中进行全文匹配支持单个词条与多个词条多个词条必须全部出现在记录中才会被命中import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset, workspacemy_workspace) # 单词条搜索 for record in dataset.records(queryparis): print(record) # 多词条搜索全部词条需同时出现 query rg.Query(querymy_term1 my_term2) records dataset.records(queryquery).to_list(flattenTrue)需要说明的是直接传入字符串时DatasetRecords.call会将其自动包装为Query(query...)因此dataset.records(queryparis)与dataset.records(queryrg.Query(queryparis))完全等价。说明dataset.records(...)返回的是一个惰性迭代器只有真正开始迭代如for循环或调用.to_list()时才会向服务器分批拉取记录。默认批大小为 256可通过batch_size参数调整见 DatasetRecords.call。高级文本查询语法当需要更复杂的文本检索时query字符串支持 Elasticsearch 的 simple query string 语法。下表总结了常用操作符详见 query.md操作符含义示例或空格AND两个词条都出现argilla distilabel\|OR任一词条出现argilla \| distilabel-否定排除词条argilla -distilabel*前缀匹配arg*匹配所有以 arg 开头的词短语精确匹配argilla and distilabel(与)分组与优先级(argilla \| distilabel) rules~N编辑距离模糊匹配argilla~1可匹配 argila若需按字面匹配这些特殊字符可用反斜杠转义例如1 \ 2匹配包含短语 1 2 的记录。按条件过滤记录Filter支持四种比较操作符见 query.md操作符含义字段值等于给定值字段值大于等于给定值字段值小于等于给定值in字段值在给定列表中文档中的经典示例——按 metadata 数值区间过滤并叠加文本搜索import argilla as rg # 构造 10 到 20 的数值区间过滤 range_filter rg.Filter( [ (metadata.count, , 10), (metadata.count, , 20), ] ) # 组合文本搜索与过滤命中 paris 且 count 落在 [10, 20] 的记录 query rg.Query(filtersrange_filter, queryparis) # 迭代结果 for record in dataset.records(queryquery): print(record)多个条件同时出现时按AND语义组合。这一点在 Filter.api_model 中体现得很清楚——所有条件会被打包进一个AndFilterModel。也就是说(label, , positive)与(label, , negative)同时出现时结果为空没有任何记录同时等于两个值这一点由集成测试 test_query_records.py 明确验证。支持的过滤字段Filter的字段名支持点号语法可以深入记录的不同实体。字段名到内部过滤作用域filter scope的映射实现在 Condition._extract_filter_scope支持的字段如下字段说明示例id记录的外部 ID(id, in, [1, 2, 3])_server_id服务器内部记录 IDUUID(_server_id, , ba69a996-85c2-4af0-a473-23138929641b)inserted_at记录插入时间datetime 或字符串(inserted_at, , 2024-10-10)updated_at记录更新时间(updated_at, , 2024-10-10)status记录状态pending/completed(status, , completed)response.status响应状态draft/submitted/discarded(response.status, , submitted)metadata.name元数据属性(metadata.split, , train)question.suggestion问题建议值(label.suggestion, , positive)question.score建议分数(label.score, , 0.9)question.agent建议来源 Agent(label.agent, , ChatGPT4.0)question.type建议类型如human/model(label.type, , human)question.response问题响应值(label.response, , negative)从 ScopeModel 定义 可以看到过滤作用域共分四类实体record记录属性、response响应、suggestion建议、metadata元数据。例如字段label.suggestion会被解析为以label为 question 的SuggestionFilterScopeModel而metadata.count会被解析为MetadataFilterScopeModel。一个综合运用多字段条件的示例filters rg.Filter( [ (label.suggestion, , positive), (metadata.count, , 10), (metadata.count, , 20), (label, in, [positive, negative]), ] ) filtered_records dataset.records(queryrg.Query(filterfilters), with_suggestionsTrue).to_list(flattenTrue)按状态过滤记录记录状态与响应状态是标注工作流中非常常用的过滤维度status_filter rg.Query( filterrg.Filter( [ (status, , completed), # 记录状态pending / completed (response.status, , discarded) # 响应状态draft / submitted / discarded ] ) ) filtered_records dataset.records(status_filter).to_list(flattenTrue)该用法同样在源码层面得到印证status字段映射到RecordFilterScopeModel(propertystatus)response.status映射到ResponseFilterScopeModel(propertystatus)见 Condition._extract_filter_scope。向量相似度检索Similar当数据集配置了向量字段VectorField时可以使用Similar进行语义相似检索。Similar的构造参数如下见 Similar 源码参数类型说明namestr向量字段名称valueIterable[float]或Record向量值或一个已有的Record对象此时以其向量作为查询向量most_similarboolTrue查找最相似的记录False查找最不相似的记录# 按向量值检索最相似记录 similar_query rg.Query( similarrg.Similar( namevector, value[0.1, 0.2, 0.3], ) ) records dataset.records(similar_query).to_list(flattenTrue) # 以现有记录作为查询向量检索最不相似记录 record next(iter(dataset.records(limit1, with_vectorsFalse))) least_similar dataset.records( queryrg.Query(similarrg.Similar(namevector, valuerecord, most_similarFalse)) ).to_list(flattenTrue)当以Record作为value时SDK 会提取该记录的服务端 ID_server_id生成VectorQueryModel(record_id...)当提供原始向量列表时则生成VectorQueryModel(value...)见 Similar.api_model。排序方向由order字段表达取值most_similar或least_similar见 VectorQueryModel。注意相似度检索要求数据集设置中必须包含对应的向量字段定义否则服务器会返回错误。向量字段的定义方式可参考 dataset.md 中的 Vectors 章节。使用相似度检索时迭代器返回的元素是(Record, score)元组其中score是服务器返回的查询得分——这一点可以从 DatasetRecordsIterator._list 的实现看到。组合检索搜索词 过滤条件Query的核心价值在于把全文搜索与结构化过滤组合成一次检索请求query_filter rg.Query( querymy_term, filterrg.Filter( [ (label.suggestion, , positive), (metadata.count, , 10), ] ) ) records dataset.records(queryquery_filter, with_suggestionsTrue).to_list(flattenTrue)底层调用链一次组合检索在 SDK 内部的完整路径如下Dataset.records(query...)创建 DatasetRecordsIterator并通过Query.has_search()判断是否走搜索接口见 _is_search_queryQuery.api_model()将文本、向量与过滤条件组装为SearchQueryModel文本部分包装为TextQueryModel(q...)向量部分包装为VectorQueryModel过滤部分包装为AndFilterModel见 Query.api_model客户端调用RecordsAPI.search向POST /api/v1/datasets/{dataset_id}/records/search发起请求并在响应中解析出每条记录的query_score与命中总数total见 argilla/src/argilla/_api/_records.py#L105-L138。值得注意的是Query的 API 模型SearchQueryModel是可选结构的没有文本搜索也没有向量检索时query部分为空没有过滤条件时filters部分为空。这意味着你完全可以只传filter不传query或反过来。测试验证检索行为的可靠依据仓库中的集成测试为上述用法提供了可复现的行为依据test_query_records.py验证了按文本词条检索queryfirst只命中 1 条、按建议值过滤(label, , positive)命中 2 条、in操作符与 AND 语义test_search_records.py覆盖了按id、_server_id、inserted_at、updated_at过滤按sentiment.agent/sentiment.type过滤以及Similar的最相似 / 最不相似 / 以记录为查询向量的全部场景test_export_records.py验证了带rg.Query(queryhello)检索结果的导出链路。这些测试同时展示了Filter的三种等价写法元组、元组列表、以及直接嵌入Query(filter...)实际使用时可按可读性任选其一。小结Argilla 的检索 API 设计简洁且组合能力强文本搜索解决内容里有什么的问题条件过滤解决结构上满足什么的问题向量相似度解决语义上像什么的问题。三者通过一个rg.Query对象即可任意组合并由 SDK 自动转换为服务器可执行的检索模型。若需进一步了解向量字段配置、记录导出等相邻能力可继续阅读 query.md、dataset.md 与 record.md若需查看完整 API 签名可参考 search.md 中对Query、Filter、Similar三类对象的逐项说明。【免费下载链接】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 记录检索指南：使用 rg.Query、rg.Filter 与 rg.Similar 构建数据集搜索与过滤
Argilla 记录检索指南使用 rg.Query、rg.Filter 与 rg.Similar 构建数据集搜索与过滤【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argillaArgilla 提供了一套声明式的 Python 检索 API用于按文本词条、结构化条件与向量相似度从数据集中获取记录。本文以 search.md 为骨架结合 查询实操指南 与 Python 客户端源码完整讲解rg.Query、rg.Filter、rg.Similar三大类的用法、支持的字段与操作符、底层请求模型并给出可直接复制运行的代码示例。读完本文你将掌握在 Argilla 中组合全文搜索、条件过滤与向量相似度检索的完整实战方案。核心类概览Query、Filter 与 Similar在 Argilla 的 Python SDK 中记录检索由三个类协作完成rg.Query定义一次检索的完整条件。它既可以只携带一个文本查询串query也可以携带一个Filter对象filter还可以携带一个Similar向量检索对象similar三者可以任意组合。rg.Filter定义结构化的过滤条件集合每个条件是一个(字段, 操作符, 值)三元组。Filter会被传入Query多个条件之间按AND与关系组合。rg.Similar定义基于向量字段的相似度检索支持最相似与最不相似两种排序方向。三者最终都会被转换为内部的 Pydantic 模型见 argilla/src/argilla/_models/_search.py并通过Dataset.records(query...)发送到 Argilla Server 执行。Query 的构造参数从 Query 源码 可以看到Query支持三个关键字参数参数类型说明queryUnion[str, None]文本查询串用于在记录文本字段中搜索词条similarUnion[Similar, None]相似度检索对象基于向量字段查找相似记录filterUnion[Filter, Conditions, None]过滤条件可以是Filter对象、单个(字段, 操作符, 值)元组或元组列表其中filter参数非常灵活直接传一个元组(label, , positive)或一个元组列表[(a, , 1), (b, in, [2, 3])]都会被自动包装成Filter对象。Filter 的构造方式Filter接受单个条件元组或条件元组列表import argilla as rg # 单个条件 single rg.Filter((label, , positive)) # 多个条件AND 组合 multiple rg.Filter( [ (metadata.count, , 10), (metadata.count, , 20), ] )每个条件的结构为(field, operator, value)其中field支持点号dot notation语法可以深入到记录的 metadata、suggestion 或 response 属性详见下文支持的过滤字段。按搜索词检索记录最直接的检索方式是向Dataset.records传入一个查询字符串。该字符串会在记录的文本字段中进行全文匹配支持单个词条与多个词条多个词条必须全部出现在记录中才会被命中import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset, workspacemy_workspace) # 单词条搜索 for record in dataset.records(queryparis): print(record) # 多词条搜索全部词条需同时出现 query rg.Query(querymy_term1 my_term2) records dataset.records(queryquery).to_list(flattenTrue)需要说明的是直接传入字符串时DatasetRecords.call会将其自动包装为Query(query...)因此dataset.records(queryparis)与dataset.records(queryrg.Query(queryparis))完全等价。说明dataset.records(...)返回的是一个惰性迭代器只有真正开始迭代如for循环或调用.to_list()时才会向服务器分批拉取记录。默认批大小为 256可通过batch_size参数调整见 DatasetRecords.call。高级文本查询语法当需要更复杂的文本检索时query字符串支持 Elasticsearch 的 simple query string 语法。下表总结了常用操作符详见 query.md操作符含义示例或空格AND两个词条都出现argilla distilabel\|OR任一词条出现argilla \| distilabel-否定排除词条argilla -distilabel*前缀匹配arg*匹配所有以 arg 开头的词短语精确匹配argilla and distilabel(与)分组与优先级(argilla \| distilabel) rules~N编辑距离模糊匹配argilla~1可匹配 argila若需按字面匹配这些特殊字符可用反斜杠转义例如1 \ 2匹配包含短语 1 2 的记录。按条件过滤记录Filter支持四种比较操作符见 query.md操作符含义字段值等于给定值字段值大于等于给定值字段值小于等于给定值in字段值在给定列表中文档中的经典示例——按 metadata 数值区间过滤并叠加文本搜索import argilla as rg # 构造 10 到 20 的数值区间过滤 range_filter rg.Filter( [ (metadata.count, , 10), (metadata.count, , 20), ] ) # 组合文本搜索与过滤命中 paris 且 count 落在 [10, 20] 的记录 query rg.Query(filtersrange_filter, queryparis) # 迭代结果 for record in dataset.records(queryquery): print(record)多个条件同时出现时按AND语义组合。这一点在 Filter.api_model 中体现得很清楚——所有条件会被打包进一个AndFilterModel。也就是说(label, , positive)与(label, , negative)同时出现时结果为空没有任何记录同时等于两个值这一点由集成测试 test_query_records.py 明确验证。支持的过滤字段Filter的字段名支持点号语法可以深入记录的不同实体。字段名到内部过滤作用域filter scope的映射实现在 Condition._extract_filter_scope支持的字段如下字段说明示例id记录的外部 ID(id, in, [1, 2, 3])_server_id服务器内部记录 IDUUID(_server_id, , ba69a996-85c2-4af0-a473-23138929641b)inserted_at记录插入时间datetime 或字符串(inserted_at, , 2024-10-10)updated_at记录更新时间(updated_at, , 2024-10-10)status记录状态pending/completed(status, , completed)response.status响应状态draft/submitted/discarded(response.status, , submitted)metadata.name元数据属性(metadata.split, , train)question.suggestion问题建议值(label.suggestion, , positive)question.score建议分数(label.score, , 0.9)question.agent建议来源 Agent(label.agent, , ChatGPT4.0)question.type建议类型如human/model(label.type, , human)question.response问题响应值(label.response, , negative)从 ScopeModel 定义 可以看到过滤作用域共分四类实体record记录属性、response响应、suggestion建议、metadata元数据。例如字段label.suggestion会被解析为以label为 question 的SuggestionFilterScopeModel而metadata.count会被解析为MetadataFilterScopeModel。一个综合运用多字段条件的示例filters rg.Filter( [ (label.suggestion, , positive), (metadata.count, , 10), (metadata.count, , 20), (label, in, [positive, negative]), ] ) filtered_records dataset.records(queryrg.Query(filterfilters), with_suggestionsTrue).to_list(flattenTrue)按状态过滤记录记录状态与响应状态是标注工作流中非常常用的过滤维度status_filter rg.Query( filterrg.Filter( [ (status, , completed), # 记录状态pending / completed (response.status, , discarded) # 响应状态draft / submitted / discarded ] ) ) filtered_records dataset.records(status_filter).to_list(flattenTrue)该用法同样在源码层面得到印证status字段映射到RecordFilterScopeModel(propertystatus)response.status映射到ResponseFilterScopeModel(propertystatus)见 Condition._extract_filter_scope。向量相似度检索Similar当数据集配置了向量字段VectorField时可以使用Similar进行语义相似检索。Similar的构造参数如下见 Similar 源码参数类型说明namestr向量字段名称valueIterable[float]或Record向量值或一个已有的Record对象此时以其向量作为查询向量most_similarboolTrue查找最相似的记录False查找最不相似的记录# 按向量值检索最相似记录 similar_query rg.Query( similarrg.Similar( namevector, value[0.1, 0.2, 0.3], ) ) records dataset.records(similar_query).to_list(flattenTrue) # 以现有记录作为查询向量检索最不相似记录 record next(iter(dataset.records(limit1, with_vectorsFalse))) least_similar dataset.records( queryrg.Query(similarrg.Similar(namevector, valuerecord, most_similarFalse)) ).to_list(flattenTrue)当以Record作为value时SDK 会提取该记录的服务端 ID_server_id生成VectorQueryModel(record_id...)当提供原始向量列表时则生成VectorQueryModel(value...)见 Similar.api_model。排序方向由order字段表达取值most_similar或least_similar见 VectorQueryModel。注意相似度检索要求数据集设置中必须包含对应的向量字段定义否则服务器会返回错误。向量字段的定义方式可参考 dataset.md 中的 Vectors 章节。使用相似度检索时迭代器返回的元素是(Record, score)元组其中score是服务器返回的查询得分——这一点可以从 DatasetRecordsIterator._list 的实现看到。组合检索搜索词 过滤条件Query的核心价值在于把全文搜索与结构化过滤组合成一次检索请求query_filter rg.Query( querymy_term, filterrg.Filter( [ (label.suggestion, , positive), (metadata.count, , 10), ] ) ) records dataset.records(queryquery_filter, with_suggestionsTrue).to_list(flattenTrue)底层调用链一次组合检索在 SDK 内部的完整路径如下Dataset.records(query...)创建 DatasetRecordsIterator并通过Query.has_search()判断是否走搜索接口见 _is_search_queryQuery.api_model()将文本、向量与过滤条件组装为SearchQueryModel文本部分包装为TextQueryModel(q...)向量部分包装为VectorQueryModel过滤部分包装为AndFilterModel见 Query.api_model客户端调用RecordsAPI.search向POST /api/v1/datasets/{dataset_id}/records/search发起请求并在响应中解析出每条记录的query_score与命中总数total见 argilla/src/argilla/_api/_records.py#L105-L138。值得注意的是Query的 API 模型SearchQueryModel是可选结构的没有文本搜索也没有向量检索时query部分为空没有过滤条件时filters部分为空。这意味着你完全可以只传filter不传query或反过来。测试验证检索行为的可靠依据仓库中的集成测试为上述用法提供了可复现的行为依据test_query_records.py验证了按文本词条检索queryfirst只命中 1 条、按建议值过滤(label, , positive)命中 2 条、in操作符与 AND 语义test_search_records.py覆盖了按id、_server_id、inserted_at、updated_at过滤按sentiment.agent/sentiment.type过滤以及Similar的最相似 / 最不相似 / 以记录为查询向量的全部场景test_export_records.py验证了带rg.Query(queryhello)检索结果的导出链路。这些测试同时展示了Filter的三种等价写法元组、元组列表、以及直接嵌入Query(filter...)实际使用时可按可读性任选其一。小结Argilla 的检索 API 设计简洁且组合能力强文本搜索解决内容里有什么的问题条件过滤解决结构上满足什么的问题向量相似度解决语义上像什么的问题。三者通过一个rg.Query对象即可任意组合并由 SDK 自动转换为服务器可执行的检索模型。若需进一步了解向量字段配置、记录导出等相邻能力可继续阅读 query.md、dataset.md 与 record.md若需查看完整 API 签名可参考 search.md 中对Query、Filter、Similar三类对象的逐项说明。【免费下载链接】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），仅供参考