OpenAI Chat Completions API: guida a funzionalità e utilizzo

Creare un'applicazione basata sull'IA non significa solo far generare risposte a un modello. Serve anche un modo affidabile per gestire le conversazioni, guidare le risposte e collegare il tutto all'applicazione. L'API OpenAI Chat Completions lo rende possibile, offrendo agli sviluppatori il controllo sul modo in cui l'IA gestisce i messaggi e genera risposte. Se vuoi capire come funziona e come usarla nei tuoi progetti, questo articolo ti illustrerà tutto ciò che devi sapere.

L'API OpenAI Chat Completions consente agli sviluppatori di integrare i modelli linguistici di OpenAI in applicazioni e servizi. Genera risposte a partire da una sequenza di messaggi e supporta attività quali conversazione, risposta a domande, generazione di contenuti e analisi del testo.

Chat Completions continua a essere supportato. Per i nuovi progetti, OpenAI consiglia la Responses API. Questa guida si concentra su Chat Completions per illustrarne il formato dei messaggi, i parametri delle richieste e l'uso con SDK compatibili.

A differenza dell'endpoint Completions legacy (/v1/completions), che accetta un prompt testuale, Chat Completions accetta un elenco strutturato di messaggi. Ogni messaggio ha un ruolo, ad esempio developer, user o assistant, che aiuta il modello a interpretare le istruzioni e il contesto della conversazione. I ruoli e i tipi di contenuto supportati dipendono dal modello selezionato.

Gli sviluppatori possono utilizzare l'API per creare diverse funzionalità basate sull'IA, tra cui:

• Applicazioni conversazionali: crea chatbot IA, assistenti virtuali e sistemi di assistenza clienti che rispondono ai messaggi degli utenti.

• Generazione di contenuti: genera articoli, descrizioni di prodotti, email, riepiloghi e altri contenuti scritti.

• Analisi del testo: classifica il testo, estrae informazioni, analizza il sentiment e individua i punti chiave nei documenti.

• Assistenza alla programmazione: genera frammenti di codice, spiega concetti di programmazione e aiuta gli sviluppatori a risolvere gli errori.

• Elaborazione linguistica: traduce, riscrive, semplifica e corregge testi in lingue diverse.

L'API offre un modo flessibile per collegare i modelli linguistici al software esistente, consentendo agli sviluppatori di integrare nelle proprie applicazioni risposte generate dall'IA senza dover creare e ospitare i propri modelli linguistici.

L'API Chat Completions segue un flusso di richiesta e risposta. Un'applicazione invia all'endpoint API una richiesta contenente un identificatore del modello e un elenco di messaggi. Il modello selezionato elabora l'input e restituisce una risposta generata.

Il flusso di base comprende i seguenti passaggi:

1. Prepara la conversazione: l'applicazione raccoglie l'input dell'utente e lo organizza in un elenco di messaggi. È possibile includere anche i messaggi delle conversazioni precedenti per fornire contesto.

2. Invia una richiesta API: l'applicazione invia una richiesta POST a https://api.openai.com/v1/chat/completions con il modello selezionato e l'elenco dei messaggi. Le richieste usano un'intestazione Authorization: Bearer <API_KEY>. Il metodo client.chat.completions.create() dell'SDK Python gestisce questa struttura di richiesta e l'autenticazione.

3. Elabora l'input: il modello interpreta i messaggi, ne considera ruoli e contenuti e genera una risposta in base al contesto e ai parametri forniti.

4. Ricevi la risposta: una richiesta senza streaming restituisce una risposta JSON contenente il completamento generato e i metadati. Con lo streaming abilitato, l'API invia una sequenza di eventi inviati dal server (SSE), che l'applicazione elabora man mano che arrivano.

5. Visualizza o elabora l'output: l'applicazione estrae il messaggio generato e lo mostra all'utente oppure lo passa a un altro componente dell'applicazione.

Il flusso di lavoro si basa sul modello di richiesta e risposta dell'API OpenAI Chat Completions.

Per utilizzare efficacemente l'API Chat Completions, gli sviluppatori devono comprenderne i principali parametri di richiesta e il modo in cui influenzano il comportamento del modello.

Il parametro model specifica quale modello linguistico elabora la richiesta. Modelli diversi possono offrire capacità, velocità di risposta, prestazioni di ragionamento e prezzi differenti.

Gli sviluppatori dovrebbero selezionare un modello in base alla complessità dell'attività, alla qualità di risposta prevista, ai requisiti di latenza e al budget.

Il parametro messages contiene un array di messaggi della conversazione. Ogni messaggio include in genere un campo role e un campo content.

I ruoli più comuni includono:

Scegli il ruolo di istruzione supportato dal tuo modello; non è necessario inviare sia messaggi system sia messaggi developer per le stesse istruzioni. Per mantenere il contesto tra un turno e l'altro, includi in ogni richiesta la cronologia pertinente della conversazione. I provider compatibili potrebbero supportare ruoli diversi, quindi, quando adatti un'integrazione, segui la documentazione del loro modello.

Nei modelli e nelle configurazioni che la supportano, temperature controlla la casualità del campionamento. Il riferimento API definisce un intervallo da 0 a 2, con un valore predefinito di 1. Prima di impostare un valore personalizzato, verifica il supporto dei parametri del modello selezionato.

• Temperatura più bassa: produce risposte più mirate e prevedibili, risultando utile per la classificazione, l'estrazione di informazioni e le attività strutturate.

• Temperatura più alta: consente una maggiore varietà nel testo generato, utile per il brainstorming e la scrittura creativa.

Alcune configurazioni di ragionamento non accettano valori personalizzati di temperature o top_p. Per tali configurazioni, ometti questi parametri di campionamento e utilizza invece controlli supportati, come lo sforzo di ragionamento e i limiti di output.

Dove supportato, top_p controlla la selezione dei token tramite il campionamento nucleus. Imposta la soglia di probabilità cumulativa utilizzata per scegliere i token candidati.

Ad esempio, un valore di 0,1 indica che il modello considera i token compresi nel 10% più alto della massa di probabilità cumulativa. Valori più bassi producono in genere un output più mirato, mentre valori più alti consentono maggiori variazioni.

OpenAI consiglia di regolare temperature oppure top_p, anziché modificare entrambi contemporaneamente.

Il parametro max_completion_tokens imposta il numero massimo di token che il modello può generare in una risposta, inclusi i token di ragionamento, ove applicabile.

Impostare un limite adeguato aiuta gli sviluppatori a controllare la lunghezza dell'output e a gestire il consumo di token. Se il modello raggiunge questo limite prima di completare la risposta, il completamento potrebbe terminare con il motivo di fine length.

Il parametro stream determina se l'API restituisce la risposta generata tutta insieme oppure progressivamente durante la generazione.

• false: restituisce la risposta completa al termine della generazione.

• true: trasmette i dati della risposta all'applicazione tramite eventi inviati dal server (SSE).

Lo streaming è utile per le interfacce di chat e le applicazioni in cui gli utenti traggono vantaggio dal vedere le risposte comparire progressivamente anziché attendere l'intero output.

Il parametro response_format seleziona il formato di output nei modelli supportati. Il testo è il valore predefinito. Impostando type su json_object si attiva la modalità JSON, che produce JSON valido ma non impone uno schema specifico. Includi nei messaggi un'istruzione per restituire JSON.

Per campi e tipi di dati prevedibili, utilizza gli output strutturati basati su JSON Schema con type: "json_schema" e strict: true su un modello compatibile. In modalità rigorosa può essere utilizzato solo il sottoinsieme supportato di JSON Schema. Prima di elaborare il risultato, verifica la presenza di un rifiuto o di una risposta troncata. Per i dettagli di configurazione, consulta la guida agli output strutturati.

Il parametro tool_choice controlla la selezione degli strumenti quando il modello supporta la chiamata di strumenti tramite Chat Completions. Il supporto dipende sia dal modello sia dalla relativa configurazione di ragionamento; alcuni modelli più recenti richiedono la Responses API per utilizzare gli strumenti. Verifica questi requisiti prima di aggiungere strumenti a una richiesta.

Le impostazioni comuni includono:

• none: impedisce al modello di chiamare strumenti.

• auto: consente al modello di decidere se chiamare uno strumento disponibile.

• required: richiede al modello di chiamare uno o più strumenti.

Questa funzionalità supporta la chiamata di funzioni, consentendo a un'applicazione di collegare le decisioni generate dal modello a funzioni, database e servizi esterni. L'applicazione è responsabile dell'esecuzione della funzione richiesta e della restituzione del relativo risultato al modello.

Consulta il riferimento dell'API Chat Completions per le definizioni dei parametri e i requisiti di compatibilità dei modelli. L'esempio Python seguente utilizza una richiesta di testo di base senza strumenti.

Gli sviluppatori possono accedere all'API Chat Completions tramite richieste HTTP o un SDK ufficiale. L'esempio seguente utilizza Python per inviare una richiesta conversazionale e recuperare la risposta generata.

Passaggio 1. Ottieni una chiave API

Crea una chiave API nella piattaforma API OpenAI e assicurati che il tuo account abbia accesso al modello selezionato e disponga di crediti API o capacità di fatturazione sufficienti. Salva la chiave in una variabile d'ambiente anziché nel codice sorgente dell'applicazione. Su macOS o Linux, esegui:

Sostituisci YOUR_API_KEY con la tua chiave. Su Windows, imposta la stessa variabile OPENAI_API_KEY nella shell o nell'ambiente di sistema.

Passaggio 2. Installa l'SDK Python di OpenAI

Installa la libreria Python ufficiale usando pip:

Passaggio 3. Inizializza il client API

Importa l'SDK e inizializza il client. OpenAI() legge automaticamente la variabile d'ambiente OPENAI_API_KEY impostata nel passaggio 1.

Passaggio 4. Invia una richiesta di completamento della chat

Chiama client.chat.completions.create() con un modello e un elenco di messaggi. Questo esempio utilizza gpt-6-astra con un basso sforzo di ragionamento e un limite totale di generazione di 4.096 token. Se questo modello non è disponibile per il tuo account, scegli un modello che supporti Chat Completions e adatta i parametri alla relativa documentazione.

In questo esempio:

• model identifica il modello linguistico utilizzato per generare la risposta.

• messages fornisce istruzioni e input dell'utente.

• reasoning_effort imposta lo sforzo di ragionamento per i modelli che supportano questo parametro.

• max_completion_tokens limita i token generati, inclusi quelli di ragionamento. Non garantisce una quantità specifica di testo visibile.

• response.choices[0].message.content estrae la risposta dell'assistente.

Elaborare la risposta dell'API

Per questa richiesta non in streaming, l'API restituisce un JSON contenente il completamento e i metadati della richiesta. L'SDK Python lo analizza in un oggetto ChatCompletion, motivo per cui l'esempio accede ai campi tramite attributi come response.choices[0].message.content.

Tra i campi di risposta importanti figurano:

Il campo finish_reason può aiutare gli sviluppatori a capire come si è conclusa una generazione. I valori comuni includono stop, length e tool_calls.

Gli sviluppatori possono anche esaminare il campo usage per monitorare il consumo di token in input e output, utile per stimare i costi dell'API e ottimizzare l'utilizzo dell'applicazione.

Questo esempio mostra una risposta di testo di base. Quando si aggiungono streaming, output strutturato o strumenti, aggiornare sia la richiesta sia la logica di gestione della risposta in base al modello e all'endpoint selezionati.

Per gli sviluppatori che esplorano alternative all'API OpenAI Chat Completions, Kimi API consente di accedere ai modelli linguistici di grandi dimensioni di Moonshot AI tramite un formato API compatibile con OpenAI.

Kimi offre le interfacce Chat Completions, Responses e Messages. L'esempio seguente usa il suo endpoint Chat Completions compatibile con OpenAI, così da poter riutilizzare il flusso di lavoro dell'SDK introdotto sopra. Configurare una chiave Kimi API, impostare l'URL di base Kimi e selezionare un modello supportato. Per i parametri del modello, i ruoli dei messaggi e il supporto degli strumenti, fare riferimento alla documentazione di Kimi.

Passaggio 1. Ottenere una chiave Kimi API

Registrarsi sulla piattaforma Kimi API e creare una chiave API nella console per sviluppatori. Prima di effettuare la prima richiesta, controllare il saldo, l'accesso ai modelli e i limiti di frequenza dell'account.

Memorizzare la chiave Kimi in una variabile d'ambiente separata. Su macOS o Linux, eseguire:

Sostituire YOUR_KIMI_API_KEY con la propria chiave Kimi. Su Windows, impostare nell'ambiente la stessa variabile KIMI_API_KEY.

Passaggio 2. Installare l'SDK Python OpenAI

Se l'SDK non è già installato, eseguire:

Passaggio 3. Configurare il client Kimi API

Creare un kimi_client separato usando l'URL di base Kimi e la variabile KIMI_API_KEY impostata nel passaggio 1. La lettura della chiave con os.environ rende immediatamente visibile come errore l'assenza di una variabile d'ambiente.

Passaggio 4. Inviare una richiesta Chat Completions

Usare lo stesso metodo dell'SDK con il client Kimi. Questa richiesta seleziona kimi-k3, usa il ruolo system supportato da Kimi per le istruzioni e restituisce una risposta di testo non in streaming.

• Opzioni di modello per diversi carichi di lavoro: Kimi K3.1 Pro supporta ragionamenti complessi, programmazione a lungo orizzonte e lavoro basato sulla conoscenza. La sua variante Highspeed offre output più rapido con le stesse capacità del modello. L'esempio sopra usa Kimi K3; consultare l'elenco aggiornato dei modelli per disponibilità e indicazioni sulla migrazione.

• Compatibilità con OpenAI API: Gli sviluppatori che conoscono il formato OpenAI Chat Completions possono riutilizzare una struttura di richiesta simile e i flussi di lavoro SDK supportati nell'integrazione dei modelli Kimi.

• Conversazioni multi-turno: Gli sviluppatori possono fornire cronologie dei messaggi per supportare conversazioni consapevoli del contesto, assistenti virtuali e applicazioni interattive.

• Streaming e chiamata di funzioni: L'API supporta risposte in streaming e flussi di lavoro di chiamata degli strumenti, consentendo agli sviluppatori di creare applicazioni più interattive e collegare i modelli a funzioni esterne.

• Input multimodale: I modelli Kimi supportati possono elaborare diversi tipi di input, inclusi testo, immagini e video, a seconda delle capacità del modello.

Quando lavorano con l'API Chat Completions, gli sviluppatori possono riscontrare errori relativi all'autenticazione, alla configurazione dell'API, alla disponibilità dei modelli o ai limiti delle richieste. Comprendere questi problemi comuni può aiutare a individuare gli errori e a far funzionare correttamente l'integrazione:

• Chiave API non valida o mancante: Errori di autenticazione, come HTTP 401, possono verificarsi quando la chiave API è errata, scaduta, revocata o non configurata correttamente. Verificare che la chiave sia valida, che la variabile d'ambiente venga caricata correttamente e che la richiesta includa le credenziali di autenticazione appropriate.

• URL di base dell'API errato: Le richieste inviate a un endpoint errato possono restituire errori come 404 o errori di connessione. Verificare che l'URL di base corrisponda alla documentazione del provider API e che la richiesta utilizzi il percorso dell'endpoint corretto. Quando si passa da OpenAI a provider compatibili, ricordarsi di aggiornare di conseguenza l'URL di base.

• ID del modello non valido o non disponibile: Una richiesta può non riuscire se il nome del modello specificato è errato, non disponibile per il proprio account o non supportato dall'endpoint selezionato. Consultare la documentazione del provider sui modelli e confermare che l'ID del modello corrisponda a quello disponibile per il proprio account API.

• Lunghezza del contesto superata: Se i messaggi di input combinati e l'output generato superano la finestra di contesto del modello, l'API può rifiutare la richiesta. Ridurre la lunghezza dell'input, rimuovere la cronologia della conversazione non necessaria oppure riassumere i messaggi precedenti prima di inviare nuovamente la richiesta.

• Output troncato: Una risposta può interrompersi prima di completare il contenuto richiesto se raggiunge il limite max_completion_tokens. Aumentare il limite di token quando supportato oppure suddividere un'attività di generazione lunga in richieste più piccole. È anche possibile esaminare choices[].finish_reason per verificare se la risposta si è conclusa a causa del limite length.

• Limite di frequenza o quota superato: Per OpenAI, HTTP 429 può indicare un limite di frequenza per richieste o token, un limite di spesa o un'altra restrizione di utilizzo. Esaminare il tipo e il codice dell'errore prima di riprovare. In caso di limite di frequenza temporaneo, ridurre la frequenza delle richieste e rispettare Retry-After quando fornito, oppure usare un backoff esponenziale.

Se l'errore indica crediti esauriti o un limite di fatturazione o di spesa, controllare il saldo e le impostazioni di fatturazione dell'account; tentativi ripetuti non ripristineranno l'accesso. Quando si usa Kimi o un altro provider compatibile, seguire la documentazione di quel provider sui codici di errore, poiché i codici di stato e le regole sulle quote possono differire.

Per un debug più efficiente, controllare il codice di stato HTTP e il messaggio di errore restituiti dall'API prima di modificare i parametri della richiesta. Questi dettagli possono aiutare a distinguere tra problemi di autenticazione, errori di configurazione e limiti di utilizzo.

L'API Chat Completions può supportare un'ampia gamma di scenari applicativi. Il suo formato strutturato dei messaggi e i parametri di generazione personalizzabili la rendono adatta sia a funzionalità semplici basate sul testo sia a flussi di lavoro IA più complessi.

• Chatbot IA e assistenti virtuali: Gli sviluppatori possono usare l'API per creare assistenti conversazionali per siti web, applicazioni mobili e piattaforme di assistenza clienti. Passando i messaggi precedenti alle richieste successive, le applicazioni possono mantenere il contesto della conversazione e fornire risposte più pertinenti.

• Creazione di contenuti e modifica del testo: L'API può generare e trasformare testo in base alle istruzioni dell'utente. Le applicazioni possono usarla per preparare bozze di articoli per blog, scrivere testi di marketing, riassumere contenuti lunghi, riscrivere paragrafi e adattare gli stili di scrittura a pubblici e finalità diversi.

• Classificazione del testo ed estrazione di informazioni: Le aziende possono integrare l'API in flussi di lavoro che elaborano grandi volumi di testo. Ad esempio, può classificare il feedback dei clienti, individuare il sentiment, estrarre informazioni importanti dai messaggi e organizzare contenuti non strutturati in categorie predefinite.

• Assistenti di programmazione: l'API può supportare gli strumenti di sviluppo software generando codice, spiegando concetti di programmazione, suggerendo soluzioni e aiutando gli sviluppatori a individuare gli errori. Le applicazioni possono anche collegare il modello a strumenti di sviluppo esterni tramite le chiamate di funzione.

• Flussi di lavoro aziendali basati sull'IA: gli sviluppatori possono integrare l'API nelle applicazioni aziendali per automatizzare attività ripetitive legate al linguaggio. Tra gli esempi rientrano l'elaborazione delle richieste dei clienti, la generazione di report, l'estrazione di informazioni dai documenti e la preparazione di risposte basate su istruzioni predefinite.

L'API Chat Completions di OpenAI offre agli sviluppatori un modo pratico per integrare l'IA conversazionale nelle proprie applicazioni e creare esperienze utente più utili. Scegliere il modello giusto, comprenderne i parametri e gestire con attenzione le risposte dell'API può fare una reale differenza nelle prestazioni di un'applicazione. Tuttavia, nello sviluppo di soluzioni basate sull'IA, gli sviluppatori non devono affidarsi a un unico fornitore. Se desideri esplorare un'altra opzione, prova Kimi API e scopri come la sua configurazione compatibile con OpenAI si adatta alle tue esigenze di sviluppo.