Tutorial panggilan fungsi

Panggilan fungsi mempermudah Anda mendapatkan output data terstruktur dari model generatif. Kemudian, Anda dapat menggunakan output ini untuk memanggil API lain dan menampilkan data respons yang relevan ke model. Dengan kata lain, panggilan fungsi membantu Anda menghubungkan model generatif ke sistem eksternal sehingga konten yang dihasilkan menyertakan informasi terbaru dan akurat.

Jika Anda belum melakukannya, lihat Pengantar panggilan fungsi untuk mempelajarinya lebih lanjut.

Tutorial ini menunjukkan cara menyiapkan Panggilan Fungsi untuk Gemini API guna menafsirkan permintaan pencahayaan pengguna dan memetakan ke setelan API untuk mengontrol nilai kecerahan dan suhu warna lampu.

Menentukan fungsi API

Buat fungsi yang membuat permintaan API. Fungsi ini harus ditentukan dalam kode aplikasi Anda, tetapi dapat memanggil layanan atau API di luar aplikasi Anda. Gemini API tidak memanggil fungsi ini secara langsung, sehingga Anda dapat mengontrol cara dan waktu fungsi ini dijalankan melalui kode aplikasi. Untuk tujuan demonstrasi, tutorial ini menentukan fungsi API tiruan yang hanya menampilkan nilai pencahayaan yang diminta:

async function setLightValues(brightness, colorTemp) {
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

Membuat deklarasi fungsi

Buat deklarasi fungsi yang akan Anda teruskan ke model generatif. Saat mendeklarasikan fungsi untuk digunakan oleh model, Anda harus menyertakan detail sebanyak mungkin dalam deskripsi fungsi dan parameter. Model generatif menggunakan informasi ini untuk menentukan fungsi mana yang akan dipilih dan cara memberikan nilai untuk parameter dalam panggilan fungsi. Kode berikut menunjukkan cara mendeklarasikan fungsi kontrol pencahayaan:

const controlLightFunctionDeclaration = {
  name: "controlLight",
  parameters: {
    type: "OBJECT",
    description: "Set the brightness and color temperature of a room light.",
    properties: {
      brightness: {
        type: "NUMBER",
        description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
      },
      colorTemperature: {
        type: "STRING",
        description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
      },
    },
    required: ["brightness", "colorTemperature"],
  },
};

// Put functions in a "map" keyed by the function name so it is easier to call
const functions = {
  controlLight: ({ brightness, colorTemperature }) => {
    return setLightValues( brightness, colorTemperature)
  }
};

Mendeklarasikan fungsi selama inisialisasi model

Jika ingin menggunakan panggilan fungsi dengan model, Anda harus memberikan deklarasi fungsi saat melakukan inisialisasi objek model. Anda mendeklarasikan fungsi dengan menetapkan parameter tools model:

const { GoogleGenerativeAI } = require("@google/generative-ai");

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

const generativeModel = genAI.getGenerativeModel({
  model: "gemini-2.0-flash",
  // Specify the function declaration.
  tools: {
    functionDeclarations: [controlLightFunctionDeclaration],
  },
});

Membuat panggilan fungsi

Setelah melakukan inisialisasi model dengan deklarasi fungsi, Anda dapat meminta model dengan fungsi yang ditentukan. Anda harus menggunakan panggilan fungsi menggunakan perintah chat (sendMessage()), karena panggilan fungsi umumnya mendapatkan manfaat dari memiliki konteks perintah dan respons sebelumnya.

const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";

const result = await chat.sendMessage(prompt);
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model
  const result2 = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result2.response.text());
}

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 sekumpulan 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.

Anda dapat menentukan mode panggilan fungsi dengan menetapkan parameter toolConfig saat melakukan inisialisasi model generatif.

const generativeModel2 = genAI.getGenerativeModel({
  // Setting a function calling mode is only available in Gemini 1.5 Pro.
  model: "gemini-1.5-pro-latest",
  tools: {
    functionDeclarations: [getExchangeRateFunctionDeclaration],
  },
  toolConfig: {
    functionCallingConfig: {
      // Possible values are: Mode.AUTO, Mode.ANY, Mode.NONE
      mode: FunctionCallingMode.ANY
    }
  }
});