Introduzione alla chiamata di funzione con l'API Gemini

Le funzioni personalizzate possono essere definite e fornite ai modelli Gemini utilizzando la funzione Funzionalità di chiamata. I modelli non richiamano direttamente queste funzioni, ma generare un output di dati strutturati che specifichi il nome della funzione e i dati argomenti. Questo output consente di scrivere applicazioni che utilizzano lo schema e richiamare le API esterne; l'output dell'API risultante può quindi incorporate in un ulteriore prompt del modello, consentendo una query più completa diverse. La chiamata di funzione consente agli utenti di interagire con informazioni e vari servizi, come database, rapporti con i clienti, sistemi di gestione e repository di documenti, migliorando la loro capacità fornire risposte pertinenti e contestuali.

Come funzionano le chiamate di funzione

Puoi utilizzare 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 superato il test un elenco di dichiarazioni di funzione in una query al modello, analizza la funzione e il resto della query per determinare come utilizzare le dichiarazioni API 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 rispondere alla chiamata di funzione consigliata parametri, richiamare l'API effettiva, ottenere una risposta e fornire tale risposta l'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.

Modelli supportati

I seguenti modelli supportano la funzionalità di chiamata di funzione:

  • gemini-1.0-pro
  • gemini-1.0-pro-001
  • gemini-1.5-flash-latest
  • gemini-1.5-pro-latest

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 per la funzione all'interno dell'API chiamata.
  • description (stringa). Una spiegazione completa della funzione della funzione scopo e capacità.
  • 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 e boolean.
      • description (stringa). Una spiegazione chiara del parametro lo scopo e il formato previsto.
    • 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 e informazioni sulla creazione di dichiarazioni di funzione per altre piattaforme, consulta Guida alle piattaforme per la funzione di chiamata 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 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 o punti (.) o trattini (-). Utilizza invece il trattino basso (_) o una custodia a cammello.

  • description: fornisci informazioni dettagliate, chiare e specifiche nella funzione 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 di tipo forte per ridurre allucinazioni dei modelli. 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, invece di the location to search, usa The city and state, e.g. San Francisco, CA or a zip code e.g. 95616.

Per altre best practice relative all'utilizzo delle chiamate di funzione, consulta le Best practice.

Modalità chiamata di funzione

Puoi utilizzare il parametro Chiamata di funzione mode per modificare l'esecuzione comportamento della caratteristica. 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 è fornito, il modello sceglie tra tutti i 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.

Puoi anche trasmettere un insieme di allowed_function_names che, se disponibili, limitano le funzioni che il modello chiamerà. Devi includere solo allowed_function_names 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 richiesta di esempio mostra come imposta mode su ANY e specifica 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 le chiamate di funzione utilizzando i comandi cURL. Gli esempi includono scenari a turno singolo e a turni multipli e l'abilitazione diverse modalità di chiamata di funzione.

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

Esempio a turno singolo

A turno singolo si verifica quando chiami il modello linguistico una volta. Con la chiamata di funzione, un caso d'uso a turno singolo potrebbe essere quando fornisci al modello un linguaggio naturale query e un elenco di funzioni. In questo caso, il modello utilizza la funzione che include il nome della funzione, i parametri e la descrizione, prevedere 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. Diversi dichiarazioni di funzione sono incluse nella richiesta, come 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"
  },
}

Chiamate di funzione a turno singolo 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:

Chiamate di funzione a turno singolo 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 un solo passaggio 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 al 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 funzione in più passaggi:

  1. Ottieni una risposta a una chiamata di funzione chiamando il modello linguistico. Questo è il primo girare.
  2. Chiama il modello linguistico utilizzando la risposta alla chiamata di funzione dal primo turno e la risposta di funzione che si ottiene chiamando quella funzione. Questo è il secondo turno.

La risposta del secondo turno riassume i risultati per rispondere nel primo turno o contiene una seconda chiamata di funzione che puoi utilizzare per ulteriori informazioni per la tua query.

Questo argomento include due esempi di curl in più passaggi:

Usa una risposta di una svolta precedente

Il seguente esempio curl chiama la funzione e gli argomenti restituiti dal precedente esempio a turno singolo per ottenere una risposta. Metodo e parametri restituiti dall'esempio a turno singolo sono in questo JSON.

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

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": "function",
    "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:

Funzione multi-turno che chiama una risposta di esempio 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 un'espressione 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": "function",
    "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 l'accuratezza e l'affidabilità delle chiamate di funzione.

Prompt dell'utente

Per ottenere 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. Per esempio: Ask clarifying questions if not enough information is available to complete the request.

Parametri di campionamento

Per il parametro della temperatura, utilizza 0 o un altro valore basso. Questo indica il modello per generare risultati più sicuri e ridurre le allucinazioni.

Chiamata all'API

Se il modello propone il richiamo di una funzione che invia un ordine, aggiornare un database o avere conseguenze significative, convalidare di funzione chiamata all'utente prima di eseguirla.