Anda dapat menjamin bahwa output yang dihasilkan model selalu mematuhi skema tertentu sehingga Anda menerima respons yang diformat secara konsisten. Misalnya, Anda mungkin memiliki skema data yang sudah ada yang digunakan untuk tugas lain. Jika Anda membuat model mengikuti skema yang sama, Anda dapat langsung mengekstrak data dari output model tanpa pemrosesan pasca-pemrosesan.
Untuk menentukan struktur output model, tentukan skema respons, yang berfungsi seperti blueprint untuk respons model. Saat Anda mengirimkan perintah dan menyertakan skema respons, respons model akan selalu mengikuti skema yang Anda tentukan.
Anda dapat mengontrol output yang dihasilkan saat menggunakan model berikut:
- Model Gemini:
Klik untuk meluaskan model yang didukung
- Gemini Robotics ER 2
- Gemini 4 Hydrogen
- Gemini 4 Carbon untuk cyber
- Gemini 4 Carbon
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Flash Cyber
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
- Gemini 3 Flash
- Gemini 2.5 Pro
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash
Model terbuka:
Untuk Model Terbuka, ikuti panduan pengguna ini.
Contoh kasus penggunaan
Salah satu kasus penggunaan untuk menerapkan response schema adalah memastikan bahwa respons model menghasilkan JSON yang valid dan sesuai dengan skema Anda. Output model generatif dapat memiliki tingkat variabilitas tertentu, sehingga menyertakan skema respons akan memastikan Anda selalu menerima JSON yang valid. Akibatnya, tugas downstream Anda dapat dengan andal mengharapkan input JSON yang valid dari respons yang dihasilkan.
Contoh lainnya adalah membatasi cara model merespons. Misalnya, Anda dapat
meminta model menganotasi teks dengan label yang ditentukan pengguna, bukan dengan label yang
dihasilkan model. Batasan ini berguna jika Anda mengharapkan kumpulan label tertentu seperti positive atau negative dan tidak ingin menerima campuran label lain yang mungkin dihasilkan model seperti good, positive, negative, atau bad.
Pertimbangan
Pertimbangan berikut membahas potensi batasan jika Anda berencana menggunakan skema respons:
- Anda harus menggunakan API untuk menentukan dan menggunakan skema respons. Tidak ada dukungan konsol.
- Ukuran skema respons Anda diperhitungkan dalam batas token input.
Hanya format output tertentu yang didukung, seperti
application/jsonatautext/x.enum. Terkait output JSON:- Menetapkan
response_mime_typekeapplication/jsontanpa menentukanresponse_schemahanya berfungsi sebagai petunjuk yang kuat dan memiliki risiko kecil menghasilkan JSON yang salah format. - Untuk memastikan objek JSON 100% valid, permintaan harus menyertakan
response_schemadanresponse_mime_typeyang ditetapkan keapplication/json. - Sebagai praktik terbaik, jika kasus penggunaan Anda mencegah Anda menentukan skema sebelumnya, terapkan validator JSON sisi klien dengan mekanisme percobaan ulang.
- Menetapkan
Output terstruktur mendukung subset referensi skema Gemini Enterprise Agent Platform. Untuk mengetahui informasi selengkapnya, lihat Kolom skema yang didukung.
Skema yang kompleks dapat menyebabkan error
InvalidArgument: 400. Kompleksitas mungkin berasal dari nama properti yang panjang, batas panjang array yang panjang, enum dengan banyak nilai, objek dengan banyak properti opsional, atau kombinasi dari faktor-faktor ini.Jika Anda mendapatkan error ini dengan skema yang valid, lakukan satu atau beberapa perubahan berikut untuk mengatasi error:
- Persingkat nama properti atau nama enum.
- Meratakan array bertingkat.
- Kurangi jumlah properti dengan batasan, seperti angka dengan batas minimum dan maksimum.
- Kurangi jumlah properti dengan batasan yang kompleks, seperti
properti dengan format yang kompleks seperti
date-time. - Kurangi jumlah properti opsional.
- Kurangi jumlah nilai yang valid untuk enum.
Kolom skema yang didukung
Anda dapat menentukan response_schema yang menjelaskan format output.
Model akan menghasilkan respons yang sesuai dengan skema yang diberikan. Saat menggunakan output terstruktur, model akan menghasilkan output dalam urutan yang sama dengan kunci dalam skema.
Kolom berikut dari skema Agent Platform didukung. Jika Anda menggunakan kolom yang tidak didukung, Agent Platform masih dapat menangani permintaan Anda, tetapi akan mengabaikan kolom tersebut:
anyOfenum: hanya elemenstringyang tidak kosong yang didukung. Menyertakan string kosong ("") akan menampilkan error400 INVALID_ARGUMENT(cannot be empty).formatitemsmaximummaxItemsminimumminItemsnullableproperties: kunci properti harus berupa string yang tidak kosong. Menyertakan kunci string kosong ("") akan menampilkan error400 INVALID_ARGUMENT(key cannot be empty).descriptionpropertyOrdering*required
* propertyOrdering khusus untuk output terstruktur dan bukan bagian dari skema Agent Platform. Kolom ini menentukan urutan pembuatan properti. Properti yang tercantum harus unik dan harus berupa kunci yang valid dalam kamus properties.
Saat Anda menentukan skema, model tidak sepenuhnya mengikuti urutan properti yang Anda tentukan di kolom properties. Untuk menerapkan urutan tertentu untuk pembuatan properti, gunakan kolom propertyOrdering. Properti yang tercantum dalam propertyOrdering dibuat terlebih dahulu, dalam urutan yang ditentukan, diikuti dengan properti lainnya.
Jika Anda menggunakan Python SDK, pengurutan properti default akan mengikuti urutan yang ditentukan dalam skema Anda. Untuk semua kasus lainnya, properti dibuat menurut abjad dengan properti wajib dikelompokkan terlebih dahulu, diikuti dengan properti opsional.
Untuk kolom format, Agent Platform mendukung nilai berikut:
date, date-time, duration, dan time. Deskripsi dan format setiap nilai dijelaskan dalam OpenAPI Initiative Registry.
Sebelum memulai
Tentukan skema respons untuk menentukan struktur output model, nama kolom, dan jenis data yang diharapkan untuk setiap kolom. Hanya gunakan kolom yang didukung seperti yang tercantum di bagian Pertimbangan. Semua kolom lainnya akan diabaikan.
Sertakan response schema Anda sebagai bagian dari kolom responseSchema saja. Jangan
menduplikasi skema dalam perintah input Anda. Jika Anda melakukannya, output yang dihasilkan mungkin
berkualitas lebih rendah.
Untuk contoh skema, lihat bagian Contoh skema dan respons model.
Perilaku model dan skema respons
Saat membuat respons, model menggunakan nama dan deskripsi kolom dari skema yang disediakan. Gunakan struktur yang jelas dan nama kolom yang tidak ambigu agar
maksud Anda jelas. Sebagai praktik terbaik, gunakan kolom description
di dalam properti skema untuk menentukan tujuan setiap kolom.
Secara default, kolom bersifat opsional, yang berarti model dapat mengisi kolom atau melewatinya. Anda dapat menetapkan kolom sebagai wajib diisi untuk memaksa model memberikan nilai. Jika tidak ada konteks yang memadai dalam perintah input terkait, model akan menghasilkan respons terutama berdasarkan data yang digunakan untuk melatihnya.
Jika Anda tidak melihat hasil yang diharapkan, mulailah dengan melakukan iterasi pada deskripsi dalam skema. Jika Anda tidak dapat menangkap nuansa skema dalam deskripsi skema saja, Anda dapat membahas skema dalam perintah dengan mengikuti panduan berikut:
Hanya tentukan skema di objek skema. Jangan juga menentukan skema dalam perintah. Melakukan keduanya dapat mengurangi performa.
Hindari membahas skema dalam perintah (selain "ikuti skema yang disediakan" atau yang serupa) kecuali jika diperlukan. Hal ini memudahkan pemeliharaan; jika skema Anda perlu diubah, Anda hanya perlu memperbarui skema, bukan memperbarui perintah dan skema.
Jika Anda harus membahas skema dalam perintah (untuk memberikan contoh, atau untuk memberikan petunjuk yang sangat mendetail yang dapat menyebabkan nilai
descriptionyang panjang dalam skema), ikuti urutan kolom yang exact seperti dalam skema yang disediakan. Mengacaukan urutan kolom dalam skema yang disediakan versus perintah dapat menyebabkan error output.
Mengirim perintah dengan skema respons
Secara default, semua kolom bersifat opsional, yang berarti model dapat menghasilkan respons untuk suatu kolom. Untuk memaksa model agar selalu menghasilkan respons terhadap suatu kolom, tetapkan kolom tersebut sebagai wajib diisi.
Python
Instal
pip install --upgrade google-genai
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
Pelajari cara menginstal atau mengupdate Go.
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
Instal
npm install @google/genai
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
Pelajari cara menginstal atau mengupdate Java.
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
REST
GenerateContent API
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- GENERATE_RESPONSE_METHOD: Jenis respons yang Anda inginkan untuk dihasilkan oleh model.
Pilih metode yang menghasilkan cara Anda ingin respons model ditampilkan:
streamGenerateContent: Respons di-streaming saat dibuat untuk mengurangi persepsi latensi bagi audiens manusia.generateContent: Respons ditampilkan setelah dibuat sepenuhnya.
- LOCATION: Region untuk memproses permintaan.
- PROJECT_ID: Project ID Anda.
- MODEL_ID: ID model dari model multimodal yang ingin Anda gunakan.
- ROLE:
Peran dalam percakapan yang terkait dengan konten. Menentukan peran diperlukan bahkan dalam
kasus penggunaan singleturn.
Nilai yang dapat diterima mencakup hal berikut:
USER: Menentukan konten yang dikirim oleh Anda.
- TEXT: Petunjuk teks yang akan disertakan dalam perintah.
- RESPONSE_MIME_TYPE: Jenis format teks kandidat yang dihasilkan. Untuk mengetahui daftar nilai yang didukung, lihat
parameter
responseMimeTypedi Gemini API. - RESPONSE_SCHEMA: Skema yang harus diikuti model saat membuat respons. Praktik terbaiknya adalah menggunakan kolom
descriptionuntuk menjelaskan tujuan skema dan propertinya. Untuk mengetahui informasi selengkapnya, lihat referensi Skema.
Metode HTTP dan URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD
Meminta isi JSON:
{
"contents": {
"role": "user",
"parts": {
"text": "List a few popular cookie recipes."
}
},
"generation_config": {
"maxOutputTokens": 2048,
"responseMimeType": "application/json",
"responseSchema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
"description": "The name of the cookie recipe."
}
},
"required": ["recipe_name"]
}
}
}
}
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json,
dan jalankan perintah berikut:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"
PowerShell
Simpan isi permintaan dalam file bernama request.json,
dan jalankan perintah berikut:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content
Anda akan melihat respons JSON yang mirip seperti berikut:
Interactions API
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- MODEL_ID: ID model dari model multimodal yang ingin Anda gunakan.
Metode HTTP dan URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
Meminta isi JSON:
{
"model": "MODEL_ID",
"input": [
{
"type": "user_input",
"content": [
{
"type": "text",
"text": "List a few popular cookie recipes."
}
]
}
],
"generation_config": {
"max_output_tokens": 2048
},
"response_format": {
"type": "text",
"mime_type": "application/json",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
"description": "The name of the cookie recipe."
}
},
"required": ["recipe_name"]
}
}
}
}
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json,
dan jalankan perintah berikut:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions"
PowerShell
Simpan isi permintaan dalam file bernama request.json,
dan jalankan perintah berikut:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" | Select-Object -Expand Content
Anda akan melihat respons JSON yang mirip seperti berikut:
Contoh skema untuk output JSON
Bagian berikut menunjukkan berbagai contoh perintah dan skema respons. Contoh respons model juga disertakan setelah setiap contoh kode.
- Memperkirakan cuaca untuk setiap hari dalam seminggu dalam array
- Mengklasifikasikan produk dengan enum yang ditentukan dengan baik
Memperkirakan cuaca untuk setiap hari dalam seminggu
Contoh berikut menghasilkan objek forecast untuk setiap hari
dalam seminggu yang menyertakan array properti seperti perkiraan
suhu dan tingkat kelembapan untuk hari tersebut. Beberapa properti ditetapkan ke nullable
sehingga model dapat menampilkan nilai null jika tidak memiliki cukup konteks untuk
menghasilkan respons yang bermakna. Strategi ini membantu mengurangi halusinasi.
Python
Instal
pip install --upgrade google-genai
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
Pelajari cara menginstal atau mengupdate Go.
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
Instal
npm install @google/genai
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
Pelajari cara menginstal atau mengupdate Java.
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Mengklasifikasikan produk
Contoh berikut menyertakan enum tempat model harus mengklasifikasikan jenis dan kondisi objek dari daftar nilai yang diberikan.
Python
Instal
pip install --upgrade google-genai
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
Pelajari cara menginstal atau mengupdate Go.
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
Instal
npm install @google/genai
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
Pelajari cara menginstal atau mengupdate Java.
Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.
Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True