Anda dapat menambahkan metadata kustom ke panggilan API generateContent
dan streamGenerateContent
menggunakan label. Halaman ini menjelaskan apa yang dimaksud dengan label, dan menunjukkan cara menggunakannya untuk mengelompokkan tagihan yang ditagih.
Apa itu label?
Label adalah pasangan nilai kunci yang dapat Anda tetapkan ke panggilan API generateContent
dan
streamGenerateContent
. Label membantu Anda mengatur panggilan ini dan mengelola biaya dalam skala besar, dengan perincian yang Anda butuhkan. Anda dapat melampirkan label ke
setiap panggilan, lalu memfilter panggilan berdasarkan labelnya. Informasi tentang label
diteruskan ke sistem penagihan yang memungkinkan Anda mengelompokkan tagihan biaya
berdasarkan label. Dengan laporan penagihan bawaan, Anda dapat memfilter dan mengelompokkan biaya berdasarkan label. Anda juga dapat menggunakan label untuk
membuat kueri
ekspor data penagihan.
Persyaratan untuk label
Label yang diterapkan ke panggilan API harus memenuhi persyaratan berikut:
- Setiap panggilan API dapat memiliki maksimal 64 label.
- Setiap label harus berupa pasangan nilai kunci.
- Kunci memiliki panjang minimum 1 karakter dan panjang maksimum 63 karakter, serta tidak boleh kosong. Nilai boleh kosong dan memiliki panjang maksimum 63 karakter.
- Kunci dan nilai hanya boleh berisi huruf kecil, karakter numerik, garis bawah, dan tanda pisah. Semua karakter harus menggunakan encoding UTF-8, dan boleh menggunakan karakter internasional. Kunci harus diawali dengan huruf kecil atau karakter internasional.
- Bagian kunci label harus unik dalam satu panggilan API. Namun, Anda dapat menggunakan kunci yang sama dengan beberapa panggilan.
Batasan ini berlaku untuk kunci dan nilai untuk setiap label, serta untuk setiap panggilan API yang memiliki label. Tidak ada batasan jumlah label yang dapat Anda terapkan di semua panggilan API dalam sebuah project.
Penggunaan label secara umum
Berikut adalah beberapa kasus penggunaan umum untuk label:
Label tim atau pusat biaya: Menambahkan label berdasarkan tim atau pusat biaya untuk membedakan panggilan API yang dimiliki oleh tim yang berbeda (misalnya,
team:research
danteam:analytics
). Anda dapat menggunakan jenis label ini untuk pencatatan atau penganggaran biaya.Label komponen: Misalnya,
component:redis
,component:frontend
,component:ingest
, dancomponent:dashboard
.Label lingkungan atau tahap: Misalnya,
environment:production
danenvironment:test
.Label kepemilikan: Digunakan untuk mengidentifikasi tim yang bertanggung jawab atas operasi, misalnya:
team:shopping-cart
.
Sebaiknya Anda tidak membuat label unik dalam jumlah besar, seperti untuk stempel waktu atau nilai individual bagi setiap panggilan API. Masalah dari pendekatan ini adalah ketika nilai sering berubah atau dengan kunci yang mengacaukan katalog, ini akan menyulitkan pemfilteran dan pelaporan panggilan API secara efektif.
Menambahkan label ke panggilan API
Untuk menambahkan label ke panggilan API generateContent
atau streamGenerateContent
, lakukan
hal berikut:
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
GENERATE_RESPONSE_METHOD
: Jenis respons yang ingin Anda hasilkan dari 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 sepenuhnya dibuat.
LOCATION
: Region untuk memproses permintaan. Opsi yang tersedia mencakup hal berikut:Klik untuk meluaskan sebagian daftar region yang tersedia
us-central1
us-west4
northamerica-northeast1
us-east4
us-west1
asia-northeast3
asia-southeast1
asia-northeast1
PROJECT_ID
: Project ID Anda.MODEL_ID
: ID model model multimodal yang ingin Anda gunakan. Beberapa opsi meliputi:gemini-1.0-pro-002
gemini-1.0-pro-vision-001
gemini-1.5-pro-002
gemini-1.5-flash
ROLE
: Peran dalam percakapan yang terkait dengan konten. Menentukan peran diperlukan bahkan dalam kasus penggunaan satu giliran. Nilai yang dapat diterima mencakup hal berikut:USER
: Menentukan konten yang dikirim oleh Anda.MODEL
: Menentukan respons model.
Petunjuk teks yang akan disertakan dalam perintah. JSONPROMPT_TEXT
LABEL_KEY
: Metadata label yang ingin Anda kaitkan dengan panggilan API ini.LABEL_VALUE
: Nilai label.
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json
.
Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:
cat > request.json << 'EOF' { "contents": { "role": "ROLE", "parts": { "text": "PROMPT_TEXT" } }, "labels": { "LABEL_KEY": "LABEL_VALUE" }, } EOF
Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:
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
.
Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:
@' { "contents": { "role": "ROLE", "parts": { "text": "PROMPT_TEXT" } }, "labels": { "LABEL_KEY": "LABEL_VALUE" }, } '@ | Out-File -FilePath request.json -Encoding utf8
Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:
$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 menerima respons JSON yang mirip dengan berikut ini.
Python
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
ProdukGoogle Cloud melaporkan data penggunaan dan biaya ke proses Penagihan Cloud pada interval yang berbeda-beda. Akibatnya, Anda mungkin melihat jeda antara penggunaan layananGoogle Cloud , dan saat penggunaan dan biaya dapat dilihat di Penagihan Cloud. Biasanya, biaya Anda tersedia dalam satu hari, tetapi terkadang dapat memerlukan waktu lebih dari 24 jam.