在Quantus中开发自定义评估指标：继承Metric基类完整指南（含测试与文档）

在Quantus中开发自定义评估指标继承Metric基类完整指南含测试与文档【免费下载链接】Quantus[JMLR 2023] Quantus is an eXplainable AI toolkit for responsible evaluation of neural network explanations项目地址: https://gitcode.com/gh_mirrors/qu/QuantusQuantus 是一款发表于 JMLR 2023 的可解释 AIXAI工具包专用于对神经网络解释进行负责任的量化评估。如果你希望向 Quantus 贡献一个自定义评估指标本文带你完整走一遍继承Metric基类的标准流程从类设计、评估逻辑实现到单元测试与文档补充一篇搞定。 先搞懂Quantus 需要什么样的自定义指标Quantus 内置六大类评估指标覆盖解释质量的不同维度Faithfulness忠实性解释是否真实反映模型决策Robustness鲁棒性解释对输入扰动的稳定性Localisation定位性解释能否定位到关键区域Complexity简洁性解释是否稀疏、高效Randomisation随机化检验排除碰巧有效的解释Axiomatic公理化检验公理属性是否满足如果你的研究需要一种库中尚未提供的度量方式就可以通过继承Metric基类位于 quantus/metrics/base.py来扩展让新指标无缝接入 Quantus 的统一 API。⚡ 一键搭建 Quantus 开发环境先克隆仓库并用 Tox 配置可编辑安装的开发环境git clone https://gitcode.com/gh_mirrors/qu/Quantus cd Quantus python3 -m pip install tox python3 -m tox devenv source venv/bin/activateTox 会自动完成依赖安装与可编辑安装之后即可直接修改quantus/下的源码并运行测试。 读懂 Metric 基类自定义评估指标的核心结构所有指标都继承自Metric泛型基类。当你调用metric(model..., x_batch..., ...)时基类会按固定流水线执行general_preprocess()自动处理 channel-first 转换、模型包装、解释生成、取绝对值abs与归一化normalise等通用预处理evaluate_batch()这是你要实现的抽象方法编写你自己的逐样本评估逻辑custom_postprocess() 按aggregate_func聚合得分如np.mean因此自定义指标只需实现评估核心批次处理、归一化、进度条、警告等脏活全部由基类代劳。参考实现见 quantus/metrics/complexity/sparseness.py 中的Sparseness指标。 五步完成自定义指标开发从类定义到注册第一步在对应评估类别目录创建指标文件确认你的指标属于哪个类别然后在对应的quantus/metrics/类别/文件夹中新建一个 Python 文件六大类别见上文。第二步声明 5 个类属性继承 Metricfrom quantus.helpers.enums import ( DataType, ModelType, ScoreDirection, EvaluationCategory ) from quantus.metrics.base import Metric class MyCustomMetric(Metric[List[float]]): 指标的一句话描述附 References 与 Assumptions。 name MyCustomMetric data_applicability {DataType.IMAGE, DataType.TABULAR} model_applicability {ModelType.TORCH, ModelType.TF} score_direction ScoreDirection.HIGHER evaluation_category EvaluationCategory.COMPLEXITY这 5 个类属性决定了指标如何被 Quantus 识别枚举值定义在 quantus/helpers/enums.py。__init__中沿用abs、normalise、return_aggregate、aggregate_func等标准参数并调用super().__init__(...)即可。第三步实现 evaluate_batch 评估逻辑这是唯一的必写核心方法输入是整个批次返回每个样本一个分数def evaluate_batch(self, x_batch: np.ndarray, a_batch: np.ndarray, **kwargs) - List[float]: # 在此实现你的度量逻辑例如 # 1) 扁平化 a_batcha_batch.reshape(batch_size, -1) # 2) 逐样本计算得分 # 3) 返回与 batch_size 等长的得分列表 ...批量接口batched API由基类统一分派天然获得并行计算的性能收益。第四步把指标注册到包入口在你的类别目录__init__.py中加一行导入例如参照 quantus/metrics/complexity/init.py。顶层 quantus/metrics/init.py 使用星号导入注册后即可通过from quantus.metrics import MyCustomMetric直接使用。第五步调用并验证得分metric MyCustomMetric(absTrue, normaliseTrue, return_aggregateTrue) scores metric(modelmodel, x_batchx_batch, y_batchy_batch, a_batcha_batch)✅ 为自定义指标编写单元测试的完整流程Quantus 使用 pytest 测试目标是接近 100% 的代码覆盖率。在tests/metrics/下为对应类别的测试文件中添加用例例如 tests/metrics/test_complexity_metrics.pypytest.mark.complexity def test_my_custom_metric(almost_uniform_1d): scores MyCustomMetric(disable_warningsTrue)( modelNone, x_batchalmost_uniform_1d[x_batch], y_batchalmost_uniform_1d[y_batch], a_batchalmost_uniform_1d[a_batch], ) assert all(0.0 s 1.0 for s in scores)测试编写要点用pytest.mark.类别打上类别标记若使用新标记记得在 pytest.ini 中登记用lazy_fixture复用conftest.py中现成的模型与数据夹具无需自建用pytest.mark.parametrize覆盖abs/normalise等不同参数组合按类别跑测试python3 -m tox run -e py39 -- -m complexity -s 补充指标文档docstring 与 rst 文件类级 docstring必须包含指标详细描述、References原始论文引用、Assumptions格式参照 quantus/metrics/complexity/sparseness.py每个方法含__init__、__call__、evaluate_batch都要有 numpydoc 风格的参数与返回值说明在 docs/source/docs_api/ 下按现有模式新增你的指标的.rst页面参考 quantus.metrics.complexity.sparseness.rst并挂入 quantus.metrics.rst 索引代码风格遵循 PEP-8用black行宽 88与flake8检查后再提交完整贡献规范可查阅 CONTRIBUTING.md 中的 Contributing a New Metric 章节。 提测前检查清单5 个类属性齐全score_direction与得分含义一致evaluate_batch对每个样本返回一个分数已在类别__init__.py中注册顶层导入可用测试全部通过python3 -m tox run代码通过 black 与 flake8 检查docstring 与.rst文档已补齐至此你的自定义评估指标已经可以像Sparseness、Infidelity等内置指标一样被用户一行代码调用 。【免费下载链接】Quantus[JMLR 2023] Quantus is an eXplainable AI toolkit for responsible evaluation of neural network explanations项目地址: https://gitcode.com/gh_mirrors/qu/Quantus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考