Tutorial panggilan fungsi

Panggilan fungsi memudahkan Anda mendapatkan output data terstruktur dari model generatif. Selanjutnya, 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 terbaru dan akurat.

Anda dapat memberikan deskripsi fungsi ke model Gemini. Ini adalah fungsi yang Anda tulis dalam bahasa aplikasi (artinya, fungsi tersebut bukan 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 kode contoh di repositori Buku resep Gemini API.

Contoh API untuk kontrol pencahayaan

Bayangkan Anda memiliki sistem kontrol pencahayaan dasar dengan application programming interface (API) dan Anda 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 cahaya dan suhu warnanya, yang didefinisikan sebagai dua parameter terpisah:

Parameter Jenis Wajib Deskripsi
brightness number ya Level 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 mempermudah, sistem pencahayaan imajiner ini hanya memiliki satu cahaya, 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 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 nilai 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.

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 bagaimana dan kapan fungsi ini dijalankan melalui kode aplikasi Anda. Untuk tujuan demonstrasi, tutorial ini menentukan fungsi API tiruan yang hanya menampilkan 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 Anda membuat fungsi yang akan digunakan dalam panggilan fungsi 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.

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 menginisialisasi model dengan deklarasi fungsi, Anda dapat memerintahkan 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.

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 untuk otomatis memiliki SDK

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

Menentukan 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 instruksi 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 otomatis skema dari fungsi Python tidak berfungsi di semua kasus. Misalnya: kode ini tidak menangani kasus saat Anda mendeskripsikan kolom objek kamus bertingkat, tetapi API mendukungnya. 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.

Intip di dalam atribut _tools model terlebih dahulu, Anda dapat melihat caranya menjelaskan 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 cetak tidak familier, hal itu karena merupakan class protobuf Google. Setiap genai.protos.Tool (dalam kasus ini) berisi daftar genai.protos.FunctionDeclarations, yang menjelaskan fungsi dan argumennya.

Berikut adalah deklarasi untuk fungsi pengalian yang sama yang ditulis menggunakan class genai.protos. Perhatikan bahwa class ini hanya menjelaskan fungsi untuk API, tidak menyertakan implementasinya. Jadi, penggunaannya 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 sebelum 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}))]))