Comment utiliser l’appel de fonction avec Azure OpenAI Service (Préversion)
Les dernières versions de gpt-35-turbo et gpt-4 sont affinées pour fonctionner avec des fonctions et sont en mesure de déterminer quand et comment une fonction doit être appelée. Si une ou plusieurs fonctions sont incluses dans votre requête, le modèle détermine si l’une des fonctions doit être appelée en fonction du contexte de l’invite. Lorsque le modèle détermine qu’une fonction doit être appelée, elle répond avec un objet JSON, y compris les arguments de la fonction.
Les modèles formulent des appels d’API et des sorties de données de structure, toutes basées sur les fonctions que vous spécifiez. Il est important de noter que même si les modèles peuvent générer ces appels, c’est à vous de les exécuter, ce qui vous permet de garder le contrôle.
À un niveau élevé, vous pouvez décomposer l’utilisation des fonctions en trois étapes :
- Appeler l’API d’achèvement de conversation avec vos fonctions et l’entrée de l’utilisateur
- Utiliser la réponse du modèle pour appeler votre API ou fonction
- Appelez à nouveau l’API d’achèvement de conversation, y compris la réponse de votre fonction pour obtenir une réponse finale
Important
Les paramètres functions et function_call ont été déconseillés avec la publication de la version 2023-12-01-preview de l’API. Le remplacement de functions est le paramètre tools. Le remplacement de function_call est le paramètre tool_choice.
Prise en charge de l’appel de fonction
Appel de fonction parallèle
gpt-35-turbo(1106)gpt-35-turbo(0125)gpt-4(1106-Preview)gpt-4(préversion 0125)gpt-4(vision-préversion)gpt-4(2024-04-09)gpt-4o(2024-05-13)gpt-4o-mini(18-07-2024)
La prise en charge des fonctions parallèles a été ajoutée pour la première fois dans la version de l’API 2023-12-01-preview
Appel de fonction de base avec des outils
- Tous les modèles qui prennent en charge l’appel de fonction parallèle
gpt-4(0613)gpt-4-32k(0613)gpt-35-turbo-16k(0613)gpt-35-turbo(0613)
Exemple d’appel d’outil/fonction unique
Tout d’abord, nous allons commencer par un simple appel de fonction jouet qui peut vérifier l’heure dans trois emplacements codés en dur avec un seul outil/fonction défini. Nous avons ajouté des instructions d’impression pour faciliter l’exécution du code :
import os
import json
from openai import AzureOpenAI
from datetime import datetime
from zoneinfo import ZoneInfo
# Initialize the Azure OpenAI client
client = AzureOpenAI(
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"),
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview"
)
# Define the deployment you want to use for your chat completions API calls
deployment_name = "<YOUR_DEPLOYMENT_NAME_HERE>"
# Simplified timezone data
TIMEZONE_DATA = {
"tokyo": "Asia/Tokyo",
"san francisco": "America/Los_Angeles",
"paris": "Europe/Paris"
}
def get_current_time(location):
"""Get the current time for a given location"""
print(f"get_current_time called with location: {location}")
location_lower = location.lower()
for key, timezone in TIMEZONE_DATA.items():
if key in location_lower:
print(f"Timezone found for {key}")
current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
return json.dumps({
"location": location,
"current_time": current_time
})
print(f"No timezone data found for {location_lower}")
return json.dumps({"location": location, "current_time": "unknown"})
def run_conversation():
# Initial user message
messages = [{"role": "user", "content": "What's the current time in San Francisco"}] # Single function call
#messages = [{"role": "user", "content": "What's the current time in San Francisco, Tokyo, and Paris?"}] # Parallel function call with a single tool/function defined
# Define the function for the model
tools = [
{
"type": "function",
"function": {
"name": "get_current_time",
"description": "Get the current time in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name, e.g. San Francisco",
},
},
"required": ["location"],
},
}
}
]
# First API call: Ask the model to use the function
response = client.chat.completions.create(
model=deployment_name,
messages=messages,
tools=tools,
tool_choice="auto",
)
# Process the model's response
response_message = response.choices[0].message
messages.append(response_message)
print("Model's response:")
print(response_message)
# Handle function calls
if response_message.tool_calls:
for tool_call in response_message.tool_calls:
if tool_call.function.name == "get_current_time":
function_args = json.loads(tool_call.function.arguments)
print(f"Function arguments: {function_args}")
time_response = get_current_time(
location=function_args.get("location")
)
messages.append({
"tool_call_id": tool_call.id,
"role": "tool",
"name": "get_current_time",
"content": time_response,
})
else:
print("No tool calls were made by the model.")
# Second API call: Get the final response from the model
final_response = client.chat.completions.create(
model=deployment_name,
messages=messages,
)
return final_response.choices[0].message.content
# Run the conversation and print the result
print(run_conversation())
Sortie :
Model's response:
ChatCompletionMessage(content=None, role='assistant', function_call=None, tool_calls=[ChatCompletionMessageToolCall(id='call_pOsKdUlqvdyttYB67MOj434b', function=Function(arguments='{"location":"San Francisco"}', name='get_current_time'), type='function')])
Function arguments: {'location': 'San Francisco'}
get_current_time called with location: San Francisco
Timezone found for san francisco
The current time in San Francisco is 09:24 AM.
Si nous utilisons un modèle de déploiement qui prend en charge les appels de fonction parallèle, nous pourrions convertir cela en exemple d’appel de fonction parallèle en modifiant le tableau des messages pour demander l’heure dans plusieurs emplacements au lieu d’un seul.
Pour ce faire, échangez les commentaires dans ces deux lignes :
messages = [{"role": "user", "content": "What's the current time in San Francisco"}] # Single function call
#messages = [{"role": "user", "content": "What's the current time in San Francisco, Tokyo, and Paris?"}] # Parallel function call with a single tool/function defined
Pour obtenir le résultat suivant, puis exécutez à nouveau le code :
#messages = [{"role": "user", "content": "What's the current time in San Francisco"}] # Single function call
messages = [{"role": "user", "content": "What's the current time in San Francisco, Tokyo, and Paris?"}] # Parallel function call with a single tool/function defined
Cela génère la sortie suivante :
Sortie :
Model's response:
ChatCompletionMessage(content=None, role='assistant', function_call=None, tool_calls=[ChatCompletionMessageToolCall(id='call_IjcAVz9JOv5BXwUx1jd076C1', function=Function(arguments='{"location": "San Francisco"}', name='get_current_time'), type='function'), ChatCompletionMessageToolCall(id='call_XIPQYTCtKIaNCCPTdvwjkaSN', function=Function(arguments='{"location": "Tokyo"}', name='get_current_time'), type='function'), ChatCompletionMessageToolCall(id='call_OHIB5aJzO8HGqanmsdzfytvp', function=Function(arguments='{"location": "Paris"}', name='get_current_time'), type='function')])
Function arguments: {'location': 'San Francisco'}
get_current_time called with location: San Francisco
Timezone found for san francisco
Function arguments: {'location': 'Tokyo'}
get_current_time called with location: Tokyo
Timezone found for tokyo
Function arguments: {'location': 'Paris'}
get_current_time called with location: Paris
Timezone found for paris
As of now, the current times are:
- **San Francisco:** 11:15 AM
- **Tokyo:** 03:15 AM (next day)
- **Paris:** 08:15 PM
Les appels de fonction parallèles vous permettent d'effectuer plusieurs appels de fonction ensemble, ce qui permet une exécution parallèle et la récupération des résultats. Cela réduit le nombre d'appels à l'API et peut améliorer les performances globales.
Par exemple, dans notre application de période simple, nous avons récupéré plusieurs heure en même temps. Cela entraîne un message de saisie semi-automatique de conversation avec trois appels de fonction dans le tableau tool_calls, chacun avec un id unique. Si vous souhaitez répondre à ces appels de fonction, vous devez ajouter trois nouveaux messages à la conversation, chacun contenant le résultat d’un appel de fonction, avec un référencement tool_call_id au id de tools_calls.
Pour forcer le modèle à appeler une fonction spécifique, définissez le paramètre tool_choice avec un nom de fonction spécifique. Vous pouvez également forcer le modèle à générer un message accessible par l’utilisateur en définissant tool_choice: "none".
Remarque
Le comportement par défaut (tool_choice: "auto") est que le modèle décide de son propre choix quant à l’appel d’une fonction et, si c’est le cas, quelle fonction appeler.
Appel de fonction parallèle avec plusieurs fonctions
Nous allons maintenant passer à un autre exemple d’appel de fonction jouet, cette fois-ci avec deux outils/fonctions différents définis.
import os
import json
from openai import AzureOpenAI
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
# Initialize the Azure OpenAI client
client = AzureOpenAI(
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"),
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview"
)
# Provide the model deployment name you want to use for this example
deployment_name = "YOUR_DEPLOYMENT_NAME_HERE"
# Simplified weather data
WEATHER_DATA = {
"tokyo": {"temperature": "10", "unit": "celsius"},
"san francisco": {"temperature": "72", "unit": "fahrenheit"},
"paris": {"temperature": "22", "unit": "celsius"}
}
# Simplified timezone data
TIMEZONE_DATA = {
"tokyo": "Asia/Tokyo",
"san francisco": "America/Los_Angeles",
"paris": "Europe/Paris"
}
def get_current_weather(location, unit=None):
"""Get the current weather for a given location"""
print(f"get_current_weather called with location: {location}, unit: {unit}")
for key in WEATHER_DATA:
if key in location_lower:
print(f"Weather data found for {key}")
weather = WEATHER_DATA[key]
return json.dumps({
"location": location,
"temperature": weather["temperature"],
"unit": unit if unit else weather["unit"]
})
print(f"No weather data found for {location_lower}")
return json.dumps({"location": location, "temperature": "unknown"})
def get_current_time(location):
"""Get the current time for a given location"""
print(f"get_current_time called with location: {location}")
location_lower = location.lower()
for key, timezone in TIMEZONE_DATA.items():
if key in location_lower:
print(f"Timezone found for {key}")
current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
return json.dumps({
"location": location,
"current_time": current_time
})
print(f"No timezone data found for {location_lower}")
return json.dumps({"location": location, "current_time": "unknown"})
def run_conversation():
# Initial user message
messages = [{"role": "user", "content": "What's the weather and current time in San Francisco, Tokyo, and Paris?"}]
# Define the functions for the model
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": "The city name, e.g. San Francisco",
},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["location"],
},
}
},
{
"type": "function",
"function": {
"name": "get_current_time",
"description": "Get the current time in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name, e.g. San Francisco",
},
},
"required": ["location"],
},
}
}
]
# First API call: Ask the model to use the functions
response = client.chat.completions.create(
model=deployment_name,
messages=messages,
tools=tools,
tool_choice="auto",
)
# Process the model's response
response_message = response.choices[0].message
messages.append(response_message)
print("Model's response:")
print(response_message)
# Handle function calls
if response_message.tool_calls:
for tool_call in response_message.tool_calls:
function_name = tool_call.function.name
function_args = json.loads(tool_call.function.arguments)
print(f"Function call: {function_name}")
print(f"Function arguments: {function_args}")
if function_name == "get_current_weather":
function_response = get_current_weather(
location=function_args.get("location"),
unit=function_args.get("unit")
)
elif function_name == "get_current_time":
function_response = get_current_time(
location=function_args.get("location")
)
else:
function_response = json.dumps({"error": "Unknown function"})
messages.append({
"tool_call_id": tool_call.id,
"role": "tool",
"name": function_name,
"content": function_response,
})
else:
print("No tool calls were made by the model.")
# Second API call: Get the final response from the model
final_response = client.chat.completions.create(
model=deployment_name,
messages=messages,
)
return final_response.choices[0].message.content
# Run the conversation and print the result
print(run_conversation())
Sortie
Model's response:
ChatCompletionMessage(content=None, role='assistant', function_call=None, tool_calls=[ChatCompletionMessageToolCall(id='call_djHAeQP0DFEVZ2qptrO0CYC4', function=Function(arguments='{"location": "San Francisco", "unit": "celsius"}', name='get_current_weather'), type='function'), ChatCompletionMessageToolCall(id='call_q2f1HPKKUUj81yUa3ITLOZFs', function=Function(arguments='{"location": "Tokyo", "unit": "celsius"}', name='get_current_weather'), type='function'), ChatCompletionMessageToolCall(id='call_6TEY5Imtr17PaB4UhWDaPxiX', function=Function(arguments='{"location": "Paris", "unit": "celsius"}', name='get_current_weather'), type='function'), ChatCompletionMessageToolCall(id='call_vpzJ3jElpKZXA9abdbVMoauu', function=Function(arguments='{"location": "San Francisco"}', name='get_current_time'), type='function'), ChatCompletionMessageToolCall(id='call_1ag0MCIsEjlwbpAqIXJbZcQj', function=Function(arguments='{"location": "Tokyo"}', name='get_current_time'), type='function'), ChatCompletionMessageToolCall(id='call_ukOu3kfYOZR8lpxGRpdkhhdD', function=Function(arguments='{"location": "Paris"}', name='get_current_time'), type='function')])
Function call: get_current_weather
Function arguments: {'location': 'San Francisco', 'unit': 'celsius'}
get_current_weather called with location: San Francisco, unit: celsius
Weather data found for san francisco
Function call: get_current_weather
Function arguments: {'location': 'Tokyo', 'unit': 'celsius'}
get_current_weather called with location: Tokyo, unit: celsius
Weather data found for tokyo
Function call: get_current_weather
Function arguments: {'location': 'Paris', 'unit': 'celsius'}
get_current_weather called with location: Paris, unit: celsius
Weather data found for paris
Function call: get_current_time
Function arguments: {'location': 'San Francisco'}
get_current_time called with location: San Francisco
Timezone found for san francisco
Function call: get_current_time
Function arguments: {'location': 'Tokyo'}
get_current_time called with location: Tokyo
Timezone found for tokyo
Function call: get_current_time
Function arguments: {'location': 'Paris'}
get_current_time called with location: Paris
Timezone found for paris
Here's the current information for the three cities:
### San Francisco
- **Time:** 09:13 AM
- **Weather:** 72°C (quite warm!)
### Tokyo
- **Time:** 01:13 AM (next day)
- **Weather:** 10°C
### Paris
- **Time:** 06:13 PM
- **Weather:** 22°C
Is there anything else you need?
Important
La réponse JSON peut ne pas toujours être valide. Vous devez donc ajouter une logique supplémentaire à votre code pour pouvoir gérer les erreurs. Pour certains cas d’usage, il peut s'avérer nécessaire de procéder à un réglage précis pour améliorer les performances d’appel de fonction.
Ingénierie d’invite avec des fonctions
Lorsque vous définissez une fonction dans le cadre de votre demande, les détails sont injectés dans le message système à l’aide de la syntaxe spécifique sur laquelle le modèle a été entraîné. Cela signifie que les fonctions consomment des jetons dans votre invite et que vous pouvez appliquer des techniques d’ingénierie d’invite pour optimiser les performances de vos appels de fonction. Le modèle utilise le contexte complet de l’invite pour déterminer si une fonction doit être appelée, y compris la définition de la fonction, le message système et les messages utilisateur.
Amélioration de la qualité et de la fiabilité
Si le modèle n’appelle pas votre fonction quand vous vous attendez ou comme prévu, vous pouvez essayer d’améliorer la qualité de plusieurs éléments.
Fournissez plus de détails dans votre définition de fonction
Il est important de fournir une description explicite description de la fonction et de fournir des descriptions pour tous les paramètres qui peuvent ne pas être évidents pour le modèle. Par exemple, dans la description du paramètre location, vous pouvez inclure des détails supplémentaires et des exemples sur le format de l’emplacement.
"location": {
"type": "string",
"description": "The location of the hotel. The location should include the city and the state's abbreviation (i.e. Seattle, WA or Miami, FL)"
},
Fournir plus de contexte dans le message système
Le message système peut également être utilisé pour fournir davantage de contexte au modèle. Par exemple, si vous avez une fonction appelée search_hotels, vous pouvez inclure un message système comme le suivant pour indiquer au modèle d’appeler la fonction lorsqu’un utilisateur demande de l’aide pour trouver un hôtel.
{"role": "system", "content": "You're an AI assistant designed to help users search for hotels. When a user asks for help finding a hotel, you should call the search_hotels function."}
Demander au modèle de poser des questions de clarification
Dans certains cas, vous souhaitez demander au modèle de poser des questions de clarification afin d’éviter d’effectuer des hypothèses sur les valeurs à utiliser avec les fonctions. Par exemple, avec search_hotels vous souhaitez que le modèle demande une clarification si la demande de l’utilisateur n’a pas inclus de détails sur location. Pour demander au modèle de poser une question de clarification, vous pouvez inclure du contenu comme dans l’exemple suivant dans votre message système.
{"role": "system", "content": "Don't make assumptions about what values to use with functions. Ask for clarification if a user request is ambiguous."}
Réduction des erreurs
Un autre domaine où l’ingénierie rapide peut être utile est la réduction des erreurs dans les appels de fonction. Les modèles sont entraînés pour générer des appels de fonction correspondant au schéma que vous définissez, mais les modèles produisent un appel de fonction qui ne correspond pas au schéma que vous avez défini ou essayez d’appeler une fonction que vous n’avez pas inclus.
Si vous constatez que le modèle génère des appels de fonction qui n’ont pas été fournis, essayez d’inclure une phrase dans le message système qui indique "Only use the functions you have been provided with.".
Utilisation responsable de l’appel de fonction
Comme tout système IA, l’utilisation de l’appel de fonction pour intégrer des modèles de langage à d’autres outils et systèmes présente des risques potentiels. Il est important de comprendre les risques que les appels de fonction peuvent présenter et de prendre des mesures pour vous assurer d’utiliser les fonctionnalités de manière responsable.
Voici quelques conseils pour vous aider à utiliser les fonctions en toute sécurité :
- Valider les appels de fonction : vérifiez toujours les appels de fonction générés par le modèle. Cela inclut la vérification des paramètres, de la fonction en cours d’appel et la vérification de l’alignement de l’appel avec l’action prévue.
- Utiliser des données et des outils approuvés : utilisez uniquement les données provenant de sources approuvées et vérifiées. Les données non approuvées dans la sortie d’une fonction peuvent être utilisées pour indiquer au modèle d’écrire des appels de fonction d’une manière autre que celle prévue.
- Respectez le principe des privilèges minimum : accordez uniquement l’accès minimal nécessaire à la fonction pour effectuer son travail. Cela réduit l’impact potentiel en cas d’utilisation incorrecte ou d’exploitation d’une fonction. Par exemple, si vous utilisez des appels de fonction pour interroger une base de données, vous devez uniquement accorder à votre application un accès en lecture seule à la base de données. Vous ne devez pas non plus dépendre uniquement de l’exclusion de fonctionnalités dans la définition de fonction en tant que contrôle de sécurité.
- Prenez en compte Real-World Impact : tenez compte de l’impact réel des appels de fonction que vous prévoyez d’exécuter, en particulier ceux qui déclenchent des actions telles que l’exécution de code, la mise à jour des bases de données ou l’envoi de notifications.
- Implémenter les étapes de confirmation de l’utilisateur : en particulier pour les fonctions qui effectuent des actions, nous vous recommandons d’inclure une étape dans laquelle l’utilisateur confirme l’action avant son exécution.
Pour en savoir plus sur nos recommandations sur l’utilisation responsable des modèles Azure OpenAI, consultez Vue d’ensemble des pratiques d’IA responsable pour les modèles Azure OpenAI.
Étapes suivantes
- En savoir plus sur Azure OpenAI.
- Consultez le référentiel GitHub Azure OpenAI Samples (uniquement disponible en anglais) pour découvrir d’autres exemples d’utilisation de fonctions
- Prise en main du modèle GPT-35-Turbo avec le Démarrage rapide GPT-35-Turbo.