AI engineering, one layer at a time.

O que é engenharia de IAWhat AI engineering is

O livro AI Engineering (Chip Huyen, O’Reilly, 2025) ensina a construir aplicações em cima de modelos de fundação (foundation models): grandes modelos de linguagem, de imagem e outros, treinados por terceiros e usados por API ou hospedados por você.The book AI Engineering (Chip Huyen, O’Reilly, 2025) teaches how to build applications on top of foundation models: large language, image and other models, trained by others and used through an API or hosted by you.

A virada está no autossupervisionamento: o modelo aprende prevendo partes do próprio texto, sem rótulos feitos à mão. Isso permitiu escalar para bilhões de parâmetros e deu origem a uma nova profissão. Comparada à engenharia de ML tradicional, a engenharia de IA lida com modelos maiores, mais caros e com respostas abertas (texto livre), o que torna testar e avaliar muito mais difícil. Por isso ela fica mais próxima do produto.The turning point is self-supervision: the model learns by predicting parts of its own text, with no hand-made labels. That made it possible to scale to billions of parameters and created a new profession. Compared with traditional ML engineering, AI engineering deals with bigger, costlier models with open-ended outputs (free text), which makes testing and evaluating much harder. That is why it sits closer to the product.

Tokens: a unidade do modeloTokens: the model’s unit

Um modelo de linguagem não trabalha com letras nem com palavras, e sim com tokens. O conjunto de todos os tokens é o vocabulário (o do GPT-4 tem 100.256; o do Mixtral 8x7B, 32.000). Há dois tipos de modelo: o mascarado (preenche lacunas, como o BERT) e o autorregressivo (prevê o próximo token, usado para gerar texto). Daqui em diante, “modelo” é o autorregressivo: uma máquina de completar texto.A language model works with neither letters nor words, but with tokens. The set of all tokens is the vocabulary (GPT-4’s has 100,256; Mixtral 8x7B’s has 32,000). There are two kinds of model: the masked one (fills in blanks, like BERT) and the autoregressive one (predicts the next token, used to generate text). From here on, “model” means the autoregressive kind: a text-completion machine.

Como o modelo escolhe cada palavraHow the model picks each word

A cada passo o modelo calcula uma pontuação (logit) para cada token do vocabulário e as converte em probabilidades (softmax). Depois sorteia um token. É por isso que a mesma pergunta pode ter respostas diferentes: a geração é probabilística.At each step the model computes a score (logit) for every token in the vocabulary and turns them into probabilities (softmax). Then it samples one token. That is why the same question can get different answers: generation is probabilistic.

Temperatura, top-k e top-pTemperature, top-k and top-p

• Temperatura divide os logits antes do softmax. Exemplo do livro com dois tokens, A (logit 1) e B (logit 2): com temperatura 1, B sai 73% das vezes; com 0,5, sobe para 88%. Perto de 0, o modelo escolhe sempre o mais provável. Temperatura 0 é a escolha comum para respostas consistentes.Temperature divides the logits before the softmax. Book example with two tokens, A (logit 1) and B (logit 2): at temperature 1, B comes out 73% of the time; at 0.5 it rises to 88%. Close to 0, the model always picks the most likely one. Temperature 0 is the usual choice for consistent answers.
• Top-k considera só os k tokens mais prováveis (k costuma ficar entre 50 e 500).Top-k considers only the k most likely tokens (k is usually between 50 and 500).
• Top-p (nucleus) considera o menor grupo de tokens cuja probabilidade soma p (por exemplo, 0,9). Para “responda só sim ou não” sobram dois; para “qual o sentido da vida?” sobram muitos.Top-p (nucleus) considers the smallest group of tokens whose probabilities add up to p (for example, 0.9). For “answer yes or no only” two remain; for “what is the meaning of life?” many remain.

Do modelo bruto ao assistenteFrom raw model to assistant

O modelo só pré-treinado é um completador de texto “selvagem”. Dois passos de pós-treinamento o tornam útil: ajuste supervisionado (SFT), em que ele vê exemplos de boas respostas, e ajuste por preferência, em que aprende quais respostas as pessoas preferem. A qualidade dos dados de treino e a escala (parâmetros, tokens e capacidade de computação) explicam grande parte do desempenho.The pre-trained-only model is a “wild” text completer. Two post-training steps make it useful: supervised finetuning (SFT), where it sees examples of good answers, and preference finetuning, where it learns which answers people prefer. The quality of the training data and the scale (parameters, tokens and compute) explain a large share of performance.

Prompt engineeringPrompt engineering

Um prompt reúne instruções, exemplos, contexto e a pergunta. Por baixo dos panos, o prompt do sistema e o do usuário são concatenados num texto só, seguindo um chat template que cada modelo define. Usar o template errado causa falhas silenciosas: o modelo responde algo razoável, só que pior. Imprima o prompt final antes de enviar.A prompt brings together instructions, examples, context and the question. Under the hood, the system and user prompts are concatenated into a single text, following a chat template each model defines. Using the wrong template causes silent failures: the model answers something reasonable, only worse. Print the final prompt before sending it.

O teste “agulha no palheiro” mostra o efeito da figura: esconda um fato em posições diferentes de um texto longo e peça para o modelo achá-lo. Os modelos testados achavam melhor no começo e no fim.The “needle in a haystack” test shows the effect in the figure: hide a fact at different positions in a long text and ask the model to find it. The models tested did better at the start and end.

Boas práticas que valem para quase todo modeloBest practices that hold for almost any model

• Instruções claras e explícitas: diga o papel, a tarefa, o formato e o que evitar.Clear, explicit instructions: state the role, the task, the format and what to avoid.
• Dê contexto suficiente: o modelo só sabe o que está no prompt (e no treino).Give enough context: the model only knows what is in the prompt (and in training).
• Quebre tarefas complexas em subtarefas encadeadas, cada uma com seu prompt simples.Break complex tasks into subtasks chained together, each with its own simple prompt.
• Dê tempo para pensar: pedir o raciocínio passo a passo (chain-of-thought) melhora tarefas difíceis.Give the model time to think: asking for step-by-step reasoning (chain-of-thought) improves hard tasks.
• Itere e versione: trate prompts como código: teste, compare, guarde versões.Iterate and version: treat prompts like code: test, compare, keep versions.

Um exemplo simples (inventado)A simple example (invented)

Ruim:   "Resuma isto."

Melhor: "Você é um assistente de suporte. Resuma o e-mail abaixo
        em até 3 frases para um gerente. Destaque o pedido do
        cliente e o prazo. Se faltar o prazo, escreva 'prazo não
        informado'.

        E-mail: <<<...>>>"

Defesa: seu prompt também é uma superfície de ataqueDefense: your prompt is also an attack surface

O livro lista três ataques: extração do prompt (descobrir suas instruções), jailbreak e injeção de prompt (fazer o modelo agir mal, inclusive por texto escondido em documentos que ele lê) e extração de informação (vazar dados de treino ou de contexto). Com ferramentas, o risco sobe: um ataque pode virar execução de código ou consulta indevida ao banco. Mitigue limitando as permissões das ferramentas, filtrando entradas e saídas e tratando todo conteúdo externo como dado, não como ordem.The book lists three attacks: prompt extraction (discovering your instructions), jailbreaking and prompt injection (making the model misbehave, including through text hidden in documents it reads) and information extraction (leaking training or context data). With tools the risk goes up: an attack can become code execution or an improper database query. Mitigate by limiting tool permissions, filtering inputs and outputs, and treating all external content as data, not orders.

RAG: dar ao modelo o que ele não sabeRAG: giving the model what it doesn’t know

O modelo não conhece seus documentos privados e pode estar desatualizado. O RAG (Retrieval-Augmented Generation) resolve em dois passos: buscar os trechos relevantes numa base externa e gerar a resposta com eles no prompt. Também economiza contexto e dinheiro, porque você manda só o que importa.The model doesn’t know your private documents and may be out of date. RAG (Retrieval-Augmented Generation) fixes that in two steps: retrieve the relevant chunks from an external base and generate the answer with them in the prompt. It also saves context and money, because you send only what matters.

Dois jeitos de buscarTwo ways to retrieve

• Por termos (TF-IDF, BM25, Elasticsearch): conta palavras. Quanto mais um termo aparece num documento (TF), mais relevante; quanto mais documentos contêm o termo, menos informativo ele é (IDF). Um índice invertido guarda, para cada termo, os documentos onde ele aparece. É leve e um excelente ponto de partida.By terms (TF-IDF, BM25, Elasticsearch): counts words. The more a term appears in a document (TF), the more relevant; the more documents contain the term, the less informative it is (IDF). An inverted index stores, for each term, the documents where it appears. It is light and an excellent starting point.
• Por embeddings (busca vetorial): cada trecho vira um vetor numérico que captura o significado, e a busca acha os vetores mais próximos do vetor da pergunta. Acha “carro” quando você escreveu “automóvel”, mas custa mais.By embeddings (vector search): each chunk becomes a numeric vector capturing its meaning, and the search finds the vectors closest to the question’s vector. It finds “car” when you wrote “automobile”, but costs more.

Índice invertido (simplificado)
termo      docs onde aparece (documento, frequência)
banana     (10, 3)  (5, 2)
machine    (1, 5)  (10, 1)  (38, 9)  (42, 5)

Exemplo de IDF do livro: se há 10 documentos e 5 contêm o termo, a razão 10 / 5 = 2. Um termo presente em todos os documentos (como “de”) tem IDF baixo e pouco ajuda. Na prática usa-se o logaritmo dessa razão.Book example of IDF: with 10 documents, 5 of which contain the term, the ratio is 10 / 5 = 2. A term in every document (like “the”) has a low IDF and helps little. In practice the logarithm of that ratio is used.

Quebrar os documentos em trechos (chunking)Splitting documents into chunks

Como você divide importa. Dá para cortar por tamanho fixo, por frase, por parágrafo ou recursivamente (seção, depois parágrafo, depois frase). Use sobreposição entre trechos: se o texto “Deixei um bilhete para minha esposa” for cortado em “Deixei um bilhete para” e “minha esposa”, nenhum pedaço faz sentido sozinho. Trechos menores permitem colocar mais fontes no prompt; trechos maiores guardam mais contexto.How you split matters. You can cut by fixed size, by sentence, by paragraph or recursively (section, then paragraph, then sentence). Use overlap between chunks: if “I left my wife a note” is cut into “I left my wife” and “a note”, neither piece makes sense alone. Smaller chunks let you fit more sources in the prompt; bigger ones keep more context.

AgentesAgents

Um agente é qualquer coisa que percebe um ambiente e age nele. Em IA, o modelo é o “cérebro” que planeja, e as ferramentas (buscar na web, rodar código, consultar SQL, chamar APIs) são as mãos. Um sistema RAG é um agente simples cuja única ferramenta é o buscador.An agent is anything that perceives an environment and acts on it. In AI, the model is the “brain” that plans, and tools (web search, running code, SQL queries, API calls) are the hands. A RAG system is a simple agent whose only tool is the retriever.

Exemplo do livro: “projete as vendas dos próximos três meses”. O agente raciocina que precisa do histórico, gera e executa uma consulta SQL, vê que faltam dados, busca as campanhas de marketing passadas, e só então produz a projeção.Book example: “project sales for the next three months”. The agent reasons that it needs the history, generates and runs a SQL query, sees data is missing, fetches past marketing campaigns, and only then produces the projection.

• Planejamento: separar o plano da execução permite validar o plano antes de agir.Planning: separating the plan from execution lets you validate the plan before acting.
• Reflexão e correção de erros: o agente confere o resultado e tenta de novo.Reflection and error correction: the agent checks the result and tries again.
• Memória: guardar o que já foi feito e aprendido.Memory: keeping what has been done and learned.
• Mais ferramentas, mais poder, mais risco: quanto mais autonomia, mais graves as falhas. Peça confirmação humana antes de ações irreversíveis.More tools, more power, more risk: the more autonomy, the worse the failures. Ask for human confirmation before irreversible actions.

Avaliação: como saber se funcionaEvaluation: knowing whether it works

O livro dedica dois capítulos à avaliação, porque sem ela você não sabe se melhorou ou piorou. Como as respostas são abertas, não dá para só comparar com um gabarito. As técnicas:The book devotes two chapters to evaluation, because without it you can’t tell whether you improved or regressed. Since answers are open-ended, you can’t just compare against an answer key. The techniques:

• Correção funcional: rode o resultado. O SQL gerado devolve os dados certos? O código passa nos testes? É a avaliação mais confiável quando é possível.Functional correctness: run the result. Does the generated SQL return the right data? Does the code pass the tests? It is the most reliable evaluation when possible.
• Similaridade com uma resposta de referência: igualdade exata, parecença de texto ou de significado (embeddings).Similarity to a reference answer: exact match, text overlap or meaning similarity (embeddings).
• IA como juiz: outro modelo dá nota ou compara respostas. É flexível e explica a nota, mas é subjetivo: depende do juiz e do prompt do juiz, e muda quando o juiz muda.AI as a judge: another model scores or compares answers. It is flexible and explains its score, but it is subjective: it depends on the judge and the judge’s prompt, and it changes when the judge changes.
• Avaliação comparativa: “qual das duas é melhor, A ou B?”, como num ranking de xadrez.Comparative evaluation: “which one is better, A or B?”, like a chess ranking.
• Pessoas: amostras revisadas por humanos continuam essenciais.People: samples reviewed by humans remain essential.

Prompt de juiz (simplificado, do tipo mostrado no livro)
"Dada a pergunta e a resposta, dê uma nota de 1 a 5.
 1 = muito ruim, 5 = muito boa.
 Pergunta: [PERGUNTA]
 Resposta: [RESPOSTA]
 Nota:"

Montando seu pipeline de avaliaçãoBuilding your evaluation pipeline

1. Avalie cada componente do sistema (busca, geração, ferramentas), não só o resultado final.Evaluate each component of the system (retrieval, generation, tools), not only the final result.
2. Escreva um guia de avaliação: o que é uma boa resposta para o seu caso? Inclua exemplos.Write an evaluation guideline: what is a good answer in your case? Include examples.
3. Defina métodos e dados: um conjunto de perguntas reais, de casos fáceis e difíceis, que você roda a cada mudança.Define methods and data: a set of real questions, easy and hard cases, that you run on every change.

Finetuning e dadosFinetuning and data

Finetuning é continuar o treino do modelo com seus exemplos. A regra de bolso do livro: finetuning é para forma, RAG é para fatos.Finetuning is continuing the model’s training on your examples. The book’s rule of thumb: finetuning is for form, RAG is for facts.

Antes de ajustar, esgote o prompting. Para testar a ideia, comece com um conjunto pequeno e bem feito (50 a 100 exemplos); se não há melhora nenhuma, mais dados raramente resolvem.Before finetuning, exhaust prompting. To test the idea, start with a small, well-made set (50 to 100 examples); if there is no improvement at all, more data rarely helps.

Ajustar sem quebrar o orçamento: PEFT e LoRAFinetuning without breaking the budget: PEFT and LoRA

Treinar todos os pesos de um modelo grande exige muita memória. Os métodos PEFT treinam só uma fração. O mais popular é o LoRA: em vez de alterar uma matriz grande W, você a congela e treina duas matrizes finas, A e B, cujo produto é somado a W. No exemplo do livro, uma matriz 9 × 9 tem 81 números, mas fatorada em 9 × 1 e 1 × 9 tem só 18. Num caso citado do GPT-3, o LoRA treinou cerca de 4,7 milhões de parâmetros, 0,0027% do ajuste completo, com desempenho comparável em várias tarefas. Os módulos LoRA também são fáceis de trocar e combinar.Training all the weights of a big model takes a lot of memory. PEFT methods train only a fraction. The most popular is LoRA: instead of changing a large matrix W, you freeze it and train two thin matrices, A and B, whose product is added to W. In the book’s example a 9 × 9 matrix has 81 numbers, but factored into 9 × 1 and 1 × 9 it has only 18. In a cited GPT-3 case, LoRA trained about 4.7 million parameters, 0.0027% of full finetuning, with comparable performance on several tasks. LoRA modules are also easy to swap and combine.

Engenharia de dadosDataset engineering

Os dados de treino têm três critérios: qualidade, cobertura (variedade de casos) e quantidade. Pouco dado de alta qualidade pode superar muito dado ruidoso. Quando faltam exemplos, usa-se dados sintéticos gerados por outro modelo, que também precisam ser avaliados. O livro lembra: dá para automatizar a geração, mas não o pensar sobre quais dados você quer nem a atenção aos detalhes.Training data has three criteria: quality, coverage (variety of cases) and quantity. A little high-quality data can beat a lot of noisy data. When examples are scarce, synthetic data generated by another model is used, and it must be evaluated too. The book reminds us: you can automate generation, but not thinking about which data you want, nor attention to detail.

Inferência: velocidade e custoInference: speed and cost

Um modelo bom demais e lento demais não serve. A resposta tem duas fases: o prefill (ler o prompt, que define o tempo até o primeiro token, TTFT) e o decode (gerar um token por vez, com tempo por token TPOT). Para ler em streaming, algo como 120 ms por token já acompanha uma leitura rápida.A model that is too good and too slow is useless. The answer has two phases: prefill (reading the prompt, which sets the time to first token, TTFT) and decode (generating one token at a time, with time per token TPOT). For streamed reading, around 120 ms per token already keeps up with fast readers.

Há um equilíbrio entre latência e custo: agrupar muitas requisições (batching) baixa o custo por resposta, mas pode aumentar a espera. Técnicas citadas: quantização (usar menos bits por número), destilação (treinar um modelo menor para imitar um maior), KV cache (guardar cálculos já feitos do prompt) e prompt caching (reaproveitar o início de prompts repetidos, útil com documentos longos). Se você usa APIs, boa parte já vem pronta; saber isso ajuda a comparar fornecedores.There is a trade-off between latency and cost: grouping many requests (batching) lowers cost per answer but can increase waiting. Techniques mentioned: quantization (fewer bits per number), distillation (training a smaller model to imitate a bigger one), KV cache (keeping calculations already done on the prompt) and prompt caching (reusing the start of repeated prompts, useful with long documents). If you use APIs much of this comes built in; knowing it helps compare vendors.

Arquitetura de uma aplicação de IAArchitecture of an AI application

O último capítulo junta tudo e propõe crescer em etapas, só quando preciso. Começa com o caminho mínimo (a pergunta vai ao modelo e a resposta volta) e vai acrescentando:The last chapter ties it all together and proposes growing in steps, only when needed. It starts with the minimal path (the question goes to the model and the answer comes back) and adds:

1. Contexto: RAG e ferramentas, como “feature engineering” do modelo.Context: RAG and tools, like “feature engineering” for the model.
2. Guardrails: na entrada, bloquear ou mascarar dados sensíveis e ataques; na saída, checar formato, toxicidade e fatos.Guardrails: on input, block or mask sensitive data and attacks; on output, check format, toxicity and facts.
3. Router e gateway: um classificador de intenção manda perguntas simples para modelos baratos e as difíceis para os fortes; o gateway centraliza chaves, limites e trocas de fornecedor.Router and gateway: an intent classifier sends simple questions to cheap models and hard ones to strong models; the gateway centralizes keys, limits and vendor swaps.
4. Caches: o exato reaproveita respostas para pedidos idênticos; o semântico reaproveita para pedidos parecidos.Caches: the exact one reuses answers for identical requests; the semantic one reuses them for similar requests.
5. Agentes: fluxos com laços, condições e ações de escrita.Agents: flows with loops, conditions and write actions.

Em cima de tudo, observabilidade: métricas e alertas para saber como o sistema falha e achar a causa. E o feedback dos usuários (um polegar para cima, uma edição, uma reclamação) vira dado para melhorar o produto: o chamado data flywheel.On top of everything, observability: metrics and alerts to know how the system fails and find the cause. And user feedback (a thumbs-up, an edit, a complaint) becomes data to improve the product: the so-called data flywheel.