Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Migliori pratiche per la produzione

Lezione 17 di 22 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Migliori pratiche per la produzione
  2. 1. Architettura del client
  3. 2. Gestione dei prompt
  4. 3. Timeout e limiti
  5. 4. Fallback del modello
  6. 5. Elaborazione in batch
  7. 6. Test e validazione
  8. 7. Checklist per il deploy in produzione
  9. Punti chiave

Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI: temperature e top_p sono accettati solo con uno sforzo di ragionamento (reasoning effort) impostato su none, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificare reasoning={"effort": "none"} (API Responses) o reasoning_effort="none" (Chat Completions). Fonti: Utilizzo di GPT-6 · GPT-5.6 Terra.

Migliori pratiche per la produzione

Questa lezione copre le migliori pratiche essenziali per il deploy in produzione di un’applicazione basata sull’API OpenAI. Considerala la tua checklist pre-lancio. Le lezioni precedenti ti hanno fornito i mattoni fondamentali: gestione degli errori, limiti di frequenza, resilienza, osservabilità e costi. Ora è il momento di assemblarli in un’applicazione che un collega possa prendere in carico ed eseguire senza il tuo intervento.

1. Architettura del client

Singleton con configurazione centralizzata

Istanziare un client OpenAI a ogni chiamata spreca la connessione HTTP sottostante e, cosa più grave, disperde la tua configurazione. Ti ritrovi con un timeout di 30 secondi qui e il default là, senza sapere quale si applichi in produzione. Il decoratore lru_cache garantisce un’unica istanza, configurata in un unico punto.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Client singleton con configurazione di produzione."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# Ovunque nel tuo codice:
client = get_client()

Variabili d’ambiente

Lo stesso principio si applica alle impostazioni che variano tra gli ambienti. Verifica le variabili richieste all’avvio: è meglio che un servizio si rifiuti di partire con un messaggio chiaro piuttosto che avviarsi e fallire alla prima chiamata dell’utente. Questo rende il modello, il limite di token e la temperatura regolabili senza bisogno di un nuovo deploy.

import os

# OBBLIGATORIO: non hardcodare mai le chiavi
REQUIRED_ENV = ["OPENAI_API_KEY"]

for var in REQUIRED_ENV:
    if not os.environ.get(var):
        raise RuntimeError(f"Variabile mancante {var}")

# Configurazione specifica per ambiente
MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.6-terra")
MAX_TOKENS = int(os.environ.get("OPENAI_MAX_TOKENS", "4096"))
TEMPERATURE = float(os.environ.get("OPENAI_TEMPERATURE", "0.7"))

2. Gestione dei prompt

Separa i prompt dal codice

Un prompt è un asset aziendale, proprio come una regola di business. Seppellirlo in una f-string all’interno di una funzione rende impossibile la revisione da parte di qualcuno che conosce il business ma non Python. Isotalo come template parametrizzato: la funzione si riduce allora alla formattazione e alla chiamata, e una temperatura di 0.0 rende la classificazione riproducibile.

# prompts/classification.txt
PROMPT_CLASSIFICATION = """You are a text classifier.
Classify the following text into one of these categories:
{categories}

Text: {texte}

Reply only with the category name."""

def classifier(texte: str, categories: list[str]) -> str:
    prompt = PROMPT_CLASSIFICATION.format(
        categories=", ".join(categories),
        texte=texte
    )
    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # la temperatura richiede effort none
        input=prompt,
        temperature=0.0
    )
    return response.output_text.strip()

Versiona i tuoi prompt

Modificare un prompt cambia il comportamento del sistema con la stessa certezza di una modifica al codice, ma senza che alcun test unitario se ne accorga. Mantieni le versioni successive e seleziona quella attiva tramite configurazione. Questo ti permette di confrontare due formulazioni sul traffico reale e di tornare alla precedente con una variabile d’ambiente se la nuova degrada i risultati.

PROMPTS = {
    "classification_v1": "Classify: {texte}",
    "classification_v2": "Analyze and classify precisely: {texte}",
}

# In produzione, usa una versione specifica
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Timeout e limiti

Delimita qualsiasi input proveniente dall’esterno prima che raggiunga l’API. Un utente che incolla un PDF di 200 pagine nel tuo campo di input non deve poter innescare una chiamata da diversi dollari o causare il fallimento della richiesta per overflow del contesto. La troncatura preventiva, combinata con il limite di output e la temperatura dalla configurazione, rende prevedibili costo e latenza di ogni chiamata.

def appel_avec_garde_fous(prompt: str) -> str:
    """Chiamata API con tutte le protezioni."""
    # Limita la dimensione del prompt
    MAX_PROMPT_CHARS = 50000
    if len(prompt) > MAX_PROMPT_CHARS:
        prompt = prompt[:MAX_PROMPT_CHARS]
        print(f"Prompt troncato a {MAX_PROMPT_CHARS} caratteri")

    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # la temperatura richiede effort none
        input=prompt,
        max_output_tokens=MAX_TOKENS,
        temperature=TEMPERATURE,
    )

    return response.output_text

4. Fallback del modello

Quando un modello è saturato o temporaneamente non disponibile, restituire un errore non è l’unica opzione. Passare a un modello secondario degrada la qualità ma preserva il servizio: un compromesso spesso preferibile per un assistente di supporto, meno per l’analisi contrattuale. Il ciclo iterava attraverso i modelli in ordine di preferenza e solleva un’eccezione solo se tutti falliscono.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Prova Terra poi passa a Luna in caso di errore."""
    modeles = ["gpt-5.6-terra", "gpt-5.6-luna"]

    for modele in modeles:
        try:
            response = get_client().responses.create(
                model=modele,
                input=prompt
            )
            return response.output_text
        except (RateLimitError, InternalServerError) as e:
            print(f"{modele} non disponibile: {e}")
            continue

    raise RuntimeError("Tutti i modelli non sono disponibili")

5. Elaborazione in batch

Per elaborare mille documenti, le chiamate sequenziali sono troppo lente e quelle simultanee fanno esplodere i tuoi limiti di frequenza. Un semaforo trova il giusto equilibrio. Due dettagli rendono robusta questa implementazione: return_exceptions=True impedisce che un singolo fallimento cancelli l’intero batch, e l’ordinamento per indice ripristina l’ordine originale, che asyncio.gather non garantisce nel tempo di esecuzione.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Elabora un batch di prompt con concorrenza limitata."""
    client = AsyncOpenAI()
    semaphore = asyncio.Semaphore(max_concurrent)
    resultats = []

    async def traiter_un(index: int, prompt: str):
        async with semaphore:
            response = await client.responses.create(
                model="gpt-5.6-terra",
                input=prompt
            )
            return index, response.output_text

    tasks = [traiter_un(i, p) for i, p in enumerate(prompts)]
    results = await asyncio.gather(*tasks, return_exceptions=True)

    # Ordina per indice per mantenere l'ordine
    sorted_results = sorted(
        [(idx, res) for idx, res in results if not isinstance(res, Exception)],
        key=lambda x: x[0]
    )
    return [res for _, res in sorted_results]

# prompts = ["Question 1", "Question 2", "Question 3"]
# résultats = asyncio.run(traiter_batch(prompts))

6. Test e validazione

Hai bisogno di due tipi diversi di test. Il primo verifica l’infrastruttura: la chiave funziona, la rete passa, il modello risponde; si adatta bene a un controllo di salute all’avvio. Il secondo, più originale, testa la qualità del prompt stesso: invii un caso di cui conosci la risposta corretta e verifichi che appaia. Queste asserzioni sono la tua rete di sicurezza contro le regressioni quando riformuli un template.

def test_api_disponible():
    """Verifica che l'API sia accessibile."""
    try:
        response = get_client().responses.create(
            model="gpt-5.6-terra",
            input="test",
            max_output_tokens=5
        )
        assert response.output_text is not None
        print("API OK")
        return True
    except Exception as e:
        print(f"API KO: {e}")
        return False

def test_prompt_quality(prompt: str, attendu: str) -> bool:
    """Verifica che un prompt restituisca un risultato coerente."""
    response = get_client().responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # la temperatura richiede effort none
        input=prompt,
        temperature=0.0
    )
    resultat = response.output_text.lower()
    return attendu.lower() in resultat

# Test di regressione dei prompt
assert test_prompt_quality(
    "Classify 'excellent product': positive or negative?",
    "positive"
)

Costruisci una dozzina di casi di test come questo, rappresentativi dei tuoi casi d’uso reali, ed eseguili ogni volta che modifichi un prompt. Una suite di test di dieci minuti ti risparmierà settimane di dubbi sulla qualità percepita.

7. Checklist per il deploy in produzione

Prima del deploy, verifica ogni punto:

Infrastruttura

  • Variabili d’ambiente configurate (OPENAI_API_KEY, ecc.)
  • Timeout e max_retries configurati
  • Logging strutturato attivo
  • Monitoraggio dei costi abilitato

Resilienza

  • Gestione completa degli errori (tutti i codici HTTP)
  • Backoff esponenziale per i retry
  • Circuit breaker per interruzioni prolungate
  • Fallback su un modello alternativo

Sicurezza

  • Chiave API mai esposta nel codice o nei log
  • Validazione dell’input utente
  • Limitazione della frequenza lato client
  • Nessun dato sensibile nei prompt

Prestazioni

  • Streaming abilitato per le interfacce utente
  • Elaborazione in batch per compiti ad alto volume
  • Caching per richieste ripetitive
  • Scelta del modello adattata a ogni compito

Costi

  • Budget giornaliero definito
  • Alert configurati
  • max_output_tokens impostato dove possibile
  • Modello più conveniente selezionato per ogni compito

Punti chiave

  • Centralizza la configurazione del client con un singleton
  • Separa e versiona i tuoi prompt fuori dal codice
  • Implementa il fallback del modello per l’alta disponibilità
  • Usa l’elaborazione in batch con concorrenza limitata per i volumi elevati
  • Testa i tuoi prompt con asserzioni di qualità
  • Segui la checklist completa prima di ogni deploy in produzione