AI Router Stack#

Guida Operativa Completa per la configurazione e l'uso del sistema di routing AI multi-provider.

1. Panoramica#

AI Router Stack è un sistema di orchestrazione che permette di:

Unified Endpoint: Un solo endpoint per tutti i provider AI (Anthropic Claude, MiniMax, ecc.)
Smart Routing: Instradamento automatico basato su costi, latenza, disponibilita
Failover Intelligente: Fallback automatico in caso di errori o sovraccarichi
Risparmio Economico: Ottimizzazione dei costi tramite routing intelligente

Schema Base Il router funziona come proxy trasparente: le richieste arrivano sulla porta 8787 e vengono instradate al provider piu appropriato in base alla modalita configurata.

2. Architettura di Rete#

┌─────────────────────────────────────────────────────────────────────────────┐
│                           AI ROUTER STACK                                    │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                         PORTA 8787 (Unified)                         │    │
│  │              ┌──────────────────────────────┐                       │    │
│  │              │     Smart Router Engine      │                       │    │
│  │              │  ┌────────────────────────┐  │                       │    │
│  │              │  │  Modalita:             │  │                       │    │
│  │              │  │  - Anthropic (Pura)    │  │                       │    │
│  │              │  │  - MiniMax (Pura)      │  │                       │    │
│  │              │  │  - Mixed (Fallback)    │  │                       │    │
│  │              │  │  - Interactive         │  │                       │    │
│  │              │  └────────────────────────┘  │                       │    │
│  └──────────────┼──────────────────────────────┼───────────────────────┘    │
│                 │                              │                              │
│     ┌───────────┴───────────┐                  │                              │
│     │                       │                  │                              │
│     ▼                       ▼                  │                              │
│ ┌───────────┐         ┌───────────┐           │                              │
│ │  PORTA    │         │  PORTA    │           │                              │
│ │  8771     │         │  8772     │           │                              │
│ │           │         │           │           │                              │
│ │ Anthropic │         │ MiniMax   │           │                              │
│ │ Direct    │         │ Direct    │           │                              │
│ └───────────┘         └───────────┘           │                              │
│                                               │                              │
└─────────────────────────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────┐     ┌─────────────────┐
│  api.anthropic  │     │  api.minimax.io │
│  .com           │     │                 │
│                 │     │                 │
│  Claude Models  │     │  MiniMax Models │
└─────────────────┘     └─────────────────┘

Componenti

Componente	Porta	Descrizione
Unified Proxy	8787	Endpoint principale con routing intelligente
Anthropic Direct	8771	Accesso diretto solo Anthropic
MiniMax Direct	8772	Accesso diretto solo MiniMax
Health Check	8788	Endpoint per monitoraggio stato

3. Le Quattro Modalita di Routing#

3.1 Anthropic (Pura)#

Tutto il traffico viene instradato esclusivamente verso Anthropic Claude.

ANTHROPIC_API_KEY=sk-ant-...
ROUTING_MODE=anthropic

Caso d'uso: quando hai bisogno solo di Claude per ragioni di compatibilita o preferenza.

3.2 MiniMax (Pura)#

Tutto il traffico viene instradato esclusivamente verso MiniMax.

MINIMAX_API_KEY=eyJhbG...
ROUTING_MODE=minimax

Caso d'uso: ottimizzazione costi o test specifici su MiniMax.

3.3 Mixed (Fallback Bidirezionale)#

Routing con fallback automatico bidirezionale. Se un provider fallisce, l'altro subentra.

ANTHROPIC_API_KEY=sk-ant-...
MINIMAX_API_KEY=eyJhbG...
ROUTING_MODE=mixed
PRIMARY_PROVIDER=anthropic
FALLBACK_ENABLED=true

Logica di Failover

Richiesta → Provider Primario
                │
                ├─[OK]→ Risposta
                │
                └─[ERRORE]→ Fallback Provider
                              │
                              ├─[OK]→ Risposta
                              │
                              └─[ERRORE]→ Errore "Tutti i provider non disponibili"

3.4 Interactive (Intelligente)#

Routing basato su analisi del contenuto della richiesta e ottimizzazione costi.

ANTHROPIC_API_KEY=sk-ant-...
MINIMAX_API_KEY=eyJhbG...
ROUTING_MODE=interactive
COST_OPTIMIZATION=true
LATENCY_THRESHOLD_MS=2000

Criteri di selezione:

Complessita della richiesta
Costo per token del provider
Latenza attuale del provider
Stato di salute del provider

4. Cambiare Modalita Runtime#

4.1 Porta Dinamica (8787)#

La porta 8787 accetta comandi speciali per cambiare modalita al volo.

# Cambia modalita via curl
curl -X POST http://localhost:8787/mode \
  -H "Content-Type: application/json" \
  -d '{"mode": "minimax"}'

# Modalita disponibili: anthropic, minimax, mixed, interactive

Cambiamenti Temporanei I cambiamenti via API sono temporanei e si resettano al riavvio del servizio. Per persistenza, usa le variabili d'ambiente.

4.2 Porte Fisse (8771-8774)#

Porta	Provider	Modalita	Uso
8771	Anthropic	Diretta	Accesso esclusivo Anthropic
8772	MiniMax	Diretta	Accesso esclusivo MiniMax
8773	Mixed	Fallback	Primary Anthropic, Fallback MiniMax
8774	Interactive	Smart	Routing intelligente

5. Comandi In-Chat#

Puoi forzare il provider direttamente nei messaggi chat con comandi speciali.

# Claude Code: forza MiniMax
@minimax Scrivi un hello world in Python

# Forza Anthropic (default)
Scrivi un hello world in Python

# Forza fallback
@fallback:minimax Analizza questo codice

Sintassi Comandi @provider - forza provider specifico
@fallback:provider - usa come fallback dopo il primary

6. Health Check#

# Check completo
curl http://localhost:8788/health

# Risposta JSON
{
  "status": "ok",
  "providers": {
    "anthropic": {
      "status": "healthy",
      "latency_ms": 150,
      "quota_remaining": 45000
    },
    "minimax": {
      "status": "healthy",
      "latency_ms": 80,
      "quota_remaining": 120000
    }
  },
  "current_mode": "interactive",
  "uptime_seconds": 86400
}

Endpoint Specifici

# Solo Anthropic
curl http://localhost:8788/health/anthropic

# Solo MiniMax
curl http://localhost:8788/health/minimax

# Latenza
curl http://localhost:8788/health/latency

7. Esempi d'Uso#

7.1 Claude Code di Base#

Configurazione semplice per iniziare subito con routing automatico.

# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
MINIMAX_API_KEY=eyJhbGc...
ROUTING_MODE=interactive

# Avvio
docker-compose up -d

# Claude Code
claude-code --provider router

7.2 Sessioni Parallele con Backend Diversi#

# Terminale 1: Claude su Anthropic
ANTHROPIC_API_KEY=sk-ant-... claudia-code --port 8771

# Terminale 2: Claude su MiniMax
MINIMAX_API_KEY=eyJhbG... claude-code --port 8772

# Entrambi funzionano in parallelo!

7.3 Failover Automatico#

Configurazione per alta disponibilita con fallback automatico.

# .env - Alta Disponibilita
ANTHROPIC_API_KEY=sk-ant-...
MINIMAX_API_KEY=eyJhbG...
ROUTING_MODE=mixed
PRIMARY_PROVIDER=anthropic
FALLBACK_ENABLED=true
FALLBACK_DELAY_MS=500
MAX_RETRIES=3

# Il router tentera:
# 1. Anthropic (primary)
# 2. Se fallisce entro 500ms, MiniMax (fallback)
# 3. Se anche MiniMax fallisce, ritorna errore dopo 3 retry

7.4 Risparmio Intelligente#

Ottimizzazione costi usando Interactive mode con soglie.

# .env - Ottimizzazione Costi
ROUTING_MODE=interactive
COST_OPTIMIZATION=true
COST_THRESHOLD_CENTS=10
PREFER_CHEAPER=true

# Regole:
# - Richieste semplici (< 10 cent): MiniMax
# - Richieste complesse: Anthropic
# - Fallback automatico se un provider e in sovraccarico

8. Troubleshooting Rapido#

Problema	Soluzione
Connessione rifiutata	Verifica che il servizio sia in esecuzione: `docker ps \| grep router`
401 Unauthorized	Controlla che le API key siano corrette nel file .env
Timeout frequenti	Aumenta TIMEOUT_MS o verifica la connessione internet
Sempre stesso provider	Verifica la modalita con `curl localhost:8788/health`
Errore 429	Rate limit raggiunto. Attendi o aumenta i limiti con il provider

Log Debug

# Abilita log dettagliati
LOG_LEVEL=debug docker-compose up

# Cerca errori specifici
docker-compose logs | grep -i error

# Trace una richiesta specifica
docker-compose logs -f | grep "request-id-123"

9. Hardening e Resilienza (tripla difesa)#

Livello 1: Rate Limiting

# Limiti per provider
ANTHROPIC_RATE_LIMIT=100
MINIMAX_RATE_LIMIT=200
GLOBAL_RATE_LIMIT=150

Livello 2: Circuit Breaker

Il sistema chiude automaticamente il circuito verso un provider se:

5 errori consecutivi
Tasso di errore > 50% in 1 minuto
Latenza > 10 secondi

# Configurazione Circuit Breaker
CIRCUIT_BREAKER_THRESHOLD=5
CIRCUIT_BREAKER_TIMEOUT=60
CIRCUIT_BREAKER_RESET=300

Livello 3: Health Monitoring

# Check automatici
HEALTH_CHECK_INTERVAL=30
HEALTH_CHECK_ENDPOINT=/v1/models
AUTO_RECOVERY=true

Importante Non disattivare mai tutti e tre i livelli di difesa insieme. Questo espone il sistema a cascate di errori e costi non controllati.

10. Variabili d'Ambiente#

Variabile	Default	Descrizione
`ROUTING_MODE`	interactive	Modalita: anthropic, minimax, mixed, interactive
`ANTHROPIC_API_KEY`	-	Chiave API Anthropic
`MINIMAX_API_KEY`	-	Chiave API MiniMax
`PRIMARY_PROVIDER`	anthropic	Provider primario per mixed mode
`FALLBACK_ENABLED`	true	Abilita fallback automatico
`TIMEOUT_MS`	30000	Timeout per richiesta (ms)
`LOG_LEVEL`	info	Livello log: debug, info, warn, error
`PORT`	8787	Porta principale
`COST_OPTIMIZATION`	false	Abilita ottimizzazione costi
`CIRCUIT_BREAKER_THRESHOLD`	5	Errori prima di aprire circuito

11. Requisiti di Sistema#

Componente	Minimo	Raccomandato
CPU	1 core	2+ core
RAM	512 MB	1 GB
Docker	20.10+	24.0+
Docker Compose	2.0+	2.20+
Network	Stabile	Banda larga

Browser Supportati

Chrome/Edge 90+
Firefox 88+
Safari 14+

12. Cose da NON Fare#

NON Esportare API Key in Plain Text

Non commitare mai le API key su Git. Usa .env.example come template.

NON Disabilitare il Circuit Breaker in Produzione

Senza protezione, un provider guasto puo generare costi enormi.

NON Usare la Stessa API Key su Tutti i Backend

Mantieni le key separate per tracciare meglio i costi.

Anti-pattern da Evitare

No hardcoding: Usa sempre variabili d'ambiente
No retry infiniti: Imposta MAX_RETRIES
No logging di API key: Maschera sempre i valori sensibili
No timeout infinito: Limita sempre il tempo massimo