O que é Como ler este catálogo?
Como ler este catálogo (How to read this catalog) é um fundamento de engenharia de IA para quem trabalha com LLMs. Os cinco pilares, como as páginas se ligam e por onde começar conforme o seu perfil.
Conteúdo da trilha
Capítulos
Transcrição
Abertura
Imagine sua primeira semana num time novo. Você herdou um assistente que atende clientes no WhatsApp, consulta pedidos e às vezes chama uma pessoa.
Ele funciona. Mas toda mudança no prompt dá medo, a conta do provedor subiu, e ninguém sabe explicar por que o bot disse um absurdo ontem.
Você abre o código. A primeira coisa que aparece é um prompt de sistema com quarenta parágrafos.
Depois, um loop que chama o modelo até ele decidir que terminou, sem contador nenhum.
E nenhum teste. Você sente que tem algo errado. O difícil é dizer o quê, decidir o que vem primeiro e consertar sem quebrar o resto.
Você não precisa de mais um tutorial de como chamar uma API. Precisa de palavras para o que está errado e de um caminho seguro para consertar. É para isso que serve este catálogo, e nesta aula você vai aprender a usá-lo.
A ideia
O catálogo organiza a engenharia de sistemas com modelos de linguagem em cinco pilares. Cada um responde uma pergunta diferente.
Fundamentos respondem: o que eu preciso saber antes de projetar qualquer coisa? Tokens, custo, como o modelo escolhe palavras.
Smells respondem: o que está errado no meu sistema? Aquele prompt gigante tem nome. Chama prompt bloat.
Refatorações respondem: como eu conserto sem quebrar?
Padrões respondem: qual é o formato certo para esse tipo de problema? E o quinto pilar, os cenários reais, mostra tudo isso dentro de um sistema completo.
Como funciona
Os pilares não são caixas separadas. Eles formam um caminho, e você vai percorrê-lo muitas vezes.
Começa com um smell. Um smell é um sinal de que algo vai doer depois. O sistema funciona hoje, mas está ficando caro, frágil ou inseguro.
O smell aponta para uma refatoração. Uma refatoração muda a estrutura sem mudar o que o usuário recebe. E toda refatoração começa e termina com um eval, um teste para o que o modelo produz.
A refatoração leva a um padrão de projeto, o jeito comprovado de resolver aquele tipo de problema.
E o padrão aparece nos cenários reais. Cada cenário começa com uma primeira versão ingênua. Essa primeira versão tem os smells do passo um, e o ciclo recomeça.
Um caso real
Vamos voltar ao assistente que você herdou e seguir esse caminho com os dois problemas mais visíveis dele.
Primeiro, o loop sem contador. Uma única execução custou dezenas de vezes mais que uma normal. Esse smell se chama unbounded loop.
A correção é uma refatoração chamada add loop budget: um limite de passos, tokens e tempo.
E onde você chega é um padrão chamado stop conditions, em que o agente sabe exatamente quando precisa parar.
Segundo, o prompt de quarenta parágrafos, em que cada bug corrigido virou mais um parágrafo. Isso é prompt bloat.
A refatoração tira uma tarefa e coloca num prompt menor, só dela. Chama extract subprompt.
E o destino é o prompt chaining: poucas etapas curtas, cada uma fácil de testar.
Agora repare na ordem. Você não pula do sintoma direto para reescrever tudo com o padrão certo. A refatoração é o caminho pequeno e medido entre o que existe hoje e o formato final. Primeiro mede, depois muda a estrutura, depois mede de novo.
Um desafio
Uma pergunta para você. Um colega aplicou extract subprompt no classificador de tickets e diz que ficou muito melhor. Pelo que você acabou de ouvir, o que falta antes de aceitar essa mudança?
Falta o eval, rodado antes e depois, com os números lado a lado. Sem o número de antes, melhor é só uma impressão. E uma queda em outra categoria passaria totalmente despercebida.
Trocar para um modelo maior também não responde a pergunta. Mistura duas mudanças e deixa tudo mais caro. A garantia de que nada piorou vem da medição.
Smell não é bug
A palavra smell vem da refatoração clássica de código. E tem uma diferença que vale guardar. Um bug quebra hoje. Um smell funciona hoje e cobra depois.
Cobra na conta.
No tempo que o seu time gasta mantendo.
E às vezes num incidente de segurança.
Por isso todo smell do catálogo tem uma seção chamada quando ignorar. Um prompt grande num protótipo com dez usuários pode estar ótimo. O mesmo prompt num canal de atendimento com milhares de conversas por dia é dinheiro saindo todo mês.
O catálogo dá o diagnóstico. A decisão de quando consertar continua sua.
E o erro mais comum de quem está começando é o contrário: ler a lista de smells e tentar consertar todos de uma vez. Comece pelo que mais dói. Normalmente, é o que aparece na conta ou no incidente da semana.
Como se achar
Toda página de um pilar tem as mesmas seções na mesma ordem. Aprenda o formato uma vez e você acha tudo sem procurar. E os números dos diagramas batem com os comentários do código. Se o passo três do diagrama é classificar, o código também diz passo três, classificar. Quando se perder no código, volte ao diagrama pelo número.
No caminho, você encontra perguntas curtas. Toda opção tem explicação, até as erradas, porque o erro mais útil é o que você entende.
E se você chegou por uma busca, ler fora de ordem não tem problema. Toda página termina com um leia a seguir, apontando o próximo passo mais útil dali. Se quiser uma ordem, siga as trilhas. Elas formam um curso só: fundamentos, evals, RAG e contexto, agentes, segurança e produção.
Experimente
Agora escolha um sistema que você conhece e responda quatro perguntas. Escreva as respostas, mesmo que seja não sei.
Um. Quantos tokens tem o prompt de sistema hoje? Se a resposta for vários milhares, ou não faço ideia, leia prompt bloat.
Dois. Se alguém muda uma linha do prompt, como você sabe que nada piorou? Se a resposta for a gente testa umas perguntas na mão, leia untested prompt.
Três. Se o modelo faz algo errado em produção, onde você olha? Se não dá para saber, leia no tracing.
Quatro. Qual foi a execução mais cara do mês, e quanto custou? Se ninguém acompanha isso, leia no cost budget.
A maioria dos times responde mal pelo menos duas. É normal, e é um bom ponto de partida. Você acabou de montar a sua lista de prioridades, com nomes que o resto do time consegue consultar.
Fechamento
Esse é o valor de um vocabulário comum. Dizer que este agente tem tool sprawl diz mais ao time do que dizer que o agente se confunde às vezes. O nome carrega o diagnóstico, a correção testada e o formato que você quer alcançar.
Na próxima aula, a gente começa pelo próprio modelo: quatro propriedades que todo engenheiro precisa conhecer e que quase todo padrão daqui tenta controlar. Até lá.
Como ler este catálogo
How to read this catalog
Como ler este catálogo (How to read this catalog) é um fundamento de engenharia de IA para quem trabalha com LLMs. Os cinco pilares, como as páginas se ligam e por onde começar conforme o seu perfil.
- Elemento
- 01/13
- Nível
- Iniciante
- Leitura
- 6 min
- Atualizado
A situação
Você herdou um assistente com LLM. Ele responde clientes no WhatsApp, consulta pedidos e às vezes chama uma pessoa. Funciona, mas cada mudança no prompt dá medo, a conta do provedor subiu e ninguém sabe dizer por que o bot respondeu aquela bobagem ontem.
Você abre o código e acha um system prompt de 40 parágrafos, um loop while True sem contador e nenhum teste. Dá para sentir que tem algo errado. O difícil é dizer o quê, decidir o que vem primeiro e consertar sem quebrar o resto.
Você não precisa de mais um tutorial de “como chamar a API”. Precisa de um vocabulário para dar nome ao que está errado e de um caminho seguro para consertar. É para isso que este catálogo existe.
O conceito
O ai-guru organiza a engenharia de sistemas com LLM em cinco pilares. Cada um responde a uma pergunta diferente.
| Pilar | Pergunta que responde | Exemplo |
|---|---|---|
| 0. Fundamentos | O que eu preciso saber antes de desenhar? | Tokens e janela de contexto |
| 1. Smells | O que está errado no meu sistema? | Prompt Inchado |
| 2. Refatorações | Como eu conserto sem quebrar? | Extrair Subprompt |
| 3. Padrões | Qual é a forma certa de montar isso? | Roteamento |
| 4. Cenários reais | Como isso fica num sistema inteiro? | Bot de suporte com escalonamento humano |
Os pilares não são caixas separadas. Eles formam um grafo:
flowchart LR
S(["1. Smell: o sintoma"]):::io --> R["2. Refatoração: o conserto"]:::tool
R --> P(["3. Padrão: a forma final"]):::llm
P --> C[("4. Cenário: o sistema real")]:::store
C -.->|"versão 1"| S
- Você reconhece um smell, um sinal de que algo vai doer mais tarde. O sistema funciona, mas fica caro, frágil ou inseguro.
- O smell aponta para uma ou mais refatorações. Cada uma muda a estrutura sem mudar o que o usuário recebe, e começa e termina com um eval (um teste para saída de modelo).
- A refatoração leva a um padrão de projeto, a forma testada de resolver aquele tipo de problema.
- O padrão aparece em cenários reais, sistemas contados da versão ingênua até a arquitetura final. A versão ingênua de cada cenário tem os smells do passo 1, e o ciclo recomeça.
Um exemplo, do sintoma ao sistema
Volte ao assistente que você herdou e siga o grafo com os dois problemas mais visíveis.
| Passo | Problema 1: o loop | Problema 2: o prompt |
|---|---|---|
| O que você vê | while True sem contador; uma execução custou dezenas de vezes a mediana |
System prompt de 40 parágrafos; cada bug resolvido virou mais um |
| Smell | Loop Sem Fim | Prompt Inchado |
| Refatoração | Adicionar Orçamento ao Loop | Extrair Subprompt |
| Padrão de destino | Condições de Parada | Encadeamento de Prompts |
Repare na ordem. Você não pula do sintoma para “reescrever tudo com o padrão certo”. A refatoração é o caminho pequeno e medido entre o que existe hoje e a forma final. Primeiro você mede o comportamento atual com um eval, depois muda a estrutura, depois mede de novo.
Smell não é bug
Smell (cheiro de problema) é um termo emprestado da refatoração de código clássica. Um bug quebra hoje. Um smell funciona hoje e cobra depois: na fatura, no tempo de quem mantém, no incidente de segurança.
Por isso todo smell tem a seção “Quando ignorar”. Um prompt grande num protótipo com dez usuários pode ser aceitável. O mesmo prompt num atendimento com milhares de conversas por dia é dinheiro saindo todo mês. O catálogo te dá o diagnóstico; a decisão de quando consertar continua sendo sua.
O erro comum de quem começa é o oposto: ler a lista de smells e querer consertar todos de uma vez. Comece pelo que mais dói. Em geral é o que aparece na fatura ou no incidente da semana.
O formato fixo das páginas
Toda página de um mesmo pilar tem as mesmas seções, na mesma ordem. Você aprende o formato uma vez e passa a achar tudo sem procurar.
- Fundamentos abrem com uma situação concreta, explicam o conceito com diagrama e trazem um experimento de 5 minutos.
- Smells mostram como reconhecer, por que acontece, quanto custa ignorar e um quiz para confirmar o diagnóstico.
- Refatorações mostram o antes e depois, o passo a passo seguro e os riscos.
- Padrões têm intenção, problema contado como história, diagrama numerado, pseudocódigo, custo, falhas, como avaliar e código.
- Cenários contam o negócio, o que quebrou, as refatorações aplicadas e os números.
Os números do diagrama batem com os comentários do pseudocódigo e com as seções do código. Se o passo 3 do diagrama é “classificar”, o código também tem # 3. classificar. Quando você se perder no código, volte ao diagrama pelo número.
As checagens ao longo do texto
As páginas têm perguntas curtas no meio do texto e um bloco no fim. Cada uma testa uma ideia da página com uma situação parecida com as do seu trabalho. Toda opção tem explicação, inclusive as erradas, porque o erro mais útil é o que você entende.
Cada pergunta acertada na primeira tentativa vale pontos. Os pontos de uma trilha somam no certificado da trilha. Se errar, leia a explicação, volte ao trecho e siga em frente: a pergunta existe para você saber o que já entendeu.
Por onde começar
| Você é | Comece por |
|---|---|
| Começando com LLMs | Trilha 1: Fundamentos de LLM para engenheiros |
| Vai colocar uma feature com LLM no ar e precisa confiar nela | Trilha 2: Evals e confiabilidade |
| Vai construir busca ou chat sobre documentos | Trilha 3: RAG e contexto |
| Quem vai construir agentes | Trilha 4: Construindo agentes |
| Quem responde por segurança | Trilha 5: Segurança de sistemas com IA |
| Tech lead ou quem opera em produção | Trilha 6: Produção: custo, latência e operação |
Se você chegou por uma busca, tudo bem ler fora de ordem. Toda página termina com “Leia a seguir”, que aponta o próximo passo mais útil a partir dali.
Experimente
Escolha um sistema com LLM que você conhece e responda quatro perguntas em 5 minutos. Escreva a resposta, mesmo que seja “não sei”.
1. Quantos tokens tem o system prompt hoje?
2. Se alguém mudar uma linha do prompt, como você sabe que nada piorou?
3. Se o modelo fizer algo errado em produção, onde você olha para entender por quê?
4. Qual foi a execução mais cara do mês, e quanto ela custou?Cada resposta ruim aponta para uma página:
| Se a resposta foi | Leia |
|---|---|
| 1: “alguns milhares” ou “não sei” | Prompt Inchado |
| 2: “a gente testa umas perguntas na mão” | Prompt Sem Eval |
| 3: “não dá para saber” | Voo Cego |
| 4: “ninguém acompanha” | Custo Sem Teto |
A maioria dos times responde mal a pelo menos duas. Isso é normal e é um bom ponto de partida: você acabou de montar sua lista de prioridades com nomes que o resto do time pode procurar.
O que isso muda
Com nomes para os problemas, a conversa no time fica mais curta. “Esse agente tem Ferramentas Demais” diz mais que “o agente às vezes se confunde”. O nome já traz o diagnóstico, o conserto testado e o padrão de destino, e qualquer pessoa do time pode abrir a mesma página.
Os nomes também ajudam a priorizar. Um item de backlog chamado “Loop Sem Fim no agente de boletos” tem custo e solução conhecidos. “Melhorar o agente” não tem.
Se você vai seguir em ordem, o próximo passo é LLM para engenheiros, que explica as quatro propriedades do modelo que quase todos os padrões deste catálogo tentam controlar.
Atalhos que ajudam a usar o site: / abre a busca, t troca o tema, l troca o idioma, j e k andam pela trilha.
Teste seu entendimento
Checagem da aula
Responda as 6 perguntas para concluir a aula. Só assistir não conclui: a checagem é o que conta para a trilha e para o certificado.
Perguntas rápidas
Para ir além
Relações
- Aparece nas trilhas 1