diff --git a/docs/zh_cn/tutorials/metric_and_evaluator.md b/docs/zh_cn/design/metric_and_evaluator.md similarity index 85% rename from docs/zh_cn/tutorials/metric_and_evaluator.md rename to docs/zh_cn/design/metric_and_evaluator.md index 7cf962ebe92bdf263b95173d54d89553a7a248ff..79aa24b40dcf5f66beca3878f8ff13a56f74f748 100644 --- a/docs/zh_cn/tutorials/metric_and_evaluator.md +++ b/docs/zh_cn/design/metric_and_evaluator.md @@ -5,38 +5,18 @@ **è¯„æµ‹æŒ‡æ ‡** æ ¹æ®æ¨¡åž‹çš„输入数æ®å’Œé¢„测结果,完æˆç‰¹å®šæŒ‡æ ‡ä¸‹æ¨¡åž‹ç²¾åº¦çš„è®¡ç®—ã€‚è¯„æµ‹æŒ‡æ ‡ä¸Žæ•°æ®é›†ä¹‹é—´ç›¸äº’解耦,这使得用户å¯ä»¥ä»»æ„组åˆæ‰€éœ€çš„测试数æ®å’Œè¯„æµ‹æŒ‡æ ‡ã€‚å¦‚ [COCOMetric](Todo:coco-metric-doc-link) å¯ç”¨äºŽè®¡ç®— COCO æ•°æ®é›†çš„ AP,AR ç‰è¯„æµ‹æŒ‡æ ‡ï¼Œä¹Ÿå¯ç”¨äºŽå…¶ä»–çš„ç›®æ ‡æ£€æµ‹æ•°æ®é›†ä¸Šã€‚ **评测器** æ˜¯è¯„æµ‹æŒ‡æ ‡çš„ä¸Šå±‚æ¨¡å—,通常包å«ä¸€ä¸ªæˆ–å¤šä¸ªè¯„æµ‹æŒ‡æ ‡ã€‚è¯„æµ‹å™¨çš„ä½œç”¨æ˜¯åœ¨æ¨¡åž‹è¯„æµ‹æ—¶å®Œæˆå¿…è¦çš„æ•°æ®æ ¼å¼è½¬æ¢ï¼Œå¹¶è°ƒç”¨è¯„æµ‹æŒ‡æ ‡è®¡ç®—æ¨¡åž‹ç²¾åº¦ã€‚è¯„æµ‹å™¨é€šå¸¸ç”±[执行器](TODO:runner-doc-link)或测试脚本构建,分别用于在线评测和离线评测。 -用户通常ä¸éœ€è¦æ·±å…¥äº†è§£æˆ–æ‰‹åŠ¨ä¿®æ”¹è¯„æµ‹å™¨ï¼Œå› æ¤è¯¥æ–‡æ¡£å°†é‡ç‚¹ä»‹ç»è¯„æµ‹æŒ‡æ ‡çš„åŽŸç†å’Œä½¿ç”¨æ–¹å¼ã€‚ - -## 模型精度评测 +## 模型精度评测æµç¨‹ 通常,模型精度评测的过程如下图所示。 **在线评测**:测试数æ®é€šå¸¸ä¼šè¢«åˆ’分为若干批次(batch)。通过一个循环,ä¾æ¬¡å°†æ¯ä¸ªæ‰¹æ¬¡çš„æ•°æ®é€å…¥æ¨¡åž‹ï¼Œå¾—到对应的预测结果,并将测试数æ®å’Œæ¨¡åž‹é¢„测结果é€å…¥è¯„æµ‹å™¨ã€‚è¯„æµ‹å™¨ä¼šè°ƒç”¨è¯„æµ‹æŒ‡æ ‡çš„ `process()` 方法对数æ®å’Œé¢„测结果进行处ç†ã€‚当循环结æŸåŽï¼Œè¯„æµ‹å™¨ä¼šè°ƒç”¨è¯„æµ‹æŒ‡æ ‡çš„ `evaluate()` 方法,å¯è®¡ç®—å¾—åˆ°å¯¹åº”æŒ‡æ ‡çš„æ¨¡åž‹ç²¾åº¦ã€‚ -**离线评测**:与在线评测过程类似,区别是直接读å–预先ä¿å˜çš„模型预测结果æ¥è¿›è¡Œè¯„测。评测器æ供了 `offline_evaluate` 接å£ï¼Œç”¨äºŽåœ¨ç¦»çº¿æ–¹å¼ä¸‹è°ƒç”¨è¯„æµ‹æŒ‡æ ‡æ¥è®¡ç®—模型精度。为了é¿å…åŒæ—¶å¤„ç†å¤§é‡æ•°æ®å¯¼è‡´å†…å˜æº¢å‡ºï¼Œç¦»çº¿è¯„测时会将测试数æ®å’Œé¢„测结果分æˆè‹¥å¹²ä¸ªå—(Chunk)进行处ç†ï¼Œç±»ä¼¼åœ¨çº¿è¯„测ä¸çš„批次。 +**离线评测**:与在线评测过程类似,区别是直接读å–预先ä¿å˜çš„模型预测结果æ¥è¿›è¡Œè¯„测。评测器æ供了 `offline_evaluate` 接å£ï¼Œç”¨äºŽåœ¨ç¦»çº¿æ–¹å¼ä¸‹è°ƒç”¨è¯„æµ‹æŒ‡æ ‡æ¥è®¡ç®—模型精度。为了é¿å…åŒæ—¶å¤„ç†å¤§é‡æ•°æ®å¯¼è‡´å†…å˜æº¢å‡ºï¼Œç¦»çº¿è¯„测时会将测试数æ®å’Œé¢„测结果分æˆè‹¥å¹²ä¸ªå—(chunk)进行处ç†ï¼Œç±»ä¼¼åœ¨çº¿è¯„测ä¸çš„批次。 <div align="center"> <img src="https://user-images.githubusercontent.com/15977946/163718224-20a4970a-e540-4a3a-8b01-bf0a604c6841.jpg" width="500"/> </div> -## 在é…置文件ä¸é…ç½®è¯„æµ‹æŒ‡æ ‡ - -在é…置文件ä¸å¯ä»¥é€šè¿‡ `val_evaluator` å’Œ `test_evaluator` 2 个å—段分别指定模型验è¯å’Œæµ‹è¯•é˜¶æ®µçš„è¯„æµ‹æŒ‡æ ‡ã€‚ä¾‹å¦‚ï¼Œç”¨æˆ·åœ¨è®ç»ƒåˆ†ç±»æ¨¡åž‹æ—¶ï¼Œå¸Œæœ›åœ¨æ¨¡åž‹éªŒè¯é˜¶æ®µä½¿ç”¨åˆ†ç±»æ£ç¡®çŽ‡å’Œ F1 Score ä¸¤ä¸ªè¯„æµ‹æŒ‡æ ‡ï¼Œå¯ä»¥æŒ‰ä»¥ä¸‹æ–¹å¼é…置: - -```python -val_evaluator = [ - dict(type='Accuracy', top_k=1), # 使用分类æ£ç¡®çŽ‡è¯„æµ‹æŒ‡æ ‡ - dict(type='F1Score') # 使用 F1_score è¯„æµ‹æŒ‡æ ‡ -] -``` - -é…ç½®ä¸çš„`val_evaluator` 会被用于构建一个包å«å¤šä¸ªè¯„æµ‹æŒ‡æ ‡çš„è¯„æµ‹å™¨ï¼Œå…¶ä¸çš„æ¯ä¸ªå—å…¸å¯¹åº”äºŽä¸€ä¸ªè¯„æµ‹æŒ‡æ ‡çš„ç±»åˆ«å’Œå‚数。 -如果åªä½¿ç”¨å•ä¸ªè¯„æµ‹æŒ‡æ ‡ï¼Œä¹Ÿå¯ä»¥çœç•¥æŽ‰é…ç½®ä¸çš„åˆ—è¡¨ï¼Œç›´æŽ¥æŒ‡å®šè¯„æµ‹æŒ‡æ ‡å‚数。例如,在模型测试阶段使用分类æ£ç¡®çŽ‡è¯„æµ‹æŒ‡æ ‡ï¼Œå¯¹åº”çš„é…置如下: - -```python -test_evaluator = dict(type='Accuracy', top_k=1) -``` - ## å¢žåŠ è‡ªå®šä¹‰è¯„æµ‹æŒ‡æ ‡ 在 OpenMMLab çš„å„个算法库ä¸ï¼Œå·²ç»å®žçŽ°äº†å¯¹åº”æ–¹å‘çš„å¸¸ç”¨è¯„æµ‹æŒ‡æ ‡ã€‚å¦‚ MMDetection ä¸æ供了 COCO è¯„æµ‹æŒ‡æ ‡ï¼ŒMMClassification ä¸æ供了 Accuracyã€F1Score ç‰è¯„æµ‹æŒ‡æ ‡ç‰ã€‚ diff --git a/docs/zh_cn/tutorials/evaluation.md b/docs/zh_cn/tutorials/evaluation.md new file mode 100644 index 0000000000000000000000000000000000000000..01480584d690bf1eb83c91374f1762c2ce6a5eee --- /dev/null +++ b/docs/zh_cn/tutorials/evaluation.md @@ -0,0 +1,64 @@ +# 模型精度评测 + +在模型验è¯å’Œæ¨¡åž‹æµ‹è¯•ä¸ï¼Œé€šå¸¸éœ€è¦å¯¹æ¨¡åž‹ç²¾åº¦åšå®šé‡è¯„测。在 MMEngine ä¸å®žçŽ°äº†è¯„æµ‹æŒ‡æ ‡ï¼ˆMetric)和评测器(Evaluator)模å—æ¥å®Œæˆè¿™ä¸€åŠŸèƒ½ï¼š + +- è¯„æµ‹æŒ‡æ ‡ï¼š ç”¨äºŽæ ¹æ®æµ‹è¯•æ•°æ®å’Œæ¨¡åž‹é¢„测结果,完æˆæ¨¡åž‹ç‰¹å®šç²¾åº¦æŒ‡æ ‡çš„计算。在 OpenMMLab å„算法库ä¸æä¾›äº†å¯¹åº”ä»»åŠ¡çš„å¸¸ç”¨è¯„æµ‹æŒ‡æ ‡ï¼Œå¦‚ [MMClassification](https://github.com/open-mmlab/mmclassification) ä¸æ供了[分类æ£ç¡®çŽ‡æŒ‡æ ‡ï¼ˆAccuracy)](https://mmclassification.readthedocs.io/zh_CN/dev-1.x/generated/mmcls.evaluation.Accuracy.html) 用于计算分类模型的 Top-k 分类æ£ç¡®çŽ‡ã€‚ + +- 评测器: æ˜¯è¯„æµ‹æŒ‡æ ‡çš„ä¸Šå±‚æ¨¡å—,用于在数æ®è¾“å…¥è¯„æµ‹æŒ‡æ ‡å‰å®Œæˆå¿…è¦çš„æ ¼å¼è½¬æ¢ï¼Œå¹¶æ供分布å¼æ”¯æŒã€‚在模型è®ç»ƒå’Œæµ‹è¯•ä¸ï¼Œè¯„测器由[执行器(Runner)](https://mmengine.readthedocs.io/zh_CN/latest/api/runner.html)自动构建。用户亦å¯æ ¹æ®éœ€æ±‚手动创建评测器,进行离线评测。 + +## 在模型è®ç»ƒæˆ–测试ä¸è¿›è¡Œè¯„测 + +### è¯„æµ‹æŒ‡æ ‡é…ç½® + +在基于 MMEngine 进行模型è®ç»ƒæˆ–测试时,执行器会自动构建评测器进行评测,用户åªéœ€è¦åœ¨é…置文件ä¸é€šè¿‡ `val_evaluator` å’Œ `test_evaluator` 2 个å—段分别指定模型验è¯å’Œæµ‹è¯•é˜¶æ®µçš„è¯„æµ‹æŒ‡æ ‡å³å¯ã€‚例如,用户在使用 [MMClassification](https://github.com/open-mmlab/mmclassification) è®ç»ƒåˆ†ç±»æ¨¡åž‹æ—¶ï¼Œå¸Œæœ›åœ¨æ¨¡åž‹éªŒè¯é˜¶æ®µè¯„测 top-1 å’Œ top-5 分类æ£ç¡®çŽ‡ï¼Œå¯ä»¥æŒ‰ä»¥ä¸‹æ–¹å¼é…置: + +```python +val_evaluator = dict(type='Accuracy', top_k=(1, 5)) # 使用分类æ£ç¡®çŽ‡è¯„æµ‹æŒ‡æ ‡ +``` + +如果需è¦åŒæ—¶è¯„æµ‹å¤šä¸ªæŒ‡æ ‡ï¼Œä¹Ÿå¯ä»¥å°† `val_evaluator` 或 `test_evaluator` 设置为一个列表,其ä¸æ¯ä¸€é¡¹ä¸ºä¸€ä¸ªè¯„æµ‹æŒ‡æ ‡çš„é…置信æ¯ã€‚例如,在使用 [MMDetection](https://github.com/open-mmlab/mmdetection) è®ç»ƒå…¨æ™¯åˆ†å‰²æ¨¡åž‹æ—¶ï¼Œå¸Œæœ›åœ¨æ¨¡åž‹æµ‹è¯•é˜¶æ®µåŒæ—¶è¯„æµ‹æ¨¡åž‹çš„ç›®æ ‡æ£€æµ‹ï¼ˆCOCO AP/AR)和全景分割精度,å¯ä»¥æŒ‰ä»¥ä¸‹æ–¹å¼é…置: + +```python +test_evaluator = [ + # ç›®æ ‡æ£€æµ‹æŒ‡æ ‡ + dict( + type='COCOMetric', + metric=['bbox', 'segm'], + ann_file='annotations/instances_val2017.json', + ), + # å…¨æ™¯åˆ†å‰²æŒ‡æ ‡ + dict( + type='CocoPanopticMetric', + ann_file='annotations/panoptic_val2017.json', + seg_prefix='annotations/panoptic_val2017', + ) +] +``` + +### è‡ªå®šä¹‰è¯„æµ‹æŒ‡æ ‡ + +如果算法库ä¸æä¾›çš„å¸¸ç”¨è¯„æµ‹æŒ‡æ ‡æ— æ³•æ»¡è¶³éœ€æ±‚ï¼Œç”¨æˆ·ä¹Ÿå¯ä»¥å¢žåŠ è‡ªå®šä¹‰çš„è¯„æµ‹æŒ‡æ ‡ã€‚å…·ä½“çš„æ–¹æ³•å¯ä»¥å‚考[è¯„æµ‹æŒ‡æ ‡å’Œè¯„æµ‹å™¨è®¾è®¡](/docs/zh_cn/design/metric_and_evaluator.md)。 + +## 使用离线结果进行评测 + +å¦ä¸€ç§å¸¸è§çš„模型评测方å¼ï¼Œæ˜¯åˆ©ç”¨æå‰ä¿å˜åœ¨æ–‡ä»¶ä¸çš„模型预测结果进行离线评测。æ¤æ—¶ï¼Œç”±äºŽä¸å˜åœ¨æ‰§è¡Œå™¨ï¼Œç”¨æˆ·éœ€è¦æ‰‹åŠ¨æž„建评测器,并调用评测器的相应接å£å®Œæˆè¯„测。以下是一个离线评测示例: + +```python +from mmengine.evaluator import Evaluator +from mmengine.fileio import load + +# 构建评测器。å‚æ•° `metrics` ä¸ºè¯„æµ‹æŒ‡æ ‡é…ç½® +evaluator = Evaluator(metrics=dict(type='Accuracy', top_k=(1, 5))) + +# 从文件ä¸è¯»å–测试数æ®ã€‚æ•°æ®æ ¼å¼éœ€è¦å‚考具使用的 metric。 +data = load('test_data.pkl') + +# 从文件ä¸è¯»å–模型预测结果。该结果由待评测算法在测试数æ®é›†ä¸ŠæŽ¨ç†å¾—到。 +# æ•°æ®æ ¼å¼éœ€è¦å‚考具使用的 metric。 +predictions = load('prediction.pkl') + +# 调用评测器离线评测接å£ï¼Œå¾—到评测结果 +# chunk_size 表示æ¯æ¬¡å¤„ç†çš„æ ·æœ¬æ•°é‡ï¼Œå¯æ ¹æ®å†…å˜å¤§å°è°ƒæ•´ +results = evaluator.offline_evaluate(data, predictions, chunk_size=128) + +```