LiteLLM Proxy: 1 API per 100+ LLM (Setup Docker in 15 Minuti)

Configurazione del Proxy LiteLLM: Chiavi, Costi e Limiti di Velocità

Il tuo team condivide le chiavi API di OpenAI nei DM di Slack. Nessuno sa chi ha speso €400 martedì scorso. Non c'è limite di velocità, nessun fallback quando un provider cade, e passare da GPT-4o a Claude significa modificare il codice in dodici posti. Ti suona familiare? Un gateway LLM self-hosted risolve tutto questo, e il proxy LiteLLM è l'opzione open source più popolare -- un singolo endpoint compatibile con OpenAI che instrada le richieste a più di 100 provider LLM.

Questa guida copre la configurazione completa del proxy LiteLLM: Docker Compose con PostgreSQL, chiavi virtuali di team con budget, monitoraggio dei costi, limiti di velocità e collegamento di IDE AI come Claude Code e Cursor. Se stai valutando strumenti gateway LLM, questo è il tutorial pratico che ti porta da zero alla produzione.

Una nota importante prima di iniziare: l'SDK di LiteLLM (la libreria Python) e il Server Proxy sono cose diverse. L'SDK è per un singolo sviluppatore che chiama più API LLM da Python. Il proxy è per i team -- si siede come server tra le tue app e i provider LLM. Se sei uno sviluppatore singolo che scrive uno script, l'SDK è sufficiente. Se gestisci chiavi, budget e accessi per un team, hai bisogno del proxy. È quello che stiamo configurando qui.

Il Proxy LiteLLM in Sintesi

Ecco come si confrontano i metodi di deployment:

Per la maggior parte dei team, Docker Compose con PostgreSQL è il punto di equilibrio. È quello che costruiremo -- ma prima, facciamo girare un proxy in 60 secondi.

Prerequisiti e Configurazione dell'Ambiente

Prima di iniziare, assicurati di avere:

• Docker e Docker Compose installati (Docker Desktop include entrambi)
• Almeno una chiave API LLM (OpenAI, Anthropic o un'istanza locale di Ollama)
• Conoscenza base del terminale / CLI

Verifica che Docker sia pronto ed esporta le tue chiavi API:

# Controlla che Docker sia installato
docker --version
docker compose version

# Esporta le tue chiavi API LLM (aggiungi al tuo profilo shell per persistenza)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Opzionale: imposta una chiave master per il tuo proxy (ti servirà più avanti)
export LITELLM_MASTER_KEY="sk-master-la-tua-chiave-segreta"

Tutto qui. Nessuna versione speciale di Python, nessuno strumento specifico del sistema operativo. Se Docker gira sulla tua macchina, sei pronto.

Avvio Rapido -- Il Tuo Primo Proxy LiteLLM in 60 Secondi

Un comando per avviare un proxy con GPT-4o:

docker run -d \
  --name litellm-proxy \
  -p 4000:4000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e LITELLM_MASTER_KEY=$LITELLM_MASTER_KEY \
  ghcr.io/berriai/litellm:main-stable \
  --model openai/gpt-4o

Testa con curl:

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Say hello from LiteLLM"}]
  }'

O testa da Python:

from openai import OpenAI

# Punta l'SDK standard di OpenAI al tuo proxy
client = OpenAI(
    api_key="sk-master-la-tua-chiave-segreta",
    base_url="http://localhost:4000/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Say hello from LiteLLM"}]
)
print(response.choices[0].message.content)

Cosa è appena successo? Il tuo codice parla con localhost:4000 usando il formato SDK standard di OpenAI. Il proxy riceve la richiesta, la inoltra all'API di OpenAI con la chiave reale e restituisce la risposta. Il codice della tua applicazione non tocca mai la chiave API reale.

Questa è l'idea centrale. Ora costruiamo una configurazione di produzione.

Configurazione di Produzione con Docker Compose e PostgreSQL

Il singolo comando docker run funziona per i test, ma i team di produzione hanno bisogno di monitoraggio persistente dei costi, chiavi virtuali e storage su database appropriato. Questo significa Docker Compose con PostgreSQL.

Il File Docker Compose

# docker-compose.yml
version: "3.9"

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    container_name: litellm-proxy
    ports:
      - "4000:4000"         # Porta API proxy
    volumes:
      - ./config.yaml:/app/config.yaml   # Monta il tuo file di configurazione
    environment:
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://litellm:litellm_password@postgres:5432/litellm
      - LITELLM_SALT_KEY=${LITELLM_SALT_KEY:-sk-salt-random-string}
    command: --config /app/config.yaml --detailed_debug
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    container_name: litellm-db
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm_password
    volumes:
      - litellm_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  litellm_pgdata:

La LITELLM_SALT_KEY cifra i dati delle chiavi virtuali nel database. La documentazione sulle migliori pratiche di produzione LiteLLM raccomanda di impostarla per qualsiasi deployment di team.

Avvio dello Stack

# Crea un file .env con le tue chiavi (non committarlo su git)
echo "LITELLM_MASTER_KEY=sk-master-il-tuo-segreto" > .env
echo "OPENAI_API_KEY=sk-..." >> .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
echo "LITELLM_SALT_KEY=sk-salt-$(openssl rand -hex 16)" >> .env

# Avvia tutto
docker compose up -d

# Controlla i log
docker compose logs -f litellm

Verifica che Tutto Funzioni

# Controllo di salute
curl http://localhost:4000/health

# Testa una richiesta
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}]}'

Se vedi una risposta positiva, il tuo stack di produzione è in esecuzione. PostgreSQL archivia tutti i dati di costo, le chiavi virtuali e le metriche di utilizzo in modo persistente attraverso i riavvii dei container.

Verdetto: Docker Compose + PostgreSQL è la configurazione di produzione consigliata. Ti dà storage persistente, monitoraggio dei costi e chiavi virtuali con circa 10 minuti di lavoro. La documentazione di deployment Docker copre Kubernetes e Helm se hai bisogno di auto-scaling in seguito.

Spiegazione di Config.yaml -- Una Configurazione Reale Multi-Provider

La maggior parte dei tutorial mostra un config.yaml con un solo modello. Ecco come appare una vera configurazione di team con tre provider, fallback e bilanciamento del carico.

Il File di Configurazione

# config.yaml -- Configurazione reale multi-provider
model_list:
  # Principale: OpenAI GPT-4o
  - model_name: gpt-4o          # Il nome che usa IL TUO codice
    litellm_params:
      model: openai/gpt-4o      # Il provider/modello reale
      api_key: os.environ/OPENAI_API_KEY

  # Secondario: Anthropic Claude
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

  # Locale: Ollama per sviluppo / test senza costi
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3.1
      api_base: http://host.docker.internal:11434

  # Fallback: instrada "gpt-4o" verso Claude se OpenAI è giù
  - model_name: gpt-4o
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  routing_strategy: least-busy    # Bilancia il carico su modelli con lo stesso nome
  num_retries: 3
  retry_after: 5                  # Secondi tra i tentativi
  fallbacks: [{"gpt-4o": ["claude-sonnet"]}]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

Alias di Modelli e Routing

Nota che gpt-4o appare due volte nella configurazione -- una volta puntando a OpenAI, una volta ad Anthropic. Quando il tuo codice richiede gpt-4o, LiteLLM prova prima OpenAI. Se fallisce, l'impostazione fallbacks instrada automaticamente verso Claude. Il codice della tua applicazione non cambia affatto.

Se usi backend di inferenza in produzione come vLLM o SGLang, puoi aggiungerli nello stesso modo -- imposta semplicemente api_base al tuo server di inferenza.

Riferimento Rapido Provider

L'impostazione routing_strategy: least-busy distribuisce le richieste tra modelli con lo stesso model_name. Se hai due chiavi OpenAI (magari organizzazioni diverse con diversi limiti di velocità), elencale entrambe sotto gpt-4o e LiteLLM bilancia il carico.

Chiavi Virtuali -- Chiavi API per Team con Budget e Limiti di Velocità

Qui LiteLLM smette di essere "solo un proxy" e diventa uno strumento di gestione del team. Le chiavi virtuali ti permettono di dare a ogni membro del team o servizio la propria chiave API con limiti di spesa e tetti di velocità -- tutto instradato attraverso il tuo unico set di chiavi API del provider.

Creare una Chiave di Team con Budget

# Crea una chiave virtuale con un budget di $50/mese
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "frontend-team",
    "max_budget": 50.0,
    "budget_duration": "1mo",
    "models": ["gpt-4o", "claude-sonnet"],
    "metadata": {"purpose": "frontend AI features"}
  }'

La risposta ti dà una nuova chiave come sk-team-abc123.... Dala al team frontend. Possono usarla esattamente come una chiave OpenAI, ma è limitata a $50/mese e ha accesso solo ai modelli che hai specificato.

Impostare i Limiti di Velocità

# Crea una chiave con limiti di velocità: 100 richieste/minuto, 50K token/minuto
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "backend-team",
    "max_budget": 200.0,
    "budget_duration": "1mo",
    "rpm_limit": 100,
    "tpm_limit": 50000,
    "models": ["gpt-4o", "claude-sonnet", "local-llama"]
  }'

La documentazione delle chiavi virtuali copre ogni parametro. Puoi anche impostare budget e limiti di velocità per utente per un controllo ancora più granulare.

Monitorare l'Utilizzo delle Chiavi

import requests

# Controlla la spesa corrente e i limiti di una chiave
response = requests.get(
    "http://localhost:4000/key/info",
    headers={"Authorization": f"Bearer {MASTER_KEY}"},
    params={"key": "sk-team-abc123..."}
)
info = response.json()
print(f"Speso: ${info['spend']:.2f} / ${info['max_budget']:.2f}")
print(f"RPM usato: {info['rpm_limit_used']} / {info['rpm_limit']}")

Hai bisogno di revocare una chiave compromessa? Una chiamata API:

curl -X POST http://localhost:4000/key/delete \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["sk-team-abc123..."]}'

Verdetto: Le chiavi virtuali fanno di LiteLLM uno strumento di team, non solo un proxy personale. Senza di esse, stai solo aggiungendo un salto tra il tuo codice e l'LLM. Con esse, hai controllo degli accessi, applicazione del budget e attribuzione dell'utilizzo -- il tipo di cose che impediscono al tuo CFO di andare nel panico.

Monitoraggio dei Costi e la Dashboard LiteLLM

Una volta che PostgreSQL è connesso, LiteLLM traccia automaticamente il costo di ogni richiesta. Non devi configurare nulla -- conosce il prezzo per token per ogni modello supportato.

La Dashboard

Accedi all'interfaccia integrata su http://localhost:4000/ui (accedi con la tua chiave master). Vedrai:

• Spesa totale su tutti i team e le chiavi
• Suddivisione per modello -- quali modelli consumano il tuo budget
• Spesa per team -- chi usa cosa
• Volume di richieste nel tempo

Per i team seriosi sulla riduzione dei costi dell'API LLM, la dashboard da sola giustifica l'esecuzione del proxy. Puoi anche connettere LiteLLM a piattaforme esterne di osservabilità AI come Langfuse o Helicone per analisi più approfondite.

Confronto Costi per Provider

Ecco quanto costano i principali modelli per milione di token (aprile 2026):

Quando vedi questi numeri nella dashboard suddivisi per team, le conversazioni su "dovremmo usare un modello più economico per questo caso d'uso?" diventano molto concrete.

Verdetto: Il monitoraggio dei costi da solo giustifica il proxy per qualsiasi team che spende più di $100/mese in API LLM. Non puoi ottimizzare ciò che non puoi misurare.

Connettere gli IDE AI -- Claude Code, Cursor e Continue

Ecco qualcosa che la maggior parte delle guide LiteLLM salta completamente: puoi puntare anche i tuoi strumenti di codifica AI al proxy. Un proxy, tutti i tuoi strumenti IDE, fatturazione unificata.

Claude Code

# Imposta Claude Code per usare il tuo proxy LiteLLM
export ANTHROPIC_BASE_URL=http://localhost:4000/v1
export ANTHROPIC_API_KEY=sk-team-la-tua-chiave-virtuale

Tutto qui. Claude Code invia richieste al tuo proxy, che le instrada verso Anthropic (o dove dice la tua configurazione) mentre traccia i costi sotto la tua chiave virtuale.

Cursor

Nelle impostazioni di Cursor, aggiungi un endpoint personalizzato compatibile con OpenAI:

{
  "openai.apiBaseUrl": "http://localhost:4000/v1",
  "openai.apiKey": "sk-team-la-tua-chiave-virtuale"
}

Continue (VS Code)

Nel config.json di Continue:

{
  "models": [
    {
      "title": "GPT-4o via LiteLLM",
      "provider": "openai",
      "model": "gpt-4o",
      "apiBase": "http://localhost:4000/v1",
      "apiKey": "sk-team-la-tua-chiave-virtuale"
    }
  ]
}

Perché farlo? Perché ora l'utilizzo dell'IDE di ogni sviluppatore passa attraverso il proxy. Ottieni il monitoraggio dei costi per persona per gli assistenti di codifica AI, limiti di velocità in modo che nessuno bruci accidentalmente €500 in una sessione di codifica, e un unico posto per cambiare modello se trovi un'opzione migliore.

Risoluzione dei Problemi Comuni

"File di configurazione non trovato"

Di solito significa che il percorso di montaggio del volume è errato in Docker. Assicurati che il tuo config.yaml sia nella directory da cui stai montando:

# Controlla che il file esista dove pensi
ls -la ./config.yaml

# Il montaggio del volume in docker-compose.yml deve corrispondere
# volumes:
#   - ./config.yaml:/app/config.yaml

"Connessione rifiutata" a PostgreSQL

Il networking Docker prende tutti almeno una volta. Se LiteLLM non riesce a raggiungere Postgres, controlla che:

• Il nome del servizio in DATABASE_URL corrisponda al nome del servizio Docker Compose (postgres, non localhost)
• Il depends_on con condition: service_healthy sia impostato (in modo che LiteLLM aspetti che Postgres sia pronto)
• Entrambi i servizi siano sulla stessa rete Docker (lo sono per default in Compose)

"Formato chiave API non valido"

La confusione più comune: la tua LITELLM_MASTER_KEY è per le operazioni amministrative (creare chiavi virtuali, accedere alla dashboard). Le chiavi virtuali (sk-team-...) sono quelle che usano le tue applicazioni. Non confonderle.

"Modello non trovato"

Il campo model nella tua richiesta deve corrispondere a un model_name in config.yaml. Se la tua configurazione definisce gpt-4o ma il tuo codice richiede openai/gpt-4o, non corrisponderà. Controlla l'ortografia esatta.

Il proxy si avvia ma le richieste rimangono bloccate

Di solito un problema di firewall o di binding della porta. Verifica che la porta 4000 sia esposta e non bloccata:

# Controlla se la porta è in ascolto
docker port litellm-proxy
# Dovrebbe mostrare: 4000/tcp -> 0.0.0.0:4000

Sicurezza: Evita le Versioni 1.82.7 e 1.82.8

A marzo 2026, un incidente alla supply chain ha colpito le versioni LiteLLM 1.82.7 e 1.82.8. Le versioni compromesse sono state ritirate e una versione pulita è stata rilasciata a 1.83.0. Fissa sempre la tua immagine Docker a una versione specifica e controlla l'aggiornamento di sicurezza ufficiale prima di aggiornare. Se sei su 1.82.7 o 1.82.8, aggiorna immediatamente.

Quale Metodo di Configurazione LiteLLM Scegliere?

Se stai leggendo questa guida per la prima volta, inizia con Docker Compose + PostgreSQL. Puoi sempre migrare a Kubernetes in seguito -- il config.yaml rimane lo stesso.

FAQ

Cos'è il proxy LiteLLM e come funziona?

Il proxy LiteLLM è un server gateway AI open source che si siede tra le tue applicazioni e i provider LLM come OpenAI e Anthropic. Espone un singolo endpoint compatibile con OpenAI, quindi il tuo codice parla con un URL mentre il proxy gestisce routing, gestione delle chiavi, monitoraggio dei costi e fallback in background.

Come configuro il proxy LiteLLM con Docker Compose?

Crea un docker-compose.yml con l'immagine del proxy LiteLLM e un database PostgreSQL, monta il tuo config.yaml, imposta le tue chiavi API come variabili d'ambiente ed esegui docker compose up -d. La sezione "Configurazione di Produzione con Docker Compose" sopra contiene un file completo pronto da copiare e incollare.

Come gestisco le chiavi API del team con LiteLLM?

Usa le chiavi virtuali. Chiama l'endpoint /key/generate con la tua chiave master per creare chiavi per team o per utente. Ogni chiave virtuale può avere il proprio budget mensile, limiti di velocità (RPM e TPM) e restrizioni di accesso ai modelli. La sezione "Chiavi Virtuali" copre il flusso di lavoro completo.

Come aggiungo monitoraggio dei costi e limiti di velocità alla mia API LLM?

Connetti PostgreSQL al proxy (tramite DATABASE_URL) e il monitoraggio dei costi avviene automaticamente. Per i limiti di velocità, imposta rpm_limit e tpm_limit quando generi le chiavi virtuali. La dashboard integrata su /ui mostra la spesa per team e per modello.

Il proxy LiteLLM è sicuro da usare in produzione?

Sì, con una avvertenza: evita le versioni 1.82.7 e 1.82.8, che sono state colpite da un incidente alla supply chain a marzo 2026. Usa la versione 1.83.0 o successiva. Fissa la versione della tua immagine Docker, imposta la LITELLM_SALT_KEY per la crittografia e segui le migliori pratiche di produzione ufficiali.

Qual è la differenza tra l'SDK LiteLLM e il proxy LiteLLM?

L'SDK è una libreria Python per chiamare più API LLM dal tuo codice. Il proxy è un server autonomo a cui si connette tutto il tuo team. Usa l'SDK quando sei uno sviluppatore singolo che scrive uno script. Usa il proxy quando hai bisogno di controllo degli accessi condiviso, monitoraggio dei costi e limiti di velocità su un team.

Posso usare il proxy LiteLLM con Ollama e modelli locali?

Assolutamente. Aggiungi una voce al tuo config.yaml con model: ollama/llama3.1 e api_base: http://host.docker.internal:11434 (o il tuo host Ollama). Il tuo team può quindi accedere ai modelli locali attraverso lo stesso endpoint proxy, il che è ottimo per lo sviluppo e i test senza costi.

Quanto costa il proxy LiteLLM?

Il proxy LiteLLM è gratuito e open source (licenza MIT). Lo ospiti tu stesso sulla tua infrastruttura. Gli unici costi sono il tuo server (un piccolo VPS è sufficiente per la maggior parte dei team) e i costi API LLM che stai già pagando. BerriAI offre anche una versione cloud gestita se non vuoi fare self-hosting.

Quali provider supporta LiteLLM?

Oltre 100, tra cui OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Ollama, Hugging Face, Cohere, Replicate e molti altri. L'elenco completo è sul repository GitHub di LiteLLM.

Come aggiorno il proxy LiteLLM in modo sicuro?

Fissa sempre una versione specifica nel tag della tua immagine Docker (es. ghcr.io/berriai/litellm:v1.83.2-stable). Prima di aggiornare, controlla il changelog per le modifiche che possono causare rotture. Non usare mai latest in produzione. E verifica sempre che la nuova versione non sia nell'elenco degli avvisi di sicurezza -- l'incidente di marzo 2026 ha dimostrato che anche i pacchetti fidati possono essere compromessi.

Verdetto Finale e Prossimi Passi

Se il tuo team spende soldi in API LLM e non hai ancora un proxy, inizia oggi con Docker Compose + Postgres. La configurazione richiede 15 minuti, e avrai visibilità dei costi e controllo degli accessi alla fine.

Una volta in esecuzione, esplora l'aggiunta di guardrail alla tua pipeline LLM per il filtraggio dei contenuti e i controlli di sicurezza. Il proxy è la fondamenta -- tutto il resto si costruisce sopra.

Fonti

• Avvio Rapido del Proxy LiteLLM -- Documentazione ufficiale
• Guida al Deployment Docker di LiteLLM
• Documentazione Chiavi Virtuali LiteLLM
• Migliori Pratiche di Produzione LiteLLM
• Aggiornamento di Sicurezza LiteLLM -- Marzo 2026
• BerriAI/litellm -- Repository GitHub