Pengantar panggilan fungsi dengan Gemini API

Dengan menggunakan fitur panggilan fungsi Gemini API, Anda dapat memberikan definisi fungsi kustom ke model. Model ini 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 penggunaan pemanggilan fungsi, 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.

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

Panggilan fungsi komposisi

Gemini 2.0 mendukung kemampuan panggilan fungsi baru: panggilan fungsi komposisi. Panggilan fungsi komposisi memungkinkan Gemini API memanggil beberapa fungsi yang ditentukan pengguna secara otomatis dalam proses pembuatan respons. Misalnya, untuk merespons perintah "Get the temperature in my current location", Gemini API dapat memanggil fungsi get_current_location() dan fungsi get_weather() yang menggunakan lokasi sebagai parameter.

Panggilan fungsi komposisi dengan eksekusi kode memerlukan streaming dua arah dan hanya didukung oleh Multimodal Live API baru. Berikut adalah contoh yang menunjukkan cara menggunakan panggilan fungsi komposisi, eksekusi kode, dan Multimodal Live API secara bersamaan:

turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}

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

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

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

Developer Python dapat mencobanya di notebook Penggunaan Alat API Live.

Penggunaan multi-alat

Dengan Gemini 2.0, Anda dapat mengaktifkan beberapa alat secara bersamaan, dan model akan memutuskan kapan harus memanggilnya. Berikut adalah contoh yang mengaktifkan dua alat, Pemrosesan dengan Google Penelusuran dan eksekusi kode, dalam permintaan menggunakan Multimodal Live API.

prompt = """
  Hey, I need you to do three things for me.

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

  Thanks!
  """

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

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

Developer Python dapat mencobanya di notebook Penggunaan Alat API Live.

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.

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.

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

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:

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

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:

{
  "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-putaran:

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

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:

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

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"]
      }
    }]
  }]
}'
    
[{
  "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 detail berikut di awal kueri pengguna:

  • 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 yakin 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.