，一次講透度量學習模型評估)
pytorch-metric-learning Testers 完整指南從選型到訓練閉環(huán)一次講透度量學習模型評估【免費下載鏈接】ocpFAIR Chemistrys library of machine learning methods for chemistry項目地址: https://gitcode.com/GitHub_Trending/oc/ocppytorch-metric-learning 的 Testers評估器是度量學習鏈路里的考官拿到訓練好的模型trunk embedder和數據集劃分后它為每個樣本批量算出嵌入向量可以理解為樣本指紋再基于最近鄰檢索給模型打出一組精度分數。本文按先選型 → 走鏈路 → 讀結果 → 接閉環(huán)的順序展開覆蓋 Testers 的完整用法、指標輸出解讀以及如何用 logging_presets 實現訓練—驗證—保存最佳模型的閉環(huán)。速覽評估器卡在數據 → 嵌入 → 檢索 → 指標的哪一環(huán)Testers 不參與梯度更新是純評估組件。它的內部流程固定為四步嵌入生成把dataset_dict里每個 split 的樣本過一遍模型eval()模式 無梯度得到高維嵌入檢索默認用 faiss 后端FaissKNN在 reference 集合中為每條 query 做 k-NN指標計算把 query/reference 的嵌入與標簽交給AccuracyCalculator產出precision_at_1、r_precision、NMI 等指標輸出結果寫入tester.all_accuracies嵌套字典split → 指標名 → 數值并可觸發(fā)可視化與end_of_testing_hook。一句話總結你提供模型和數據它交回一張分數表。下這張圖是模型評估對比圖的常見畫法一軸是誤差指標、一軸是推理開銷理解 Testers 輸出時可以套用同樣的視角一張表里同時回答準不準和貴不貴。調用形態(tài)非常統(tǒng)一所有測試器都是這么用的from pytorch_metric_learning import testers t testers.GlobalEmbeddingSpaceTester() dataset_dict {train: train_ds, val: val_ds} all_accuracies t.test(dataset_dict, epoch, trunk, embedder) # embedder 可省略先選型我該用哪個 Tester結論先行90% 的場景用GlobalEmbeddingSpaceTester只有當標簽帶層級、或你的損失函數是TwoStreamMetricLoss時才需要另外兩個。三者的邊界如下源碼位于 src/pytorch_metric_learning/testers/Tester適用場景數據要求關鍵限制GlobalEmbeddingSpaceTester通用評估看嵌入空間中所有點的最近鄰質量__getitem__返回(data, labels)無特殊限制splits_to_eval任意組合WithSameParentLabelTester標簽有層級如 animal → cat/dog只在與 query 同父類兄弟的樣本里檢索二維標簽(num_samples, 層級數)第L1維是父標簽只能評估L 層級數 - 1的層級否則斷言報錯GlobalTwoStreamEmbeddingSpaceTester配合TwoStreamMetricLoss的配對式訓練返回(anchor, positive, label)三元組僅支持splits_to_eval默認值每個 split 自查詢query/reference 必須同 split兩個容易踩的選型細節(jié)TwoStream 版內部把每個 batch 的 anchor 嵌入拼在前半段當 query、posneg 嵌入拼在后半段當 reference且ref_includes_query恒為False兩邊不是同一批樣本。它會在set_reference_and_query()里顯式斷言 query 與 reference 是同一個 split傳自定義組合會直接失敗。WithSameParentLabel 版對每個唯一父標簽篩出子集、在子集內分別算指標最后跨父標簽取平均np.mean。它衡量的是細粒度類在粗粒度類內部的可分性與全局視角回答的不是同一個問題。從配置到產出的完整鏈路第一步嵌入生成——指紋得先可比BaseTestersrc/pytorch_metric_learning/testers/base_tester.py的__init__參數決定了這一步的行為最常用的幾個參數默認值作用normalize_embeddingsTrue檢索前對嵌入做 L2 單位化保證余弦/L2 距離口徑一致use_trunk_outputFalse為True時跳過 embedder直接用 trunk 輸出評估pcaNone先標準化、再經 faiss 的PCAMatrix降到 N 維在歸一化之前執(zhí)行batch_size/dataloader_num_workers32/2嵌入前向的批大小與加載進程數data_device/dtypeNone設備自動選 CUDA與數據類型如torch.float16data_and_label_getterNone自定義如何從__getitem__輸出中拆出(data, labels)兩點補充不傳embedder_model時源碼會把它替換成torch.nn.Identity()即無操作直接消費 trunk 輸出嵌入生成邏輯封裝在get_all_embeddings()里可脫離test()單獨調用——想自己導出嵌入做 t-SNE/UMAP用它就夠了。第二步query 與 reference 的組合技巧默認行為是自查詢dataset_dict里每個 split 既當 query 又當 reference。更靈活的組合通過test()的splits_to_eval參數指定它是(query_split, [reference_splits])元組的列表# 默認等價于 [(dataset_a, [dataset_a]), (train, [train])] # query 用測試集reference 用訓練集評估泛化 [(test, [train])] # reference 由多個 split 合并 [(test, [test, train])]源碼在get_splits_to_compute_embeddings()中處理三件事query split 不允許重復出現query 與 reference 的并集才計算嵌入同一 split 只跑一次前向若 query 包含在 reference 列表中會被移到 reference 最前面——因為AccuracyCalculator.get_accuracy()要求ref_includes_queryTrue時reference 的前l(fā)en(query)個元素必須與 query 逐元素相等有torch.allclose顯式校驗。經驗建議關心泛化能力時讓 query 來自測試集、reference 來自訓練集避免自查詢帶來的樣本總能檢索到自身導致的指標虛高。第三步kNN 檢索——faiss 是引擎檢索由 src/pytorch_metric_learning/utils/inference.py 中的FaissKNNk-NN與FaissKMeansNMI/AMI 用的聚類完成也是AccuracyCalculator的默認后端因此faiss 是硬依賴。關鍵參數是k默認kNone等價于 k reference 嵌入總數——數據集一大檢索就會很慢推薦顯式傳k1000或kmax_bin_count每個類別的最大樣本數顯著提速。裝faiss-gpu時只有k 1024CUDA 9.5或k 2048CUDA ≥ 9.5才走 GPU否則回退 CPU 并告警——小數據集上若發(fā)現檢索沒跑在 GPU 上多半是這個原因。第四步指標計算——考官判分檢索結果交給 src/pytorch_metric_learning/utils/accuracy_calculator.py 中的AccuracyCalculator。默認指標速覽指標回答的問題備注precision_at_1第 1 個最近鄰是否與 query 同標簽最直觀的檢索命中率r_precision/mean_average_precision_at_r前 r 個鄰居中的檢索質量r 每個 query 的相關鄰居數要求kNone、kmax_bin_count或k max(bincount(reference_labels))否則失真會打警告NMI/AMI嵌入空間的聚類結構質量用FaissKMeans對 query 嵌入聚類簇數 query 唯一標簽數mean_average_precision、mean_reciprocal_rank可選補充指標按需開啟一個細節(jié)若某些 query 標簽根本沒出現在 reference 里這些樣本會被排除出 k-NN 類指標——它們注定 0 分不能反映嵌入質量排除后更公平。讀懂輸出keyname 規(guī)則、指標值與自查詢虛高test()返回并緩存在tester.all_accuracies上的結構是兩層字典{val: {precision_at_1_level0: 0.42, NMI_level0: 0.55, ...}}指標名遵循固定拼裝規(guī)則accuracies_keyname()生成_levelL后綴L 是label_hierarchy_level參數選中的標簽層級。單標簽數據保持默認 0 即可直接忽略后綴AVERAGE_前綴當label_hierarchy_levelall或傳入層級列表時會對各層級額外匯總出AVERAGE_precision_at_1這類平均指標_pcaN后綴設置了pca后自動追加標明該組指標基于降維后的嵌入。關于自查詢虛高默認自查詢模式下每個樣本的最近鄰大概率是自己precision_at_1天然偏高。這不是 bug而是口徑問題——對比不同模型時保證口徑一致即可單獨匯報泛化數字時則建議用test 查 train的組合見上文splits_to_eval示例。另外epoch參數只用于日志與歷史記錄寫入all_accuracies[split][epoch]不影響任何計算。接入訓練閉環(huán)logging_presets 早停 保存最佳模型評估器的end_of_testing_hook最實用的去處是接上 docs/logging_presets.md 里的logging_presets把每輪驗證 挑最佳模型 早停自動化import pytorch_metric_learning.utils.logging_presets as LP rk, _, _ LP.get_record_keeper(logs, tensorboard_logs) hooks LP.get_hook_container(rk) dataset_dict {val: val_dataset} tester testers.GlobalEmbeddingSpaceTester(end_of_testing_hookhooks.end_of_testing_hook) end_of_epoch_hook hooks.end_of_epoch_hook(tester, dataset_dict, saved_models) trainer trainers.MetricLossOnly( models, optimizers, batch_size, loss_funcs, mining_funcs, train_dataset, samplersampler, end_of_iteration_hookhooks.end_of_iteration_hook, end_of_epoch_hookend_of_epoch_hook, ) trainer.train(num_epochsnum_epochs)要點HookContainer的primary_metric決定用哪個指標挑最佳 checkpoint默認mean_average_precision_at_r可選r_precision、precision_at_1、NMIend_of_epoch_hook返回真正的鉤子函數驗證集鍵名默認val還支持test_interval隔幾輪驗證與patience早停耐心值歷史記錄同時落 csv、sqlite 與 tensorboard之后可用hooks.get_accuracy_history(tester, val, ...)回放任意指標的歷史曲線。避坑與提速清單faiss 必裝FaissKNN/FaissKMeans/PCA 都壓在它身上用 conda 安裝faiss-cpu或faiss-gpu大集提速顯式設accuracy_calculatorAccuracyCalculator(k1000)或kmax_bin_count注意r_precision/mean_average_precision_at_r在 k 偏小時會失真字符串標簽必須set_min_label_to_zeroTrue并同時傳dataset_labelsLabelMapper才會做重映射此時標簽按集合內排名變成連續(xù)整數雙流測試器的硬限制splits_to_eval只支持默認值query 與 reference 必須是同一 split別嘗試傳自定義組合臨時數據別出 hookembeddings_and_labels在test()末尾被刪除釋放內存需要在里面讀嵌入就放在end_of_testing_hook里做鉤子只調用一次end_of_testing_hook在所有 split 評估完之后觸發(fā)一次不是每個 split 一次只算部分指標AccuracyCalculator(include(precision_at_1,))可顯著加速評估。下一步跑一遍 examples/notebooks 下的示例 notebook如 TripletMarginLossMNIST觀察每個 epoch 的驗證指標如何進入all_accuracies并驅動最佳模型保存細讀 tests/testers/ 下的三個測試文件splits_to_eval三種組合對precision_at_1數值的影響、PCA 分支的端到端行為、雙流測試器的斷言都在斷言里寫得明明白白深入指標數學見 docs/accuracy_calculation.md參數總覽見 docs/testers.md。【免費下載鏈接】ocpFAIR Chemistrys library of machine learning methods for chemistry項目地址: https://gitcode.com/GitHub_Trending/oc/ocp創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 pytorch-metric-learning Testers 完整指南：從選型到訓練閉環(huán)，一次講透度量學習模型評估
pytorch-metric-learning Testers 完整指南從選型到訓練閉環(huán)一次講透度量學習模型評估【免費下載鏈接】ocpFAIR Chemistrys library of machine learning methods for chemistry項目地址: https://gitcode.com/GitHub_Trending/oc/ocppytorch-metric-learning 的 Testers評估器是度量學習鏈路里的考官拿到訓練好的模型trunk embedder和數據集劃分后它為每個樣本批量算出嵌入向量可以理解為樣本指紋再基于最近鄰檢索給模型打出一組精度分數。本文按先選型 → 走鏈路 → 讀結果 → 接閉環(huán)的順序展開覆蓋 Testers 的完整用法、指標輸出解讀以及如何用 logging_presets 實現訓練—驗證—保存最佳模型的閉環(huán)。速覽評估器卡在數據 → 嵌入 → 檢索 → 指標的哪一環(huán)Testers 不參與梯度更新是純評估組件。它的內部流程固定為四步嵌入生成把dataset_dict里每個 split 的樣本過一遍模型eval()模式 無梯度得到高維嵌入檢索默認用 faiss 后端FaissKNN在 reference 集合中為每條 query 做 k-NN指標計算把 query/reference 的嵌入與標簽交給AccuracyCalculator產出precision_at_1、r_precision、NMI 等指標輸出結果寫入tester.all_accuracies嵌套字典split → 指標名 → 數值并可觸發(fā)可視化與end_of_testing_hook。一句話總結你提供模型和數據它交回一張分數表。下這張圖是模型評估對比圖的常見畫法一軸是誤差指標、一軸是推理開銷理解 Testers 輸出時可以套用同樣的視角一張表里同時回答準不準和貴不貴。調用形態(tài)非常統(tǒng)一所有測試器都是這么用的from pytorch_metric_learning import testers t testers.GlobalEmbeddingSpaceTester() dataset_dict {train: train_ds, val: val_ds} all_accuracies t.test(dataset_dict, epoch, trunk, embedder) # embedder 可省略先選型我該用哪個 Tester結論先行90% 的場景用GlobalEmbeddingSpaceTester只有當標簽帶層級、或你的損失函數是TwoStreamMetricLoss時才需要另外兩個。三者的邊界如下源碼位于 src/pytorch_metric_learning/testers/Tester適用場景數據要求關鍵限制GlobalEmbeddingSpaceTester通用評估看嵌入空間中所有點的最近鄰質量__getitem__返回(data, labels)無特殊限制splits_to_eval任意組合WithSameParentLabelTester標簽有層級如 animal → cat/dog只在與 query 同父類兄弟的樣本里檢索二維標簽(num_samples, 層級數)第L1維是父標簽只能評估L 層級數 - 1的層級否則斷言報錯GlobalTwoStreamEmbeddingSpaceTester配合TwoStreamMetricLoss的配對式訓練返回(anchor, positive, label)三元組僅支持splits_to_eval默認值每個 split 自查詢query/reference 必須同 split兩個容易踩的選型細節(jié)TwoStream 版內部把每個 batch 的 anchor 嵌入拼在前半段當 query、posneg 嵌入拼在后半段當 reference且ref_includes_query恒為False兩邊不是同一批樣本。它會在set_reference_and_query()里顯式斷言 query 與 reference 是同一個 split傳自定義組合會直接失敗。WithSameParentLabel 版對每個唯一父標簽篩出子集、在子集內分別算指標最后跨父標簽取平均np.mean。它衡量的是細粒度類在粗粒度類內部的可分性與全局視角回答的不是同一個問題。從配置到產出的完整鏈路第一步嵌入生成——指紋得先可比BaseTestersrc/pytorch_metric_learning/testers/base_tester.py的__init__參數決定了這一步的行為最常用的幾個參數默認值作用normalize_embeddingsTrue檢索前對嵌入做 L2 單位化保證余弦/L2 距離口徑一致use_trunk_outputFalse為True時跳過 embedder直接用 trunk 輸出評估pcaNone先標準化、再經 faiss 的PCAMatrix降到 N 維在歸一化之前執(zhí)行batch_size/dataloader_num_workers32/2嵌入前向的批大小與加載進程數data_device/dtypeNone設備自動選 CUDA與數據類型如torch.float16data_and_label_getterNone自定義如何從__getitem__輸出中拆出(data, labels)兩點補充不傳embedder_model時源碼會把它替換成torch.nn.Identity()即無操作直接消費 trunk 輸出嵌入生成邏輯封裝在get_all_embeddings()里可脫離test()單獨調用——想自己導出嵌入做 t-SNE/UMAP用它就夠了。第二步query 與 reference 的組合技巧默認行為是自查詢dataset_dict里每個 split 既當 query 又當 reference。更靈活的組合通過test()的splits_to_eval參數指定它是(query_split, [reference_splits])元組的列表# 默認等價于 [(dataset_a, [dataset_a]), (train, [train])] # query 用測試集reference 用訓練集評估泛化 [(test, [train])] # reference 由多個 split 合并 [(test, [test, train])]源碼在get_splits_to_compute_embeddings()中處理三件事query split 不允許重復出現query 與 reference 的并集才計算嵌入同一 split 只跑一次前向若 query 包含在 reference 列表中會被移到 reference 最前面——因為AccuracyCalculator.get_accuracy()要求ref_includes_queryTrue時reference 的前l(fā)en(query)個元素必須與 query 逐元素相等有torch.allclose顯式校驗。經驗建議關心泛化能力時讓 query 來自測試集、reference 來自訓練集避免自查詢帶來的樣本總能檢索到自身導致的指標虛高。第三步kNN 檢索——faiss 是引擎檢索由 src/pytorch_metric_learning/utils/inference.py 中的FaissKNNk-NN與FaissKMeansNMI/AMI 用的聚類完成也是AccuracyCalculator的默認后端因此faiss 是硬依賴。關鍵參數是k默認kNone等價于 k reference 嵌入總數——數據集一大檢索就會很慢推薦顯式傳k1000或kmax_bin_count每個類別的最大樣本數顯著提速。裝faiss-gpu時只有k 1024CUDA 9.5或k 2048CUDA ≥ 9.5才走 GPU否則回退 CPU 并告警——小數據集上若發(fā)現檢索沒跑在 GPU 上多半是這個原因。第四步指標計算——考官判分檢索結果交給 src/pytorch_metric_learning/utils/accuracy_calculator.py 中的AccuracyCalculator。默認指標速覽指標回答的問題備注precision_at_1第 1 個最近鄰是否與 query 同標簽最直觀的檢索命中率r_precision/mean_average_precision_at_r前 r 個鄰居中的檢索質量r 每個 query 的相關鄰居數要求kNone、kmax_bin_count或k max(bincount(reference_labels))否則失真會打警告NMI/AMI嵌入空間的聚類結構質量用FaissKMeans對 query 嵌入聚類簇數 query 唯一標簽數mean_average_precision、mean_reciprocal_rank可選補充指標按需開啟一個細節(jié)若某些 query 標簽根本沒出現在 reference 里這些樣本會被排除出 k-NN 類指標——它們注定 0 分不能反映嵌入質量排除后更公平。讀懂輸出keyname 規(guī)則、指標值與自查詢虛高test()返回并緩存在tester.all_accuracies上的結構是兩層字典{val: {precision_at_1_level0: 0.42, NMI_level0: 0.55, ...}}指標名遵循固定拼裝規(guī)則accuracies_keyname()生成_levelL后綴L 是label_hierarchy_level參數選中的標簽層級。單標簽數據保持默認 0 即可直接忽略后綴AVERAGE_前綴當label_hierarchy_levelall或傳入層級列表時會對各層級額外匯總出AVERAGE_precision_at_1這類平均指標_pcaN后綴設置了pca后自動追加標明該組指標基于降維后的嵌入。關于自查詢虛高默認自查詢模式下每個樣本的最近鄰大概率是自己precision_at_1天然偏高。這不是 bug而是口徑問題——對比不同模型時保證口徑一致即可單獨匯報泛化數字時則建議用test 查 train的組合見上文splits_to_eval示例。另外epoch參數只用于日志與歷史記錄寫入all_accuracies[split][epoch]不影響任何計算。接入訓練閉環(huán)logging_presets 早停 保存最佳模型評估器的end_of_testing_hook最實用的去處是接上 docs/logging_presets.md 里的logging_presets把每輪驗證 挑最佳模型 早停自動化import pytorch_metric_learning.utils.logging_presets as LP rk, _, _ LP.get_record_keeper(logs, tensorboard_logs) hooks LP.get_hook_container(rk) dataset_dict {val: val_dataset} tester testers.GlobalEmbeddingSpaceTester(end_of_testing_hookhooks.end_of_testing_hook) end_of_epoch_hook hooks.end_of_epoch_hook(tester, dataset_dict, saved_models) trainer trainers.MetricLossOnly( models, optimizers, batch_size, loss_funcs, mining_funcs, train_dataset, samplersampler, end_of_iteration_hookhooks.end_of_iteration_hook, end_of_epoch_hookend_of_epoch_hook, ) trainer.train(num_epochsnum_epochs)要點HookContainer的primary_metric決定用哪個指標挑最佳 checkpoint默認mean_average_precision_at_r可選r_precision、precision_at_1、NMIend_of_epoch_hook返回真正的鉤子函數驗證集鍵名默認val還支持test_interval隔幾輪驗證與patience早停耐心值歷史記錄同時落 csv、sqlite 與 tensorboard之后可用hooks.get_accuracy_history(tester, val, ...)回放任意指標的歷史曲線。避坑與提速清單faiss 必裝FaissKNN/FaissKMeans/PCA 都壓在它身上用 conda 安裝faiss-cpu或faiss-gpu大集提速顯式設accuracy_calculatorAccuracyCalculator(k1000)或kmax_bin_count注意r_precision/mean_average_precision_at_r在 k 偏小時會失真字符串標簽必須set_min_label_to_zeroTrue并同時傳dataset_labelsLabelMapper才會做重映射此時標簽按集合內排名變成連續(xù)整數雙流測試器的硬限制splits_to_eval只支持默認值query 與 reference 必須是同一 split別嘗試傳自定義組合臨時數據別出 hookembeddings_and_labels在test()末尾被刪除釋放內存需要在里面讀嵌入就放在end_of_testing_hook里做鉤子只調用一次end_of_testing_hook在所有 split 評估完之后觸發(fā)一次不是每個 split 一次只算部分指標AccuracyCalculator(include(precision_at_1,))可顯著加速評估。下一步跑一遍 examples/notebooks 下的示例 notebook如 TripletMarginLossMNIST觀察每個 epoch 的驗證指標如何進入all_accuracies并驅動最佳模型保存細讀 tests/testers/ 下的三個測試文件splits_to_eval三種組合對precision_at_1數值的影響、PCA 分支的端到端行為、雙流測試器的斷言都在斷言里寫得明明白白深入指標數學見 docs/accuracy_calculation.md參數總覽見 docs/testers.md。【免費下載鏈接】ocpFAIR Chemistrys library of machine learning methods for chemistry項目地址: https://gitcode.com/GitHub_Trending/oc/ocp創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考