Como construir uma API de IA com Python, FastAPI, Pydantic e LLMs

Padrão de API de IA em produção: schemas Pydantic, streaming, timeouts, autenticação, orçamento de tokens e tratamento de falhas.

Por Emerson AmorimPublicado em 19 de setembro de 202615 min de leitura

Uma API de IA em produção é um serviço com contrato rígido: entrada validada, saída tipada, limites de tempo e custo, autenticação e falhas previsíveis — o LLM é só um dependente.

Contrato com Pydantic

Request/Response com limites

from pydantic import BaseModel, Field

class GenerateRequest(BaseModel):
    prompt: str = Field(min_length=1, max_length=8000)
    temperature: float = Field(default=0.2, ge=0, le=1)
    max_tokens: int = Field(default=512, ge=16, le=2048)

class GenerateResponse(BaseModel):
    text: str
    model: str
    input_tokens: int
    output_tokens: int
    request_id: str

Endpoint síncrono e streaming

FastAPI com timeout e request id

from fastapi import FastAPI, Depends, HTTPException
from fastapi.responses import StreamingResponse
import uuid, asyncio

app = FastAPI(title="AI API")

@app.post("/v1/generate", response_model=GenerateResponse)
async def generate(body: GenerateRequest, user=Depends(auth)):
    request_id = str(uuid.uuid4())
    budget = await reserve_budget(user.id, body.max_tokens)
    if not budget.ok:
        raise HTTPException(402, "token_budget_exceeded")
    try:
        result = await asyncio.wait_for(
            llm_generate(body, user_id=user.id),
            timeout=30,
        )
    except asyncio.TimeoutError:
        await release_budget(budget)
        raise HTTPException(504, "upstream_timeout")
    return GenerateResponse(**result, request_id=request_id)

Para UX conversacional, exponha SSE ou WebStream. Mantenha o mesmo request_id no início do stream e um evento final com contagem de tokens.

Segurança e isolamento

AuthN/AuthZ por chave ou JWT; nunca chave de provedor no cliente
Rate limit por usuário e por rota
Redação de PII em logs
Allowlist de modelos e de ferramentas se a API orquestra agentes

Confiabilidade

Timeouts menores que o do API gateway
Retry apenas em erros transitórios idempotentes
Circuit breaker para o provedor de modelo
Idempotency-Key em operações pagas ou com side effect

Controle de custo

Reserve orçamento antes da chamada, registre tokens reais depois, exponga métricas por rota/modelo/tenant. Sem isso, o LLM vira fatura imprevisível.

Limitações

FastAPI não resolve grounding. Se a resposta precisa citar fontes, acrescente retrieval e validação. Se precisa de ações, acrescente harness — não apenas um endpoint /chat.