Utilizzare lo strumento delle funzioni

  • 5 minuti

Lo strumento funzione consente al modello di chiamare le funzioni definite dallo sviluppatore per recuperare dati o attivare azioni durante una risposta.

Qual è la funzione dello strumento?

Lo strumento di funzione (chiamata di funzione) consente a un modello di decidere quando chiamare gli strumenti denominati esposti nell'applicazione. Il modello non esegue direttamente la logica di business. Restituisce invece una chiamata di funzione strutturata, il codice esegue la funzione e quindi si passa nuovamente l'output della funzione al modello.

Questo modello è ideale per connettere il ragionamento del modello a sistemi reali come API, database, flussi di lavoro aziendali e funzioni di utilità.

Le funzionalità principali includono:

  • Chiamate agli strumenti strutturati : il modello genera richieste esplicite di chiamata di funzione
  • Esecuzione controllata dallo sviluppatore: l'applicazione decide come e dove vengono eseguite le funzioni
  • Modello di integrazione affidabile : chiamare API, servizi interni o utilità helper in modo sicuro
  • Orchestrazione a più turni - Restituire l'output dello strumento e consentire al modello di continuare a ragionare
  • Risposte basate sui dati - Le risposte possono includere dati in tempo reale generati dal sistema

Casi d'uso comuni

Caso d'uso Esempio
Integrazione del sistema Chiamare un'API interna per i dettagli dell'account o dell'ordine
Automazione attività Attivare flussi di lavoro come la creazione di ticket o le notifiche
Ricerca dati Eseguire query sulle regole business o sulle tabelle di riferimento prima di rispondere

Un semplice esempio

Ecco un esempio che espone una get_time funzione e consente al modello di chiamarlo quando necessario:

import time
from openai import OpenAI

# Function to get the current time
def get_time():
    return f"The time is {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime())}"


# Main function
def main():
    client = OpenAI(
        base_url={openai_endpoint},
        api_key={auth_key_or_token}
    )

    function_tools = [
        {
            "type": "function",
            "name": "get_time",
            "description": "Get the current time"
        }
    ]

    # Initialize messages with a system prompt
    messages = [
        {"role": "developer", "content": "You are an AI assistant that provides information."},
    ]

    # Loop until the user types 'quit'
    while True:
        prompt = input("\nEnter a prompt (or type 'quit' to exit)\n")
        if prompt.lower() == "quit":
            break

        # Append the user prompt to the messages
        messages.append({"role": "user", "content": prompt})

        # Get initial response
        response = client.responses.create(
            model=model_deployment,
            input=messages,
            tools=function_tools
        )

        # Append model output to the messages
        messages += response.output

        # Was there a function call?
        for item in response.output:
            if item.type == "function_call" and item.name == "get_time":
                current_time = get_time()
                messages.append({
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": current_time
                })

                # Get a follow up response using the tool output
                response = client.responses.create(
                    model=model_deployment,
                    instructions="Answer only with the tool output.",
                    input=messages,
                    tools=function_tools
                )

        print(response.output_text)


# Run the main function when the script starts
if __name__ == '__main__':
    main()

In questo flusso, il modello decide quando chiamare get_time, il codice esegue la funzione e il modello restituisce quindi una risposta finale fondata. Poiché l'utente può immettere qualsiasi richiesta, il modello deve determinare quando deve chiamare la funzione. In tal caso, la risposta al prompt includerà una chiamata di funzione, che il codice dell'applicazione deve implementare prima di inviare una nuova richiesta con l'output della funzione che il modello deve elaborare.

L'output potrebbe essere simile al seguente:

Enter a prompt (or type 'quit' to exit)
Hello

Hello! How can I help you today?

Enter a prompt (or type 'quit' to exit)
What time is it?

The time is 2026-03-19 17:17:41.

Enter a prompt (or type 'quit' to exit)

Il primo prompt dell'utente ("Hello") non richiedeva l'uso dello strumento di funzione, quindi il modello rispondeva normalmente. La seconda richiesta ("Qual è l'ora?") ha attivato il modello per selezionare la get_time funzione, indicata nella risposta. Il codice dell'applicazione ha quindi eseguito la funzione e restituito i risultati al modello, che ha quindi inviato una seconda risposta con i risultati della funzione.

Suggerimento

In questo esempio viene usata una singola funzione senza parametri. È possibile configurare lo strumento per l'uso di più funzioni, con o senza parametri. Per altre informazioni sulla specifica dei dettagli della funzione, vedere la guida per sviluppatori OpenAI.

Come funziona lo strumento per le funzioni

Il processo generale per l'uso dello strumento per le funzioni è:

  1. Definire gli strumenti: specificare una o più definizioni di funzione nella matrice di strumenti.
  2. Model valuta il prompt : determina se è necessaria una chiamata di funzione.
  3. Il modello genera una chiamata di funzione : la risposta include il nome della funzione e i metadati delle chiamate.
  4. L'app esegue la logica : eseguire la funzione corrispondente nel codice.
  5. Restituisci l'output della funzione - Invia un function_call_output elemento con il risultato.
  6. Il modello completa la risposta : incorpora i risultati degli strumenti nella risposta finale.

Procedure consigliate

  • Mantenere concentrati gli strumenti : le funzioni di piccole dimensioni e a singolo scopo sono più facili da controllare e testare
  • Validare gli input della funzione - Non fidarti mai degli argomenti degli strumenti alla cieca nei sistemi di produzione
  • Gestire gli errori in modo sicuro - Restituire output di errore chiari di cui il modello può ragionare
  • Utilizzo dello strumento di log : tenere traccia delle chiamate, della latenza e delle percentuali di errore per il debug e la governance
  • Limitare le operazioni sensibili - Richiedere l'autorizzazione esplicita per le azioni ad alto impatto

Limitazioni da conoscere

  • Il modello richiede chiamate di funzione, ma l'applicazione deve eseguirle
  • Possono verificarsi argomenti dello strumento non corretti o imprevisti e devono essere convalidati
  • La latenza degli strumenti può aumentare il tempo di risposta end-to-end
  • Le chiamate di funzione migliorano l'affidabilità, ma gli output finali devono comunque essere esaminati per le decisioni critiche

Se usato bene, lo strumento funzionale trasforma un modello da generatore di testo in un orchestratore che può interagire con i sistemi reali in modo controllato e verificabile.