针对 RNN 中状态变化的可视化分析

有关 LSTMVis 的更多信息、介绍视频以及在线演示链接，请访问 lstm.seas.harvard.edu。

同时，也请查看我们在序列到序列模型方面的最新工作，相关代码可在 github 上找到，或访问在线演示页面 http://seq2seq-vis.io/。

V2.1 版本更新

• 更新至 Python 3.7 及以上版本（感谢 @nneophyt）

V2 版本更新

• 全新设计与服务器后端
• 隐藏状态轨迹支持离散缩放
• 新增元数据与预测标注轨道
• 添加了针对 TensorFlow 的训练与数据提取流程
• 客户端现采用 ES6 和 D3v4
• 客户端侧进行了一些性能优化
• 增加了 Keras 教程 此处（感谢 Mohammadreza Ebrahimi）

安装

请使用 Python 3.7 或更高版本 来安装 LSTMVis。

克隆仓库：

git clone https://github.com/HendrikStrobelt/LSTMVis.git; cd LSTMVis

使用 pip 安装服务器端依赖：

python -m venv  venv3
source venv3/bin/activate
pip install -r requirements.txt

下载并解压示例数据集至 <LSTMVis>/data/05childbook：

儿童读物 - 古腾堡计划 - 2.2 GB

Parens 数据集 - 1 万条小样本 - 0.03 GB

启动服务器：

source venv3/bin/activate
python lstm_server.py -dir <datadir>

对于示例数据集，使用 python lstm_server.py -dir data

在浏览器中打开 http://localhost:8888，大功告成！

添加您自己的数据

如果您希望先训练自己的数据，请阅读 训练 文档。如果您已有数据，将其添加到 LSTMVis 非常简单，您只需要三个文件：

• 包含每个时间步状态向量的 HDF5 文件（例如 states.hdf5）
• 包含每个时间步单词 ID 的 HDF5 文件（例如 train.hdf5）*
• 包含单词 ID 到单词映射的字典文件（例如 train.dict）*

数据格式示意如下：

*如果您还没有这些文件，而只有以空格分隔的 .txt 格式训练数据，请查看我们的 文本转换工具

数据目录

LSTMVis 会解析 <datadir> 下的所有子目录，查找配置文件 lstm.yml。典型的 <datadir> 目录结构可能如下所示：

<datadir>
├── paren  		        <--- 项目目录
│   ├── lstm.yml 		<--- 配置文件
│   ├── states.hdf5 	        <--- 每个时间步的状态
│   ├── train.hdf5 		<--- 每个时间步的单词 ID
│   └── train.dict 		<--- 单词 ID 到单词的映射
├── fun .. 

配置文件

一个简单的 lstm.yml 示例：

name: children books  # 项目名称
description: children book texts from the Gutenberg project # 简要描述

files: # 将文件分配给引用名称
  states: states.hdf5 # HDF5 文件必须以 .h5 或 .hdf5 结尾！！！
  train: train.hdf5 # 训练集的单词 ID
  words: train.dict # 字典文件必须以 .dict 结尾！！！

word_sequence: # 定义单词序列
  file: train # HDF5 文件
  path: word_ids # HDF5 中表格的路径
  dict_file: words # 用于将 HDF5 中的 ID 映射为单词的字典

states: # 定义您希望查看的模型状态部分
  file: states # 包含各位置状态的 HDF5 文件
  types: [
        {type: state, layer: 1, path: states1}, # type={state, output}, layer=[1..x], path = HDF5 路径
        {type: state, layer: 2, path: states2},
        {type: output, layer: 2, path: output2}
  ]

感兴趣吗？更多内容如下……

请参阅我们的文档，了解：

• 关于配置状态文件输入的详细说明
• 添加结果热图的注释文件
• 使用 PyTorch 训练模型
• 新增！！！使用 TensorFlow 训练模型（链接）
• 让您的工作更轻松的工具

致谢

LSTMVis 是哈佛大学工程与应用科学学院 Hendrik Strobelt、Sebastian Gehrmann、Bernd Huber、Hanspeter Pfister 和 Alexander M. Rush 共同合作的项目。

LSTMVis 快速上手指南

LSTMVis 是一个用于可视化递归神经网络（RNN/LSTM）状态变化的工具，帮助开发者直观分析模型内部隐藏状态的动态变化。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux / macOS / Windows (需支持 Python 虚拟环境)
• Python 版本：Python 3.7 或更高版本 (必须)
• 依赖管理：pip (Python 包管理器)
• 浏览器：现代浏览器 (Chrome, Firefox, Edge 等)，用于访问本地可视化界面

注意：本项目后端基于 Python，前端已编译为 ES6/D3v4，通常无需额外安装 Node.js 或 Bower，除非您需要修改前端源码。

安装步骤

1. 克隆项目

打开终端，执行以下命令下载源代码：

git clone https://github.com/HendrikStrobelt/LSTMVis.git
cd LSTMVis

2. 创建并激活虚拟环境

为了避免依赖冲突，建议创建独立的 Python 虚拟环境：

python -m venv venv3
source venv3/bin/activate
# Windows 用户请使用: venv3\Scripts\activate

3. 安装 Python 依赖

安装服务器端所需的库：

pip install -r requirements.txt

(国内用户若下载缓慢，可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 使用清华镜像源)

4. 准备示例数据

下载示例数据集并解压到 data 目录下。您可以选择以下任一数据集进行测试：

• Children Book (较大，2.2 GB): Google Drive 链接
• Parens Dataset (较小，0.03 GB，推荐快速测试): Google Drive 链接

将解压后的文件夹放入 <LSTMVis>/data/ 目录中。例如，若下载了 Parens 数据集，目录结构应类似 data/paren/...。

基本使用

1. 启动服务

在激活虚拟环境的状态下，运行服务器脚本并指定数据目录。

如果使用上述下载的示例数据（假设数据位于 data 文件夹内）：

source venv3/bin/activate
python lstm_server.py -dir data

如果您自定义了数据路径，请将 data 替换为您的实际路径，例如 -dir /path/to/my/project。

2. 访问界面

服务启动后，打开浏览器访问以下地址：

http://localhost:8888/client/index.html

您将看到 LSTMVis 的可视化界面，可以加载示例项目（如 "paren" 或 "children books"）进行探索。

3. 接入自有数据（简述）

若要分析自己的模型，需在数据目录下创建一个子文件夹（例如 my_model），并在其中放置以下三个核心文件及配置文件 lstm.yml：

1. states.hdf5: 包含每个时间步的状态向量。
2. train.hdf5: 包含每个时间步的词 ID。
3. train.dict: 词 ID 到单词的映射字典。
4. lstm.yml: 配置文件，定义项目名称、文件路径及要可视化的层级（参考 README 中的 Config File 章节）。

配置完成后，重启服务器并使用 -dir 指向包含该子文件夹的根目录即可。