Introduzione alle chiamate di funzione con l'API Gemini

Utilizzando la funzionalità di chiamata di funzione dell'API Gemini, puoi fornire al modello definizioni di funzioni personalizzate. Il modello non richiama direttamente queste funzioni, ma genera un output strutturato che specifica un nome di funzione e argomenti suggeriti. 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 e servizi in tempo reale, come database, sistemi di gestione dei rapporti con i clienti e repository di documenti. La funzionalità migliora anche la capacità del modello di fornire risposte pertinenti e contestuali. La chiamata di funzioni è ideale per interagire con sistemi esterni. Se il tuo caso d'uso richiede che il modello esegua calcoli, ma non coinvolge sistemi o API esterni, ti consigliamo di utilizzare l'esecuzione di codice.

Per un esempio pratico di chiamata di funzioni, consulta il notebook"light bot".

Come funzionano le chiamate di funzione

Per utilizzare la funzionalità di chiamata di funzione, aggiungi a un prompt del modello i dati delle query strutturate che descrivono le interfacce di programmazione, chiamate dichiarazioni di funzione. Le dichiarazioni di funzione forniscono il nome della funzione dell'API, ne spiegano lo scopo, eventuali parametri supportati e le descrizioni di questi parametri. 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 in uno schema compatibile con OpenAPI che specifica come chiamare una o più delle 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 non chiama effettivamente le funzioni dichiarate. Utilizza invece i parametri dell'oggetto schema restituito per chiamare la funzione. L'API Gemini supporta anche le chiamate di funzioni parallele, in cui il modello consiglia più chiamate di funzioni API in base a 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. 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): 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 elenca i nomi dei parametri obbligatori per il funzionamento della funzione.

Per esempi di codice di una dichiarazione di funzione che utilizza i comandi cURL, consulta gli esempi di chiamata di funzioni. Per esempi di creazione di dichiarazioni di funzioni utilizzando gli SDK dell'API Gemini, consulta il tutorial sulle chiamate di funzione.

Best practice per le dichiarazioni di funzione

La definizione accurata delle funzioni è essenziale per integrarle nelle richieste. Ogni funzione si basa su parametri specifici che ne guidano il comportamento e l'interazione con il modello. La seguente voce fornisce indicazioni su come definire i parametri di una singola funzione in un array functions_declarations.

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

  • description: fornisci descrizioni delle funzioni dettagliate, chiare e specifiche, fornendo esempi, se necessario. Ad esempio, anziché find theaters, utilizza find theaters based on location and optionally movie title that is currently playing in theaters. Evita descrizioni eccessivamente generiche o ambigue.

  • properties > type: utilizza parametri fortemente tipiizzati per ridurre le allucinazioni del modello. Ad esempio, se i valori del parametro provengono da un insieme finito, 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 viene fornito allowed_function_names , il modello sceglie dall'insieme di funzioni consentite.
  • NONE: il modello non prevede una chiamata di funzione. In questo caso, il comportamento del modello è lo stesso che se non passi dichiarazioni di funzioni.

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

Puoi anche passare un insieme di allowed_function_names che, se fornito, limita le funzioni che il modello chiamerà. Devi includere allowed_function_names solo quando la modalità è ANY. I nomi delle funzioni devono corrispondere ai nomi delle dichiarazioni delle funzioni. Con la modalità impostata su ANY e l'insieme allowed_function_names, il modello prevede una chiamata di funzione dall'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à, le informazioni sulla funzione e sui parametri sono 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 di svolta singola

La modalità singola chiamata si verifica quando chiami 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 di una descrizione di una funzione che restituisce informazioni su dove viene proiettato un film. Nella richiesta sono incluse diverse dichiarazioni di funzione, ad esempio find_movies e find_theaters.

Richiesta di esempio di chiamata di funzione con un solo passaggio

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.

Risposta di esempio di chiamata di funzione con una sola svolta di 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 svolta singola con modalità QUALSIASI

L'esempio di curl riportato di seguito è simile all'esempio di svolta singola, ma imposta la modalità su ANY:

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

Chiamata di funzione con un solo turno 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 all'esempio con una svolta, ma imposta la modalità su ANY e include un elenco di funzioni consentite:

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

Chiamata di funzione con un solo turno 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 delle funzioni consentite, quindi prevede una funzione diversa. La risposta potrebbe essere simile alla seguente:

Chiamata di funzione con un solo turno 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 di conversazioni con 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 quella funzione. È 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:

Utilizzare 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 di 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.

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"
            }]
          }
        }
      }
    }]
  },
  {
    "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"]
      }
    }]
  }]
}'

Risposta di esempio di chiamata di funzione con più turni di 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 la 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.