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

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

מהן תוויות?

תווית היא צמד מפתח/ערך שאפשר להקצות לקריאות ל-API כמו generateContent ו-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, כמו שמוצג בקטע חיפוש כל תווית ברשומת היומן.

פלטפורמת הסוכנים גם מתעדת קבוצה קטנה של כותרות משלה: 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.

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

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

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

המודלים של Google

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

  • generateContent
  • streamGenerateContent

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

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

  • rawPredict
  • streamRawPredict

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

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

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

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

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

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

כדי להוסיף תווית לקריאה ל-API של generateContent או streamGenerateContent:

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.