Model Bahasa Besar (LLM) sangat andal dalam memecahkan berbagai jenis masalah. Namun, konfigurasinya dibatasi oleh batasan berikut:
- LLM dibekukan setelah pelatihan, sehingga pengetahuan yang ada dalamnya tidak diperbarui.
- LLM tidak dapat membuat kueri atau mengubah data eksternal.
Panggilan fungsi dapat mengatasi kekurangan ini. Panggilan fungsi terkadang disebut sebagai penggunaan alat karena memungkinkan model menggunakan alat eksternal seperti API dan fungsi.
Saat mengirimkan perintah ke LLM, Anda juga
memberikan serangkaian alat yang dapat digunakan model untuk merespons perintah pengguna. Misalnya, Anda dapat menyediakan fungsi get_weather yang menggunakan parameter
lokasi dan menampilkan informasi tentang kondisi cuaca di lokasi tersebut.
Saat memproses perintah, model dapat memilih untuk mendelegasikan tugas pemrosesan data tertentu ke fungsi yang Anda identifikasi. Model tidak memanggil fungsi secara langsung. Sebagai gantinya, model ini memberikan output data terstruktur
yang menyertakan fungsi yang akan dipanggil dan nilai parameter yang akan digunakan. Misalnya, untuk
prompt What is the weather like in Boston?, model dapat mendelegasikan pemrosesan
ke fungsi get_weather dan memberikan nilai parameter lokasi Boston, MA.
Anda dapat menggunakan output terstruktur dari model untuk memanggil API eksternal. Misalnya, Anda dapat terhubung ke API layanan cuaca, memberikan lokasi
Boston, MA, dan menerima informasi tentang suhu, tutupan awan, dan kondisi
angin.
Kemudian, Anda dapat memberikan output API kembali ke model, sehingga model dapat menyelesaikan
responsnya terhadap perintah. Untuk contoh cuaca, model dapat memberikan
respons berikut: It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies.
Model yang didukung
Model berikut memberikan dukungan untuk panggilan fungsi:
| Model | Versi | Tahap peluncuran panggilan fungsi | Dukungan untuk panggilan fungsi paralel | Dukungan untuk panggilan fungsi paksa |
|---|---|---|---|---|
| Gemini 1.0 Pro | all versions |
Ketersediaan Umum | Tidak | Tidak |
| Gemini 1.5 Flash | all versions |
Ketersediaan Umum | Ya | Ya |
| Gemini 1.5 Pro | all versions |
Ketersediaan Umum | Ya | Ya |
Kasus penggunaan panggilan fungsi
Anda dapat menggunakan panggilan fungsi untuk tugas berikut:
| Kasus Penggunaan | Contoh deskripsi | Contoh link |
|---|---|---|
| Mengintegrasikan dengan API eksternal | Mendapatkan informasi cuaca menggunakan API meteorologi | Tutorial notebook |
| Mengonversi alamat menjadi koordinat lintang/bujur | Tutorial notebook | |
| Mengonversi mata uang menggunakan API pertukaran mata uang | Codelab | |
| Membuat chatbot lanjutan | Menjawab pertanyaan pelanggan tentang produk dan layanan | Tutorial notebook |
| Membuat asisten untuk menjawab pertanyaan keuangan dan berita tentang perusahaan | Tutorial notebook | |
| Menyusun dan mengontrol panggilan fungsi | Mengekstrak entity terstruktur dari data log mentah | Tutorial notebook |
| Mengekstrak satu atau beberapa parameter dari input pengguna | Tutorial notebook | |
| Menangani daftar dan struktur data bertingkat dalam panggilan fungsi | Tutorial notebook | |
| Menangani perilaku panggilan fungsi | Menangani respons dan panggilan fungsi paralel | Tutorial notebook |
| Mengelola kapan dan fungsi mana yang dapat dipanggil model | Tutorial notebook | |
| Membuat kueri database dengan bahasa alami | Mengonversi pertanyaan dalam bahasa alami menjadi kueri SQL untuk BigQuery | Aplikasi contoh |
| Panggilan fungsi multimodal | Menggunakan gambar, video, audio, dan PDF sebagai input untuk memicu panggilan fungsi | Tutorial notebook |
Berikut beberapa kasus penggunaan lainnya:
Menafsirkan perintah suara: Membuat fungsi yang sesuai dengan tugas dalam kendaraan. Misalnya, Anda dapat membuat fungsi yang mengaktifkan radio atau mengaktifkan AC. Kirim file audio perintah suara pengguna ke model, dan minta model untuk mengonversi audio menjadi teks dan mengidentifikasi fungsi yang ingin dipanggil pengguna.
Mengotomatiskan alur kerja berdasarkan pemicu lingkungan: Buat fungsi untuk mewakili proses yang dapat diotomatiskan. Berikan data dari sensor lingkungan ke model dan minta model untuk mengurai dan memproses data untuk menentukan apakah satu atau beberapa alur kerja harus diaktifkan. Misalnya, model dapat memproses data suhu di gudang dan memilih untuk mengaktifkan fungsi sprinkler.
Mengotomatiskan penetapan tiket dukungan: Berikan tiket dukungan, log, dan aturan berbasis konteks kepada model. Minta model untuk memproses semua informasi ini guna menentukan kepada siapa tiket harus ditetapkan. Panggil fungsi untuk menetapkan tiket kepada orang yang disarankan oleh model.
Mengambil informasi dari pusat informasi: Buat fungsi yang mengambil artikel akademis tentang subjek tertentu dan meringkasnya. Memungkinkan model menjawab pertanyaan tentang mata pelajaran akademis dan memberikan kutipan untuk jawabannya.
Cara membuat aplikasi panggilan fungsi
Agar pengguna dapat berinteraksi dengan model dan menggunakan panggilan fungsi, Anda harus membuat kode yang melakukan tugas berikut:
- Menyiapkan lingkungan Anda
- Menentukan dan mendeskripsikan kumpulan fungsi yang tersedia menggunakan deklarasi fungsi.
- Kirim perintah pengguna dan deklarasi fungsi ke model.
- Memanggil fungsi menggunakan output data terstruktur dari model.
- Berikan output fungsi ke model.
Anda dapat membuat aplikasi yang mengelola semua tugas ini. Aplikasi ini dapat berupa chatbot teks, agen suara, alur kerja otomatis, atau program lainnya.
Anda dapat menggunakan panggilan fungsi untuk membuat satu respons teks atau untuk mendukung sesi chat. Respons teks ad hoc berguna untuk tugas bisnis tertentu, termasuk pembuatan kode. Sesi chat berguna dalam skenario percakapan bebas, tempat pengguna cenderung mengajukan pertanyaan lanjutan.
Jika menggunakan panggilan fungsi untuk menghasilkan satu respons, Anda harus memberikan konteks interaksi lengkap ke model. Di sisi lain, jika Anda menggunakan panggilan fungsi dalam konteks sesi chat, sesi akan menyimpan konteks untuk Anda dan menyertakannya dalam setiap permintaan model. Dalam kedua kasus tersebut, Vertex AI menyimpan histori interaksi di sisi klien.
Panduan ini menunjukkan cara menggunakan panggilan fungsi untuk menghasilkan satu respons teks. Untuk contoh menyeluruh, lihat Contoh teks. Untuk mempelajari cara menggunakan panggilan fungsi guna mendukung sesi chat, lihat Contoh chat.
Langkah 1: Menyiapkan lingkungan Anda
Impor modul yang diperlukan dan lakukan inisialisasi model:
Python
import vertexai
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerationConfig,
GenerativeModel,
Part,
Tool,
)
# Initialize Vertex AI
# TODO(developer): Update and un-comment below lines
# PROJECT_ID = 'your-project-id'
vertexai.init(project=PROJECT_ID, location="us-central1")
# Initialize Gemini model
model = GenerativeModel(model_name="gemini-1.5-flash-002")
Langkah 2: Deklarasikan kumpulan fungsi
Aplikasi harus mendeklarasikan serangkaian fungsi yang dapat digunakan model untuk memproses perintah.
Jumlah maksimum deklarasi fungsi yang dapat diberikan dengan permintaan adalah 128.
Anda harus memberikan deklarasi fungsi dalam format skema yang kompatibel
dengan skema OpenAPI. Vertex AI menawarkan dukungan terbatas untuk skema OpenAPI. Atribut
berikut didukung: type, nullable, required, format,
description, properties, items, enum. Atribut berikut tidak
didukung: default, optional, maximum, oneOf. Untuk praktik terbaik terkait deklarasi fungsi, termasuk tips untuk nama dan deskripsi, lihat
Praktik terbaik.
Jika Anda menggunakan REST API, tentukan skema menggunakan JSON. Jika menggunakan
Vertex AI SDK untuk Python, Anda dapat menentukan skema secara manual menggunakan kamus Python atau secara otomatis dengan fungsi bantuan from_func.
JSON
{
"contents": ...,
"tools": [
{
"function_declarations": [
{
"name": "find_movies",
"description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"description": {
"type": "string",
"description": "Any kind of description including category or genre, title words, attributes, etc."
}
},
"required": [
"description"
]
}
},
{
"name": "find_theaters",
"description": "find theaters based on location and optionally movie title which are is currently playing in theaters",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "string",
"description": "Any movie title"
}
},
"required": [
"location"
]
}
},
{
"name": "get_showtimes",
"description": "Find the start times for movies playing in a specific theater",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "string",
"description": "Any movie title"
},
"theater": {
"type": "string",
"description": "Name of the theater"
},
"date": {
"type": "string",
"description": "Date for requested showtime"
}
},
"required": [
"location",
"movie",
"theater",
"date"
]
}
}
]
}
]
}
Kamus Python
Deklarasi fungsi berikut menggunakan satu parameter string:
function_name = "get_current_weather"
get_current_weather_func = FunctionDeclaration(
name=function_name,
description="Get the current weather in a given location",
# Function parameters are specified in JSON schema format
parameters={
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city name of the location for which to get the weather."}
},
},
)
Deklarasi fungsi berikut menggunakan parameter objek dan array:
extract_sale_records_func = FunctionDeclaration(
name="extract_sale_records",
description="Extract sale records from a document.",
parameters={
"type": "object",
"properties": {
"records": {
"type": "array",
"description": "A list of sale records",
"items": {
"description": "Data for a sale record",
"type": "object",
"properties": {
"id": {"type": "integer", "description": "The unique id of the sale."},
"date": {"type": "string", "description": "Date of the sale, in the format of MMDDYY, e.g., 031023"},
"total_amount": {"type": "number", "description": "The total amount of the sale."},
"customer_name": {"type": "string", "description": "The name of the customer, including first name and last name."},
"customer_contact": {"type": "string", "description": "The phone number of the customer, e.g., 650-123-4567."},
},
"required": ["id", "date", "total_amount"],
},
},
},
"required": ["records"],
},
)
Python dari fungsi
Contoh kode berikut mendeklarasikan fungsi yang mengalikan array angka dan menggunakan from_func untuk membuat skema FunctionDeclaration.
# Define a function. Could be a local function or you can import the requests library to call an API
def multiply_numbers(numbers):
"""
Calculates the product of all numbers in an array.
Args:
numbers: An array of numbers to be multiplied.
Returns:
The product of all the numbers. If the array is empty, returns 1.
"""
if not numbers: # Handle empty array
return 1
product = 1
for num in numbers:
product *= num
return product
multiply_number_func = FunctionDeclaration.from_func(multiply_numbers)
'''
multiply_number_func contains the following schema:
name: "multiply_numbers"
description: "Calculates the product of all numbers in an array."
parameters {
type_: OBJECT
properties {
key: "numbers"
value {
description: "An array of numbers to be multiplied."
title: "Numbers"
}
}
required: "numbers"
description: "Calculates the product of all numbers in an array."
title: "multiply_numbers"
}
'''
Langkah 3: Kirim perintah dan deklarasi fungsi ke model
Saat pengguna memberikan perintah, aplikasi harus memberikan perintah pengguna dan deklarasi fungsi kepada model. Untuk mengonfigurasi cara model menghasilkan hasil, aplikasi dapat memberikan konfigurasi pembuatan ke model. Untuk mengonfigurasi cara model menggunakan deklarasi fungsi, aplikasi dapat memberikan konfigurasi alat ke model.
Menentukan perintah pengguna
Berikut adalah contoh perintah pengguna: "Bagaimana cuaca di Jakarta?"
Berikut adalah contoh cara menentukan perintah pengguna:
Python
# Define the user's prompt in a Content object that we can reuse in model calls
user_prompt_content = Content(
role="user",
parts=[
Part.from_text("What is the weather like in Boston?"),
],
)
Untuk praktik terbaik terkait perintah pengguna, lihat Praktik terbaik - Perintah pengguna.
Konfigurasi pembuatan
Model ini dapat memberikan hasil yang berbeda untuk parameter value yang berbeda. Parameter
suhu mengontrol tingkat keacakan dalam pembuatan ini.
Suhu yang lebih rendah cocok untuk fungsi yang memerlukan parameter value deterministik, sedangkan suhu yang lebih tinggi cocok untuk fungsi dengan parameter yang menerima parameter value yang lebih beragam atau kreatif. Suhu 0 bersifat
deterministik. Dalam hal ini, respons untuk perintah tertentu sebagian besar bersifat deterministik, tetapi sejumlah kecil variasi masih memungkinkan. Untuk mempelajari
lebih lanjut, lihat Gemini API.
Untuk menetapkan parameter ini, kirimkan konfigurasi pembuatan (generation_config) bersama dengan perintah dan deklarasi fungsi. Anda dapat memperbarui
parameter temperature selama percakapan chat menggunakan Vertex AI
API dan generation_config yang diperbarui. Untuk contoh penetapan parameter temperature, lihat Cara mengirimkan perintah dan deklarasi fungsi.
Untuk praktik terbaik terkait konfigurasi pembuatan, lihat Praktik terbaik - Konfigurasi pembuatan.
Konfigurasi alat
Anda dapat menempatkan beberapa batasan tentang cara model menggunakan deklarasi fungsi yang Anda berikan. Misalnya, daripada mengizinkan model memilih antara respons bahasa alami dan panggilan fungsi, Anda dapat memaksanya untuk hanya memprediksi panggilan fungsi ("panggilan fungsi paksa" atau "panggilan fungsi dengan pembuatan terkontrol"). Anda juga dapat memilih untuk memberikan kumpulan lengkap deklarasi fungsi ke model, tetapi membatasi responsnya ke subkumpulan fungsi ini.
Untuk menempatkan batasan ini, kirimkan konfigurasi alat (tool_config) bersama dengan perintah dan deklarasi fungsi. Dalam konfigurasi, Anda dapat
menentukan salah satu mode berikut:
| Mode | Deskripsi |
|---|---|
AUTO |
Perilaku model default. Model memutuskan apakah akan memprediksi panggilan fungsi atau respons bahasa alami. |
ANY |
Model dibatasi untuk selalu memprediksi panggilan fungsi. Jika allowed_function_names tidak diberikan, model akan memilih dari semua deklarasi fungsi yang tersedia. Jika allowed_function_names disediakan, model akan memilih dari kumpulan fungsi yang diizinkan. |
NONE |
Model tidak boleh memprediksi panggilan fungsi. Perilaku ini setara dengan permintaan model tanpa deklarasi fungsi terkait. |
Untuk mengetahui daftar model yang mendukung mode ANY ("panggilan fungsi paksa"),
lihat model yang didukung.
Untuk mempelajari lebih lanjut, lihat Function Calling API.
Cara mengirimkan perintah dan deklarasi fungsi
Berikut adalah contoh cara mengirimkan perintah dan deklarasi
fungsi ke model, dan membatasi model untuk hanya memprediksi
panggilan fungsi get_current_weather.
Python
# Define a tool that includes some of the functions that we declared earlier
tool = Tool(
function_declarations=[get_current_weather_func, extract_sale_records_func, multiply_number_func],
)
# Send the prompt and instruct the model to generate content using the Tool object that you just created
response = model.generate_content(
user_prompt_content,
generation_config=GenerationConfig(temperature=0),
tools=[tool],
tool_config=ToolConfig(
function_calling_config=ToolConfig.FunctionCallingConfig(
# ANY mode forces the model to predict only function calls
mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
# Allowed function calls to predict when the mode is ANY. If empty, any of
# the provided function calls will be predicted.
allowed_function_names=["get_current_weather"],
)
)
)
Jika model menentukan bahwa model memerlukan output fungsi tertentu, respons yang diterima aplikasi dari model akan berisi nama fungsi dan nilai parameter yang digunakan untuk memanggil fungsi.
Berikut adalah contoh respons model terhadap perintah pengguna "Bagaimana cuaca di Boston?". Model ini mengusulkan untuk memanggil
fungsi get_current_weather dengan parameter Boston, MA.
candidates {
content {
role: "model"
parts {
function_call {
name: "get_current_weather"
args {
fields {
key: "location"
value {
string_value: "Boston, MA"
}
}
}
}
}
}
...
}
Untuk perintah seperti "Dapatkan detail cuaca di New Delhi dan San Francisco?", model dapat mengusulkan beberapa panggilan fungsi paralel. Untuk mempelajari lebih lanjut, lihat Contoh panggilan fungsi paralel.
Langkah 4: Panggil API eksternal
Jika aplikasi menerima nama fungsi dan nilai parameter dari model, aplikasi harus terhubung ke API eksternal dan memanggil fungsi.
Contoh berikut menggunakan data sintetis untuk menyimulasikan payload respons dari API eksternal:
Python
# Check the function name that the model responded with, and make an API call to an external system
if (response.candidates[0].function_calls[0].name == "get_current_weather"):
# Extract the arguments to use in your API call
location = response.candidates[0].function_calls[0].args["location"]
# Here you can use your preferred method to make an API request to fetch the current weather, for example:
# api_response = requests.post(weather_api_url, data={"location": location})
# In this example, we'll use synthetic data to simulate a response payload from an external API
api_response = """{ "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy",
"icon": "partly-cloudy", "humidity": 65, "wind": { "speed": 10, "direction": "NW" } }"""
Untuk praktik terbaik terkait pemanggilan API, lihat Praktik terbaik - Pemanggilan API.
Langkah 5: Berikan output fungsi ke model
Setelah aplikasi menerima respons dari API eksternal, aplikasi harus memberikan respons ini ke model. Berikut adalah contoh cara melakukannya menggunakan Python:
Python
response = model.generate_content(
[
user_prompt_content, # User prompt
response.candidates[0].content, # Function call response
Content(
parts=[
Part.from_function_response(
name="get_current_weather",
response={
"content": api_response, # Return the API response to Gemini
},
)
],
),
],
tools=[weather_tool],
)
# Get the model summary response
summary = response.text
Jika model telah mengusulkan beberapa panggilan fungsi paralel, aplikasi harus memberikan semua respons kembali ke model. Untuk mempelajari lebih lanjut, lihat Contoh panggilan fungsi paralel.
Model dapat menentukan bahwa output fungsi lain diperlukan untuk merespons perintah. Dalam hal ini, respons yang diterima aplikasi dari model berisi nama fungsi lain dan kumpulan nilai parameter lainnya.
Jika model menentukan bahwa respons API cukup untuk merespons perintah pengguna, model akan membuat respons bahasa alami dan menampilkannya ke aplikasi. Dalam hal ini, aplikasi harus meneruskan respons kembali ke pengguna. Berikut adalah contoh respons:
It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies. The humidity is 65% and the wind is blowing at 10 mph from the northwest.
Contoh panggilan fungsi
Contoh teks
Anda dapat menggunakan panggilan fungsi untuk membuat satu respons teks. Respons teks ad hoc berguna untuk tugas bisnis tertentu, termasuk pembuatan kode.
Jika menggunakan panggilan fungsi untuk menghasilkan satu respons, Anda harus memberikan konteks interaksi lengkap ke model. Vertex AI menyimpan histori interaksi di sisi klien.
Python
Contoh ini menunjukkan skenario teks dengan satu fungsi dan satu
perintah. Class ini menggunakan class GenerativeModel dan metodenya. Untuk mengetahui informasi
selengkapnya tentang penggunaan Vertex AI SDK untuk Python dengan model
multimodal Gemini, lihat
Pengantar class multimodal di Vertex AI SDK untuk Python.
Python
Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Python API.
Node.js
Contoh ini menunjukkan skenario teks dengan satu fungsi dan satu perintah.
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Node.js Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Go
Contoh ini menunjukkan skenario teks dengan satu fungsi dan satu perintah.
Go
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Go Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
C#
Contoh ini menunjukkan skenario teks dengan satu fungsi dan satu perintah.
C#
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API C# Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
REST
Contoh ini menunjukkan skenario teks dengan tiga fungsi dan satu perintah.
Dalam contoh ini, Anda memanggil model AI generatif dua kali.
- Pada panggilan pertama, Anda memberikan prompt dan deklarasi fungsi ke model.
- Pada panggilan kedua, Anda memberikan respons API ke model.
Permintaan model pertama
Permintaan harus menentukan perintah di parameter text. Contoh ini menentukan
perintah berikut: "Bioskop mana di Yogyakarta yang menayangkan film Barbie?".
Permintaan juga harus menentukan alat (tools) dengan kumpulan deklarasi
fungsi (functionDeclarations). Deklarasi fungsi ini harus
ditentukan dalam format yang kompatibel dengan
skema OpenAPI. Contoh ini menentukan fungsi berikut:
find_moviesmenemukan judul film yang diputar di bioskop.find_theatresmenemukan bioskop berdasarkan lokasi.get_showtimesmenemukan waktu mulai film yang diputar di bioskop tertentu.
Untuk mempelajari parameter permintaan model lebih lanjut, lihat Gemini API.
Ganti my-project dengan nama project Google Cloud Anda.
Permintaan model pertama
PROJECT_ID=my-project
MODEL_ID=gemini-1.0-pro
API=streamGenerateContent
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": {
"role": "user",
"parts": {
"text": "Which theaters in Mountain View show the Barbie movie?"
}
},
"tools": [
{
"function_declarations": [
{
"name": "find_movies",
"description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"description": {
"type": "string",
"description": "Any kind of description including category or genre, title words, attributes, etc."
}
},
"required": [
"description"
]
}
},
{
"name": "find_theaters",
"description": "find theaters based on location and optionally movie title which are is currently playing in theaters",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "string",
"description": "Any movie title"
}
},
"required": [
"location"
]
}
},
{
"name": "get_showtimes",
"description": "Find the start times for movies playing in a specific theater",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "string",
"description": "Any movie title"
},
"theater": {
"type": "string",
"description": "Name of the theater"
},
"date": {
"type": "string",
"description": "Date for requested showtime"
}
},
"required": [
"location",
"movie",
"theater",
"date"
]
}
}
]
}
]
}'
Untuk perintah "Bioskop mana di Jakarta yang menayangkan film Barbie?", model
mungkin menampilkan fungsi find_theatres dengan parameter Barbie dan
Mountain View, CA.
Respons terhadap permintaan model pertama
[{
"candidates": [
{
"content": {
"parts": [
{
"functionCall": {
"name": "find_theaters",
"args": {
"movie": "Barbie",
"location": "Mountain View, CA"
}
}
}
]
},
"finishReason": "STOP",
"safetyRatings": [
{
"category": "HARM_CATEGORY_HARASSMENT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"probability": "NEGLIGIBLE"
}
]
}
],
"usageMetadata": {
"promptTokenCount": 9,
"totalTokenCount": 9
}
}]
Permintaan model kedua
Contoh ini menggunakan data sintetis, bukan memanggil API eksternal.
Ada dua hasil, masing-masing dengan dua parameter (name dan address):
name:AMC Mountain View 16,address:2000 W El Camino Real, Mountain View, CA 94040name:Regal Edwards 14,address:245 Castro St, Mountain View, CA 94040
Ganti my-project dengan nama project Google Cloud Anda.
Permintaan model kedua
PROJECT_ID=my-project
MODEL_ID=gemini-1.0-pro
API=streamGenerateContent
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Which theaters in Mountain View show the Barbie movie?"
}]
}, {
"role": "model",
"parts": [{
"functionCall": {
"name": "find_theaters",
"args": {
"location": "Mountain View, CA",
"movie": "Barbie"
}
}
}]
}, {
"parts": [{
"functionResponse": {
"name": "find_theaters",
"response": {
"name": "find_theaters",
"content": {
"movie": "Barbie",
"theaters": [{
"name": "AMC Mountain View 16",
"address": "2000 W El Camino Real, Mountain View, CA 94040"
}, {
"name": "Regal Edwards 14",
"address": "245 Castro St, Mountain View, CA 94040"
}]
}
}
}
}]
}],
"tools": [{
"functionDeclarations": [{
"name": "find_movies",
"description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "STRING",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"description": {
"type": "STRING",
"description": "Any kind of description including category or genre, title words, attributes, etc."
}
},
"required": ["description"]
}
}, {
"name": "find_theaters",
"description": "find theaters based on location and optionally movie title which are is currently playing in theaters",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "STRING",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "STRING",
"description": "Any movie title"
}
},
"required": ["location"]
}
}, {
"name": "get_showtimes",
"description": "Find the start times for movies playing in a specific theater",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "STRING",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "STRING",
"description": "Any movie title"
},
"theater": {
"type": "STRING",
"description": "Name of the theater"
},
"date": {
"type": "STRING",
"description": "Date for requested showtime"
}
},
"required": ["location", "movie", "theater", "date"]
}
}]
}]
}'
Respons model mungkin mirip dengan berikut ini:
Respons terhadap permintaan model kedua
{
"candidates": [
{
"content": {
"parts": [
{
"text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
}
]
}
}
],
"usageMetadata": {
"promptTokenCount": 9,
"candidatesTokenCount": 27,
"totalTokenCount": 36
}
}
Contoh chat
Anda dapat menggunakan panggilan fungsi untuk mendukung sesi chat. Sesi chat berguna dalam skenario percakapan bebas, tempat pengguna cenderung mengajukan pertanyaan lanjutan.
Jika Anda menggunakan panggilan fungsi dalam konteks sesi chat, sesi akan menyimpan konteks untuk Anda dan menyertakannya dalam setiap permintaan model. Vertex AI menyimpan histori interaksi di sisi klien.
Python
Contoh ini menunjukkan skenario chat dengan dua fungsi dan dua perintah berurutan. Class ini menggunakan class GenerativeModel dan metodenya. Untuk
mengetahui informasi selengkapnya tentang penggunaan Vertex AI SDK untuk Python dengan model multimodal, lihat
Pengantar class multimodal di Vertex AI SDK untuk Python.
Untuk mempelajari cara menginstal atau mengupdate Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Python API.
Java
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Java Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Go
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Go Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Node.js Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Contoh panggilan fungsi paralel
Untuk perintah seperti "Dapatkan detail cuaca di New Delhi dan San Francisco?", model dapat mengusulkan beberapa panggilan fungsi paralel. Untuk daftar model yang mendukung panggilan fungsi paralel, lihat Model yang didukung.
REST
Contoh ini menunjukkan skenario dengan satu fungsi get_current_weather.
Perintah pengguna adalah "Dapatkan detail cuaca di New Delhi dan San Francisco?". Model
ini mengusulkan dua panggilan fungsi get_current_weather paralel: satu dengan
parameter New Delhi dan yang lainnya dengan parameter San Francisco.
Untuk mempelajari parameter permintaan model lebih lanjut, lihat Gemini API.
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "New Delhi"
}
}
},
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "San Francisco"
}
}
}
]
},
...
}
],
...
}
Perintah berikut menunjukkan cara memberikan output fungsi ke model. Ganti my-project dengan nama project Google Cloud Anda.
Permintaan model
PROJECT_ID=my-project
MODEL_ID=gemini-1.5-pro-002
VERSION="v1"
LOCATION="us-central1"
ENDPOINT=${LOCATION}-aiplatform.googleapis.com
API="generateContent"
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://${ENDPOINT}/${VERSION}/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": [
{
"role": "user",
"parts": {
"text": "What is difference in temperature in New Delhi and San Francisco?"
}
},
{
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "New Delhi"
}
}
},
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "San Francisco"
}
}
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "get_current_weather",
"response": {
"temperature": 30.5,
"unit": "C"
}
}
},
{
"functionResponse": {
"name": "get_current_weather",
"response": {
"temperature": 20,
"unit": "C"
}
}
}
]
}
],
"tools": [
{
"function_declarations": [
{
"name": "get_current_weather",
"description": "Get the current weather in a specific location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
}
},
"required": [
"location"
]
}
}
]
}
]
}'
Respons bahasa alami yang dibuat oleh model mirip dengan berikut ini:
Respons model
[
{
"candidates": [
{
"content": {
"parts": [
{
"text": "The temperature in New Delhi is 30.5C and the temperature in San Francisco is 20C. The difference is 10.5C. \n"
}
]
},
"finishReason": "STOP",
...
}
]
...
}
]
Python
Go
Praktik terbaik untuk panggilan fungsi
Nama fungsi
Nama fungsi harus diawali dengan huruf atau garis bawah dan hanya berisi karakter a-z, A-Z, 0-9, garis bawah, titik, atau tanda hubung dengan panjang maksimum 64.
Deskripsi fungsi
Tulis deskripsi fungsi dengan jelas dan panjang. Misalnya, untuk fungsi book_flight_ticket:
- Berikut adalah contoh deskripsi fungsi yang baik:
book flight tickets after confirming users' specific requirements, such as time, departure, destination, party size and preferred airline - Berikut adalah contoh deskripsi fungsi yang buruk:
book flight ticket
Parameter fungsi
Nama parameter fungsi dan atribut bertingkat harus diawali dengan huruf atau garis bawah dan hanya berisi karakter a-z, A-Z, 0-9, atau garis bawah dengan panjang maksimum 64. Jangan gunakan titik (.), tanda hubung (-), atau karakter spasi dalam nama parameter fungsi dan atribut bertingkat.
Sebagai gantinya, gunakan karakter garis bawah (_) atau karakter lainnya.
Deskripsi
Tulis deskripsi parameter yang jelas dan panjang, termasuk detail seperti
format atau nilai pilihan Anda. Misalnya, untuk
fungsi book_flight_ticket:
- Berikut adalah contoh yang baik dari deskripsi parameter
departure:Use the 3 char airport code to represent the airport. For example, SJC or SFO. Don't use the city name. - Berikut adalah contoh buruk deskripsi parameter
departure:the departure airport
Jenis
Jika memungkinkan, gunakan parameter dengan jenis yang kuat untuk mengurangi halusinasi model. Misalnya, jika parameter value berasal dari kumpulan terbatas, tambahkan kolom enum, bukan memasukkan kumpulan nilai ke dalam deskripsi. Jika nilai parameter
selalu berupa bilangan bulat, tetapkan jenisnya ke integer, bukan number.
Petunjuk sistem
Saat menggunakan fungsi dengan parameter tanggal, waktu, atau lokasi, sertakan tanggal, waktu, atau informasi lokasi yang relevan saat ini (misalnya, kota dan negara) dalam petunjuk sistem. Hal ini memastikan model memiliki konteks yang diperlukan untuk memproses permintaan secara akurat, meskipun perintah pengguna tidak memiliki detail.
Perintah pengguna
Untuk hasil terbaik, tambahkan perintah pengguna dengan detail berikut:
- Konteks tambahan untuk model-misalnya,
You are a flight API assistant to help with searching flights based on user preferences. - Detail atau petunjuk tentang cara dan waktu menggunakan fungsi-misalnya,
Don't make assumptions on the departure or destination airports. Always use a future date for the departure or destination time. - Petunjuk untuk mengajukan pertanyaan klarifikasi jika kueri pengguna ambigu-misalnya,
Ask clarifying questions if not enough information is available.
Konfigurasi pembuatan
Untuk parameter suhu, gunakan 0 atau nilai rendah lainnya. Hal ini akan memerintahkan
model untuk menghasilkan hasil yang lebih meyakinkan dan mengurangi halusinasi.
Pemanggilan API
Jika model mengusulkan pemanggilan fungsi yang akan mengirim pesanan, memperbarui database, atau memiliki konsekuensi yang signifikan, validasikan panggilan fungsi dengan pengguna sebelum mengeksekusinya.
Harga
Harga untuk panggilan fungsi didasarkan pada jumlah karakter dalam input dan output teks. Untuk mempelajari lebih lanjut, lihat Harga Vertex AI.
Di sini, input teks (perintah) mengacu pada perintah pengguna untuk giliran percakapan saat ini, deklarasi fungsi untuk giliran percakapan saat ini, dan histori percakapan. Histori percakapan mencakup kueri, panggilan fungsi, dan respons fungsi dari putaran percakapan sebelumnya. Vertex AI memotong histori percakapan pada 32.000 karakter.
Output teks (respons) mengacu pada panggilan fungsi dan respons teks untuk giliran percakapan saat ini.
Langkah selanjutnya
Pelajari ekstensi Vertex AI.
Pelajari LangChain di Vertex AI.