Installare l'SDK Python
In questa pagina
Installare l’SDK Python
L’SDK Python openai è la libreria ufficiale per interagire con l’API. Questa lezione ti guida attraverso l’installazione e configura una struttura di progetto pulita che utilizzerai per tutto il resto del corso.
Prerequisiti e Installazione
Hai bisogno di Python 3.10 o superiore—il minimo richiesto dall’SDK openai (versione 3.42.1 al 2 novembre 2026, secondo PyPI)—di un gestore di pacchetti (pip o uv) e della chiave API ottenuta nella lezione precedente. Inizia confermando il tuo interprete, poiché le macchine di sviluppo spesso ospitano più versioni:
python --version
# Python 3.12.4
L’installazione richiede un singolo comando: pip install openai, oppure uv pip install openai se usi uv, che è significativamente più veloce. Tuttavia, prendi l’abitudine di lavorare all’interno di un ambiente virtuale. Questo evita lo scenario comune in cui, sei mesi dopo, scopri che due progetti richiedono versioni incompatibili della stessa libreria.
# Crea un ambiente virtuale
python -m venv .venv
# Attiva (Linux/macOS)
source .venv/bin/activate
# Attiva (Windows)
.venv\Scripts\activate
# Installa l'SDK
pip install openai
Due compagni appaiono in quasi ogni progetto e meritano di essere installati insieme all’SDK. Pydantic aiuta a definire schemi per l’Output Strutturato, che vedrai più avanti; python-dotenv carica il file .env nelle variabili d’ambiente.
# Installa con supporto per le dataclass di Pydantic
pip install openai pydantic
# Installa con python-dotenv per le variabili d'ambiente
pip install openai python-dotenv
Infine, verifica che l’importazione funzioni e prendi nota della versione installata. Questa è la prima informazione da fornire se apri un ticket di supporto.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
Un Client, Tutte le API
L’SDK ruota attorno a un singolo oggetto client che espone l’intera piattaforma tramite sottomoduli. Non hai bisogno di istanziare nulla di nuovo per passare dalla generazione di testo agli embedding o alla moderazione.
from openai import OpenAI
client = OpenAI()
# Responses API (testo, chiamata di funzioni, output strutturato)
client.responses.create(...)
# Chat Completions API (legacy)
client.chat.completions.create(...)
# Embeddings
client.embeddings.create(...)
# Immagini
client.images.generate(...)
# Audio
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Moderazione
client.moderations.create(...)
Configurare il Client per il Tuo Contesto
Le impostazioni predefinite dell’SDK funzionano per la sperimentazione, ma sono insufficienti per le applicazioni web. Il timeout predefinito è di dieci minuti: in un’API HTTP che dovrebbe rispondere in pochi secondi, questo significa che una richiesta bloccata occupa un worker per troppo tempo. Riducilo e aumenta il numero di tentativi automatici, che per default è due.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 secondi (default: 10 minuti)
max_retries=3, # 3 tentativi in caso di errore (default: 2)
)
Il parametro base_url risponde a un’altra esigenza: instradare le chiamate attraverso un proxy aziendale che registra il traffico in uscita, o verso un servizio che espone un’API compatibile.
# Utile per proxy aziendali o API compatibili
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
Infine, se la tua applicazione si basa su asyncio—FastAPI, aiohttp e simili—usa AsyncOpenAI. Il client sincrono bloccherebbe il loop degli eventi durante la generazione, annullando i benefici del codice asincrono.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Utilizzo con await
import asyncio
async def main():
response = await async_client.responses.create(
model="gpt-5.6-terra",
input="Hello!"
)
print(response.output_text)
asyncio.run(main())
# Output: Hello! How can I help you today?
Strutturare il Tuo Progetto
Adotta un’organizzazione che isoli la configurazione del client dal resto del tuo codice fin dall’inizio. Questo evita di disseminare decine di chiamate OpenAI() in tutto il progetto, ognuna con le proprie impostazioni.
my-project/
├── .env # Chiave API (NON fare mai commit su git)
├── .gitignore # Include .env
├── requirements.txt # Dipendenze
├── src/
│ ├── __init__.py
│ ├── client.py # Configurazione del client OpenAI
│ └── main.py # Punto di ingresso
└── tests/
└── test_api.py
Il file src/client.py centralizza la factory del client: il giorno in cui cambierai il timeout o aggiungerai un proxy, dovrai modificare un solo punto.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Restituisce un client OpenAI configurato."""
return OpenAI(
max_retries=3,
timeout=30.0
)
E requirements.txt fissa le versioni minime attese:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Tre Errori Comuni
Un ModuleNotFoundError su openai segnala quasi sempre un ambiente virtuale non attivo o diverso da quello in cui hai installato il pacchetto. Individua l’interprete effettivamente in uso con which python su Linux e macOS, o where python su Windows, quindi reinstalla con pip install --upgrade openai. Un AuthenticationError punta alla variabile d’ambiente: stampa os.environ.get("OPENAI_API_KEY", "NOT DEFINED") per escludere problemi: il file .env non viene caricato se load_dotenv() non è stato chiamato prima di istanziare il client. Infine, un errore riguardante un parametro sconosciuto indica solitamente un SDK troppo vecchio per la funzionalità che stai utilizzando: pip install --upgrade openai risolve il problema.
Punti chiave
- Installa l’SDK con
pip install openaiall’interno di un ambiente virtuale - Il client
OpenAI()è il punto di ingresso per tutte le API - Usa
AsyncOpenAI()per le applicazioni asincrone - Configura timeout e retry in base alle tue esigenze
- Struttura il tuo progetto con un file
.enve un client centralizzato