attnview

attnview mostra padrões de atenção de Transformers no terminal ou em um HTML interativo. A entrada é uma camada no formato [n_heads, query_length, key_length]: linhas são queries; colunas são keys.

Comece aqui — dois comandos

pip install --upgrade attnview

Quer saber se está funcionando? Rode exatamente isto:

attnview demo

Você verá os pesos de uma query, com tokens e posições explícitos. Para gerar o relatório HTML:

attnview demo --output attention.html

O comando informa o caminho do arquivo. Abra attention.html no navegador; não há servidor para iniciar nem URL para procurar.

Use com sua atenção real

import attnview

# `attention` can be a NumPy array, a PyTorch tensor, or nested Python sequences.
# Mostra no terminal.
attnview.show(attention, tokens=["[BOS]", "The", "cat", "sat", "."])

# Cria o arquivo HTML e informa onde ele foi salvo.
attnview.show(attention, tokens=tokens, output="attention.html")

Se seus dados já estão em JSON, você também pode renderizá-los diretamente:

attnview render attention.json --tokens tokens.json
attnview render attention.json --tokens tokens.json --output attention.html

attention.json contém a matriz [heads, queries, keys]; tokens.json é uma lista como ["[BOS]", "The", "cat", "sat", "."].

Como ler a tela

A versão 0.2 começa pela pergunta: para quais keys esta query distribui atenção? Escolha query=2 na API ou --query 2 no terminal. No HTML, clique no token; trocar de head preserva essa seleção. Todos os índices começam em zero.

Os destinos aparecem na ordem da sequência, acompanhados do peso bruto. No HTML, você pode ordenar a tabela por peso ou abrir a matriz completa. Barras representam magnitude relativa ao maior peso absoluto da query; os dados não são normalizados. O terminal imprime um relatório estático, inclusive sem cores; não é uma TUI.

• Rows are queries: the token doing the attending.
• Columns are keys: the token being attended to.
• Repeated tokens are distinguished by their sequence positions.
• Weight displays use six significant digits; the expanded HTML matrix exposes the stored numeric values.

API Python

attnview.show(
    attention,
    tokens=None,
    query_tokens=None,
    key_tokens=None,
    head=0,
    query=0,
    output=None,
    top_k=3,
    title="Attention Explorer",
)

Pass tokens for self-attention. For cross-attention, pass query_tokens and key_tokens independently. With output=None (the default), show prints to the current terminal. With an .html path, it writes a standalone HTML document and returns its Path.

render_html(...) returns the standalone HTML string when embedding it elsewhere.

Requirements

Python 3.10+ and Rich. NumPy and PyTorch are not required: if they are installed, their arrays/tensors are accepted directly.

Development

python -m pip install -e '.[dev]'
python -m pytest
python -m build
python -m twine check dist/*

License

MIT