Definire gli schemi delle funzioni per l'API
Scriva le definizioni JSON Schema per le funzioni, le passi nel parametro tools e comprenda come il modello decide quando e come chiamarle.
Definire gli schemi delle funzioni per l'API è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Engineering Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Engineering Academy include 4 lezioni in totale.
Che cos'è il function calling?
Il function calling di OpenAI (ora chiamato tool calling) consente di descrivere le funzioni Python al modello in un formato JSON Schema strutturato. Quando il modello determina che è necessario chiamare una funzione, invece di produrre testo libero restituisce un oggetto JSON strutturato con il nome e gli argomenti della funzione, che il codice può quindi eseguire in modo affidabile.
Struttura del parametro tools
Passi le definizioni delle funzioni all'API nel parametro tools come elenco di oggetti. Ogni oggetto ha un type pari a 'function' e una chiave function contenente il nome, la descrizione e uno JSON Schema che definisce i parametri.
from openai import OpenAI
client = OpenAI()
tools = [
{
'type': 'function',
'function': {
'name': 'get_current_weather',
'description': 'Get the current weather in a given location.',
'parameters': {
'type': 'object',
'properties': {
'location': {
'type': 'string',
'description': 'City and country, e.g. London, UK'
},
'unit': {
'type': 'string',
'enum': ['celsius', 'fahrenheit'],
'description': 'Temperature unit to use.'
}
},
'required': ['location']
}
}
}
]JSON Schema per i parametri
Il campo parameters segue la specifica JSON Schema. Utilizzi type per specificare string, number, integer, boolean, array o object. Utilizzi description per ogni proprietà, così da spiegare al modello il significato del campo. Elenchi i campi obbligatori nell'array required: i campi facoltativi possono essere omessi da required.
# A more complex schema with multiple types
create_event_tool = {
'type': 'function',
'function': {
'name': 'create_calendar_event',
'description': 'Create a new calendar event. Use when the user wants to schedule a meeting or appointment.',
'parameters': {
'type': 'object',
'properties': {
'title': {'type': 'string', 'description': 'Event title.'},
'start_time': {'type': 'string', 'description': 'ISO 8601 datetime, e.g. 2024-03-15T14:00:00.'},
'duration_minutes': {'type': 'integer', 'description': 'Duration in minutes.', 'minimum': 5},
'attendees': {
'type': 'array',
'items': {'type': 'string'},
'description': 'List of email addresses of attendees.'
},
'location': {'type': 'string', 'description': 'Physical or virtual meeting location.'}
},
'required': ['title', 'start_time', 'duration_minutes']
}
}
}Effettuare la chiamata API con gli strumenti
Passi direttamente l'elenco tools a chat.completions.create. Il modello può rispondere con un normale messaggio di testo, se è in grado di rispondere senza una funzione, oppure con un oggetto tool_calls che Le indica di eseguire una funzione. Controlli sempre finish_reason per sapere in quale dei due casi si trova.
response = client.chat.completions.create(
model='gpt-4o',
messages=[
{'role': 'user', 'content': 'What is the weather in Tokyo?'}
],
tools=tools
)
print('Finish reason:', response.choices[0].finish_reason)
# 'tool_calls' means the model wants to call a function
# 'stop' means the model gave a regular text response
choice = response.choices[0].message
if response.choices[0].finish_reason == 'tool_calls':
print('Model wants to call:', choice.tool_calls[0].function.name)Controllare la selezione degli strumenti con tool_choice
Il parametro tool_choice controlla se il modello deve chiamare una funzione o può scegliere liberamente. Impostandolo su 'auto', lascia che sia il modello a decidere. Impostandolo su 'required', forza una chiamata allo strumento. Impostandolo sul nome di una funzione specifica, forza la chiamata esattamente a quella funzione: è utile per le attività di estrazione in cui desidera sempre un output strutturato.
# Force the model to always call extract_contact
response = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': 'Hi, I am John Smith, john@example.com, +1-555-0100.'}],
tools=[extract_contact_tool],
tool_choice={'type': 'function', 'function': {'name': 'extract_contact'}}
)
# With tool_choice forced, finish_reason will always be 'tool_calls'Campi enum per scelte vincolate
Utilizzi il campo enum nel Suo JSON Schema ogni volta che un parametro deve essere limitato a un insieme fisso di valori. Questo migliora notevolmente l'affidabilità: il modello ha molte meno probabilità di inventare un'opzione non valida quando può vedere nel schema l'elenco esatto dei valori consentiti.
classify_sentiment_tool = {
'type': 'function',
'function': {
'name': 'classify_sentiment',
'description': 'Classify the sentiment of a customer review.',
'parameters': {
'type': 'object',
'properties': {
'sentiment': {
'type': 'string',
'enum': ['positive', 'negative', 'neutral', 'mixed'],
'description': 'The sentiment classification.'
},
'confidence': {
'type': 'number',
'minimum': 0.0,
'maximum': 1.0,
'description': 'Model confidence from 0 to 1.'
}
},
'required': ['sentiment', 'confidence']
}
}
}Schemi JSON per oggetti annidati
JSON Schema supporta gli oggetti annidati. Utilizzi 'type': 'object' con le proprie properties per definire strutture di dati gerarchiche complesse. È ideale per estrarre dati strutturati da testo non strutturato, come email o documenti.
extract_order_tool = {
'type': 'function',
'function': {
'name': 'extract_order',
'description': 'Extract order details from a customer email.',
'parameters': {
'type': 'object',
'properties': {
'customer': {
'type': 'object',
'properties': {
'name': {'type': 'string'},
'email': {'type': 'string', 'format': 'email'}
},
'required': ['name']
},
'items': {
'type': 'array',
'items': {
'type': 'object',
'properties': {
'product_id': {'type': 'string'},
'quantity': {'type': 'integer', 'minimum': 1}
},
'required': ['product_id', 'quantity']
}
}
},
'required': ['customer', 'items']
}
}
}Generazione di schemi da modelli Pydantic
Scrivere JSON Schema manualmente è noioso e soggetto a errori. Definisca invece la struttura dei dati come un modello Pydantic e utilizzi .schema() per generare automaticamente il JSON Schema. In questo modo ottiene anche la convalida a livello Python quando deserializza la risposta del modello.
from pydantic import BaseModel, Field
from typing import Optional, List
class ContactInfo(BaseModel):
name: str = Field(description='Full name of the person.')
email: Optional[str] = Field(None, description='Email address.')
phone: Optional[str] = Field(None, description='Phone number in E.164 format.')
company: Optional[str] = Field(None, description='Company or organization.')
# Auto-generate the JSON Schema
schema = ContactInfo.schema()
# Build the tool definition
extract_contact_tool = {
'type': 'function',
'function': {
'name': 'extract_contact',
'description': 'Extract contact information from text.',
'parameters': schema
}
}Scrivere descrizioni efficaci delle funzioni
La descrizione della funzione è il segnale principale che il modello utilizza per decidere quando chiamare uno strumento. Una buona descrizione specifica il caso d'uso, indica quando la funzione deve e non deve essere chiamata e descrive quale sarà l'output. Le descrizioni vaghe inducono il modello a chiamare la funzione sbagliata o a non riconoscere le occasioni in cui chiamare quella corretta.
- Vaga: 'Get weather data.'
- Buona: 'Get the current weather conditions for a specific city. Use when the user explicitly asks about weather in a named location. Returns temperature, conditions, and humidity.'
Modalità strict per garantire il rispetto dello schema
La strict mode di OpenAI per gli output strutturati garantisce che il modello produca JSON che corrisponde esattamente al Suo schema, senza campi aggiuntivi né campi obbligatori mancanti. La abiliti impostando 'strict': true nella definizione della funzione. Nota: la strict mode richiede additionalProperties: false in tutti gli oggetti dello schema.
strict_tool = {
'type': 'function',
'function': {
'name': 'classify_ticket',
'description': 'Classify a support ticket into category and priority.',
'strict': True, # Enable strict schema adherence
'parameters': {
'type': 'object',
'additionalProperties': False, # Required for strict mode
'properties': {
'category': {
'type': 'string',
'enum': ['billing', 'technical', 'account', 'other']
},
'priority': {
'type': 'string',
'enum': ['low', 'medium', 'high', 'urgent']
}
},
'required': ['category', 'priority']
}
}
}Testare gli schemi delle funzioni
Prima della distribuzione, testi ogni schema di funzione con input diversificati: casi normali, casi limite e input avversari. Verifichi che il modello chiami la funzione corretta, produca tipi di argomento validi, gestisca correttamente i campi facoltativi e rispetti i vincoli enum. Utilizzi OpenAI Playground per iterare rapidamente prima di scrivere il codice per la produzione.
Verifica rapida
Verifichi la Sua comprensione della definizione degli schemi delle funzioni per l'API OpenAI.
Riepilogo della lezione
In questa lezione ha imparato che: gli schemi delle funzioni utilizzano JSON Schema per definire i tipi, le descrizioni e i vincoli dei parametri, tool_choice controlla se il modello deve chiamare una funzione o può scegliere liberamente e i modelli Pydantic possono generare automaticamente JSON Schema, riducendo la necessità di scrivere manualmente gli schemi. Ora imparerà a gestire le chiamate agli strumenti nella Sua applicazione, rilevandole, eseguendole e inviando indietro i risultati.
Domande Frequenti
La lezione «Definire gli schemi delle funzioni per l'API» è gratuita?
Sì — il testo completo di «Definire gli schemi delle funzioni per l'API» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Engineering Academy, passa a CoddyKit PRO. Il corso AI Engineering Academy include 4 lezioni in totale.
Cosa imparerò in «Definire gli schemi delle funzioni per l'API»?
Scriva le definizioni JSON Schema per le funzioni, le passi nel parametro tools e comprenda come il modello decide quando e come chiamarle. Eserciti AI Engineering Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Engineering Academy?
Non è richiesta alcuna esperienza precedente. AI Engineering Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.
Quanto tempo richiede la lezione «Definire gli schemi delle funzioni per l'API»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Engineering Academy?
Sì. Ogni lezione AI Engineering Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Definire gli schemi delle funzioni per l'API
- Elaborare le chiamate agli strumenti nell'applicazione
- Chiamate di funzioni in parallelo
- Creare un'interfaccia al database in linguaggio naturale