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.

Anda dapat memberikan deskripsi fungsi ke model Gemini. Ini adalah fungsi yang Anda tulis dalam bahasa aplikasi (yaitu, bukan Google Cloud Functions). Model mungkin meminta Anda untuk memanggil fungsi dan mengirim kembali hasilnya untuk membantu model menangani kueri Anda.

Jika belum, lihat Pengantar panggilan fungsi untuk mempelajari lebih lanjut.

Contoh API untuk kontrol pencahayaan

Bayangkan Anda memiliki sistem kontrol pencahayaan dasar dengan antarmuka pemrograman aplikasi (API) dan ingin mengizinkan pengguna mengontrol lampu melalui permintaan teks sederhana. Anda dapat menggunakan fitur Panggilan Fungsi untuk menafsirkan permintaan perubahan pencahayaan dari pengguna dan menerjemahkannya menjadi panggilan API untuk menetapkan nilai pencahayaan. Sistem kontrol pencahayaan hipotetis ini memungkinkan Anda mengontrol kecerahan lampu dan suhu warnanya, yang ditentukan sebagai dua parameter terpisah:

Parameter	Jenis	Wajib diisi	Deskripsi
`brightness`	angka	ya	Tingkat cahaya dari 0 hingga 100. Nol adalah nonaktif dan 100 adalah kecerahan penuh.
`colorTemperature`	string	ya	Suhu warna perlengkapan lampu yang dapat berupa `daylight`, `cool`, atau `warm`.

Untuk memudahkan, sistem pencahayaan imajiner ini hanya memiliki satu lampu, sehingga pengguna tidak perlu menentukan ruangan atau lokasi. Berikut adalah contoh permintaan JSON yang dapat Anda kirim ke API kontrol pencahayaan untuk mengubah tingkat cahaya menjadi 50% menggunakan suhu warna cahaya siang:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

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.

Sebelum memulai: Menyiapkan project dan kunci API

Sebelum memanggil Gemini API, Anda perlu menyiapkan project dan mengonfigurasi kunci API.

Luaskan untuk melihat cara menyiapkan project dan kunci API

Mendapatkan dan mengamankan kunci API

Anda memerlukan kunci API untuk memanggil Gemini API. Jika Anda belum memilikinya, buat kunci di Google AI Studio.

Mendapatkan kunci API

Sebaiknya jangan melakukan check in kunci API ke dalam sistem kontrol versi Anda.

Anda harus menyimpan kunci API di penyimpanan secret seperti Secret Manager Google Cloud.

Tutorial ini mengasumsikan bahwa Anda mengakses kunci API sebagai variabel lingkungan.

Mengimpor paket SDK dan mengonfigurasi kunci API Anda

Dalam aplikasi Anda, lakukan hal berikut:

Di direktori modul Anda, get paket Go SDK:

go get github.com/google/generative-ai-go

Impor paket dan konfigurasikan layanan dengan kunci API Anda:

import (
  // import standard libraries
  // Import the GenerativeAI package for Go
  "github.com/google/generative-ai-go/genai"
  "google.golang.org/api/option"
)

ctx := context.Background()
// Access your API key as an environment variable
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// ...

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 dieksekusi melalui kode aplikasi. Untuk tujuan demonstrasi, tutorial ini menentukan fungsi API tiruan yang hanya menampilkan nilai pencahayaan yang diminta:

func setLightValues(brightness int, colorTemp string) map[string]any {
    // This mock API returns the requested lighting values
    return map[string]any{
        "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:

lightControlTool := &genai.Tool{
    FunctionDeclarations: []*genai.FunctionDeclaration{{
        Name:        "controlLight",
        Description: "Set the brightness and color temperature of a room light.",
        Parameters: &genai.Schema{
            Type: genai.TypeObject,
            Properties: map[string]*genai.Schema{
                "brightness": {
                    Type:        genai.TypeString,
                    Description: "Light level from 0 to 100. Zero is off and"+
                        " 100 is full brightness.",
                },
                "colorTemperature": {
                    Type:        genai.TypeString,
                    Description: "Color temperature of the light fixture which" +
                        " can be `daylight`, `cool` or `warm`.",
                },
            },
            Required: []string{"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:

// ...

lightControlTool := &genai.Tool{
    // ...
}

// Use a model that supports function calling, like a Gemini 1.5 model
model := client.GenerativeModel("gemini-1.5-flash")

// Specify the function declaration.
model.Tools = []*genai.Tool{lightControlTool}

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.

// Start new chat session.
session := model.StartChat()

prompt := "Dim the lights so the room feels cozy and warm."

// Send the message to the generative model.
resp, err := session.SendMessage(ctx, genai.Text(prompt))
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Check that you got the expected function call back.
part := resp.Candidates[0].Content.Parts[0]
funcall, ok := part.(genai.FunctionCall)
if !ok {
    log.Fatalf("Expected type FunctionCall, got %T", part)
}
if g, e := funcall.Name, lightControlTool.FunctionDeclarations[0].Name; g != e {
    log.Fatalf("Expected FunctionCall.Name %q, got %q", e, g)
}
fmt.Printf("Received function call response:\n%q\n\n", part)

apiResult := map[string]any{
    "brightness":  "30",
    "colorTemperature":  "warm" }

// Send the hypothetical API result back to the generative model.
fmt.Printf("Sending API result:\n%q\n\n", apiResult)
resp, err = session.SendMessage(ctx, genai.FunctionResponse{
    Name:     lightControlTool.FunctionDeclarations[0].Name,
    Response: apiResult,
})
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Show the model's response, which is expected to be text.
for _, part := range resp.Candidates[0].Content.Parts {
    fmt.Printf("%v\n", part)
}