Label metadata kustom

Anda dapat menambahkan metadata kustom ke panggilan API seperti generateContent dan rawPredict menggunakan label. Halaman ini menjelaskan apa yang dimaksud dengan label, dan menunjukkan cara menggunakannya untuk mengelompokkan tagihan biaya 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 akan 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 satu project. Setiap kunci label dapat memiliki hingga 1.000 nilai unik di semua permintaan selama masa aktif akun penagihan terkait. Kunci label mungkin akan 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: Menambahkan 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 individu bagi tiap panggilan API. Masalah dari pendekatan ini adalah kunci mengacaukan katalog, meningkatkan waktu pemuatan secara signifikan selama kueri, dan membuat pemfilteran serta pelaporan panggilan API secara efektif menjadi sulit dilakukan.

Model yang didukung

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

Menambahkan label ke panggilan API model Google

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

cat > request.json << 'EOF'
{
  "contents": {
    "role": "ROLE",
    "parts": { "text": "PROMPT_TEXT" }
  },
  "labels": {
    "LABEL_KEY": "LABEL_VALUE"
  },
}
EOF

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"

@'
{
  "contents": {
    "role": "ROLE",
    "parts": { "text": "PROMPT_TEXT" }
  },
  "labels": {
    "LABEL_KEY": "LABEL_VALUE"
  },
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": Generative AI is a type of artificial intelligence (AI) that can **create new
            content**, like text, images, audio, video, and even code.
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.037841797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.06347656
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.053466797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.08496094
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08154297,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.033203125
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.071777344,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.083984375
        }
      ],
      "avgLogprobs": -0.40486351219383448
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 555,
    "totalTokenCount": 560
  }
}

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

Cloud de Confiance by S3NS produk melaporkan data penggunaan dan biaya ke proses Penagihan Cloud di berbagai interval. Akibatnya, Anda mungkin melihat jeda antara penggunaan Cloud de Confiance by S3NS layanan 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:

cat > request.json << 'EOF'
{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "user",
      "content": "What is Generative AI?"
    }
  ],
  "max_tokens": 1024,
  "stream": false
}
EOF

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"

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