Ferret圆形logo，右侧为名称

ferret是一个Python库，用于简化Transformers模型的可解释性技术的使用和基准测试。

文档：https://ferret.readthedocs.io
论文：https://aclanthology.org/2023.eacl-demo.29/
演示：https://huggingface.co/spaces/g8a9/ferret

ferret旨在与🤗 transformers模型无缝集成，目前仅支持文本模型。我们提供：

🔍 四种基于Token级特征归因的成熟可解释性技术。使用它们可以快速找到对模型输出最相关的词。
⚖️ 六种忠实度和合理性评估协议。针对这些测试对任何token级解释进行基准测试，以指导您选择最可靠的解释器。

ACL Anthology Bibkey:

attanasio-etal-2023-ferret

📝 示例

全面教程（测试所有解释器、评估指标和XAI数据集接口）：Colab

文本分类

使用多语言XLM RoBERTa进行意图检测：Colab

入门

安装

对于默认安装（不包括语音XAI功能的依赖项），请运行：

pip install -U ferret-xai

我们的主要依赖项是🤗 transformers和datasets。

如果需要语音XAI功能，请运行：

pip install -U ferret-xai[speech]

目前，语音XAI相关的依赖项是唯一的额外依赖项，所以安装ferret-xai[speech]或ferret-xai[all]是等效的。

重要提示 我们的一些依赖项可能使用scikit-learn的包名，这会导致ferret安装失败。如果您的pip安装命令失败，请尝试：

SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=True pip install -U ferret-xai

这希望只是一个临时情况！

解释和基准测试

以下代码提供了一个最小示例，用于运行ferret支持的所有特征归因解释器，并对它们进行忠实度指标的基准测试。

我们从一个常见的文本分类流程开始

from transformers import AutoModelForSequenceClassification, AutoTokenizer
from ferret import Benchmark

name = "cardiffnlp/twitter-xlm-roberta-base-sentiment"
model = AutoModelForSequenceClassification.from_pretrained(name)
tokenizer = AutoTokenizer.from_pretrained(name)

使用ferret非常简单：

bench = Benchmark(model, tokenizer)
explanations = bench.explain("You look stunning!", target=1)
evaluations = bench.evaluate_explanations(explanations, target=1)

bench.show_evaluation_table(evaluations)

请确保在Jupyter Notebook/Colab中运行代码：上面的单元格将生成一个格式良好的表格，用于分析显著性图。

特性

ferret提供与Hugging Face模型和命名约定的无痛集成。如果您已经在使用transformers库，您可以立即访问我们的解释和评估API。

后验解释器

梯度（普通梯度或乘以输入token嵌入）（Simonyan等，2014）
积分梯度（普通梯度或乘以输入token嵌入）（Sundararajan等，2017）
SHAP（通过Partition SHAP近似Shapley值）（Lundberg和Lee，2017）
LIME（Ribeiro等，2016）

评估指标

忠实度度量：

AOPC全面性（DeYoung等，2020）
AOPC充分性（DeYoung等，2020）
与Leave-One-Out token移除的Kendall's Tau相关性（Jain和Wallace，2019）

合理性度量：

精确率-召回率曲线下面积（软分数）（DeYoung等，2020）
Token F1（硬分数）（DeYoung等，2020）
Token交并比（硬分数）（DeYoung等，2020）

详情请参阅我们的论文。

可视化

Benchmark类提供了易于使用的表格可视化方法（例如，在Jupyter Notebooks中）

bench = Benchmark(model, tokenizer)

# 漂亮地打印所有支持的解释器的特征归因分数
explanations = bench.explain("You look stunning!")
bench.show_table(explanations)

打印所有支持的评估指标

evaluations = bench.evaluate_explanations(explanations) bench.show_evaluation_table(evaluations)


## 数据集评估

`Benchmark`类有一个方便的方法来计算和平均多个数据集样本的评估指标。

```python
import numpy as np
bench = Benchmark(model, tokenizer)

# 计算并平均一个支持的数据集的评估分数
samples = np.arange(20)
hatexdata = bench.load_dataset("hatexplain")
sample_evaluations =  bench.evaluate_samples(hatexdata, samples)

# 美观打印结果
bench.show_samples_evaluation_table(sample_evaluations)

计划开发

更多详情请参见更新日志文件。

✅ 支持GPU加速推理 (v0.4.0)
✅ 内部方法近似步骤的批量推理（如LIME或SHAP）(v0.4.0)
⚙️ 简化的任务API，支持NLI、零样本文本分类、语言建模（分支）
⚙️ 多样本解释生成和评估
⚙️ 通过inseq支持序列到序列和自回归生成的解释器
⚙️ 新评估指标：敏感性、稳定性（Yin等人）
⚙️ 新评估指标：阈值性能曲线下面积（AUC-TP）（Atanasova等人）
⚙️ 新解释器：采样和遮蔽（SOC）（Jin等人，2020）
⚙️ 新解释器：离散化积分梯度（DIG）（Sanyal和Ren，2021）
⚙️ 新解释器：值置零（Mohebbi等人，2023）
⚙️ 支持嵌入隐藏维度的其他聚合形式

作者

致谢

本包是使用Cookiecutter和audreyr/cookiecutter-pypackage项目模板创建的。

Cookiecutter：https://github.com/audreyr/cookiecutter
audreyr/cookiecutter-pypackage

标志和图形资产由Luca Attanasio制作。

如果您在工作中使用ferret，请考虑引用我们！

@inproceedings{attanasio-etal-2023-ferret,
    title = "ferret: a Framework for Benchmarking Explainers on Transformers",
    author = "Attanasio, Giuseppe and Pastor, Eliana and Di Bonaventura, Chiara and Nozza, Debora",
    booktitle = "Proceedings of the 17th Conference of the European Chapter of the Association for Computational Linguistics: System Demonstrations",
    month = may,
    year = "2023",
    publisher = "Association for Computational Linguistics",
}