Transformer Encoder Simplificado

Descrição do Projeto

Este repositório implementa um Encoder Transformer simplificado utilizando Python e NumPy, com o objetivo educacional de demonstrar os componentes matemáticos e arquiteturais fundamentais de um modelo Transformer. O projeto implementa o mecanismo de self-attention, normalização de camadas, redes feed-forward e o empilhamento de múltiplas camadas de encoder, conforme descrito na arquitetura original do modelo Transformer.

A implementação utiliza apenas bibliotecas numéricas (NumPy e Pandas), sem depender de frameworks de deep learning como TensorFlow ou PyTorch, permitindo uma compreensão mais profunda dos algoritmos subjacentes.

---

Objetivo

O objetivo principal deste projeto é fornecer uma implementação clara e educacional dos componentes principais de um Transformer Encoder, permitindo que estudantes compreendam:

• O mecanismo de scaled dot-product attention
• A implementação de self-attention com múltiplas projeções
• O papel da normalização de camadas (Layer Normalization)
• A estrutura das redes feed-forward
• O processo de empilhamento de camadas do encoder

---

Estrutura do Repositório

Transformer-Encoder/
├── preparacao_dados.py        # Preparação dos dados de entrada
├── componentes_transformer.py # Implementação dos componentes matemáticos
├── encoder_transformer.py     # Empilhamento do encoder com 6 camadas
└── README.md                  # Este arquivo

Descrição dos Arquivos

preparacao_dados.py

Responsável pela preparação e formatação dos dados de entrada para o modelo:

• Definição do vocabulário com mapeamento de palavras para IDs
• Conversão de tokens em identificadores numéricos
• Criação da matriz de embeddings aleatória (tamanho: vocabulário × d_model)
• Processamento de sentença para gerar o tensor de entrada X com formato (batch, seq_length, d_model)

Formato da saída: Tensor X de dimensões (1, 2, 64), correspondendo a 1 amostra, 2 tokens e 64 dimensões de modelo.

componentes_transformer.py

Implementa o motor matemático do Transformer com as seguintes funções:

• funcao_softmax(z): Função softmax com normalização numérica para evitar overflow
• scaled_dot_product_attention(Q, K, V): Implementa o mecanismo de scaled dot-product attention
  • Calcula o produto escalar entre Q (queries) e K (keys)
  • Normaliza pelo fator √d_k (raiz quadrada da dimensão de keys)
  • Aplica softmax para obter os pesos de atenção
  • Retorna a soma ponderada com V (values) e os pesos de atenção
• normalizacao_camada(x, eps): Normalização de camadas para estabilização numérica
• add_and_norm(X, sublayer_output): Combina a conexão residual (skip connection) com normalização
• funcao_relu(x): Função de ativação ReLU
• RedeFFN: Rede feed-forward com duas camadas lineares e ativação ReLU
  • Dimensão intermediária: d_ff = 4 × d_model
• ScaledDotProductAttention: Implementa self-attention com projeções lineares para Q, K e V

encoder_transformer.py

Implementa o Transformer Encoder com 6 camadas empilhadas:

Para cada uma das 6 camadas, aplica-se sequencialmente:

1. Self-Attention → Output de atenção
2. Add + Norm → Conexão residual + normalização de camada
3. Feed Forward → Rede feed-forward
4. Add + Norm → Conexão residual + normalização de camada

O arquivo inclui validações de sanidade para garantir:

• Manutenção das dimensões do tensor de entrada
• Alteração dos valores durante o processamento (verificação de que o modelo está funcionando)

Saída: Tensor Z com representações contextualizadas dos tokens de entrada.

---

Requisitos

O projeto requer as seguintes dependências:

• Python (versão 3.7 ou superior)
• NumPy (para operações numéricas e álgebra linear)
• Pandas (para manipulação e exibição de dados)

Para instalar as dependências, execute:

pip install numpy pandas

---

Como Executar o Projeto

O projeto segue uma pipeline sequencial de execução:

1. Preparação dos Dados

Execute preparacao_dados.py primeiro para preparar e visualizar os dados de entrada:

python preparacao_dados.py

Saída esperada:

• DataFrame com o vocabulário: palavras e seus identificadores
• Lista de IDs dos tokens
• Shape da matriz de embeddings: (2, 64)
• Shape do tensor de entrada X: (1, 2, 64)

2. Teste dos Componentes de Atenção

Execute componentes_transformer.py para validar as funções de self-attention:

python componentes_transformer.py

Saída esperada:

• Resultado da função softmax
• Shape do tensor de saída da self-attention

3. Execução Completa do Encoder

Execute encoder_transformer.py para processar os dados através de todas as 6 camadas do encoder:

python encoder_transformer.py

Saída esperada:

• Confirmação de manutenção das dimensões
• Confirmação de alteração dos valores no tensor
• Mensagem de validação bem-sucedida: VALIDAÇÃO DE SANIDADE: PASSOU
• Tensor Z final com representações contextualizadas

Execução Sequencial Recomendada

Para uma execução completa do pipeline:

python preparacao_dados.py && python componentes_transformer.py && python encoder_transformer.py

Ou simplesmente:

python encoder_transformer.py

Este comando importa automaticamente os outros módulos.

---

Formato do Tensor de Entrada

O tensor de entrada X segue o formato padrão da arquitetura Transformer:

$$X \in \mathbb{R}^{B \times T \times d_{model}}$$

Onde:

• B (Batch): Número de amostras no lote (neste projeto: 1)
• T (Tokens/Sequence Length): Número de tokens na sequência (neste projeto: 2)
• d_model: Dimensionalidade do espaço de embedding (neste projeto: 64)

Exemplo: Um tensor de entrada com shape (1, 2, 64) representa:

• 1 amostra (batch size)
• 2 tokens na sequência
• 64 dimensões para cada token

Este formato é mantido constante através de todas as 6 camadas do encoder.

---

Validação de Sanidade do Modelo

O arquivo encoder_transformer.py implementa validações automáticas para garantir o funcionamento correto do modelo:

Verificações Realizadas

1. Preservação de Dimensões: Confirma que o tensor de saída possui as mesmas dimensões do tensor de entrada (1, 2, 64)
2. Dimensão de Model: Valida que a última dimensão permanece igual a 64 (d_model)
3. Alteração de Valores: Verifica que os valores do tensor foram modificados durante o processamento, confirmando que o modelo não está apenas retornando a entrada inalterada

Resultado da Validação

Ao executar o encoder completo com sucesso, o programa exibe:

ok - Dimensoes: (1, 2, 64)
ok - d_model: 64
ok - Valores foram alterados

>>> VALIDACAO DE SANIDADE: PASSOU <<<

Se alguma validação falhar, o programa lançará uma exceção (ValueError) indicando o problema específico.

---

Uso de Inteligência Artificial

Este projeto foi desenvolvido como trabalho acadêmico. Durante o desenvolvimento, ferramentas de inteligência artificial generativa foram utilizadas exclusivamente para as seguintes finalidades:

Funções de Suporte das Ferramentas de IA

• Esclarecimento de sintaxe: Dúvidas sobre funções do NumPy (broadcasting, transpose de matrizes 3D)
• Revisão de código: Identificação de possíveis erros de implementação
• Validação técnica: Verificação da correspondência entre a implementação e a teoria do Transformer Encoder

---

Referências

• Vaswani, A., Shazeer, N., Parmar, N., et al. (2017). "Attention is All You Need". Advances in Neural Information Processing Systems, 30.

---

Autor

Desenvolvido como projeto acadêmico para a disciplina de Tópicos em Inteligência Artificial - 2026.1

Instituição: iCEV - Instituto de Ensino Superior

---

Última atualização: 07/03/2026