Inspectus

Inspectus 是一款功能强大的机器学习可视化工具。它通过简单易用的 Python API，在 Jupyter Notebook 中流畅运行。

目录

• 安装
• 注意力机制可视化
  • 预览
  • 组件
  • 使用方法
  • 教程
    • Huggingface 模型
    • 自定义注意力图
• Token 可视化
  • 预览
  • 使用方法
• 分布图
  • 预览
  • 使用方法
  • 示例用法
• 开发环境搭建
• 引用

安装

pip install inspectus

注意力机制可视化

Inspectus 提供了用于深度学习模型中注意力机制的可视化工具。它包含一系列全面的视图，帮助用户更轻松地理解这些模型的工作原理。

预览

点击某个 token 可以选中它并取消其他 token 的选中状态。再次点击则会重新选中所有 token。若只想改变单个 token 的状态，请按住 Shift 键再点击

组件

注意力矩阵： 可视化 token 之间的注意力分数，突出显示每个 token 在处理过程中如何关注其他 token。

查询 token 热力图： 展示每个查询 token 与选定键 token 之间注意力分数的总和。

键 token 热力图： 展示每个键 token 与选定查询 token 之间注意力分数的总和。

维度热力图： 展示各维度（层和头）中每个元素的注意力分数总和，并按维度进行归一化。

使用方法

导入库：

import inspectus

简单用法：

# attn: 注意力图；一个 2-4D 张量，或来自 Huggingface Transformers 的注意力图
inspectus.attention(attn, tokens)

对于不同的查询和键 token：

inspectus.attention(attns, query_tokens, key_tokens)

有关详细的 API 文档，请参阅官方文档。

教程

Huggingface 模型

from transformers import AutoTokenizer, GPT2LMHeadModel, AutoConfig
import torch
import inspectus

# 初始化分词器和模型
context_length = 128
tokenizer = AutoTokenizer.from_pretrained("huggingface-course/code-search-net-tokenizer")

config = AutoConfig.from_pretrained(
    "gpt2",
    vocab_size=len(tokenizer),
    n_ctx=context_length,
    bos_token_id=tokenizer.bos_token_id,
    eos_token_id=tokenizer.eos_token_id,
)

model = GPT2LMHeadModel(config)

# 对输入文本进行分词
text= 'The quick brown fox jumps over the lazy dog'
tokenized = tokenizer(
    text,
    return_tensors='pt',
    return_offsets_mapping=True
)
input_ids = tokenized['input_ids']

tokens = [text[s: e] for s, e in tokenized['offset_mapping'][0]]

with torch.no_grad():
    res = model(input_ids=input_ids.to(model.device), output_attentions=True)

# 使用 Inspectus 库可视化注意力图
inspectus.attention(res['attentions'], tokens)

在此查看笔记本：Huggingface 教程

自定义注意力图

import numpy as np
import inspectus

# 表示查询和键 token 之间注意力值的 2D 注意力图
attn = np.random.rand(3, 3)

# 使用 Inspectus 库可视化注意力值
# 第一个参数是注意力矩阵
# 第二个参数是查询 token 列表
# 第三个参数是键 token 列表
inspectus.attention(arr, ['a', 'b', 'c'], ['d', 'e', 'f'])

在此查看笔记本：自定义注意力图教程

Token 可视化

该工具用于可视化与 token 相关的一些指标。它支持多种指标，可以通过下拉菜单选择要可视化的指标。除了指标之外，还可以为 token 添加额外的信息。

预览

使用方法

import inspectus
inspectus.tokens(["Hello", " World", "!"], {
    'loss': [-7.375, -8.312, -7.5625],
    'entropy': [3.323, 1.0666, 0.432]
}, token_info=["info 1", "info 2", "info 3"])

在此查看笔记本：GPT2 示例

分布图

分布图是一种展示一系列数据分布情况的图表。在每一步中，都会计算数据的分布，并从 9 个基点中绘制最多 5 条带。（0, 6.68, 15.87, 30.85, 50.00, 69.15, 84.13, 93.32, 100.00）

预览

使用方法

import inspectus

inspectus.distribution({'x': [x for x in range(0, 100)]})

为了聚焦于图表的特定部分并放大显示，可以使用小地图。若要选择单个图表，可使用右上角的图例。

有关完整的使用指南，请参阅此笔记本：分布图教程

示例用法

该图表可用于识别数据中的异常值。以下笔记本展示了如何使用分布图来识别 MNIST 训练损失中的异常值。

MNIST

开发环境搭建

开发文档

引用

如果您在学术研究中使用 Inspectus，请使用以下 BibTeX 条目引用该库。

@misc{inspectus,
 author = {Varuna Jayasiri, Lakshith Nishshanke},
 title = {inspectus：用于大型语言模型的可视化与分析工具},
 year = {2024},
 url = {https://github.com/labmlai/inspectus},
}

Inspectus 快速上手指南

Inspectus 是一款专为机器学习设计的可视化工具，特别适用于在 Jupyter Notebook 中直观分析深度学习模型的注意力机制、Token 指标及数据分布。

环境准备

• 操作系统：支持 Windows、macOS 和 Linux
• Python 版本：建议 Python 3.7 及以上
• 运行环境：推荐在 Jupyter Notebook 或 JupyterLab 中使用以获得最佳交互体验
• 前置依赖：无需额外复杂配置，安装时会自动处理依赖（如 numpy, torch 等，视具体功能而定）

安装步骤

使用 pip 直接安装：

pip install inspectus

国内用户加速建议：如果下载速度较慢，可使用清华或阿里镜像源：

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

基本使用

1. 注意力机制可视化 (Attention Visualization)

这是 Inspectus 最核心的功能，可直观展示 Token 之间的注意力权重。

简单用法（适用于已有的注意力矩阵）：

import inspectus

# attn: 注意力矩阵 (2-4 维张量)
# tokens: 对应的文本 token 列表
inspectus.attention(attn, tokens)

快速尝试 Hugging Face 模型：

from transformers import AutoTokenizer, GPT2LMHeadModel, AutoConfig
import torch
import inspectus

# 初始化分词器和模型
context_length = 128
tokenizer = AutoTokenizer.from_pretrained("huggingface-course/code-search-net-tokenizer")

config = AutoConfig.from_pretrained(
    "gpt2",
    vocab_size=len(tokenizer),
    n_ctx=context_length,
    bos_token_id=tokenizer.bos_token_id,
    eos_token_id=tokenizer.eos_token_id,
)

model = GPT2LMHeadModel(config)

# 分词
text = 'The quick brown fox jumps over the lazy dog'
tokenized = tokenizer(text, return_tensors='pt', return_offsets_mapping=True)
input_ids = tokenized['input_ids']
tokens = [text[s: e] for s, e in tokenized['offset_mapping'][0]]

# 获取注意力输出
with torch.no_grad():
    res = model(input_ids=input_ids.to(model.device), output_attentions=True)

# 可视化
inspectus.attention(res['attentions'], tokens)

2. Token 指标可视化 (Token Visualization)

用于展示每个 Token 的相关指标（如 Loss、熵等），支持多选指标切换。

import inspectus

inspectus.tokens(["Hello", " World", "!"], {
    'loss': [-7.375, -8.312, -7.5625],
    'entropy': [3.323, 1.0666, 0.432]
}, token_info=["info 1", "info 2", "info 3"])

3. 数据分布图 (Distribution Plot)

用于观察数据随时间步的分布变化，帮助识别异常值。

import inspectus

inspectus.distribution({'x': [x for x in range(0, 100)]})

提示：在生成的图表中，可利用右上角图例选择特定曲线，或使用底部缩略图进行缩放查看细节。