הפעלת צינור לעיבוד נתונים לצורך הערכה

ב-Gemini Enterprise Agent Platform אתם יכולים להעריך את הביצועים של מודלים בסיסיים ושל מודלים מכווננים של AI גנרטיבי. המודלים נבדקים באמצעות קבוצת מדדים, בהשוואה לקבוצת נתונים להערכה שאתם מספקים. בדף הזה מוסבר איך פועלת הערכת מודלים שמבוססת על חישובים באמצעות שירות צינור עיבוד הנתונים להערכה, איך יוצרים ומעצבים את מערך הנתונים להערכה ואיך מבצעים את ההערכה באמצעות מסוף Google Cloud , ממשק ה-API של Agent Platform או Agent Platform SDK ל-Python.

איך פועלת הערכת מודלים שמבוססת על חישובים

כדי להעריך את הביצועים של מודל, קודם צריך ליצור מערך נתונים להערכה שמכיל הנחיות וזוגות של אמת קרקע (ground truth). בכל זוג, ההנחיה היא הקלט שרוצים להעריך, ואמת הקרקע היא התשובה האידיאלית להנחיה הזו. במהלך ההערכה, ההנחיה בכל זוג בקבוצת הנתונים להערכה מועברת למודל כדי להפיק פלט. הפלט שנוצר על ידי המודל ואמת הקרקע (ground truth) מקבוצת הנתונים להערכה משמשים לחישוב מדדי ההערכה.

סוג המדדים שמשמשים להערכה תלוי במשימה שאתם מעריכים. בטבלה הבאה מוצגות המשימות הנתמכות והמדדים שמשמשים להערכת כל משימה:

משימה מדד
סיווג ‫Micro-F1, ‏ Macro-F1, ‏ Per class F1
סיכום ROUGE-L
מענה לשאלות התאמה מדויקת
יצירת טקסט ‫BLEU, ‏ ROUGE-L

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

אפשר להעריך את המודלים הבאים:

  • ‫text-bison: גרסאות בסיסיות וגרסאות שעברו כוונון.

  • ‫Gemini: כל המשימות חוץ מסיווג.

הכנת מערך נתונים להערכה

קבוצת נתוני ההערכה שמשמשת להערכת המודל כוללת הנחיות וזוגות של אמת קרקע (ground truth) שתואמים למשימה שרוצים להעריך. קבוצת הנתונים חייבת לכלול לפחות זוג אחד של הנחיה ואמת קרקע (ground truth), ולפחות 10 זוגות כדי לקבל מדדים משמעותיים. ככל שתספקו יותר דוגמאות, כך התוצאות יהיו משמעותיות יותר.

פורמט של קבוצת נתונים

קבוצת הנתונים להערכה צריכה להיות בפורמט JSON Lines‏ (JSONL), שבו כל שורה מכילה הנחיה אחת וצמד אחד של אמת קרקע (ground truth) שמצוינים בשדות input_text ו-output_text, בהתאמה. השדה input_text מכיל את ההנחיה שרוצים להעריך, והשדה output_text מכיל את התשובה האידיאלית להנחיה.

אורך הטוקן המקסימלי של input_text הוא 8,192, ואורך הטוקן המקסימלי של output_text הוא 1,024.

העלאת מערך נתונים להערכה ל-Cloud Storage

אתם יכולים ליצור קטגוריה חדשה של Cloud Storage או להשתמש בקטגוריה קיימת כדי לאחסן את קובץ מערך הנתונים. הקטגוריה צריכה להיות באותו אזור שבו נמצא המודל.

אחרי שהקטגוריה מוכנה, מעלים אליה את קובץ מערך הנתונים.

הערכת המודל

אפשר להעריך מודלים באמצעות ה-API בארכיטקטורת REST או מסוף Google Cloud .

REST

כדי ליצור משימה להערכת מודל, שולחים בקשת POST באמצעות השיטה pipelineJobs.

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

  • ‫PROJECT_ID: הפרויקט ב- Google Cloud שמריץ את רכיבי צינור עיבוד הנתונים.
  • ‫PIPELINEJOB_DISPLAYNAME: השם המוצג של pipelineJob.
  • ‫LOCATION: האזור שבו יופעלו רכיבי צינור עיבוד הנתונים. כרגע יש תמיכה רק ב-us-central1.
  • ‫DATASET_URI: ה-URI של מערך הנתונים להפניה ב-Cloud Storage. אפשר לציין URI אחד או יותר. הפרמטר הזה תומך בתווים כלליים לחיפוש. מידע נוסף על הפרמטר הזה זמין במאמר InputConfig.
  • ‫OUTPUT_DIR: ה-URI של Cloud Storage שבו מאוחסן פלט ההערכה.
  • ‫MODEL_NAME: מציינים מודל של בעל תוכן דיגיטלי או משאב של מודל מכוונן, באופן הבא:
    • מודל בעל התוכן הדיגיטלי: publishers/google/models/MODEL@MODEL_VERSION

      לדוגמה: publishers/google/models/text-bison@002

    • מודל מכוונן: projects/PROJECT_NUMBER/locations/LOCATION/models/ENDPOINT_ID

      לדוגמה: projects/123456789012/locations/us-central1/models/1234567890123456789

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

  • ‫EVALUATION_TASK: המשימה שרוצים להעריך את המודל לפיה. משימת ההערכה מחשבת קבוצה של מדדים שרלוונטיים למשימה הספציפית הזו. הערכים הקבילים כוללים:
    • summarization
    • question-answering
    • text-generation
    • classification
  • ‫INSTANCES_FORMAT: הפורמט של מערך הנתונים. כרגע יש תמיכה רק ב-jsonl. מידע נוסף על הפרמטר הזה זמין במאמר InputConfig.
  • ‫PREDICTIONS_FORMAT: הפורמט של פלט ההערכה. כרגע יש תמיכה רק ב-jsonl. מידע נוסף על הפרמטר הזה זמין במאמר InputConfig.
  • ‫MACHINE_TYPE: (אופציונלי) סוג המכונה להרצת משימת ההערכה. ערך ברירת המחדל הוא e2-highmem-16. לרשימה של סוגי המכונות הנתמכים, ראו סוגי מכונות.
  • SERVICE_ACCOUNT: (אופציונלי) חשבון השירות שבו משתמשים כדי להריץ את משימת ההערכה. במאמר הגדרת חשבון שירות עם הרשאות פרטניות מוסבר איך יוצרים חשבון שירות בהתאמה אישית. אם לא מציינים סוכן שירות, המערכת משתמשת בסוכן השירות של Gemini Enterprise Agent Platform Custom Code.
  • ‫NETWORK: (אופציונלי) השם המלא של רשת Compute Engine שאליה רוצים לקשר את משימת ההערכה. הפורמט של שם הרשת הוא projects/PROJECT_NUMBER/global/networks/NETWORK_NAME. אם אתם מציינים את השדה הזה, אתם צריכים קישור רשתות VPC ב-Gemini Enterprise Agent Platform. אם לא מציינים רשת, משימת ההערכה לא מקושרת לאף רשת.
  • ‫KEY_NAME: (אופציונלי) השם של מפתח ההצפנה בניהול הלקוח (CMEK). אם מגדירים את האפשרות הזו, המשאבים שנוצרים על ידי משימת ההערכה מוצפנים באמצעות מפתח ההצפנה שסופק. הפורמט של שם המפתח הוא projects/PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY. המפתח צריך להיות באותו אזור שבו נמצאת משימת ההערכה.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/pipelineJobs

גוף בקשת JSON: 

{
  "displayName": "PIPELINEJOB_DISPLAYNAME",
  "runtimeConfig": {
    "gcsOutputDirectory": "gs://OUTPUT_DIR",
    "parameterValues": {
      "project": "PROJECT_ID",
      "location": "LOCATION",
      "batch_predict_gcs_source_uris": ["gs://DATASET_URI"],
      "batch_predict_gcs_destination_output_uri": "gs://OUTPUT_DIR",
      "model_name": "MODEL_NAME",
      "evaluation_task": "EVALUATION_TASK",
      "batch_predict_instances_format": "INSTANCES_FORMAT",
      "batch_predict_predictions_format: "PREDICTIONS_FORMAT",
      "machine_type": "MACHINE_TYPE",
      "service_account": "SERVICE_ACCOUNT",
      "network": "NETWORK",
      "encryption_spec_key_name": "KEY_NAME"
    }
  },
  "templateUri": "https://us-kfp.pkg.dev/vertex-evaluation/pipeline-templates/evaluation-llm-text-generation-pipeline/1.0.1"
}

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

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

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/pipelineJobs"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$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/pipelineJobs" | Select-Object -Expand Content

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

דוגמה לפקודת curl

PROJECT_ID=myproject
REGION=us-central1
MODEL_NAME=publishers/google/models/text-bison@002
TEST_DATASET_URI=gs://my-gcs-bucket-uri/dataset.jsonl
OUTPUT_DIR=gs://my-gcs-bucket-uri/output

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/pipelineJobs" -d \
$'{
  "displayName": "evaluation-llm-text-generation-pipeline",
  "runtimeConfig": {
    "gcsOutputDirectory": "'${OUTPUT_DIR}'",
    "parameterValues": {
      "project": "'${PROJECT_ID}'",
      "location": "'${REGION}'",
      "batch_predict_gcs_source_uris": ["'${TEST_DATASET_URI}'"],
      "batch_predict_gcs_destination_output_uri": "'${OUTPUT_DIR}'",
      "model_name": "'${MODEL_NAME}'",
    }
  },
  "templateUri": "https://us-kfp.pkg.dev/vertex-evaluation/pipeline-templates/evaluation-llm-text-generation-pipeline/1.0.1"
}'

Python

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

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

import os

import vertexai
from vertexai.evaluation import EvalResult, EvalTask

# TODO (Developer) Set environment variables
PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION_ID = os.getenv("LOCATION_ID", "us-central1")
MODEL_NAME = os.getenv("MODEL_NAME", "gemini-2.5-flash")


def evaluate_model() -> EvalResult:
    """Evaluate the performance of a generative AI model."""

    vertexai.init(project=PROJECT_ID, location=LOCATION_ID)

    # Dataset URI containing input prompts and ground truth labels
    dataset_uri = "gs://cloud-samples-data/ai-platform/generative_ai/llm_classification_bp_input_prompts_with_ground_truth.jsonl"

    metric_column_mapping = {"reference": "ground_truth"}

    # Define evaluation task
    eval_task = EvalTask(
        dataset=dataset_uri,
        metrics=["exact_match"],
        experiment="gemini-classification-eval",
        metric_column_mapping=metric_column_mapping,
    )

    # Define a prompt template so the generative Gemini model produces formatted labels
    prompt_template = (
        "Classify the following text into exactly one category from "
        "[nature, news, sports, health, startups]. Return only the category name:\n\n{prompt}"
    )

    # Evaluate using a modern Gemini model
    eval_result = eval_task.evaluate(
        model=MODEL_NAME,
        prompt_template=prompt_template,
    )

    print("=== SUMMARY METRICS ===")
    print(eval_result.summary_metrics)

    print("\n=== METRICS TABLE SAMPLE ===")
    print(eval_result.metrics_table.head())

    return eval_result

המסוף

כדי ליצור משימה להערכת מודל באמצעות מסוף Google Cloud :

  1. במסוף Google Cloud , נכנסים לדף Gemini Enterprise Agent Platform מרשם המודלים.

    כניסה ל-Gemini Enterprise Agent Platform Model Registry

  2. לוחצים על שם המודל שרוצים להעריך.
  3. בכרטיסייה Evaluate, לוחצים על Create evaluation ומגדירים את הפרטים הבאים:
    • מטרה: בוחרים את המשימה שרוצים להעריך.
    • Target column or field: (סיווג בלבד) מזינים את עמודת היעד לחיזוי. לדוגמה: ground_truth.
    • ‫Source path: מזינים או בוחרים את ה-URI של מערך הנתונים להערכה.
    • פורמט הפלט: מזינים את הפורמט של פלט ההערכה. יש תמיכה רק ב-jsonl.
    • ‫Cloud Storage path: מזינים או בוחרים את ה-URI שבו רוצים לשמור את פלט ההערכה.
    • שמות מחלקות: (סיווג בלבד) מזינים את רשימת שמות המחלקות האפשריים.
    • מספר צומתי המחשוב: מזינים את מספר צומתי המחשוב להרצת משימת ההערכה.
    • ‫Machine type: בוחרים את סוג המכונה שבה תשתמשו כדי להריץ את משימת ההערכה.
  4. לוחצים על התחלת ההערכה.

הצגת תוצאות הבדיקה

תוצאות ההערכה מופיעות בספריית הפלט של Cloud Storage שציינתם כשיצרתם את משימת ההערכה. שם הקובץ הוא evaluation_metrics.json.

במודלים מכווננים, אפשר גם לראות את תוצאות ההערכה במסוף Google Cloud :

  1. בקטע Agent Platform במסוף Google Cloud , נכנסים לדף Gemini Enterprise Agent Platform מרשם המודלים.

    מעבר אל Gemini Enterprise Agent Platform Model Registry

  2. לוחצים על שם המודל כדי לראות את מדדי ההערכה שלו.

  3. בכרטיסייה Evaluate, לוחצים על השם של הרצת ההערכה שרוצים לראות.

המאמרים הבאים