תוויות של מטא-נתונים בהתאמה אישית

אתם יכולים להוסיף מטא-נתונים מותאמים אישית לקריאות ל-API כמו generateContent,‏ interactions.create ו-rawPredict באמצעות תוויות. בדף הזה מוסבר מהן תוויות ואיך להשתמש בהן כדי לפרט את החיובים.

מידע על התוויות

תווית היא צמד של מפתח וערך שאפשר להקצות לקריאות ל-API כמו generateContent,‏ interactions.create ו-rawPredict. הם עוזרים לכם לארגן את הקריאות האלה ולנהל את השימוש והעלויות בקנה מידה נרחב, ברמת הפירוט שאתם צריכים. אפשר לצרף תווית לכל קריאה, ואז לסנן את הקריאות לפי התוויות שלהן. המידע על התוויות מועבר למערכת הרישום ביומן ולמערכת החיוב, כך שאתם יכולים לפרט את השימוש ואת החיובים לפי התוויות. בעזרת דוחות החיוב המובנים, אתם יכולים לסנן ולקבץ את העלויות לפי תוויות. אפשר גם להשתמש בתוויות כדי לשלוח שאילתות על ייצוא של נתוני חיוב. בסקירה הכללית של התוויות מוסבר איך משתמשים בתוויות אחרי שיוצרים אותן.

פלטפורמת Agent Platform תומכת בשני סוגים של תוויות: תוויות של גוף הבקשה, שמגיעות לחיוב ב-Cloud, ותוויות של כותרות, שמופיעות ביומני המטא-נתונים של בקשות ההסקה. בקטע הבא נשווה ביניהם.

בחירת תווית בהתאם לתרחיש לדוגמה

ב-Agent Platform יש שני מנגנוני תוויות. מגדירים אותם בצורה שונה, הם מגיעים ליעדים שונים והם מופיעים בשדות שונים ביומן המטא-נתונים של בקשת ההסקה. אפשר להשתמש באחת מהן או בשתיהן באותה בקשה, אם יש תמיכה בכך.

התוויות של גוף הבקשה פועלות באופן הבא:

  • מגדירים אותם בשדה labels של גוף הבקשה.
  • הם מגיעים ליומני המטא-נתונים של בקשות ההסקה והחיוב ב-Cloud.
  • הם מופיעים בשדה labels של רשומת היומן.
  • נתמך בתנועה בתשלום לפי שימוש.
  • במודלים של שותפים כמו Claude, תוויות הבקשה נשלחות בכותרת X-Vertex-AI-Labels במקום בגוף הבקשה. הם מגיעים לחיוב ב-Cloud אבל לא נכתבים ביומן המטא-נתונים של בקשות ההסקה.

תוויות הכותרת פועלות באופן הבא:

  • מגדירים אותם בכותרת הבקשה x-goog-agent-platform-observability-label-KEY.
  • הם מגיעים רק ליומני המטא-נתונים של בקשות ההסקה.
  • הם מופיעים בשדה jsonPayload.httpHeaders של רשומת היומן.
  • השיטות הנתמכות של ה-API: ‏generateContent ו-streamGenerateContent למודלים של Gemini, ו-rawPredict ו-streamRawPredict למודלים של Claude. אפשרויות הצריכה הנתמכות: הקצאת משאבים לפי התפוקה שנקבעה וכל אפשרות של תשלום לפי שימוש שהמודל מציע.

מאתרים כל תווית ברשומת היומן

בקשה אחת יכולה להכיל את שניהם. הבקשה הבאה מגדירה אחד מכל סוג:

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": "..."}]}]
}

שתי התוויות מופיעות בשדות שונים באותה רשומה ביומן:

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

שני סוגי התוויות נמצאים בשדות שונים, ולכן צריך לשלוח שאילתות שונות כדי לקבל אותם. ב-Logs Explorer:

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

ב-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

איך פועלות תוויות הכותרת

תוויות הכותרת הן חלק מרישום המטא-נתונים של בקשות ההסקה ביומן. כדי לתעד אותם, צריך להפעיל את יומני המטא-נתונים של בקשות ההסקה בפרויקט.

שולחים כותרת אחת לכל תווית, באמצעות הקידומת השמורה. הקידומת לא תלוית-רישיות:

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

לדוגמה:

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

כל כותרת מופיעה ברשומת היומן בקטע jsonPayload.httpHeaders, עם מפתח לפי שם הכותרת באותיות קטנות, והערך במערך values, כמו שמוצג בקטע איתור כל תווית ברשומת היומן.

פלטפורמת Agent Platform גם מתעדת קבוצה קטנה של כותרות משלה: x-vertex-ai-llm-request-type ו-x-vertex-ai-llm-shared-request-type. לא נאספות כותרות אחרות.

תוויות הכותרת פועלות באותו אופן ב-Gemini וב-Claude, והן משמשות לתיוג בקשות Claude ביומן המטא-נתונים של בקשות ההסקה.

מגבלות על תוויות של כותרות

  • בבקשה אחת אפשר לכתוב עד 32 כותרות. אם יש יותר סוכנים שעומדים בתנאים, פלטפורמת הסוכנים שומרת אותם בסדר אלפביתי עולה ומוותרת על השאר. ההשקה מתבצעת בשקט.
  • ערך כותרת שארוך מ-1,024 בייטים נחתך, והחיתוך מסומן בערך המאוחסן.
  • כותרות חוזרות עם אותו שם משולבות לרשומה אחת עם כמה ערכים.

כדי לשלוח שאילתות לגבי תוויות של כותרות, קראו את המאמר שימוש לפי תווית של כותרת בהתאמה אישית.

הדרישות לגבי תוויות

התוויות שמוחלות על קריאה ל-API צריכות לעמוד בדרישות הבאות:

  • כל קריאה ל-API יכולה לכלול עד 64 תוויות למודלים של Google ועד 32 תוויות למודלים של שותפים.
  • כל תווית חייבת להיות צמד מפתח/ערך.
  • המפתחות צריכים להיות באורך של תו אחד לפחות ו-63 תווים לכל היותר, והם לא יכולים להיות ריקים. הערכים יכולים להיות ריקים, והאורך המקסימלי שלהם הוא 63 תווים.
  • המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים. כל התווים צריכים להיות בקידוד UTF-8, ואפשר להשתמש בתווים בינלאומיים. המפתחות צריכים להתחיל באות קטנה או בתו בינלאומי.
  • החלק של המפתח בתווית חייב להיות ייחודי בקריאה אחת ל-API. עם זאת, אפשר להשתמש באותו מפתח בכמה קריאות.

המגבלות האלה חלות על המפתח והערך של כל תווית, ועל הקריאה הספציפית ל-API שכוללת תוויות. אין הגבלה על מספר מפתחות התוויות שאפשר ליצור בכל הקריאות ל-API בפרויקט. לכל מפתח תווית יכולים להיות עד 1,000 ערכים ייחודיים בכל הבקשות במהלך כל משך החיים של החשבון לחיוב שמשויך אליו. אם למפתח התווית יש יותר מ-1,000 ערכים ייחודיים, יכול להיות שהוא יוסר בלי הודעה מוקדמת.

שימושים נפוצים בתוויות

הנה כמה תרחישים נפוצים לשימוש בתוויות:

  • תוויות של צוות או מרכז עלות: הוספת תוויות על סמך צוות או מרכז עלות כדי להבחין בין קריאות ל-API שבבעלות צוותים שונים (לדוגמה, team:research ו-team:analytics). אפשר להשתמש בסוג הזה של תוויות לחשבונאות עלויות או לתקצוב.

  • תוויות של רכיבים: לדוגמה, component:redis,‏ component:frontend,‏ component:ingest ו-component:dashboard.

  • תוויות של סביבה או שלב: לדוגמה, environment:production ו-environment:test.

  • תוויות בעלות: משמשות לזיהוי הצוותים שאחראים על הפעולות, לדוגמה: team:shopping-cart.

  • ‫שיוך של ניצול לרעה על ידי משתמשי קצה (safety_identifier): צירוף מזהה משתמש אנונימי לכל משתמש (לדוגמה, safety_identifier:user_session_001) בקריאות ל-Gemini ול-Veo, כדי שהמשוב על המדיניות יתמקד במשתמשי קצה ספציפיים ולא בפרויקט כולו. במאמר העברת מזהה בטיחות של משתמש קצה בקריאות ל-API מפורטים כללי הפורמט ודוגמאות.

אל תיצרו מספר גדול של תוויות ייחודיות, כמו חותמות זמן או ערכים נפרדים לכל קריאה ל-API. יצירת מספר גדול של מפתחות ייחודיים יוצרת עומס בקטלוג, מגדילה משמעותית את זמני הטעינה במהלך שאילתות ומקשה על סינון יעיל ודיווח על קריאות ל-API.

מודלים נתמכים לתוויות של בקשות

מודלים שונים תומכים בתוויות של בקשות ובתוויות של כותרות. אפשר להוסיף תוויות לבקשות במודלים של Google ובחלק מהמודלים של השותפים. אם תוסיפו תוויות לבקשה של מודל שלא נתמך, תקבלו הודעת שגיאה. המודלים של Google מקבלים תוויות בקשה בשדה labels של גוף הבקשה. מודלים של שותפים מקבלים אותם בכותרת X-Vertex-AI-Labels.

המודלים של Google

המודלים של Google תומכים בתוויות בשיטות ה-API הבאות:

  • generateContent
  • streamGenerateContent
  • ‫predictLongRunning (יצירת סרטונים באמצעות Veo)
  • interactions.create

מודלים של השותפים

מודלים של שותפים תומכים בתוויות בשיטות ה-API הבאות:

  • rawPredict
  • streamRawPredict

המודלים הבאים של שותפים תומכים בתוויות:

התוויות מועברות לחיוב ב-Cloud רק כשהבקשה משתמשת באפשרות הצריכה PayGo. בבקשות שמשתמשות באפשרות הצריכה הקצאת משאבים לפי התפוקה שנקבעה, המערכת מתעלמת מהתוויות שנשלחות בבקשה.

מודלים נתמכים של תוויות כותרת

תוויות הכותרת נכתבות רק ביומן המטא-נתונים של בקשות ההסקה, ולכן הן פועלות במודלים ובשיטות שהיומן מתעד.

  • מודלים של Gemini: ‏generateContent ו-streamGenerateContent.
  • מודלים של Claude: ‏rawPredict ו-streamRawPredict.
  • אפשרויות צריכה: הקצאת משאבים לפי התפוקה שנקבעה וכל אפשרות של תשלום לפי שימוש שהמודל מציע.
  • אין תמיכה במודלים אחרים של שותפים, כולל Mistral AI. בקשה אליהם עם תוויות כותרת עדיין תצליח, אבל לא תיכתב רשומה ביומן, כך שהתוויות לא יתועדו בשום מקום.
  • תוויות של כותרות אף פעם לא מגיעות לחיוב ב-Cloud. כדי לפרט את החיובים, השתמשו בתוויות של בקשות.

הוספת תווית בקשה לקריאה ל-API של מודל של Google

כדי להוסיף תווית לקריאה ל-API מסוג generateContent,‏ streamGenerateContent או interactions.create:

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫GENERATE_RESPONSE_METHOD: סוג התשובה שרוצים שהמודל ייצור. בוחרים שיטה שקובעת איך התשובה של המודל תוחזר:
    • ‫streamGenerateContent: התשובה מועברת בסטרימינג בזמן שהיא נוצרת, כדי להפחית את תפיסת זמן האחזור אצל קהל אנושי.
    • ‫generateContent: התשובה מוחזרת אחרי שהיא נוצרת במלואה.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫PROJECT_ID: מזהה הפרויקט. .
  • ‫MODEL_ID: מזהה המודל שבו רוצים להשתמש.
  • ‫ROLE: התפקיד בשיחה שמשויך לתוכן. חובה לציין תפקיד גם בתרחישי שימוש של פנייה אחת. הערכים הקבילים כוללים:
    • USER: מציין תוכן שאתם שלחתם.
    • ‫MODEL: מציין את התשובה של המודל.
  • PROMPT_TEXT
    ההוראות בטקסט שצריך לכלול בהנחיה. JSON
  • ‫LABEL_KEY: המטא-נתונים של התווית שרוצים לשייך לקריאה הזו ל-API.
  • ‫LABEL_VALUE: הערך של התווית.

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל:

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

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST:

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

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל:

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

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST:

$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

אתם אמורים לקבל תגובת JSON שדומה לזו:

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python שמפורטות במאמר התחלה מהירה של Agent Platform באמצעות ספריות לקוח.

כדי לבצע אימות ב-Agent Platform, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.


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

מוצריGoogle Cloud מדווחים לתהליכי החיוב ב-Cloud על נתוני השימוש והעלויות במרווחי זמן שונים. לכן יכול להיות שלא תראו בחיוב ב-Cloud את נתוני השימוש והעלויות מייד אחרי השימוש בשירותיGoogle Cloud . בדרך כלל נתוני העלויות זמינים תוך יום, אבל לפעמים הם מדוּוחים אחרי יותר מ-24 שעות.

הוספת תווית בקשה לקריאה ל-API של מודל שותף

כדי להוסיף תווית לקריאה ל-API מסוג rawPredict או streamRawPredict:

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הערכים בשדות הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫MODEL_ID: מזהה המודל שבו רוצים להשתמש. לדוגמה, claude-opus-4-6.

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל:

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

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST:

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

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python שמפורטות במאמר התחלה מהירה של Agent Platform באמצעות ספריות לקוח.

כדי לבצע אימות ב-Agent Platform, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הערכים בשדות הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫MODEL_ID: מזהה המודל שבו רוצים להשתמש. לדוגמה, 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"))

הוספת תוויות של כותרות לקריאות ל-API

תוויות של כותרות לא דורשות שינויים בגוף הבקשה. מוסיפים כותרת x-goog-agent-platform-observability-label-KEY אחת לכל תווית לכל בקשה נתמכת. בדוגמאות הבאות מוצגים הבקשה והשדות שנוצרו ברשומה ביומן המטא-נתונים של בקשת ההסקה, מבקשות בדיקה בתאריך 14 באוקטובר 2026.

הוספת תוויות של כותרות לקריאה ל-API של מודל Gemini

שליחת תוויות כותרת באמצעות generateContent או streamGenerateContent. מחליפים את PROJECT_ID במזהה הפרויקט.

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?"}]}]}'

הרשומה ביומן מתעדת כל תווית בקטע jsonPayload.httpHeaders. תוויות הכותרת מתועדות גם בתנועה של הקצאת משאבים לפי התפוקה שנקבעה, שלא נתמכת בתוויות הבקשה:

{
  "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"}
}

הוספת תוויות של כותרות לקריאה ל-API של מודל Claude

שליחת תוויות כותרת באמצעות rawPredict או streamRawPredict. מחליפים את PROJECT_ID ואת MODEL_ID, לדוגמה 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}'

הרשומה ביומן מתעדת את התווית בקטע jsonPayload.httpHeaders, לצד מספר הטוקנים של 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}}
}

בקשה ל-Claude יכולה גם לכלול תוויות בקשה בכותרת X-Vertex-AI-Labels, כמו שמוסבר במאמר הוספת תווית בקשה לקריאה ל-API של מודל שותף. הם מגיעים לחיוב ב-Cloud אבל לא נכתבים ברשומת היומן.

תוויות של כותרות השאילתה

ב-Logs Explorer, מסננים לפי ערך אחד של תווית כותרת:

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

ב-Observability Analytics, מקבצים לפי תווית של כותרת באמצעות השאילתה Usage by custom header label בדף Log inference request metadata.