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

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

1. הכנת הקלט

קלט של אחסון BigQuery

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

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

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

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

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

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

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

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

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

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

המשימה והטבלה צריכות להיות באותו אזור.

המסוף

  1. בקטע Agent Platform במסוף Google Cloud , נכנסים לדף Batch Inference.

    לדף Batch Inference

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

REST

כדי ליצור משימת הסקה באצווה, משתמשים ב-method‏ 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 ומסוף Google Cloud .

המסוף

  1. נכנסים לדף Batch Inference.

    לדף Batch Inference

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

REST

כדי לעקוב אחרי משימת הסקה באצווה, משתמשים ב-method‏ 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 כקלט למשימה החדשה.