Argilla 數(shù)據(jù)集查詢與過濾實戰(zhàn)指南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本篇技術(shù)指南基于 Argilla 官方 How-to 文檔 query.md 編寫系統(tǒng)講解如何通過 Python SDK 對數(shù)據(jù)集中的記錄進行全文查詢Query、條件過濾Filter與向量相似性檢索Similar。讀完本文后你將掌握rg.Query、rg.Filter、rg.Similar三個核心類的全部用法、可過濾字段與運算符語義并能將三者自由組合出復雜的檢索表達式以及把檢索結(jié)果導出為字典、列表、JSON 或 Hugging Face Dataset。Query 與 Filter檢索的兩條路徑在 Argilla 中查詢與過濾是兩個相互獨立又互為補充的概念Query全文查詢作用于記錄的文本內(nèi)容通過搜索詞匹配文本字段返回包含指定詞的記錄。Filter條件過濾基于條件判斷篩選記錄支持對元數(shù)據(jù)、建議suggestion、作答response、狀態(tài)等字段做等值、范圍與集合包含判斷。兩者可以獨立使用也可以組合使用Query對象負責承載搜索詞與相似性向量Filter對象則以條件列表的形式嵌入Query從而構(gòu)建出復雜的復合檢索表達式。檢索結(jié)果既可以在 Python 中逐條迭代也可以通過to_list/to_dict等方式導出原文檔也明確指出可以從數(shù)據(jù)集中將記錄導出為單個字典或字典列表。核心類一覽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], )從源碼看這三個類都實現(xiàn)了api_model()方法用于把面向用戶的簡潔表達轉(zhuǎn)換為內(nèi)部檢索模型_search.pyCondition.api_model()將(field, operator, value)三元組映射為TermsFilterModel對應、in或RangeFilterModel對應、并把字段名解析為具體的過濾作用域_search.py#L38-L94Filter.api_model()把所有條件包裝進一個AndFilterModel即多個條件之間默認是AND邏輯與關(guān)系_search.py#L145-L146Query.api_model()則組裝出完整的SearchQueryModel其中query部分承載文本查詢與向量查詢filters部分承載過濾條件_search.py#L183-L200模型定義見 _models/_search.py。用搜索詞查詢記錄要對數(shù)據(jù)集做全文檢索只需通過Dataset.records傳入一個rg.Query(query...)對象即可。檢索發(fā)生在服務端的文本字段上使用搜索詞作為匹配依據(jù)。單術(shù)語搜索檢索包含某個詞的全部記錄。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)多術(shù)語搜索當傳入多個術(shù)語時所有術(shù)語都必須出現(xiàn)在記錄中才會被召回默認邏輯與。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查詢實現(xiàn)?？捎玫倪\算符匯總?cè)缦逻\算符描述示例或空格AND同時匹配兩個詞argilla distilabel或argilla distilabel返回同時包含 argilla 與 distilabel 的記錄\|OR匹配其中任意一個詞argilla \| distilabel返回包含 argilla 或 distilabel 的記錄-否定排除某個詞argilla -distilabel返回包含 argilla 且不包含 distilabel 的記錄*前綴按前綴匹配arg*返回包含任何以 arg- 開頭單詞的記錄短語精確短語匹配argilla and distilabel返回包含 argilla and distilabel 這一完整短語的記錄(與)優(yōu)先級對術(shù)語分組(argilla \| distilabel) rules返回包含 argilla 或 distilabel 且同時包含 rules 的記錄~N編輯距離按編輯距離匹配術(shù)語或短語argilla~1返回包含與 argilla 編輯距離為 1 的術(shù)語如 argila的記錄提示如果需要把上述特殊字符作為普通字符匹配請用反斜杠轉(zhuǎn)義例如1 \ 2會匹配包含短語 1 2 的記錄。值得一提的是服務端實現(xiàn)中該查詢的default_operator被設(shè)置為ANDfuzzy_transpositions被關(guān)閉analyze_wildcard為False見 commons.py#L111-L123這與文檔描述的多術(shù)語必須全部出現(xiàn)的行為一致也解釋了轉(zhuǎn)義規(guī)則與通配符的實際語義邊界。按條件過濾條件過濾使用Filter類定義條件再傳給Dataset.records。支持的運算符如下運算符描述字段值等于給定值字段值大于等于給定值字段值小于等于給定值in字段值包含在給定的值列表中條件可以用點號dot表示法組合以針對元數(shù)據(jù)、建議或作答進行過濾可以只用一個條件也可以使用多個條件多條件之間為 AND 關(guān)系見前文AndFilterModel的實現(xiàn)。單一條件例如篩選標簽字段值為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 )多個條件可以同時針對建議值、元數(shù)據(jù)范圍與多值集合進行過濾。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的構(gòu)造器同時接受元組和元組列表兩種形式內(nèi)部會把單個元組自動包裝成列表見_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記錄的內(nèi)部 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記錄狀態(tài)可取pending或completed(status, , completed)response.status作答狀態(tài)可取draft、submitted或discarded(response.status, , submitted)metadata.name按元數(shù)據(jù)屬性過濾(metadata.split, , train)question.suggestion按某道問題的建議值過濾(label.suggestion, , positive)question.score按建議分數(shù)過濾(label.score, , 0.9)question.agent按建議來源代理過濾(label.agent, , ChatGPT4.0)question.response按某道問題的作答值過濾(label.response, , negative)結(jié)合源碼可以進一步理解這些字段的語義id與_server_id的區(qū)分前者映射為記錄的external_id屬性后者映射為服務端內(nèi)部id_search.py#L64-L67status、inserted_at、updated_at屬于記錄級作用域response.status屬于作答級作用域metadata.name屬于元數(shù)據(jù)作用域而question.suggestion/.score/.agent屬于建議級作用域SuggestionFilterScopeModel的property默認值為value也支持agent、score、type見 _models/_search.py#L34-L40若字段名不匹配任何已知模式源碼會把它當作問題字段映射為針對該問題的建議值過濾_search.py#L92-L94。按狀態(tài)過濾在實際標注工作流中經(jīng)常需要按記錄的完成進度或作答的審核狀態(tài)來篩選數(shù)據(jù)。記錄狀態(tài)可取pending待標注或completed已完成作答狀態(tài)可取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 關(guān)系——上述查詢將返回記錄已完成且其作答被丟棄的記錄。相似性搜索向量檢索除了全文檢索與條件過濾Argilla 還支持基于向量的相似性搜索給定一個向量檢索與其最相似的記錄。這需要使用Similar類定義向量并作為query參數(shù)的一部分傳入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檢索要求數(shù)據(jù)集設(shè)置中已定義對應的向量字段。如果數(shù)據(jù)集沒有向量字段檢索將返回錯誤。向量字段的定義方式詳見 dataset.md 的 Vectors 小節(jié)——在創(chuàng)建數(shù)據(jù)集時通過rg.VectorField(namevector, dimensions768)之類的設(shè)置聲明向量字段對應 UI 中的向量字段配置界面可參考 vectors.png。從源碼還可以挖掘出Similar的更多能力_search.py#L100-L125name向量字段的名稱必須與數(shù)據(jù)集設(shè)置中的向量字段一致value既可以是向量數(shù)值列表也可以是一個rg.Record對象——傳入記錄時會自動使用該記錄在對應向量字段上的向量值進行檢索record_id會被序列化進請求most_similar默認True控制檢索方向設(shè)為False時返回最不相似的記錄服務端通過向量取反實現(xiàn)見 elasticsearch.py 中_inverse_vector的實現(xiàn)。底層實現(xiàn)上向量字段在 Elasticsearch 中以dense_vector類型存儲并建立索引相似度度量采用cosine余弦相似度elasticsearch.py#L74-L85檢索時通過 KNN 查詢返回排序后的結(jié)果。組合查詢與過濾如文檔開篇所述全文檢索與條件過濾并非互斥你可以把搜索詞與一個或多個過濾條件組合在同一個Query對象中構(gòu)建復雜檢索表達式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__還提供了更多可控參數(shù)batch_size每批拉取的記錄數(shù)默認 256start_offset從第幾條記錄開始拉取默認 0with_suggestions/with_responses是否攜帶建議/作答默認Truewith_vectors可傳向量名稱列表僅返回指定向量、True返回全部向量或None不返回向量limit最多拉取的記錄總數(shù)。當傳入的是普通列表無查詢條件時SDK 走records.list接口一旦Query包含搜索詞、相似性向量或過濾條件has_search()返回True則走/api/v1/datasets/{dataset_id}/records/search檢索接口_records.py#L106-L138并把query_score一并返回相似性檢索場景下迭代器會產(chǎn)出(record, score)元組見 _dataset_records.py#L112-L120。檢索結(jié)果的導出dataset.records(...)返回的是惰性迭代器DatasetRecordsIterator支持直接for record in iterator逐條迭代同時它還提供了豐富的導出方法_dataset_records.py#L150-L161to_list(flattenTrue|False)導出為字典列表。flattenTrue時字段、元數(shù)據(jù)、建議、作答被扁平化并使用點號表示法如label.suggestion、label.responseflattenFalse時保持嵌套結(jié)構(gòu)to_dict(flatten..., orientnames|index)導出為單個字典orientnames以屬性名為鍵orientindex以記錄 ID 為鍵to_json(path...)將記錄寫入本地 JSON 文件to_datasets()導出為 Hugging Facedatasets.Dataset方便后續(xù)用于訓練或分享。例如本文各示例中的.to_list(flattenTrue)即把檢索命中的記錄扁平化為字典列表在導出to_datasets的場景下檢索出的子集會完整保留字段、元數(shù)據(jù)、建議與作答信息參考 _hub.py 中with_vectorsTrue, with_responsesTrue, with_suggestionsTrue的組合用法。從 SDK 到服務端的完整檢索鏈路為了加深理解這里把一次檢索請求的完整鏈路梳理如下這也是集成測試 test_query_records.py 驗證過的行為路徑客戶端組裝rg.Query/rg.Filter/rg.Similar通過各自的api_model()轉(zhuǎn)換為SearchQueryModel_search.py、_models/_search.pyHTTP 請求RecordsAPI.search向POST /api/v1/datasets/{dataset_id}/records/search發(fā)送檢索請求攜帶query、filters、offset、limit與include參數(shù)_records.py#L106-L138服務端翻譯文本查詢被翻譯為 Elasticsearchsimple_query_string默認 AND 操作符過濾條件被翻譯為terms/range查詢向量檢索被翻譯為dense_vector上的 KNN 查詢commons.py、elasticsearch.py結(jié)果回流服務端返回命中的記錄與query_score客戶端逐批迭代并組裝為rg.Record對象。掌握這條鏈路后你就能在排查檢索結(jié)果不符合預期時快速定位問題出在客戶端參數(shù)組裝、服務端查詢翻譯還是索引映射配置上例如多術(shù)語為什么變成了 AND 語義相似性檢索為什么返回錯誤缺少向量字段定義label與label.suggestion的過濾差異等常見問題都可以在上文對應的源碼位置找到答案?！久赓M下載鏈接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets項目地址: https://gitcode.com/GitHub_Trending/ar/argilla創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考