Amparada IA — modelo experimental:
Esta pasta contém uma prova de conceito de modelo de linguagem implementada com PyTorch e treinada do zero. É um projeto experimental para estudar tokenização, treinamento e geração de texto; não é um assistente pronto para atendimento.
Estado atual:
- Arquitetura: Transformer Decoder-only.
- Tokenização: BPE (Byte Pair Encoding) simples, implementado no projeto.
- Objetivo: prever o próximo token de uma sequência.
- Dados: arquivos UTF-8 separados para treino e validação.
- Checkpoint padrão:
runs/amparada_ia_bpe.pt.
O checkpoint armazena os pesos, a configuração e o vocabulário/fusões do tokenizador. Checkpoints antigos baseados em caracteres não são compatíveis com o formato BPE atual.
Tokenização BPE:
O tokenizador separa inicialmente palavras, sequências de espaços e grupos de pontuação. Depois aprende fusões de pares de símbolos frequentes no corpus de treino e reaplica essas fusões na ordem aprendida.
--vocab-size é uma meta, não um limite rígido: se o conjunto inicial de caracteres já for maior que o valor informado, o vocabulário final poderá ultrapassá-lo. Caracteres ausentes no vocabulário de treino são convertidos para <unk>.
Requisitos:
- Python 3.10 ou superior
- PyTorch 2.2 ou superior
- NumPy conforme
requirements.txt
Treinar:
Execute dentro desta pasta (Amparada IA), com o ambiente virtual ativado:
python -m src.amparada_ia.train --steps 2000
Para começar em um celular com memória limitada:
python -m src.amparada_ia.train --steps 350 --batch-size 1 --block-size 64 --n-embd 32 --n-head 4 --vocab-size 256
O corpus padrão é data/treino.txt; a validação usa data/validacao.txt. O tokenizador é aprendido somente com o corpus de treino. A validação não atualiza os pesos. O arquivo original de treino não é apagado.
O consumo de memória depende principalmente de --batch-size, --block-size, --n-embd, --n-head e --n-layer. Aumentar --steps aumenta o número de atualizações, mas não garante respostas melhores.
Gerar texto:
python -m src.amparada_ia.generate --prompt "Tecnologia responsável" --tokens 120
A geração usa o tokenizador armazenado no checkpoint para manter os mesmos IDs do treinamento.
Avaliar:
python -m src.amparada_ia.evaluate --batches 20 --batch-size 2
A avaliação calcula a perda em lotes do conjunto de validação. Perda menor pode indicar melhor previsão nesse conjunto, mas não comprova compreensão, factualidade ou segurança.
Limitações:
BPE pode representar partes frequentes de palavras com menos tokens do que a tokenização por caracteres, mas não cria conhecimento por si só. Fluência depende também da quantidade e qualidade do corpus, da capacidade do modelo e do treinamento. Um corpus e um modelo pequenos normalmente produzem texto pouco coerente.
Este protótipo pode repetir padrões, errar fatos ou gerar conteúdo inadequado. Não deve ser apresentado como serviço de acolhimento, aconselhamento jurídico, médico ou de emergência, nem conectado a fluxos reais de atendimento sem avaliação humana e revisão de segurança, privacidade, acessibilidade e proteção de dados.
Dados e segurança:
Use somente textos próprios, sintéticos ou de origem e licença verificadas. Preserve atribuições e condições de licença. Não adicione relatos privados, nomes, endereços, conversas ou informações identificáveis sobre situações reais de violência.
⚙️Arquitetura da Amparada IA:
Objetivo e estado atual:
A Amparada IA é uma prova de conceito para estudar os fundamentos de modelos de linguagem. O modelo é inicializado com parâmetros aleatórios e aprende padrões estatísticos a partir do corpus fornecido.
Implementação atual:
- Transformer Decoder-only.
- Tokenizador BPE simples, implementado no projeto.
- Previsão autorregressiva do próximo token.
- Treinamento com PyTorch e otimizador AdamW.
- Checkpoint com pesos, configuração e estado do tokenizador.
Fluxo de dados:
- O programa lê
data/treino.txt e data/validacao.txt como UTF-8.
- O tokenizador BPE é aprendido exclusivamente a partir do texto de treino.
- O texto é inicialmente separado em palavras, sequências de espaços e grupos de pontuação; depois são aprendidas fusões de pares frequentes.
- Cada token vira um ID inteiro. Símbolos desconhecidos são convertidos para
<unk>.
- O treinamento seleciona janelas aleatórias de
block_size tokens. A entrada contém a sequência e o alvo contém a mesma sequência deslocada uma posição à frente.
- O modelo produz logits para cada posição, isto é, pontuações para o próximo token.
- A entropia cruzada calcula a perda entre os logits e os tokens-alvo.
- AdamW atualiza os parâmetros. Os gradientes são limitados por norma máxima de 1,0.
- Em intervalos definidos, a perda é estimada separadamente nos dados de treino e validação. A validação não atualiza os pesos.
- Ao final, o checkpoint salva os pesos, a configuração, o tokenizador (vocabulário e fusões) e informações básicas do treinamento.
Componentes do modelo:
Embeddings
- Embedding de tokens: transforma cada ID em um vetor de dimensão
n_embd.
- Embedding posicional aprendido: adiciona informação sobre a posição de cada token, até o limite de
block_size.
Blocos causais:
Cada bloco contém:
- LayerNorm antes da atenção (Pre-LN).
- Atenção multi-head causal: uma máscara triangular impede que uma posição consulte tokens futuros.
- Conexão residual: soma a saída da atenção à representação de entrada.
- LayerNorm antes da rede feed-forward.
- Rede feed-forward: expande a dimensão para
4 × n_embd, aplica GELU, projeta de volta para n_embd e aplica dropout.
- Conexão residual: soma a saída feed-forward à representação anterior.
O número de blocos é controlado por n_layer; o número de cabeças, por n_head.
Saída e geração:
Uma LayerNorm final prepara as representações. A cabeça de linguagem é uma camada linear que produz pontuações para cada token do vocabulário em cada posição. A função de perda treina a previsão do próximo token.
Na geração, o modelo aplica softmax às pontuações da última posição, ajustadas pela temperatura, e amostra o próximo token. O processo se repete de forma autorregressiva, mantendo o contexto dentro de block_size.
Tokenizador BPE:
O tokenizador começa com caracteres dentro de unidades separadas por uma expressão regular e aprende fusões de pares adjacentes ponderadas pela frequência das unidades no corpus. A ordem das fusões é armazenada e reutilizada durante a codificação.
O vocabulário e as fusões são serializados no checkpoint, garantindo que geração e avaliação usem o mesmo mapeamento de IDs do treinamento.
--vocab-size funciona como meta. O conjunto inicial de caracteres pode, por si só, exceder essa meta; portanto, o tamanho final não é necessariamente limitado ao valor informado. Caracteres ausentes no vocabulário são representados por <unk>.
Dados e validação:
Treino e validação devem ser arquivos distintos. O tokenizador é aprendido somente no treino, evitando aprender fusões a partir da validação. A validação acompanha a perda em dados que não atualizam os pesos. Se o texto de validação contiver caracteres ausentes no vocabulário de treino, eles serão convertidos para <unk>; muitos desconhecidos tornam a avaliação menos representativa.
Métricas e interpretação:
A perda é a entropia cruzada média da previsão do próximo token. A perplexidade é a exponencial da perda média. Nenhuma dessas métricas, isoladamente, comprova compreensão, factualidade, segurança, utilidade ou qualidade de acolhimento.
Limitações e segurança:
O corpus, a capacidade reduzida e o treinamento limitado restringem a qualidade da geração. O modelo pode produzir texto sem sentido, repetir padrões, inventar informações ou gerar conteúdo inadequado. Prever sequências prováveis não equivale a compreender seu significado.
Não use este protótipo para aconselhamento, triagem de risco, atendimento de emergência ou decisões sobre pessoas. Não o conecte a usuárias em situações reais sem avaliação humana e revisão especializada de segurança, privacidade, acessibilidade e proteção de dados.
Não inclua no corpus dados pessoais, relatos privados de violência, conversas, documentos, endereços ou identificadores de usuárias. Use textos próprios, sintéticos ou com origem e licença verificadas, preservando as atribuições e condições aplicáveis.
Retrieval-Augmented Generation (RAG):
A Amparada IA utiliza Retrieval-Augmented Generation (RAG) para complementar a geração de respostas com informações recuperadas de fontes externas ou bases de conhecimento disponíveis.
O RAG permite que o modelo utilize informações relevantes durante a geração de respostas, reduzindo a dependência exclusiva dos conhecimentos adquiridos durante o treinamento.
Como funciona:
O processo de RAG envolve três etapas principais:
- Recuperação: busca informações relevantes na base de conhecimento a partir da consulta recebida.
- Contextualização: organiza e disponibiliza as informações recuperadas como contexto para o modelo.
- Geração: o modelo utiliza a consulta e o contexto recuperado para produzir uma resposta.
Integração com o modelo:
O RAG atua como um mecanismo complementar à arquitetura Transformer Decoder-only da Amparada IA.
Enquanto o modelo é responsável pelo processamento da linguagem e pela geração de texto, o RAG permite consultar informações adicionais que podem enriquecer as respostas.
Benefícios:
- Acesso a informações complementares ao treinamento.
- Possibilidade de utilização de bases de conhecimento atualizáveis.
- Respostas contextualizadas com informações recuperadas.
- Separação entre recuperação de informações e geração de texto.
Limitações:
O RAG não garante que todas as informações recuperadas estejam corretas ou atualizadas. A qualidade das respostas depende da relevância, qualidade e disponibilidade das fontes consultadas.
A utilização de RAG também não elimina completamente a possibilidade de respostas incorretas ou informações não verificadas.
🌐 Site oficial: https://mulher-amparada.github.io/mulher-amparada-app/
💻 Repositório GitHub: https://github.com/mulher-amparada/mulher-amparada-app