Programowe wywoływanie narzędzi za pomocą Responses API usługi Azure OpenAI

Programistyczne wywoływanie narzędzi pozwala modelowi używać kodu do orkiestracji narzędzi podczas żądania Responses API. Zamiast wymagać oddzielnej tury modelu dla każdego wywołania narzędzia, model może wygenerować program, który wywołuje narzędzia i przetwarza ich wyniki. Program może wykonywać operacje, takie jak rozgałęzianie lub iteracja.

W tym artykule wyjaśniono, kiedy programowe wywoływanie narzędzi jest przydatne i jak różni się od wywoływania funkcji, równoległego wywoływania narzędzi i wyszukiwania narzędzi.

Zagadnienia dotyczące dostępności

Przed zaimplementowaniem programistycznego wywoływania narzędzi upewnij się, że wdrożenie modelu Azure OpenAI i wersja zestawu SDK Azure obsługują tę funkcję. Nie zakładaj, że obsługa interfejsu API odpowiedzi ustanawia również obsługę programowego wywoływania narzędzi.

Aby uzyskać informacje o konfiguracji punktu końcowego i uwierzytelniania, zobacz Korzystanie z interfejsu API odpowiedzi usługi Azure OpenAI.

Programistyczne wywoływanie narzędzi i wywoływanie funkcji

W przypadku wywołania standardowej funkcji aplikacja zwykle uczestniczy w każdym kroku wywoływania narzędzi:

Model -> wywołanie narzędzia -> aplikacja wykonuje narzędzie -> model -> następne wywołanie narzędzia -> aplikacja wykonuje narzędzie -> model

Za pomocą programistycznego wywoływania narzędzi model może wygenerować kod, który koordynuje wiele operacji narzędzi:

Model -> wygenerowany program -> operacje narzędzia -> wynik programu -> model

Takie podejście może zmniejszyć liczbę iteracji modelu potrzebnych dla przepływów pracy obejmujących kilka narzędzi.

Te przepływy ilustrują koncepcyjną różnicę w orkiestracji. Nie określają, które operacje wykonuje aplikacja lub usługa.

Przykład: porównywanie stanu magazynowego z zapotrzebowaniem

Ten przykład Python uwidacznia dwie funkcje zdefiniowane przez aplikację, które zwracają przykładowe dane spisu i zapotrzebowania. Model używa programistycznego wywoływania narzędzi do porównania wyników. Aplikacja wykonuje funkcje i zwraca wyniki, aby środowisko uruchomieniowe mogło wznowić wygenerowany program.

Bloki kodu tworzą jeden skrypt. Połącz je w pokazanej kolejności.

klient Azure OpenAI

Użyj wdrożenia Azure OpenAI, które obsługuje programowe wywoływanie narzędzi, oraz wersji zestawu SDK OpenAI, która zawiera output_schema, allowed_callers i informacje o obiekcie wywołującym. Zainstaluj pakiety openai i azure-identity w środowisku Python:

pip install --upgrade openai azure-identity

Skonfiguruj uwierzytelnianie Microsoft Entra ID zgodnie z opisem w temacie Use the Azure OpenAI Responses API. Twoja tożsamość musi mieć uprawnienia do wywoływania wdrożenia Azure OpenAI.

Zastąp YOUR-RESOURCE-NAME nazwą zasobu. Wartość model w dalszej części przykładu to nazwa wdrożenia Azure, a nie identyfikator katalogu modeli.

import json

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import OpenAI

# Use the Azure OpenAI v1 endpoint and Microsoft Entra ID authentication.
endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(
    credential, "https://cognitiveservices.azure.com/.default"
)
openai = OpenAI(base_url=endpoint, api_key=token_provider)

Funkcje zdefiniowane przez aplikację

Funkcje zwracają stałe dane przykładowe: 42 dostępne jednostki i 31 żądanych jednostek dla określonego SKU. Zastąp te implementacje własnymi źródłami danych zapasów i popytu w aplikacji.

def get_inventory(sku):
    return {"sku": sku, "available_units": 42}


def get_demand(sku):
    return {"sku": sku, "requested_units": 31}


implementations = {
    "get_inventory": get_inventory,
    "get_demand": get_demand,
}

Definicje narzędzi

Każda funkcja deklaruje schemat wejściowy i element output_schema opisujący wynik JSON. Ustawienie allowed_callers na ["programmatic"] sprawia, że funkcja jest dostępna dla wygenerowanych programów, a nie dla bezpośrednich wywołań modelu.

tools = [
    {
        "type": "function",
        "name": "get_inventory",
        "description": "Return the SKU and available inventory units.",
        "strict": True,
        "parameters": {
            "type": "object",
            "properties": {"sku": {"type": "string"}},
            "required": ["sku"],
            "additionalProperties": False,
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "sku": {"type": "string"},
                "available_units": {"type": "number"},
            },
            "required": ["sku", "available_units"],
            "additionalProperties": False,
        },
        "allowed_callers": ["programmatic"],
    }
]

Dodaj funkcję popytu i programistyczną możliwość wywoływania narzędzi do tej samej listy:

tools.extend([
    {
        "type": "function",
        "name": "get_demand",
        "description": "Return the SKU and requested demand units.",
        "strict": True,
        "parameters": {
            "type": "object",
            "properties": {"sku": {"type": "string"}},
            "required": ["sku"],
            "additionalProperties": False,
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "sku": {"type": "string"},
                "requested_units": {"type": "number"},
            },
            "required": ["sku", "requested_units"],
            "additionalProperties": False,
        },
        "allowed_callers": ["programmatic"],
    },
    {"type": "programmatic_tool_calling"},
])

Wyniki narzędzia i informacje o wywołującym

Aplikacja rozdziela wywołania funkcji po nazwie i serializuje każdy wynik. Zachowaj informacje o caller wywołaniu, aby środowisko uruchomieniowe mogło wznowić prawidłowy program. Nieznane nazwy narzędzi i nieprawidłowe argumenty powodują błędy zamiast zwracać sfabrykowane wyniki.

def run_tool(call):
    run = implementations.get(call.name)
    if run is None:
        raise ValueError(f"Unknown tool: {call.name}")

    arguments = json.loads(call.arguments)
    if (
        not isinstance(arguments, dict)
        or set(arguments) != {"sku"}
        or not isinstance(arguments["sku"], str)
    ):
        raise ValueError(f"Invalid arguments for tool: {call.name}")

    result = run(**arguments)
    output = {
        "type": "function_call_output",
        "call_id": call.call_id,
        "output": json.dumps(result),
    }
    if call.caller is not None:
        output["caller"] = call.caller.model_dump(exclude_none=True)
    return output

Kontynuacja odpowiedzi

Zastąp YOUR-MODEL-DEPLOYMENT nazwą obsługiwanego wdrożenia Azure OpenAI.

Dzięki store=False aplikacja kontynuuje rozmowę. Zachowaj każdy element wyjściowy, w tym elementy programowe i elementy rozumowania, przed dodaniem wyników narzędzia. Pętla zatrzymuje się na ostatecznej odpowiedzi lub odmowie i zgłasza błąd, jeśli odpowiedź zakończy się niepowodzeniem lub zostanie osiągnięty limit żądań.

input_items = [
    {"role": "user", "content": "Compare inventory with demand for sku_123."}
]
MAX_REQUESTS = 10
for _ in range(MAX_REQUESTS):
    response = openai.responses.create(
        model="YOUR-MODEL-DEPLOYMENT",
        store=False, input=input_items, tools=tools,
    )
    if response.status != "completed":
        raise RuntimeError(f"Response ended with status {response.status}")
    input_items.extend(
        item.model_dump(exclude_none=True) for item in response.output
    )
    calls = [item for item in response.output if item.type == "function_call"]
    if calls:
        input_items.extend(run_tool(call) for call in calls)
        continue
    if response.output_text:
        print(response.output_text)
        break
    refusals = [
        part.refusal for item in response.output if item.type == "message"
        for part in item.content if part.type == "refusal"
    ]
    if refusals:
        print("\n".join(refusals))
        break
else:
    raise RuntimeError("Programmatic tool calling exceeded the request limit")

Ostateczna odpowiedź powinna wyjaśnić, że stan magazynowy pokrywa zapotrzebowanie: 42 dostępne jednostki minus 31 żądanych jednostek daje 11 jednostek. Sformułowanie może się różnić. Zamiast tego drukowana jest odmowa, jeśli model odmawia żądania.

Aplikacja wykonuje funkcje inwentaryzacji i zapotrzebowania, podczas gdy wygenerowany program koordynuje ich użycie i przetwarza wyniki.

Kiedy należy używać programowego wywoływania narzędzi

Rozważ programistyczne wywoływanie narzędzi podczas wykonywania zadania:

• Wymaga kilku powiązanych wywołań narzędzi.
• Zawiera logikę warunkową.
• Wymaga iteracji po wynikach narzędzia.
• Wykonuje przetwarzanie danych pośrednich przed utworzeniem odpowiedzi.
• W przeciwnym razie wymagałoby to wielokrotnych kolejnych tur modelu w celu koordynowania narzędzi.

W przypadku prostych przepływów pracy obejmujących jedną lub dwie niezależne funkcje standardowe wywołania funkcji mogą być łatwiejsze do zaimplementowania.

Programistyczne wywoływanie narzędzi i równoległe wywoływanie narzędzi

Równoległe wywoływanie narzędzi i programistyczne wywoływanie narzędzi odpowiadają na różne potrzeby orkiestracji.

Użyj równoległego wywoływania narzędzi , gdy kilka niezależnych operacji może być wykonywanych w tym samym czasie. Na przykład pobierz pogodę dla pięciu niezależnych lokalizacji.

Użyj programistycznego wywoływania narzędzi, gdy operacje narzędzi wymagają koordynacji, obliczeń pośrednich, rozgałęziania lub iteracji. Na przykład pobierz zamówienia klienta, wybierz zamówienia, które pasują do warunku, i sprawdź informacje o wysyłce dla tych zamówień.

Programistyczne wywoływanie narzędzi i wyszukiwanie narzędzi

Wyszukiwanie narzędzi określa, które definicje narzędzi są ładowane do kontekstu modelu.

Programistyczne wywoływanie narzędzi steruje sposobem koordynowania użycia narzędzi przez model po ich udostępnieniu.

Rozróżnienie dotyczy odnajdywania narzędzi i orkiestracji narzędzi. Ich koncepcyjna relacja nie rozstrzyga, czy wdrożenie obsługuje używanie obu funkcji w tym samym żądaniu.

Zagadnienia dotyczące zabezpieczeń

Traktuj wygenerowane programy jako niezaufany kod.

Podczas udostępniania narzędzi:

• Przestrzegaj zasady najmniejszych uprawnień.
• Zweryfikuj argumenty narzędzia.
• Ogranicz dostęp do operacji poufnych.
• Uwierzytelniaj i autoryzuj operacje niezależnie od danych wyjściowych modelu.
• Rejestruj wykonanie narzędzia na potrzeby inspekcji i diagnostyki bez rejestrowania tajnych informacji lub niepotrzebnych poufnych danych.
• Unikaj uwidaczniania niepotrzebnych narzędzi lub danych.

Nie należy polegać na kodzie wygenerowanym przez model jako granicy autoryzacji.

Treści powiązane

• Skorzystaj z API odpowiedzi Azure OpenAI
• Wywoływanie funkcji za pomocą interfejsu Azure OpenAI
• Korzystanie z wyszukiwania narzędzi za pomocą interfejsu Responses API usługi Azure OpenAI