Label metadata kustom

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

Tentang label

Label adalah key-value pair yang dapat Anda tetapkan ke panggilan API seperti generateContent, interactions.create, dan rawPredict. Label membantu Anda mengatur panggilan ini dan mengelola penggunaan serta 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 logging dan penagihan, sehingga Anda dapat mengelompokkan penggunaan dan 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 pembuatan, lihat contoh dari ringkasan label.

Agent Platform mendukung dua jenis label: label isi permintaan, yang mencapai Penagihan Cloud, dan label header, yang muncul di log metadata permintaan inferensi. Bagian berikutnya akan membandingkan keduanya.

Memilih label berdasarkan kasus penggunaan Anda

Agent Platform menawarkan dua mekanisme label. Anda menetapkannya secara berbeda, keduanya mencapai tujuan yang berbeda, dan muncul di kolom yang berbeda dalam log metadata permintaan inferensi. Anda dapat menggunakan salah satu atau keduanya pada permintaan yang sama jika didukung.

Label isi permintaan berfungsi sebagai berikut:

  • Anda dapat menetapkannya di kolom labels pada isi permintaan.
  • Mereka menjangkau log metadata permintaan inferensi dan Penagihan Cloud.
  • Label tersebut muncul di kolom labels entri log.
  • Didukung pada traffic bayar sesuai penggunaan.
  • Untuk model partner seperti Claude, label permintaan dikirim di header X-Vertex-AI-Labels, bukan di isi permintaan. Permintaan tersebut mencapai Penagihan Cloud, tetapi tidak ditulis ke log metadata permintaan inferensi.

Label header berfungsi sebagai berikut:

  • Anda menetapkannya di header permintaan x-goog-agent-platform-observability-label-KEY.
  • Log tersebut hanya menjangkau log metadata permintaan inferensi.
  • Label tersebut muncul di kolom jsonPayload.httpHeaders entri log.
  • Metode API yang didukung: generateContent dan streamGenerateContent untuk model Gemini, serta rawPredict dan streamRawPredict untuk model Claude. Opsi konsumsi yang didukung: Throughput yang Disediakan dan setiap opsi bayar sesuai penggunaan yang ditawarkan model.

Menemukan setiap label dalam entri log

Satu permintaan dapat membawa keduanya. Permintaan berikut menetapkan masing-masing satu:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-pro:generateContent
x-goog-agent-platform-observability-label-team: payments

{
  "labels": {"cost_center": "cc-1234"},
  "contents": [{"role": "user", "parts": [{"text": "..."}]}]
}

Kedua label tersebut berada di kolom yang berbeda dalam entri log yang sama:

{
  "labels": {
    "gen_ai.operation.name": "generate_content",
    "cost_center": "cc-1234"
  },
  "jsonPayload": {
    "httpHeaders": {
      "x-goog-agent-platform-observability-label-team": {
        "values": ["payments"]
      }
    }
  }
}

Kedua jenis label menempati kolom yang berbeda, sehingga Anda mengkuerinya secara berbeda. Di Logs Explorer:

labels.cost_center="cc-1234"
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"

Di Observability Analytics:

JSON_VALUE(labels.cost_center) AS cost_center,
JSON_VALUE(json_payload.httpHeaders
  ["x-goog-agent-platform-observability-label-team"].values[0]) AS team

Cara kerja label header

Label header adalah bagian dari logging metadata permintaan inferensi. Untuk mencatatnya, aktifkan log metadata permintaan inferensi untuk project.

Kirim satu header per label, menggunakan awalan yang dicadangkan. Awalan tidak peka huruf besar/kecil:

x-goog-agent-platform-observability-label-KEY: VALUE

Contoh:

x-goog-agent-platform-observability-label-team: payments
x-goog-agent-platform-observability-label-application: invoice-ocr

Setiap header muncul di entri log di bagian jsonPayload.httpHeaders, yang diberi kunci oleh nama header dalam huruf kecil, dengan nilai dalam array values, seperti yang ditunjukkan dalam Menemukan setiap label di entri log.

Agent Platform juga menangkap sekumpulan kecil headernya sendiri: x-vertex-ai-llm-request-type dan x-vertex-ai-llm-shared-request-type. Tidak ada header lain yang diambil.

Label header berfungsi dengan cara yang sama untuk Gemini dan Claude, dan label ini adalah cara Anda memberi label pada permintaan Claude di log metadata permintaan inferensi.

Batas untuk label header

  • Satu permintaan menulis maksimal 32 header. Jika ada lebih banyak yang memenuhi syarat, Agent Platform akan menyimpannya dalam urutan abjad menaik dan menghapus sisanya. Penurunan ini tidak bersuara.
  • Nilai header yang lebih panjang dari 1.024 byte akan dipangkas, dan pemangkasan tersebut ditandai dalam nilai yang disimpan.
  • Header berulang dengan nama yang sama digabungkan menjadi satu entri dengan beberapa nilai.

Untuk membuat kueri label header, lihat Penggunaan menurut label header kustom.

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 panggilan API individual yang memiliki label. Tidak ada batasan jumlah kunci label yang dapat Anda buat di semua panggilan API dalam satu project. Setiap kunci label dapat memiliki hingga 1.000 nilai unik di semua permintaan selama masa aktif akun penagihan terkait. Kunci label mungkin dihapus tanpa pemberitahuan jika ada lebih dari 1.000 nilai unik yang terkait 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.

  • Atribusi penyalahgunaan oleh pengguna akhir (safety_identifier): Lampirkan ID pengguna yang dianonimkan (misalnya, safety_identifier:user_session_001) pada panggilan Gemini dan Veo sehingga masukan kebijakan menargetkan pengguna akhir tertentu, bukan seluruh project Anda. Untuk mengetahui aturan dan contoh pemformatan, lihat Meneruskan ID keamanan pengguna akhir dalam panggilan API.

Hindari membuat label unik dalam jumlah besar, seperti untuk stempel waktu atau nilai individual bagi setiap panggilan API. Membuat kunci unik dalam jumlah besar akan mengacaukan katalog, meningkatkan waktu pemuatan secara signifikan selama kueri, dan menyulitkan pemfilteran dan pelaporan panggilan API secara efektif.

Model yang didukung untuk label permintaan

Label permintaan dan label header didukung pada model yang berbeda. Kemampuan untuk menambahkan label permintaan ke permintaan didukung untuk model Google dan subset model partner. Jika Anda menambahkan label permintaan ke permintaan untuk model yang tidak didukung, permintaan tersebut akan menghasilkan error. Model Google mengambil label permintaan di kolom labels pada isi permintaan. Model partner menerimanya di header X-Vertex-AI-Labels.

Model Google

Model Google mendukung label pada metode API berikut:

  • generateContent
  • streamGenerateContent
  • predictLongRunning (Pembuatan video Veo)
  • interactions.create

Model partner

Model partner mendukung label pada metode API berikut:

  • rawPredict
  • streamRawPredict

Model partner berikut mendukung label:

Label hanya diteruskan ke Penagihan Cloud jika permintaan menggunakan opsi konsumsi PayGo. Permintaan yang menggunakan opsi konsumsi Throughput yang Disediakan akan mengabaikan label yang dikirim dalam permintaan tanpa memberikan pemberitahuan.

Model yang didukung untuk label header

Label header hanya ditulis ke log metadata permintaan inferensi, sehingga label tersebut berfungsi pada model dan metode yang dicatat log.

  • Model Gemini: generateContent dan streamGenerateContent.
  • Model Claude: rawPredict dan streamRawPredict.
  • Opsi konsumsi: Throughput yang Disediakan dan setiap opsi bayar sesuai penggunaan yang ditawarkan model.
  • Model partner lainnya, termasuk Mistral AI, tidak didukung. Permintaan ke layanan tersebut dengan label header masih berhasil, tetapi tidak ada entri log yang ditulis, sehingga label tidak dicatat di mana pun.
  • Label header tidak pernah sampai ke Penagihan Cloud. Untuk mengelompokkan biaya yang ditagih, gunakan label permintaan.

Menambahkan label permintaan ke panggilan API model Google

Untuk menambahkan label ke panggilan API generateContent, streamGenerateContent, atau interactions.create, lakukan hal berikut:

REST

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 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.
    • 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 os

from google import genai

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = os.getenv("LOCATION_ID")
GEMINI_MODEL = os.getenv("GEMINI_MODEL_ID", "gemini-2.5-flash")


def generate_content() -> genai.types.GenerateContentResponse:

    genai_client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)

    labels = {
        "environment": "testing",
        "feature": "genai",
        "model": "gemini",
    }

    config = genai.types.GenerateContentConfig(temperature=0.4, labels=labels)

    response = genai_client.models.generate_content(
        model=GEMINI_MODEL, contents="What is Generative AI?", config=config
    )

    print(response.text)
    return response

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 permintaan 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"))

Menambahkan label header ke panggilan API

Label header tidak memerlukan perubahan isi permintaan. Tambahkan satu header x-goog-agent-platform-observability-label-KEY per label ke permintaan yang didukung. Contoh berikut menunjukkan permintaan dan kolom yang dihasilkan dari entri log metadata permintaan inferensi, dari permintaan pengujian pada 14-10-2026.

Menambahkan label header ke panggilan API model Gemini

Kirim label header dengan generateContent atau streamGenerateContent. Ganti PROJECT_ID dengan project ID Anda.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-agent-platform-observability-label-team: payments" \
  -H "x-goog-agent-platform-observability-label-application: invoice-ocr" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "What is Generative AI?"}]}]}'

Entri log mencatat setiap label di bagian jsonPayload.httpHeaders. Label header juga dicatat pada traffic Throughput yang Disediakan, yang tidak didukung oleh label permintaan:

{
  "method": "GENERATE_CONTENT",
  "trafficType": "PROVISIONED_THROUGHPUT",
  "httpHeaders": {
    "x-goog-agent-platform-observability-label-application": {"values": ["invoice-ocr"]},
    "x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
  },
  "generateContentDetails": {"usageMetadata": {"promptTokenCount": 6, "candidatesTokenCount": 1, "totalTokenCount": 7}},
  "provisionedThroughput": {"accountingResource": "projects/PROJECT_NUMBER", "ptChargedInputTokenCount": "6", "ptChargedOutputTokenCount": "9"}
}

Menambahkan label header ke panggilan API model Claude

Kirim label header dengan rawPredict atau streamRawPredict. Ganti PROJECT_ID dan MODEL_ID, misalnya claude-opus-4-6.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-agent-platform-observability-label-team: payments" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL_ID:rawPredict" \
  -d '{"anthropic_version": "vertex-2023-10-16", "messages": [{"role": "user", "content": "What is Generative AI?"}], "max_tokens": 256}'

Entri log mencatat label di bagian jsonPayload.httpHeaders, di samping jumlah token Claude:

{
  "method": "RAW_PREDICT",
  "trafficType": "ON_DEMAND",
  "httpHeaders": {
    "x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
  },
  "rawPredictDetails": {"usageMetadata": {"input_tokens": 17, "output_tokens": 16, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}
}

Permintaan Claude juga dapat membawa label permintaan di header X-Vertex-AI-Labels, seperti yang ditunjukkan dalam Menambahkan label permintaan ke panggilan API model partner. Data tersebut akan sampai ke Penagihan Cloud, tetapi tidak ditulis ke entri log.

Label header kueri

Di Logs Explorer, filter satu nilai label header:

jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"

Di Observability Analytics, kelompokkan menurut label header dengan kueri Usage by custom header label di halaman Log inference request metadata.