Ecco 是一个用于探索和解释自然语言处理模型的 Python 库，通过交互式可视化来实现。

Ecco 提供了多种界面，帮助解释和理解基于 Transformer 的语言模型。更多信息请参阅：解释 Transformer 语言模型的界面。

Ecco 运行在 Jupyter 笔记本中，构建于 PyTorch 和 Transformers 之上。

Ecco 并不涉及模型的训练或微调，而是专注于探索和理解现有的预训练模型。目前，该库仍处于研究项目的 Alpha 版本阶段。欢迎各位贡献代码，共同完善它！

文档：ecco.readthedocs.io

功能特性

• 支持多种语言模型（GPT2、BERT、RoBERTA、T5、T0 等）[笔记本及添加更多模型的说明]。
• 可以加载您自己的 本地模型（前提是这些模型基于 Hugging Face 的 PyTorch 模型）。
• 特征归因功能（包括 IntegratedGradients、Saliency、InputXGradient、DeepLift、DeepLiftShap、GuidedBackprop、GuidedGradCam、Deconvolution 以及通过 Captum 实现的 LRP 等方法）。
• 在 Transformer 块中的 FFNN 层中 捕获神经元激活。
• 识别并 可视化神经元激活模式（通过非负矩阵分解）。
• 使用 SVCCA、PWCCA 和 CKA 比较激活空间，从而分析神经元激活情况（请观看 使用 CCA 检查神经网络的视频）。
• 提供以下可视化：
  • 模型各层对单个 token 处理过程的演变（Logit lens）。
  • 每一层候选输出 token 及其概率分布。

安装

您可以使用 pip 或 conda 来安装 ecco。

使用 pip

pip install ecco

使用 conda

conda install -c conda-forge ecco

示例：

所有示例均可在此处运行 [笔记本] | [Colab]。

这篇影评的情感倾向是什么？

使用大型语言模型（此处为 T5）检测文本情感。除了情感分类外，还可以查看模型将文本拆分后的 token，这有助于调试一些边缘情况。

这篇评论中哪些词促使模型将其情感判定为“负面”？

利用 Integrated Gradients 进行特征归因，可以帮助您深入理解模型的决策过程。例如，在这个例子中，将“weakness”替换为“inclination”，模型便能正确地将预测结果改为 正面。

通过填空题探索 GPT 模型的世界知识。

GPT2 知道希思罗机场在哪里吗？是的，它知道。

除了伦敦之外，模型还考虑了哪些城市或其他词语？

可视化候选输出 token 及其概率分数。

哪些输入词让模型联想到伦敦？

模型在哪些层获得了足够的信心，认定伦敦是正确答案？

模型在最后一层之后，将概率最高的 token 排名第一，从而选择了伦敦。那么，每一层对提升“伦敦”的排名分别作出了怎样的贡献呢？这正是 logit lens 可视化工具的作用——帮助我们探索不同模型层的活动。

BERT 在处理一段文本时，其神经元激活有哪些模式？

BERT 中的一些神经元群倾向于在遇到逗号和其他标点符号时被激活，而另一些则更易对代词产生反应。借助此可视化工具，您可以对单个 FFNN 层或整个模型中的神经元活动进行因子分解。

阅读论文：

Ecco：一个用于解释 Transformer 语言模型的开源库 计算语言学协会 (ACL) 系统演示，2021年

教程

• 视频：使用 Ecco 深入了解语言模型。[Colab 笔记本]

操作指南

• 解释 Transformer 语言模型的接口
• 寻找恰当的词语：语言模型的隐藏状态可视化

API 参考

Ecco 的 API 参考文档和架构页面详细介绍了 Ecco 的各个组件及其协作方式。

作品集与示例

获取帮助

遇到困难了吗？

• 在 讨论区 中或许能找到相关解答。如果没有，您也可以在那里提问。
• 如发现错误，请前往 Ecco 的 问题追踪器 提交报告。

用于引用的 BibTeX 格式：

@inproceedings{alammar-2021-ecco,
    title = "Ecco：用于解释 Transformer 语言模型的开源库",
    author = "Alammar, J",
    booktitle = "第59届计算语言学协会年会暨第11届国际自然语言处理联合会议：系统演示",
    year = "2021",
    publisher = "计算语言学协会",
}

Ecco 快速上手指南

Ecco 是一个用于探索和解释基于 Transformer 的自然语言处理（NLP）模型的 Python 库。它通过交互式可视化帮助开发者理解预训练模型（如 GPT-2, BERT, T5 等）的内部工作机制，包括特征归因、神经元激活分析和层级预测演化等。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：支持 Python 3.7 及以上版本
• 运行环境：推荐在 Jupyter Notebook 或 JupyterLab 中使用，以获得最佳的交互式可视化体验
• 前置依赖：Ecco 基于 PyTorch 和 Hugging Face transformers 构建，安装时会自动处理这些依赖。

安装步骤

您可以选择使用 pip 或 conda 进行安装。国内用户建议使用国内镜像源以加速下载。

方式一：使用 pip 安装

默认源安装：

pip install ecco

推荐使用国内镜像源（如清华源）加速安装：

pip install ecco -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 conda 安装

如果您使用 Anaconda 或 Miniconda，可以通过 conda-forge 渠道安装：

conda install -c conda-forge ecco

基本使用

Ecco 的核心功能是在 Jupyter Notebook 中加载预训练模型并进行交互式探索。以下是最简单的使用示例。

1. 初始化模型

在 Notebook 单元格中导入 ecco 并加载一个预训练模型（例如 t5-small）。Ecco 会自动下载模型（如果本地不存在）。

import ecco

# 初始化 Ecco 并加载 T5 模型
lm = ecco.from_pretrained('t5-small')

2. 生成文本并查看可视化

调用 generate() 方法输入提示词（Prompt），Ecco 将返回生成结果并自动展示交互式可视化组件。您可以查看候选 token 的概率、特征归因（哪些输入词影响了输出）以及数据在模型各层级的演变过程。

# 输入提示词并生成回复
output = lm.generate("What is the capital of France?")

交互功能说明：

• Token 概率：查看模型在每个位置预测的候选词及其置信度。
• 特征归因 (Attribution)：高亮显示对输出结果影响最大的输入词汇（支持 Integrated Gradients, Saliency 等多种算法）。
• 层级演化 (Logit Lens)：观察特定 Token 的排名如何随着模型层数的加深而变化，理解模型是如何逐步确定答案的。

3. 加载本地模型

如果您已经下载了 Hugging Face 格式的本地模型，可以直接指定路径加载：

# 加载本地模型路径
lm = ecco.from_pretrained('/path/to/your/local/model')

提示：更多高级用法（如神经元激活模式分析、多模型对比等），请参考官方文档 ecco.readthedocs.io 或查看项目仓库中的示例 Notebook。