LiteLLM: una guida con esempi pratici

Passare da un provider LLM all’altro non dovrebbe costringerti a riscrivere tutta la codebase. Ma è esattamente quello che succede oggi quando lavori con più servizi di IA. Ogni provider ha il suo SDK, il suo metodo di autenticazione e il suo formato di risposta. LiteLLM risolve il problema con un’interfaccia unificata.

In questo tutorial ti spiegherò le parti principali di LiteLLM e ti mostrerò come iniziare con chiamate API di base fino ad arrivare a risposte in streaming, output strutturati e tracciamento dei costi.

Cos’è LiteLLM?

LiteLLM è una libreria Python open source che funziona come un traduttore universale per modelli di IA. Invece di imparare API diverse per ogni provider, usi un’unica interfaccia che si collega a oltre 100 servizi LLM.

Il framework ha due componenti principali. L’SDK Python ti permette di scrivere il codice una volta e farlo girare con qualsiasi provider. Il proxy server agisce da gateway centrale per team e aziende che devono gestire servizi di IA su larga scala.

LiteLLM ti offre anche questi vantaggi:

• Tracciamento dei costi integrato: visualizza la spesa su tutti i provider in un’unica dashboard invece di controllare più sistemi di fatturazione
• Failover automatici: quando un provider ha un down o raggiunge i rate limit, LiteLLM prova automaticamente le tue opzioni di backup
• Opzione self-hosted: esegui tutto sui tuoi server se hai esigenze di privacy o conformità dei dati

Nota che OpenRouter offre un accesso unificato simile a più LLM, anche se con prezzi e set di funzionalità diversi.

Il proxy server aggiunge limiti di spesa per team, tracciamento dell’uso tra progetti e gestione centralizzata delle chiavi API. Tutta la configurazione avviene tramite semplici file YAML.

LiteLLM funziona bene per diversi tipi di utenti:

• Sviluppatori individuali che vogliono testare più modelli senza aprire account ovunque
• Piccoli team che hanno bisogno di visibilità sui costi e non vogliono il vendor lock-in
• Grandi aziende che richiedono gestione centralizzata, controllo dei budget e analisi dettagliate dell’uso

La libreria è sotto licenza MIT ed è completamente open source. Puoi ispezionare il codice, modificarlo per le tue esigenze o contribuire al progetto.

Ora che sai cosa può fare LiteLLM, ecco come impostare il tuo ambiente.

Prerequisiti

Prima di iniziare a usare LiteLLM, devi configurare alcune cose. Se hai già lavorato con modelli di IA, probabilmente la maggior parte è già a posto.

Ambiente Python

Ti serve Python 3.7 o superiore. Oggi quasi tutti i sistemi lo hanno, ma puoi controllare la versione con:

import sys
print(f"Python version: {sys.version_info.major}.{sys.version_info.minor}")

Installazione pacchetti

Installa LiteLLM e python-dotenv per gestire le variabili d’ambiente:

uv add litellm python-dotenv
# or with pip: pip install litellm python-dotenv

Chiavi API

Ti serviranno le chiavi API dei provider che vuoi usare. In questo tutorial lavoreremo con due modelli:

• Chiave API OpenAI: puoi ottenere una chiave da platform.openai.com (per GPT-5)
• Chiave API Anthropic: puoi ottenere una chiave da console.anthropic.com (per Claude Sonnet 4)

Salvale in un file .env nella directory del tuo progetto:

OPENAI_API_KEY=your_openai_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here

Verifica dell’ambiente

Esegui questo script per controllare la configurazione:

import os
import sys
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Check Python version
print(f"Python version: {sys.version_info.major}.{sys.version_info.minor}")

# Check LiteLLM
try:
   import litellm
   print("✓ LiteLLM installed")
except ImportError:
   print("✗ LiteLLM not installed")

# Check API keys
openai_key = os.getenv("OPENAI_API_KEY")
anthropic_key = os.getenv("ANTHROPIC_API_KEY")

if openai_key:
   print(f"✓ OpenAI API key found")
else:
   print("✗ OpenAI API key not found")

if anthropic_key:
   print(f"✓ Anthropic API key found")
else:
   print("✗ Anthropic API key not found")

Python version: 3.11
✓ LiteLLM installed
✓ OpenAI API key found
✓ Anthropic API key found

Se vedi tutte le spunte verdi, sei pronto. Se qualche controllo fallisce, assicurati di aver installato i pacchetti e aggiunto le chiavi API al file .env.

La tua prima chiamata API con LiteLLM

LiteLLM usa la stessa interfaccia che forse conosci da OpenAI, ma funziona con qualsiasi provider.

Configurazione di base

Inizia con questi import:

import litellm
from dotenv import load_dotenv

# Load your API keys
load_dotenv()

Una richiesta di base a GPT-5 segue questo schema: definisci i messaggi, chiama litellm.completion() e ottieni la risposta.

messages = [
   {"role": "user", "content": "Write a simple Python function that adds two numbers"}
]

response = litellm.completion(
   model="gpt-5",
   messages=messages
)

print(response.choices[0].message.content)

def add(a, b):
   """Return the sum of a and b."""
   return a + b

Hai appena chiamato GPT-5 tramite LiteLLM. L’oggetto di risposta segue il formato di OpenAI, quindi se hai già usato la loro API ti sembrerà familiare. Potresti voler ispezionare quale modello ha effettivamente risposto e controllare l’uso di token:

print(f"Model used: {response.model}")
print(f"Response ID: {response.id}")
print(f"Total tokens: {response.usage.total_tokens}")

Model used: gpt-5-2025-08-07
Response ID: chatcmpl-CIbZWUDE1amW2vHtHDmieTX6hnZUq
Total tokens: 557

Cambio di provider

La vera forza di LiteLLM emerge quando cambi provider. Vuoi provare Claude Sonnet 4 invece? Cambia un parametro:

response = litellm.completion(
   model="anthropic/claude-sonnet-4-20250514",
   messages=messages
)

print(response.choices[0].message.content)

Here's a simple Python function that adds two numbers:

def add_numbers(a, b):
   """
   Adds two numbers and returns the result.
  
   Args:
       a: First number
       b: Second number
  
   Returns:
       The sum of a and b
   """
   return a + b

# Example usage:
result = add_numbers(5, 3)
print(result)  # Output: 8

This function:
- Takes two parameters a and b
- Returns their sum using the + operator
- Works with integers, floats, and even negative numbers
- Includes a docstring to explain what the function does

Stessa struttura di codice, provider diverso. Claude offre una risposta molto più dettagliata con documentazione ed esempi, mentre GPT-5 è stato più conciso.

Gestione errori di base

Aggiungi un po’ di gestione degli errori per quando qualcosa va storto:

try:
   response = litellm.completion(
       model="gpt-5",
       messages=messages
   )
   print(response.choices[0].message.content)
except Exception as e:
   print(f"API call failed: {e}")

Questo schema intercetta problemi comuni come chiavi API non valide, problemi di rete o indisponibilità del modello.

E adesso?

Ora conosci lo schema base per usare LiteLLM con qualsiasi provider. La documentazione Getting Started copre più dettagli su modelli e parametri supportati, e la reference della funzione Completion mostra tutte le opzioni disponibili.

Per costruire applicazioni di produzione, vorrai anche seguire le best practice di progettazione delle API per creare sistemi affidabili e ad alte prestazioni.

Cambio provider e fallback

Il sistema di fallback di LiteLLM gestisce automaticamente i problemi dei provider così i tuoi utenti non vedono mai messaggi di errore. Quando costruisci applicazioni reali, ti servono piani di backup che funzionino senza codice extra da parte tua.

Configurazione di fallback base

Per impostare un fallback, aggiungi una lista fallbacks alla tua chiamata di completion:

messages = [
   {"role": "user", "content": "Explain what a Python decorator is in one sentence"}
]

response = litellm.completion(
   model="gpt-5",
   messages=messages,
   fallbacks=["anthropic/claude-sonnet-4-20250514"]
)

print(f"Response: {response.choices[0].message.content}")
print(f"Model used: {response.model}")

Response: A Python decorator is a callable that wraps another function or class to augment its behavior and returns it, applied with the @ syntax so you can add reusable functionality without changing the original code.
Model used: gpt-5-2025-08-07

Se GPT-5 fallisce, LiteLLM prova automaticamente Claude Sonnet 4. In ogni caso, gli utenti ricevono una risposta.

Costruire catene di fallback

Puoi concatenare più provider per maggiore affidabilità. Usando gli stessi messaggi di prima:

response = litellm.completion(
   model="gpt-5",
   messages=messages,
   fallbacks=["anthropic/claude-sonnet-4-20250514", "gpt-3.5-turbo"]
)

print(f"Model used: {response.model}")

Model used: gpt-5-2025-08-07

LiteLLM prova i modelli in ordine. Se quello primario fallisce, prova il primo fallback. Se fallisce anche quello, prova il secondo. Più livelli di protezione.

Aggiungere retry

Combina fallback e retry per un’affidabilità ancora migliore:

response = litellm.completion(
   model="gpt-5",
   messages=messages,  # Same messages as before
   num_retries=2
)

Ritenta lo stesso modello due volte prima di passare ai fallback. Utile per problemi di rete temporanei o picchi di rate limit.

I fallback gestiscono automaticamente la maggior parte dei fallimenti, ma dovresti comunque intercettare i casi in cui tutti i modelli falliscono:

try:
   response = litellm.completion(
       model="gpt-5",
       messages=messages,  # Same messages as before
       fallbacks=["anthropic/claude-sonnet-4-20250514"],
       num_retries=2
   )
   return response.choices[0].message.content
except Exception as e:
   # All models failed - handle gracefully
   return "Sorry, I'm having trouble right now. Please try again."

Anche quando i provider funzionano perfettamente, gli utenti affrontano comunque un altro problema: l’attesa frustrante. Qualcuno clicca invia nella tua app e non vede nulla per alcuni secondi. Si chiede se si sia rotto qualcosa.

Streaming per risposte in tempo reale

La maggior parte delle risposte delle API di IA arriva come un blocco completo, come scaricare un file. Gli utenti aspettano senza feedback finché l’intera risposta non è pronta. Lo streaming cambia questo mostrando il testo man mano che viene generato, parola per parola.

Perché lo streaming cambia l’esperienza utente

Invece di aspettare la risposta completa, lo streaming mostra il testo mentre l’IA lo genera. Guarda la differenza:

import litellm
from dotenv import load_dotenv

load_dotenv()

messages = [{"role": "user", "content": "What is Python in one sentence?"}]

response = litellm.completion(
   model="gpt-5",
   messages=messages,
   stream=True
)

for chunk in response:
   if chunk.choices[0].delta.content:
       print(chunk.choices[0].delta.content, end="", flush=True)

Python is a high-level, interpreted, dynamically typed, general-purpose programming language known for its readability and vast ecosystem, used across web development, data science, automation, scripting, and more.

Il testo appare gradualmente invece che tutto in una volta (quando esegui lo snippet sopra sulla tua macchina). Gli utenti vedono subito i progressi, il che risulta molto più reattivo che fissare una rotellina di caricamento.

Come funziona davvero lo streaming

Funziona a livello di chunk. Invece di una grande risposta, ricevi molti piccoli pezzi, chiamati delta. A volte i chunk sono vuoti, quindi dovresti gestirli correttamente per sicurezza:

response = litellm.completion(
   model="anthropic/claude-sonnet-4-20250514",
   messages=[{"role": "user", "content": "Define JavaScript in exactly two sentences"}],
   stream=True
)

for chunk in response:
   if hasattr(chunk.choices[0].delta, 'content') and chunk.choices[0].delta.content:
       print(f"'{chunk.choices[0].delta.content}'", end=" ")

'JavaScript is a high' '-level, interpreted programming language primarily used for creating' ' interactive and dynamic content on web pages, running' ' in web browsers to manip' 'ulate HTML elements, handle user events' ', and communicate with servers.' ' Originally designed for client-side web development, JavaScript has evolve' 'd into a versatile language that can also' ' be used for server-side development, mobile applications' ', and desktop software through various runtime' ' environments like Node.js.'

Rendere riutilizzabile lo streaming

Per applicazioni reali, vorrai catturare la risposta completa pur mostrando l’output in streaming. Ecco una funzione per farlo:

def stream_and_capture(model, messages):
   """Stream response while capturing the complete text"""
   response = litellm.completion(
       model=model,
       messages=messages,
       stream=True
   )
  
   full_response = ""
   for chunk in response:
       if chunk.choices[0].delta.content:
           content = chunk.choices[0].delta.content
           print(content, end="", flush=True)
           full_response += content
  
   print()  # New line after response
   return full_response

# Test it
messages = [{"role": "user", "content": "Define APIs in 2 sentences max"}]
result = stream_and_capture("gpt-5", messages)

APIs (Application Programming Interfaces) are standardized contracts, often exposed as endpoints, that specify how software components or services can communicate, including the allowed operations, inputs, and outputs. They let developers access functionality or data without knowing the underlying implementation, enabling modular, interoperable systems.

Il parametro end="" evita le interruzioni di riga tra i chunk. flush=True forza la visualizzazione immediata invece del buffering.

Streaming con fallback

Puoi anche combinare lo streaming con il sistema di fallback per maggiore affidabilità:

response = litellm.completion(
   model="gpt-5",
   messages=[{"role": "user", "content": "Define machine learning in one sentence"}],
   fallbacks=["anthropic/claude-sonnet-4-20250514"],
   stream=True
)

for chunk in response:
   if chunk.choices[0].delta.content:
       print(chunk.choices[0].delta.content, end="", flush=True)

Machine learning is a branch of artificial intelligence where algorithms learn patterns from data to make predictions or decisions without being explicitly programmed.

Feedback immediato più cambio automatico di provider se il modello primario fallisce.

Lo streaming offre feedback immediato, ma rimane un altro problema quando costruisci applicazioni reali. Una volta arrivato il testo, il tuo codice deve lavorarci. Potresti estrarre dati, salvare informazioni in database o passare valori ad altre funzioni. Ma effettuare il parsing di risposte testuali è complicato e si rompe facilmente quando cambia il formato.

Uso di output strutturati

Ecco cosa succede davvero: costruisci un’app che analizza i feedback dei clienti. La tua IA restituisce testo come “Il sentiment è positivo con confidenza 0,85 e le principali keyword: reattivo, disponibile, veloce.” Scrivi regex per estrarre il punteggio di confidenza e le keyword. In test funziona tutto.

Poi l’IA cambia leggermente formato in “Sentiment: positivo (confidenza: 0,85). Le keyword includono reattivo, disponibile e veloce.” Le tue regex si rompono. La pipeline dati smette di funzionare. I report sul sentiment mostrano valori vuoti al posto dei punteggi. La dashboard va in crash. Passi ore a correggere parsing che funzionava ieri.

Gli output strutturati evitano il problema restituendo dati in formati prevedibili fin dall’inizio.

Ottenere JSON invece di testo

LiteLLM può restituire JSON al posto di semplice testo. Indichi nella prompt quale struttura desideri e ottieni la risposta già formattata correttamente:

import litellm
from dotenv import load_dotenv

load_dotenv()

messages = [{"role": "user", "content": "Describe Python as a programming language. Return as JSON with fields: language, difficulty, description"}]

response = litellm.completion(
   model="gpt-5",
   messages=messages,
   response_format={"type": "json_object"}
)

print(response.choices[0].message.content)

{
 "language": "Python",
 "difficulty": "Beginner-friendly (easy to learn, moderate to master)",
 "description": "Python is a high-level, interpreted, dynamically typed, general-purpose programming language focused on readability and developer productivity. It supports multiple paradigms (object-oriented, functional, procedural), uses indentation for block structure, and includes a large standard library with an extensive third-party ecosystem (PyPI). Common uses include web development, data science, machine learning, automation/scripting, scientific computing, and DevOps. While not the fastest for CPU-bound tasks, it integrates well with C/C++ and accelerators, and runs cross-platform."
}

Questo approccio strutturato elimina i tipici problemi di parsing. Invece di cercare informazioni nel testo, ricevi JSON valido con esattamente i campi richiesti. Niente mal di testa da parsing, niente sorprese di formato.

Lavorare con i dati JSON

Le stringhe JSON grezze non sono utili finché non le converti in oggetti Python con cui la tua applicazione può lavorare. Devi trasformare quella stringa in oggetti Python realmente utilizzabili:

import json

messages = [{"role": "user", "content": "Describe JavaScript in 2 sentences. Return as JSON with fields: name, paradigm, use_cases (array of exactly 3 items)"}]

response = litellm.completion(
   model="anthropic/claude-sonnet-4-20250514",
   messages=messages,
   response_format={"type": "json_object"}
)

# Parse the JSON response
data = json.loads(response.choices[0].message.content)
print(f"Language: {data['name']}")
print(f"Paradigm: {data['paradigm']}")
print(f"Use cases: {', '.join(data['use_cases'])}")

Language: JavaScript
Paradigm: multi-paradigm (object-oriented, functional, event-driven)
Use cases: web development and browser scripting, server-side development with Node.js, mobile app development with frameworks like React Native

Ora che hai dati strutturati, puoi passarli direttamente ad altre funzioni, salvarli nei database o mostrarli nella tua UI senza alcuna manipolazione testuale. Per flussi di analisi dati, strumenti come Pandas AI possono lavorare direttamente con questo output strutturato per generare insight.

Aggiungere type safety con Pydantic

Il parsing JSON intercetta gli errori di sintassi, ma tipi di dato sbagliati o campi mancanti sono un altro problema. I modelli Pydantic lo risolvono convalidando la struttura dei dati e intercettando i problemi prima che rompano l’applicazione:

from pydantic import BaseModel
import json

class ProgrammingLanguage(BaseModel):
   name: str
   paradigm: str
   use_cases: list[str]

messages = [{"role": "user", "content": "Describe CSS briefly. Return as JSON with fields: name, paradigm, use_cases (array of 3 items)"}]

response = litellm.completion(
   model="gpt-5",
   messages=messages,
   response_format={"type": "json_object"}
)

# Parse and validate with Pydantic
data = json.loads(response.choices[0].message.content)
language = ProgrammingLanguage(**data)

print(f"Validated data: {language.name} - {language.paradigm}")
print(f"Use cases: {language.use_cases}")

Validated data: CSS (Cascading Style Sheets) - Declarative, rule-based stylesheet language for describing the presentation of structured documents.
Use cases: ['Styling layout, colors, and typography of web pages', 'Responsive design across devices and viewports', 'Animations, transitions, and visual effects']

Pydantic convalida automaticamente che name e paradigm siano stringhe, e che use_cases sia una lista di stringhe. Se l’IA restituisce tipi errati o dimentica un campo obbligatorio, otterrai un errore chiaro invece di bug misteriosi più avanti.

Gestire errori JSON

Il parsing JSON può fallire se l’IA restituisce JSON malformato o testo non JSON. Aggiungi una gestione errori di base:

import json

messages = [{"role": "user", "content": "Summarize machine learning in 1 sentence. Return as JSON with topic and summary fields"}]

try:
   response = litellm.completion(
       model="anthropic/claude-sonnet-4-20250514",
       messages=messages,
       response_format={"type": "json_object"}
   )
  
   data = json.loads(response.choices[0].message.content)
   print(f"Topic: {data['topic']}")
   print(f"Summary: {data['summary']}")
  
except json.JSONDecodeError:
   print("Invalid JSON returned")
except Exception as e:
   print(f"Request failed: {e}")

Topic: machine learning
Summary: Machine learning is a subset of artificial intelligence that allows computers to learn and make predictions or decisions from data without being explicitly programmed for each specific task.

Gli output strutturati sostituiscono parsing disordinati del testo con strutture dati pulite. Puoi combinare la modalità JSON con i fallback proprio come le completion normali.

Gli output strutturati ti danno dati puliti e prevedibili che non romperanno la tua logica di parsing. Ma c’è un altro problema che emerge quando passi dal prototipo alla produzione: le bollette. Ogni chiamata API costa, e quei costi possono sorprenderti.

Tracciamento dei costi

Ecco cosa succede: il tuo prototipo funziona benissimo in test con 50 chiamate API al giorno. Spendendo circa 2$ a settimana. Sembra tutto ok. Lanci in produzione e ottieni 500 utenti. Ora fai 5.000 chiamate API al giorno. La tua bolletta mensile passa da 8$ a 800$.

Senza tracciamento dei costi, non avevi alcun preavviso. Non puoi capire quali funzionalità costano di più, quali modelli sono più cari o come pianificare il budget per la crescita. Scopri l’impennata del conto settimane dopo, quando arriva l’estratto conto della carta.

LiteLLM traccia esattamente quanto spendi su tutti i provider.

Capire l’uso dei token

Ogni risposta dell’IA include informazioni dettagliate sull’uso che mostrano esattamente ciò per cui vieni addebitato:

import litellm
from dotenv import load_dotenv

load_dotenv()

messages = [{"role": "user", "content": "Explain what a REST API is in two sentences"}]

response = litellm.completion(
   model="gpt-5",
   messages=messages
)

print(f"Response: {response.choices[0].message.content}")
print(f"Prompt tokens: {response.usage.prompt_tokens}")
print(f"Completion tokens: {response.usage.completion_tokens}")
print(f"Total tokens: {response.usage.total_tokens}")

Response: A REST API is a web service that follows the Representational State Transfer architectural style, exposing resources identified by URLs and manipulated with HTTP methods like GET, POST, PUT, and DELETE. It uses stateless client-server communication, cacheability, and uniform representations (often JSON) to support scalable, decoupled interactions.
Prompt tokens: 15
Completion tokens: 201
Total tokens: 216

I token di input sono la tua prompt, quelli di output sono la risposta dell’IA. Provider diversi applicano tariffe diverse per ciascun tipo.

Calcolo automatico dei costi

I conteggi grezzi dei token non ti dicono l’importo in dollari. LiteLLM calcola per te il costo effettivo:

# Get the cost for a completed response
cost = litellm.completion_cost(completion_response=response)
print(f"Total cost: ${cost:.4f}")
Total cost: $0.0020

Il database dei prezzi di LiteLLM converte i token in dollari in base al tuo modello.

Calcoli dei costi manuali

A volte vuoi stimare i costi prima di fare una chiamata, o calcolare i costi per testo che hai già:

# Calculate cost without making an API call
prompt_text = "Explain machine learning"
completion_text = "Machine learning is a method of data analysis that automates analytical model building."

estimated_cost = litellm.completion_cost(
   model="anthropic/claude-sonnet-4-20250514",
   prompt=prompt_text,
   completion=completion_text
)

print(f"Estimated cost: ${estimated_cost:.4f}")

Estimated cost: $0.0002

Utile per fare budgeting e confrontare i modelli.

Tracciare più chiamate API

Per applicazioni che fanno molte chiamate API, puoi tracciare i costi cumulativi:

total_cost = 0.0

conversation = [
   "What is Python?",
   "How do you install Python packages?",
   "What are virtual environments?"
]

for i, question in enumerate(conversation):
   response = litellm.completion(
       model="gpt-5",
       messages=[{"role": "user", "content": question}]
   )
  
   call_cost = litellm.completion_cost(completion_response=response)
   total_cost += call_cost
  
   print(f"Call {i+1}: ${call_cost:.4f}")

print(f"Total cost: ${total_cost:.4f}")

Call 1: $0.0057
Call 2: $0.0134
Call 3: $0.0102
Total cost: $0.0292

Il tracciamento dei costi ti aiuta a prendere decisioni informate su quali modelli usare ed evitare bollette a sorpresa. Vedi esattamente quanto costa ogni chiamata API e confronti i provider.

Conclusione

Ora hai gli strumenti per costruire applicazioni di IA senza vendor lock-in. Hai imparato chiamate API di base, fallback automatici, risposte in streaming, output strutturati e tracciamento dei costi.

Questo ti dà la libertà di scegliere i modelli migliori per ogni task. Cambia provider con facilità, imposta fallback automatici e traccia i costi. Quando arriveranno modelli migliori, potrai adottarli senza riscrivere il codice.