MÓDULO 3.7

🌐 Multi-Provider Routing

4 provedores LLM, 3-tier routing, cost optimization, fallback strategies.

6
Tópicos
45
Minutos
Avançado
Nível
Operações
Tipo
1

🌐 Os 4 providers suportados

Ruflo não te prende a um único LLM. Quatro provedores nativos: Claude (Anthropic), GPT (OpenAI), Gemini (Google) e Ollama (local). Cada um tem força em algo diferente — você escolhe o melhor para cada tarefa, ou deixa o roteador decidir automaticamente.

🧠

Claude (Anthropic)

Reasoning profundo

Melhor para arquitetura, security review, planning complexo, análise de código longo. Sonnet é o sweet spot custo/benefício; Opus para casos críticos.

⚡

GPT (OpenAI)

Generalista forte

Bom em geração de código rápida, function calling robusto, ecossistema de tools maduro. Use para implementação iterativa.

🌈

Gemini (Google)

Context window enorme

1M+ tokens de contexto. Ideal para entender repositórios inteiros de uma vez, processar documentos massivos, análise multimodal.

🏠

Ollama (local)

Self-hosted, zero cost

Modelos open-source rodando na sua máquina. Llama, Mistral, DeepSeek. Use para dev/test, dados sensíveis que não podem sair, ou economizar em volume alto.

2

🚦 3-tier routing (ADR-026)

Ruflo usa 3 tiers de roteamento para decidir qual recurso processa cada tarefa. Tier 1 nem chama LLM — usa WASM. Tier 2 usa modelo barato. Tier 3 usa modelo top. A maioria das tarefas resolve em Tier 1 ou 2; só o difícil sobe para Tier 3.

🎯Tier 1 — Agent Booster (WASM)

  • •Latência: <1ms
  • •Custo: $0 (sem chamada LLM)
  • •Para: var→const, add types, format, lint fix, simple refactor
  • •Skip LLM entirely — transformações determinísticas resolvem direto

⚡Tier 2 — Haiku

  • •Latência: ~500ms
  • •Custo: $0.0002 por chamada típica
  • •Para: tarefas simples, complexity score <30%
  • •Exemplos: commit messages, classificação, summarização curta

🧠Tier 3 — Sonnet/Opus

  • •Latência: 2-5s
  • •Custo: $0.003-0.015 por chamada
  • •Para: complexity score >30%, reasoning, arquitetura, security
  • •Exemplos: design de sistema, debug profundo, refatoração cross-module
3

💰 Cost optimization

O roteador classifica cada tarefa pelo complexity score e direciona para o tier mais econômico que resolve. Score <30% vai pra Haiku ($0.0002), score >30% vai pra Opus ($0.015). Diferença prática: 75x mais barato em tarefas simples.

✓ Score baixo (<30%)

  • ✓Renomear variável
  • ✓Gerar commit message
  • ✓Classificar issue
  • ✓Format JSON
  • ✓Add error handling simples
  • ✓→ Haiku ou Tier 1

✓ Score alto (>30%)

  • ✓Design de schema
  • ✓Refactor cross-module
  • ✓Security audit
  • ✓Debug bug intermitente
  • ✓Plan de migração
  • ✓→ Sonnet ou Opus

💡Economia real

Em projetos reais com Ruflo, ~70% das chamadas resolvem em Tier 1 ou 2. Resultado: economia de 60-80% no gasto LLM mantendo qualidade equivalente.

4

🔄 Fallback strategies

Quando provider primário fica indisponível ou sobrecarregado, o roteador faz fallback automático. Você não interrompe o swarm — graceful degradation acontece transparente. Pediu Sonnet, mas Anthropic está com 503? Cai pra Gemini ou GPT equivalente.

🔁Cadeia de fallback típica

  1. Tentativa 1: provider primário (ex: Claude Sonnet)
  2. Tentativa 2: retry com backoff exponencial
  3. Tentativa 3: fallback para provider equivalente (ex: GPT-4o)
  4. Tentativa 4: tier inferior se ainda falhar (ex: Haiku)
  5. Tentativa 5: Ollama local como último recurso

📊Graceful degradation

Fallback nunca é silencioso — é logado e reportado. Você sabe quando o swarm rodou em modo degradado, que provider foi usado, quantas tentativas foram feitas. Essencial para SLA e billing accuracy.

5

⚙️ Configuration

Setup multi-provider acontece via comando providers. Você adiciona credenciais (sempre via env vars, nunca hardcoded), testa conexão, e configura prioridades. Tudo persistido em config — vai pro git via dotfiles, não via secrets.

🛠️Comandos providers

Listar providers configurados:

npx claude-flow@v3alpha providers list

Adicionar Claude:

npx claude-flow@v3alpha providers add anthropic \
  --api-key-env ANTHROPIC_API_KEY

Adicionar Gemini:

npx claude-flow@v3alpha providers add google \
  --api-key-env GOOGLE_API_KEY

Testar conexão:

npx claude-flow@v3alpha providers test --all

Configurar prioridades:

npx claude-flow@v3alpha providers configure \
  --primary anthropic \
  --fallback google,openai,ollama

⚠️Atenção

Nunca passe --api-key direto na CLI — fica no shell history. Use sempre --api-key-env apontando para variável de ambiente carregada via .env (que está no .gitignore).

6

📊 Provider metrics

Decisão de provider é data-driven, não dogma. Ruflo coleta métricas por provider — latência p50/p95/p99, success rate, custo por chamada, tokens por requisição. Você compara performance real e ajusta prioridades baseado no seu workload.

📈Métricas coletadas

  • •Latência — tempo de primeira resposta e tempo total (p50, p95, p99)
  • •Cost — custo por chamada e custo agregado por dia/semana/mês
  • •Success rate — % de requisições que retornaram com sucesso
  • •Tokens — input/output por requisição, média por agente
  • •Fallback rate — quantas vezes o primário falhou

🔍Comando metrics

npx claude-flow@v3alpha performance metrics \
  --filter providers \
  --window 7d \
  --output table

💡Decisão data-driven

Após uma semana de uso, exporte as métricas e compare. Talvez Gemini esteja sendo 2x mais rápido que Sonnet no seu workload e suficiente em qualidade — vale trocar a primária. Sem dados, é só achismo.

📋Resumo do Módulo

✓
4 providers — Claude, GPT, Gemini, Ollama com forças complementares
✓
3-tier routing — WASM <1ms / Haiku 500ms / Sonnet 2-5s
✓
Cost optimization — Score <30% = Haiku, >30% = Opus. Economia 60-80%
✓
Fallback — Cadeia automática + graceful degradation
✓
Configuration — providers add/test/configure via env vars
✓
Metrics — Latência, cost, success rate por provider

Próximo Módulo:

3.8 - Produção: Deploy, CI/CD & Observabilidade (módulo final)

← Voltar para Trilha Próximo Módulo →