OpenAI Responses API: la guida definitiva per sviluppatori

Che cos’è la Responses API di OpenAI?

La Responses API è l’API più recente e avanzata di OpenAI. Riunisce i punti di forza delle API Chat Completions e Assistants in un’unica interfaccia snella. Rilasciata a marzo 2025, mantiene funzionalità già note offrendo al contempo un approccio più integrato alla creazione di applicazioni AI. 

La vera innovazione sta nel modo in cui semplifica lo sviluppo: gestisce automaticamente la logica di orchestrazione e integra nativamente gli strumenti integrati di OpenAI per la ricerca sul web e la ricerca nei file, senza richiedere implementazioni personalizzate.

In questo tutorial vedremo come usare la Responses API nei tuoi progetti. Scoprirai come gestisce la generazione di testo, come lavora con le immagini e come fornisce risposte in streaming. Esamineremo gli strumenti integrati che rendono lo sviluppo più veloce e lineare rispetto a prima, mostrandoti come questi strumenti collaborano all’interno del framework dell’API. 

Al termine di questa guida saprai quando usare la Responses API al posto di altre opzioni OpenAI e come queste conoscenze possano aiutarti a creare applicazioni più efficienti con meno codice e meno sforzo. Se sei alle prime armi con l’API di OpenAI, dai un’occhiata al nostro corso introduttivo, Working with the OpenAI API, per iniziare il tuo percorso nello sviluppo di applicazioni basate sull’AI.

Primi passi con la Responses API

La Responses API offre un’interfaccia più lineare e facile da usare per interagire con i modelli di OpenAI, unificando in una soluzione elegante ciò che prima richiedeva sintassi prolisse e complesse. 

Prima di entrare nei casi d’uso specifici, configuriamo l’ambiente e capiamo la sintassi di base.

from openai import OpenAI
import os
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Initialize the client
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

Questo passaggio di inizializzazione crea un oggetto client che gestirà tutte le richieste all’API. Il pacchetto dotenv aiuta a gestire la tua chiave API in modo sicuro tramite variabili d’ambiente, invece di inserirla direttamente nello script: una best practice che rende il codice più portabile e sicuro tra ambienti diversi.

Generare contenuti con la Responses API

L’uso più immediato della Responses API è la generazione di testo. Vediamo uno scenario reale: supponiamo che tu stia costruendo una piattaforma e-commerce e abbia bisogno di generare automaticamente descrizioni prodotto convincenti a partire da dettagli di base.

Tradizionalmente, questo richiederebbe un attento lavoro di prompt engineering e più iterazioni. Con la Responses API, puoi creare una semplice funzione che gestisce il tutto in modo elegante:

def generate_product_description(product_name, features, target_audience):
   response = client.responses.create(
       model="gpt-4o",
       instructions="You are a professional copywriter specialized in creating concise, compelling product descriptions. Focus on benefits rather than just features.",
       input=f"""
       Create a product description for {product_name}.
       Key features:
       - {features[0]}
       - {features[1]}
       - {features[2]}
       Target audience: {target_audience}
       Keep it under 150 words.
       """,
       temperature=0.7,
       max_output_tokens=200
   )
  
   return response.output_text

# Example usage
headphones_desc = generate_product_description(
   "NoiseGuard Pro Headphones",
   ["Active noise cancellation", "40-hour battery life", "Memory foam ear cushions"],
   "Business travelers and remote workers"
)

print(headphones_desc)

Output:

Experience unparalleled focus and comfort with NoiseGuard Pro Headphones—your perfect travel and work companion. 
Designed for business travelers and remote workers, these headphones feature cutting-edge active noise cancellation to block out distractions, allowing you to concentrate on what truly matters. 
With an impressive 40-hour battery life, you can enjoy uninterrupted productivity or relaxation on even the longest journeys. 
The luxurious memory foam ear cushions ensure a snug, comfortable fit for all-day wear, reducing fatigue and enhancing your listening experience. 
Elevate your work and travel with NoiseGuard Pro—where clarity meets comfort.

Con poche righe di codice abbiamo creato un testo di qualità marketing che normalmente richiederebbe un copywriter professionista. La funzione è anche riutilizzabile: ti basta cambiare i parametri per generare descrizioni per qualsiasi prodotto del tuo catalogo.

Questo esempio mostra alcuni schemi chiave nell’uso della Responses API:

1. Il parametro instructions funge da system prompt, definendo il comportamento e il contesto dell’AI.
2. Il parametro temperature (0-2) controlla la casualità: valori più bassi producono output più deterministici, mentre quelli più alti introducono più creatività.
3. Il parametro max_output_tokens limita la lunghezza della risposta, aiutando a controllare i costi e a garantire output concisi.
4. L’oggetto di risposta contiene il testo generato nella proprietà output_text.

Analizzare immagini per applicazioni pratiche

Molte applicazioni reali devono elaborare sia testo sia immagini. Ad esempio, le piattaforme e-commerce devono analizzare le foto dei prodotti, i sistemi di moderazione dei contenuti devono esaminare i file caricati e le app social devono comprendere i contenuti visivi.

La Responses API eccelle in attività multimodali come l’analisi di immagini, senza richiedere endpoint separati o codice di integrazione complesso:

def analyze_product_image(image_url):
   response = client.responses.create(
       model="gpt-4o",
       instructions="You are a product photography expert and e-commerce consultant.",
       input=[
           {"role": "user", "content": "Analyze this product image and provide the following details:\n1. Product category\n2. Key visible features\n3. Potential quality issues\n4. Suggested improvements for the product photography"},
           {
               "role": "user",
               "content": [
                   {
                       "type": "input_image",
                       "image_url": image_url
                   }
               ],
           },
       ],
       temperature=0.2
   )
  
   return response.output_text

# Example with a sports team image
analysis = analyze_product_image("https://upload.wikimedia.org/wikipedia/commons/a/a5/Barcelona_fc_lamina_elgrafico.jpg")
print(analysis)

Output:

1. **Product Category**: Sports team memorabilia or vintage sports photography.

2. **Key Visible Features**:
  - The image features a group of individuals in sports uniforms, likely a football (soccer) team.
  - The uniforms have distinct vertical stripes in red and blue.
  - A football is visible in the foreground.
  - The setting appears to be an outdoor field, possibly a stadium.

...

Questa funzione può essere integrata in una piattaforma e-commerce per analizzare automaticamente le foto dei prodotti quando i venditori le caricano. Il sistema potrebbe fornire feedback immediati sulla qualità delle immagini e suggerire miglioramenti, portando in definitiva a tassi di conversione più alti grazie a inserzioni di qualità superiore, il tutto senza revisione manuale.

Quando lavori con le immagini, dovresti passare un array di oggetti messaggio al parametro input invece di una stringa, ciascuno con valori role e content.

Il contenuto immagine è specificato come oggetto con type: input_image e un image_url. Puoi combinare testo e immagini nella stessa richiesta, abilitando interazioni multimodali ricche.

Implementare lo streaming per applicazioni reattive

Gli utenti si aspettano feedback istantanei. Aspettare diversi secondi per una risposta dell’AI può uccidere l’engagement: ecco perché lo streaming è essenziale per creare esperienze utente reattive, soprattutto in app di chat o in tempo reale.

Immagina di costruire uno strumento di analisi dei feedback dei clienti per un product team. Invece di farli aspettare l’analisi completa, puoi trasmettere i risultati man mano che vengono generati:

def analyze_customer_feedback(feedback_text):
   print("Analyzing customer feedback in real-time:")
  
   stream = client.responses.create(
       model="gpt-4o",
       instructions="Extract key sentiments, product issues, and actionable insights from this feedback.",
       input=feedback_text,
       stream=True,
       temperature=0.3,
       max_output_tokens=500
   )
  
   full_response = ""
   print("\nAnalysis results:")
   for event in stream:
       if event.type == "response.output_text.delta":
           print(event.delta, end="")
           full_response += event.delta
       elif event.type == "response.error":
           print(f"\nError occurred: {event.error}")
  
   return full_response

# Example with a complex customer review
feedback = """
I've been using the SmartHome Hub for about 3 months now. The voice recognition is fantastic
and the integration with my existing devices was mostly seamless. However, the app crashes
at least once a day, and the night mode feature often gets stuck until I restart the system.
Customer support was helpful but couldn't fully resolve the app stability issues.
"""

analysis_result = analyze_customer_feedback(feedback)

In un’app reale, sostituiresti le istruzioni print con aggiornamenti dell’interfaccia, permettendo agli utenti di vedere l’analisi formarsi in tempo reale, proprio come le moderne app di chat mostrano l’AI che "pensa" mentre genera una risposta. Questo crea un’esperienza più coinvolgente e dà un riscontro immediato che la richiesta è in elaborazione.

L’implementazione dello streaming funziona così:

1. Impostare stream=True nel metodo create
2. Elaborare la risposta come iterabile di eventi con tipi specifici
3. Gestire separatamente i diversi tipi di evento: response.output_text.delta per i blocchi di contenuto, response.error per gli errori

Ora che abbiamo coperto le funzionalità di base della Responses API, vediamo gli strumenti integrati che ne potenziano ulteriormente le capacità.

Strumenti integrati della OpenAI Responses API

La Responses API integra alcuni strumenti che estendono le sue capacità oltre la semplice generazione di testo. Questi tool permettono di creare applicazioni più potenti senza bisogno di codice di integrazione complesso o chiamate multiple all’API.

Ricerca sul web: accesso a informazioni in tempo reale

Lo strumento di ricerca sul web consente alla Responses API di recuperare informazioni aggiornate da internet, superando il limite degli LLM vincolati ai soli dati di addestramento.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
   model="gpt-4o",
   tools=[{"type": "web_search_preview"}],
   input="What are some news related to the stock market?",
)

print(response.output_text)

Output:

Recent developments in the stock market have been significantly influenced by escalating trade tensions between the United States and China. On April 5, 2025, President Donald Trump announced an additional 34% tariff on Chinese goods, raising total tariffs to 54% this year. In response, China imposed reciprocal 34% tariffs on U.S. products and introduced export restrictions on certain rare earth elements. These actions led to a sharp global market selloff, with the S&P 500 falling 9% for the week, marking the steepest decline since the pandemic. (reuters.com)

…..


## Escalating US-China Trade Tensions Impact Global Markets:
- [China says 'market has spoken' after US tariffs spark selloff](https://www.reuters.com/world/china/china-says-market-has-spoken-after-us-tariffs-spark-selloff-2025-04-05/?utm_source=openai)
- [Trump touts "economic revolution" as economists warn of recession](https://www.axios.com/2025/04/05/trump-tariffs-stock-market-recession?utm_source=openai)
- [Believe it or not, there were some winners in the stock market this week](https://apnews.com/article/ce81e9ae6fb463dc763dfaa464778343?utm_source=openai)

Quando è attivato, lo strumento di ricerca sul web esegue diverse operazioni, dall’analisi della query alla sintesi di informazioni da più fonti con citazioni appropriate. Questa capacità apre possibilità per applicazioni ricche di informazioni, come strumenti di analisi finanziaria che forniscono insight sui mercati, piattaforme di aggregazione notizie che combinano più fonti o risorse educative che integrano i contenuti principali con ricerche aggiornate.

Un vantaggio chiave di questo strumento è la possibilità di fornire informazioni tempestive senza dover creare e mantenere un’integrazione di ricerca personalizzata o un sistema di web scraping. Lo strumento gestisce il processo di ricerca presentando i risultati con citazioni corrette per mantenere trasparenza sulle fonti.

Ricerca nei file: estrarre informazioni dai documenti

Se la ricerca sul web porta conoscenze esterne nella tua applicazione, lo strumento di ricerca nei file si concentra sullo sblocco delle informazioni nei documenti. Questo tool consente all’API di cercare ed estrarre informazioni da documenti caricati su OpenAI.

Lo strumento di ricerca nei file abilita diverse funzionalità chiave:

• Ricerca tra più tipi di file (PDF, documenti Word, presentazioni, ecc.).
• Individuazione di informazioni specifiche all’interno dei documenti tramite query in linguaggio naturale.
• Estrazione e sintesi di informazioni da più documenti contemporaneamente.
• Fornitura di citazioni a sezioni specifiche dei documenti sorgente.
• Supporto a query complesse che fanno riferimento a informazioni distribuite su più file.

Questa capacità è ideale per casi d’uso di analisi documentale, come l’estrazione di informazioni da contratti legali, l’analisi di articoli di ricerca o la creazione di knowledge base da documentazione tecnica. Lo strumento può identificare sezioni rilevanti in più documenti e sintetizzare le informazioni in risposta a query specifiche.

L’implementazione prevede prima il caricamento dei file sull’endpoint files di OpenAI, quindi il passaggio degli ID dei file alla Responses API al momento della query. Si crea così un flusso di lavoro semplificato per le applicazioni che devono fare riferimento a informazioni specifiche nei documenti senza richiedere ricerche manuali agli utenti.

Computer use: capacità di interazione con le interfacce

Sulla base della comprensione di testo e documenti, lo strumento di computer use estende le capacità dell’AI al campo dell’interazione con le interfacce. Questo tool rappresenta un avanzamento significativo che colma il divario tra comprensione del linguaggio e manipolazione delle UI.

Lo strumento di computer use può eseguire una varietà di interazioni con l’interfaccia:

• Navigare autonomamente siti web e web app.
• Compilare moduli con informazioni appropriate.
• Estrarre dati da pagine web e applicazioni.
• Eseguire processi multi-step su schermate diverse.
• Interagire con elementi come pulsanti, menu a discesa e campi di testo.
• Comprendere il contesto e lo scopo dei diversi elementi dell’interfaccia.

Le applicazioni potenziali includono automazione di processi ripetitivi, assistenza guidata per workflow complessi e miglioramenti di accessibilità per chi ha difficoltà con le interfacce tradizionali. Lo strumento può essere usato per automatizzare la compilazione di moduli, navigare siti complessi o effettuare test delle interfacce utente.

La tecnologia funziona consentendo all’AI di vedere e interagire con gli elementi sullo schermo, comprendere il contesto ed eseguire azioni basate su istruzioni in linguaggio naturale. Questo crea possibilità di automazione e assistenza che altrimenti richiederebbero sviluppo specializzato di codice specifico per l’interfaccia.

Capacità aggiuntive degli strumenti

L’ecosistema di strumenti all’interno della Responses API continua a crescere, con OpenAI che aggiunge regolarmente nuove funzionalità. La documentazione completa degli strumenti copre i dettagli di implementazione per tutti gli strumenti disponibili, mentre l’articolo sui nuovi strumenti per costruire agenti fornisce il contesto strategico dell’evoluzione in corso.

Questi strumenti integrati offrono capacità potenti già pronte, ma molte applicazioni richiedono collegamenti a servizi specializzati o sistemi proprietari. Qui entra in gioco il function calling, che ti permette di estendere la Responses API con i tuoi tool personalizzati e servizi esterni: il focus della prossima sezione.

Function calling nella Responses API

Sebbene gli strumenti integrati offrano funzionalità potenti, molte applicazioni richiedono connessioni a servizi specializzati o sistemi proprietari. Il function calling ti consente di estendere la Responses API con i tuoi strumenti personalizzati, permettendo al modello di decidere quando e come chiamare le tue funzioni in base all’input dell’utente.

Il function calling crea un ponte tra la comprensione del linguaggio dell’AI e i tuoi sistemi esterni, che si tratti di recuperare tassi di cambio, calcolare distanze o verificare la disponibilità di appuntamenti. Questo pattern segue un flusso chiaro:

1. Definisci funzioni che l’AI può usare, specificando parametri e relativi tipi.
2. L’AI decide quando chiamare queste funzioni in base alle richieste dell’utente.
3. Il tuo codice esegue le funzioni con i parametri forniti dall’AI.
4. Ritorni i risultati all’AI, che li incorpora nella sua risposta.

Creare uno strumento di conversione valutaria

Implementiamo come esempio una semplice funzione di conversione valutaria:

# Dictionary of exchange rates (relative to USD)
exchange_rates = {
   "USD": 1.0,
   "EUR": 0.93,
   "GBP": 0.79,
   "JPY": 153.2,
   "CAD": 1.37,
   "AUD": 1.52
}

def convert_currency(amount, from_currency, to_currency):
   """Convert an amount from one currency to another."""
   # Normalize currency codes to uppercase
   from_currency = from_currency.upper()
   to_currency = to_currency.upper()
  
   # Check if currencies are supported
   if from_currency not in exchange_rates:
       return {"error": f"Currency not supported: {from_currency}"}
   if to_currency not in exchange_rates:
       return {"error": f"Currency not supported: {to_currency}"}
  
   # Convert to USD first, then to target currency
   amount_in_usd = amount / exchange_rates[from_currency]
   converted_amount = amount_in_usd * exchange_rates[to_currency]
  
   return {
       "original_amount": amount,
       "from_currency": from_currency,
       "to_currency": to_currency,
       "converted_amount": round(converted_amount, 2)
   }

Questa funzione accetta tre parametri: l’importo da convertire, la valuta di origine e quella di destinazione. Esegue una conversione semplice usando tassi di cambio predefiniti e restituisce un risultato strutturato con i dettagli della conversione.

Definire la funzione per la Responses API

Ora dobbiamo informare il modello della nostra funzione, così da permettergli di decidere quando chiamarla:

from openai import OpenAI
import json

client = OpenAI()

tools = [
   {
       "type": "function",
       "name": "convert_currency",
       "description": "Convert an amount from one currency to another using current exchange rates",
       "parameters": {
           "type": "object",
           "properties": {
               "amount": {
                   "type": "number",
                   "description": "The amount of money to convert"
               },
               "from_currency": {
                   "type": "string",
                   "description": "The currency code to convert from (e.g., USD, EUR, GBP)"
               },
               "to_currency": {
                   "type": "string",
                   "description": "The currency code to convert to (e.g., USD, EUR, GBP)"
               }
           },
           "required": ["amount", "from_currency", "to_currency"],
           "additionalProperties": False
       },
       "strict": True
   }
]

Questa definizione specifica chiaramente:

• Il nome della funzione convert_currency che corrisponde alla nostra funzione Python.
• Una descrizione che spiega quando dovrebbe essere usata.
• Tre parametri obbligatori con relativi tipi e descrizioni.
• Il flag strict: true per garantire che il modello segua esattamente le specifiche dei parametri.

Gestire una richiesta dell’utente

Simuliamo una conversazione in cui un utente chiede una conversione valutaria:

input_messages = [
   {"role": "user", "content": "How much is 100 euros in Japanese yen?"}
]

response = client.responses.create(
   model="gpt-4o",
   input=input_messages,
   tools=tools,
)

Quando il modello vede questa domanda sulla conversione valutaria, riconosce che deve usare la nostra funzione. Identifica automaticamente che:

• L’importo è 100
• La valuta di origine è l’euro (EUR)
• La valuta di destinazione è lo yen giapponese (JPY)

Elaborare la chiamata di funzione

Ora estraiamo i dettagli della chiamata di funzione ed eseguiamo la nostra funzione:

tool_call = response.output[0]
print(f"Function called: {tool_call.name}")
print(f"Arguments: {tool_call.arguments}")

args = json.loads(tool_call.arguments)

# Execute the function with the parameters determined by the model
conversion_result = convert_currency(**args)
print(f"Function results: {conversion_result}")

Il modello ha tradotto la query in linguaggio naturale in parametri strutturati. La nostra funzione esegue poi il calcolo in base a questi parametri e restituisce l’importo convertito.

Restituire i risultati della funzione al modello

Infine, inviamo i risultati al modello affinché generi una risposta fruibile:

input_messages.append(tool_call)  # append model's function call message
input_messages.append(
   {  # append result message
       "type": "function_call_output",
       "call_id": tool_call.call_id,
       "output": json.dumps(conversion_result)
   }
)

response_2 = client.responses.create(
   model="gpt-4o",
   input=input_messages,
   tools=tools,
)
print(response_2.output_text)

Output:

100 euros is equal to 16,473.12 Japanese yen based on current exchange rates.

Il modello ha preso i dati grezzi della conversione e li ha trasformati in una risposta naturale e leggibile. Ha interpretato correttamente il risultato numerico e lo ha presentato in un formato adeguato per le valute.

Mettere tutto insieme

In un’app reale, vorrai incapsulare l’intero processo in un’unica interfaccia che gestisca il flusso della conversazione in modo trasparente. Ecco come potresti creare un assistente completo che gestisce l’intero processo di function calling:

def currency_assistant(user_message, conversation_history=None):
   """A complete assistant that handles currency conversion queries."""
   if conversation_history is None:
       conversation_history = []
  
   # Add the user's new message to the conversation
   conversation_history.append({"role": "user", "content": user_message})
  
   # Define available tools (our currency conversion function)
   tools = [{
       "type": "function",
       "name": "convert_currency",
       "description": "Convert an amount from one currency to another using current exchange rates",
       "parameters": {
           "type": "object",
           "properties": {
               "amount": {
                   "type": "number",
                   "description": "The amount of money to convert"
               },
               "from_currency": {
                   "type": "string",
                   "description": "The currency code to convert from (e.g., USD, EUR, GBP)"
               },
               "to_currency": {
                   "type": "string",
                   "description": "The currency code to convert to (e.g., USD, EUR, GBP)"
               }
           },
           "required": ["amount", "from_currency", "to_currency"],
           "additionalProperties": False
       },
       "strict": True
   }]
  
   # Get initial response from the model
   response = client.responses.create(
       model="gpt-4o",
       input=conversation_history,
       tools=tools,
   )
  
   # Check if the model wants to call a function
   if response.output and isinstance(response.output, list) and response.output[0].type == "function_call":
       tool_call = response.output[0]
      
       # Process the function call
       args = json.loads(tool_call.arguments)
       result = convert_currency(**args)
      
       # Add the function call and its result to the conversation
       conversation_history.append(tool_call)
       conversation_history.append({
           "type": "function_call_output",
           "call_id": tool_call.call_id,
           "output": json.dumps(result)
       })
      
       # Get the final response with the function results incorporated
       final_response = client.responses.create(
           model="gpt-4o",
           input=conversation_history,
           tools=tools,
       )
      
       return final_response.output_text, conversation_history
   else:
       # If no function call was needed, return the direct response
       return response.output_text, conversation_history

# Example usage
response, conversation = currency_assistant("How much is 50 British pounds in Australian dollars?")
print("Assistant:", response)

# Continue the conversation
response, conversation = currency_assistant("And what if I wanted to convert 200 Canadian dollars instead?", conversation)
print("Assistant:", response)

Questa implementazione:

1. Mantiene la cronologia della conversazione per fornire contesto alle domande successive.
2. Gestisce l’intero processo di function calling in un’unica interfaccia.
3. Determina quando il function calling è necessario e quando il modello può rispondere direttamente.
4. Supporta conversazioni multi-turn in cui il contesto precedente è importante.

Con questo approccio, puoi creare esperienze conversazionali fluide in cui gli utenti interagiscono in modo naturale senza accorgersi del complesso function calling che avviene dietro le quinte. L’assistente gestisce il passaggio tra comprensione del linguaggio naturale, chiamate di funzione strutturate e generazione del linguaggio naturale.

La costruzione di applicazioni più complesse può includere:

1. Supporto a più funzioni, ciascuna per diversi tipi di query.
2. Gestione di autenticazione e autorizzazione per operazioni sensibili.
3. Implementazione di gestione errori e ripristino più sofisticati.
4. Aggiunta di logging e monitoraggio per uso e prestazioni delle funzioni.
5. Creazione di interfacce utente che supportino interazioni testuali, vocali o multimodali.

Il function calling consente alla Responses API di collegare gli input in linguaggio naturale con i tuoi servizi e dati. Si crea così un ponte tra le richieste degli utenti e i tuoi sistemi aziendali, permettendo agli utenti di esprimersi in linguaggio semplice mentre l’applicazione gestisce in background i dettagli tecnici.

Oltre al function calling, un’altra potente capacità della Responses API è la generazione di output strutturati. Questa funzione completa il function calling offrendo un modo per ricevere risposte in formati specifici che si allineano alle esigenze della tua applicazione.

Output strutturati con la Responses API

Quando crei applicazioni AI, spesso hai bisogno di risposte in un formato specifico per un’integrazione più semplice con i tuoi sistemi. La Responses API supporta output strutturati che permettono di ricevere dati in un formato ben definito e coerente, anziché testo libero. Questa funzione è particolarmente utile quando devi:

1. Estrarre informazioni specifiche da testo non strutturato.
2. Trasformare input utente in dati strutturati.
3. Garantire formati di risposta coerenti per l’elaborazione a valle.
4. Integrare direttamente gli output dell’AI con database o API.

Gli output strutturati riducono la necessità di parsing e validazioni aggiuntive, rendendo le applicazioni più robuste e facili da mantenere.

Estrarre informazioni di prodotto dalle descrizioni

Esploriamo un esempio pratico: immagina di costruire una piattaforma e-commerce e di dover estrarre automaticamente i dettagli di prodotto da descrizioni non strutturate per popolare il tuo database.

from openai import OpenAI
import json

client = OpenAI()

product_description = """
Our Premium Laptop Backpack is perfect for professionals and students alike.
Made with water-resistant material, it features padded compartments that fit
laptops up to 15.6 inches. The backpack includes 3 main storage areas,
5 smaller pockets, and has an integrated USB charging port. Available in
navy blue, black, and gray. Current retail price: $79.99, though it's
currently on sale for $64.99 until the end of the month.
"""

response = client.responses.create(
   model="gpt-4o",
   input=f"Extract structured product information from this description: {product_description}",
   text={
       "format": {
           "type": "json_schema",
           "name": "product_details",
           "schema": {
               "type": "object",
               "properties": {
                   "product_name": {"type": "string"},
                   "category": {"type": "string"},
                   "features": {"type": "array", "items": {"type": "string"}},
                   "colors": {"type": "array", "items": {"type": "string"}},
                   "pricing": {
                       "type": "object",
                       "properties": {
                           "regular_price": {"type": "number"},
                           "sale_price": {"type": "number"},
                           "currency": {"type": "string"},
                       },
                       "additionalProperties": False,
                       "required": ["regular_price", "sale_price", "currency"],
                   },
               },
               "required": ["product_name", "features", "colors", "pricing","category"],
               "additionalProperties": False,
           },
           "strict": True,
       }
   },
)

product_data = json.loads(response.output_text)
print(json.dumps(product_data, indent=2))

Output:

{
 "product_name": "Premium Laptop Backpack",
 "category": "Backpack",
 "features": [
   "Water-resistant material",
   "Padded compartments for laptops up to 15.6 inches",
   "3 main storage areas",
   "5 smaller pockets",
   "Integrated USB charging port"
 ],
 "colors": [
   "Navy blue",
   "Black",
   "Gray"
 ],
 "pricing": {
   "regular_price": 79.99,
   "sale_price": 64.99,
   "currency": "USD"
 }
}

Questi dati JSON formattati possono ora essere integrati direttamente nel tuo database prodotti, eliminando la necessità di logiche di parsing personalizzate e riducendo le possibilità di errore.

Capire la configurazione degli output strutturati

La chiave per output strutturati efficaci e senza errori è definire correttamente lo schema. Vediamo gli elementi importanti della configurazione:

text={
   "format": {
       "type": "json_schema",        # Specifies we're using JSON Schema
       "name": "product_details",    # A descriptive name for this schema
       "schema": {
           # Your JSON Schema definition here
           "type": "object",
           "properties": {
               # Each property with type information, e.g.
               "product_name": {"type": "string"},
               # ... other properties
           },
           "required": ["product_name", ...], # All other properties
           "additionalProperties": False
       },
       "strict": True                # Enforce schema constraints strictly
   }
}

I componenti più importanti sono:

1. Definizione dello schema: descrive la struttura, incluse tutte le proprietà e i relativi tipi.
2. Campi obbligatori: elenca le proprietà che devono essere incluse nella risposta.
3. Proprietà aggiuntive: quando impostato su False, impedisce l’inclusione di campi extra non definiti nello schema.
4. Modalità strict: quando True, garantisce che il modello segua lo schema alla lettera.

Consigli pratici per usare gli output strutturati

Per ottenere il meglio dagli output strutturati, segui queste linee guida:

1. Progetta lo schema con cura: includi tutti i campi necessari ma mantienilo focalizzato sulle informazioni essenziali.
2. Usa tipi di dato appropriati: abbina i tipi dello schema a come userai i dati (numeri per calcoli, stringhe per testo).
3. Imposta vincoli chiari: usa enum per campi con opzioni limitate e minimum/maximum per i limiti numerici.
4. Testa con input vari: assicurati che lo schema gestisca formati diversi e casi limite.
5. Includi descrizioni chiare: aggiungere descrizioni ai campi aiuta il modello a interpretare quali informazioni estrarre.

Confronto con la Chat Completions API

Mentre la Responses API fornisce output strutturati tramite JSON Schema, la Chat Completions API offre un approccio alternativo con modelli Pydantic, molto più semplice:

from pydantic import BaseModel, Field
from typing import List, Optional
from openai import OpenAI

client = OpenAI()

class ProductDetails(BaseModel):
   product_name: str
   category: str = Field(default=None)
   features: List[str]
   specifications: Optional[dict] = None
   colors: List[str]
   pricing: dict

# With Chat Completions API
completion = client.beta.chat.completions.parse(
   model="gpt-4o",
   messages=[
       {"role": "system", "content": "Extract structured product information."},
       {"role": "user", "content": product_description}
   ],
   response_format=ProductDetails
)

pydantic_product = completion.choices[0].message.parsed

Ogni approccio ha i suoi vantaggi:

• La Responses API usa direttamente JSON Schema standard nella chiamata API
• La Chat Completions API si integra con il sistema di tipi di Python tramite Pydantic

Se vuoi sapere la mia, userei la Chat Completions API per evitare di scrivere JSON Schema a mano. Almeno finché, naturalmente, OpenAI non aggiungerà il supporto ai modelli Pydantic anche alla Responses API.

Per maggiori informazioni, consulta la documentazione della Responses API sugli output strutturati.

Conclusione

La OpenAI Responses API semplifica il modo in cui gli sviluppatori interagiscono con i modelli linguistici, combinando i punti di forza delle API precedenti in un’unica interfaccia che richiede meno codice e complessità. Supporta generazione di testo, analisi di immagini, function calling e output strutturati, rendendo le capacità dell’AI più accessibili e permettendo agli sviluppatori di concentrarsi sulla risoluzione di problemi di business invece che sulle sfide di integrazione.

Proseguendo nel tuo percorso con la Responses API, potresti trovare utili queste risorse per approfondire la comprensione ed espandere le tue capacità di implementazione:

• Working with the OpenAI API
• OpenAI Fundamentals Track
• GPT-4.5: novità dell’ultimo modello di OpenAI
• Deep Research con OpenAI
• Tutorial sul Function Calling in GPT-4.5
• Tutorial sull’API di GPT-4.5
• Tutorial sull’OpenAI Agents SDK