A függvényhívás használata a Microsoft Foundry-modellekkel

Megjegyzés

Ez a példa az OpenAI-kompatibilis Chat Completions API-t használja egy Foundry Models végponton keresztül. A Válaszok API-on keresztüli hívás más kérés- és válaszformátumot használ. További információ: Az Azure OpenAI Responses API használata.

Ha egy vagy több függvényt is belefoglal a kérésbe, a modell eldönti, hogy a kérés kontextusa alapján meghívja-e bármelyik függvényt. Amikor a modell úgy dönt, hogy meghív egy függvényt, egy JSON-objektummal válaszol, amely tartalmazza a függvény argumentumait.

A modell függvényhívásokat és strukturált argumentumokat hoz létre a megadott függvények alapján. Az alkalmazás végrehajtja a függvényeket, és visszaadja az eredményeket a modellnek, így Ön továbbra is kézben tarthatja a végrehajtott műveleteket.

Magas szinten három lépésre bonthatja a függvények működését:

  1. A csevegővégzítési API meghívása a függvényekkel és a felhasználó bemenetével
  2. A modell válaszát használva hívja meg az API-t vagy a függvényt
  3. Hívja meg újra a csevegés befejezése API-t, beleértve a függvény válaszát is a végső válasz lekéréséhez

Előfeltételek

  • Egy Foundry-modell üzembe helyezése, amely támogatja a Csevegés befejezések API-val történő függvényhívást.
  • Egy Foundry-erőforrásvégpont formátumában https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/.
  • Microsoft Entra ID hitelesítéshez:
    • Egyéni altartomány lett konfigurálva. További információ: Egyéni altartománynevek.
    • Csomagok: pip install openai azure-identity.

Példa egy eszköz/függvény hívására

Ez a példa egy egyszerű szemléltető függvényhívást mutat be, amely egyetlen definiált eszköz vagy függvény használatával három fixen megadott helyen kérdezi le az időt. A nyomtatási utasítások megkönnyítik a kód végrehajtását:

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://ai.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())

Kimeneti:

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.

Ha olyan modelltelepítést használunk, amely támogatja a párhuzamos függvényhívásokat, ezt egy párhuzamos függvényhívási példává alakíthatjuk úgy, hogy az üzenettömböt úgy módosítjuk, hogy több helyen kérjük az időt egy helyett.

Ennek elvégzéséhez cserélje fel az alábbi két sorban szereplő megjegyzéseket.

    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

Annak érdekében, hogy így nézzen ki, futtassa újra a kódot:

    #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

Ez a következő kimenetet hozza létre:

Kimeneti:

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

A párhuzamos függvényhívások lehetővé teszik több függvényhívás együttes végrehajtását, lehetővé téve a párhuzamos végrehajtást és az eredmények lekérését. Ez csökkenti az API-ba irányuló hívások számát, amelyeket el kell indítani, és javíthatja az általános teljesítményt.

Az egyszerű időalkalmazásban például egyszerre többször is lekértük. Ennek eredményeként egy csevegés befejező üzenet jött létre, amelyben három függvényhívás volt a tool_calls tömbben, és mindegyik egyedi id-vel rendelkezett. Ha ezekre a függvényhívásokra szeretne válaszolni, három új üzenetet kellene hozzáadnia a beszélgetéshez, amelyek mindegyike tartalmazza egy függvényhívás eredményét, és tool_call_id hivatkozik a id-re a tool_calls alapján.

Ha egy adott függvény meghívására szeretné kényszeríteni a modellt, állítson be tool_choice egy elnevezett eszközobjektumot, például: tool_choice={"type": "function", "function": {"name": "get_current_time"}}. "A felhasználói üzenet kényszerítéséhez állítsa be a következőt: tool_choice="none"."

Megjegyzés

Az alapértelmezett viselkedés (tool_choice: "auto") az, hogy a modell önállóan döntse el, hogy meghív-e egy függvényt, és ha igen, melyik függvényt hívja meg.

Párhuzamos függvényhívás több függvénnyel

Most egy másik, ezúttal két különböző eszközt/függvényt definiáló, példaként szolgáló függvényt mutatunk be.

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://ai.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())

Kimeneti

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?

Fontos

Előfordulhat, hogy a JSON-válasz nem mindig érvényes, ezért további logikát kell hozzáadnia a kódhoz a hibák kezeléséhez. Bizonyos használati esetekben előfordulhat, hogy a függvényhívási teljesítmény javítása érdekében finomhangolást kell használnia.

Gyors tervezés függvényekkel

Amikor a kérés részeként definiál egy függvényt, a rendszer a részleteket a rendszerüzenetbe injektálja a modell betanított szintaxisával. Ez azt jelenti, hogy a függvények tokeneket használnak az utasításokban, és promptmérnöki technikákat alkalmazhat a függvényhívások teljesítményének optimalizálásához. A modell az üzenet teljes kontextusával határozza meg, hogy egy függvényt kell-e meghívni, beleértve a függvénydefiníciót, a rendszerüzenetet és a felhasználói üzeneteket.

A minőség és a megbízhatóság javítása

Ha a modell nem hívja meg a függvényt, amikor vagy ahogyan elvárja, néhány dolgot kipróbálhat a minőség javítása érdekében.

További részleteket adjon meg a függvénydefinícióban

Fontos, hogy a függvényt értelmesen description adja meg, és adjon meg leírásokat minden olyan paraméterhez, amely nem feltétlenül nyilvánvaló a modell számára. A location paraméter leírásában például további részleteket és példákat is megadhat a hely formátumáról.

"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)"
},
Nyújtson több kontextust a rendszerüzenetben

A rendszerüzenet további kontextust is biztosít a modell számára. Ha például van egy úgynevezett search_hotels függvénye, az alábbihoz hasonló rendszerüzenettel utasíthatja a modellt, hogy hívja meg a függvényt, amikor egy felhasználó segítséget kér egy szálloda megtalálásához.

{"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."}
Utasítsa a modellt, hogy tegyen fel tisztázó kérdéseket

Bizonyos esetekben arra szeretné utasítani a modellt, hogy tegyen fel tisztázó kérdéseket, hogy ne tegyenek feltételezéseket a függvényekkel használandó értékekről. Ha például szeretné, hogy a modell pontosítást kérjen, ha a felhasználói kérés nem tartalmaz részleteket search_hotelslocation. Ha arra szeretné utasítani a modellt, hogy tegyen fel egy tisztázó kérdést, a következő példához hasonló tartalmat is felvehet a rendszerüzenetbe.

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

Hibák csökkentése

Egy másik terület, ahol a parancssori tervezés hasznos lehet, a függvényhívások hibáinak csökkentése. A modellek be vannak tanítva a definiált sémának megfelelő függvényhívások létrehozására, de a modellek olyan függvényhívást hoznak létre, amely nem egyezik a megadott sémával, vagy olyan függvényt próbál meghívni, amelyet nem tartalmazott.

Ha úgy találja, hogy a modell nem megadott függvényhívásokat hoz létre, próbáljon meg belefogni egy mondatot a rendszerüzenetbe, amely azt jelzi "Only use the functions you have been provided with.".

Függvényhívás felelősségteljes használata

Mint minden AI-rendszer, a nyelvi modellek más eszközökkel és rendszerekkel való integrálásához használt függvényhívások potenciális kockázatokat jelentenek. Fontos tisztában lenni azzal, hogy milyen kockázatokat jelenthetnek a függvényhívások, és intézkedéseket kell tenni annak érdekében, hogy felelősen használjuk a funkciókat.

Íme néhány tipp a függvények biztonságos és védett módon történő használatához:

  • Függvényhívások ellenőrzése: Mindig ellenőrizze a modell által generált függvényhívásokat. Ez magában foglalja a paraméterek ellenőrzését, a meghívandó függvényt, valamint annak biztosítását, hogy a hívás igazodjon a kívánt művelethez.
  • Megbízható adatok és eszközök használata: Csak megbízható és ellenőrzött forrásokból származó adatokat használjon. A függvény kimenetében nem megbízható adatok arra utasíthatják a modellt, hogy a kívánttól eltérő módon írjon függvényhívásokat.
  • Kövesse a minimális jogosultság elvét: Csak a függvény feladatának elvégzéséhez szükséges minimális hozzáférést adja meg. Ez csökkenti a lehetséges hatást, ha egy függvényt visszaélnek vagy kihasználnak. Ha például függvényhívásokkal kérdez le egy adatbázist, csak írásvédett hozzáférést kell adnia az alkalmazásnak az adatbázishoz. Nem szabad kizárólag a függvénydefinícióból kizárt képességek biztonsági ellenőrzőként való alkalmazására támaszkodnia.
  • Fontolja meg a valós hatást: Vegye figyelembe a végrehajtani tervezett függvényhívások valós hatását, különösen azokat, amelyek olyan műveleteket aktiválnak, mint a kód végrehajtása, az adatbázisok frissítése vagy az értesítések küldése.
  • Felhasználói megerősítési lépések implementálása: Különösen a műveleteket végrehajtó függvények esetében javasoljuk, hogy adjon meg egy lépést, amelyben a felhasználó a végrehajtás előtt megerősíti a műveletet.

Az Öntödei modellek felelős AI-eljárásairól a felelős AI-eljárások áttekintésében olvashat bővebben.

Fontos

A Chat Completions API-ban a functions és function_call paraméterek elavultak. Használja a tools paramétert a helyett functions, és használja a tool_choice paramétert a helyett function_call.

Függvényhívás támogatása

A Foundry Models támogatja a Chat Completions API-val vagy a Responses API-val történő hívásokat. A támogatás modelltől, API-tól, üzembe helyezési típustól és modellverziótól függően változik.

A függvényhívást támogató modell megkereséséhez tekintse át a következő katalógusokat:

A modell részletei között keresse meg a következő képességeket:

  • Chat Completions API vagy Responses API, attól függően, hogy melyik API-t tervezi használni.
  • Függvények vagy eszközök a függvényhívás támogatásához.
  • Párhuzamos eszközhívás , ha az alkalmazásnak több függvényhívást kell kérnie egy válaszban.

Ez a cikk bemutatja, hogyan implementálhat függvényhívást a Csevegés befejezése API-val. A Válaszok API kérés- és válaszformátumát a Azure OpenAI Responses API használata című témakörben talál.

Megjegyzés

A tool_choice paraméter mostantól támogatott a következővel: o3-mini és o1. További információt az érvelési modellek útmutatójában talál.

Fontos

Az eszköz- és függvényleírások jelenleg legfeljebb 1024 karakter hosszúságúak. Ha ez a korlát változik, frissítjük ezt a cikket.

Következő lépések

  • Utolsó frissítés időpontja: