# 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**.

```python
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`.

## Perguntas de revisão

1. **Por que um protótipo não vira produto sozinho?** Por causa do abismo de integração: concorrência, formatos, latência, dependências e segurança.
2. **Quais os três pilares de um sistema com LLM?** API (ponte), LLM (cérebro) e RAG (memória).
3. **GET ou POST quando há payload?** POST; sem payload, GET.
4. **O que significa HTTP ser stateless?** Cada requisição é independente; o servidor não guarda estado entre elas.
5. **Para que serve a rota `/health`?** Para que balanceadores e orquestradores verifiquem se o serviço está vivo.
6. **O que o Pydantic faz numa API?** Valida o contrato de entrada e saída antes do código rodar.
7. **Que temperatura usar em RAG?** Baixa, entre 0 e 0,2.
8. **Onde guardar a chave de API?** Em variável de ambiente (`.env`), nunca no código.
9. **Como tratar o erro 429?** Com backoff exponencial, respeitando os limites, e um modelo de reserva.
10. **Por que a saída de um LLM custa mais?** Porque o preço por milhão de tokens de saída costuma ser maior que o de entrada.
11. **O que é um embedding?** Um vetor denso que representa o significado de um texto.
12. **Qual o cosseno de dois vetores na mesma direção?** 1 (0 se ortogonais, -1 se opostos).
13. **Por que usar sobreposição no chunking?** Para não cortar uma informação no limite entre dois pedaços.
14. **Quais as fases do RAG?** Offline (extrair, quebrar, vetorizar, gravar) e online (vetorizar a pergunta, buscar, montar o prompt, gerar).
15. **RAG corrige dado errado?** Não; lixo entra, lixo sai.
16. **RAG ou fine-tuning para uma política interna que muda?** RAG; fine-tuning é para estilo e formato.
17. **Onde costuma estar o gargalo de latência?** Na geração do LLM, não na busca vetorial.
18. **Por que não usar um banco vetorial local em produção?** Falta escala e alta disponibilidade; use um serviço dedicado.
19. **Como testar se o RAG está ancorado?** Fazendo perguntas fora da base: a resposta deve ser "não consta".
20. **O RAG altera os pesos do modelo?** Não; só fornece contexto na hora da pergunta.

---
Fonte: Atlas de Dados — https://atlas.frediania.com/materia/apis-llms-rag
