Miru Tracer v0.2: das probabilidades de tokens ao funcionamento interno dos modelos

A Miru Tracer v0.2 é a maior atualização desde o início do projeto.

Nosso primeiro post sobre a Miru Tracer apresentou o projeto como uma forma visual de acompanhar a geração de um modelo de linguagem, token por token. Ele mostrava probabilidades e entropia e permitia substituir manualmente a escolha do próximo token pelo modelo.

Essa versão rastreava o que saía do modelo. A v0.2 também consegue inspecionar e modificar o que acontece entre as camadas.

De um rastreador a uma bancada de interpretabilidade

O lançamento original respondia a um conjunto restrito de perguntas. Qual token provavelmente virá a seguir? Quão confiante está o modelo? O que acontece se escolhermos outro token?

A v0.2 acrescenta outro conjunto. Quais conceitos semelhantes a tokens podem ser lidos em uma camada intermediária? Como essas leituras mudam ao longo da rede? O que acontece se adicionarmos, removermos ou substituirmos uma dessas direções internas antes de a geração continuar?

As principais novidades são:

• Duas lentes para as camadas: uma lente de logits que funciona de imediato e uma lente jacobiana ajustada para leituras das camadas iniciais e intermediárias.

• Uma bancada dedicada na aba Lens: inspecione camadas e posições de tokens, compare as duas lentes, agregue leituras recorrentes e acompanhe tokens selecionados ao longo da rede.

• Intervenções nas ativações: direcione, faça ablação ou troque direções de tokens em uma ou mais camadas, com várias intervenções ativas ao mesmo tempo.

• Um mecanismo de geração reescrito: probabilidades brutas e ajustadas, tratamento mais seguro do cache KV, navegação livre entre etapas, geração interrompível e logs versionados.

• Um pacote e um processo de lançamento completos: pontos de entrada de linha de comando, versões de dependências controladas, testes automatizados, CI e uma imagem Docker publicada.

Olhando através das camadas

A cada posição de token, um transformer atualiza um vetor chamado fluxo residual. O estado residual final passa pelas camadas de normalização e unembedding do modelo para produzir pontuações para o vocabulário.

As novas lentes aplicam a mesma ideia antes de o modelo chegar à camada final.

Lente de logits: h_l  -> normalização -> unembedding -> pontuações de tokens
Lente jacobiana: h_l  -> J_l -> normalização -> unembedding -> pontuações de tokens

Essas são leituras de representações intermediárias. Elas não são transcrições de um raciocínio privado, e seus tokens mais bem classificados não devem ser tratados como fonte definitiva do que um modelo está “pensando”.

A lente de logits

A lente de logits envia um estado residual intermediário diretamente pelo unembedding do próprio modelo. Ela propõe uma pergunta contrafactual útil: se o modelo tivesse de produzir um token a partir dessa camada, o que o estado atual favoreceria?

Ela não exige ajuste e funciona assim que um modelo compatível é carregado. Em geral, sua leitura é mais clara perto das camadas finais, onde o fluxo residual já está próximo do sistema de coordenadas usado na saída.

As camadas iniciais são mais difíceis. As representações mudam à medida que atravessam a rede, enquanto a lente de logits presume que todas as camadas usam as coordenadas da camada final.

A lente jacobiana

A lente jacobiana corrige esse desalinhamento. Ela se baseia no artigo da Anthropic “Verbalizable Representations Form a Global Workspace in Language Models” e em sua implementação de referência.

Para cada camada, ela estima uma matriz J_l que descreve como as mudanças naquela camada afetam, em média e ao longo de muitos contextos, o fluxo residual final. Aplicar esse transporte antes do unembedding pode recuperar sinais legíveis nas camadas iniciais e intermediárias, onde a lente de logits costuma produzir ruído.

A Miru Tracer incorpora o código de referência relevante sob a licença Apache-2.0 e o integra aos modelos do Hugging Face. O restante da Miru Tracer permanece sob a Unlicense.

Ao contrário da lente de logits, a lente jacobiana precisa de um arquivo de ajuste para o checkpoint exato do modelo. O ajuste é executado separadamente da interface web e exige muito poder computacional, pois requer retropropagações repetidas. Modelos pequenos podem ser ajustados com tranquilidade em uma GPU moderna; modelos grandes podem exigir distribuição entre várias GPUs. Um ajuste não pode ser reutilizado com pesos diferentes só porque a arquitetura é semelhante.

O processo de ajuste salva checkpoints do progresso, retoma o trabalho após uma interrupção e mantém utilizáveis os ajustes parciais. Novos ajustes usam safetensors; artefatos legados em .pt ainda podem ser carregados e convertidos. O fluxo de ajuste e as opções de configuração atuais são mantidos no tutorial da Lens.

Uma bancada para comparar leituras

A aba Lens é organizada em torno de uma sequência, e não de um único gráfico. Ela reúne em um só fluxo o texto gerado, posições de tokens selecionáveis, intervalos de camadas e visualizações Logit, Jacobian ou lado a lado.

A Miru alinha cada token exibido com o estado causal anterior que o produziu. Assim, a leitura da camada final fica vinculada à distribuição real do modelo para aquele token, e não ao token seguinte.

A bancada inclui:

• leituras por camada e por posição;

• uma visão agregada dos tokens que se repetem nas células selecionadas;

• mapas de calor com navegação horizontal para recortes extensos de camada por posição;

• acompanhamento do ranking de tokens fixados ao longo das camadas;

• IDs exatos dos tokens e rótulos multilíngues decodificados;

• filtro para tokens semelhantes a palavras; e

• um painel Layer Lens dentro do Interactive Mode para o token atual.

A aba usa um espaço de trabalho com dois painéis para a geração e os controles das lentes, com as visualizações de resultados em largura total logo abaixo. Leituras densas e mapas de calor são renderizados como HTML leve e carregados apenas quando sua visualização está ativa, o que mantém utilizáveis no navegador até recortes extensos de camada por posição.

A camada final continua sendo um ponto de referência incorporado. Se sua leitura não corresponder à distribuição real de saída do modelo, há algo errado com a análise.

Ler era apenas metade do plano

O post original sobre a Miru indicava activation steering como o próximo caminho. A v0.2 o implementa.

O novo mecanismo de intervenções pode editar as direções das lentes durante a geração:

• Steer (direcionar): adicione uma direção de token ao fluxo residual ou a subtraia usando uma intensidade negativa.

• Ablate (ablação): remova o componente da ativação ao longo de uma direção de token.

• Swap (troca): transfira o componente associado a uma direção de token para outra, preservando o restante ortogonal.

As intervenções podem usar a base da lente de logits ou da lente jacobiana. Elas podem ter como alvo camadas individuais, listas ou intervalos, e qualquer quantidade pode ser composta em ordem dentro da mesma passagem pela rede.

Essas edições não alteram os pesos do modelo. Remover as intervenções restaura o caminho de geração sem modificações.

Um exemplo simples de steering pela base jacobiana

Em um exemplo simples com o Qwen3-4B, usamos o prompt Think of an animal. Answer in one word. Sem nenhuma intervenção, o modelo responde Dog.

Sem intervenção, o Qwen3-4B responde “Dog”.

Em seguida, direcionamos suavemente o modelo para o token 猫 (“gato” em chinês) usando a base jacobiana, com uma intensidade de apenas +0.15 em cada uma das três camadas finais. A resposta muda para Cat.

Com um direcionamento suave pela base jacobiana para 猫, o mesmo modelo responde “Cat”.

Nessa execução, uma direção escolhida a partir de um token em chinês altera uma resposta em inglês. É um exemplo direto de como usar a leitura de uma lente como direção de intervenção e depois observar o efeito no comportamento.

Este é um instrumento experimental, não uma API confiável de controle. Uma intervenção que altera uma saída não prova, por si só, que o rótulo selecionado nomeia um conceito claro e isolado dentro do modelo.

O mecanismo de geração também foi refeito

A bancada da aba Lens se apoia em um tracer reescrito.

Para cada posição, a Miru agora calcula os logits brutos uma única vez e deriva as visualizações de temperatura, top-k e top-p sem executar o modelo novamente. As probabilidades brutas representam a distribuição do modelo antes dos ajustes de amostragem; as probabilidades ajustadas mostram a distribuição efetivamente usada para escolher um token.

Essa distinção aparece nas visualizações ao vivo, nos logs exportados, nos mapas de calor e nos cálculos de entropia. A entropia exata só é informada quando a distribuição completa de probabilidades foi registrada.

O formato de exportação agora é versionado. O esquema v3 registra os parâmetros de amostragem e a origem da seleção em cada etapa, enquanto a aba Log Analysis ainda aceita logs produzidos pelo lançamento original.

O Interactive Mode pode executar vários tokens, interromper uma geração ativa, desfazer etapas ou voltar a qualquer ponto anterior. O Logging Mode pode continuar uma execução existente em vez de recomeçar.

Há suporte a entradas de completion, chat estruturado e tokens brutos em todas as ferramentas de geração. O modo de chat também oferece controles para templates de raciocínio e o preenchimento prévio opcional desse raciocínio nos modelos que adotam essas convenções.

Mais modelos, com ressalvas explícitas

A pilha de lentes agora detecta os blocos residuais, a normalização, os embeddings e a cabeça de saída em várias famílias de modelos.

A Miru foi projetada para reconhecer Llama, Qwen, Mistral, Gemma, OLMo, GPT-2, Phi, GPT-NeoX, wrappers do Gemma 4 e arquiteturas MoE e DSA no estilo GLM. Nesta versão, porém, apenas a família Qwen3 foi testada na prática; o Qwen3-0.6B conta com um teste automatizado de ponta a ponta. A compatibilidade com as demais famílias não é garantida e deve ser validada para cada checkpoint.

Checkpoints grandes, como Gemma 4 e GLM 5.2, ainda exigem hardware adequado ao seu porte, e os modelos Gemma multimodais devem ser analisados apenas no modo texto.

Para quem quiser experimentar modelos maiores em GPUs na nuvem, também disponibilizamos um template público da Miru Tracer no RunPod.

O carregador de modelos agora consegue descarregar um checkpoint de forma limpa, informar o uso de memória, reduzir o pico de uso da memória principal e solicitar carregamento em 4 ou 8 bits no CUDA. Modelos que exigem código Python fornecido pelo próprio repositório só são habilitados explicitamente.

Empacotamento, implantação e testes

As versões anteriores usavam um fluxo de inicialização baseado em um único arquivo. A v0.2 é um pacote Python instalável, com pontos de entrada de linha de comando separados para a aplicação web, o ajuste de lentes e a conversão de ajustes legados. Um arquivo de restrições torna reproduzível o conjunto de dependências usado na CI, enquanto as dependências opcionais de GPU permanecem separadas da instalação padrão para CPU.

A CI executa a suíte de testes offline nas versões compatíveis do Python, testa o Qwen3-0.6B de ponta a ponta nos pull requests e verifica a construção da imagem Docker com CUDA.

O contêiner executa a aplicação como um usuário sem privilégios, vincula a porta publicada ao endereço de loopback no comando documentado e oferece autenticação opcional. O carregamento de código de modelos de terceiros fica desativado, a menos que seja permitido explicitamente.

O fluxo de lançamento publica imagens versionadas no GitHub Container Registry e anexa atestados de procedência da build depois que a CI é concluída com sucesso na branch master.

Os detalhes de instalação, configuração, contêiner e uso evoluem com o projeto. As instruções atuais ficam no repositório da Miru Tracer, e o fluxo de ajuste e análise está no tutorial da Lens.

Limitações

As funcionalidades de lentes e intervenções são novas e ainda experimentais. Seus resultados podem estar errados ou não fazer sentido de formas que ainda não detectamos.

A lente jacobiana é uma aproximação linear média. Suas leituras se limitam a conceitos representados por tokens do vocabulário, e a qualidade de um ajuste depende do corpus, do número de prompts e do checkpoint do modelo.

A lente de logits é mais simples e muitas vezes útil, mas seus rótulos para as camadas iniciais podem ser enganosos. Nenhum dos métodos transforma uma ativação interna em uma explicação definitiva em linguagem natural.

Valide os resultados com a camada final, compare as duas lentes, repita as intervenções e evite tirar conclusões de uma única execução.

Conclusão

As versões anteriores nos permitiam pausar a geração e perguntar por que o modelo havia selecionado um token em vez de outro. A v0.2 acrescenta duas perguntas mais difíceis: em que ponto essa direção se tornou legível e o que muda se intervirmos antes de ela chegar à saída?

Isso transforma a Miru Tracer de um visualizador de probabilidades em uma bancada experimental de interpretabilidade mecanicista. A lente de logits oferece leituras imediatas por camada, a lente jacobiana estende a visão às partes iniciais da rede e as intervenções transformam essas leituras em hipóteses que podem ser testadas no comportamento.

Nenhuma lente torna uma rede neural transparente. O que a v0.2 oferece é um ciclo mais estreito entre observação, intervenção e verificação, apoiado por um mecanismo de geração e um processo de lançamento mais confiáveis.

O post original sobre a Miru identificava activation steering como o próximo passo. Agora, ele faz parte de uma base mais ampla para inspecionar e testar como modelos de linguagem constroem suas saídas.

O lançamento da v0.2, o código-fonte e o tutorial da Lens estão disponíveis no GitHub.