Label metadata kustom

Anda dapat menambahkan metadata kustom ke panggilan API seperti generateContent dan rawPredict menggunakan label. Halaman ini menjelaskan apa itu label, dan menunjukkan cara menggunakannya untuk mengelompokkan tagihan Anda.

Apa yang dimaksud dengan label?

Label adalah pasangan nilai kunci yang dapat Anda tetapkan ke panggilan API seperti generateContent dan rawPredict. 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, sehingga Anda dapat 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. Untuk mengetahui informasi tentang cara menggunakan label setelah dibuat, lihat contoh dari ringkasan label.

Persyaratan untuk label

Label yang diterapkan ke panggilan API harus memenuhi persyaratan berikut:

  • Setiap panggilan API dapat memiliki hingga 64 label untuk model Google dan hingga 32 label untuk model partner.
  • 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 kunci label yang dapat Anda buat di semua panggilan API dalam sebuah project. Setiap kunci label dapat memiliki hingga 1.000 nilai unik di semua permintaan selama masa aktif akun penagihan terkait. Kunci label dapat dihapus tanpa pemberitahuan jika lebih dari 1.000 nilai unik dikaitkan dengannya.

Penggunaan label secara umum

Berikut adalah beberapa kasus penggunaan umum untuk label:

  • Label tim atau pusat biaya: Tambahkan label berdasarkan tim atau pusat biaya untuk membedakan panggilan API yang dimiliki oleh tim yang berbeda (misalnya, team:research dan team:analytics). Anda dapat menggunakan jenis label ini untuk pencatatan atau penganggaran biaya.

  • Label komponen: Misalnya, component:redis, component:frontend, component:ingest, dan component:dashboard.

  • Label lingkungan atau tahap: Misalnya, environment:production dan environment: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 kunci mengacaukan katalog, meningkatkan waktu pemuatan secara signifikan selama kueri, dan menyulitkan pemfilteran dan pelaporan panggilan API secara efektif.

Model yang didukung

Kemampuan untuk menambahkan label ke permintaan didukung untuk model Google dan subkumpulan model partner. Jika Anda menambahkan label ke permintaan untuk model yang tidak didukung, permintaan akan menghasilkan error.

Model Google

Model Google mendukung label pada metode API berikut.

  • generateContent
  • streamGenerateContent

Model partner

Model partner mendukung label pada metode API berikut.

  • rawPredict
  • streamRawPredict

Model partner berikut mendukung label.

Label hanya diteruskan ke Penagihan Cloud saat permintaan menggunakan opsi konsumsi PayGo. Permintaan yang menggunakan opsi konsumsi Throughput yang Disediakan akan mengabaikan label yang dikirim dalam permintaan secara diam-diam.

Menambahkan label ke panggilan API Google Model

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 Anda inginkan dari model. Pilih metode yang menghasilkan cara yang Anda inginkan untuk menampilkan respons model:
    • 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 meliputi:

    Klik untuk meluaskan daftar sebagian wilayah yang tersedia

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: [ID project](/resource-manager/docs/creating-managing-projects#identifiers) Anda. .
  • MODEL_ID: ID model yang ingin Anda gunakan.
  • 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.
  • PROMPT_TEXT
     Petunjuk teks yang akan disertakan dalam perintah. JSON
  • 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 Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

import vertexai

from vertexai.generative_models import GenerativeModel

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel("gemini-2.0-flash-001")

prompt = "What is Generative AI?"
response = model.generate_content(
    prompt,
    # Example Labels
    labels={
        "team": "research",
        "component": "frontend",
        "environment": "production",
    },
)

print(response.text)
# Example response:
# Generative AI is a type of Artificial Intelligence focused on **creating new content** based on existing data.

ProdukGoogle Cloud melaporkan data penggunaan dan biaya ke proses Penagihan Cloud pada berbagai interval. Akibatnya, Anda mungkin melihat jeda antara penggunaan layananGoogle Cloud dengan 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.

Menambahkan label ke panggilan API model partner

Untuk menambahkan label ke panggilan API rawPredict atau streamRawPredict, lakukan hal berikut:

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda.
  • MODEL_ID: ID model yang ingin Anda gunakan. Contoh, claude-opus-4-6.

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'
{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "user",
      "content": "What is Generative AI?"
    }
  ],
  "max_tokens": 1024,
  "stream": false
}
EOF

Kemudian jalankan perintah berikut untuk mengirim permintaan REST Anda:

REQUEST_LABELS=$(echo -n '{"team": "research", "component": "frontend"}' | base64 --wrap 0)

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Vertex-AI-Labels: ${REQUEST_LABELS}" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @request.json \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL_ID:rawPredict"

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda.
  • MODEL_ID: ID model yang ingin Anda gunakan. Contoh, claude-opus-4-6.
import base64
import json

from google.cloud.aiplatform import aiplatform_v1
from google.api import httpbody_pb2

project_id = "PROJECT_ID"
model_id = "MODEL_ID"
request_body = {
    "anthropic_version": "vertex-2023-10-16",
    "messages": [{
        "role": "user",
        "content": [{"type": "text", "text": "What is Generative AI?"}]
    }],
    "max_tokens": 256,
    "stream": True,
}

# Encode labels to base64 for the X-Vertex-AI-Labels header
labels = {
    "team": "research",
    "component": "frontend",
    "environment": "production",
}
labels_json = json.dumps(labels).encode("utf-8")
vertex_header_value = base64.b64encode(labels_json)

endpoint_id=f"projects/{project_id}/locations/global/publishers/anthropic/models/{model_id}"
client = aiplatform_v1.PredictionServiceClient()
responses = client.stream_raw_predict(
    request=aiplatform_v1.StreamRawPredictRequest(
        endpoint=endpoint_id,
        http_body=httpbody_pb2.HttpBody(
            data=json.dumps(request_body).encode("utf-8"),
            content_type="application/json",
        ),
    ),
    metadata=[("x-vertex-ai-labels", vertex_header_value)],
)

for response in responses:
  print(response.data.decode("utf-8"))