Pular para o conteúdo
Atlas de Dados

Texto e IA generativa

APIs, LLMs e RAG

Do protótipo ao serviço — HTTP/REST, FastAPI e Pydantic, LLM como componente de engenharia (tokens, custo, temperatura, limites, chaves), embeddings, similaridade de cosseno, bancos vetoriais e uma API de RAG.

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.
  • GET para consultar (sem corpo); POST para 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 /health responde 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.