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 berisi informasi yang terbaru dan akurat.

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

Jika belum melakukannya, lihat Pengantar panggilan fungsi untuk mempelajari lebih lanjut. Anda juga dapat mencoba fitur ini di Google Colab atau melihat contoh kode di repositori Gemini API Cookbook.

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 pencahayaan mengubah permintaan dari pengguna dan menerjemahkannya menjadi panggilan API untuk menyetel pencahayaan masing-masing. Sistem kontrol pencahayaan hipotetis ini memungkinkan Anda mengontrol kecerahan cahaya dan suhu warnanya, yang didefinisikan sebagai dua parameter:

Parameter Jenis Wajib diisi Deskripsi
brightness angka ya Tingkat cahaya dari 0 hingga 100. Nol tidak aktif dan 100 adalah kecerahan penuh.
colorTemperature string ya Suhu warna lampu yang bisa daylight, cool, atau warm.

Untuk kesederhanaan, sistem pencahayaan imajiner ini hanya memiliki satu cahaya, sehingga pengguna tidak harus menentukan ruangan atau lokasi. Berikut adalah contoh permintaan JSON Anda bisa mengirim ke Light Control API untuk mengubah level cahaya menjadi 50% menggunakan suhu warna siang hari:

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

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

Sebelum memulai: Siapkan project dan kunci API Anda

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

Menentukan fungsi API

Buat fungsi yang membuat permintaan API. Fungsi ini harus ditentukan dalam kode aplikasi Anda, namun dapat memanggil layanan atau API di luar aplikasi Anda. Gemini API tidak memanggil fungsi ini secara langsung, sehingga Anda dapat mengontrol bagaimana dan kapan fungsi ini dijalankan melalui aplikasi Anda pada kode sumber. Untuk tujuan demonstrasi, tutorial ini mendefinisikan fungsi API tiruan yang hanya mengembalikan nilai pencahayaan yang diminta:

def set_light_values(brightness, color_temp):
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {
        "brightness": brightness,
        "colorTemperature": color_temp
    }

Saat membuat fungsi yang akan digunakan dalam panggilan fungsi oleh model, Anda harus menyertakan detail sebanyak mungkin dalam fungsi dan parameter deskripsi. Model generatif menggunakan informasi ini untuk menentukan fungsi untuk memilih dan cara memberikan nilai untuk parameter dalam fungsi panggilan telepon.

Mendeklarasikan fungsi selama inisialisasi model

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

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                              tools=[set_light_values])

Membuat panggilan fungsi

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

chat = model.start_chat()
response = chat.send_message('Dim the lights so the room feels cozy and warm.')
response.text

Objek ChatSession Python SDK menyederhanakan pengelolaan sesi chat dengan menangani histori percakapan untuk Anda. Anda dapat menggunakan enable_automatic_function_calling agar SDK secara otomatis memanggil fungsi.

# Create a chat session that automatically makes suggested function calls
chat = model.start_chat(enable_automatic_function_calling=True)

Panggilan fungsi paralel

Selain panggilan fungsi dasar yang dijelaskan di atas, Anda juga dapat memanggil beberapa fungsi dalam satu giliran. Bagian ini menampilkan contoh cara menggunakan panggilan fungsi paralel.

Tentukan alat.

def power_disco_ball(power: bool) -> bool:
    """Powers the spinning disco ball."""
    print(f"Disco ball is {'spinning!' if power else 'stopped.'}")
    return True


def start_music(energetic: bool, loud: bool, bpm: int) -> str:
    """Play some music matching the specified parameters.

    Args:
      energetic: Whether the music is energetic or not.
      loud: Whether the music is loud or not.
      bpm: The beats per minute of the music.

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}, {bpm=}")
    return "Never gonna give you up."


def dim_lights(brightness: float) -> bool:
    """Dim the lights.

    Args:
      brightness: The brightness of the lights, 0.0 is off, 1.0 is full.
    """
    print(f"Lights are now set to {brightness:.0%}")
    return True

Sekarang, panggil model dengan petunjuk yang dapat menggunakan semua alat yang ditentukan.

# Set the model up with tools.
house_fns = [power_disco_ball, start_music, dim_lights]

model = genai.GenerativeModel(model_name="gemini-1.5-flash", tools=house_fns)

# Call the API.
chat = model.start_chat()
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call.
for part in response.parts:
    if fn := part.function_call:
        args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
        print(f"{fn.name}({args})")

power_disco_ball(power=True)
start_music(energetic=True, loud=True, bpm=120.0)
dim_lights(brightness=0.3)

Setiap hasil yang dicetak mencerminkan satu panggilan fungsi yang telah diminta model. Untuk mengirim kembali hasil, sertakan respons dalam urutan yang sama seperti yang diminta.

# Simulate the responses from the specified tools.
responses = {
    "power_disco_ball": True,
    "start_music": "Never gonna give you up.",
    "dim_lights": True,
}

# Build the response parts.
response_parts = [
    genai.protos.Part(function_response=genai.protos.FunctionResponse(name=fn, response={"result": val}))
    for fn, val in responses.items()
]

response = chat.send_message(response_parts)
print(response.text)

Let's get this party started! I've turned on the disco ball, started playing some upbeat music, and dimmed the lights. 🎶✨  Get ready to dance! 🕺💃

Pemetaan jenis data panggilan fungsi

Ekstraksi skema otomatis dari fungsi Python tidak berfungsi dalam semua kasus. Misalnya: tidak menangani kasus saat Anda menjelaskan kolom objek kamus bertingkat, tetapi API mendukung hal ini. API ini dapat mendeskripsikan salah satu jenis berikut:

AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])

Library klien google.ai.generativelanguage menyediakan akses ke jenis tingkat rendah yang memberi Anda kontrol penuh.

Pertama-tama, lihat atribut _tools model, Anda dapat melihat cara atribut tersebut mendeskripsikan fungsi yang Anda teruskan ke model:

def multiply(a:float, b:float):
    """returns a * b."""
    return a*b

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                             tools=[multiply])

model._tools.to_proto()

[function_declarations {
   name: "multiply"
   description: "returns a * b."
   parameters {
     type_: OBJECT
     properties {
       key: "b"
       value {
         type_: NUMBER
       }
     }
     properties {
       key: "a"
       value {
         type_: NUMBER
       }
     }
     required: "a"
     required: "b"
   }
 }]

Tindakan ini akan menampilkan daftar objek genai.protos.Tool yang akan dikirim ke API. Jika format yang dicetak tidak dikenal, hal ini karena format tersebut adalah class protobuf Google. Setiap genai.protos.Tool (1 dalam kasus ini) berisi daftar genai.protos.FunctionDeclarations, yang mendeskripsikan fungsi dan argumen.

Berikut adalah deklarasi untuk fungsi perkalian yang sama yang ditulis menggunakan class genai.protos. Perhatikan bahwa class ini hanya menjelaskan fungsi untuk API, tetapi tidak menyertakan implementasinya. Jadi, penggunaan ini tidak berfungsi dengan panggilan fungsi otomatis, tetapi fungsi tidak selalu memerlukan implementasi.

calculator = genai.protos.Tool(
    function_declarations=[
      genai.protos.FunctionDeclaration(
        name='multiply',
        description="Returns the product of two numbers.",
        parameters=genai.protos.Schema(
            type=genai.protos.Type.OBJECT,
            properties={
                'a':genai.protos.Schema(type=genai.protos.Type.NUMBER),
                'b':genai.protos.Schema(type=genai.protos.Type.NUMBER)
            },
            required=['a','b']
        )
      )
    ])

Dengan demikian, Anda dapat mendeskripsikan objek ini sebagai objek yang kompatibel dengan JSON:

calculator = {'function_declarations': [
      {'name': 'multiply',
       'description': 'Returns the product of two numbers.',
       'parameters': {'type_': 'OBJECT',
       'properties': {
         'a': {'type_': 'NUMBER'},
         'b': {'type_': 'NUMBER'} },
       'required': ['a', 'b']} }]}

genai.protos.Tool(calculator)

function_declarations {
  name: "multiply"
  description: "Returns the product of two numbers."
  parameters {
    type_: OBJECT
    properties {
      key: "b"
      value {
        type_: NUMBER
      }
    }
    properties {
      key: "a"
      value {
        type_: NUMBER
      }
    }
    required: "a"
    required: "b"
  }
}

Apa pun itu, Anda harus meneruskan representasi genai.protos.Tool atau daftar alat ke

model = genai.GenerativeModel('gemini-1.5-flash', tools=calculator)
chat = model.start_chat()

response = chat.send_message(
    f"What's 234551 X 325552 ?",
)

Seperti sebelumnya, model menampilkan genai.protos.FunctionCall yang memanggil fungsi multiply kalkulator:

response.candidates

[index: 0
content {
  parts {
    function_call {
      name: "multiply"
      args {
        fields {
          key: "b"
          value {
            number_value: 325552
          }
        }
        fields {
          key: "a"
          value {
            number_value: 234551
          }
        }
      }
    }
  }
  role: "model"
}
finish_reason: STOP
]

Jalankan fungsi sendiri:

fc = response.candidates[0].content.parts[0].function_call
assert fc.name == 'multiply'

result = fc.args['a'] * fc.args['b']
result

76358547152.0

Kirim hasilnya ke model, untuk melanjutkan percakapan:

response = chat.send_message(
    genai.protos.Content(
    parts=[genai.protos.Part(
        function_response = genai.protos.FunctionResponse(
          name='multiply',
          response={'result': result}))]))