Sdílet prostřednictvím

Jak používat volání funkcí s Azure OpenAI v modelech Microsoft Foundry

Pokud je jedna nebo více funkcí součástí vašeho požadavku, model určí, jestli by se některá z funkcí měla volat na základě kontextu výzvy. Když model určí, že se má funkce volat, odpoví objektem JSON, včetně argumentů funkce.

Modely formulují volání rozhraní API a strukturují výstupy dat, a to vše na základě zadaných funkcí. Je důležité si uvědomit, že zatímco modely můžou tato volání generovat, je na vás je spustit a zajistit, abyste udrželi kontrolu.

Na vysoké úrovni můžete rozdělit práci s funkcemi do tří kroků:

  1. Zavolejte rozhraní API pro dokončení chatu s vašimi funkcemi a vstupem uživatele
  2. Použití odpovědi modelu k volání rozhraní API nebo funkce
  3. Znovu volejte rozhraní API pro dokončování chatu, včetně odpovědi z vaší funkce, abyste získali konečnou odpověď.

Příklad volání jednoho nástroje nebo funkce

Nejprve předvedeme ukázkové volání funkce, které může zkontrolovat čas ve třech pevně daných místech pomocí definované funkce/nástroje. Přidali jsme příkazy print, které usnadňují provádění kódu:

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

Výstup:

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.

Pokud používáme nasazení modelu, které podporuje paralelní volání funkcí, můžeme ho převést na příklad volání paralelní funkce tak, že změníme pole zpráv tak, aby místo jednoho požadovalo čas v několika umístěních.

Chcete-li toho dosáhnout, prohoďte komentáře v těchto dvou řádcích.

    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

Aby to vypadalo takto, spusťte kód znovu.

    #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

Tím se vygeneruje následující výstup:

Výstup:

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

Paralelní volání funkcí umožňují společně provádět více volání funkcí, což umožňuje paralelní spouštění a načítání výsledků. Tím se sníží počet volání rozhraní API, které je potřeba provést, a může zlepšit celkový výkon.

Například v naší jednoduché časové aplikaci jsme načetli více časů současně. Výsledkem je zpráva o dokončení chatu se třemi voláními funkce v tool_calls poli, z nichž každý má jedinečný id. Pokud byste chtěli reagovat na tato volání funkcí, přidali byste do konverzace tři nové zprávy, z nichž každá obsahuje výsledek jednoho volání funkce, s tool_call_id odkazující na id z tools_calls.

Chcete-li vynutit, aby model volal konkrétní funkci, nastavte tool_choice parametr s konkrétním názvem funkce. Model můžete také vynutit, aby vygeneroval uživatelskou zprávu nastavením tool_choice: "none".

Poznámka:

Výchozí chování (tool_choice: "auto") je, aby se model sám rozhodl, jestli má volat funkci, a pokud ano, která funkce se má volat.

Paralelní volání funkcí s více funkcemi

Teď si ukážeme další příklad volání ukázkové funkce, tentokrát se dvěma různými nástroji nebo funkcemi definovanými.

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

Výstup

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?

Důležité

Odpověď JSON nemusí být vždy platná, takže je potřeba do kódu přidat další logiku, aby bylo možné zpracovat chyby. V některých případech použití můžete zjistit, že k vylepšení výkonu volání funkcí potřebujete použít jemné ladění.

Navrhování promptů s využitím funkcí

Když definujete funkci jako součást požadavku, podrobnosti se vloží do systémové zprávy pomocí konkrétní syntaxe, na které byl model natrénován. To znamená, že funkce spotřebovávají tokeny v promptu a že můžete použít techniky inženýrství promptu k optimalizaci výkonu volání funkcí. Model používá úplný kontext výzvy k určení, jestli by měla být volána funkce, včetně definice funkce, systémové zprávy a zpráv uživatelů.

Zlepšení kvality a spolehlivosti

Pokud model nevolá vaši funkci, kdy nebo jak očekáváte, existuje několik věcí, které můžete zkusit pro zlepšení kvality.

Zadání dalších podrobností v definici funkce

Je důležité poskytnout smysluplný popis funkce a zadat popisy všech parametrů, které nemusí být pro model zřejmé. Například v popisu parametru location můžete zahrnout další podrobnosti a příklady ve formátu umístění.

"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)"
},
Poskytnutí dalšího kontextu v systémové zprávě

Systémovou zprávu lze také použít k poskytnutí dalšího kontextu modelu. Například, pokud máte funkci nazývanou search_hotels, můžete do modelu zahrnout systémovou zprávu, například takto, a dát modelu instrukci, aby funkci volal, když uživatel požádá o pomoc s vyhledáním hotelu.

{"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."}
Řekněte modelu, aby se zeptal na objasnění otázek.

V některých případech byste měli model instruovat, aby kladl objasňující otázky, aby zabránil předpokladům o tom, jaké hodnoty použít u funkcí. Například s search_hotels by model měl chtít požádat o objasnění, pokud uživatelská žádost neobsahuje podrobnosti o location. Pokud chcete modelu dát pokyn, aby položil objasňující otázku, můžete do systémové zprávy zahrnout obsah podobný následujícímu příkladu.

{"role": "system", "content": "Don't make assumptions about what values to use with functions. Ask for clarification if a user request is ambiguous."}

Omezení chyb

Další oblastí, ve které může být navrhování podnětů cenné, je snížení chyb ve volání funkcí. Modely se vytrénují tak, aby generovaly volání funkcí odpovídající schématu, které definujete, ale modely vytvářejí volání funkce, které neodpovídá vámi definovanému schématu, nebo se pokusí volat funkci, kterou jste nezahrnuli.

Pokud zjistíte, že model generuje volání funkcí, která nebyla poskytnuta, zkuste do systémové zprávy zahrnout větu, která říká "Only use the functions you have been provided with.".

Zodpovědné používání volání funkcí

Stejně jako jakýkoli systém umělé inteligence představuje použití volání funkcí k integraci jazykových modelů s jinými nástroji a systémy potenciální rizika. Je důležité porozumět rizikům, která volání funkcí může představovat, a přijmout opatření k zajištění zodpovědného používání schopností.

Tady je několik tipů, které vám pomůžou bezpečně a bezpečně používat funkce:

  • Ověření volání funkcí: Vždy ověřte volání funkcí vygenerovaná modelem. To zahrnuje kontrolu parametrů, volání funkce a zajištění toho, aby volání odpovídalo zamýšlené akci.
  • Použití důvěryhodných dat a nástrojů: Používejte pouze data z důvěryhodných a ověřených zdrojů. Nedůvěryhodná data ve výstupu funkce se dají použít k tomu, aby model dal pokyn k zápisu volání funkcí jiným způsobem, než jste chtěli.
  • Postupujte podle principu nejnižšího oprávnění: Udělte funkci pouze minimální přístup potřebný k provedení své úlohy. To snižuje potenciální dopad v případě zneužití funkce. Pokud například používáte volání funkcí k dotazování databáze, měli byste aplikaci udělit přístup jen pro čtení k databázi. Neměli byste také záviset výhradně na vyloučení funkcí v definici funkce jako bezpečnostních prvků.
  • Zvažte skutečný dopad: Mějte na paměti skutečný dopad volání funkcí, která plánujete provést, zejména těch, které aktivují akce, jako je spouštění kódu, aktualizace databází nebo odesílání oznámení.
  • Implementujte kroky potvrzení uživatele: Zejména pro funkce, které provádějí akce, doporučujeme přidat krok, ve kterém uživatel před spuštěním akci potvrdí.

Další informace o našich doporučeních k zodpovědnému používání modelů Azure OpenAI najdete v přehledu postupů zodpovědné umělé inteligence pro modely Azure OpenAI.

Důležité

Parametry functions a function_call byly označeny jako zastaralé vydáním verze 2023-12-01-preview rozhraní API. Parametrem functions je nahrazení tools. Parametrem function_call je nahrazení tool_choice.

Podpora volání funkcí

Paralelní volání funkcí

  • 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)

Podpora paralelní funkce byla poprvé přidána ve verzi rozhraní API. 2023-12-01-preview

Volání základních funkcí pomocí nástrojů

  • Všechny modely, které podporují paralelní volání funkcí
  • 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)

Poznámka:

Parametr tool_choice je nyní podporován s parametrem o3-mini a o1. Další informace najdete v průvodci modely odůvodnění.

Důležité

Popisy nástrojů a funkcí jsou v současné době omezené na 1 024 znaků v Azure OpenAI. Pokud se tento limit změní, aktualizujeme tento článek.

Další kroky

  • Last updated on