Um guia prático para diagramas de Transformer
Todo mundo já viu aquele desenho com setas entrando e saindo de blocos retangulares. A maioria dos tutoriais que você encontra na internet mostra apenas a arquitetura final, pronta para impressão. O problema é que quando você tenta explicar isso para alguém ou precisa fazer uma apresentação própria, o desenho técnico sai truncado e a audiência simplesmente não consegue acompanhar. Eu passei por isso durante anos enquanto preparava slides para palestras e revisões de papers.
O que significa como desenhar os transformers
Desenhar um Transformer não é só traçar caixas e linhas. É decidir como representar fluxo de dados, dimensionalidade, paralelismo e as conexões residuais que todo mundo esquece de colocar. Eu costumava pular a normalização de camada nos meus primeiros rascunhos e depois passava meia hora tentando explicar por que a perda explodia durante o treinamento. A solução foi simples: adicionar o layer norm logo após cada sub-bloco e deixar claro no diagrama que o resíduo pula por cima, não por baixo. A parte mais difícil costuma ser o multi-head attention. Todo mundo desenha três setas saindo do mesmo bloco Q, K, V e depois as junta numa única linha de output. Isso funciona para um slide, mas se você quer mostrar o que realmente acontece, precisa dividir em heads individuais ou pelo menos indicar que o concatenamento acontece antes do peso linear final. Eu descobri isso na prática quando um colega de laboratório ficou confuso por duas semanas porque o diagrama não mostrava o split de dimensão.
Comece pelo fluxo, não pelos blocos
A maioria dos diagramas erra na ordem. Eles começam mostrando o encoder inteiro e só depois entra no decoder. O jeito certo é seguir a sequência temporal de processamento: entrada, embedding posicional, atenção, feed-forward, saída. Se você inverter essa lógica, o leitor perde o fio da meada porque não entende por que a mask causou aquele shape específico no padding. Eu costumo sempre começar meu rascunho com um tensor 1x8x768 na esquerda e mostrar como elevia para 1x8x64 depois do primeiro layer. Esse detalhe de dimensionalidade é o que separa um diagrama útil de um que ninguém consegue ler. A ferramenta que eu uso hoje é o Excalidraw porque permite arrastar conectores sem quebrar o layout quando você precisa redesenhar os heads de atenção.
Os componentes que não podem faltar
Input embedding: Aqui as pessoas erram ao mostrar apenas "tokens entram". O certo é indicar que cada token vira um vetor de 768 dimensões e que o positional encoding é somado, não concatenado. Sem esse detalhe, quem vê o diagrama não entende por que a ordem das palavras importa no modelo. Multi-head self-attention: Este é o coração do Transformer e também onde todos cometem erros. Cada head deve receber Q, K, V separados e o output de cada head vira um vetor de 64 dimensões que é concatenado com os outros heads. O peso linear final projeta de volta para 768. Eu levei três tentativas para fazer esse diagrama funcionar porque initially eu colocava todos os heads juntos num único bloco e depois ninguém entendia o shape mismatch.
Feed-forward network: As pessoas frequentemente esquecem de mostrar as duas camadas lineares com a ReLU no meio. O primeiroProjeta de 768 para 3072, a segunda volta para 768. Sem esses números, o diagrama fica vago e quem lê não consegue dimensionar a complexidade do modelo. Layer normalization e residual connections: Aqui é onde o diagrama fica-legível. Cada sub-bloco deve ter sua normalização e o resíduo deve ser mostrado pulando por cima, não por baixo. Eu passei por isso quando um estudante de mestrado ficou confuso porque o diagrama não mostrava a ordem correta das operações e achava que a normalização vinha antes da atenção.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Erro comum: pular o positional encoding
Todo mundo quer colocar o embedding e já ir para a atenção. O positional encoding é crucial e deveria ser mostrado como uma soma, não como um bloco separado. Eu descobri isso na prática quando um colega de trabalho ficou confuso por duas semanas porque o diagrama não mostrava que o position era adicionado ao embedding, não concatenado. A solução foi adicionar um pequeno bloco "positional encoding" logo após o embedding e indicar claramente no diagrama que a operação é uma soma. O detalhe de dimensionalidade que eu sempre incluo é mostrar o tensor passando de 1x8x768 para 1x8x64 depois do primeiro layer. Esse número ajuda quem lê o diagrama a entender como o modelo processa sequências curtas versus longas. A ferramenta que eu recomendo é o draw.io porque permite ajustar conectores sem refazer todo o layout quando você precisa redesenhar os heads de atenção.
Ferramentas e formatos
O formato SVG é o ideal porque permite zoom sem perder qualidade. Eu evito PNG porque quando você precisa ampliar o diagrama para mostrar os detalhes dos heads, a imagem fica pixelada e ninguém consegue ler os números de dimensionalidade. O Excalidraw também é bom para rascunhos rápidos porque permite conectar blocos sem travar o software quando você está ajustando o layout. O tempo médio que eu gasto refazendo um diagrama é de 20 a 30 minutos quando eu começo do zero. Isso inclui ajustar os conectores, verificar as dimensionalidades e garantir que todos os componentes estejam na ordem correta. Se você usar template pronto, esse tempo cai para cerca de 5 minutos, mas o resultado final costuma ficar genérico e pouco informativo.
O que funciona na prática
A técnica que eu recomendo é sempre começar com um rascunho em papel antes de passar para o digital. Isso ajuda a organizar os componentes na ordem certa e identificar quais conexões residuais são necessárias. Eu gasto cerca de 10 minutos no papel e depois 15 minutos no software para refinar o diagrama final. O resultado costuma ser mais limpo porque eu já tomei as decisões de layout no rascunho inicial. O detalhe que faz diferença é sempre mostrar as dimensionalidades em cada etapa. Quando eu deixo de colocar esses números no diagrama, as pessoas ficam confusas sobre como o modelo processa sequências de tamanhos diferentes. Eu recomendo incluir os shapes nos cantos dos conectores ou em pequenas legendas ao lado dos blocos. Isso evita perguntas repetidas sobre por que o tensor tem aquele tamanho.
Limitações que todo mundo ignora
Diagramas de Transformer funcionam mal para mostrar processos de treinamento. Eles são ótimos para explicar a arquitetura, mas péssimos para mostrar como os gradientes fluem durante o backpropagation. Se você precisa explicar o treinamento, recomendo um diagrama separado mostrando as atualizações de peso. Eu já perdi duas horas tentando encaixar tudo num único desenho e o resultado ficou ilegível. A principal limitação é que diagramas estáticos não mostram o paralelismo inerente ao Transformer. Eles são ótimos para uma visão geral, mas ruins para explicar por que o modelo consegue processar tokens em paralelo. Se você precisa demonstrar o paralelismo, recomendo um diagrama animado ou pelo menos indicar claramente no texto como os heads operam simultaneamente. Eu gastaria cerca de 45 minutos criando uma versão animada usando ferramentas como o Figma, mas o resultado vale a pena para apresentações técnicas.
Downloads e recursos
O template que eu uso está disponível gratuitamente em formato SVG no meu repositório pessoal. Você pode baixá-lo e adaptar para suas necessidades, mas eu recomendo ajustar as dimensionalidades para corresponder ao modelo específico que você está documentando. O template padrão usa 768 dimensões, mas se você trabalha com modelos menores como o TinyBERT, precisará ajustar para 384 ou 128 dimensões. Eu gastaria cerca de 15 minutos fazendo esses ajustes no template, mas o resultado final fica muito mais preciso para seu caso de uso. O tempo médio que eu dedico a atualizar meus diagramas é de 30 minutos por versão. Isso inclui verificar as conexões, atualizar os números de dimensionalidade e garantir que todos os componentes estejam na ordem correta. Se você usar uma ferramenta de versionamento como o Git, esse tempo cai para cerca de 10 minutos por atualização, mas o controle de mudanças fica muito mais organizado para colaborações em equipe.
