MAV - 模型活动可视化工具

在大型语言模型生成文本时，可视化其内部运作过程

🚀 快速入门

方法 1：使用 uv（推荐）

# 使用 PyPI 包运行
uv run --with openmav mav

# 或直接从 GitHub 运行
uv run --with git+https://github.com/attentionmech/mav mav --model gpt2 --prompt "hello mello"

注意：您可以将 gpt2 替换为任何其他与 transformers 兼容的 Hugging Face 模型：

• HuggingFaceTB/SmolLM-135M
• gpt2-medium
• gpt2-large
• meta-llama/Llama-3.2-1B

对于受限制的仓库，请确保您已执行 huggingface-cli login，并且您的环境具有访问权限。

方法 2：使用 pip

1. 设置并激活虚拟环境
2. 安装包：

   # 从 PyPI
   pip install openmav
   
   # 或从 GitHub
   pip install git+https://github.com/attentionmech/mav
   

3. 运行可视化工具：

   mav --model gpt2 --prompt "hello mello"
   

4. 或在代码中导入：

   from openmav.mav import MAV
   MAV("gpt2", "Hello")
   

方法 3：本地开发

1. 克隆仓库：

   git clone https://github.com/attentionmech/mav
   cd mav
   

2. 设置并激活虚拟环境
3. 以开发模式安装：

   pip install .
   

4. 运行可视化工具：

   mav --model gpt2 --prompt "hello mello"
   

方法 4：Jupyter Notebook/Colab

📚 文档与教程

文档

请参阅 documentation.md 文件以获取详细信息。

教程

自定义插件开发

高级用法示例

# 使用训练循环和自定义模型运行 MAV
uv run examples/test_vis_train_loop.py

# 使用自定义面板配置运行
uv run --with git+https://github.com/attentionmech/mav mav \
  --model gpt2 \
  --num-grid-rows 3 \
  --selected-panels generated_text attention_entropy top_predictions \
  --max-bar-length 20 \
  --refresh-rate 0 \
  --max-new-tokens 10000

🎥 演示视频

• 基础插件
• 交互模式
• 限制字符数
• 带温度采样的示例
• 使用自定义模型运行
• 面板选择
• 在 Colab 笔记本中运行

注意：请通过命令行帮助探索更多选项，因为许多采样参数都已公开。

👥 贡献

克隆仓库并以开发模式安装包：

git clone https://github.com/attentionmech/mav
cd mav

# 使用 uv（推荐）
uv sync

# 或使用 pip
pip install -e .

📝 引用

@article{attentionmech2025openmav,
  title={OpenMAV: 模型活动可视化工具},
  author={attentionmech},
  year={2025}
}

🧠 小知识

该项目起源于一次简单的终端 UI 循环测试中的一个小推文： 推文

⭐ 星标历史

MAV 快速上手指南

MAV (Model Activity Visualiser) 是一个用于可视化大型语言模型（LLM）在生成文本时内部工作机制的开源工具。它能在终端中实时展示模型的注意力机制、预测概率等内部状态。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.8 及以上
• 前置依赖：
  • 推荐安装 uv 以获得最快的安装和运行体验。
  • 若使用受限模型（如 Llama 系列），需提前运行 huggingface-cli login 完成认证。

安装步骤

你可以选择以下任意一种方式进行安装：

方法一：使用 uv（推荐，无需预先安装）

直接使用 uv 运行 PyPI 包或 GitHub 源码，无需手动创建虚拟环境：

# 直接运行 PyPI 版本
uv run --with openmav mav

# 或直接运行 GitHub 最新版本并指定参数
uv run --with git+https://github.com/attentionmech/mav mav --model gpt2 --prompt "hello mello"

方法二：使用 pip 安装

1. 创建并激活虚拟环境。
2. 执行安装命令：

# 从 PyPI 安装
pip install openmav

# 或从 GitHub 安装
pip install git+https://github.com/attentionmech/mav

方法三：本地开发模式

git clone https://github.com/attentionmech/mav
cd mav
pip install -e .

基本使用

安装完成后，可通过命令行或 Python 代码启动可视化界面。

1. 命令行启动

最简单的用法是指定模型和提示词：

mav --model gpt2 --prompt "hello mello"

支持的模型： 你可以将 gpt2 替换为任何兼容 Hugging Face transformers 的模型，例如：

• HuggingFaceTB/SmolLM-135M
• gpt2-medium
• meta-llama/Llama-3.2-1B

2. Python 代码调用

也可以在脚本或 Jupyter Notebook 中直接导入使用：

from openmav.mav import MAV

# 初始化并运行
MAV("gpt2", "Hello")

3. 高级用法示例

自定义面板布局、刷新率和生成长度：

mav \
  --model gpt2 \
  --num-grid-rows 3 \
  --selected-panels generated_text attention_entropy top_predictions \
  --max-bar-length 20 \
  --refresh-rate 0 \
  --max-new-tokens 10000

提示：运行 mav --help 可查看完整的命令行参数列表，包括温度采样（temperature）等更多控制选项。