הסקת מסקנות (inference) באצווה ב-BigQuery

בדף הזה מוסבר איך לקבל מסקנות (inferences) באצווה באמצעות BigQuery.

1. הכנת הנתונים

קלט של אחסון BigQuery

לחשבון השירות צריכות להיות הרשאות מתאימות ב-BigQuery. כדי להעניק לחשבון השירות את התפקיד BigQuery User, משתמשים בפקודה gcloud iam service-accounts add-iam-policy-binding באופן הבא:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
        --role="roles/bigquery.user"

מחליפים את הערכים הבאים:

  • ‫PROJECT_ID: המזהה של הפרויקט שבו נוצר חשבון השירות.
  • ‫SERVICE_ACCOUNT_ID: המזהה של חשבון השירות.

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

התוכן בעמודה request צריך להיות במבנה של GenerateContentRequest.

בטבלת הקלט יכולים להיות טיפוסי נתונים בעמודות שאינם request. העמודות האלה יכולות להכיל סוגי נתונים של BigQuery, חוץ מהסוגים הבאים: array, ‏ struct, ‏ range, ‏ datetime ו-geography. המערכת מתעלמת מהעמודות האלה כשיוצרת תוכן, אבל הן נכללות בטבלת הפלט.

קלט לדוגמה (JSON) 
        
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a recipe for banana bread."
        }
      ]
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "You are a chef."
      }
    ]
  }
}

2. שליחת משימה באצווה

אפשר ליצור משימה באצווה דרך Cloud de Confiance המסוף, Google Gen AI SDK או API בארכיטקטורת REST.

העבודה והטבלה צריכות להיות באותו אזור.

המסוף

  1. בקטע Agent Platform במסוף Cloud de Confiance , עוברים לדף Batch Inference.

    כניסה לדף Batch Inference

  2. לוחצים על יצירה.

REST

כדי ליצור משימת הסקה באצווה, משתמשים בשיטה projects.locations.batchPredictionJobs.create.

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

  • ‫ENDPOINT_PREFIX: האזור של משאב המודל ואחריו -. לדוגמה, us-central1-. אם משתמשים בנקודת הקצה הגלובלית, משאירים את השדה ריק. הערה: אין תמיכה בנקודת הקצה הגלובלית להסקת מסקנות באצווה באמצעות מודלים שעברו התאמה.
  • ‫LOCATION: אזור שבו יש תמיכה במודלים של Gemini. אם משתמשים בנקודת הקצה הגלובלית, מזינים global.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫MODEL_PATH: שם המודל של בעל התוכן הדיגיטלי, לדוגמה, publishers/google/models/gemini-2.0-flash-001, או שם נקודת הקצה של המודל שעבר התאמה, לדוגמה, projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, כאשר MODEL_ID הוא מזהה המודל של המודל שעבר התאמה.
  • ‫INPUT_URI: הטבלה ב-BigQuery שבה נמצא קובץ הקלט של ההסקה באצווה, למשל bq://myproject.mydataset.input_table. מערך הנתונים צריך להיות באותו אזור שבו נמצאת משימת ההסקה באצווה. אין תמיכה במערכי נתונים בכמה אזורים.
  • ‫OUTPUT_FORMAT: כדי להגדיר פלט לטבלה ב-BigQuery, מציינים bigquery. כדי להגדיר פלט לקטגוריה של Cloud Storage, מציינים jsonl.
  • ‫DESTINATION: ב-BigQuery, מציינים bigqueryDestination. ב-Cloud Storage, מציינים gcsDestination.
  • ‫OUTPUT_URI_FIELD_NAME: ב-BigQuery, מציינים outputUri. ב-Cloud Storage, מציינים outputUriPrefix.
  • ‫OUTPUT_URI: ב-BigQuery, מציינים את מיקום הטבלה, למשל bq://myproject.mydataset.output_result. האזור של מערך הנתונים של הפלט ב-BigQuery צריך להיות זהה לאזור של משימת ההיסק של אצווה ב-Agent Platform. ב-Cloud Storage, מציינים את הקטגוריה ואת מיקום הספרייה, למשל gs://mybucket/path/to/output.

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

POST https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs

גוף בקשת JSON: 

{
  "displayName": "my-bigquery-batch-inference-job",
  "model": "MODEL_PATH",
  "inputConfig": {
    "instancesFormat": "bigquery",
    "bigquerySource":{
      "inputUri" : "INPUT_URI"
    }
  },
  "outputConfig": {
    "predictionsFormat": "OUTPUT_FORMAT",
    "DESTINATION": {
      "OUTPUT_URI_FIELD_NAME": "OUTPUT_URI"
    }
  }
}

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

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://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs"

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://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

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

התגובה כוללת מזהה ייחודי של עבודת האצווה. אפשר לדגום את הסטטוס של משימה באצווה באמצעות BATCH_JOB_ID. מידע נוסף מופיע במאמר בנושא מעקב אחרי סטטוס העבודה. הערה: אין תמיכה בדוחות של חשבון שירות בהתאמה אישית, התקדמות בזמן אמת, CMEK ו-VPCSC.

Python

התקנה

pip install --upgrade google-genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

import time

from google import genai
from google.genai.types import CreateBatchJobConfig, HttpOptions, JobState

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# TODO(developer): Update and un-comment below line
# output_uri = f"bq://your-project.your_dataset.your_table"

job = client.batches.create(
    # To use a tuned model, set the model param to your tuned model using the following format:
    # model="projects/{PROJECT_ID}/locations/{LOCATION}/models/{MODEL_ID}
    model="gemini-3.5-flash",
    src="bq://storage-samples.generative_ai.batch_requests_for_multimodal_input",
    config=CreateBatchJobConfig(dest=output_uri),
)
print(f"Job name: {job.name}")
print(f"Job state: {job.state}")
# Example response:
# Job name: projects/.../locations/.../batchPredictionJobs/9876453210000000000
# Job state: JOB_STATE_PENDING

# See the documentation: https://googleapis.github.io/python-genai/genai.html#genai.types.BatchJob
completed_states = {
    JobState.JOB_STATE_SUCCEEDED,
    JobState.JOB_STATE_FAILED,
    JobState.JOB_STATE_CANCELLED,
    JobState.JOB_STATE_PAUSED,
}

while job.state not in completed_states:
    time.sleep(30)
    job = client.batches.get(name=job.name)
    print(f"Job state: {job.state}")
# Example response:
# Job state: JOB_STATE_PENDING
# Job state: JOB_STATE_RUNNING
# Job state: JOB_STATE_RUNNING
# ...
# Job state: JOB_STATE_SUCCEEDED

3. מעקב אחרי הסטטוס וההתקדמות של העבודה

אחרי ששולחים את העבודה, אפשר לבדוק את הסטטוס של משימה באצווה באמצעות API, ‏ SDK ו Cloud de Confiance מסוף.

המסוף

  1. עוברים לדף Batch Inference.

    כניסה לדף Batch Inference

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

REST

כדי לעקוב אחרי משימת הסקת מסקנות באצווה, משתמשים בשיטה projects.locations.batchPredictionJobs.get ומסתכלים על השדה CompletionStats בתגובה.

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

  • ‫ENDPOINT_PREFIX: האזור של משאב המודל ואחריו -. לדוגמה, us-central1-. אם משתמשים בנקודת הקצה הגלובלית, משאירים את השדה ריק.
  • ‫LOCATION: אזור שבו יש תמיכה במודלים של Gemini. אם משתמשים בנקודת הקצה הגלובלית, מזינים global.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫BATCH_JOB_ID: מזהה העבודה של אצווה.

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

GET https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID

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

curl

מריצים את הפקודה הבאה: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID"

PowerShell

מריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID" | Select-Object -Expand Content

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

Python

התקנה

pip install --upgrade google-genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

    from google import genai
    from google.genai.types import HttpOptions

    client = genai.Client(http_options=HttpOptions(api_version="v1"))

    # Get the batch job
# Eg. batch_job_name = "projects/123456789012/locations/.../batchPredictionJobs/1234567890123456789"
    batch_job = client.batches.get(name=batch_job_name)

    print(f"Job state: {batch_job.state}")
    # Example response:
    # Job state: JOB_STATE_PENDING
    # Job state: JOB_STATE_RUNNING
    # Job state: JOB_STATE_SUCCEEDED

הסטטוס של משימה באצווה נתונה יכול להיות אחד מהבאים:

  • ‫JOB_STATE_PENDING: תור לקיבולת. הסטטוס של העבודה יכול להיות queue עד 72 שעות לפני שהוא משתנה ל-running.
  • ‫JOB_STATE_RUNNING: קובץ הקלט אומת בהצלחה והקבוצה מופעלת.
  • ‫JOB_STATE_SUCCEEDED: האצווה הושלמה והתוצאות מוכנות
  • ‫JOB_STATE_FAILED: קובץ הקלט נכשל בתהליך האימות, או שלא ניתן היה להשלים את התהליך תוך 24 שעות אחרי הכניסה למצב RUNNING.
  • ‫JOB_STATE_CANCELLING: מתבצע ביטול של החבילה.
  • ‫JOB_STATE_CANCELLED: האצווה בוטלה.

4. אחזור פלט של מקבץ

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

בשורות שבהן הפעולה הצליחה, תשובות המודל מאוחסנות בעמודה response. אחרת, פרטי השגיאה מאוחסנים בעמודה status לבדיקה נוספת.

פלט לדוגמה

דוגמה להצלחה

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "In a medium bowl, whisk together the flour, baking soda, baking powder."
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.14057204,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.14270912
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 396,
    "totalTokenCount": 404
  }
}

דוגמה לשיחה שנכשלה

  • בקשה

    {"contents":[{"parts":{"text":"Explain how AI works in a few words."},"role":"tester"}]}

  • תשובה

    Bad Request: {"error": {"code": 400, "message": "Please use a valid role: user, model.", "status": "INVALID_ARGUMENT"}}

חזרה למשימה באצווה שלא הושלמה

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

כדי להפעיל מחדש משימת אצווה, יוצרים משימת אצווה חדשה ומזינים את קובץ Cloud Storage או את פלט הטבלה ב-BigQuery כקלט למשימה החדשה.