Chiamata di strumenti a livello di codice con l'API Responses di Azure OpenAI

La chiamata a uno strumento programmatico consente a un modello di usare il codice per orchestrare gli strumenti durante una richiesta Responses API. Anziché richiedere un turno di modello separato per ogni chiamata dello strumento, il modello può generare un programma che chiama gli strumenti ed elabora i risultati. Il programma può eseguire operazioni come la diramazione o l'iterazione.

Questo articolo illustra quando la chiamata di strumenti programmatica è utile e in che modo differisce dalla chiamata di funzioni, dalla chiamata parallela di strumenti e dalla ricerca degli strumenti.

Considerazioni sulla disponibilità

Prima di implementare la chiamata a strumenti a livello di codice, verificare che la distribuzione del modello Azure OpenAI e la versione dell'SDK Azure supportino la funzionalità. Non presupporre che il supporto per la Responses API stabilisca anche il supporto per l'invocazione programmatica degli strumenti.

Per la configurazione dell'endpoint e dell'autenticazione, vedere Usare l'API Responses di Azure OpenAI.

Chiamata a strumenti a livello di codice e chiamata di funzioni

Con la chiamata di funzione standard, l'applicazione partecipa in genere a ogni fase di chiamata degli strumenti:

Modello -> Chiamata dello strumento -> L'applicazione esegue lo strumento -> Modello -> Chiamata successiva dello strumento -> L'applicazione esegue lo strumento -> modello

Con la chiamata a uno strumento programmatico, il modello può generare codice che orchestra più operazioni degli strumenti:

Modello -> Programma generato -> Operazioni degli strumenti -> Risultato del programma -> Modello

Questo approccio può ridurre il numero di turni di modello necessari per i flussi di lavoro che coinvolgono diversi strumenti.

Questi flussi illustrano la differenza concettuale nell'orchestrazione. Non specificano quali operazioni eseguono l'applicazione o il servizio.

Esempio: Confrontare l'inventario con la domanda

Questo esempio Python espone due funzioni definite dall'applicazione che restituiscono dati di inventario e domanda di esempio. Il modello usa la chiamata programmatica degli strumenti per confrontare i risultati. L'applicazione esegue le funzioni e restituisce i risultati in modo che il runtime possa riprendere il programma generato.

I blocchi di codice formano uno script. Combinarli nell'ordine visualizzato.

client di Azure OpenAI

Usare una distribuzione Azure OpenAI che supporta la chiamata di strumenti a livello di codice e una versione di OpenAI SDK che include output_schema, allowed_callers e informazioni sul chiamante. Installare i pacchetti azure-identity e openai nell'ambiente Python:

pip install --upgrade openai azure-identity

Configurare l'autenticazione Microsoft Entra ID come descritto in Usare l'API Responses di Azure OpenAI. L'identità deve avere l'autorizzazione per chiamare la distribuzione Azure OpenAI.

Sostituire YOUR-RESOURCE-NAME con il nome della risorsa. Il valore model più avanti nell'esempio è il nome del deployment di Azure, non un identificatore del catalogo dei modelli.

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)

Funzioni definite dall'applicazione

Le funzioni restituiscono dati di esempio fissi: 42 unità disponibili e 31 unità richieste per lo SKU specificato. Sostituire le loro implementazioni con le tue origini dati di inventario e domanda nell'applicazione.

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,
}

Definizioni degli strumenti

Ogni funzione dichiara uno schema di input e un output_schema che descrive il risultato JSON. L'impostazione di allowed_callers su ["programmatic"] rende la funzione disponibile per i programmi generati anziché per le chiamate dirette al modello.

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"],
    }
]

Aggiungere la funzione di domanda e la funzionalità di chiamata dello strumento a livello di codice allo stesso elenco:

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"},
])

Risultati degli strumenti e informazioni sul chiamante

L'applicazione smista le chiamate di funzione per nome e serializza ogni risultato. Mantenere le informazioni della caller chiamata in modo che il runtime possa riprendere il programma corretto. I nomi degli strumenti sconosciuti e gli argomenti non validi generano errori invece di restituire risultati inventati.

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

Continuazione della risposta

Sostituire YOUR-MODEL-DEPLOYMENT con il nome della distribuzione Azure OpenAI supportata.

Con store=False, l'applicazione porta avanti la conversazione. Conservare ogni elemento di output, inclusi gli elementi di programma e di ragionamento, prima di aggiungere i risultati dello strumento. Il ciclo si arresta con una risposta finale o un rifiuto e genera un errore se una risposta fallisce o viene raggiunto il limite della richiesta.

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

La risposta finale dovrebbe spiegare che l'inventario copre la domanda: 42 unità disponibili meno 31 unità richieste lasciano 11 unità. La formulazione può variare. Un rifiuto viene invece stampato se il modello rifiuta la richiesta.

L'applicazione esegue le funzioni di inventario e domanda, mentre il programma generato coordina l'uso e elabora i risultati.

Quando usare la chiamata a strumenti programmatici

Considera la chiamata programmatica di strumenti quando un'attività:

  • Richiede diverse chiamate agli strumenti correlate.
  • Contiene logica condizionale.
  • Richiede l'iterazione sui risultati degli strumenti.
  • Esegue l'elaborazione dati intermedia prima di produrre una risposta.
  • Altrimenti richiederebbe turni ripetuti del modello per coordinare gli strumenti.

Per i flussi di lavoro semplici che coinvolgono una o due funzioni indipendenti, la chiamata a funzioni standard potrebbe essere più semplice da implementare.

Chiamata a strumenti programmatica e chiamata a strumenti paralleli

La chiamata parallela agli strumenti e la chiamata programmatica agli strumenti rispondono a diverse esigenze di orchestrazione.

Usare la chiamata parallela degli strumenti quando più operazioni indipendenti possono essere eseguite contemporaneamente. Ad esempio, recuperare il meteo per cinque posizioni indipendenti.

Usare la chiamata programmatica degli strumenti quando le operazioni degli strumenti richiedono il coordinamento, il calcolo intermedio, la diramazione o l'iterazione. Ad esempio, recuperare gli ordini di un cliente, selezionare gli ordini che corrispondono a una condizione ed eseguire query sulle informazioni di spedizione per tali ordini.

La ricerca degli strumenti determina quali definizioni degli strumenti vengono caricate nel contesto del modello.

La chiamata programmatica degli strumenti controlla il modo in cui il modello orchestra gli strumenti dopo che sono disponibili.

La distinzione è tra l'individuazione degli strumenti e l'orchestrazione degli strumenti. La relazione concettuale non stabilisce se la tua distribuzione supporta l'uso di entrambe le funzionalità nella stessa richiesta.

Considerazioni relative alla sicurezza

Considera i programmi generati come codice non attendibile.

Quando si espongono strumenti:

  • Segui il principio del privilegio minimo.
  • Convalida gli argomenti dello strumento.
  • Limitare l'accesso alle operazioni sensibili.
  • Autentica e autorizza le operazioni indipendentemente dall'output del modello.
  • Registrare l'esecuzione dello strumento per il controllo e la diagnostica senza registrare segreti o dati sensibili non necessari.
  • Evitare di esporre strumenti o dati non necessari.

Non basarsi sul codice generato dal modello come barriera di autorizzazione.

Contenuti correlati

  • Ultimo aggiornamento: