Aracılığıyla paylaş

Azure OpenAI Hizmeti ile işlev çağrısını kullanma (Önizleme)

  • Makale

Gpt-35-turbo ve gpt-4'ün en son sürümleri, işlevlerle çalışacak şekilde ince ayarlıdır ve bir işlevin ne zaman ve nasıl çağrılması gerektiğini belirleyebilir. İsteğinize bir veya daha fazla işlev dahil edilirse model, işlevlerden herhangi birinin istem bağlamı temelinde çağrılıp çağrılmadığını belirler. Model bir işlevin çağrılması gerektiğini belirlediğinde, işlevin bağımsız değişkenlerini içeren bir JSON nesnesiyle yanıt verir.

Modeller, api çağrılarını formüle eder ve veri çıkışlarını, belirttiğiniz işlevlere göre yapılandırır. Modellerin bu çağrıları oluşturabilmesine karşın bunları yürütmenin size bağlı olduğunu ve denetimin sizinde kalmasını sağlamanın önemli olduğunu unutmayın.

Yüksek düzeyde işlevlerle çalışmayı üç adıma ayırabilirsiniz:

  1. İşlevleriniz ve kullanıcının girişiyle sohbet tamamlama API'sini çağırma
  2. API'nizi veya işlevinizi çağırmak için modelin yanıtını kullanın
  3. Son yanıtı almak için işlevinizden gelen yanıt da dahil olmak üzere sohbet tamamlama API'sini yeniden çağırın

Önemli

functions ve function_call parametreleri, API sürümünün yayımlanmasıyla 2023-12-01-preview birlikte kullanım dışı bırakılmıştır. parametresinin functions yerine geçer tools . parametresinin function_call yerine geçer tool_choice .

İşlev çağrısı desteği

Paralel işlev çağrısı

  • gpt-35-turbo (1106)
  • gpt-35-turbo (0125)
  • gpt-4 (1106-Önizleme)
  • gpt-4 (0125-Önizleme)
  • gpt-4 (görüntü önizleme)
  • gpt-4 (2024-04-09)
  • gpt-4o (2024-05-13)

Paralel işlev desteği ilk olarak API sürümünde eklendi 2023-12-01-preview

Araçlarla temel işlev çağrısı

  • Paralel işlev çağrısını destekleyen tüm modeller
  • gpt-4 (0613)
  • gpt-4-32k (0613)
  • gpt-35-turbo-16k (0613)
  • gpt-35-turbo (0613)

Tek araç/işlev çağırma örneği

İlk olarak, tek bir araç/işlev tanımlı üç sabit kodlu konumdaki zamanı denetleyebilen basit bir oyuncak işlev çağrısı göstereceğiz. Kod yürütmeyi daha kolay takip etmeye yardımcı olmak için print deyimleri ekledik:

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

Çıktı:

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.

Paralel işlev çağrılarını destekleyen bir model dağıtımı kullanıyorsak, messages dizisini bir yerine birden çok konumdaki zamanı isteyecek şekilde değiştirerek bunu paralel işlev çağırma örneğine dönüştürebiliriz.

Bunu gerçekleştirmek için şu iki satırdaki açıklamaları değiştirin:

    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

Bu şekilde görünmesi ve kodu yeniden çalıştırması için:

    #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

Bu, aşağıdaki çıkışı oluşturur:

Çıktı:

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

Paralel işlev çağrıları birden çok işlev çağrısını birlikte gerçekleştirmenize olanak tanıyarak paralel yürütmeye ve sonuçların alınmasına olanak tanır. Bu, API'ye yapılması gereken çağrı sayısını azaltır ve genel performansı artırabilir.

Örneğin basit saat uygulamamızda aynı anda birden çok kez aldık. Bu, dizide her birinin benzersiz idolduğu üç işlev çağrısı içeren tool_calls bir sohbet tamamlama iletisiyle sonuçlandı. Bu işlev çağrılarını yanıtlamak istiyorsanız, konuşmaya her biri bir işlev çağrısının sonucunu içeren ve öğesine tools_callsbaşvuran id üç tool_call_id yeni ileti ekleyebilirsiniz.

Modeli belirli bir işlevi çağırmaya zorlamak için parametresini tool_choice belirli bir işlev adıyla ayarlayın. Ayrıca, ayarını yaparak tool_choice: "none"modeli kullanıcıya yönelik bir ileti oluşturmaya zorlayabilirsiniz.

Not

Varsayılan davranış (tool_choice: "auto"), modelin bir işlevin çağrılıp çağrılmayacağına ve çağrılıp çağrılmayacağına kendi karar vermesine yöneliktir.

Birden çok işlevle paralel işlev çağrısı

Şimdi bu kez tanımlanan iki farklı araç/işlevle başka bir oyuncak işlevi çağırma örneği göstereceğiz.

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

Çıktı

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?

Önemli

JSON yanıtı her zaman geçerli olmayabilir, bu nedenle hataları işleyebilmek için kodunuza ek mantık eklemeniz gerekir. Bazı kullanım örnekleri için işlev çağırma performansını geliştirmek için ince ayarlama kullanmanız gerektiğini fark edebilirsiniz.

İşlevlerle istem mühendisliği

İsteğinizin bir parçası olarak bir işlev tanımladığınızda, ayrıntılar modelin eğitildiği belirli söz dizimi kullanılarak sistem iletisine eklenir. Bu, işlevlerin isteminizdeki belirteçleri kullandığı ve işlev çağrılarınızın performansını iyileştirmek için istem mühendisliği teknikleri uygulayabileceğiniz anlamına gelir. Model, işlev tanımı, sistem iletisi ve kullanıcı iletileri dahil olmak üzere bir işlevin çağrılıp çağrılmadığını belirlemek için istemin tam bağlamını kullanır.

Kalite ve güvenilirliği artırma

Model, işlevinizi beklediğiniz zaman veya beklediğiniz şekilde çağırmıyorsa, kaliteyi artırmak için deneyebileceğiniz birkaç şey vardır.

İşlev tanımınızda daha fazla ayrıntı sağlayın

İşlevin anlamlı description bir kısmını sağlamanız ve model için belirgin olmayabilecek herhangi bir parametre için açıklamalar sağlamanız önemlidir. Örneğin, parametresinin açıklamasına konumun location biçimine ek ayrıntılar ve örnekler ekleyebilirsiniz.

"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)"
},
Sistem iletisinde daha fazla bağlam sağlayın

Sistem iletisi, modele daha fazla bağlam sağlamak için de kullanılabilir. Örneğin, adlı search_hotels bir işleviniz varsa, kullanıcı otel bulma konusunda yardım istediğinde modelin işlevi çağırmasını isteyen aşağıdaki gibi bir sistem iletisi ekleyebilirsiniz.

{"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."}
Modele net sorular sormasını isteyin

Bazı durumlarda, modele işlevlerle hangi değerlerin kullanılacağına ilişkin varsayımlarda bulunmayı önlemek için net sorular sormasını istemek istiyorsunuz. Örneğin, search_hotels kullanıcı isteğinde locationayrıntıların yer almaması durumunda modelin açıklamasını istemesini isteyebilirsiniz. Modele net bir soru sormasını istemek için sistem iletinize sonraki örneğe benzer içerikler ekleyebilirsiniz.

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

Hataları azaltma

İstem mühendisliğinin değerli olabileceği bir diğer alan da işlev çağrılarındaki hataları azaltmaktır. Modeller, tanımladığınız şemayla eşleşen işlev çağrıları oluşturmak için eğitilir, ancak modeller tanımladığınız şemayla eşleşmeyen bir işlev çağrısı oluşturur veya eklemediğiniz bir işlevi çağırmaya çalışır.

Modelin sağlanmayan işlev çağrıları oluşturduğunu fark ederseniz, sistem iletisine ifadesini "Only use the functions you have been provided with."içeren bir cümle eklemeyi deneyin.

İşlev çağırmayı sorumlu bir şekilde kullanma

Tüm yapay zeka sistemlerinde olduğu gibi, dil modellerini diğer araçlar ve sistemlerle tümleştirmek için işlev çağrısının kullanılması olası risklere neden olur. İşlev çağrısının sunabileceği riskleri anlamak ve yetenekleri sorumlu bir şekilde kullandığınızdan emin olmak için önlemler almak önemlidir.

İşlevleri güvenli ve güvenli bir şekilde kullanmanıza yardımcı olacak birkaç ipucu aşağıdadır:

  • İşlev Çağrılarını Doğrulama: Her zaman model tarafından oluşturulan işlev çağrılarını doğrulayın. Bu, parametreleri denetlemeyi, çağrılan işlevi ve çağrının hedeflenen eylemle uyumlu olmasını sağlamayı içerir.
  • Güvenilen Veri ve Araçları Kullanma: Yalnızca güvenilir ve doğrulanmış kaynaklardan gelen verileri kullanın. Bir işlevin çıkışındaki güvenilmeyen veriler, modele işlev çağrılarını istediğinizden farklı bir şekilde yazmasını bildirmek için kullanılabilir.
  • En Az Ayrıcalık İlkesi'ni izleyin: İşlevin işini gerçekleştirmesi için yalnızca gereken en düşük erişimi verin. Bu, bir işlevin kötüye kullanılması veya kötüye kullanılması durumunda olası etkiyi azaltır. Örneğin, bir veritabanını sorgulamak için işlev çağrıları kullanıyorsanız, uygulamanıza veritabanına yalnızca salt okunur erişim vermeniz gerekir. Ayrıca yalnızca işlev tanımındaki özellikleri güvenlik denetimi olarak hariç tutmalısınız.
  • Gerçek Dünya Etkisini Göz önünde bulundurun: Özellikle kod yürütme, veritabanlarını güncelleştirme veya bildirim gönderme gibi eylemleri tetikleyenler olmak üzere, yürütmeyi planladığınız işlev çağrılarının gerçek dünya üzerindeki etkisine dikkat edin.
  • Kullanıcı Onayı Adımlarını Uygulama: Özellikle eylemde bulunan işlevler için, kullanıcının eylemi yürütülmeden önce onayladığı bir adım eklemenizi öneririz.

Azure OpenAI modellerini sorumlu bir şekilde kullanma önerilerimiz hakkında daha fazla bilgi edinmek için bkz . Azure OpenAI modelleri için sorumlu yapay zeka uygulamalarına genel bakış.

Sonraki adımlar