DEV Community: Von Grossi

Como testar Sistemas multiagentes com ADK

Von Grossi — Tue, 29 Sep 2026 21:05:52 +0000

O que aprendi construindo um pipeline com Google ADK, MCP e modelos locais

Sistemas multiagentes costumam ser apresentados de uma maneira muito atraente. Um agente pesquisa, outro escreve, um terceiro revisa e o resultado parece pronto para produção.

O problema aparece quando o resultado está quase certo.

Um título passa do limite permitido. Uma URL parece real, mas não existe. Um agente de revisão recebe o caminho errado. Um validador deveria interromper o fluxo, mas não consegue enxergar o estado produzido na etapa anterior.

Foi justamente para explorar esse tipo de problema que organizei o repositório adk-multiagent. Ele reúne oito agentes em Python usando o Google Agent Development Kit, conhecido como ADK, além de um servidor local MCP, testes offline, integração com RAG, revisão de código, verificação de links e uma cadeia de modelos hospedados e locais.

A ideia central do projeto é simples:

O modelo deve interpretar, decidir e explicar. O código deve medir, limitar, buscar e rejeitar.

Essa separação torna o comportamento dos agentes mais previsível e também mais fácil de testar.

O projeto não é apenas uma coleção de agentes

Cada agente fica em sua própria pasta e expõe um root_agent em agent.py. Existe também um common.py, responsável por montar a cadeia de modelos usada pelos agentes.

A estrutura prática é parecida com esta:

blogger          planejamento, escrita e validação
linkcheck        verificação de URLs e fontes
seo              metadados para publicação
rag              documentos indexados e respostas com citações
codereview       leitura segura de arquivos e heurísticas
triage           classificação e roteamento por confiança
mcp_text_audit   agente que consome um servidor MCP local
researcher       exemplo mínimo de um agente
common.py        cadeia de modelos e fallback

O ADK trata agentes como unidades de execução com modelo, instruções e ferramentas. Aplicações maiores podem combinar essas unidades em hierarquias ou workflows. A documentação oficial explica os conceitos em ADK Agents e ADK Workflows.

No projeto, a divisão de pastas também representa uma divisão de responsabilidades. Cada fronteira existe para controlar um tipo diferente de falha.

Problema	Solução usada no projeto
O modelo erra uma contagem de caracteres	Validação em Python
Uma URL parece plausível, mas é falsa	HTTP e busca de fontes
O agente tenta ler um arquivo indevido	Caminho limitado ao diretório do projeto
Um segredo passa despercebido	Heurísticas executadas antes do modelo
O validador não enxerga o resultado anterior	Interpolação explícita do estado
Um servidor MCP apresenta comportamento difícil de reproduzir	Servidor local e testes offline

Por isso, o projeto é mais interessante como estudo de fronteiras de controle do que como demonstração de vários agentes conversando entre si.

O fluxo em uma imagem

O repositório já inclui dois diagramas do fluxo principal, um para temas claros e outro para temas escuros. Eles mostram a sequência entre o agente Blogger, o planejador, o escritor e os validadores.

O diagrama ajuda a perceber que o sistema não é uma conversa livre entre agentes. Existe uma sequência definida, existem artefatos compartilhados e existem pontos claros em que o processo pode ser aprovado ou repetido.

O pipeline de blog mostra onde o estado realmente importa

O agente blogger é o exemplo mais completo do repositório. Ele recebe um tema, cria um outline, escreve o artigo e passa o resultado por validadores.

O fluxo usa dois blocos principais. Um planeja o outline e outro escreve o texto. Cada bloco tem um gerador e um validador. O validador pode responder ok ou retry. Quando o resultado está adequado, um callback encerra o loop. Quando existe um problema, o gerador recebe o feedback e tenta novamente.

Os artefatos intermediários ficam registrados no estado:

blog_outline         outline produzido pelo planejador
outline_validation   resultado da validação do outline
blog_post            artigo produzido pelo escritor
post_validation      resultado da validação do artigo

Aqui existe uma diferença importante entre armazenar um valor e torná-lo visível para o modelo.

Não basta escrever no prompt algo como “verifique o conteúdo de blog_outline”. O valor precisa ser interpolado na instrução. O projeto usa expressões como {blog_outline?} e {post_validation?} para isso.

O ponto de interrogação também é importante. Na primeira execução, a chave ainda pode não existir. A forma opcional evita que o pipeline falhe antes mesmo de produzir o primeiro resultado.

Esse detalhe parece pequeno, mas é uma das diferenças entre um agente que apenas possui memória de execução e um agente que realmente consegue trabalhar com os artefatos produzidos por outros agentes.

A validação também não fica restrita a um comentário no final. Ela participa do controle do fluxo. Um resultado aprovado encerra o loop. Um resultado rejeitado gera uma nova tentativa.

O projeto ainda usa LoopAgent nessa parte porque, segundo a documentação do próprio repositório, o novo Workflow não pode ser usado como subagente de um LlmAgent nesse arranjo específico. A documentação atual do ADK recomenda workflows para novas orquestrações determinísticas quando eles atenderem ao caso de uso. Portanto, este exemplo deve ser entendido como uma solução compatível com a arquitetura atual do projeto, não como uma regra para todo sistema novo.

O que deve sair do prompt e virar código

Uma das decisões mais importantes do projeto foi retirar algumas tarefas simples do modelo.

Metadados para SEO

O agente de SEO produz título, descrição, slug, tags e texto alternativo. Os limites são verificados em Python, incluindo quantidade de caracteres, normalização do slug e número máximo de tags.

O modelo continua sendo útil para escolher palavras e adaptar o texto. Mas não é razoável depender dele para provar que uma string tem menos de cem caracteres.

Uma instrução pode pedir “mantenha o título abaixo de cem caracteres”. Uma função pode verificar essa condição com precisão.

Essa é uma boa regra para qualquer sistema com LLM: deixe o modelo sugerir o valor e deixe o código validar o contrato.

Revisão de código

O agente de revisão lê o arquivo real antes de opinar. A ferramenta de leitura aceita apenas arquivos dentro do diretório definido para o projeto. O modelo não recebe liberdade para escolher qualquer caminho do sistema.

Antes de chamar o modelo, o código também procura padrões associados a chaves de API, strings de conexão com credenciais e blocos except: genéricos.

O modelo pode explicar a gravidade do problema e organizar os achados. Ele não deveria ser a única camada responsável por descobrir um segredo escrito literalmente em um arquivo.

Verificação de links

O agente linkcheck separa duas perguntas diferentes:

A URL responde por HTTP?
Existe uma fonte sobre o assunto que a URL deveria representar?

A primeira verificação encontra domínios inválidos, páginas removidas e erros de rede. A segunda tenta encontrar URLs que parecem convincentes, mas não correspondem ao assunto informado.

Isso também mostra por que “a citação está correta” não é um teste único. É necessário verificar existência, identidade, assunto e, dependendo do caso, se a fonte realmente sustenta a afirmação.

MCP é uma fronteira de integração

O exemplo mcp_text_audit conecta um agente ADK a um servidor MCP local por standard input e standard output.

O servidor expõe três ferramentas determinísticas:

Contar caracteres, palavras, linhas e URLs.
Encontrar placeholders não preenchidos.
Identificar padrões que podem indicar segredos gravados no código.

São tarefas adequadas para uma ferramenta porque um modelo pode responder com muita confiança e ainda assim errar uma contagem ou ignorar um placeholder.

O projeto também documenta duas armadilhas práticas.

A primeira é que mensagens de diagnóstico em stdout podem corromper o fluxo JSON RPC. Logs devem ir para stderr.

A segunda é que a criação dos parâmetros de conexão não significa necessariamente que a conexão já foi aberta. Alguns erros só aparecem quando a sessão é iniciada. Por isso, o tratamento de exceções precisa envolver a operação que realmente abre a conexão.

Esses pontos não são exclusivos do ADK. Um servidor MCP só é confiável quando seu processo, transporte, timeout, schema e tratamento de erros também são observáveis e testados. A especificação oficial pode ser consultada no Model Context Protocol.

Uma execução real do agente MCP

Para testar o servidor local, foi enviada a seguinte entrada:

Audite o texto abaixo usando as ferramentas disponíveis:

Título: Guia de deploy {ENVIRONMENT}
API_KEY=demo_key_123456
URL: https://example.com/documentacao
Este texto possui um placeholder não preenchido e uma credencial de demonstração.

O trace registrou a inicialização da sessão MCP, a listagem das ferramentas e três chamadas de ferramenta: achar_placeholders, achar_segredos e contar_texto. A execução completa levou aproximadamente 18,43 segundos na interface observada.

O resultado confirmou o placeholder {ENVIRONMENT}, contou 180 caracteres, 24 palavras, 4 linhas e uma URL. A ferramenta de segredos retornou limpo: true para esse texto de demonstração.

Esse último resultado merece uma observação. O texto continha a string API_KEY=demo_key_123456, mas a heurística não a classificou como segredo. Isso não significa que o detector esteja errado. A ferramenta pode ter sido desenhada para reconhecer padrões específicos, ou pode considerar valores explícitos de demonstração como não sensíveis. O que a execução comprova é mais limitado: esse formato específico não foi marcado pela regra atual.

Essa é uma boa ilustração da diferença entre ter uma ferramenta e ter cobertura completa. O MCP retirou do modelo a tarefa de contar e procurar padrões, mas as regras determinísticas ainda precisam ser ampliadas e testadas contra uma coleção de exemplos positivos e negativos.

O trace também mostra uma segunda chamada ao modelo depois das ferramentas. O servidor executa as operações determinísticas, o agente recebe os resultados e então produz uma resposta legível para o usuário. O fluxo observado é:

inicialização MCP → descoberta das ferramentas → chamadas determinísticas → resposta do agente

Triage com classificação e confiança

O próximo experimento foi o agente triage, responsável por classificar mensagens de suporte e escolher uma fila.

A entrada usada foi:

O cliente não consegue acessar o painel desde esta manhã.
A autenticação retorna erro 401 mesmo depois da redefinição da senha.
O problema afeta toda a equipe.

O trace mostrou uma latência total aproximada de 8,09 segundos. Também apareceram duas chamadas ao modelo, uma chamada à função classificar_ticket e uma geração final de resposta.

O resultado observado foi:

Route: auto:technical
Department: technical
Confidence: 1.00
Urgency: yes
Frustration: low
Runner-up category: billing
Runner-up confidence: 0.00

O chamado foi encaminhado para a área técnica porque descrevia um erro de autenticação 401 que afetava toda a equipe. A urgência foi marcada como verdadeira e a confiança retornada foi 1,00.

Esse resultado mostra o comportamento do agente nessa execução, mas não prova que a confiança esteja calibrada. Para afirmar calibração seria necessário usar um conjunto de tickets rotulados, comparar as previsões com os resultados reais e medir se uma confiança de 0,80, por exemplo, corresponde aproximadamente a 80% de acertos.

Também é importante distinguir o que o print comprova sobre o JEV. As imagens mostram o agente, a função de classificação, as chamadas ao modelo e o resultado final. Elas não mostram explicitamente o nome do provedor ou do modelo usado em cada chamada. Para documentar o JEV com precisão, será necessário capturar a configuração ativa ou o log que identifica o modelo.

Mesmo assim, o experimento já demonstra uma propriedade importante do pipeline: a classificação não é apresentada apenas como uma categoria. Ela inclui departamento, urgência, frustração, confiança e uma alternativa de roteamento.

Onde o JEV entra na arquitetura

A execução do triage usa o OpenRouter como provider para acessar o JEV. Isso é diferente de usar um modelo Gemini diretamente pelo caminho suportado pelo ADK.

O OpenRouter funciona aqui como uma camada de acesso ao modelo. O agente continua sendo construído e executado pelo ADK, mas a chamada de inferência passa por um provider externo compatível com a interface utilizada pelo projeto.

Na tela do OpenRouter, o modelo aparece como Jev 1.13, associado à TypeSafe. A descrição também indica que o modelo retorna decisões estruturadas e foi projetado para roteamento e classificação, em vez de texto livre.

Essa arquitetura explica uma diferença importante do laboratório. O ADK oferece o runtime do agente, o estado, as ferramentas e a orquestração. O OpenRouter fornece o acesso ao modelo selecionado. O JEV, por sua vez, produz a decisão estruturada usada pelo agente de triage.

Não devemos descrever isso como suporte nativo do ADK ao JEV. A formulação mais precisa é:

O projeto integra o JEV ao ADK por meio do OpenRouter, usando uma camada externa de acesso ao modelo.

Essa distinção também é relevante para avaliação. O eval do ADK foi projetado para o caminho de modelos Gemini usado diretamente no ambiente ADK. A execução com JEV via OpenRouter pode funcionar no runtime, mas não é automaticamente coberta pelo mesmo mecanismo de avaliação.

Antes de publicar a captura do OpenRouter, é necessário ocultar o endereço de e-mail visível no canto superior esquerdo. O print também contém informações de uso e custo da conta. Podemos manter apenas o nome do modelo, a associação com a TypeSafe e os detalhes técnicos necessários para explicar a integração.

RAG começa com uma decisão de indexação

O agente de RAG indexa documentos no ChromaDB e responde com citações. O projeto separa a criação do índice da consulta. Isso evita gerar embeddings novamente a cada pergunta.

Também existem regras diferentes para Markdown e código. Documentos Markdown são divididos por cabeçalhos. Código é dividido por blocos de linhas que preservam melhor as funções.

Essa separação revela dois custos diferentes:

O custo de criar e atualizar o índice.
O custo de recuperar contexto para cada pergunta.

O README do projeto relata o uso de gemini-embedding-001 e observa que a cota de embeddings pode ser consumida antes da cota de geração de texto. Essa observação é útil para entender o ambiente utilizado no projeto, mas não deve ser tratada como uma garantia de custo ou desempenho para qualquer aplicação.

O mesmo cuidado vale para os números registrados sobre modelos locais, latência e qualidade. Eles dependem do hardware, da quantização, do prompt, da versão do modelo e da data da medição.

Uma execução observada no ADK Web

Depois de executar o agente pela linha de comando, a interface Web do ADK permitiu observar o mesmo fluxo por dentro.

A aba de eventos mostra o agente Blogger chamando o planejador e depois o escritor. Também aparecem os artefatos registrados no estado, como blog_outline, outline_validation, blog_post e post_validation.

Esse detalhe é mais importante do que o artigo final isoladamente. A interface mostra que o pipeline possui etapas intermediárias observáveis. O resultado não surge de uma única chamada invisível. Ele passa por planejamento, escrita e validação.

A aba de traces decompõe a execução em chamadas de modelo, agentes e validadores. Nesta execução específica, a latência total exibida foi de aproximadamente 54,81 segundos. O planejador aparece com cerca de 14,49 segundos e o escritor com cerca de 20,50 segundos. Os validadores também aparecem como etapas separadas.

Esses números não são um benchmark. Eles representam uma única execução em um ambiente específico. Ainda assim, são úteis para mostrar como a interface ajuda a localizar onde o tempo foi consumido.

Durante a mesma análise, a interface apresentou um aviso de performance informando que as instruções do sistema haviam sido modificadas entre turnos. Isso causou um context cache miss e aumentou a latência.

Esse aviso não indica uma falha do agente. Ele mostra que o custo de uma execução não depende apenas do modelo. A forma como as instruções são construídas e reutilizadas também pode afetar o desempenho.

Essa é uma das razões pelas quais traces são importantes em sistemas agentic. Sem eles, uma execução lenta pode parecer apenas um modelo lento. Com eles, é possível investigar chamadas individuais, retries, mudanças de instrução e etapas de validação.

O output completo de uma execução

O comando utilizado foi:

adk run blogger "Escreva um artigo técnico sobre structured concurrency em Python"

O output completo foi o seguinte:

Log setup complete: /tmp/agents_log/agent.20260929_090719.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log

[ADK] Aviso experimental: FALLBACK_MODEL habilitado.
[ADK] Aviso experimental: InMemoryCredentialService habilitado.
Session ID: [omitido nesta publicação]
[ADK] Aviso experimental: JSON_SCHEMA_FOR_FUNC_DECL habilitado.

[Blogger]: Aqui está o artigo técnico solicitado sobre Concorrência Estruturada em Python.

# Concorrência Estruturada em Python: O Fim do Caos em Código Assíncrono

Se você escreve código assíncrono em Python há algum tempo, provavelmente já se deparou com tarefas que esqueceram de terminar, exceções silenciosas que derrubaram seu serviço ou vazamentos de memória causados por corrotinas que continuaram rodando em background muito depois de sua função principal ter retornado.

O culpado por esses problemas costuma ser a concorrência não estruturada.

## O Problema dos Fire and Forget

Em sistemas assíncronos tradicionais, é muito fácil disparar uma tarefa e esquecê-la:

async def processar_dados():
    asyncio.create_task(tarefa_background())
    return "Sucesso"

O problema aqui é o ciclo de vida. Se a função processar_dados falhar, a tarefa background pode continuar rodando. Se ela levantar uma exceção, essa exceção pode não ser tratada pelo bloco principal.

## O Que é Concorrência Estruturada?

A concorrência estruturada propõe que tarefas assíncronas sigam regras de escopo semelhantes às estruturas tradicionais de controle.

Uma tarefa deve ter início, meio e fim definidos dentro de um escopo. Quando o escopo termina, as tarefas relacionadas devem terminar ou ser canceladas de forma previsível.

## A Evolução: Trio e asyncio.TaskGroup

A ideia foi popularizada pela biblioteca Trio, com o conceito de Nursery. O Python 3.11 introduziu o asyncio.TaskGroup na biblioteca padrão.

Antes:

await asyncio.gather(tarefa_1(), tarefa_2())

Com Python 3.11 ou superior:

async def main():
    async with asyncio.TaskGroup() as tg:
        t1 = tg.create_task(tarefa_1())
        t2 = tg.create_task(tarefa_2())

    print("Todas finalizadas com sucesso.")

## Benefícios principais

1. Gestão de erros mais determinística.
2. Maior previsibilidade sobre o ciclo de vida das tarefas.
3. Melhor rastreabilidade durante a investigação de falhas.

## Limitações e cuidados

O uso de TaskGroup não elimina a necessidade de tratar cancelamentos. As tarefas devem executar a limpeza necessária em blocos finally e respeitar asyncio.CancelledError.

Também é importante revisar afirmações sobre asyncio.gather. Quando uma tarefa falha, gather pode propagar a primeira exceção sem cancelar automaticamente as outras tarefas. Elas podem continuar executando, dependendo do contexto.

## Títulos alternativos

1. Concorrência Estruturada: Como o Python 3.11 tornou seu código assíncrono mais seguro.
2. Por que você deve parar de usar fire and forget em Python.
3. Domando o caos assíncrono com asyncio.TaskGroup.

## Hooks para redes sociais

TaskGroup no Python 3.11 mudou a forma de estruturar tarefas assíncronas. O importante não é apenas iniciar tarefas, mas também controlar seu ciclo de vida.

Esse output é uma evidência de geração bem sucedida do pipeline. Ele não é, sozinho, uma prova de correção técnica. A saída ainda precisa passar por revisão humana, principalmente em afirmações sobre cancelamento, exceções e diferenças entre asyncio.gather e asyncio.TaskGroup.

Quando o laboratório falha

Nem toda execução terminou com um artigo. Em uma tentativa posterior, a interface do ADK Web apresentou um erro HTTP 400 com o código INVALID_ARGUMENT:

Please ensure that a function call turn comes immediately after a user turn
or after a function response turn.

Esse erro indica que o backend rejeitou a sequência de mensagens usada durante uma chamada de ferramenta. O contrato esperado exige que uma chamada de função apareça imediatamente depois de uma mensagem do usuário ou depois de uma resposta de função.

Neste ponto, é importante não transformar a mensagem em uma conclusão maior do que a evidência permite. O print comprova que a execução falhou durante o processamento de uma chamada de função. Ele não comprova, sozinho, se a causa foi o modelo, o adaptador, a montagem do histórico, uma repetição do loop ou uma combinação específica de mensagens.

O próximo passo de investigação é consultar o trace da execução e verificar a sequência exata de mensagens antes da chamada que falhou. Também vale comparar essa execução com a execução bem sucedida, observando:

Qual modelo estava ativo.
Qual agente estava executando.
Se havia ocorrido um retry antes do erro.
Qual ferramenta foi chamada.
Se existiam duas mensagens de ferramenta ou duas chamadas consecutivas sem a resposta intermediária esperada.

Esse incidente também mostra por que uma demo técnica precisa registrar falhas. Um agente pode funcionar em uma execução e falhar na seguinte por causa de uma diferença no histórico, no modelo ou no formato de tool calling. Documentar apenas o resultado final esconderia justamente a parte mais útil do experimento.

Por enquanto, a conclusão segura é: o pipeline possui uma dependência sensível ao protocolo de chamadas de função, e essa dependência precisa ser observada em cada combinação de ADK, modelo e adaptador.

O trace dessa tentativa acrescenta uma informação importante. A execução teve latência total de aproximadamente 898,85 milissegundos. O maior bloco aparece associado ao agente Blogger, com cerca de 708,09 milissegundos. Dentro dele, a chamada call_llm levou aproximadamente 658,22 milissegundos e generate_content cerca de 640,01 milissegundos.

O trace não mostra chamadas ao RobustBlogPlanner, ao RobustBlogWriter ou aos validadores. Isso sugere que a falha ocorreu antes de o pipeline entrar nas etapas de planejamento e escrita. A evidência disponível aponta para a primeira chamada ao modelo, durante generate_content, e não para um problema no loop de validação.

Ainda não é possível concluir apenas com esse trace se o histórico já estava inválido antes da chamada ou se o backend rejeitou o formato enviado naquele momento. Para diferenciar essas hipóteses, seria necessário inspecionar o payload ou os eventos detalhados da chamada e comparar a configuração do modelo com a execução bem sucedida.

A mesma execução em uma sessão nova

Para verificar se o erro era reproduzível, a mesma solicitação foi executada em uma sessão nova do ADK Web:

Escreva um artigo técnico sobre structured concurrency em Python

Nesta segunda tentativa, o fluxo foi concluído. A interface mostrou novamente o planejador, o escritor, os artefatos de estado e o resultado final. O estado terminou com post_validation: "ok".

Essa comparação é mais informativa do que olhar apenas para a mensagem de erro. O mesmo prompt falhou em uma sessão e funcionou em outra. Portanto, não há evidência suficiente para atribuir o problema diretamente ao conteúdo do artigo ou ao código do validador.

O incidente passa a ser classificado como uma falha intermitente ou dependente do estado da sessão. As hipóteses mais prováveis ainda precisam ser verificadas no trace detalhado:

Histórico de mensagens deixado pela sessão anterior.
Sequência de chamadas de função construída durante a execução.
Estado temporário do backend ou do modelo.
Diferença de contexto entre a sessão reutilizada e a sessão nova.

O resultado também mostra uma prática útil para laboratórios com agentes: quando uma execução falhar, repetir o mesmo caso em uma sessão limpa ajuda a separar um defeito determinístico de uma falha transitória.

Um caso com requisitos mais rígidos

A etapa seguinte foi executada com um prompt que exigia uma estrutura explícita: comparação entre asyncio.gather e asyncio.TaskGroup, exemplo de código, explicação sobre asyncio.CancelledError, limitações, exatamente três referências externas e uma conclusão com cinco itens.

O agente produziu o artigo e terminou com post_validation: "ok". A sequência exibida pela interface mostra novamente o planejador, o estado do outline, o escritor e o estado final do artigo.

Essa execução não provocou um retry. Isso também é um resultado válido: significa que, nesse caso, o primeiro texto produzido já foi considerado compatível com os requisitos configurados no validador.

É importante não interpretar esse resultado como prova de que o agente sempre acerta de primeira. Ele mostra apenas que uma execução específica satisfez o contrato. Para medir a consistência, seria necessário repetir o mesmo caso várias vezes e registrar quantas execuções terminam com ok na primeira tentativa, quantas precisam de retry e quantas falham.

O valor da captura está justamente na combinação entre o prompt e o estado final. O leitor consegue ver os requisitos enviados, acompanhar as etapas do pipeline e confirmar que a execução terminou com aprovação.

Testes offline colocam um limite honesto nas conclusões

O projeto mantém uma suíte offline para testar o máximo possível sem depender de rede ou de uma chave de API. Existem também testes e benchmarks separados que fazem chamadas reais.

Essa divisão é importante porque uma suíte verde não prova que o sistema completo funciona em qualquer modelo.

Um teste offline pode provar que um validador devolve retry para um determinado fixture. Ele não prova que um modelo hospedado fará essa escolha de forma consistente.

Um servidor falso pode provar que o adaptador envia um payload válido. Ele não prova que um GGUF específico seguirá o template correto para tool calling.

Um mock pode provar que a regra de roteamento funciona. Ele não calibra um limiar de confiança sem um conjunto de dados rotulado.

O próprio projeto registra essa diferença. Um modelo pode inventar o resultado de uma ferramenta, e nenhum teste puramente offline consegue detectar esse comportamento.

Essa é uma boa prática para qualquer sistema de IA: declarar o que o teste prova e também declarar o que ele não prova.

A limitação do eval do ADK

Existe uma diferença importante entre fazer um agente funcionar e conseguir avaliá-lo com a ferramenta oficial de avaliação.

No estado atual deste projeto, o eval do ADK funciona quando o fluxo usa os modelos Gemini. Quando a execução utiliza OpenRouter ou Gemma servido localmente por llama.cpp, os agentes conseguem funcionar dentro dos requisitos definidos no código, mas não entram no mesmo caminho de avaliação do ADK.

Isso cria duas camadas diferentes de confiança.

Na primeira camada, ficam os testes de engenharia. Eles verificam se o agente monta o estado corretamente, se as ferramentas respondem, se o fallback é acionado, se o loop termina e se os contratos de saída são respeitados.

Na segunda camada, fica a avaliação oficial do ADK. Ela é útil para medir o comportamento do agente com os modelos Gemini, mas não cobre automaticamente as outras combinações de provedor e runtime presentes no projeto.

O resultado é uma assimetria que pode passar despercebida. O mesmo pipeline pode ser executado com Gemini, OpenRouter e llama.cpp, mas a evidência disponível não é equivalente entre os três ambientes.

Isso é particularmente relevante para modelos locais. O agente pode produzir o resultado esperado em um teste funcional e ainda apresentar diferenças no formato de tool calling, no uso do contexto, no veredito ok ou retry e na tendência de repetir o loop. Sem uma avaliação comparável, essas diferenças ficam mais difíceis de medir de maneira sistemática.

Neste projeto, portanto, é mais correto dizer que os modelos alternativos foram validados dentro dos contratos e testes disponíveis. Não é correto dizer que eles foram avaliados pelo mesmo mecanismo do ADK usado para Gemini.

MLflow só que não: traces e avaliação

Uma opção interessante para essa lacuna seria instrumentar o pipeline com MLflow.

Essa integração ainda não foi testada e nem sei se isso é possível, então deve ser vista como uma possibilidade de evolução, não como uma capacidade já comprovada do repositório.

O MLflow possui tracing para aplicações GenAI e agentes. A documentação atual descreve integrações automáticas com Google ADK, além de instrumentação manual com @mlflow.trace e spans. Os traces podem registrar entradas, saídas e etapas intermediárias, como chamadas de ferramentas, recuperação de documentos e decisões de roteamento. Consulte a documentação de tracing para agentes e de instrumentação automática.

Uma integração possível seria registrar cada execução com metadados como:

Campo	Exemplo
Provedor	Gemini, OpenRouter ou llama.cpp
Modelo	Nome e versão do modelo usado
Agente	Blogger, RAG, SEO ou Code Review
Iteração	Primeira tentativa ou retry
Estado	Outline, validação ou artigo final
Ferramenta	HTTP, MCP, filesystem ou busca
Resultado	`ok`, `retry`, erro ou timeout
Custo e latência	Quando o provedor disponibilizar esses dados

Com esses traces, seria possível comparar os mesmos casos de teste entre provedores sem depender exclusivamente do eval do ADK.

O mlflow.genai.evaluate() também permite avaliar traces já coletados usando scorers prontos ou métricas customizadas. A documentação do MLflow cita avaliações de relevância, groundedness, aderência a guidelines e comportamento intermediário do agente. Veja avaliação de traces e a referência de mlflow.genai.evaluate.

Para este repositório, os scorers mais interessantes provavelmente não seriam apenas métricas de qualidade textual. Eles poderiam verificar:

Se o agente chamou a ferramenta esperada.
Se o arquivo acessado estava dentro do diretório permitido.
Se o resultado foi validado antes de ser entregue.
Se o agente interrompeu o loop depois de ok.
Se o RAG citou um trecho realmente recuperado.
Se um modelo de fallback preservou o mesmo schema de saída.

Essa abordagem permitiria separar três tipos de avaliação:

Testes determinísticos para regras de aplicação.
Avaliação de traces para o comportamento do agente.
Avaliação específica do modelo para qualidade de texto, tool calling e aderência às instruções.

O MLflow não resolveria automaticamente a diferença entre provedores. Ainda seria necessário definir um dataset comum, normalizar os campos de saída, decidir qual modelo será usado como juiz e separar qualidade do texto de correção do workflow.

Mas ele poderia oferecer a camada de observabilidade e comparação que falta quando o mesmo agente roda em Gemini, OpenRouter e llama.cpp.

Fallback melhora disponibilidade, mas não garante qualidade

O common.py monta uma cadeia com modelo principal, modelo alternativo e, opcionalmente, um servidor local baseado em llama.cpp.

Esse desenho ajuda quando existe um erro temporário, uma limitação de cota ou a necessidade de executar localmente. Mas trocar de modelo pode alterar várias coisas ao mesmo tempo:

O formato das chamadas de ferramentas.
A disposição para devolver exatamente ok ou retry.
A forma de lidar com contexto.
A latência e o custo.
A qualidade da revisão e não apenas a qualidade do primeiro rascunho.

Essa última parte é especialmente importante em um pipeline com loops. Um modelo que critica excessivamente um resultado já aceitável pode consumir outra iteração e mais uma chamada de API.

Nesse caso, o melhor modelo não é necessariamente aquele que escreve o texto mais bonito. É aquele que respeita o contrato de controle com consistência suficiente para o loop terminar.

Por isso, modelos de fallback devem ser avaliados com os contratos reais do sistema. Uma pergunta genérica não é suficiente para validar um modelo que precisa produzir tool calls, obedecer schemas e decidir quando encerrar uma revisão.

O que temos neste projeto

Divide o fluxo por responsabilidade.
Torna os artefatos intermediários explícitos.
Usa validadores como parte do controle de fluxo.
Coloca regras exatas em código.
Limita o acesso a arquivos e ferramentas.
Separa testes de transporte dos testes de modelo.
Mantem uma suíte determinística offline.
Registra limitações e tarefas pendentes.

🚨 Isso não prova que oito agentes são melhores do que um.
Também não apresenta um benchmark independente comparando ADK com outros frameworks. Os números de custo, latência, cota e qualidade dependem do ambiente descrito no projeto e podem mudar com versões futuras.

🚨 Isso não reduz o valor do repositório. Apenas define melhor o que ele representa: um exemplo concreto de como tornar sistemas agentic mais observáveis, testáveis e fáceis de explicar.

Uma lista a considerar para um sistema com ADK

Antes de começar a criar mais um agente, vale responder estas perguntas:

Existe uma responsabilidade nova ou apenas mais um prompt para a mesma responsabilidade?
Qual artefato atravessa a fronteira entre as etapas?
Como o próximo agente recebe esse artefato?
Quais regras precisam ser verificadas por código?
O que o modelo pode acessar e o que deve ficar limitado pela aplicação?
Quais falhas precisam de duas verificações independentes?
O comportamento pode ser testado sem modelo ao vivo ou sem rede?
O modelo de fallback respeita o mesmo schema e o mesmo critério de término?
Quais afirmações são testadas, quais são apenas observadas e quais ainda são desconhecidas?

Os sistemas multiagentes mais maduros não são necessariamente os que têm a hierarquia mais complexa. São os que possuem contratos claros entre as etapas, condições explícitas de término e uma noção honesta do que cada teste realmente comprova.

Multiagentes não são uma resposta universal

Existe muito entusiasmo em torno de arquiteturas multiagentes e de modelos especializados como o JEV. Esse entusiasmo pode ser útil para descobrir novas possibilidades, mas não deve virar uma decisão automática de arquitetura.

Dividir uma aplicação em agentes especializados pode facilitar a organização das responsabilidades. Também pode tornar o sistema mais fácil de explicar, testar e evoluir. Ao mesmo tempo, cada divisão cria uma nova fronteira de comunicação, uma nova dependência e um novo ponto onde o fluxo pode falhar.

Neste projeto, por exemplo, uma execução pode depender de vários componentes diferentes:

O runtime do ADK.
O modelo principal.
O modelo de fallback.
O provider usado para acessar um modelo externo.
O servidor MCP.
A sequência de chamadas de ferramentas.
O estado compartilhado entre os agentes.
Os validadores e suas condições de término.

Adicionar fallback também não garante disponibilidade. O caminho Gemini pode falhar por cota ou indisponibilidade. O OpenRouter pode apresentar erro de rede ou de autenticação. O JEV pode não responder como esperado. O llama.cpp pode estar indisponível, lento ou incompatível com determinado formato de tool calling.

Um fallback aumenta as opções de recuperação, mas também aumenta a superfície que precisa ser observada e testada. Se os modelos não obedecerem ao mesmo contrato de saída, a troca de provider pode apenas transformar um erro de disponibilidade em um erro de comportamento.

Por isso, a pergunta mais importante antes de adotar uma arquitetura multiagente não é “qual framework está em alta?”. É:

A divisão em agentes resolve um problema real deste caso de uso ou apenas adiciona complexidade ao sistema?

Se uma única chamada bem delimitada resolve o problema, uma arquitetura com vários agentes pode ser uma escolha ruim. Se existem responsabilidades claramente diferentes, ferramentas distintas, ciclos de validação ou limites de contexto que justificam a separação, o desenho multiagente pode fazer sentido.

A recomendação mais segura é experimentar e validar no próprio contexto. Comece com uma implementação simples. Meça custo, latência, taxa de erro, qualidade e facilidade de manutenção. Depois compare com uma versão multiagente usando os mesmos casos de teste.

O resultado dessa comparação é mais importante do que a popularidade de uma técnica. Arquitetura deve seguir necessidade real, evidência e comportamento observado.

O próprio agente Blogger como guia para este post

Este texto também foi estruturado usando o próprio gerador de Blogger apresentado no projeto.

A ideia não foi pedir que o agente escrevesse um artigo definitivo e publicar o resultado sem revisão. O gerador foi usado como guia para organizar o tema, testar o fluxo de planejamento, observar os artefatos intermediários e entender como o sistema lida com validação, falhas e novas tentativas.

O processo acabou funcionando como uma demonstração do próprio argumento deste artigo:

O agente ajudou a produzir uma primeira estrutura.
O ADK Web permitiu observar eventos, estado e traces.
O output foi revisado contra o comportamento real do repositório.
As execuções bem sucedidas e as falhas foram documentadas.
Afirmações que não podiam ser comprovadas foram tratadas como limitações ou hipóteses.

Esse ciclo é mais interessante do que a ideia de geração automática sem supervisão. O modelo acelera a organização e a produção de material, mas a qualidade final depende da combinação entre código, testes, observabilidade e revisão técnica.

No fim, o objetivo de um sistema multiagente não deveria ser esconder o processo atrás de uma resposta convincente. Deveria ser tornar o processo claro o suficiente para que outra pessoa consiga entender o que aconteceu, reproduzir o experimento e decidir o que ainda precisa ser melhorado.

É esse o principal aprendizado do projeto: agentes são mais úteis quando fazem parte de um sistema com contratos, ferramentas determinísticas, traces e limites explícitos.

Referências

O projeto funcional está no github em vongrossi/adk-multiagent.

Alguns conceitos usados neste artigo,
ADK Agents, ADK Workflows, o repositório Python do ADK e a especificação do MCP.

Para a estratégia de avaliação proposta, consulte a documentação de MLflow Tracing, instrumentação automática e avaliação de traces.

Fazendo um LLM do Zero — Sessão 08: O Fim do Começo (Por que agora tudo faz sentido?) 🚀🧠

Von Grossi — Sun, 15 Feb 2026 01:42:01 +0000

Fazendo um LLM do Zero — Sessão 08: O Fim do Começo (Por que agora tudo faz sentido?) 🚀🧠
Chegando ao fim dessa jornada. Mas, paradoxalmente, este é apenas o começo da sua verdadeira jornada com Inteligência Artificial.

A Sessão 08 é diferente. Ela não está no sumário do livro de Sebastian Raschka. Ela não vai te ensinar uma nova função do PyTorch nem introduzir uma arquitetura revolucionária. Esta sessão é o que eu chamo de “O Momento Matrix”.

Sabe aquela cena icônica em que o Neo finalmente para de ver as paredes, os agentes e o cenário, e começa a enxergar apenas o código verde escorrendo em cascata? É exatamente assim que me sinto agora ao olhar para qualquer aplicação de IA moderna.

Durante meses, nós construímos cada engrenagem desse sistema. Do momento em que quebramos uma palavra em tokens até o instante em que calculamos o gradiente de erro de uma resposta complexa. Ao fazer isso, algo mudou irreversivelmente. Eu não vejo mais a “mágica”. A caixa preta foi aberta.

O que eu vejo agora são probabilidades, vetores densos e multiplicações de matrizes.

E acredite: perder a ilusão da mágica foi a melhor coisa que poderia ter acontecido para a minha carreira de engenheiro de software.

🔍 O Fim da “Caixa Preta”: Por que suas aplicações falham?

Antes dessa jornada, quando o ChatGPT inventava um fato ou quando meu sistema de busca falhava, minha reação era de frustração e confusão. “Por que ele fez isso? Não faz sentido!”. Agora, a confusão deu lugar ao diagnóstico preciso. Entender os fundamentos me deu a capacidade de olhar para o erro e identificar a causa raiz.

1. A Anatomia da Alucinação(Vibe Coding e Prompt Engineering)

Aprendemos na Sessão 05 a verdade dura: um LLM é, em sua essência, uma máquina estatística treinada para prever a próxima palavra. Ele não tem compromisso com a verdade factual; ele tem compromisso com a verossimilhança estatística.

Quando você está fazendo um “Vibe Coding” e o modelo sugere uma importação de biblioteca que não existe, você não fica mais bravo. Você entende:

“Ah, estatisticamente, essa importação fazia todo sentido nesse contexto de código, por isso ele ‘alucinou’ esse nome”. O modelo não mentiu; ele apenas seguiu a probabilidade mais alta. Saber disso muda como você escreve seus prompts. Você para de pedir “seja criativo” e começa a impor restrições de contexto, porque você sabe que sem restrições, a estatística corre solta.

2. O Poder Oculto dos Embeddings (Custo, Performance e RAG)

Na Sessão 02, desmistificamos os Embeddings. Vimos que para o computador, “significado” nada mais é do que distância geométrica em um espaço vetorial.

Isso mudou a forma como projeto sistemas de RAG (Retrieval-Augmented Generation). Hoje, eu sei que a qualidade da resposta do meu agente não depende apenas do LLM caro que estou usando na ponta final (como o GPT-4), mas depende criticamente da qualidade do meu Embedding na busca. Se meus vetores não capturarem a nuance semântica, o LLM nunca receberá a informação correta. Escolher o modelo de embedding errado não é apenas um detalhe técnico; é uma decisão que impacta diretamente o preço e a latência da sua aplicação. Um vetor mal construído torna sua busca “burra” e sua infraestrutura cara.

3. Agentes Especializados e Instruction Tuning

Na Sessão 07, sofremos para alinhar o modelo. Vimos como é difícil fazer a máquina parar de apenas “completar texto” e começar a “obedecer ordens”.

Essa experiência é valiosa quando estamos criando Agentes Autônomos. Se o seu agente sai dos trilhos e começa a agir de forma imprevisível, a culpa provavelmente não é do modelo ser “burro”, mas da falta de exemplos robustos de Instruction Tuning ou Few-Shot Prompting. Você aprendeu na prática que o modelo precisa de exemplos negativos (o que não fazer) tanto quanto de exemplos positivos. A engenharia de prompt deixou de ser “tentativa e erro” e virou*“ajuste de pesos via contexto”*.

📊 A Verdade nos Números: O que os Gráficos nos Contam

Nossa jornada não foi feita apenas de conceitos abstratos. Nossos notebooks geraram dados reais, e esses dados contam a história do aprendizado da máquina. Vale a pena revisitar três momentos visuais que definiram nossa evolução:

1. O Momento “Eureca” da Classificação (Sessão 06)

Lembra quando transformamos o GPT em um classificador de SPAM? Ver o modelo pegar uma frase como “Ganhe dinheiro rápido e fácil!!!” e cravar a categoria SPAM (99%) foi a prova definitiva.

Não foi mágica. Nós vimos os pesos da Classification Head se ajustarem para reconhecer esse padrão.

2. A Queda da Loss (Sessão 07)

Não há gráfico mais bonito para um cientista de dados ou engenheiro de ML do que uma curva de Loss descendo.

Essa linha descendente não é apenas um gráfico; é a representação visual da “inteligência” emergindo. Cada degrau que a linha desce significa que o modelo entendeu um pouco mais sobre a estrutura da linguagem humana. O momento em que a linha se estabiliza é o momento em que a máquina encontrou o padrão ótimo. É poesia matemática.

Join Medium for free to get updates from this writer.

3. A Matriz de Confusão: A Hora da Verdade

E, claro, a nossa “prova real”. Nenhuma IA é perfeita, e a Matriz de Confusão nos ensinou a humildade.

Ela nos mostrou exatamente onde o modelo tropeça. Ele confunde ironia com seriedade? Ele deixa passar falsos positivos? Aprender a ler esse gráfico é o que separa quem usa IA de quem avalia e melhora IA.

🔮 O Futuro: O que podemos fazer agora?

Nesta sessão extra, compilamos reflexões sobre os próximos passos. O campo de LLMs está explodindo e mudando a cada semana, mas os fundamentos que aprendemos aqui — Attention, Backpropagation, Embeddings, Tokenization — são a base imutável de tudo isso.

Com essa base sólida, agora podemos nos aventurar em tópicos avançados sem medo:

Quantização: Como fazer esse modelo gigante caber na memória de um celular, reduzindo a precisão dos números sem perder a inteligência?

RAG Avançado: Como conectar esse “cérebro” a um banco de dados proprietário da empresa, garantindo que ele só responda com fatos verificados?

Agentes Multimodais: E se, além de tokens de texto, adicionarmos tokens de imagem? A arquitetura Transformer permite isso!

A base que construímos nos permite navegar por essas novidades sem nos perdermos em um hype.

❤️ Gratidão: O Alicerce do Open Source

Nenhum conhecimento é construído no vácuo. Se conseguimos criar um LLM do zero usando apenas um navegador e o Google Colab, foi porque gigantes nos permitiram subir em seus ombros.

Este projeto é, acima de tudo, um reconhecimento ao ecossistema Open Source e à comunidade científica que compartilha conhecimento abertamente.

Aos mantenedores do PyTorch, que tornaram a matemática complexa acessível através de código elegante.

Ao time do Google Colab, que democratizou o acesso às GPUs, permitindo que qualquer pessoa com internet treine uma rede neural.

E, principalmente, ao autor Sebastian Raschka, cujo livro foi o farol que guiou essa jornada, transformando teoria densa em prática acessível.

Escrevi uma carta aberta de agradecimento ao autor, detalhando como sua didática impactou meu aprendizado e o de todos que acompanharam essa série. Se você também aprendeu algo, recomendo a leitura como forma de celebrar o compartilhamento de conhecimento:

📄Leia a Carta ao Autor aqui

🏁 O Código

O repositório Fazendo um LLM do Zero não é apenas meu; é nosso.

Todos os notebooks, todos os infográficos traduzidos, todos os experimentos e códigos comentados estão disponíveis e abertos para sempre.

🔗 GitHub Oficial: vongrossi/fazendo-um-llm-do-zero

Sinta-se livre para experimentar e extender, clone o repositório

Quebre o modelo. Tente treiná-lo com outras fontes de dados. Erre. Conserte. Experimente durante a jornada eu tentei varias abordagens

Acho que melhor forma de prever o futuro da Inteligência Artificial é construí-lo você mesmo.

End of transmission. 📡👋

Fazendo um LLM do Zero — Sessão 07: De Gerador de Texto a Assistente (Instruction Tuning) 💬🤝

Von Grossi — Sun, 15 Feb 2026 01:41:38 +0000

Fazendo um LLM do Zero — Sessão 07: De Gerador de Texto a Assistente (Instruction Tuning) 💬🤝
Chegamos ao último grande marco da nossa jornada.

Até aqui, construímos um modelo que sabe tudo sobre a estrutura da língua (Sessão 05) e que até aprendeu uma profissão específica (Sessão 06).

Mas ainda faltava um “tempero” essencial para que ele se parecesse com o ChatGPT que usamos no dia a dia.

Se você pedisse ao nosso modelo da Sessão 05: “Escreva uma receita de bolo”, ele poderia simplesmente responder: “…e uma lista de ingredientes para o jantar”. Ele não entendeu que você deu uma ordem; ele achou que você estava apenas começando um texto que ele deveria completar.

Na Sessão 07, resolvemos isso com o Instruction Tuning. Como Sebastian Raschka explora no Capítulo 7 de seu livro, este é o processo de

Alinhamento: ensinar o modelo a entender a intenção humana e a agir como um assistente útil.

1. O Modelo Base vs. O Assistente

A diferença entre um modelo treinado em texto bruto e um modelo alinhado é a diferença entre um estudante que leu todos os livros da biblioteca e um profissional que sabe atender um cliente.

O modelo base é um “completador de frases”. O modelo alinhado é um seguidor de instruções.

2. A Gramática das Ordens: Formato Instrução-Resposta

Para que o modelo aprenda a nos obedecer, não podemos simplesmente jogar texto aleatório nele. Precisamos de exemplos estruturados. Como

Sebastian Raschka detalha, usamos um formato específico que separa a Instrução, o Contexto (Input) e a Resposta Esperada.

É como dar um roteiro para um ator: “Sempre que alguém te pedir X, você deve responder Y”. Com exemplos suficientes, o modelo entende o padrão de interação.

3. O Truque do Mestre: Mascaramento da Loss

Aqui entra um detalhe técnico brilhante que vimos nesta sessão. Durante o treino, nós não queremos que o modelo aprenda a “prever a pergunta”. A pergunta (instrução) já está lá! Nós queremos que ele foque toda a sua energia em aprender a Resposta.

Join Medium for free to get updates from this writer.

Para isso, usamos o Mascaramento da Loss.

Nós ignoramos os erros que o modelo comete enquanto lê a pergunta e só ajustamos os neurônios dele quando ele começa a escrever a resposta. Isso força o modelo a ser um “resolvedor de problemas”, não apenas um papagaio.

4. O Pipeline de Supervised Fine-Tuning (SFT)

O processo de transformar o modelo base em assistente é chamado de SFT. É uma linha de montagem de alta precisão: pegamos os pesos pré-treinados, passamos pelo dataset de instruções e avaliamos a qualidade da conversa.

5. Como Medir a Utilidade?

Como saber se um assistente é bom? Diferente da classificação (Sessão 06), aqui não existe “certo ou errado” absoluto. Uma receita de bolo pode ser escrita de mil formas diferentes.

Por isso, a avaliação deixa de ser apenas matemática e passa a ser qualitativa. O modelo é coerente? Ele foi educado? Ele seguiu todas as restrições da instrução?

🏁 O Fim da Jornada (E o Começo da Próxima)

Com a conclusão da Sessão 07, fechamos o ciclo completo de construção de um LLM:

1. Preparamos o terreno (Sessão 00 e 01).

2. Transformamos texto em números (Sessão 02).

3. Criamos o mecanismo de atenção (Sessão 03).

4. Montamos o corpo do GPT (Sessão 04).

5. Ensinamos o modelo a falar (Sessão 05).

6. Damos a ele uma especialidade (Sessão 06).

7. E, finalmente, o ensinamos a conversar e seguir instruções (Sessão 07).

O que antes era uma caixa preta mágica agora é um sistema que você construiu, peça por peça, do zero. A inteligência artificial não é mágica; é engenharia, é matemática e, acima de tudo, é a curiosidade de entender como os fios se conectam.

🚀 Explore o Capítulo Final

No notebook da Sessão 07, implementamos o treinamento de instruções e vimos o nosso GPTMini deixar de ser um gerador aleatório para se tornar um mini-assistente conversacional.

👇 Confira o resultado final:

📓 Notebook no Google Colab:Rodar Sessão 07

📂 Repositório GitHub:vongrossi/fazendo-um-llm-do-zero

Obrigado por acompanhar essa serie de posts. Agora que você sabe como um LLM é feito, o que você vai construir com esse conhecimento? 🛠️🧠

Fazendo um LLM do Zero #03: Atenção é Tudo o que Você Precisa? 🎯👀

Von Grossi — Sun, 15 Feb 2026 00:00:00 +0000

Fazendo um LLM do Zero #03: Atenção é Tudo o que Você Precisa? 🎯👀 Você já parou para pensar em como é difícil entender uma frase isolada?

Imagine que eu chego para você e digo:

“Eu estou indo para o banco.”

Você pensaria em dinheiro 💰 ou em um parque 🌳?

Sem o resto da conversa, é impossível saber. A palavra “banco” é ambígua. O que define o significado dela não são as letras B-A-N-C-O, mas sim as palavras que estão ao redor dela.

Se a frase fosse “Sentei no banco da praça”, a palavra “banco” absorve o significado de “praça”.

Se fosse “Saquei dinheiro no banco”, ela absorve o significado de “dinheiro”.

Esse “superpoder” de misturar significados baseados no contexto é algo que nós fazemos naturalmente. Mas, para computadores, isso sempre foi um pesadelo. Até 2017.

Bem-vindo ao nossa 3a jornada, onde vamos desvendar o Self-Attention (Autoatenção), o mecanismo que transformou papagaios digitais em modelos capazes de manter uma conversa coerente.

1. O Problema da Tradução “Robótica”

Antigamente, modelos de linguagem liam texto como um cavalo com antolhos: focados apenas na palavra atual ou na anterior.

O resultado? Traduções literais e frases sem nexo. Veja este exemplo clássico de tradução do Alemão para o Inglês:

Contexto importa na tradução

Para traduzir corretamente, a palavra final da frase depende de uma palavra que apareceu lá no começo. Se o modelo não tiver “memória” ou “visão periférica”, ele erra.

2. A Intuição: Todo Mundo Olhando para Todo Mundo

A grande sacada do paper “Attention Is All You Need” foi dizer: e se cada palavra pudesse “olhar” para todas as outras palavras da frase e decidir quais são importantes para ela?

Na frase “O gato que estava no telhado miou”, quando processamos a palavra “miou”, o modelo deve prestar muita atenção em “gato” (quem miou?) e pouca atenção em “telhado” (onde estava).

Isso cria uma teia de conexões semânticas. O modelo aprende quem fez o quê, onde e como, apenas ajustando o foco da atenção.

3. O Coquetel de Informações

Matematicamente, o que acontece é que a palavra “banco” deixa de ser um vetor estático. Ela se torna uma mistura ponderada de todas as palavras da frase.

Se a palavra “dinheiro” está na frase, ela “doa” um pouco do seu significado para “banco”.

O resultado final (o vetor de contexto) é uma representação muito mais rica. É a diferença entre um dicionário (significado estático) e uma conversa (significado contextual).

4. O Mecanismo: Query, Key e Value (A Busca no Spotify)

Aqui a coisa fica técnica (e genial). Como o modelo decide quanto foco dar para cada palavra?

Ele usa um sistema de busca parecido com o do YouTube ou Spotify.

Join Medium for free to get updates from this writer.

Para cada palavra, criamos três vetores:

1. Query (Q — A Pergunta): O que eu estou procurando?

2. Key (K — A Etiqueta): O que eu tenho a oferecer?

3. Value (V — O Conteúdo): Se você gostar de mim, leve esta informação.

A “Atenção” nada mais é do que o casamento (produto escalar) entre a Pergunta (Query) de uma palavra e a Etiqueta (Key) de outra. Se elas combinam, a afinidade é alta, e o modelo absorve muito do Conteúdo (Value).

Mas esses vetores Q, K e V não são fixos! Eles são aprendidos. O modelo possui matrizes de pesos treináveis que ele ajusta durante o treinamento para aprender como prestar atenção melhor.

5. Regras do Jogo: Sem Spoilers e Sem Decorar

Para criar um GPT (que gera texto), temos uma regra de ouro: você não pode ler o futuro.

Se o modelo pudesse ver a próxima palavra durante o treino, ele apenas copiaria a resposta em vez de aprender a prever.

Para impedir essa “cola”, aplicamos uma Máscara Causal. Ela zera a atenção para qualquer palavra que venha depois da atual. É como colocar uma cortina no futuro.

Além disso, para evitar que o modelo “decore” frases específicas, usamos o Dropout. Desligamos aleatoriamente algumas conexões de atenção durante o treino. Isso força o modelo a ser robusto e aprender caminhos alternativos para entender o contexto.

6. Multi-Head Attention: Vários Pontos de Vista

Linguagem é complexa. Uma frase pode ter uma estrutura gramatical difícil E um tom emocional sutil. É difícil focar nas duas coisas ao mesmo tempo.

A solução? Multi-Head Attention (Atenção com Múltiplas Cabeças).

Em vez de fazer esse processo uma vez, fazemos 4, 8 ou 12 vezes em paralelo.

Head 1 (Cabeça 1) foca na gramática (quem é o sujeito?).

Head 2 (Cabeça 2) foca na relação temporal (aconteceu antes ou depois?).

Head 3 (Cabeça 3) foca no vocabulário específico.

No final, juntamos tudo e temos uma compreensão super-humana do texto.

7. Onde isso tudo se encaixa?

A Atenção é o coração, mas precisa de um corpo. Ela é o primeiro grande bloco dentro da arquitetura do Transformer que estamos construindo.

Depois de entender o contexto com a Atenção, a informação flui para as redes neurais (Feed Forward) que processam esse significado.

🚀 Mão na Massa

A teoria é linda, mas implementar o Self-Attention do zero, multiplicando matrizes na mão, é onde você realmente entende a mágica. E é exatamente isso que fazemos no notebook deste capítulo. Nada de import attention. Nós criamos a classe MultiHeadAttention linha por linha.

Quer ver como transformar essa teoria em código Python puro?

👇 Acesse agora:

📓 Notebook no Google Colab:Rodar no colab

📂 Código no GitHub: Ver repositório:vongrossi/fazendo-um-llm-do-zero

No proximo post, vamos pegar esses blocos de atenção e finalmente construir o corpo do GPT. Prepare-se, porque o monstro vai ganhar vida.

🧟‍♂️🤖

Fazendo um LLM do Zero #01: A Mágica é Apenas Estatística (Bem Feita) 🎩📊

Von Grossi — Sun, 15 Feb 2026 00:00:00 +0000

Fazendo um LLM do Zero #01: A Mágica é Apenas Estatística (Bem Feita) 🎩📊

Você se lembra da primeira vez que usou o ChatGPT?

Para mim, houve um momento de estranhamento. Eu digitava uma pergunta complexa, e a resposta surgia na tela, palavra por palavra, como se houvesse um humano do outro lado digitando em tempo real. Parecia haver raciocínio, intenção, talvez até… consciência?

É fácil se deixar levar pela ilusão da “Inteligência”.

Mas, como engenheiros (ou aspirantes a), nosso trabalho não é admirar a mágica. É descobrir onde está o alçapão, os espelhos e os fios invisíveis.

Nessa parte da nossa série Fazendo um LLM do Zero, nós puxamos a cortina. E a verdade é, ao mesmo tempo, decepcionante para os sonhadores e fascinante para os construtores:

O modelo não sabe o que está dizendo. Ele está apenas chutando a próxima palavra.

Bem-vindo ao mundo da Previsão do Próximo Token.

🔮 A Bola de Cristal Probabilística

Para entender um Large Language Model (LLM), você precisa esquecer a ideia de “cérebro digital” por um minuto e olhar para o seu celular.

Abra o WhatsApp. Digite “Bom”.

O seu teclado provavelmente vai sugerir “dia”, “trabalho” ou “fim”.

O seu teclado entende o conceito de saudação matinal? Não.

Ele sabe que você está feliz ou cansado? Não.

Ele apenas calculou uma probabilidade condicional: “Dado que o usuário digitou ‘Bom’, existe 80% de chance da próxima palavra ser ‘dia’”.

Um LLM, no fundo, é um autocompletar que tomou esteroides. 💊

A diferença é a escala. Enquanto o teclado do seu celular olha para as últimas 2 ou 3 palavras, um modelo como o GPT-4 olha para milhares de palavras de contexto (livros, artigos, código, conversas) para calcular qual é o próximo pedacinho de texto (token) que faz mais sentido estatístico.

O fluxo simples de Texto -> Modelo -> Probabilidade

Quando o modelo escreve um poema ou um código em Python, ele não planejou o resultado final. Ele está navegando no escuro, acendendo uma luz (token) de cada vez, baseando-se apenas no caminho que já percorreu.

🏗️ A Revolução Transformer: Paramos de Ler como Humanos

Se a ideia é apenas “prever a próxima palavra”, por que não tínhamos IAs assim nos anos 90?

O problema era a memória.

Antigamente, as Redes Neurais Recorrentes (RNNs) liam texto como nós, humanos cansados: uma palavra de cada vez, da esquerda para a direita.

“O”… (ok, guardei)
“gato”… (ok, é um animal)
“subiu”… (ação)
…
“telhado”.

Quando a frase era longa, a rede já tinha “esquecido” o começo. Ela perdia o contexto.

Join Medium for free to get updates from this writer.

A grande virada de chave — e o motivo pelo qual estamos vivendo esse hype hoje — foi a introdução da arquitetura Transformer (apresentada pelo

Google no paper “Attention Is All You Need” em 2017).

O Transformer não lê como a gente. Ele olha para a frase inteira de uma vez só. Ele processa tudo em paralelo. É como se, em vez de ler um livro página por página, ele tirasse uma foto de todas as páginas ao mesmo tempo e entendesse as conexões entre o capítulo 1 e o capítulo 10 instantaneamente.

Isso permitiu treinar modelos com quantidades absurdas de dados. E, com dados suficientes, a estatística começou a parecer inteligência.

🧩 O GPT é um “Decoder-Only”

Existem muitos tipos de Transformers, mas nós vamos focar na arquitetura GPT (Generative Pre-trained Transformer).

O GPT é o que chamamos de modelo Decoder-Only.

Imagine um tradutor.

1. Ele ouve a frase em inglês (Encoder).

2. Ele gera a frase em português (Decoder).

O GPT ignorou a primeira parte. Ele é especialista apenas na segunda: gerar. Ele é treinado para olhar para o passado e alucinar o futuro, token por token. É por isso que ele é tão bom em criar histórias e conversar, mas às vezes falha em tarefas que exigem “ver o todo” antes de responder.

🛠️ Mão na Massa: O Que Fizemos no Código?

Chega de teoria. No notebook desta sessão, não usamos bibliotecas prontas de “caixa preta” como langchain ou openai. Nós descemos para o nível do PyTorch.

Neste Passo 01, você vai encontrar:

1. A intuição visual: Gráficos que explicam como o texto entra e sai do modelo.

2. O conceito de Contexto: Como o tamanho da “janela” que o modelo enxerga define o quão “inteligente” ele parece.

3. A estrutura do projeto: Como organizar pastas e arquivos para não se perder quando o código crescer.

🚀 Por que isso importa?

Quando você entende que o LLM é uma máquina de probabilidade e não um ser consciente, você se torna um usuário (e desenvolvedor) muito melhor.

Você para de tentar “convencer” o chat e começa a “engenheirar” o prompt. Você entende por que ele alucina (afinal, ele só quer completar o padrão, mesmo que precise inventar um fato).

A mágica desaparece, mas dá lugar a algo muito mais poderoso: o controle.

Pronto para ver como transformar texto em números e começar a calcular essas probabilidades? Esse é o tema da próxima sessão.

👇 Acesse o material completo e execute o código agora:

📓 Notebook no Google Colab:Clique aqui para rodar

📂 Repositório no GitHub:vongrossi/fazendo-um-llm-do-zero

Vamos adiante, onde vamos aprender a matemática necessaria para o nosso modelo. Até lá! 👋

Fazendo um LLM do Zero — Sessão 04: A Arquitetura da Mente (Construindo o Corpo do GPT) 🏗️🤖

Von Grossi — Sun, 15 Feb 2026 00:00:00 +0000

Fazendo um LLM do Zero — Sessão 04: A Arquitetura da Mente (Construindo o Corpo do GPT) 🏗️🤖 Até agora, nossa jornada foi sobre coletar os materiais básicos.

Aprendemos a transformar palavras em números.

Entendemos como a Atenção permite que esses números se conectem.

Mas ter tijolos e cimento não é o mesmo que ter uma casa. Você precisa de uma planta, de engenharia e de estrutura.

Na Sessão 04, deixamos de olhar para as peças isoladas e começamos a construir o edifício. É aqui que o GPT deixa de ser uma ideia matemática e se torna um modelo funcional. Como Sebastian Raschka detalha no Capítulo 4 de seu livro Build a Large Language Model (From Scratch), o segredo da inteligência desses modelos não está em uma única peça mágica, mas na forma como empilhamos blocos simples de forma repetitiva e organizada.

1. O Bloco Fundamental: O Módulo Transformer

Um GPT não é uma massa única de código. Ele é modular. Imagine que estamos construindo um arranha-céu onde cada andar é idêntico. Se você souber construir um andar perfeitamente, você pode construir cem.

No mundo dos LLMs, esse andar é o Bloco Transformer.

Cada um bloco desses contém os órgãos vitais do modelo: a Atenção (para olhar o contexto) e a Rede Feedforward (para processar o que viu).

2. A Esteira de Produção (O Fluxo de Dados)

Quando um token entra no modelo, ele não é processado de qualquer jeito. Existe uma ordem rigorosa. Como Sebastian Raschka descreve, a informação passa por uma espécie de esteira de produção dentro de cada bloco.

A informação entra, é refinada pela atenção, estabilizada por normalizações, processada pela rede neural e entregue para o próximo bloco. Esse fluxo garante que o modelo não se perca no meio do caminho.

3. A Refinaria de Conhecimento (Feedforward Network)

Se a Atenção é o “olhar” do modelo, a rede Feedforward é o pensar.

Enquanto a Atenção decide quais palavras são importantes entre si, a rede Feedforward processa cada palavra individualmente para extrair significados mais profundos.

É como se a Atenção trouxesse as matérias-primas e a Feedforward fosse a refinaria que transforma aquilo em conhecimento útil.

Join Medium for free to get updates from this writer.

4. Redes de Segurança: Residuais e Normalização

Aqui entra um problema real de engenharia: quando empilhamos muitos blocos (como os 12 blocos do GPT-2 ou os 96 do GPT-3), a matemática pode começar a quebrar. Os números podem ficar grandes demais ou pequenos demais, e o modelo para de aprender.

Para resolver isso, usamos dois truques essenciais que Sebastian Raschka explora em seu livro:

1. Conexões Residuais: Atalhos que permitem que a informação original pule camadas, garantindo que nada importante seja esquecido.

2. Layer Normalization: Uma técnica que mantém os números em uma escala saudável, como um regulador de voltagem que impede um curto-circuito.

5. O Pipeline Completo: Nasce um GPT

Juntando tudo — os embeddings que vimos na Sessão 02, a Atenção da Sessão 03 e os blocos que montamos agora — temos finalmente o pipeline completo de um modelo GPT.

O modelo recebe tokens, adiciona a noção de posição, passa por vários blocos de processamento e, no final, entrega uma lista de probabilidades:

Qual é a próxima palavra mais provável?

🚀 Do Papel para o Código

Nesta Sessão 04, nosso trabalho no notebook foi de Arquiteto de Sistemas. Nós implementamos:

A classe TransformerBlock unindo Atenção e Feedforward.

A lógica de LayerNorm e conexões residuais.

O modelo GPTMini, que é o nosso cérebro completo pronto para ser treinado.

É um momento marcante: pela primeira vez, temos um modelo que, embora ainda não saiba falar (ele ainda não foi treinado!), já tem toda a estrutura física para aprender qualquer linguagem do mundo.

Quer ver como essas peças se encaixam no PyTorch?

👇 Acesse o laboratório prático:

📓 Notebook no Google Colab:Rodar Sessão 04

📂 Repositório GitHub:vongrossi/fazendo-um-llm-do-zero

Agora o corpo está pronto. Na próxima sessão, vamos dar um sopro de vida: O Pré-treinamento. ⚡📖

Fazendo um LLM do Zero — Sessão 05: Ensinando o Modelo a Falar (A Escola da Probabilidade) 🎓🗣️

Von Grossi — Sun, 15 Feb 2026 00:00:00 +0000

Fazendo um LLM do Zero — Sessão 05: Ensinando o Modelo a Falar (A Escola da Probabilidade) 🎓🗣️
Imagine que você acabou de construir um robô perfeito. Ele tem corpo, cérebro eletrônico e cordas vocais sintéticas. Mas quando você o liga, ele diz: “Asdfjkl çlxzkcvb”.

Frustrante? Não, esperado.

Na Sessão 04, nós construímos o corpo do GPT. Ele tem todas as conexões neurais necessárias, mas não tem conhecimento. Ele é como um recém-nascido: tem potencial infinito, mas ainda não viu o mundo.

Na Sessão 05, entramos na fase mais mágica e demorada de todas: o Pré-Treinamento. É hora de mandar nosso modelo para a escola. E, como Sebastian Raschka explica no Capítulo 5 de seu livro, essa escola não usa gramática ou dicionários. Ela usa estatística pura.

1. O Loop Infinito: Tentar, Errar, Ajustar

Como se ensina uma máquina que não pensa?

Simples: você a força a adivinhar milhões de vezes e corrige cada erro.

O ciclo de vida de um LLM no treinamento é uma rotina repetitiva e exaustiva, parecida com um estudante fazendo simulados sem parar:

1. O modelo recebe: “Era uma vez um…”

2. Ele chuta: “..microondas.” ❌

3. Nós dizemos: “Errado! Era ‘dragão’.”

4. O algoritmo (Backpropagation) ajusta os neurônios do modelo para que, da próxima vez, a probabilidade de “dragão” seja um pouquinho maior e a de “microondas” seja menor.

Multiplique isso por bilhões de frases e o modelo deixa de chutar “microondas” em contos de fadas.

2. A Régua do Erro: Cross Entropy

Mas como medimos o “tamanho” do erro?

Se o modelo chutar “cachorro” em vez de “gato”, o erro é pequeno (são animais parecidos). Se ele chutar “avião”, o erro é enorme.

Para medir essa distância matemática, usamos a Cross Entropy (Entropia Cruzada).

Ela é a professora rigorosa que dá uma nota para cada tentativa do modelo. O objetivo do treino é simples: fazer essa nota de erro (Loss) cair até chegar perto de zero.

3. O Ritmo da Escola: Batches e Epochs

Join Medium for free to get updates from this writer.

Não dá para o modelo ler a internet inteira de uma vez. Ele engasgaria.

Por isso, dividimos o estudo em pequenos pedaços chamados Batches (lotes). E quando ele termina de ver todos os dados uma vez, dizemos que completou uma Epoch (época).

É um processo industrial. Entra texto, sai erro, ajusta pesos. Repete. Repete. Repete. Até que a mágica da inteligência comece a emergir dos números.

4. O Dilema da Criatividade: Como o Modelo Escolhe?

Depois de treinado, o modelo não dá uma resposta. Ele dá probabilidades para todas as palavras do mundo.

Quem escolhe a palavra final? Nós, através da Estratégia de Decodificação (Decoding Strategy).

Isso define a personalidade do modelo:

Greedy (Ganancioso): Sempre escolhe a palavra mais provável. O modelo fica chato, repetitivo e robótico. 🤖

Temperature / Top-k: Nós adicionamos um pouco de caos controlado. O modelo arrisca palavras menos óbvias e se torna criativo. 🎨

5. Salvando o Cérebro: Checkpoints

Treinar um LLM é caro e demorado. Se a luz acabar no meio do processo, você perde dias de trabalho.

Por isso, aprendemos a importância vital dos Checkpoints: salvar uma “cópia de segurança” do cérebro do modelo a cada etapa importante.

🚀 Mão na Massa

Na Sessão 05, o nosso notebook deixa de ser estático. Nós implementamos o loop de treinamento real. Vemos a barra de progresso avançar e a curva de erro cair (o gráfico mais satisfatório para um cientista de dados!).

Nós pegamos o nosso GPTMini, alimentamos ele com texto e vimos ele aprender a formar suas primeiras frases coerentes.

Quer ver o momento exato em que a máquina aprende a escrever?

👇 Acesse o laboratório:

📓 Notebook no Google Colab:Treinar Modelo na Sessão 05

📂 Repositório GitHub:vongrossi/fazendo-um-llm-do-zero

Agora nosso modelo sabe falar. Mas ele sabe o que fazer? Na próxima sessão, vamos ensinar uma profissão para ele com o Fine-Tuning. 🎯👨‍⚕️

Fazendo um LLM do Zero #02: Como Transformar Palavras em Números (Sem Perder a Alma) 🔢✨

Von Grossi — Sun, 15 Feb 2026 00:00:00 +0000

Fazendo um LLM do Zero #02: Como Transformar Palavras em Números (Sem Perder a Alma) 🔢✨

Se você abrir o cérebro de um computador, não vai encontrar letras, palavras ou poesias. Você vai encontrar eletricidade. Zeros e uns.

Isso cria um problema fundamental para quem quer criar Inteligência Artificial: como ensinar uma máquina a ler, se a linguagem nativa dela é matemática pura?

A abordagem ingênua seria criar uma tabela gigante: “Abacate” = 1, “Bola” = 2, “Casa” = 3.

Funciona? Sim. O computador consegue ler.

Mas ele perde o significado. Para ele, “Abacate” e “Bola” são apenas números vizinhos, sem nenhuma relação real.

Nesta sessão, resolvemos esse problema. Descobrimos a alquimia que transforma texto em vetores ricos de significado.

1. O Abismo entre Texto e Máquina

Tudo o que é “dado bruto” no mundo real (texto, áudio, vídeo) precisa ser convertido para uma representação numérica densa antes de entrar em uma rede neural.

Não queremos apenas números soltos. Queremos Embeddings.

Um Embedding não é apenas um número. É uma lista de números (um vetor) que funciona como uma coordenada de GPS.

2. O GPS das Palavras (Espaço Vetorial)

Imagine um mapa gigante.

Nesse mapa, a palavra “Rei” mora em uma coordenada. A palavra “Rainha” mora bem pertinho dela.

Já a palavra “Maçã” mora do outro lado do mapa, longe da realeza, mas vizinha de “Banana”.

Isso é o Espaço Vetorial.

Quando treinamos um LLM, ele aprende a organizar esse mapa sozinho. Ele descobre que “cachorro” e “gato” compartilham muitas características, então ele os coloca próximos geometricamente. É assim que a matemática captura a semântica.

3. Quebrando o Texto: Tokenização

Mas espere… o modelo lê palavras inteiras?

Na verdade, não.

Se o modelo tivesse que decorar todas as palavras do dicionário (mais gírias, nomes, erros de digitação), o vocabulário seria infinito.

Para resolver isso, usamos a Tokenização. Nós quebramos o texto em pedacinhos chamados Tokens.

1. Lemos o texto.

2. Identificamos os pedaços únicos.

3. Criamos um vocabulário numérico.

4. O Tradutor Universal (Encode e Decode)

Join Medium for free to get updates from this writer.

Uma vez que temos o vocabulário, criamos uma ponte de duas vias.

O Encode transforma a frase “Olá Mundo” em [245, 981].

O Decode pega [245, 981] e devolve “Olá Mundo”.

É essa interface que permite que nós (humanos) e o modelo (máquina) conversemos.

5. O Lego das Palavras (BPE — Byte Pair Encoding)

E se aparecer uma palavra que o modelo nunca viu? Tipo “Supercalifragilisticexpialidocious”?

Se usássemos palavras inteiras, o modelo travaria (o temido erro “Out of Vocabulary”).

A solução moderna é genial: Subwords (Sub-palavras).

Se o modelo não conhece a palavra inteira, ele a quebra em pedaços que ele conhece.

“Infelizmente” vira: In + feliz + mente.

Com essa técnica (chamada BPE), o modelo consegue ler e escrever qualquer palavra em qualquer língua, usando apenas um conjunto limitado de peças de Lego.

6. Ensinando com Flashcards (Janela Deslizante)

Como preparamos esses dados para o treino?

Um LLM aprende a prever o futuro olhando para o passado.

Nós pegamos um texto e criamos janelas deslizantes.

Entrada: “O gato” -> Alvo: “subiu”

Entrada: “O gato subiu” -> Alvo: “no”

É assim que criamos milhões de exemplos de treinamento a partir de um único livro.

7. O Pipeline Completo: Da Letra ao Cérebro

Juntando tudo, temos o pipeline de entrada do nosso GPT.

É uma linha de montagem de dados:

Texto Bruto ➡️ Tokenização ➡️ IDs ➡️ Embeddings de Palavra + Embeddings de Posição ➡️ Entrada no Modelo.

🚀 Mão na Massa

Neste capítulo, não ficamos só na teoria. No notebook, nós implementamos:

Um Tokenizador do zero.O algoritmo BPE (sim, escrevemos a lógica de merge de tokens!).

A camada de Embeddings no PyTorch.

Quer ver como transformar Shakespeare em tensores matemáticos?

👇 O código está pronto para rodar:

📓 Notebook no Google Colab:Acessar o notebook

📂 Repositório GitHub:vongrossi/fazendo-um-llm-do-zero

Agora que transformamos texto em números, estamos prontos para a parte mais “humana” da IA. No próximo post: Atenção. 👀

Fazendo um LLM do Zero — Sessão 06: Dando uma Profissão ao Modelo (Fine-Tuning) 🎯👨‍⚕️

Von Grossi — Sun, 15 Feb 2026 00:00:00 +0000

Fazendo um LLM do Zero — Sessão 06: Dando uma Profissão ao Modelo (Fine-Tuning) 🎯👨‍⚕️
Até a sessão anterior, nosso GPT era como um adolescente que leu a biblioteca inteira: ele conhece todas as palavras, sabe construir frases bonitas e entende a estrutura da língua. Mas se você perguntar a ele: “Este e-mail é um spam ou uma promoção?”, ele pode simplesmente começar a escrever um poema sobre e-mails.

Ele tem conhecimento, mas não tem foco.

Na Sessão 06, aprendemos a transformar esse “estudante geral” em um “profissional especializado”. Como Sebastian Raschka detalha no Capítulo 6 de seu livro, esse processo se chama Fine-Tuning (Ajuste Fino). É aqui que a IA deixa de ser apenas um brinquedo curioso e se torna uma ferramenta útil para resolver problemas reais.

1. Da Educação Básica à Especialização

Podemos comparar a vida de um LLM com a carreira de um médico.

O Pré-treinamento (que vimos na Sessão 05) é a escola e a faculdade de medicina: o modelo aprende tudo sobre o corpo humano e a biologia de forma geral.

O Fine-tuning é a residência médica: o modelo escolhe uma especialidade (como Cardiologia ou Dermatologia) e foca intensamente nela.

Em vez de aprender a prever qualquer palavra, o modelo agora é treinado para uma tarefa específica, como Classificação de Texto.

2. Colocando um🎩 “Chapéu de Decisão”🧢(Classification Head)

Um GPT original foi desenhado para gerar texto. Para transformá-lo em um classificador (alguém que diz “Sim/Não”, “Positivo/Negativo”), precisamos fazer uma pequena cirurgia no seu cérebro.

Nós removemos a camada que gera palavras e colocamos uma Cabeça de Classificação.

Essa nova camada olha para toda a compreensão de texto que o modelo já tem e toma uma decisão final: “Baseado em tudo o que li nesta frase, a chance de ser Spam é 98%”.

3. Inteligência Eficiente: Congelar ou não Congelar?

Treinar um modelo inteiro de novo seria um desperdício de tempo e dinheiro. Afinal, o modelo já sabe o que é um verbo ou um substantivo. Por que ensinar isso de novo?

Join Medium for free to get updates from this writer.

Sebastian Raschka nos mostra que podemos ser inteligentes: Congelamos (Freeze) a maior parte do modelo e treinamos apenas a camada final. Ou, se tivermos mais dados, podemos Descongelar (Unfreeze) as últimas camadas para um ajuste mais fino.

É como se você contratasse um mestre de obras experiente: você não precisa ensiná-lo a usar um martelo, apenas mostra onde quer que a nova parede seja construída.

4. A Nova Linha de Montagem

O treinamento agora muda de cara. Não usamos mais apenas “texto puro”. Usamos Dados Rotulados (Exemplo:“Eu amei este filme” ->Rótulo:Positivo).

O modelo processa o texto, passa pela cabeça de classificação e nós comparamos a resposta dele com o rótulo real. O erro agora não é mais “qual era a próxima palavra”, mas sim “você acertou a categoria?”.

5. O Diagnóstico Final: A Matriz de Confusão

Como saber se o nosso especialista é realmente bom? Apenas “acurácia” pode enganar.

Se 90% dos seus e-mails não são spam, e o modelo disser “não é spam” para tudo, ele terá 90% de acerto, mas será um modelo inútil para detectar spams reais.

Para isso, usamos a Matriz de Confusão. Ela nos mostra onde o modelo está “confuso”: ele está deixando passar muito spam (Falso Negativo) ou está bloqueando e-mails importantes (Falso Positivo)?

🚀 Mão na Massa

Na Sessão 06, o nosso laboratório prático foi sobre transformar o GPTMini em um detector de sentimentos. Nós pegamos os pesos que treinamos na

Sessão 05, adicionamos a camada de classificação e vimos o modelo aprender a distinguir opiniões.

É a prova de que o conhecimento geral é a base para qualquer especialidade.

Quer transformar seu modelo em um especialista?

👇 Acesse os materiais desta sessão:

📓 Notebook no Google Colab:Rodar Fine-Tuning na Sessão 06

📂 Repositório GitHub:vongrossi/fazendo-um-llm-do-zero

Agora o modelo tem um emprego. Mas ele sabe conversar conosco e seguir ordens complexas? Esse é o desafio final da Sessão 07: Instruction Tuning.

Nos vemos lá! 💬🤝

Fazendo um LLM do Zero #00: Antes da Inteligência, a Oficina 🛠️🧠

Von Grossi — Sun, 15 Feb 2026 00:00:00 +0000

Fazendo um LLM do Zero #00: Antes da Inteligência, a Oficina 🛠️🧠 “Como isso realmente funciona por dentro?”

Essa foi a pergunta que me tirou do lugar de apenas usuário de Inteligência Artificial para o de estudante de seus fundamentos. Estamos vivendo a era dos modelos de linguagem gigantes, mas muitas vezes os usamos como caixas pretas mágicas.

Decidi mudar isso. Baseado no excelente livro Build a Large Language Model (From Scratch), de Sebastian Raschka, iniciei uma jornada para construir um GPT do zero. Mas antes de falarmos de neurônios artificiais ou atenção, precisamos alinhar o terreno.

Bem-vindo ao Passo Zero.

☁️ 1. O Laboratório na Nuvem: Google Colab

A primeira grande barreira para quem estuda IA costuma ser o hardware. “Preciso de uma GPU de milhares de dólares?”. A resposta curta é: Não.

Para esta série, escolhi o Google Colab como nossa oficina principal. Ele remove toda a fricção técnica de configuração de ambiente.

Acelerando o aprendizado sem barreiras de instalação local (Na minha maquina Funciona).

O Colab nos dá acesso a hardware potente (GPU/TPU) direto no navegador. Isso democratiza o estudo: o que importa agora é a sua lógica, não o seu computador. Os quatro pilares que sustentam nossa jornada no Colab são:

Zero Instalação: O ambiente já vem pronto.

Nuvem: Acesso de qualquer lugar.

Interatividade: Rodamos o código bloco a bloco, testando cada ideia na hora.

Análise: Gráficos e métricas integrados para entender o aprendizado do modelo.

🔥 2. PyTorch: A Nossa Oficina Matemática

Se o LLM é um cérebro, o PyTorch é o sistema biológico que o sustenta. Ele é a biblioteca de Deep Learning que escolhi para construir cada camada do nosso modelo.

Muitas vezes, a matemática da IA parece assustadora, mas o PyTorch a transforma em algo palpável.

O ecossistema que transforma matrizes em inteligência

O que realmente ligou para mim ao estudar o PyTorch foi entender sua hierarquia:

1. Tensores: São a fundação. Arrays multidimensionais que carregam nossos dados.

2. Autograd: O motor que calcula o erro e ajusta os pesos do modelo automaticamente.

3. nn.Module: As peças de LEGO (camadas lineares, funções de ativação) que vamos empilhar para criar o GPT.

Join Medium for free to get updates from this writer.

📦 3. O Ecossistema de Ferramentas

Ninguém constrói um LLM sozinho. Em Python, temos uma “caixa de ferramentas” modular que nos permite focar no que realmente importa: o conceito

🚀 Estamos prontos!

O objetivo deste Passo Zero foi garantir que você tenha tudo o que precisa para começar sem dores de cabeça com instalação ou hardware.

Construir uma IA não é mágica; é engenharia, é tentativa e erro, e é, acima de tudo, curiosidade. Com o ambiente configurado e as bibliotecas prontas, estamos prontos para a primeira pergunta real da série: O que é um LLM de verdade?

🧪 Um pouco de experimento!

O ambiente deste capítulo já está disponível para você testar. Acesse o notebook prático no Google Colab, valide seu ambiente e rode seu primeiro tensor:

👉 Abrir Passo Zero no Google Colab

Esta série é um projeto Open Source e você pode acompanhar cada atualização, sugerir melhorias ou clonar o código no repositório oficial:

🔗 GitHub: Fazendo um LLM do Zero

Se você já teve problemas tentando configurar ambientes de IA para rodar localmente?

Conte sua experiência!

Referências:

Livro: Build a Large Language Model (From Scratch) de Sebastian Raschka.

Material Inspirado no repositório: rasbt/LLMs-from-scratch https://github.com/rasbt/LLMs-from-scratch.