Como construir uma plataforma de GenAI: tutorial em 7 camadas

A maior parte das aplicações de IA generativa em produção começa simples: uma chamada a um LLM, um prompt, uma resposta. Em poucas semanas, esse desenho ingênuo encontra a parede da realidade — alucinações, custo, latência, dados sensíveis vazando, prompt injection, falta de visibilidade.

Chip Huyen escreveu um dos melhores guias que existem sobre como evoluir desse ponto inicial até uma plataforma robusta de GenAI. Este post é um tutorial inspirado no ensaio original, com adaptações práticas e foco em decisões de engenharia.

A ideia central é simples: adicione complexidade só quando o problema exigir. Cada camada que descrevo abaixo resolve uma dor específica. Pular etapas é tão custoso quanto adotar todas de uma vez.

O ponto de partida

A versão mais básica de uma aplicação GenAI é uma função pura:

user query → modelo → resposta

Nada de retrieval, nada de cache, nada de roteador. Apenas a chamada à API.

Esse desenho serve bem para validar uma ideia. Mas três limitações aparecem rápido:

• o modelo só sabe o que estava no seu treinamento;
• não há controle sobre o que entra ou sai;
• não há visibilidade sobre o que falha em produção.

A jornada que vem a seguir endereça essas três frentes.

Camada 1 — Enriqueça o contexto (RAG)

A primeira evolução é dar ao modelo informação que ele não tem. É o que chamamos de construção de contexto — equivalente a feature engineering em ML clássico.

Há três sabores principais:

RAG tradicional combina busca por termos (BM25, Elasticsearch) com busca por embeddings (FAISS, ScaNN, hnswlib). A versão híbrida quase sempre vence as duas isoladas. Um reranker barato na frente, um caro depois — esse é o padrão.

RAG com dados tabulares usa text-to-SQL: o modelo escreve a query, você executa contra o seu banco, devolve o resultado e ele formula a resposta final.

RAG agêntico combina retrieval, SQL e busca na web em um loop. O agente decide qual ação tomar com base na pergunta. Cuidado: aqui já não é mais só leitura — você está deixando o modelo encadear ações.

Uma quarta peça importante: query rewriting. Em conversas multi-turn, o usuário pergunta "e a Emília?" e o modelo precisa reescrever para "qual foi a última compra da Emília Silva?". Sem isso, o retrieval afunda.

Camada 2 — Coloque guardrails

A segunda camada protege seu sistema, seus usuários e sua empresa. Guardrails têm dois lados.

Na entrada, você quer detectar e mascarar PII (telefones, CPFs, contas bancárias), bloquear tentativas de jailbreak e filtrar tópicos restritos. Um padrão útil: substituir os dados sensíveis por placeholders reversíveis antes de mandar pro modelo, e remapear na resposta.

Na saída, você quer detectar:

• respostas vazias ou malformatadas (valide JSON com schema, código Python rodando em sandbox);
• toxicidade;
• alucinações (SelfCheckGPT, SAFE);
• vazamento de informação sensível;
• respostas que ferem a marca.

A política de falha importa tanto quanto a detecção: retry com limite, chamadas redundantes em paralelo para não inflar a latência, escalar para humano em casos de alto risco.

O tradeoff óbvio: cada guardrail adiciona latência. Streaming complica ainda mais porque você avalia tokens parciais. A pergunta certa é "qual o custo de uma falha?" — se for alto, paga a latência.

Camada 3 — Roteador de modelos e gateway

A partir daqui, sua aplicação raramente usa um modelo só. Você tem perguntas baratas que rodam em Haiku, perguntas complexas que precisam de Opus, queries com imagens, queries em outras línguas.

O roteador é um classificador de intenção que decide qual pipeline rodar. Ele evita gastar tokens caros em perguntas fora do escopo e ajusta o contexto ao limite de cada modelo.

O gateway é a camada de abstração que centraliza acesso aos modelos. Em uma frase: você não chama OpenAI nem Anthropic direto — você chama seu gateway. Isso te dá:

• controle fino de acesso e custo;
• políticas de fallback (rate limit, queda de provedor);
• logging e analytics centralizados;
• load balancing entre provedores.

Não precisa construir do zero. Portkey, MLflow AI Gateway, TrueFoundry, Kong e Cloudflare oferecem soluções maduras. Em projetos novos no ecossistema Vercel, a opção natural é o AI Gateway — você usa strings tipo "anthropic/claude-opus-4-7" no AI SDK e ganha fallback, observabilidade e cache automáticos.

Camada 4 — Reduza latência com cache

Cache em GenAI tem três variações. Cada uma resolve um problema diferente.

Prompt cache armazena segmentos de texto que se repetem entre chamadas — system prompt, documentos longos. O provedor processa uma vez e reaproveita. Anthropic, OpenAI e Google oferecem isso nativamente, com desconto típico de 75% nos tokens cacheados. Custo de armazenamento: ~$1/milhão de tokens por hora.

Exact cache guarda pares completos query→resposta. Se a mesma pergunta aparece, devolve direto, sem chamar o modelo, sem rodar retrieval, sem executar SQL. Implementação: Redis ou Postgres com política de eviction (LRU, LFU).

Semantic cache vai além — reaproveita respostas para perguntas similares, não idênticas. Requer um vector DB, threshold de similaridade calibrado e embeddings confiáveis. Funciona, mas é onde mais se erra: um threshold errado e você devolve resposta de uma pergunta diferente.

Minha recomendação: comece pelo prompt cache (é grátis), adicione exact cache quando o tráfego repetir, e só considere semantic cache quando os outros dois não bastarem.

Camada 5 — Lógica complexa e ações de escrita

Aqui sua aplicação deixa de ser um Q&A e vira um sistema.

Lógica complexa significa encadeamento iterativo de modelos com branching condicional. O output de uma chamada vira input da próxima. Um agente que planeja uma viagem para Paris faz isso o dia inteiro: pesquisa voos, decide datas, refina hotel, ajusta roteiro.

Ações de escrita são o salto seguinte: deixar o modelo mudar o mundo. Enviar e-mail, criar pedido, atualizar registro no banco. Aqui mora o maior risco da plataforma — prompt injection deixa de ser uma falha de UX e vira uma falha de segurança.

Regra de ouro: para cada ação de escrita, você precisa de:

1. uma camada de permissões clara (o modelo pode disparar essa ação para esse usuário?);
2. um guardrail específico que valida o payload;
3. logging completo para auditoria;
4. um caminho de reversão (transações, soft delete, undo).

Se você não tem confiança nessas quatro garantias, mantenha o sistema read-only.

Camada 6 — Observabilidade

Sem observabilidade, você não tem uma plataforma — tem uma caixa preta com sorte.

Três pilares clássicos, adaptados para GenAI:

Métricas que importam:

• modelo: acurácia, toxicidade, taxa de alucinação, timeout, resposta vazia;
• retrieval: relevância e precisão do contexto;
• latência: TTFT (time to first token), TBT (time between tokens), TPS, TPOT, latência total;
• custo: volume de queries, tokens de entrada e saída;
• formato: tamanho de query, contexto e resposta (mudanças bruscas sinalizam regressão).

Quebre tudo por usuário, release, versão de prompt e janela de tempo.

Logs: filosofia "logue tudo". Configuração da chamada, query original, query reescrita, contexto recuperado, prompt final, resposta crua, resposta filtrada, decisão de cada guardrail. Um hábito que separa quem está em produção de verdade: inspecionar amostras de dados em produção manualmente, todo dia, por uns 30 minutos.

Traces: o caminho completo da query até a resposta, com timing e custo por passo. Langsmith é o exemplo canônico. Quando algo falha em produção, é o trace que mostra onde.

Camada 7 — Orquestração

A última peça amarra todas as outras. Frameworks de orquestração (LangChain, LlamaIndex, Haystack, Flowise, Langflow) oferecem dois tipos de ajuda:

1. Definição de componentes: registrar modelos, bancos, ferramentas, integrações com gateway e ferramentas de avaliação.
2. Pipelining: encadear a execução do início ao fim, com paralelização onde der.

Um conselho contra-intuitivo: não comece com orquestrador. Frameworks abstraem coisas que você precisa entender na pele primeiro. Quando seu pipeline tiver 4–5 passos com branching e retry, aí faz sentido adotar.

Como usar este tutorial

A ordem importa. Resista à tentação de pular etapas porque "parece simples". Cada camada existe para resolver uma classe específica de problema:

1. comece com a chamada básica;
2. adicione RAG quando o modelo não souber;
3. coloque guardrails antes de abrir para usuário externo;
4. adicione roteador/gateway quando tiver mais de um modelo;
5. cache quando latência ou custo virarem problema;
6. lógica complexa e ações de escrita quando o produto exigir;
7. observabilidade desde o dia um (não retrofit);
8. orquestração só depois que a complexidade real justificar.

Avaliação é a única coisa que atravessa todas as camadas. Sem evals, qualquer mudança vira chute. Esse, aliás, é um tópico que merece um post próprio.

Referência

Ensaio original de Chip Huyen, que serve de espinha dorsal deste tutorial: Building A Generative AI Platform. Vale ler antes do livro AI Engineering dela, onde os tópicos que ficaram de fora (evals, fine-tuning, chunking, anotação) são tratados a fundo.