Visão geral
Um notebook que funciona não é um produto. Entre os dois existe o abismo de integração: concorrência, formatos, latência, dependências, segurança. Três pilares organizam a travessia:
- API — a ponte entre sistemas;
- LLM — o "cérebro" que interpreta e gera texto;
- RAG — a "memória": buscar trechos relevantes de uma base e entregá-los ao LLM.
HTTP e REST
- HTTP é stateless: cada requisição é independente; o servidor não lembra da anterior.
GETpara consultar (sem corpo);POSTpara enviar dados (com corpo/payload).- Respostas em JSON; códigos 2xx sucesso, 4xx erro do cliente (400 entrada inválida, 401/403 sem permissão, 429 limite excedido), 5xx erro do servidor.
- Rota
/healthresponde se o serviço está vivo (usada por balanceadores e orquestradores).
FastAPI + Pydantic
- FastAPI cria APIs em Python com documentação automática em
/docs. - Pydantic valida o contrato de entrada e saída: tipo errado vira erro de validação antes do seu código rodar.
- Rodar localmente com Uvicorn.
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Pergunta(BaseModel):
texto: str
top_k: int = 4
class Resposta(BaseModel):
resposta: str
fontes: list[str]
@app.get("/health")
def health():
return {"status": "ok"}
@app.post("/query", response_model=Resposta)
def query(p: Pergunta):
trechos = buscar(p.texto, p.top_k) # banco vetorial
texto = gerar(p.texto, trechos) # LLM
return Resposta(resposta=texto, fontes=[t.fonte for t in trechos])
LLM como componente de engenharia
- Tokens: unidade de cobrança e de limite de contexto (aprox. ¾ de palavra em inglês; um pouco menos em português).
- Custo por chamada: \(\text{custo} = \frac{\text{tokens}_{in}}{10^6}p_{in} + \frac{\text{tokens}_{out}}{10^6}p_{out}\) — a saída costuma custar mais que a entrada.
- Temperatura: baixa (0–0,2) para extração, JSON e RAG; alta (0,7–1,0) para criação.
- Limites de taxa (requisições e tokens por minuto): ao receber 429, aplique backoff exponencial e tenha um modelo de reserva.
- Chaves de API em variáveis de ambiente (
.env+load_dotenv()), nunca no código; chaves diferentes por ambiente. - FinOps: medir tokens e custo por rota; cache de respostas repetidas.
- Modelo proprietário (simples e potente, mas o prompt vai ao provedor) × pesos abertos (soberania, porém custo de infraestrutura).
Embeddings e similaridade
- Embedding: vetor denso que representa o significado; textos de sentido parecido ficam próximos no espaço.
- Similaridade de cosseno: \(\cos\theta = \dfrac{A\cdot B}{\lVert A\rVert\,\lVert B\rVert}\) — 1 = mesma direção, 0 = ortogonais, -1 = opostos. Ex.: \(A=(1,2,3)\) e \(B=(2,4,6)\) dão 1.
- Banco vetorial guarda vetores + metadados e faz busca dos mais próximos (top-K):
- protótipo local: Chroma, DuckDB, FAISS;
- serviço compartilhado: Qdrant, Milvus, Pinecone, pgvector (PostgreSQL).
RAG, passo a passo
Fase offline (ingestão) 1. Extrair o texto (PDF, páginas, documentos). 2. Chunking: quebrar em pedaços com sobreposição (comece com 10–15%) para não cortar uma informação no limite. 3. Gerar embeddings em lote (com retry em erro 429). 4. Gravar no banco vetorial com metadados (fonte, página, data).
Fase online (consulta) 1. Gerar o embedding da pergunta. 2. Buscar os top-K trechos mais próximos. 3. Montar o prompt com ancoragem: "responda só com base no contexto; se não estiver lá, diga que não consta". 4. Chamar o LLM com temperatura baixa. 5. Devolver resposta + fontes + métricas.
RAG ou fine-tuning?
| Necessidade | Escolha |
|---|---|
| Conhecimento factual que muda (políticas, manuais, catálogos) | RAG |
| Citar a fonte da resposta | RAG |
| Estilo, tom, formato fixo | fine-tuning |
| Capacidades gerais novas | treinamento |
RAG não conserta dado ruim (lixo entra, lixo sai) e não altera os pesos do modelo.
Observabilidade e avaliação
- Latência por etapa: em geral o gargalo é a geração do LLM (segundos), não a busca vetorial (milissegundos).
- Tokens e custo estimado por chamada, melhor distância de cosseno, motivo de término (
finish_reason). - Teste perguntas dentro e fora da base: fora, o sistema deve responder "não consta".
- Produção: réplicas atrás de balanceador, banco vetorial dedicado, testes de carga, chaves por ambiente, respeito às permissões de quem pergunta (o RAG não pode devolver um documento que o usuário não poderia ver).
Bibliotecas
fastapi, uvicorn, pydantic, python-dotenv, python-multipart, pypdf, requests, numpy, SDKs de LLM e embeddings, chromadb / qdrant-client / pgvector.