Pengantar panggilan fungsi dengan Gemini API

Dengan menggunakan fitur panggilan fungsi Gemini API, Anda dapat memberikan definisi fungsi kustom ke model. Model tidak langsung memanggil fungsi ini, tetapi menghasilkan output terstruktur yang menentukan nama fungsi dan argumen yang disarankan. Kemudian, Anda dapat menggunakan nama dan argumen fungsi untuk memanggil API eksternal, dan Anda dapat menggabungkan output API yang dihasilkan ke dalam kueri lebih lanjut ke model, sehingga model dapat memberikan respons yang lebih komprehensif dan mengambil tindakan tambahan.

Panggilan fungsi memungkinkan pengguna berinteraksi dengan informasi dan layanan real-time seperti database, sistem pengelolaan hubungan pelanggan, dan repositori dokumen. Fitur ini juga meningkatkan kemampuan model untuk memberikan jawaban yang relevan dan kontekstual. Panggilan fungsi paling cocok untuk berinteraksi dengan sistem eksternal. Jika kasus penggunaan Anda mengharuskan model untuk melakukan komputasi, tetapi tidak melibatkan sistem atau API eksternal, sebaiknya gunakan eksekusi kode.

Untuk contoh pemanggilan fungsi yang berfungsi, lihat notebook"light bot".

Cara kerja panggilan fungsi

Anda menggunakan fitur panggilan fungsi dengan menambahkan data kueri terstruktur yang menjelaskan antarmuka pemrograman, yang disebut deklarasi fungsi, ke perintah model. Deklarasi fungsi memberikan nama fungsi API, menjelaskan tujuannya, parameter apa pun yang didukungnya, dan deskripsi parameter tersebut. Setelah Anda meneruskan daftar deklarasi fungsi dalam kueri ke model, model akan menganalisis deklarasi fungsi dan kueri lainnya untuk menentukan cara menggunakan API yang dideklarasikan sebagai respons terhadap permintaan.

Model kemudian menampilkan objek dalam skema yang kompatibel dengan OpenAPI yang menentukan cara memanggil satu atau beberapa fungsi yang dideklarasikan untuk merespons pertanyaan pengguna. Kemudian, Anda dapat mengambil parameter panggilan fungsi yang direkomendasikan, memanggil API yang sebenarnya, mendapatkan respons, dan memberikan respons tersebut kepada pengguna atau mengambil tindakan lebih lanjut. Perhatikan bahwa model tidak benar-benar memanggil fungsi yang dideklarasikan. Sebagai gantinya, Anda menggunakan parameter objek skema yang ditampilkan untuk memanggil fungsi. Gemini API juga mendukung panggilan fungsi paralel, dengan model merekomendasikan beberapa panggilan fungsi API berdasarkan satu permintaan.

Deklarasi fungsi

Saat menerapkan panggilan fungsi dalam perintah, Anda membuat objek tools, yang berisi satu atau beberapa function declarations. Anda menentukan fungsi menggunakan JSON, khususnya dengan subset tertentu dari format skema OpenAPI. Satu deklarasi fungsi dapat menyertakan parameter berikut:

  • name (string): ID unik untuk fungsi dalam panggilan API.
  • description (string): Penjelasan lengkap tentang tujuan dan kemampuan fungsi.
  • parameters (objek): Menentukan data input yang diperlukan oleh fungsi.
    • type (string): Menentukan jenis data secara keseluruhan, seperti object.
    • properties (objek): Mencantumkan setiap parameter, masing-masing dengan:
      • type (string): Jenis data parameter, seperti string, integer, boolean.
      • description (string): Penjelasan yang jelas tentang tujuan parameter dan format yang diharapkan.
    • required (array): Array string yang mencantumkan nama parameter yang wajib agar fungsi dapat beroperasi.

Untuk contoh kode deklarasi fungsi menggunakan perintah cURL, lihat Contoh pemanggilan fungsi. Untuk mengetahui contoh pembuatan deklarasi fungsi menggunakan SDK Gemini API, lihat Tutorial panggilan fungsi.

Praktik terbaik untuk deklarasi fungsi

Menentukan fungsi secara akurat sangat penting saat mengintegrasikannya ke dalam permintaan Anda. Setiap fungsi bergantung pada parameter tertentu yang memandu perilaku dan interaksinya dengan model. Listingan berikut memberikan panduan tentang menentukan parameter setiap fungsi dalam array functions_declarations.

  • name: Gunakan nama yang jelas dan deskriptif tanpa spasi, titik (.), atau tanda hubung (-). Sebagai gantinya, gunakan karakter garis bawah (_) atau camel case.

  • description: Memberikan deskripsi fungsi yang mendetail, jelas, dan spesifik, dengan memberikan contoh jika diperlukan. Misalnya, gunakan find theaters based on location and optionally movie title that is currently playing in theaters. Hindari deskripsi yang terlalu luas atau ambigu, bukan find theaters.

  • properties > type: Gunakan parameter dengan jenis yang kuat untuk mengurangi halusinasi model. Misalnya, jika nilai parameter berasal dari kumpulan terbatas, gunakan kolom enum, bukan mencantumkan nilai dalam deskripsi (misalnya, "type": "enum", "values": ["now_playing", "upcoming"]). Jika nilai parameter selalu berupa bilangan bulat, tetapkan jenisnya ke integer, bukan number.

  • properties > description: Memberikan contoh dan batasan yang konkret. Misalnya, gunakan The city and state, e.g. San Francisco, CA or a zip code e.g. 95616, bukan the location to search.

Untuk praktik terbaik lainnya saat menggunakan panggilan fungsi, lihat bagian Praktik Terbaik.

Mode panggilan fungsi

Anda dapat menggunakan fungsi yang memanggil parameter mode untuk mengubah perilaku eksekusi fitur. Ada tiga mode yang tersedia:

  • AUTO: Perilaku model default. Model memutuskan untuk memprediksi panggilan fungsi atau respons bahasa alami.
  • ANY: Model dibatasi untuk selalu memprediksi panggilan fungsi. Jika allowed_function_names tidak diberikan, model akan memilih dari semua deklarasi fungsi yang tersedia. Jika allowed_function_names disediakan, model akan memilih dari kumpulan fungsi yang diizinkan.
  • NONE: Model tidak akan memprediksi panggilan fungsi. Dalam hal ini, perilaku model sama seperti jika Anda tidak meneruskan deklarasi fungsi apa pun.

Penggunaan mode ANY ("panggilan fungsi paksa") hanya didukung untuk model Gemini 1.5 Pro dan Gemini 1.5 Flash.

Anda juga dapat meneruskan kumpulan allowed_function_names yang, jika disediakan, akan membatasi fungsi yang akan dipanggil model. Anda hanya boleh menyertakan allowed_function_names jika modenya adalah ANY. Nama fungsi harus cocok dengan nama deklarasi fungsi. Dengan mode yang ditetapkan ke ANY dan allowed_function_names ditetapkan, model akan memprediksi panggilan fungsi dari kumpulan nama fungsi yang disediakan.

Cuplikan kode berikut dari contoh permintaan menunjukkan cara menetapkan mode ke ANY dan menentukan daftar fungsi yang diizinkan:

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

Contoh panggilan fungsi

Bagian ini memberikan contoh perintah untuk panggilan fungsi menggunakan perintah cURL. Contohnya mencakup skenario satu belokan dan beberapa belokan, serta mengaktifkan mode panggilan fungsi yang berbeda.

Saat menggunakan perintah cURL dengan fitur ini, informasi fungsi dan parameter disertakan dalam elemen tools. Setiap deklarasi fungsi dalam elemen tools berisi nama fungsi, dan Anda menentukan parameter menggunakan skema yang kompatibel dengan OpenAPI, dan deskripsi fungsi.

Contoh satu giliran

Satu giliran adalah saat Anda memanggil model bahasa satu kali. Dengan panggilan fungsi, kasus penggunaan satu giliran mungkin terjadi saat Anda memberikan kueri bahasa alami dan daftar fungsi ke model. Dalam hal ini, model menggunakan deklarasi fungsi, yang mencakup nama fungsi, parameter, dan deskripsi, untuk memprediksi fungsi mana yang akan dipanggil dan argumen yang akan digunakan untuk memanggilnya.

Contoh curl berikut adalah contoh penerusan deskripsi fungsi yang menampilkan informasi tentang tempat film diputar. Beberapa deklarasi fungsi disertakan dalam permintaan, seperti find_movies dan find_theaters.

Permintaan contoh panggilan fungsi satu giliran

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

Respons untuk contoh curl ini mungkin mirip dengan berikut ini.

Contoh respons curl panggilan fungsi satu putaran

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

Contoh satu belokan menggunakan mode APA SAJA

Contoh curl berikut mirip dengan contoh satu belokan, tetapi menetapkan mode ke ANY:

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

Panggilan fungsi satu belokan menggunakan mode APA SAJA (permintaan)

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

Responsnya mungkin mirip dengan berikut ini:

Panggilan fungsi satu belokan menggunakan mode APA SAJA (respons)

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

Contoh satu belokan menggunakan mode APA SAJA dan fungsi yang diizinkan

Contoh curl berikut mirip dengan contoh satu belokan, tetapi menetapkan mode ke ANY dan menyertakan daftar fungsi yang diizinkan:

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

Panggilan fungsi satu belokan menggunakan mode APA SAJA dan fungsi yang diizinkan (permintaan)

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

Model tidak dapat memprediksi fungsi find_movies, karena tidak ada dalam daftar fungsi yang diizinkan, sehingga model memprediksi fungsi yang berbeda. Responsnya mungkin mirip dengan berikut ini:

Panggilan fungsi satu belokan menggunakan mode APA SAJA dan fungsi yang diizinkan (respons)

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

Contoh multi-giliran

Anda dapat menerapkan skenario panggilan fungsi multi-giliran dengan melakukan hal berikut:

  1. Dapatkan respons panggilan fungsi dengan memanggil model bahasa. Ini adalah belokan pertama.
  2. Panggil model bahasa menggunakan respons panggilan fungsi dari giliran pertama dan respons fungsi yang Anda dapatkan dari memanggil fungsi tersebut. Ini adalah giliran kedua.

Respons dari giliran kedua merangkum hasil untuk menjawab kueri Anda di giliran pertama, atau berisi panggilan fungsi kedua yang dapat Anda gunakan untuk mendapatkan informasi selengkapnya untuk kueri Anda.

Topik ini mencakup dua contoh curl multi-giliran:

Menggunakan respons dari belokan sebelumnya

Contoh curl berikut memanggil fungsi dan argumen yang ditampilkan oleh contoh satu giliran sebelumnya untuk mendapatkan respons. Metode dan parameter yang ditampilkan oleh contoh satu giliran ada dalam JSON ini.

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

Contoh permintaan curl untuk fungsi multi-giliran yang memanggil

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

Respons untuk contoh curl ini mencakup hasil pemanggilan metode find_theaters. Responsnya mungkin mirip dengan berikut ini:

Contoh respons curl panggilan fungsi multi-giliran

{
  "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
  }
}

Memanggil model beberapa kali

Contoh cURL berikut memanggil model AI generatif beberapa kali untuk memanggil fungsi. Setiap kali model memanggil fungsi, model dapat menggunakan fungsi yang berbeda untuk menjawab kueri pengguna yang berbeda dalam permintaan.

Contoh permintaan curl untuk fungsi multi-giliran yang memanggil

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

Contoh respons curl panggilan fungsi multi-giliran

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

Praktik terbaik

Ikuti praktik terbaik berikut untuk meningkatkan akurasi dan keandalan panggilan fungsi Anda.

Perintah pengguna

Untuk hasil terbaik, tambahkan kueri pengguna dengan detail berikut:

  • Konteks tambahan untuk model. Contoh, You are a movie API assistant to help users find movies and showtimes based on their preferences.
  • Detail atau petunjuk tentang cara dan waktu menggunakan fungsi. Misalnya, Don't make assumptions on showtimes. Always use a future date for showtimes.
  • Petunjuk untuk mengajukan pertanyaan klarifikasi jika kueri pengguna ambigu. Misalnya, Ask clarifying questions if not enough information is available to complete the request.

Parameter sampling

Untuk parameter suhu, gunakan 0 atau nilai rendah lainnya. Hal ini akan memerintahkan model untuk menghasilkan hasil yang lebih meyakinkan dan mengurangi halusinasi.

Pemanggilan API

Jika model mengusulkan pemanggilan fungsi yang akan mengirim pesanan, memperbarui database, atau memiliki konsekuensi yang signifikan, validasikan panggilan fungsi dengan pengguna sebelum mengeksekusinya.