<commit_before><h1 align="center">
    BertViz
</h1>
<h3 align="center">
 Visualize Attention in NLP Models
</h3>
<h3 align="center">
    <a href="#-quick-tour">Quick Tour</a> &bull;
    <a href="#%EF%B8%8F-getting-started">Getting Started</a> &bull;
    <a href="https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing">Colab Tutorial</a> &bull;
    <a href="https://towardsdatascience.com/deconstructing-bert-part-2-visualizing-the-inner-workings-of-attention-60a16d86b5c1">Blog</a> &bull;
    <a href="https://www.aclweb.org/anthology/P19-3007.pdf">Paper</a> &bull;
    <a href="#-paper">Citation</a>
</h3>

BertViz is an interactive tool for visualizing attention in [Transformer](https://jalammar.github.io/illustrated-transformer/) language models such as BERT, GPT2, or T5. It can be run inside a Jupyter or Colab
 notebook through a simple Python API that supports most [Huggingface models](https://huggingface.co/models). BertViz extends the
   [Tensor2Tensor visualization tool](https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/visualization)
    by [<NAME>](https://medium.com/@llionj), providing multiple views that each offer a unique lens into the attention mechanism.

For updates on BertViz and related projects, feel free to follow me on [Twitter](https://twitter.com/jesse_vig).


## 🚀 Quick Tour

### Head View
The *head view* visualizes attention for one or more attention heads in the same 
 layer. It is based on the excellent [Tensor2Tensor visualization tool](https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/visualization) by [<NAME>](https://medium.com/@llionj). 

🕹 Try out the head view in the [<b><u>Interactive Colab Tutorial</u></b>](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing) (all visualizations pre-loaded).
<p>
    <img src="https://raw.githubusercontent.com/jessevig/bertviz/master/images/head-view.gif" width="425"/>
</p>


### Model View 

The *model view* shows a bird's-eye view of attention across all layers and heads.

🕹 Try out the model view in the [<b><u>Interactive Colab Tutorial</u></b>](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing) (all visualizations pre-loaded).

![model view](images/model-view-noscroll.gif)

### Neuron View 
The *neuron view* visualizes individual neurons in the query and key vectors and shows how they are used to compute attention.

🕹 Try out the neuron view in the [<b><u>Interactive Colab Tutorial</u></b>](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing) (all visualizations pre-loaded).


![neuron view](images/neuron-view-dark.gif)

## ⚡️ Getting Started

### Running BertViz in a Jupyter Notebook

From the command line:

```bash
pip install bertviz
```
You must also have Jupyter Notebook and ipywidgets installed:

```bash
pip install jupyterlab
pip install ipywidgets
```
(If you run into any issues installing Jupyter or ipywidgets, consult the documentation [here](https://jupyter.org/install) and [here](https://ipywidgets.readthedocs.io/en/stable/user_install.html).)

To create a new Jupyter notebook, simply run:

```bash
jupyter notebook
```

Then click `New` and select `Python 3 (ipykernel)` if prompted.


### Running BertViz in Colab

To run in [Colab](https://colab.research.google.com/), simply add the following cell at the beginning of your Colab notebook:

```
!pip install bertviz
```

### Sample code
Run the following code to load the `xtremedistil-l12-h384-uncased` model and display it in the model view: 

```python
from transformers import AutoTokenizer, AutoModel, utils
from bertviz import model_view
utils.logging.set_verbosity_error()  # Suppress standard warnings

model_name = "microsoft/xtremedistil-l12-h384-uncased"  # Find popular HuggingFace models here: https://huggingface.co/models
input_text = "The cat sat on the mat"  
model = AutoModel.from_pretrained(model_name, output_attentions=True)  # Configure model to return attention values
tokenizer = AutoTokenizer.from_pretrained(model_name)
inputs = tokenizer.encode(input_text, return_tensors='pt')  # Tokenize input text
outputs = model(inputs)  # Run model
attention = outputs[-1]  # Retrieve attention from model outputs
tokens = tokenizer.convert_ids_to_tokens(inputs[0])  # Convert input ids to token strings
model_view(attention, tokens)  # Display model view
```

The visualization may take a few seconds to load. Feel free to experiment with different input texts and
 [models](https://huggingface.co/models). 
See [Documentation](#-documentation) for additional use cases and examples, e.g., encoder-decoder models.

#### Running sample notebooks

You may also run any of the sample [notebooks](notebooks/) included with BertViz:

```bash
git clone --depth 1 <EMAIL>:jessevig/bertviz.git
cd bertviz/notebooks
jupyter notebook
```
## 🕹 Interactive Tutorial

Check out the [<b><u>Interactive Colab Tutorial</u></b>](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing) 
to learn more about BertViz and try out the tool. <b>Note</b>: all visualizations are pre-loaded, so there is no need to execute any cells.

[![Tutorial](images/tutorial-screenshots.jpg)](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing)


## 📖 Documentation

### Table of contents

- [Self-attention models (BERT, GPT-2, etc.)](#self-attention-models-bert-gpt-2-etc)
  * [Head and Model Views](#head-and-model-views)
  * [Neuron View](#neuron-view-1)
- [Encoder-decoder models (BART, T5, etc.)](#encoder-decoder-models-bart-t5-etc)
- [Installing from source](#installing-from-source)
- [Additional options](#additional-options)
  * [Dark / light mode](#dark--light-mode)
  * [Filtering layers](#filtering-layers)
  * [Setting default layer/head(s)](#setting-default-layer-head-s)
  * [Visualizing sentence pairs](#visualizing-sentence-pairs)
  * [Obtain HTML representations](#obtain-HTML-representations)
  * [Non-Huggingface models](#non-huggingface-models)
 - [Limitations](#---limitations)

### Self-attention models (BERT, GPT-2, etc.)

#### Head and Model Views
First load a Huggingface model, either a pre-trained model as shown below, or your own fine-tuned model.
 Be sure to set `output_attentions=True`.
```python
from transformers import AutoTokenizer, AutoModel, utils
utils.logging.set_verbosity_error()  # Suppress standard warnings
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModel.from_pretrained("bert-base-uncased", output_attentions=True)
```

Then prepare inputs and compute attention:

```python
inputs = tokenizer.encode("The cat sat on the mat", return_tensors='pt')
outputs = model(inputs)
attention = outputs[-1]  # Output includes attention weights when output_attentions=True
tokens = tokenizer.convert_ids_to_tokens(inputs[0]) <commit_msg>Correct section links in TOC<commit_after><h1 align="center">
    BertViz
</h1>
<h3 align="center">
 Visualize Attention in NLP Models
</h3>
<h3 align="center">
    <a href="#-quick-tour">Quick Tour</a> &bull;
    <a href="#%EF%B8%8F-getting-started">Getting Started</a> &bull;
    <a href="https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing">Colab Tutorial</a> &bull;
    <a href="https://towardsdatascience.com/deconstructing-bert-part-2-visualizing-the-inner-workings-of-attention-60a16d86b5c1">Blog</a> &bull;
    <a href="https://www.aclweb.org/anthology/P19-3007.pdf">Paper</a> &bull;
    <a href="#-paper">Citation</a>
</h3>

BertViz is an interactive tool for visualizing attention in [Transformer](https://jalammar.github.io/illustrated-transformer/) language models such as BERT, GPT2, or T5. It can be run inside a Jupyter or Colab
 notebook through a simple Python API that supports most [Huggingface models](https://huggingface.co/models). BertViz extends the
   [Tensor2Tensor visualization tool](https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/visualization)
    by [<NAME>](https://medium.com/@llionj), providing multiple views that each offer a unique lens into the attention mechanism.

For updates on BertViz and related projects, feel free to follow me on [Twitter](https://twitter.com/jesse_vig).


## 🚀 Quick Tour

### Head View
The *head view* visualizes attention for one or more attention heads in the same 
 layer. It is based on the excellent [Tensor2Tensor visualization tool](https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/visualization) by [<NAME>](https://medium.com/@llionj). 

🕹 Try out the head view in the [<b><u>Interactive Colab Tutorial</u></b>](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing) (all visualizations pre-loaded).
<p>
    <img src="https://raw.githubusercontent.com/jessevig/bertviz/master/images/head-view.gif" width="425"/>
</p>


### Model View 

The *model view* shows a bird's-eye view of attention across all layers and heads.

🕹 Try out the model view in the [<b><u>Interactive Colab Tutorial</u></b>](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing) (all visualizations pre-loaded).

![model view](images/model-view-noscroll.gif)

### Neuron View 
The *neuron view* visualizes individual neurons in the query and key vectors and shows how they are used to compute attention.

🕹 Try out the neuron view in the [<b><u>Interactive Colab Tutorial</u></b>](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing) (all visualizations pre-loaded).


![neuron view](images/neuron-view-dark.gif)

## ⚡️ Getting Started

### Running BertViz in a Jupyter Notebook

From the command line:

```bash
pip install bertviz
```
You must also have Jupyter Notebook and ipywidgets installed:

```bash
pip install jupyterlab
pip install ipywidgets
```
(If you run into any issues installing Jupyter or ipywidgets, consult the documentation [here](https://jupyter.org/install) and [here](https://ipywidgets.readthedocs.io/en/stable/user_install.html).)

To create a new Jupyter notebook, simply run:

```bash
jupyter notebook
```

Then click `New` and select `Python 3 (ipykernel)` if prompted.


### Running BertViz in Colab

To run in [Colab](https://colab.research.google.com/), simply add the following cell at the beginning of your Colab notebook:

```
!pip install bertviz
```

### Sample code
Run the following code to load the `xtremedistil-l12-h384-uncased` model and display it in the model view: 

```python
from transformers import AutoTokenizer, AutoModel, utils
from bertviz import model_view
utils.logging.set_verbosity_error()  # Suppress standard warnings

model_name = "microsoft/xtremedistil-l12-h384-uncased"  # Find popular HuggingFace models here: https://huggingface.co/models
input_text = "The cat sat on the mat"  
model = AutoModel.from_pretrained(model_name, output_attentions=True)  # Configure model to return attention values
tokenizer = AutoTokenizer.from_pretrained(model_name)
inputs = tokenizer.encode(input_text, return_tensors='pt')  # Tokenize input text
outputs = model(inputs)  # Run model
attention = outputs[-1]  # Retrieve attention from model outputs
tokens = tokenizer.convert_ids_to_tokens(inputs[0])  # Convert input ids to token strings
model_view(attention, tokens)  # Display model view
```

The visualization may take a few seconds to load. Feel free to experiment with different input texts and
 [models](https://huggingface.co/models). 
See [Documentation](#-documentation) for additional use cases and examples, e.g., encoder-decoder models.

#### Running sample notebooks

You may also run any of the sample [notebooks](notebooks/) included with BertViz:

```bash
git clone --depth 1 <EMAIL>@github.<EMAIL>:jessevig/bertviz.git
cd bertviz/notebooks
jupyter notebook
```
## 🕹 Interactive Tutorial

Check out the [<b><u>Interactive Colab Tutorial</u></b>](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing) 
to learn more about BertViz and try out the tool. <b>Note</b>: all visualizations are pre-loaded, so there is no need to execute any cells.

[![Tutorial](images/tutorial-screenshots.jpg)](https://colab.research.google.com/drive/1hXIQ77A4TYS4y3UthWF-Ci7V7vVUoxmQ?usp=sharing)


## 📖 Documentation

### Table of contents

- [Self-attention models (BERT, GPT-2, etc.)](#self-attention-models-bert-gpt-2-etc)
  * [Head and Model Views](#head-and-model-views)
  * [Neuron View](#neuron-view-1)
- [Encoder-decoder models (BART, T5, etc.)](#encoder-decoder-models-bart-t5-etc)
- [Installing from source](#installing-from-source)
- [Additional options](#additional-options)
  * [Dark / light mode](#dark--light-mode)
  * [Filtering layers](#filtering-layers)
  * [Setting default layer/head(s)](#setting-default-layerheads)
  * [Visualizing sentence pairs](#visualizing-sentence-pairs)
  * [Obtain HTML representations](#obtain-HTML-representations)
  * [Non-Huggingface models](#non-huggingface-models)
 - [Limitations](#%EF%B8%8F-limitations)

### Self-attention models (BERT, GPT-2, etc.)

#### Head and Model Views
First load a Huggingface model, either a pre-trained model as shown below, or your own fine-tuned model.
 Be sure to set `output_attentions=True`.
```python
from transformers import AutoTokenizer, AutoModel, utils
utils.logging.set_verbosity_error()  # Suppress standard warnings
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModel.from_pretrained("bert-base-uncased", output_attentions=True)
```

Then prepare inputs and compute attention:

```python
inputs = tokenizer.encode("The cat sat on the mat", return_tensors='pt')
outputs = model(inputs)
attention = outputs[-1]  # Output includes attention weights when output_attentions=True
tokens = tokenizer.convert_ids_to_tokens(inputs[0]) 
{'fraction_non_alphanumeric': 0.12598254849643037, 'fraction_numerical': 0.01514386673397274, 'mean_word_length': 5.303636363636364, 'pattern_counts': {'":': 0, '<': 88, '<?xml version=': 0, '>': 88, 'https://': 42, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1132126', 'n_tokens_mistral': 4894, 'n_tokens_neox': 4545, 'n_words': 1238}