Chiamata delle funzioni su Azure Databricks

Questo articolo descrive la chiamata alle funzioni e come usarla come parte dei flussi di lavoro generativi dell'applicazione di intelligenza artificiale. La chiamata alle funzioni di Databricks è compatibile con OpenAI ed è disponibile solo durante la gestione del modello come parte delle API del modello di Foundation e la gestione degli endpoint che servono modelli esterni.

Che cos'è la chiamata di funzione?

La funzione di chiamata consente di controllare l'output dei modelli linguistici di grandi dimensioni (LLM), in modo da generare risposte strutturate in modo più affidabile. Quando si usa una chiamata di funzione, si descrivono le funzioni nella chiamata API descrivendo gli argomenti della funzione usando uno schema JSON. LLM stesso non chiama queste funzioni, ma crea invece un oggetto JSON utilizzabile dagli utenti per chiamare le funzioni nel codice.

Per la chiamata di funzione in Databricks, la sequenza di passaggi di base è la seguente:

1. Chiamare il modello usando la query inviata e un set di funzioni definite nel parametro tools.
2. Il modello decide se chiamare o meno le funzioni definite. Quando viene chiamata la funzione , il contenuto è un oggetto JSON di stringhe conforme allo schema personalizzato.
3. Analizzare le stringhe in JSON nel codice e chiamare la funzione con gli argomenti forniti, se esistono.
4. Chiamare di nuovo il modello aggiungendo la risposta strutturata come un nuovo messaggio. La struttura della risposta è definita dalle funzioni fornite in precedenza in tools. Da qui, il modello riepiloga i risultati e poi invia il riepilogo all'utente.

Quando usare la chiamata di funzione

Di seguito sono riportati alcuni esempi di casi d'uso della chiamata di funzione:

• Creare assistenti che possano rispondere alle domande chiamando altre API. Ad esempio, è possibile definire funzioni come send_email(to: string, body: string) o current_weather(location: string, unit: 'celsius' | 'fahrenheit').
• Definire e utilizzare chiamate API basate sul linguaggio naturale. Come considerare la frase: "Chi sono i miei clienti principali?" e trasformarlo in una chiamata API denominata get_customers(min_revenue: int, created_before: string, limit: int) e chiamare quell'API.

Per le attività di inferenza batch o elaborazione dati, ad esempio la conversione di dati non strutturati in dati strutturati. Databricks consiglia di usare output strutturati.

Modelli supportati

Nella tabella seguente sono elencati i modelli supportati e la funzionalità di gestione del modello che rende disponibile ogni modello. Per questi modelli, vedere Licenze e condizioni per sviluppatori di modelli applicabili.

• Per i modelli resi disponibili dalle API del modello foundation, vedere Limiti delle API del modello di base per la disponibilità dell'area.
• Per i modelli resi disponibili da modelli esterni, consultare la Disponibilità delle regioni per la disponibilità regionale.

Important

• Meta-Llama-3.1-405B-Instruct verrà ritirato come indicato di seguito. Per informazioni su come eseguire la migrazione durante la deprecazione, vedere Modelli ritirati per il modello di sostituzione consigliato.

  • A partire dal 15 febbraio 2026, questo modello non è disponibile per i carichi di lavoro con pagamento in base al token.
  • A partire dal 15 maggio 2026, questo modello non è disponibile per carichi di lavoro con throughput approvvigionato.

• A partire dall'11 dicembre 2024, Meta-Llama-3.3-70B-Instruct sostituirà il supporto per Meta-Llama-3.1-70B-Instruct negli endpoint delle Foundation Model API con pagamento per token.

Modello	Reso disponibile tramite la funzionalità di gestione dei modelli	Notes
Claude-Sonnet-4.5	API dei modelli di base	Supportato per gli endpoint con pagamento in base al token.
Qwen3-Next 80B A3B Instruct (Beta)	API dei modelli di base	Supportato per gli endpoint con pagamento in base al token.
GPT OSS 20B	API dei modelli di base	Supportato sugli endpoint con pagamento per token e velocità effettiva con provisioning.
GPT OSS 120B	API dei modelli di base	Supportato sugli endpoint con pagamento per token e velocità effettiva con provisioning.
Gemma-3-12B	API dei modelli di base	Supportato sugli endpoint con pagamento per token e velocità effettiva con provisioning.
Claude-Sonnet-4	API dei modelli di base	Supportato per gli endpoint con pagamento in base al token.
Claude-Opus-4.1	API dei modelli di base	Supportato per gli endpoint con pagamento in base al token.
Claude-3.7-Sonnet	API dei modelli di base	Supportato per gli endpoint con pagamento in base al token.
Meta-Llama-4-Maverick	API dei modelli di base	Supportato nei carichi di lavoro con pagamento per token e carichi di lavoro con throughput provisionato.
Meta-Llama-3.3-70B-Instruct	API dei modelli di base	Supportato nei carichi di lavoro con pagamento per token e carichi di lavoro con throughput provisionato.
Meta-Llama-3.1-405B-Instruct	API dei modelli di base	Supportato nei carichi di lavoro con pagamento per token e carichi di lavoro con throughput provisionato.
Meta-Llama-3.1-8B-Instruct	API dei modelli di base	Supportato nei carichi di lavoro con pagamento per token e carichi di lavoro con throughput provisionato.
gpt-4o	Modelli esterni
gpt-4o-2024-08-06	Modelli esterni
gpt-4o-2024-05-13	Modelli esterni
gpt-4o-mini	Modelli esterni
claude-3-5-sonnet-latest	Modelli esterni	Fornitore di modelli antropici
claude-3-5-haiku-latest	Modelli esterni	Fornitore di modelli antropici
claude-3-5-opus-latest	Modelli esterni	Fornitore di modelli antropici
claude-3-5-sonnet-20241022	Modelli esterni	Provider di modelli antropici. Questo modello supporta la chiamata di strumenti tramite Uso del computer (beta).
claude-3-5-haiku-20241022	Modelli esterni	Fornitore di modelli antropici
claude-3-5-sonnet-20240620	Modelli esterni	Fornitore di modelli antropici
claude-3-haiku-20240307	Modelli esterni	Fornitore di modelli antropici
claude-3-opus-20240229	Modelli esterni	Fornitore di modelli antropici
claude-3-sonnet-20240229	Modelli esterni	Fornitore di modelli antropici
claude-3-5-sonnet-20241022-v2:0	Modelli esterni	Fornitore di modelli di Bedrock Anthropic. Questo modello supporta la chiamata di strumenti tramite Uso del computer (beta).
claude-3-5-haiku-20241022-v1:0	Modelli esterni	Fornitore di modelli Bedrock Anthropic
claude-3-5-sonnet-20240620-v1:0	Modelli esterni	Fornitore di modelli Bedrock Anthropic
claude-3-sonnet-20240229-v1:0	Modelli esterni	Fornitore di modelli Bedrock Anthropic
claude-3-opus-20240229-v1:0	Modelli esterni	Fornitore di modelli Bedrock Anthropic

Usare la chiamata di funzione

Per utilizzare la chiamata di funzione con l'applicazione di intelligenza artificiale generativa, è necessario fornire una funzione parameters e un oggetto description.

Il comportamento predefinito per tool_choice è "auto". Ciò consente al modello di decidere quali funzioni chiamare e se chiamarle.

È possibile personalizzare il comportamento predefinito a seconda del caso d'uso. Di seguito sono riportate le opzioni disponibili:

• Imposta tool_choice: "required". In questo scenario, il modello chiama sempre una o più funzioni. Il modello seleziona la funzione o le funzioni da chiamare.
• Imposta tool_choice: {"type": "function", "function": {"name": "my_function"}}. In questo scenario, il modello chiama solo una funzione specifica.
• Impostare tool_choice: "none" per disabilitare le chiamate di funzione e fare in modo che il modello generi solo un messaggio rivolto all'utente.

Di seguito è riportato un esempio a turno singolo che usa OpenAI SDK e il relativo parametro tools. Per altri dettagli sulla sintassi, si veda Attività chat.

Important

Durante l'anteprima pubblica, la chiamata di funzione in Databricks è ottimizzata per le chiamate di funzione a turno singolo.

import os
import json
from openai import OpenAI

DATABRICKS_TOKEN = os.environ.get('YOUR_DATABRICKS_TOKEN')
DATABRICKS_BASE_URL = os.environ.get('YOUR_DATABRICKS_BASE_URL')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url=DATABRICKS_BASE_URL
  )

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 and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": [
              "celsius",
              "fahrenheit"
            ]
          }
        }
      }
    }
  }
]

messages = [{"role": "user", "content": "What is the current temperature of Chicago?"}]

response = client.chat.completions.create(
    model="databricks-meta-llama-3-3-70b-instruct",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

print(json.dumps(response.choices[0].message.model_dump()['tool_calls'], indent=2))

Questo parametro supporta anche l'uso di computer (beta) per i modelli Claude.

Schema JSON

Le API del modello di base supportano ampiamente le definizioni di funzione accettate da OpenAI. Tuttavia, l'uso di uno schema JSON più semplice per le definizioni delle chiamate di funzione porta a una generazione di JSON per le chiamate di funzione di qualità superiore. Per promuovere una generazione di qualità superiore, le API dei Modelli Fondamentali supportano solo un sottoinsieme delle specifiche dello schema JSON .

Le seguenti chiavi di definizione delle chiamate di funzione non sono supportate:

• Espressioni regolari utilizzando pattern.
• Composizione di schemi complessi e annidati e loro convalida tramite: anyOf, oneOf, allOf, prefixItemso $ref.
• Elenchi di tipi ad eccezione del caso speciale di [type, “null”] in cui un tipo nell'elenco è un tipo JSON valido e l'altro è "null"

Inoltre, si applicano le seguenti limitazioni:

• Il numero massimo di chiavi specificato nello schema JSON è 16.
• Le API del modello base non applicano vincoli di lunghezza o dimensioni per oggetti e matrici.
  • Sono incluse parole chiave come maxProperties, minProperties e maxLength.
• Gli schemi JSON fortemente annidati generano una generazione di qualità inferiore. Se possibile, provare a rendere flat lo schema JSON per ottenere risultati migliori.

Utilizzo dei token

Per migliorare la qualità delle chiamate agli strumenti si ricorre all'inserimento di prompt e ad altre tecniche. In questo modo si influisce sul numero di token di input e output utilizzati dal modello, con conseguenti implicazioni per la fatturazione. Più strumenti si usano, più aumentano i token di input.

Limiti

Di seguito sono riportate alcune limitazioni per la chiamata di funzione durante l'anteprima pubblica:

• Per la funzione a più turni che chiama Databricks consiglia i modelli Claude supportati.
• Se si usa Llama 4 Maverick, la soluzione di chiamata di funzione corrente è ottimizzata per le chiamate di funzione a turno singolo. Il funzionamento a più turni è supportato durante la modalità di anteprima, ma è ancora in fase di sviluppo.
• La chiamata di funzioni parallele non è supportata.
• Il numero massimo di funzioni che è possibile definire in tools è 32.
• Per il supporto del throughput con provisioning, le chiamate di funzione sono supportate solo su nuovi endpoint. Non è possibile aggiungere chiamate di funzione agli endpoint creati in precedenza.

Esempio di notebook

Si veda il seguente notebook per esempi dettagliati di chiamate di funzioni

Notebook d'esempio per chiamata di funzione

Prendere il notebook