Chiamata di funzioni in 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 base.

Che cos'è la chiamata di funzione

La chiamata a funzioni consente di controllare l'output delle macchine virtuali, in modo che generate risposte strutturate in modo più affidabile. Quando si usa una chiamata di funzione, si descrivono le funzioni nella chiamata API specificando gli argomenti della funzione con un JSON schema. 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 utilizzando 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 al schemapersonalizzato .
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

L'table seguente elenca i modelli supportati e la funzionalità di gestione dei modelli rende disponibili ogni modello.

• 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 dai modelli esterni, vedere Disponibilità dell'area per la disponibilità dell'area.

Utilizzare 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:

• Set tool_choice: "required". In questo scenario, il modello chiama sempre una o più funzioni. Il modello seleziona la funzione o le funzioni da chiamare.
• Set tool_choice: {"type": "function", "function": {"name": "my_function"}}. In questo scenario, il modello chiama solo una funzione specifica.
• Set tool_choice: "none" disabilitare le chiamate di funzione e fare in modo che il modello generate 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.

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

schema JSON

Le API del modello di base supportano ampiamente le definizioni di funzione accettate da OpenAI. Tuttavia, l'uso di un schema JSON più semplice per le definizioni delle chiamate di funzione comporta una generazione JSON di chiamata di funzione di qualità superiore. Per promuovere una generazione di qualità superiore, le API del modello Foundation supportano solo un subset di specifiche JSON schema.

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

• Espressioni regolari utilizzando pattern.
• Composizione e convalida annidata o schema complessa tramite: anyOf, oneOf, allOf, prefixItemso $ref.
• Elenchi di tipi ad eccezione del caso speciale di [type, “null”]where un tipo nel list è un tipo JSON valido e l'altro è "null"

Inoltre, si applicano le seguenti limitazioni:

• Il numero massimo di chiavi specificato nel 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.
• Schemi JSON fortemente annidati daranno luogo a una generazione di qualità inferiore. Se possibile, provare a appiattire il JSON schema 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:

• La soluzione di chiamata di funzione corrente è ottimizzata per le chiamate di funzione a turno singolo. La chiamata a più turni viene supportata durante l'anteprima, ma è 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 della velocità effettiva con provisioning, la chiamata di funzione è supportata solo nei 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 di esempio di chiamata di funzione

Get quaderno