Cara Berinteraksi dengan API Menggunakan Panggilan Fungsi di Gemini

1. Ringkasan

Apa yang dimaksud dengan panggilan fungsi di Gemini?

Vertex AI Gemini API adalah rangkaian model AI generatif yang dikembangkan oleh Google DeepMind dan dirancang untuk kasus penggunaan multimodal. Panggilan fungsi adalah fitur model Gemini yang memudahkan developer mendapatkan output data terstruktur dari model generatif.

Developer kemudian 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.

Cara kerja panggilan fungsi

Fungsi dijelaskan menggunakan deklarasi fungsi, yang membantu model generatif memahami tujuan dan parameter dalam suatu fungsi. Setelah Anda meneruskan deklarasi fungsi dalam kueri ke model generatif, model akan menampilkan objek terstruktur yang menyertakan nama fungsi yang relevan dan argumennya berdasarkan kueri pengguna. Perhatikan bahwa dengan panggilan fungsi, model tidak benar-benar memanggil fungsi. Sebagai gantinya, Anda dapat menggunakan fungsi dan parameter yang ditampilkan untuk memanggil fungsi dalam bahasa, library, atau framework apa pun yang Anda inginkan.

Yang akan Anda build

Dalam codelab ini, Anda akan membangun pipeline AI generatif dengan Vertex AI Gemini API dan Python. Dengan menggunakan aplikasi Anda, pengguna dapat bertanya tentang nilai tukar, dan sistem akan mengambil data terbaru dari API eksternal serta memberikan jawaban kepada pengguna.

Yang akan Anda pelajari

• Cara berinteraksi dengan model Gemini menggunakan library klien Python
• Cara menentukan deklarasi fungsi dan mendaftarkannya sebagai alat
• Cara memanggil Gemini dan mendapatkan respons panggilan fungsi
• Cara menampilkan respons fungsi ke Gemini dan merespons pengguna

Yang Anda butuhkan

• Project Google Cloud
• Browser seperti Chrome
• Lingkungan pengembangan Python seperti Colab atau Colab Enterprise

2. Penyiapan dan persyaratan

Sebelum dapat mulai menggunakan panggilan fungsi di Gemini, Anda harus mengaktifkan Vertex AI API dan menginstal library klien Vertex AI Python versi terbaru.

Mengaktifkan Vertex AI API

Untuk mengaktifkan Vertex AI API, ikuti langkah-langkah berikut:

1. Di browser Anda, buka halaman Detail Layanan Vertex AI API.
2. Klik tombol Enable untuk mengaktifkan Vertex AI API di project Google Cloud Anda.

Menginstal library klien Python untuk Vertex AI

Untuk menginstal library klien Python untuk Vertex AI, ikuti langkah-langkah berikut:

1. Buka terminal di lingkungan pengembangan Anda.
2. Pastikan Anda memiliki lingkungan pengembangan Python yang valid, dan lihat pedoman ini jika diperlukan.
3. Jalankan perintah berikut guna menginstal library klien Python untuk Vertex AI:

   pip install --upgrade google-cloud-aiplatform
   

4. Jika Anda menjalankannya di lingkungan notebook, Anda mungkin perlu memulai ulang runtime/kernel untuk menggunakan paket yang baru diinstal.

Kini Anda siap menggunakan Vertex AI API.

3. Memahami masalahnya

Pernahkah Anda berinteraksi dengan model bahasa besar atau model AI generatif dan bertanya tentang informasi real-time atau terkini, hanya untuk mendapatkan respons dengan informasi yang sudah tidak berlaku atau informasi yang tidak akurat?

Mari kita coba sekarang! Pertama, kita akan mengimpor paket Python yang relevan dan melakukan inisialisasi model Gemini. Anda dapat menjalankan kode berikut di lingkungan pengembangan Python seperti Colab atau Colab Enterprise dan dengan menginstal versi terbaru Vertex AI SDK untuk Python:

import vertexai
from vertexai.generative_models import GenerativeModel
model = GenerativeModel("gemini-1.5-pro-001")

Sekarang, mari kita ajukan pertanyaan tentang kurs untuk berbagai mata uang hari ini:

response = model.generate_content(
    "What's the exchange rate for euros to dollars today?"
)
print(response.text)

Model ini akan menghasilkan respons terbatas atau usang untuk Anda, seperti:

As an AI language model, I don't have access to real-time currency exchange
rates. However, as of my last update in September 2021, the approximate exchange
rate between euros (EUR) and US dollars (USD) was:

1 EUR ≈ 1.18 USD

Please note that currency exchange rates constantly fluctuate and can vary
depending on various factors such as economic conditions, supply and demand,
political events, and more. To obtain the most up-to-date and accurate exchange
rate, I recommend using a reliable currency converter or financial website that
provides live rates.

[...]

Jika pengguna akhir menerima jenis respons ini, mereka perlu mengalihkan konteks untuk mencari mata uang yang mereka minati, mengambil nilai tukar terbaru, dan melakukan konversi sendiri.

Idealnya, pipeline model generatif dapat menangani sebagian atau semua tugas ini untuk pengguna. Di bagian berikutnya, Anda akan mencoba beberapa solusi umum untuk mendapatkan respons terstruktur dari model generatif sehingga Anda dapat memanggil sistem eksternal.

4. Coba solusi umum

Saat bekerja dengan model generatif dalam skenario di mana Anda memerlukan informasi atau data terbaru dari sumber eksternal, Anda dapat memanggil API eksternal, lalu mengirimkan hasilnya kembali ke model generatif untuk digunakan dalam responsnya.

Sebelum memanggil sistem eksternal, Anda perlu menentukan fungsi yang tepat untuk digunakan, mengekstrak parameter yang relevan dari pengguna, dan menempatkan parameter ke dalam objek data terstruktur. Hal ini biasanya melibatkan prompt engineering menyeluruh untuk memaksa model generatif menghasilkan data terstruktur yang valid.

Mari tinjau kembali pertanyaan yang kita ajukan di bagian sebelumnya dan berikan beberapa petunjuk tambahan untuk model ini. Coba kirimkan permintaan berikut ke model Gemini:

user_prompt = "What's the exchange rate from euros to US dollars today?"

response = model.generate_content("""
Your task is to extract parameters from the user's input and return it as a
structured JSON payload. The user will ask about the exchange rate and which
currency they are converting from and converting to.

User input: {user_prompt}

Please extract the currencies as parameters and put them in a JSON object.
""".format(user_prompt=user_prompt))
print(response.text)

Hasil ini adalah respons teks berikut, yang bukan JSON yang valid dan akan sulit untuk digunakan:

```json
{
  "currency_from": "euros",
  "currency_to": "US dollars"
}
```

Secara khusus, baris pertama dan terakhir dari respons teks mencakup tanda kutip terbalik untuk membatasi blok kode, baris pertama menyertakan penentu bahasa, dan nilai dalam objek JSON bukanlah singkatan mata uang tiga huruf standar yang diharapkan oleh API pertukaran mata uang sebagai parameter input.

Kita dapat mencoba menggunakan Python untuk pascapemrosesan teks ini menjadi JSON dan kamus yang valid, menambahkan lebih banyak instruksi ke perintah, memberikan satu atau beberapa contoh output yang diinginkan, meningkatkan kualitas model, atau melakukan panggilan lain ke model generatif yang memintanya untuk membersihkan JSON.

Namun ada cara yang lebih determenistik! Mari kita pelajari cara menggunakan panggilan fungsi di Gemini untuk membuat kueri informasi di layanan eksternal dan menampilkan respons yang relevan kepada pengguna akhir.

5. Cara kerja panggilan fungsi

Sebelum memulai ekstraksi parameter dan panggilan fungsi, mari pelajari langkah-langkah panggilan fungsi dan komponen mana yang digunakan saat runtime.

Input pengguna ke Gemini API

Perintah dari pengguna dikirim ke Gemini API, dan dalam panggilan API tersebut ke model Gemini, developer telah menentukan satu atau beberapa deklarasi fungsi dalam suatu alat sehingga model Gemini mengetahui fungsi mana yang dapat dipanggil dan cara memanggilnya.

Input Pengguna -> Gemini API -> Panggilan Fungsi

Gemini API menampilkan Panggilan Fungsi

Berdasarkan isi input dan perintah pengguna, Gemini akan menampilkan respons Panggilan Fungsi dengan data terstruktur yang menyertakan nama fungsi yang akan dipanggil dan parameter terkait yang akan digunakan.

Gemini API -> Panggilan Fungsi

Membuat permintaan API

Kemudian, Anda akan menggunakan nama fungsi dan parameter untuk membuat permintaan API guna mengambil informasi dari sistem atau API eksternal. Permintaan dan respons API ini diimplementasikan oleh developer dalam kode aplikasi dan terjadi di luar cakupan Gemini API dan SDK. Misalnya, Anda dapat menggunakan library requests di Python untuk memanggil REST API dan menerima respons JSON. Atau, Anda dapat memanggil fungsi menggunakan pendekatan dan library klien pilihan Anda.

Parameter API -> API Eksternal -> Respons API

Menampilkan Respons API ke Gemini

Terakhir, Anda akan meneruskan respons API kembali ke model Gemini sehingga model Gemini dapat menghasilkan respons terhadap perintah awal pengguna akhir atau memanggil respons Panggilan Fungsi lain jika model Gemini menentukan bahwa model tersebut memerlukan informasi tambahan.

Respons API -> Respons Fungsi -> Output Model

6. Pilih API Anda

Setelah memahami alur keseluruhan dan langkah-langkah spesifik dalam panggilan fungsi, Anda akan membangun pipeline AI generatif untuk mengambil nilai tukar mata uang terbaru. Pertama, kita harus memilih API yang ingin kita gunakan sebagai sumber informasi.

Untuk aplikasi pertukaran mata uang, kami akan menggunakan REST API di https://www.frankfurter.app/ untuk mengambil informasi terbaru tentang nilai tukar global.

Untuk berinteraksi dengan REST API ini, kita dapat melakukan panggilan REST API dengan requests di Python sebagai:

import requests
url = "https://api.frankfurter.app/latest"
response = requests.get(url)
response.text

atau permintaan cURL seperti:

curl https://api.frankfurter.app/latest

yang menampilkan respons yang mirip dengan:

{
  "amount": 1,
  "base": "EUR",
  "date": "2023-12-20",
  "rates": {
    "AUD": 1.6186, "BGN": 1.9558, "BRL": 5.3287,
    "CAD": 1.4609, "CHF": 0.946, "CNY": 7.8121,
    "CZK": 24.538, "DKK": 7.4565, "GBP": 0.86555,
    "HKD": 8.5439, "HUF": 385.23, "IDR": 16994,
    "ILS": 3.9983, "INR": 91.06, "ISK": 150.3,
    "JPY": 157.12, "KRW": 1425.62, "MXN": 18.6867,
    "MYR": 5.0977, "NOK": 11.2895, "NZD": 1.7421,
    "PHP": 60.991, "PLN": 4.3413, "RON": 4.9699,
    "SEK": 11.129, "SGD": 1.4562, "THB": 38.252,
    "TRY": 31.883, "USD": 1.0944, "ZAR": 20.111
  }
}

Karena panggilan fungsi di Gemini tidak benar-benar membuat panggilan API eksternal untuk Anda, tidak ada pembatasan semacam itu untuk jenis API yang Anda gunakan. Anda dapat menggunakan Layanan Cloud Run, Cloud Function, permintaan API ke layanan Google Cloud, atau REST API eksternal.

7. Mendefinisikan fungsi dan {i>tool<i}

Setelah memilih REST API yang akan digunakan, sekarang kita dapat menentukan spesifikasi API dan mendaftarkan fungsi di alat.

Pastikan Anda telah menginstal Vertex AI SDK untuk Python versi terbaru.

Kemudian, impor modul yang diperlukan dari Python SDK dan lakukan inisialisasi model Gemini:

from vertexai.generative_models import (
    Content,
    FunctionDeclaration,
    GenerativeModel,
    Part,
    Tool,
)

model = GenerativeModel("gemini-1.5-pro-001")

Mengacu kembali ke REST API di https://api.frankfurter.app/, kita dapat melihat bahwa REST API ini menerima parameter input berikut:

Parameter	Jenis	Deskripsi
from	String	Mata uang sumber konversi
to	String	Konversikan ke mata uang
date	String	Tanggal pengambilan nilai tukar untuk

Dengan menggunakan parameter ini, spesifikasi OpenAPI parsial untuk REST API ini dalam format YAML akan terlihat seperti ini:

openapi: 3.0.0
info:
  title: Frankfurter Exchange Rate API
  description: This API provides current and historical exchange rates
  version: 1.0.0
servers:
  - url: https://api.frankfurter.app
paths:
  /{date}:
    get:
      summary: Get the latest currency exchange rates.
      parameters:
        - name: date
          in: path
          description: Get currency rates for a specific date or 'latest' if a date is not specified
          required: true
          schema:
            type: string
        - name: from
          in: query
          description: The currency to convert from.
          required: true
          schema:
            type: string
        - name: to
          in: query
          description: The currency to convert to.
          schema:
            type: string

Sekarang, mari kita daftarkan ini sebagai FunctionDeclaration menggunakan Python SDK untuk Gemini:

get_exchange_rate_func = FunctionDeclaration(
    name="get_exchange_rate",
    description="Get the exchange rate for currencies between countries",
    parameters={
    "type": "object",
    "properties": {
        "currency_date": {
            "type": "string",
            "description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
        },
        "currency_from": {
            "type": "string",
            "description": "The currency to convert from in ISO 4217 format"
        },
        "currency_to": {
            "type": "string",
            "description": "The currency to convert to in ISO 4217 format"
        }
    },
         "required": [
            "currency_from",
            "currency_date",
      ]
  },
)

Pastikan untuk menggunakan deskripsi fungsi dan parameter sedetail mungkin karena model generatif akan menggunakan informasi ini untuk menentukan fungsi mana yang akan dipilih dan cara mengisi parameter dalam panggilan fungsi.

Terakhir, Anda akan menentukan Tool yang menyertakan deklarasi fungsi:

exchange_rate_tool = Tool(
    function_declarations=[get_exchange_rate_func],
)

Di sini, Anda menggunakan satu deklarasi fungsi dalam sebuah alat, tetapi perhatikan bahwa Anda dapat mendaftarkan satu atau beberapa deklarasi fungsi dalam sebuah alat, dan model akan memilih fungsi yang sesuai untuk digunakan saat runtime. Lihat dokumentasi tentang Panggilan Fungsi di Gemini API untuk mengetahui detail selengkapnya tentang FunctionDeclaration, Tool, dan class terkait di Gemini SDK untuk Python.

Anda telah menyelesaikan konfigurasi definisi fungsi dan alat Anda. Di bagian berikutnya, kita akan memanggil model generatif dengan alat ini dan mendapatkan kembali panggilan fungsi yang dapat kita gunakan untuk memanggil REST API.

8. Membuat panggilan fungsi

Sekarang Anda dapat memerintahkan model generatif dan menyertakan tool yang telah Anda tentukan:

prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""

response = model.generate_content(
    prompt,
    tools=[exchange_rate_tool],
)

Mari kita lihat objek respons:

print(response.candidates[0].content)

role: "model"
parts {
  function_call {
    name: "get_exchange_rate"
    args {
      fields {
        key: "currency_to"
        value {
          string_value: "SEK"
        }
      }
      fields {
        key: "currency_from"
        value {
          string_value: "AUD"
        }
      }
      fields {
        key: "currency_date"
        value {
          string_value: "latest"
        }
      }
    }
  }
}

Sepertinya model ini memilih satu fungsi yang tersedia dan menampilkan panggilan fungsi untuk fungsi get_exchange_rate bersama dengan parameter. Dan parameternya menggunakan format yang benar sesuai keinginan kita. Anda berhasil mendapatkan respons terstruktur dari model generatif.

Di bagian berikutnya, Anda akan menggunakan informasi dalam respons untuk membuat permintaan API.

9. Membuat permintaan API

Ingat bahwa panggilan fungsi di Gemini sebenarnya tidak melakukan panggilan API eksternal untuk Anda. Sebaliknya, Anda bebas menggunakan bahasa, pustaka, atau kerangka kerja apa pun yang Anda inginkan.

Di sini Anda akan menggunakan library requests di Python untuk memanggil REST API nilai tukar.

Mari kita urai responsnya menjadi kamus Python:

params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
    params[key[9:]] = value
params

Sekarang kita dapat memanggil requests atau metode lainnya:

import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text

Yang menghasilkan respons yang mirip dengan:

'{"amount":1.0,"base":"AUD","date":"2024-01-16","rates":{"SEK":6.8682}}'

Dan respons kami berasal dari REST API, dengan informasi nilai tukar terbaru hari ini. Di bagian berikutnya, kita akan meneruskan informasi ini kembali ke model sehingga model dapat menghasilkan respons yang relevan bagi pengguna.

10. Membuat respons

Terakhir, mari kita buat respons untuk pengguna dengan meneruskan kembali respons fungsi ke model dalam giliran percakapan berikutnya:

response = model.generate_content(
    [
    Content(role="user", parts=[
        Part.from_text(prompt + """Give your answer in steps with lots of detail
            and context, including the exchange rate and date."""),
    ]),
    Content(role="function", parts=[
        Part.from_dict({
            "function_call": {
                "name": "get_exchange_rate",
            }
        })
    ]),
    Content(role="function", parts=[
        Part.from_function_response(
            name="get_exchange_rate",
            response={
                "content": api_response.text,
            }
        )
    ]),
    ],
    tools=[exchange_rate_tool],
)


response.candidates[0].content.parts[0].text

Setelah kita meneruskan respons fungsi kembali ke model, respons tersebut akan merespons perintah pengguna beserta informasi yang relevan dari respons API.

The exchange rate from Australian dollars to Swedish krona on January 16, 2024,
is 1 Australian dollar is equal to 6.8663 Swedish krona.

So, 500 Australian dollars would be worth 500 * 6.8663 = 3,433.15 Swedish krona.

11. Lihat contoh kode lengkap

Pada tahap ini, Anda dapat menempatkan kode Python di API backend menggunakan layanan Cloud Run, Cloud Function, atau layanan Cloud lainnya dan men-deploy aplikasi frontend yang menggunakan API backend ini untuk melakukan kueri model dan panggilan API.

Berikut adalah contoh kode lengkap untuk solusi akhir kami:

import requests
from vertexai.generative_models import (
    Content,
    FunctionDeclaration,
    GenerativeModel,
    Part,
    Tool,
)

model = GenerativeModel("gemini-1.5-pro-001")

get_exchange_rate_func = FunctionDeclaration(
    name="get_exchange_rate",
    description="Get the exchange rate for currencies between countries",
    parameters={
    "type": "object",
    "properties": {
        "currency_date": {
            "type": "string",
            "description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
        },
        "currency_from": {
            "type": "string",
            "description": "The currency to convert from in ISO 4217 format"
        },
        "currency_to": {
            "type": "string",
            "description": "The currency to convert to in ISO 4217 format"
        }
    },
         "required": [
            "currency_from",
            "currency_date",
      ]
  },
)

exchange_rate_tool = Tool(
    function_declarations=[get_exchange_rate_func],
)

prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""

response = model.generate_content(
    prompt,
    tools=[exchange_rate_tool],
)

response.candidates[0].content

params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
    params[key[9:]] = value
params

import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text

response = model.generate_content(
    [
    Content(role="user", parts=[
        Part.from_text(prompt + """Give your answer in steps with lots of detail
            and context, including the exchange rate and date."""),
    ]),
    Content(role="function", parts=[
        Part.from_dict({
            "function_call": {
                "name": "get_exchange_rate",
            }
        })
    ]),
    Content(role="function", parts=[
        Part.from_function_response(
            name="get_exchange_rate",
            response={
                "content": api_response.text,
            }
        )
    ]),
    ],
    tools=[exchange_rate_tool],
)


response.candidates[0].content.parts[0].text

Dalam implementasi ini, kita menggunakan dua permintaan ke model generatif: satu permintaan untuk menghasilkan panggilan fungsi dan permintaan lainnya untuk menampilkan respons fungsi. Perlu diperhatikan bahwa ini hanyalah salah satu metode untuk menangani panggilan fungsi dan respons fungsi dengan Gemini. Anda juga dapat melakukan panggilan fungsi tambahan untuk mendapatkan informasi lebih lanjut untuk kueri Anda, atau menggunakan panggilan fungsi dengan metode chat dan asinkron.

Untuk contoh kode tambahan, lihat contoh notebook untuk panggilan fungsi di Gemini.

12. Selamat

Dengan menggunakan panggilan fungsi di Gemini, Anda telah berhasil membangun pipeline AI generatif yang digunakan dengan Vertex AI Gemini API dan Python. Pengguna dapat bertanya tentang nilai tukar, dan sistem akan mengambil data terbaru dari API eksternal serta merespons dengan sebuah jawaban.

Begitu diberi perintah dari pengguna akhir, panggilan fungsi di Gemini akan menangani pemilihan fungsi yang sesuai, mengekstrak parameter dari prompt, dan menampilkan objek data terstruktur agar Anda dapat melakukan panggilan API eksternal.

Desain panggilan fungsi di Gemini dimaksudkan untuk memberi Anda kemampuan terbaik dari kedua platform tersebut untuk mengekstrak parameter secara deterministik, sekaligus menyerahkan perangkuman dan pembuatan konten ke model generatif. Jangan ragu untuk mencoba API dan perintah lain di pipeline Anda serta mempelajari fungsi lain yang tersedia terkait Vertex AI Gemini API.

Pembersihan

Anda dapat melakukan pembersihan berikut agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini:

• Untuk menghindari biaya Google Cloud yang tidak perlu, gunakan Konsol Google Cloud untuk menghapus project jika Anda tidak memerlukannya.
• Jika Anda ingin menonaktifkan API untuk Vertex AI, buka halaman Detail Layanan Vertex AI API, lalu klik Disable API lalu konfirmasi.

Pelajari Lebih Lanjut

Terus pelajari AI percakapan dan AI generatif dengan panduan dan referensi berikut:

• Ringkasan model Gemini
• Dokumentasi untuk panggilan fungsi di Gemini
• Contoh notebook untuk panggilan fungsi di Gemini
• Contoh notebook untuk Gemini
• AI Generatif di Google Cloud

Lisensi

Karya ini dilisensikan berdasarkan Lisensi Umum Creative Commons Attribution 2.0.