Model generatif sangat andal dalam memecahkan berbagai jenis masalah. Namun, konfigurasinya dibatasi oleh batasan seperti:
- LLM dibekukan setelah pelatihan, sehingga pengetahuan yang ada dalamnya tidak diperbarui.
- LLM tidak dapat membuat kueri atau mengubah data eksternal.
Panggilan fungsi dapat membantu Anda mengatasi beberapa batasan ini. Pemanggilan fungsi terkadang disebut sebagai penggunaan alat karena memungkinkan model menggunakan alat eksternal seperti API dan fungsi untuk menghasilkan respons akhirnya.
Panduan ini menunjukkan cara menerapkan penyiapan panggilan fungsi yang mirip dengan skenario yang dijelaskan di bagian utama berikutnya pada halaman ini. Secara umum, berikut langkah-langkah untuk menyiapkan panggilan fungsi di aplikasi Anda:
Langkah 1: Tulis fungsi yang dapat memberikan informasi yang dibutuhkan model untuk membuat respons akhirnya (misalnya, fungsi dapat memanggil API eksternal).
Langkah 2: Buat deklarasi fungsi yang menjelaskan fungsi dan parameternya.
Langkah 3: Berikan deklarasi fungsi selama inisialisasi model sehingga model mengetahui cara menggunakan fungsi tersebut, jika diperlukan.
Langkah 4: Siapkan aplikasi Anda agar model dapat mengirimkan informasi yang diperlukan agar aplikasi Anda dapat memanggil fungsi.
Langkah 5: Teruskan respons fungsi kembali ke model agar model dapat membuat respons akhirnya.
Ringkasan contoh panggilan fungsi
Saat mengirim permintaan ke model, Anda juga dapat memberikan serangkaian "alat" (seperti fungsi) yang dapat digunakan model untuk membuat respons akhir. Untuk menggunakan fungsi ini dan memanggilnya ("panggilan fungsi"), model dan aplikasi Anda perlu mengirimkan informasi bolak-balik satu sama lain, sehingga cara yang direkomendasikan untuk menggunakan panggilan fungsi adalah melalui antarmuka chat multi-turn.
Bayangkan Anda memiliki aplikasi tempat pengguna dapat memasukkan perintah seperti:
What was the weather in Boston on October 17, 2024?.
Model Gemini mungkin tidak mengetahui informasi cuaca ini; namun, bayangkan Anda mengetahui API layanan cuaca eksternal yang dapat menyediakannya. Anda dapat menggunakan panggilan fungsi untuk memberi model Gemini jalur ke API tersebut dan informasi cuacanya.
Pertama, Anda menulis fungsi fetchWeather di aplikasi yang berinteraksi dengan API eksternal hipotetis ini, yang memiliki input dan output berikut:
| Parameter | Jenis | Wajib | Deskripsi |
|---|---|---|---|
| Input | |||
location |
Objek | Ya | Nama kota dan negara bagiannya untuk mendapatkan cuaca. Hanya kota di Amerika Serikat yang didukung. Harus selalu berupa objek bertingkat dari city dan state.
|
date |
String | Ya | Tanggal untuk mengambil data cuaca (harus selalu dalam
format YYYY-MM-DD).
|
| Output | |||
temperature |
Bilangan bulat | Ya | Suhu (dalam Fahrenheit) |
chancePrecipitation |
String | Ya | Kemungkinan presipitasi (dinyatakan sebagai persentase) |
cloudConditions |
String | Ya | Kondisi awan (salah satu dari clear, partlyCloudy,
mostlyCloudy, cloudy)
|
Saat melakukan inisialisasi model, Anda memberi tahu model bahwa fungsi fetchWeather
ini ada dan cara menggunakannya untuk memproses permintaan yang masuk, jika diperlukan.
Hal ini disebut "deklarasi fungsi". Model tidak memanggil fungsi
secara langsung. Sebagai gantinya, saat model memproses permintaan masuk, model akan
memutuskan apakah fungsi fetchWeather dapat membantunya merespons permintaan. Jika
model memutuskan bahwa fungsi tersebut memang dapat berguna, model akan membuat
data terstruktur yang akan membantu aplikasi Anda memanggil fungsi tersebut.
Lihat lagi permintaan yang masuk:
What was the weather in Boston on October 17, 2024?. Model kemungkinan akan
memutuskan bahwa fungsi fetchWeather dapat membantunya membuat respons. Model akan melihat parameter input yang diperlukan untuk fetchWeather, lalu membuat data input terstruktur untuk fungsi yang terlihat seperti ini:
{
functionName: fetchWeather,
location: {
city: Boston,
state: Massachusetts // the model can infer the state from the prompt
},
date: 2024-10-17
}
Model meneruskan data input terstruktur ini ke aplikasi Anda sehingga aplikasi Anda dapat
memanggil fungsi fetchWeather. Saat aplikasi Anda menerima kembali kondisi cuaca dari API, aplikasi tersebut akan meneruskan informasi ke model. Informasi cuaca ini memungkinkan model menyelesaikan pemrosesan akhirnya dan menghasilkan respons terhadap permintaan awal What was the weather in Boston on October 17, 2024?.
Model dapat memberikan respons akhir dalam bahasa alami seperti:
On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.
Menerapkan panggilan fungsi
Langkah-langkah berikut dalam panduan ini menunjukkan cara menerapkan penyiapan panggilan fungsi yang mirip dengan alur kerja yang dijelaskan dalam Ringkasan contoh panggilan fungsi (lihat bagian atas halaman ini).
Model yang didukung
gemini-3.1-pro-previewgemini-3.7-flash(dangemini-3.6-flashsertagemini-3.5-flashyang lebih lama)gemini-3.5-flash-lite(dangemini-3.1-flash-liteyang lebih lama)
Model Gemini 2.5 penggunaan umum mendukung kemampuan ini, tetapi semuanya sudah tidak digunakan lagi.
Model Gemini Live API juga mendukung kemampuan ini, tetapi semua contoh kode dalam panduan ini ditujukan untuk model Gemini penggunaan umum.
Sebelum memulai
|
Klik penyedia Gemini API untuk melihat konten dan kode khusus penyedia di halaman ini. |
Jika belum melakukannya, selesaikan
panduan memulai, yang menjelaskan cara
menyiapkan project Firebase, menghubungkan aplikasi ke Firebase, menambahkan SDK,
menginisialisasi layanan backend untuk penyedia Gemini API yang Anda pilih, dan
membuat instance GenerativeModel.
Untuk menguji dan melakukan iterasi pada perintah Anda, sebaiknya gunakan Google AI Studio.
Langkah 1: Tulis fungsi
Bayangkan Anda memiliki aplikasi tempat pengguna dapat memasukkan perintah seperti:
What was the weather in Boston on October 17, 2024?. Model Gemini
mungkin tidak mengetahui informasi cuaca ini; namun, bayangkan Anda mengetahui
API layanan cuaca eksternal yang dapat menyediakannya. Skenario dalam panduan ini
mengandalkan API eksternal hipotetis ini.
Tulis fungsi di aplikasi Anda yang akan berinteraksi dengan API eksternal hipotetis dan berikan informasi yang dibutuhkan model untuk membuat permintaan akhirnya. Dalam contoh cuaca ini, akan ada fungsi fetchWeather yang
melakukan panggilan ke API eksternal hipotetis ini.
Swift
// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
func fetchWeather(city: String, state: String, date: String) -> JSONObject {
// TODO(developer): Write a standard function that would call an external weather API.
// For demo purposes, this hypothetical response is hardcoded here in the expected format.
return [
"temperature": .number(38),
"chancePrecipitation": .string("56%"),
"cloudConditions": .string("partlyCloudy"),
]
}
Kotlin
// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
// `location` is an object of the form { city: string, state: string }
data class Location(val city: String, val state: String)
suspend fun fetchWeather(location: Location, date: String): JsonObject {
// TODO(developer): Write a standard function that would call to an external weather API.
// For demo purposes, this hypothetical response is hardcoded here in the expected format.
return JsonObject(mapOf(
"temperature" to JsonPrimitive(38),
"chancePrecipitation" to JsonPrimitive("56%"),
"cloudConditions" to JsonPrimitive("partlyCloudy")
))
}
Java
// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
// `location` is an object of the form { city: string, state: string }
public JsonObject fetchWeather(Location location, String date) {
// TODO(developer): Write a standard function that would call to an external weather API.
// For demo purposes, this hypothetical response is hardcoded here in the expected format.
return new JsonObject(Map.of(
"temperature", JsonPrimitive(38),
"chancePrecipitation", JsonPrimitive("56%"),
"cloudConditions", JsonPrimitive("partlyCloudy")));
}
Web
// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
// `location` is an object of the form { city: string, state: string }
async function fetchWeather({ location, date }) {
// TODO(developer): Write a standard function that would call to an external weather API.
// For demo purposes, this hypothetical response is hardcoded here in the expected format.
return {
temperature: 38,
chancePrecipitation: "56%",
cloudConditions: "partlyCloudy",
};
}
Dart
// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
// `location` is an object of the form { city: string, state: string }
Future<Map<String, Object?>> fetchWeather(
Location location, String date
) async {
// TODO(developer): Write a standard function that would call to an external weather API.
// For demo purposes, this hypothetical response is hardcoded here in the expected format.
final apiResponse = {
'temperature': 38,
'chancePrecipitation': '56%',
'cloudConditions': 'partlyCloudy',
};
return apiResponse;
}
Unity
// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
System.Collections.Generic.Dictionary<string, object> FetchWeather(
string city, string state, string date) {
// TODO(developer): Write a standard function that would call an external weather API.
// For demo purposes, this hypothetical response is hardcoded here in the expected format.
return new System.Collections.Generic.Dictionary<string, object>() {
{"temperature", 38},
{"chancePrecipitation", "56%"},
{"cloudConditions", "partlyCloudy"},
};
}
Langkah 2: Buat deklarasi fungsi
Buat deklarasi fungsi yang akan Anda berikan kepada model nanti (langkah berikutnya dalam panduan ini).
Dalam deklarasi Anda, sertakan detail sebanyak mungkin dalam deskripsi untuk fungsi dan parameternya.
Model menggunakan informasi dalam deklarasi fungsi untuk menentukan fungsi mana yang akan dipilih dan cara memberikan nilai parameter untuk panggilan aktual ke fungsi. Lihat Perilaku dan opsi tambahan di halaman ini untuk mengetahui cara model dapat memilih di antara fungsi-fungsi tersebut, serta cara Anda dapat mengontrol pilihan tersebut.
Perhatikan hal-hal berikut tentang skema yang Anda berikan:
Aware API mengharuskan Anda memberikan deklarasi fungsi dalam format skema yang kompatibel dengan skema OpenAPI. Agent Platform menawarkan dukungan terbatas untuk skema OpenAPI.
Atribut berikut didukung:
type,nullable,required,format,description,properties,items,enum.Atribut berikut tidak didukung:
default,optional,maximum,oneOf.
Secara default, untuk SDK Firebase AI Logic, semua kolom dianggap wajib diisi kecuali jika Anda menentukannya sebagai opsional dalam array
optionalProperties. Untuk kolom opsional ini, model dapat mengisi kolom atau melewatinya. Perhatikan bahwa hal ini berlawanan dengan perilaku default kedua penyedia Gemini API jika Anda menggunakan SDK server atau API mereka secara langsung.
Untuk praktik terbaik terkait deklarasi fungsi, termasuk tips untuk nama dan deskripsi, lihat Praktik terbaik dalam dokumentasi Gemini Developer API.
Berikut cara menulis deklarasi fungsi:
Swift
let fetchWeatherTool = FunctionDeclaration(
name: "fetchWeather",
description: "Get the weather conditions for a specific city on a specific date.",
parameters: [
"location": .object(
properties: [
"city": .string(description: "The city of the location."),
"state": .string(description: "The US state of the location."),
],
description: """
The name of the city and its state for which to get the weather. Only cities in the
USA are supported.
"""
),
"date": .string(
description: """
The date for which to get the weather. Date must be in the format: YYYY-MM-DD.
"""
),
]
)
Kotlin
val fetchWeatherTool = FunctionDeclaration(
"fetchWeather",
"Get the weather conditions for a specific city on a specific date.",
mapOf(
"location" to Schema.obj(
mapOf(
"city" to Schema.string("The city of the location."),
"state" to Schema.string("The US state of the location."),
),
description = "The name of the city and its state for which " +
"to get the weather. Only cities in the " +
"USA are supported."
),
"date" to Schema.string("The date for which to get the weather." +
" Date must be in the format: YYYY-MM-DD."
),
),
)
Java
FunctionDeclaration fetchWeatherTool = new FunctionDeclaration(
"fetchWeather",
"Get the weather conditions for a specific city on a specific date.",
Map.of("location",
Schema.obj(Map.of(
"city", Schema.str("The city of the location."),
"state", Schema.str("The US state of the location."))),
"date",
Schema.str("The date for which to get the weather. " +
"Date must be in the format: YYYY-MM-DD.")),
Collections.emptyList());
Web
const fetchWeatherTool: FunctionDeclarationsTool = {
functionDeclarations: [
{
name: "fetchWeather",
description:
"Get the weather conditions for a specific city on a specific date",
parameters: Schema.object({
properties: {
location: Schema.object({
description:
"The name of the city and its state for which to get " +
"the weather. Only cities in the USA are supported.",
properties: {
city: Schema.string({
description: "The city of the location."
}),
state: Schema.string({
description: "The US state of the location."
}),
},
}),
date: Schema.string({
description:
"The date for which to get the weather. Date must be in the" +
" format: YYYY-MM-DD.",
}),
},
}),
},
],
};
Dart
final fetchWeatherTool = FunctionDeclaration(
'fetchWeather',
'Get the weather conditions for a specific city on a specific date.',
parameters: {
'location': Schema.object(
description:
'The name of the city and its state for which to get'
'the weather. Only cities in the USA are supported.',
properties: {
'city': Schema.string(
description: 'The city of the location.'
),
'state': Schema.string(
description: 'The US state of the location.'
),
},
),
'date': Schema.string(
description:
'The date for which to get the weather. Date must be in the format: YYYY-MM-DD.'
),
},
);
Unity
var fetchWeatherTool = new Tool(new FunctionDeclaration(
name: "fetchWeather",
description: "Get the weather conditions for a specific city on a specific date.",
parameters: new