Chiamate di funzione con l'API Gemini

La chiamata di funzioni ti consente di collegare i modelli a strumenti e API esterni. Anziché generare risposte di testo, il modello comprende quando chiamare funzioni specifiche e fornisce i parametri necessari per eseguire azioni reali. In questo modo, il modello funge da ponte tra il linguaggio naturale e le azioni e i dati del mondo reale. Le chiamate di funzione hanno tre casi d'uso principali:

  • Aumenta la conoscenza:accedi alle informazioni da origini esterne come database, API e knowledge base.
  • Espandi le funzionalità:utilizza strumenti esterni per eseguire calcoli ed estendere le limitazioni del modello, ad esempio utilizzando una calcolatrice o creando grafici.
  • Esegui azioni:interagisci con sistemi esterni utilizzando le API, ad esempio per pianificare appuntamenti, creare fatture, inviare email o controllare dispositivi per la smart home.

Come funzionano le chiamate di funzione

Panoramica delle chiamate di funzione

La chiamata di funzioni prevede un'interazione strutturata tra l'applicazione, il modello e le funzioni esterne. Ecco una suddivisione della procedura:

  1. Definisci la dichiarazione di funzione:definisci la dichiarazione di funzione nel codice dell'applicazione. Le dichiarazioni di funzione descrivono al modello il nome, i parametri e lo scopo della funzione.
  2. Chiama LLM con dichiarazioni di funzione:invia al modello il prompt dell'utente insieme alle dichiarazioni di funzione. Analizza la richiesta e determina se una chiamata di funzione sarebbe utile. In questo caso, risponde con un oggetto JSON strutturato.
  3. Codice di esecuzione della funzione (responsabilità dell'utente): il modello non esegue la funzione stessa. È responsabilità della tua applicazione elaborare la risposta e verificare la presenza di una chiamata di funzione, se
    • Sì: estrai il nome e gli argomenti della funzione ed esegui la funzione corrispondente nella tua applicazione.
    • No: il modello ha fornito una risposta di testo diretta al prompt (questo flusso è meno enfatizzato nell'esempio, ma è un possibile risultato).
  4. Crea una risposta facile da usare:se è stata eseguita una funzione, acquisisci il risultato e rispediscilo al modello in un turno successivo della conversazione. Utilizzerà il risultato per generare una risposta finale facile da usare che incorpori le informazioni della chiamata di funzione.

Questa procedura può essere ripetuta per più turni, consentendo interazioni e flussi di lavoro complessi. Il modello supporta anche la chiamata di più funzioni in un singolo turno (chiamate di funzioni in parallelo) e in sequenza (chiamate di funzioni compositive).

Passaggio 1: definisci la dichiarazione della funzione

Definisci una funzione e la relativa dichiarazione all'interno del codice dell'applicazione che consenta agli utenti di impostare i valori delle luci ed effettuare una richiesta API. Questa funzione potrebbe chiamare API o servizi esterni.

PythonJavaScript
from google.genai import types

# Define a function that the model can call to control smart lights
set_light_values_declaration = {
    "name": "set_light_values",
    "description": "Sets the brightness and color temperature of a light.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "integer",
                "description": "Light level from 0 to 100. Zero is off and 100 is full brightness",
            },
            "color_temp": {
                "type": "string",
                "enum": ["daylight", "cool", "warm"],
                "description": "Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.",
            },
        },
        "required": ["brightness", "color_temp"],
    },
}

# This is the actual function that would be called based on the model's suggestion
def set_light_values(brightness: int, color_temp: str) -> dict[str, int | str]:
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {"brightness": brightness, "colorTemperature": color_temp}


import { Type } from '@google/genai';

// Define a function that the model can call to control smart lights
const setLightValuesFunctionDeclaration = {
  name: 'set_light_values',
  description: 'Sets the brightness and color temperature of a light.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'Light level from 0 to 100. Zero is off and 100 is full brightness',
      },
      color_temp: {
        type: Type.STRING,
        enum: ['daylight', 'cool', 'warm'],
        description: 'Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.',
      },
    },
    required: ['brightness', 'color_temp'],
  },
};

/**
* Set the brightness and color temperature of a room light. (mock API)
* @param {number} brightness - Light level from 0 to 100. Zero is off and 100 is full brightness
* @param {string} color_temp - Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.
* @return {Object} A dictionary containing the set brightness and color temperature.
*/
function setLightValues(brightness, color_temp) {
  return {
    brightness: brightness,
    colorTemperature: color_temp
  };
}

Passaggio 2: chiama il modello con le dichiarazioni di funzione

Dopo aver definito le dichiarazioni delle funzioni, puoi chiedere al modello di utilizzarla. Analizza le dichiarazioni del prompt e delle funzioni e decide se rispondere direttamente o chiamare una funzione. Se viene chiamata una funzione, l'oggetto risposta conterrà un suggerimento per la chiamata della funzione.

PythonJavaScript
from google import genai

# Generation Config with Function Declaration
tools = types.Tool(function_declarations=[set_light_values_declaration])
config = types.GenerateContentConfig(tools=[tools])

# Configure the client
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

# Define user prompt
contents = [
    types.Content(
        role="user", parts=[types.Part(text="Turn the lights down to a romantic level")]
    )
]

# Send request with function declarations
response = client.models.generate_content(
    model="gemini-2.0-flash", config=config, contents=contents
)

print(response.candidates[0].content.parts[0].function_call)

import { GoogleGenAI } from '@google/genai';

// Generation Config with Function Declaration
const config = {
  tools: [{
    functionDeclarations: [setLightValuesFunctionDeclaration]
  }]
};

// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Define user prompt
const contents = [
  {
    role: 'user',
    parts: [{ text: 'Turn the lights down to a romantic level' }]
  }
];

// Send request with function declarations
const response = await ai.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: contents,
  config: config
});

console.log(response.functionCalls[0]);

Il modello restituisce quindi un oggetto functionCall in uno schema compatibile con OpenAPI che specifica come chiamare una o più delle funzioni dichiarate per rispondere alla domanda dell'utente.

PythonJavaScript
id=None args={'color_temp': 'warm', 'brightness': 25} name='set_light_values'

{
  name: 'set_light_values',
  args: { brightness: 25, color_temp: 'warm' }
}

Passaggio 3: esegui il codice della funzione set_light_values

Estrai i dettagli della chiamata di funzione dalla risposta del modello, analizza gli argomenti esegui la funzione set_light_values nel nostro codice.

PythonJavaScript
# Extract tool call details
tool_call = response.candidates[0].content.parts[0].function_call

if tool_call.name == "set_light_values":
    result = set_light_values(**tool_call.args)
    print(f"Function execution result: {result}")

// Extract tool call details
const tool_call = response.functionCalls[0]

let result;
if (tool_call.name === 'set_light_values') {
  result = setLightValues(tool_call.args.brightness, tool_call.args.color_temp);
  console.log(`Function execution result: ${JSON.stringify(result)}`);
}

Passaggio 4: crea una risposta facile da usare con il risultato della funzione e chiama di nuovo il modello

Infine, invia il risultato dell'esecuzione della funzione al modello in modo che possa incorporare queste informazioni nella risposta finale all'utente.

PythonJavaScript
# Create a function response part
function_response_part = types.Part.from_function_response(
    name=tool_call.name,
    response={"result": result},
)

# Append function call and result of the function execution to contents
contents.append(types.Content(role="model", parts=[types.Part(function_call=tool_call)])) # Append the model's function call message
contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response

final_response = client.models.generate_content(
    model="gemini-2.0-flash",
    config=config,
    contents=contents,
)

print(final_response.text)

// Create a function response part
const function_response_part = {
  name: tool_call.name,
  response: { result }
}

// Append function call and result of the function execution to contents
contents.push({ role: 'model', parts: [{ functionCall: tool_call }] });
contents.push({ role: 'user', parts: [{ functionResponse: function_response_part }] });

// Get the final response from the model
const final_response = await ai.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: contents,
  config: config
});

console.log(final_response.text);

In questo modo, il flusso di chiamata della funzione è completato. Il modello ha utilizzato correttamente la funzione set_light_values per eseguire l'azione di richiesta dell'utente.

Dichiarazioni di funzione

Quando implementi la chiamata di funzione in un prompt, crei un oggetto tools contenente uno o più function declarations. Definisci le funzioni utilizzando JSON, in particolare con un sottoinsieme selezionato del formato dello schema OpenAPI. Una singola dichiarazione di funzione può includere i seguenti parametri:

  • name (stringa): un nome univoco per la funzione (get_weather_forecast, send_email). Utilizza nomi descrittivi senza spazi o caratteri speciali (utilizza trattini bassi o lettere maiuscole e minuscole).
  • description (stringa): una spiegazione chiara e dettagliata dello scopo e delle funzionalità della funzione. Questo è fondamentale per consentire al modello di capire quando utilizzare la funzione. Fornisci esempi se utili ("Trova i cinema in base alla località e, facoltativamente, al titolo del film attualmente in programmazione").
  • parameters (oggetto): definisce i parametri di input previsti dalla funzione.
    • type (stringa): specifica il tipo di dati complessivo, ad esempio object.
    • properties (oggetto): elenca i singoli parametri, ciascuno con:
      • type (stringa): il tipo di dati del parametro, ad esempio string, integer, boolean, array.
      • description (stringa): una descrizione dello scopo e del formato del parametro. Fornisci esempi e vincoli ("La città e lo stato, ad es. "San Francisco, CA" o un codice postale, ad esempio '95616'.").
      • enum (array, facoltativo): se i valori del parametro provengono da un insieme fisso, utilizza "enum" per elencare i valori consentiti anziché descriverli semplicemente nella descrizione. In questo modo viene migliorata la precisione ("enum": ["daylight", "cool", "warm"]).
    • required (array): un array di stringhe che elenca i nomi dei parametri obbligatori per il funzionamento della funzione.

Chiamata di funzioni parallele

Oltre a chiamare una singola funzione di svolta, puoi anche chiamare più funzioni contemporaneamente. La chiamata di funzioni parallele ti consente di eseguire più funzioni contemporaneamente e viene utilizzata quando le funzioni non sono dipendenti l'una dall'altra. Questo è utile in scenari come la raccolta di dati da più origini indipendenti, ad esempio il recupero dei dettagli dei clienti da diversi database o il controllo dei livelli di inventario in vari magazzini o l'esecuzione di più azioni come la conversione del tuo appartamento in un locale.

PythonJavaScript
power_disco_ball = {
    "name": "power_disco_ball",
    "description": "Powers the spinning disco ball.",
    "parameters": {
        "type": "object",
        "properties": {
            "power": {
                "type": "boolean",
                "description": "Whether to turn the disco ball on or off.",
            }
        },
        "required": ["power"],
    },
}

start_music = {
    "name": "start_music",
    "description": "Play some music matching the specified parameters.",
    "parameters": {
        "type": "object",
        "properties": {
            "energetic": {
                "type": "boolean",
                "description": "Whether the music is energetic or not.",
            },
            "loud": {
                "type": "boolean",
                "description": "Whether the music is loud or not.",
            },
        },
        "required": ["energetic", "loud"],
    },
}

dim_lights = {
    "name": "dim_lights",
    "description": "Dim the lights.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "number",
                "description": "The brightness of the lights, 0.0 is off, 1.0 is full.",
            }
        },
        "required": ["brightness"],
    },
}

import { Type } from '@google/genai';

const powerDiscoBall = {
  name: 'power_disco_ball',
  description: 'Powers the spinning disco ball.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      power: {
        type: Type.BOOLEAN,
        description: 'Whether to turn the disco ball on or off.'
      }
    },
    required: ['power']
  }
};

const startMusic = {
  name: 'start_music',
  description: 'Play some music matching the specified parameters.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      energetic: {
        type: Type.BOOLEAN,
        description: 'Whether the music is energetic or not.'
      },
      loud: {
        type: Type.BOOLEAN,
        description: 'Whether the music is loud or not.'
      }
    },
    required: ['energetic', 'loud']
  }
};

const dimLights = {
  name: 'dim_lights',
  description: 'Dim the lights.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'The brightness of the lights, 0.0 is off, 1.0 is full.'
      }
    },
    required: ['brightness']
  }
};

Chiama il modello con un'istruzione che potrebbe utilizzare tutti gli strumenti specificati. Questo esempio utilizza un tool_config. Per scoprire di più, puoi leggere l'articolo sulla configurazione delle chiamate di funzione.

PythonJavaScript
from google import genai
from google.genai import types

# Set up function declarations
house_tools = [
    types.Tool(function_declarations=[power_disco_ball, start_music, dim_lights])
]

config = {
    "tools": house_tools,
    "automatic_function_calling": {"disable": True},
    # Force the model to call 'any' function, instead of chatting.
    "tool_config": {"function_calling_config": {"mode": "any"}},
}

# Configure the client
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

chat = client.chats.create(model="gemini-2.0-flash", config=config)
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call
print("Example 1: Forced function calling")
for fn in response.function_calls:
    args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
    print(f"{fn.name}({args})")

import { GoogleGenAI } from '@google/genai';

// Set up function declarations
const houseFns = [powerDiscoBall, startMusic, dimLights];

const config = {
    tools: [{
        functionDeclarations: houseFns
    }],
    // Force the model to call 'any' function, instead of chatting.
    toolConfig: {
        functionCallingConfig: {
        mode: 'any'
        }
    }
};

// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Create a chat session
const chat = ai.chats.create({
    model: 'gemini-2.0-flash',
    config: config
});
const response = await chat.sendMessage({message: 'Turn this place into a party!'});

// Print out each of the function calls requested from this single call
console.log("Example 1: Forced function calling");
for (const fn of response.functionCalls) {
    const args = Object.entries(fn.args)
        .map(([key, val]) => `${key}=${val}`)
        .join(', ');
    console.log(`${fn.name}(${args})`);
}

Ciascuno dei risultati stampati riflette una singola chiamata di funzione richiesta dal modello. Per inviare i risultati, includi le risposte nello stesso ordine in cui sono state richieste.

L'SDK Python supporta una funzionalità chiamata chiamata di funzioni automatica che converte la funzione Python in dichiarazioni, gestisce l'esecuzione della chiamata di funzione e il ciclo di risposta per te. Di seguito è riportato un esempio per il nostro caso d'uso disco.

Python
from google import genai
from google.genai import types

# Actual implementation functions
def power_disco_ball_impl(power: bool) -> dict:
    """Powers the spinning disco ball.

    Args:
        power: Whether to turn the disco ball on or off.

    Returns:
        A status dictionary indicating the current state.
    """
    return {"status": f"Disco ball powered {'on' if power else 'off'}"}

def start_music_impl(energetic: bool, loud: bool) -> dict:
    """Play some music matching the specified parameters.

    Args:
        energetic: Whether the music is energetic or not.
        loud: Whether the music is loud or not.

    Returns:
        A dictionary containing the music settings.
    """
    music_type = "energetic" if energetic else "chill"
    volume = "loud" if loud else "quiet"
    return {"music_type": music_type, "volume": volume}

def dim_lights_impl(brightness: float) -> dict:
    """Dim the lights.

    Args:
        brightness: The brightness of the lights, 0.0 is off, 1.0 is full.

    Returns:
        A dictionary containing the new brightness setting.
    """
    return {"brightness": brightness}

config = {
    "tools": [power_disco_ball_impl, start_music_impl, dim_lights_impl],
}

chat = client.chats.create(model="gemini-2.0-flash", config=config)
response = chat.send_message("Do everything you need to this place into party!")

print("\nExample 2: Automatic function calling")
print(response.text)
# I've turned on the disco ball, started playing loud and energetic music, and dimmed the lights to 50% brightness. Let's get this party started!

Chiamata di funzioni compositive

Gemini 2.0 supporta le chiamate di funzioni compositive, il che significa che il modello può mettere in catena più chiamate di funzioni. Ad esempio, per rispondere a "Richiedi la temperatura nella mia posizione attuale", l'API Gemini potrebbe chiamare sia una funzione get_current_location() sia una funzione get_weather() che prende la posizione come parametro.

PythonJavaScript
# Light control schemas
turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}

prompt = """
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
  """

tools = [
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]

await run(prompt, tools=tools, modality="AUDIO")

// Light control schemas
const turnOnTheLightsSchema = { name: 'turn_on_the_lights' };
const turnOffTheLightsSchema = { name: 'turn_off_the_lights' };

const prompt = `
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
`;

const tools = [
  { codeExecution: {} },
  { functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] }
];

await run(prompt, tools=tools, modality="AUDIO")

Modalità di chiamata di funzione

L'API Gemini ti consente di controllare il modo in cui il modello utilizza gli strumenti forniti (dichiarazioni di funzione). Nello specifico, puoi impostare la modalità in function_calling_config.

  • AUTO (Default): il modello decide se generare una risposta in linguaggio naturale o suggerire una chiamata di funzione in base al prompt e al contesto. Si tratta della modalità più flessibile e consigliata per la maggior parte degli scenari.
  • ANY: il modello è vincolato a prevedere sempre una chiamata di funzione e a garantire l'adesione allo schema della funzione. Se allowed_function_names non è specificato, il modello può scegliere tra le dichiarazioni di funzione fornite. Se allowed_function_names viene fornito come elenco, il modello può scegliere solo tra le funzioni nell'elenco. Utilizza questa modalità quando richiedi una chiamata di funzione in risposta a ogni prompt (se applicabile).

  • NONE: al modello è vietato effettuare chiamate di funzione. Ciò equivale a inviare una richiesta senza dichiarazioni di funzioni. Utilizzalo per disattivare temporaneamente le chiamate di funzione senza rimuovere le definizioni degli strumenti.

PythonJavaScript
from google.genai import types

# Configure function calling mode
tool_config = types.ToolConfig(
    function_calling_config=types.FunctionCallingConfig(
        mode="ANY", allowed_function_names=["get_current_temperature"]
    )
)

# Create the generation config
config = types.GenerateContentConfig(
    temperature=0,
    tools=[tools],  # not defined here.
    tool_config=tool_config,
)

import { FunctionCallingConfigMode } from '@google/genai';

// Configure function calling mode
const toolConfig = {
  functionCallingConfig: {
    mode: FunctionCallingConfigMode.ANY,
    allowedFunctionNames: ['get_current_temperature']
  }
};

// Create the generation config
const config = {
  temperature: 0,
  tools: tools, // not defined here.
  toolConfig: toolConfig,
};

Chiamata di funzioni automatiche (solo Python)

Quando utilizzi l'SDK Python, puoi fornire le funzioni Python direttamente come strumenti. L'SDK converte automaticamente la funzione Python in dichiarazioni e gestisce l'esecuzione della chiamata della funzione e il ciclo di risposta. L'SDK Python esegue automaticamente le seguenti operazioni:

  1. Rileva le risposte alle chiamate di funzione del modello.
  2. Chiama la funzione Python corrispondente nel codice.
  3. Invia la risposta della funzione al modello.
  4. Restituisce la risposta di testo finale del modello.

Per utilizzarlo, definisci la funzione con suggerimenti sui tipi e una docstring, quindi passa la funzione stessa (non una dichiarazione JSON) come strumento:

Python
from google import genai
from google.genai import types

# Define the function with type hints and docstring
def get_current_temperature(location: str) -> dict:
    """Gets the current temperature for a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA

    Returns:
        A dictionary containing the temperature and unit.
    """
    # ... (implementation) ...
    return {"temperature": 25, "unit": "Celsius"}

# Configure the client and model
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))  # Replace with your actual API key setup
config = types.GenerateContentConfig(
    tools=[get_current_temperature]
)  # Pass the function itself

# Make the request
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="What's the temperature in London?",
    config=config,
)

print(response.text)  # The SDK handles the function call and returns the final text

Puoi disattivare la chiamata automatica delle funzioni con:

Python
# To disable automatic function calling:
config = types.GenerateContentConfig(
    tools=[get_current_temperature],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)

Dichiarazione dello schema della funzione automatica

L'estrazione automatica dello schema dalle funzioni Python non funziona in tutti i casi. Ad esempio, non gestisce i casi in cui descrivi i campi di un oggetto dizionario nidificato. L'API è in grado di descrivere uno dei seguenti tipi:

Python
AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])

Per vedere l'aspetto dello schema dedotto, puoi convertirlo utilizzando from_callable:

Python
def multiply(a: float, b: float):
    """Returns a * b."""
    return a * b

fn_decl = types.FunctionDeclaration.from_callable(callable=multiply, client=client)

# to_json_dict() provides a clean JSON representation.
print(fn_decl.to_json_dict())

Utilizzo di più strumenti: combina gli strumenti nativi con le chiamate di funzione

Con Gemini 2.0, puoi attivare più strumenti contemporaneamente combinando gli strumenti nativi con le chiamate di funzione. Di seguito è riportato un esempio che attiva due strumenti, Grounding con la Ricerca Google ed esecuzione di codice, in una richiesta che utilizza l'API Live.

PythonJavaScript

# Multiple tasks example - combining lights, code execution, and search
prompt = """
  Hey, I need you to do three things for me.

    1.  Turn on the lights.
    2.  Then compute the largest prime palindrome under 100000.
    3.  Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
  """

tools = [
    {'google_search': {}},
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]} # not defined here.
]

# Execute the prompt with specified tools in audio modality
await run(prompt, tools=tools, modality="AUDIO")

// Multiple tasks example - combining lights, code execution, and search
const prompt = `
  Hey, I need you to do three things for me.

    1.  Turn on the lights.
    2.  Then compute the largest prime palindrome under 100000.
    3.  Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
`;

const tools = [
  { googleSearch: {} },
  { codeExecution: {} },
  { functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] } // not defined here.
];

// Execute the prompt with specified tools in audio modality
await run(prompt, {tools: tools, modality: "AUDIO"});

Gli sviluppatori Python possono provare questa funzionalità nel notebook di utilizzo dello strumento API Live.

Modelli supportati

I modelli sperimentali non sono inclusi. Puoi trovare le relative funzionalità nella pagina Panoramica del modello.

Modello Chiamate di funzione Chiamata di funzioni parallele Chiamate di funzioni compositive
(solo API Live)
Gemini 2.0 Flash ✔️ ✔️ ✔️
Gemini 2.0 Flash-Lite X X X
Gemini 1.5 Flash ✔️ ✔️ ✔️
Gemini 1.5 Pro ✔️ ✔️ ✔️

Best practice

  • Descrizioni di funzioni e parametri:sii estremamente chiaro e specifico nelle descrizioni. Il modello si basa su questi dati per scegliere la funzione corretta e fornire gli argomenti appropriati.
  • Nomi: utilizza nomi di funzioni descrittivi (senza spazi, punti o trattini).
  • Tipizzazione forte:utilizza tipi specifici (integer, stringa, enum) per i parametri per ridurre gli errori. Se un parametro ha un insieme limitato di valori validi, utilizza un enum.
  • Prompt engineering:
    • Fornisci il contesto: indica al modello il suo ruolo (ad es. "Sei un'assistente meteo utile").
    • Fornisci istruzioni: specifica come e quando utilizzare le funzioni (ad es. "Non indovinare le date; utilizza sempre una data futura per le previsioni".
    • Incoraggia i chiarimenti: se necessario, chiedi al modello di porre domande per chiarire.
  • Temperatura:utilizza una temperatura bassa (ad es. 0) per chiamate di funzioni più deterministiche e affidabili.
  • Convalida:se una chiamata di funzione ha conseguenze significative (ad es. l'inserimento di un ordine), convalida la chiamata con l'utente prima di eseguirla.
  • Gestione degli errori: implementa una gestione degli errori solida nelle tue funzioni per gestire in modo elegante input imprevisti o errori dell'API. Restituire messaggi di errore informativi che il modello può utilizzare per generare risposte utili all'utente.
  • Sicurezza:presta attenzione alla sicurezza quando chiami API esterne. Utilizza meccanismi di autenticazione e autorizzazione appropriati. Evita di esporre dati sensibili nelle chiamate alle funzioni.
  • Limiti di token:le descrizioni e i parametri delle funzioni vengono conteggiati ai fini del limite di token di input. Se raggiungi i limiti di token, valuta la possibilità di limitare il numero di funzioni o la lunghezza delle descrizioni, suddividi le attività complesse in insiemi di funzioni più piccoli e mirati.

Note e limitazioni

  • È supportato solo un sottoinsieme dello schema OpenAPI.
  • I tipi di parametri supportati in Python sono limitati.
  • La chiamata automatica delle funzioni è una funzionalità solo dell'SDK Python.