Introduzione alle chiamate di funzione con l'API Gemini

Utilizzando la funzionalità di chiamata di funzione dell'API Gemini, puoi fornire una funzione personalizzata le definizioni del modello. Il modello non richiama direttamente queste funzioni, ma genera invece un output strutturato che specifica il nome di una funzione e argomenti. Puoi quindi utilizzare il nome e gli argomenti della funzione per chiamare un'API esterna e incorporare l'output dell'API risultante in un'ulteriore query al modello, in modo che il modello possa fornire una risposta più completa ed eseguire azioni aggiuntive.

La chiamata di funzione consente agli utenti di interagire con informazioni in tempo reale e come database, sistemi di gestione dei rapporti con i clienti e repository. La caratteristica migliora anche la capacità del modello di fornire informazioni e risposte contestuali. La chiamata di funzioni è ideale per interagire con sistemi esterni. Se il tuo caso d'uso richiede che il modello esegua il calcolo ma non coinvolgano API o sistemi esterni, considera l'uso l'esecuzione del codice.

Per un esempio funzionante di chiamata di funzione, consulta "bot luce" un blocco note personalizzato.

Come funzionano le chiamate di funzione

Puoi usare la funzionalità di chiamata di funzione aggiungendo dati di query strutturati che descrivono interfacce di programmazione, chiamate dichiarazioni di funzione, a un prompt del modello. La le dichiarazioni di funzione forniscono il nome della funzione API, ne spiegano lo scopo, i parametri supportati e le relative descrizioni. Dopo aver passato al modello un elenco di dichiarazioni di funzione in una query, il modello analizza le dichiarazioni di funzione e il resto della query per determinare come utilizzare l'API dichiarata in risposta alla richiesta.

Il modello restituisce quindi un oggetto Schema compatibile con OpenAPI che specifichi come chiamare una o più funzioni dichiarate per rispondere alla domanda dell'utente. Puoi quindi utilizzare i parametri di chiamata di funzione consigliati, chiamare l'API effettiva, ricevere una risposta e fornirla all'utente o intraprendere ulteriori azioni. Tieni presente che il modello in realtà non chiama con le funzioni dichiarate. Utilizza invece i parametri oggetto dello schema restituiti per chiama la funzione. L'API Gemini supporta anche le chiamate di funzioni parallele, per cui il modello consiglia più chiamate di funzioni API basate su una singola richiesta.

Dichiarazioni di funzione

Quando implementi la chiamata di funzione in un prompt, crei un oggetto tools, che contiene uno o più function declarations. Sei tu a definire le funzioni utilizzando JSON, in particolare seleziona un sottoinsieme del Schema OpenAPI formato. Una singola dichiarazione di funzione può includere i seguenti parametri:

  • name (stringa): l'identificatore univoco della funzione all'interno della chiamata dell'API.
  • description (stringa): una spiegazione completa dello scopo e delle funzionalità della funzione.
  • parameters (oggetto): definisce i dati di input richiesti 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.
      • description (stringa): una spiegazione chiara dello scopo e del formato previsto del parametro.
    • required (array): un array di stringhe che elencano i nomi dei parametri. obbligatori per il corretto funzionamento della funzione.

Per esempi di codice di una dichiarazione di funzione che utilizza i comandi cURL, consulta Esempi di chiamate di funzione. Per esempi di creare dichiarazioni di funzione utilizzando gli SDK dell'API Gemini, consulta Tutorial sulle chiamate di funzione.

Best practice per le dichiarazioni di funzione

La definizione accurata delle funzioni è essenziale quando le integri nel tuo richieste. Ogni funzione si basa su parametri specifici che ne guidano il comportamento e l'interazione con il modello. Il seguente elenco fornisce indicazioni su definire i parametri di una singola funzione in un functions_declarations un array di dati.

  • name: utilizza nomi chiari e descrittivi senza spazi, punti (.) o trattini (-). Utilizza invece i trattini bassi (_) o le lettere maiuscole iniziali.

  • description: fornisci una funzione dettagliata, chiara e specifica descrizioni, fornendo esempi se necessario. Ad esempio, invece di find theaters, utilizza find theaters based on location and optionally movie title that is currently playing in theaters. Evita di utilizzare termini troppo generici o ambigui descrizioni.

  • properties > type: utilizza parametri fortemente tipiizzati per ridurre le allucinazioni del modello. Ad esempio, se i valori dei parametri provengono da un intervallo impostato, utilizza un campo enum anziché elencare i valori nella descrizione (ad es. "type": "enum", "values": ["now_playing", "upcoming"]). Se il valore del parametro è sempre un numero intero, imposta il tipo su integer anziché su number.

  • properties > description: fornisci esempi e vincoli concreti. Ad esempio, utilizza The city and state, e.g. San Francisco, CA or a zip code e.g. 95616 anziché the location to search.

Per altre best practice sull'utilizzo delle chiamate di funzione, consulta la sezione Best practice.

Modalità chiamata di funzione

Puoi utilizzare il parametro di chiamata della funzione mode per modificare il comportamento di esecuzione della funzionalità. Sono disponibili tre modalità:

  • AUTO: il comportamento predefinito del modello. Il modello decide di prevedere una chiamata di funzione o una risposta in linguaggio naturale.
  • ANY: il modello è vincolato a prevedere sempre una chiamata di funzione. Se allowed_function_names non viene fornito, il modello sceglie tra tutte le dichiarazioni di funzione disponibili. Se allowed_function_names è fornito, il modello sceglie dall'insieme di funzioni consentite.
  • NONE: il modello non prevede una chiamata di funzione. In questo caso, il modello è lo stesso che se non passi alcuna dichiarazione di funzione.

L'utilizzo della modalità ANY ("chiamate di funzione forzate") è supportato solo per i modelli Gemini 1.5 Pro e Gemini 1.5 Flash.

Puoi anche trasmettere un insieme di allowed_function_names che, se disponibili, limitano le funzioni che il modello chiamerà. Devi includere allowed_function_names solo quando la modalità è ANY. I nomi delle funzioni devono corrispondere i nomi delle dichiarazioni di funzione. Con la modalità impostata su ANY e il allowed_function_names impostato, il modello prevede una chiamata di funzione dal insieme di nomi di funzioni forniti.

Il seguente snippet di codice di una richiesta di esempio mostra come impostaremode su ANY e specificare un elenco di funzioni consentite:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Esempi di chiamate di funzione

Questa sezione fornisce prompt di esempio per la chiamata di funzioni utilizzando i comandi cURL. Gli esempi includono scenari con una svolta e più svolte e l'attivazione di diverse modalità di chiamata delle funzioni.

Quando utilizzi i comandi cURL con questa funzionalità, la funzione e il parametro incluse nell'elemento tools. Ogni dichiarazione di funzione nell'elemento tools contiene il nome della funzione e specifichi i parametri utilizzando uno schema compatibile con OpenAPI e una descrizione della funzione.

Esempio a turno singolo

La modalità singola chiamata prevede di chiamare il modello linguistico una sola volta. Con le chiamate di funzione, un caso d'uso con un solo passaggio potrebbe essere quando fornisci al modello una query in linguaggio naturale e un elenco di funzioni. In questo caso, il modello utilizza la dichiarazione della funzione, che include il nome, i parametri e la descrizione della funzione, per predire quale funzione chiamare e gli argomenti con cui chiamarla.

Il seguente esempio di curl è un esempio di passaggio in una descrizione di un che restituisce informazioni sul punto in cui è in riproduzione un film. Nella richiesta sono incluse diverse dichiarazioni di funzione, ad esempio find_movies e find_theaters.

Richiesta di esempio di chiamata di funzione a turno singolo

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "Which theaters in Mountain View show Barbie movie?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ]
}'

La risposta a questo esempio di curl potrebbe essere simile alla seguente.

Funzione a turno singolo che chiama una risposta di esempio curl

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "movie": "Barbie",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "totalTokenCount": 9
  }
}]

Esempio di un solo passaggio con la modalità QUALSIASI

Il seguente esempio di curl è simile alla esempio a turno singolo, ma imposta quindi imposta la modalità su ANY:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY"
  },
}

Chiamata di funzione con un solo passaggio utilizzando la modalità QUALSIASI (richiesta)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY"
    },
  }
}'

La risposta potrebbe essere simile alla seguente:

Chiamata di funzione con un solo passaggio utilizzando la modalità QUALSIASI (risposta)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "",
                "location": "North Seattle, WA"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

Esempio di svolta singola con la modalità QUALSIASI e le funzioni consentite

Il seguente esempio di curl è simile alla esempio a turno singolo, ma imposta dalla modalità a ANY e include un elenco di :

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Chiamate di funzione a turno singolo utilizzando la modalità QUALSIASI e le funzioni consentite (richiesta)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY",
      "allowed_function_names": ["find_theaters", "get_showtimes"]
    },
  }
}'

Il modello non può prevedere la funzione find_movies perché non è nell'elenco di funzioni consentite, quindi prevede una funzione diversa. La risposta potrebbe essere simile alla seguente:

Chiamate di funzione a turno singolo utilizzando la modalità QUALSIASI e le funzioni consentite (risposta)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "location": "North Seattle, WA",
                "movie": null
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

Esempi in più passaggi

Per implementare uno scenario di chiamata di funzioni con più turni, procedi nel seguente modo:

  1. Ricevi una risposta alla chiamata di funzione chiamando il modello linguistico. Questa è la prima svolta.
  2. Chiama il modello linguistico utilizzando la risposta alla chiamata di funzione del primo turno e la risposta della funzione che ottieni chiamando la funzione. Questo è il secondo turno.

La risposta del secondo turno riassume i risultati per rispondere alla query nel primo turno o contiene una seconda chiamata di funzione che puoi utilizzare per ottenere maggiori informazioni sulla query.

Questo argomento include due esempi di curl con più giri:

Usa una risposta di una svolta precedente

Il seguente esempio di curl chiama la funzione e gli argomenti restituiti dall'esempio precedente con una sola svolta per ottenere una risposta. Il metodo e i parametri retitrati dall'esempio con una sola svolta sono in questo JSON.

"functionCall": {
  "name": "find_theaters",
  "args": {
    "movie": "Barbie",
    "location": "Mountain View, CA"
  }
}

Richiesta di esempio di chiamata di funzione con più turni di curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

La risposta a questo esempio curl include il risultato della chiamata al metodo find_theaters. La risposta potrebbe essere simile alla seguente:

Risposta di esempio di chiamata di funzione con più turni di curl

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  }
}

Chiama il modello più volte

Il seguente esempio di cURL chiama il modello di IA generativa più volte per chiamare una funzione. Ogni volta che il modello chiama la funzione, può utilizzare una funzione diversa per rispondere a una query utente diversa nella richiesta.

Funzione multi-turno che chiama una richiesta di esempio curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  },
  {
    "role": "model",
    "parts": [{
      "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
    }]
  },{
    "role": "user",
    "parts": [{
      "text": "Can we recommend some comedy movies on show in Mountain View?"
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

Funzione multi-turno che chiama una risposta di esempio curl

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "comedy",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 48,
    "totalTokenCount": 48
  }
}
]

Best practice

Segui queste best practice per migliorare la precisione e l'affidabilità delle chiamate alle funzioni.

Prompt dell'utente

Per risultati ottimali, anteponi alla query dell'utente i seguenti dettagli:

  • Contesto aggiuntivo per il modello. Ad esempio, You are a movie API assistant to help users find movies and showtimes based on their preferences.
  • Dettagli o istruzioni su come e quando utilizzare le funzioni. Ad esempio: Don't make assumptions on showtimes. Always use a future date for showtimes.
  • Istruzioni per porre domande di chiarimento se le query degli utenti sono ambigue. Ad esempio, Ask clarifying questions if not enough information is available to complete the request.

Parametri di campionamento

Per il parametro temperatura, utilizza 0 o un altro valore basso. In questo modo, il modello genera risultati più affidabili e riduce le allucinazioni.

Invocazione dell'API

Se il modello propone l'invocazione di una funzione che invia un ordine, aggiorna un database o ha conseguenze significative, convalida la chiamata della funzione con l'utente prima di eseguirla.