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

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

מהן תוויות?

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

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

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

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

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

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

ריכזנו כאן כמה תרחישי שימוש נפוצים בתוויות:

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

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

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

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

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

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

האפשרות להוסיף תוויות לבקשה נתמכת במודלים של Google ובקבוצת משנה של מודלים של שותפים. אם מוסיפים תוויות לבקשה למודל שלא נתמך, הבקשה מחזירה שגיאה.

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

כדי להוסיף תווית לקריאה ל-API של generateContent או streamGenerateContent, צריך לבצע את הפעולות הבאות:

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 מדווחים לתהליכי החיוב ב-Cloud על נתוני השימוש והעלויות במרווחי זמן שונים. לכן יכול להיות שלא תראו בחיוב ב-Cloud את נתוני השימוש והעלויות מייד אחרי השימוש בשירותיCloud de Confiance by S3NS . בדרך כלל נתוני העלויות זמינים תוך יום, אבל לפעמים הם מדוּוחים אחרי יותר מ-24 שעות.

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

כדי להוסיף תווית לקריאה ל-API של rawPredict או streamRawPredict, צריך לבצע את הפעולות הבאות:

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