Argilla 数据集查询与过滤实战指南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本篇技术指南基于 Argilla 官方 How-to 文档 query.md 编写系统讲解如何通过 Python SDK 对数据集中的记录进行全文查询Query、条件过滤Filter与向量相似性检索Similar。读完本文后你将掌握rg.Query、rg.Filter、rg.Similar三个核心类的全部用法、可过滤字段与运算符语义并能将三者自由组合出复杂的检索表达式以及把检索结果导出为字典、列表、JSON 或 Hugging Face Dataset。Query 与 Filter检索的两条路径在 Argilla 中查询与过滤是两个相互独立又互为补充的概念Query全文查询作用于记录的文本内容通过搜索词匹配文本字段返回包含指定词的记录。Filter条件过滤基于条件判断筛选记录支持对元数据、建议suggestion、作答response、状态等字段做等值、范围与集合包含判断。两者可以独立使用也可以组合使用Query对象负责承载搜索词与相似性向量Filter对象则以条件列表的形式嵌入Query从而构建出复杂的复合检索表达式。检索结果既可以在 Python 中逐条迭代也可以通过to_list/to_dict等方式导出原文档也明确指出可以从数据集中将记录导出为单个字典或字典列表。核心类一览rg.Query / rg.Filter / rg.Similar检索功能由argilla.records._search模块中的三个类支撑它们的 Python API 签名如下完整属性与方法详见 search.md 参考文档# 全文查询 可选过滤条件的组合容器 rg.Query( queryquery, # 搜索词字符串 filterfilter # 一个 rg.Filter 实例或条件元组/列表 ) # 条件过滤器 rg.Filter( [ (field, , value), ] ) # 向量相似性检索 rg.Similar( namevector, value[0.1, 0.2, 0.3], )从源码看这三个类都实现了api_model()方法用于把面向用户的简洁表达转换为内部检索模型_search.pyCondition.api_model()将(field, operator, value)三元组映射为TermsFilterModel对应、in或RangeFilterModel对应、并把字段名解析为具体的过滤作用域_search.py#L38-L94Filter.api_model()把所有条件包装进一个AndFilterModel即多个条件之间默认是AND逻辑与关系_search.py#L145-L146Query.api_model()则组装出完整的SearchQueryModel其中query部分承载文本查询与向量查询filters部分承载过滤条件_search.py#L183-L200模型定义见 _models/_search.py。用搜索词查询记录要对数据集做全文检索只需通过Dataset.records传入一个rg.Query(query...)对象即可。检索发生在服务端的文本字段上使用搜索词作为匹配依据。单术语搜索检索包含某个词的全部记录。import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset, workspacemy_workspace) query rg.Query(querymy_term) queried_records dataset.records(queryquery).to_list(flattenTrue)多术语搜索当传入多个术语时所有术语都必须出现在记录中才会被召回默认逻辑与。import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset, workspacemy_workspace) query rg.Query(querymy_term1 my_term2) queried_records dataset.records(queryquery).to_list(flattenTrue)这里可以直接传字符串作为dataset.records(querymy_term)的快捷写法——从 _dataset_records.py#L222-L223 可以看到字符串形式会被自动包装为Query(queryquery)。高级查询Elasticsearch 简单查询字符串语法如果需要更复杂的检索Argilla 底层复用了Elasticsearch 的 simple query string syntax服务端在 search_engine/commons.py#L111-L123 中通过simple_query_string查询实现。可用的运算符汇总如下运算符描述示例或空格AND同时匹配两个词argilla distilabel或argilla distilabel返回同时包含 argilla 与 distilabel 的记录\|OR匹配其中任意一个词argilla \| distilabel返回包含 argilla 或 distilabel 的记录-否定排除某个词argilla -distilabel返回包含 argilla 且不包含 distilabel 的记录*前缀按前缀匹配arg*返回包含任何以 arg- 开头单词的记录短语精确短语匹配argilla and distilabel返回包含 argilla and distilabel 这一完整短语的记录(与)优先级对术语分组(argilla \| distilabel) rules返回包含 argilla 或 distilabel 且同时包含 rules 的记录~N编辑距离按编辑距离匹配术语或短语argilla~1返回包含与 argilla 编辑距离为 1 的术语如 argila的记录提示如果需要把上述特殊字符作为普通字符匹配请用反斜杠转义例如1 \ 2会匹配包含短语 1 2 的记录。值得一提的是服务端实现中该查询的default_operator被设置为ANDfuzzy_transpositions被关闭analyze_wildcard为False见 commons.py#L111-L123这与文档描述的多术语必须全部出现的行为一致也解释了转义规则与通配符的实际语义边界。按条件过滤条件过滤使用Filter类定义条件再传给Dataset.records。支持的运算符如下运算符描述字段值等于给定值字段值大于等于给定值字段值小于等于给定值in字段值包含在给定的值列表中条件可以用点号dot表示法组合以针对元数据、建议或作答进行过滤可以只用一个条件也可以使用多个条件多条件之间为 AND 关系见前文AndFilterModel的实现。单一条件例如筛选标签字段值为positive的记录。import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset, workspacemy_workspace) filter_label rg.Filter((label, , positive)) filtered_records dataset.records(queryrg.Query(filterfilter_label)).to_list( flattenTrue )多个条件可以同时针对建议值、元数据范围与多值集合进行过滤。import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset, workspacemy_workspace) 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)从源码看Filter的构造器同时接受元组和元组列表两种形式内部会把单个元组自动包装成列表见_search.py#L131-L143因此rg.Filter((label, , positive))与rg.Filter([(label, , positive)])完全等价。运算符映射逻辑位于Condition.api_model()与in生成terms过滤器与生成range过滤器其余运算符会抛出ValueError_search.py#L41-L57。服务端相应地将这些模型翻译为 Elasticsearch 的terms与range查询commons.py#L64-L78。可过滤字段一览过滤条件的field部分支持以下字段_extract_filter_scope的解析逻辑见 _search.py#L59-L94字段描述示例id记录的外部ID(id, in, [1,2,3])_server_id记录的内部 ID必须是合法 UUID(_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按建议来源代理过滤(label.agent, , ChatGPT4.0)question.response按某道问题的作答值过滤(label.response, , negative)结合源码可以进一步理解这些字段的语义id与_server_id的区分前者映射为记录的external_id属性后者映射为服务端内部id_search.py#L64-L67status、inserted_at、updated_at属于记录级作用域response.status属于作答级作用域metadata.name属于元数据作用域而question.suggestion/.score/.agent属于建议级作用域SuggestionFilterScopeModel的property默认值为value也支持agent、score、type见 _models/_search.py#L34-L40若字段名不匹配任何已知模式源码会把它当作问题字段映射为针对该问题的建议值过滤_search.py#L92-L94。按状态过滤在实际标注工作流中经常需要按记录的完成进度或作答的审核状态来筛选数据。记录状态可取pending待标注或completed已完成作答状态可取draft草稿、submitted已提交或discarded已丢弃。两者可以叠加使用import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset, workspacemy_workspace) status_filter rg.Query( filterrg.Filter( [ (status, , completed), (response.status, , discarded) ] ) ) filtered_records dataset.records(status_filter).to_list(flattenTrue)这个示例同时演示了两个要点status与response.status是两个独立的作用域记录级 vs 作答级且多条件之间是 AND 关系——上述查询将返回记录已完成且其作答被丢弃的记录。相似性搜索向量检索除了全文检索与条件过滤Argilla 还支持基于向量的相似性搜索给定一个向量检索与其最相似的记录。这需要使用Similar类定义向量并作为query参数的一部分传入Dataset.records。import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset, workspacemy_workspace) similar_filter rg.Query( similarrg.Similar( namevector, value[0.1, 0.2, 0.3], ) ) filtered_records dataset.records(similar_filter).to_list(flattenTrue)注意Similar检索要求数据集设置中已定义对应的向量字段。如果数据集没有向量字段检索将返回错误。向量字段的定义方式详见 dataset.md 的 Vectors 小节——在创建数据集时通过rg.VectorField(namevector, dimensions768)之类的设置声明向量字段对应 UI 中的向量字段配置界面可参考 vectors.png。从源码还可以挖掘出Similar的更多能力_search.py#L100-L125name向量字段的名称必须与数据集设置中的向量字段一致value既可以是向量数值列表也可以是一个rg.Record对象——传入记录时会自动使用该记录在对应向量字段上的向量值进行检索record_id会被序列化进请求most_similar默认True控制检索方向设为False时返回最不相似的记录服务端通过向量取反实现见 elasticsearch.py 中_inverse_vector的实现。底层实现上向量字段在 Elasticsearch 中以dense_vector类型存储并建立索引相似度度量采用cosine余弦相似度elasticsearch.py#L74-L85检索时通过 KNN 查询返回排序后的结果。组合查询与过滤如文档开篇所述全文检索与条件过滤并非互斥你可以把搜索词与一个或多个过滤条件组合在同一个Query对象中构建复杂检索表达式import argilla as rg client rg.Argilla(api_urlapi_url, api_keyapi_key) dataset client.datasets(namemy_dataset, workspacemy_workspace) query_filter rg.Query( querymy_term, filterrg.Filter( [ (label.suggestion, , positive), (metadata.count, , 10), ] ) ) queried_filtered_records dataset.records( queryquery_filter, with_metadataTrue, with_suggestionsTrue ).to_list(flattenTrue)这里with_metadataTrue与with_suggestionsTrue控制返回记录中携带的附属信息。在 _dataset_records.py#L195-L238 中DatasetRecords.__call__还提供了更多可控参数batch_size每批拉取的记录数默认 256start_offset从第几条记录开始拉取默认 0with_suggestions/with_responses是否携带建议/作答默认Truewith_vectors可传向量名称列表仅返回指定向量、True返回全部向量或None不返回向量limit最多拉取的记录总数。当传入的是普通列表无查询条件时SDK 走records.list接口一旦Query包含搜索词、相似性向量或过滤条件has_search()返回True则走/api/v1/datasets/{dataset_id}/records/search检索接口_records.py#L106-L138并把query_score一并返回相似性检索场景下迭代器会产出(record, score)元组见 _dataset_records.py#L112-L120。检索结果的导出dataset.records(...)返回的是惰性迭代器DatasetRecordsIterator支持直接for record in iterator逐条迭代同时它还提供了丰富的导出方法_dataset_records.py#L150-L161to_list(flattenTrue|False)导出为字典列表。flattenTrue时字段、元数据、建议、作答被扁平化并使用点号表示法如label.suggestion、label.responseflattenFalse时保持嵌套结构to_dict(flatten..., orientnames|index)导出为单个字典orientnames以属性名为键orientindex以记录 ID 为键to_json(path...)将记录写入本地 JSON 文件to_datasets()导出为 Hugging Facedatasets.Dataset方便后续用于训练或分享。例如本文各示例中的.to_list(flattenTrue)即把检索命中的记录扁平化为字典列表在导出to_datasets的场景下检索出的子集会完整保留字段、元数据、建议与作答信息参考 _hub.py 中with_vectorsTrue, with_responsesTrue, with_suggestionsTrue的组合用法。从 SDK 到服务端的完整检索链路为了加深理解这里把一次检索请求的完整链路梳理如下这也是集成测试 test_query_records.py 验证过的行为路径客户端组装rg.Query/rg.Filter/rg.Similar通过各自的api_model()转换为SearchQueryModel_search.py、_models/_search.pyHTTP 请求RecordsAPI.search向POST /api/v1/datasets/{dataset_id}/records/search发送检索请求携带query、filters、offset、limit与include参数_records.py#L106-L138服务端翻译文本查询被翻译为 Elasticsearchsimple_query_string默认 AND 操作符过滤条件被翻译为terms/range查询向量检索被翻译为dense_vector上的 KNN 查询commons.py、elasticsearch.py结果回流服务端返回命中的记录与query_score客户端逐批迭代并组装为rg.Record对象。掌握这条链路后你就能在排查检索结果不符合预期时快速定位问题出在客户端参数组装、服务端查询翻译还是索引映射配置上例如多术语为什么变成了 AND 语义相似性检索为什么返回错误缺少向量字段定义label与label.suggestion的过滤差异等常见问题都可以在上文对应的源码位置找到答案。【免费下载链接】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），仅供参考