Pipeline LLM com Consciência de Custos

O que Pipeline LLM com Consciência de Custos faz?

Padrões para controlar custos de APIs LLM mantendo a qualidade. Combina roteamento de modelos, rastreamento de orçamento, lógica de repetição e cache de prompts em um pipeline componível.

Quando Ativar

• Construindo aplicações que chamam APIs LLM (Claude, GPT, etc.)
• Processando lotes de itens com complexidade variável
• Necessidade de permanecer dentro de um orçamento para gastos com API
• Otimizando custos sem sacrificar a qualidade em tarefas complexas

Conceitos Principais

1. Roteamento de Modelos por Complexidade da Tarefa

Selecionar automaticamente modelos mais baratos para tarefas simples, reservando modelos caros para as complexas.

MODEL_SONNET = "claude-sonnet-5"
MODEL_HAIKU = "claude-haiku-4-5-20251001"

_SONNET_TEXT_THRESHOLD = 10_000  # caracteres
_SONNET_ITEM_THRESHOLD = 30      # itens

def select_model(
    text_length: int,
    item_count: int,
    force_model: str | None = None,
) -> str:
    """Seleciona modelo baseado na complexidade da tarefa."""
    if force_model is not None:
        return force_model
    if text_length >= _SONNET_TEXT_THRESHOLD or item_count >= _SONNET_ITEM_THRESHOLD:
        return MODEL_SONNET  # Tarefa complexa
    return MODEL_HAIKU  # Tarefa simples (3-4x mais barato)

2. Rastreamento Imutável de Custos

Rastrear gastos acumulados com dataclasses congeladas. Cada chamada de API retorna um novo rastreador — nunca muta o estado.

from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class CostRecord:
    model: str
    input_tokens: int
    output_tokens: int
    cost_usd: float

@dataclass(frozen=True, slots=True)
class CostTracker:
    budget_limit: float = 1.00
    records: tuple[CostRecord, ...] = ()

    def add(self, record: CostRecord) -> "CostTracker":
        """Retorna novo rastreador com o registro adicionado (nunca muta self)."""
        return CostTracker(
            budget_limit=self.budget_limit,
            records=(*self.records, record),
        )

    @property
    def total_cost(self) -> float:
        return sum(r.cost_usd for r in self.records)

    @property
    def over_budget(self) -> bool:
        return self.total_cost > self.budget_limit

3. Lógica de Repetição Restrita

Repetir apenas em erros transitórios. Falhar rapidamente em erros de autenticação ou requisição inválida.

from anthropic import (
    APIConnectionError,
    InternalServerError,
    RateLimitError,
)

_RETRYABLE_ERRORS = (APIConnectionError, RateLimitError, InternalServerError)
_MAX_RETRIES = 3

def call_with_retry(func, *, max_retries: int = _MAX_RETRIES):
    """Repetir apenas em erros transitórios, falhar rapidamente nos outros."""
    for attempt in range(max_retries):
        try:
            return func()
        except _RETRYABLE_ERRORS:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Backoff exponencial
    # AuthenticationError, BadRequestError etc. → levanta imediatamente

4. Cache de Prompts

Armazenar em cache prompts de sistema longos para evitar reenviá-los em cada requisição.

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": system_prompt,
                "cache_control": {"type": "ephemeral"},  # Armazenar em cache
            },
            {
                "type": "text",
                "text": user_input,  # Parte variável
            },
        ],
    }
]

Composição

Combinar todas as quatro técnicas em uma única função de pipeline:

def process(text: str, config: Config, tracker: CostTracker) -> tuple[Result, CostTracker]:
    # 1. Roteamento do modelo
    model = select_model(len(text), estimated_items, config.force_model)

    # 2. Verificar orçamento
    if tracker.over_budget:
        raise BudgetExceededError(tracker.total_cost, tracker.budget_limit)

    # 3. Chamada com repetição + cache
    response = call_with_retry(lambda: client.messages.create(
        model=model,
        messages=build_cached_messages(system_prompt, text),
    ))

    # 4. Rastrear custo (imutável)
    record = CostRecord(model=model, input_tokens=..., output_tokens=..., cost_usd=...)
    tracker = tracker.add(record)

    return parse_result(response), tracker

Referência de Preços (2026)

Modelo	Entrada ($/1M tokens)	Saída ($/1M tokens)	Custo Relativo
Haiku 3.5 (legado)	$0.80	$4.00	0.8x
Haiku 4.5	$1.00	$5.00	1x
Sonnet 5	$2.00	$10.00	2x
Sonnet 4.6	$3.00	$15.00	3x
Opus 4.8	$5.00	$25.00	5x
Fable 5 / Mythos 5	$10.00	$50.00	10x
Opus 4.0 / 4.1 (legado)	$15.00	$75.00	15x

Melhores Práticas

• Comece com o modelo mais barato e só roteie para modelos caros quando os limites de complexidade forem atingidos
• Defina limites de orçamento explícitos antes de processar lotes — falhe cedo em vez de gastar demais
• Registre as decisões de seleção de modelo para poder ajustar os limites com base em dados reais
• Use cache de prompts para prompts de sistema com mais de 1024 tokens — economiza custo e latência
• Nunca repita em erros de autenticação ou validação — apenas em falhas transitórias (rede, limite de taxa, erro de servidor)

Antipadrões a Evitar

• Usar o modelo mais caro para todas as requisições, independentemente da complexidade
• Repetir em todos os erros (desperdiça orçamento em falhas permanentes)
• Mutar o estado de rastreamento de custos (dificulta depuração e auditoria)
• Codificar nomes de modelos diretamente no código (use constantes ou configuração)
• Ignorar cache de prompts para prompts de sistema repetitivos

Quando Usar

• Qualquer aplicação que chame Claude, OpenAI ou APIs LLM similares
• Pipelines de processamento em lote onde o custo se acumula rapidamente
• Arquiteturas com múltiplos modelos que precisam de roteamento inteligente
• Sistemas de produção que precisam de limites de orçamento