Partager via

Comment utiliser l’appel de fonction avec Azure OpenAI dans les modèles Microsoft Foundry

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 :

  1. Appeler l’API d’achèvement de conversation avec vos fonctions et l’entrée de l’utilisateur
  2. Utiliser la réponse du modèle pour appeler votre API ou fonction
  3. Rappelez l’API de complétions de conversation, y compris la réponse de votre fonction pour obtenir une réponse finale

Exemple d’appel d’outil/fonction unique

Tout d’abord, illustrez un appel d'une fonction simple qui peut vérifier l'heure dans trois emplacements codés en dur avec un seul outil défini. Nous avons ajouté des instructions d’impression pour faciliter l’exécution du code :

import os
import json
from openai import OpenAI
from datetime import datetime
from zoneinfo import ZoneInfo
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

# 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())

Output:

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 déploiement de modèle qui prend en charge les appels de fonction parallèles, nous pourrions convertir cela en exemple d’appel de fonction parallèle en modifiant le tableau de messages pour demander le temps dans plusieurs emplacements au lieu d’un.

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 réexécutez 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 :

Output:

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 d’heure simple, nous avons récupéré plusieurs heures en même temps. Cela a entraîné un message de complétion de chat 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 une référence 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 lui-même d’appeler ou non 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 de mini-appel de fonction, cette fois-ci avec deux outils/fonctions différents définis.

import os
import json
from openai import OpenAI
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

# 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"""
    location_lower = location.lower()
    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 de requête 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 requête et que vous pouvez appliquer des techniques d’ingénierie de requête 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 au moment ou de la manière à laquelle vous vous attendez, il existe quelques actions que vous pouvez essayer pour améliorer la qualité.

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 prennent des actions, nous vous recommandons d’inclure une étape où l’utilisateur confirme l’action avant l’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.

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 des appels de fonction

Appel de fonction parallèle

  • gpt-35-turbo (1106)
  • gpt-35-turbo (0125)
  • gpt-4 (2024-04-09)
  • gpt-4o (2024-05-13)
  • gpt-4o (2024-08-06)
  • gpt-4o (2024-11-20)
  • gpt-4o-mini (2024-07-18)
  • gpt-4.1 (2025-04-14)
  • gpt-4.1-mini (2025-04-14)
  • gpt-5 (2025-08-07)
  • gpt-5-mini (2025-08-07)
  • gpt-5-nano (2025-08-07)
  • gpt-5-codex (2025-09-11)
  • gpt-5.1 (2025-11-13)
  • gpt-5.1-chat (2025-11-13)
  • gpt-5.1-codex (2025-11-13)
  • gpt-5.1-codex-mini (2025-11-13)
  • gpt-5.1-codex-max (2025-12-04)
  • gpt-5.2 (2025-12-11)
  • gpt-5.2-chat (2025-12-11)

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-5-pro (2025-10-06)
  • codex-mini (2025-05-16)
  • o3-pro (2025-06-10)
  • o4-mini (2025-04-16)
  • o3 (2025-04-16)
  • gpt-4.1-nano (2025-04-14)
  • o3-mini (2025-01-31)
  • o1 (2024-12-17)

Remarque

Le paramètre tool_choice est désormais pris en charge avec o3-mini et o1. Pour plus d’informations, consultez le guide des modèles de raisonnement.

Important

Les descriptions des outils/fonctions sont actuellement limitées à 1 024 caractères avec Azure OpenAI. Nous allons mettre à jour cet article si cette limite est modifiée.

Étapes suivantes

  • Last updated on