Lihat di ai.google.dev | Menjalankan di Google Colab | Lihat sumber di GitHub |
Anda dapat memberikan deskripsi fungsi kepada model Gemini. Model ini mungkin meminta Anda untuk memanggil fungsi dan mengirim kembali hasilnya untuk membantu model menangani kueri Anda.
Penyiapan
Menginstal Python SDK
Python SDK untuk Gemini API terdapat dalam paket google-generativeai
. Instal dependensi menggunakan pip:
pip install -U -q google-generativeai
Mengimpor paket
Impor paket yang diperlukan.
import pathlib
import textwrap
import time
import google.generativeai as genai
from IPython import display
from IPython.display import Markdown
def to_markdown(text):
text = text.replace('•', ' *')
return Markdown(textwrap.indent(text, '> ', predicate=lambda _: True))
Menyiapkan kunci API
Sebelum dapat menggunakan Gemini API, Anda harus mendapatkan kunci API terlebih dahulu. Jika Anda belum memilikinya, buat kunci dengan sekali klik di Google AI Studio.
Di Colab, tambahkan kunci ke secret manager di bawah "mo" di panel kiri. Beri nama API_KEY
.
Setelah Anda memiliki kunci API, teruskan ke SDK. Anda dapat melakukannya dengan dua cara:
- Masukkan kunci di variabel lingkungan
GOOGLE_API_KEY
(SDK akan otomatis mengambilnya dari sana). - Teruskan kunci ke
genai.configure(api_key=...)
try:
# Used to securely store your API key
from google.colab import userdata
# Or use `os.getenv('API_KEY')` to fetch an environment variable.
GOOGLE_API_KEY=userdata.get('GOOGLE_API_KEY')
except ImportError:
import os
GOOGLE_API_KEY = os.environ['GOOGLE_API_KEY']
genai.configure(api_key=GOOGLE_API_KEY)
Dasar-Dasar Fungsi
Anda dapat meneruskan daftar fungsi ke argumen tools
saat membuat genai.GenerativeModel
.
def multiply(a:float, b:float):
"""returns a * b."""
return a*b
model = genai.GenerativeModel(model_name='gemini-1.0-pro',
tools=[multiply])
model
genai.GenerativeModel( model_name='models/gemini-1.0-pro', generation_config={}, safety_settings={}, tools=<google.generativeai.types.content_types.FunctionLibrary object at 0x10e73fe90>, )
Cara yang direkomendasikan untuk menggunakan panggilan fungsi adalah melalui antarmuka chat. Alasan utamanya adalah FunctionCalls
cocok dengan struktur multi-giliran chat.
chat = model.start_chat(enable_automatic_function_calling=True)
Dengan panggilan fungsi otomatis yang diaktifkan, chat.send_message
akan otomatis memanggil fungsi Anda jika model memintanya.
Tampaknya hanya mengembalikan respons teks, yang berisi jawaban yang benar:
response = chat.send_message('I have 57 cats, each owns 44 mittens, how many mittens is that in total?')
response.text
'The total number of mittens is 2508.'
57*44
2508
Jika melihat ChatSession.history
, Anda dapat melihat urutan peristiwa:
- Anda mengirim pertanyaan.
- Model membalas dengan
glm.FunctionCall
. genai.ChatSession
mengeksekusi fungsi secara lokal dan mengirim kembali modelglm.FunctionResponse
.- Model menggunakan output fungsi dalam jawabannya.
for content in chat.history:
part = content.parts[0]
print(content.role, "->", type(part).to_dict(part))
print('-'*80)
user -> {'text': 'I have 57 cats, each owns 44 mittens, how many mittens is that in total?'} -------------------------------------------------------------------------------- model -> {'function_call': {'name': 'multiply', 'args': {'a': 57.0, 'b': 44.0} } } -------------------------------------------------------------------------------- user -> {'function_response': {'name': 'multiply', 'response': {'result': 2508.0} } } -------------------------------------------------------------------------------- model -> {'text': 'The total number of mittens is 2508.'} --------------------------------------------------------------------------------
Secara umum, diagram status adalah:
Model ini bisa merespons dengan beberapa panggilan fungsi sebelum menampilkan respons teks, dan panggilan fungsi muncul sebelum respons teks.
Meskipun semua ini ditangani secara otomatis, jika Anda memerlukan kontrol lebih besar, Anda dapat:
- Biarkan
enable_automatic_function_calling=False
default dan proses sendiri responsglm.FunctionCall
. - Atau gunakan
GenerativeModel.generate_content
, di mana Anda juga perlu mengelola histori chat.
[Opsional] Akses tingkat rendah
Ekstraksi skema secara otomatis dari fungsi Python tidak berfungsi pada semua kasus. Misalnya: API ini tidak menangani kasus saat Anda menjelaskan kolom objek kamus bertingkat, tetapi API mendukung hal ini. API ini dapat menjelaskan jenis apa pun berikut:
AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType]
Library klien google.ai.generativelanguage
memberikan akses ke jenis tingkat rendah yang memberi Anda kontrol penuh.
import google.ai.generativelanguage as glm
Lihat sekilas ke dalam atribut _tools
model, Anda dapat melihat cara atribut tersebut 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.0-pro',
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 glm.Tool
yang akan dikirim ke API. Format cetak tidak dikenal karena format tersebut adalah class protobuf Google. Setiap glm.Tool
(dalam hal ini 1) berisi daftar glm.FunctionDeclarations
, yang menjelaskan fungsi dan argumennya.
Berikut adalah deklarasi untuk fungsi perkalian yang sama yang ditulis menggunakan class glm
.
Perhatikan bahwa class tersebut 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 = glm.Tool(
function_declarations=[
glm.FunctionDeclaration(
name='multiply',
description="Returns the product of two numbers.",
parameters=glm.Schema(
type=glm.Type.OBJECT,
properties={
'a':glm.Schema(type=glm.Type.NUMBER),
'b':glm.Schema(type=glm.Type.NUMBER)
},
required=['a','b']
)
)
])
Pada dasarnya, Anda dapat mendeskripsikan 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']} }]}
glm.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 meneruskan representasi glm.Tool
atau daftar alat untuk
model = genai.GenerativeModel('gemini-pro', tools=calculator)
chat = model.start_chat()
response = chat.send_message(
f"What's 234551 X 325552 ?",
)
Seperti sebelum model menampilkan glm.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(
glm.Content(
parts=[glm.Part(
function_response = glm.FunctionResponse(
name='multiply',
response={'result': result}))]))
Ringkasan
Panggilan fungsi dasar didukung di SDK. Perlu diingat bahwa pengelolaan menggunakan mode chat akan lebih mudah karena struktur bolak-balik yang alami. Anda bertanggung jawab untuk memanggil fungsi dan mengirimkan hasilnya kembali ke model sehingga model bisa menghasilkan respons teks.