הסקת מסקנות באצווה מ-Cloud Storage

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

‫1. הכנת הקלט

הסקה באצווה למודלים של Gemini מקבלת כנתוני קלט קובץ אחד של שורות JSON‏ (JSONL) שמאוחסן ב-Cloud Storage. כל שורה בנתוני הקלט של האצווה היא בקשה למודל.

לדוגמה:

{"request":{"contents": [{"role": "user", "parts": [{"text": "What is the relation between the following video and image samples?"}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/video/animals.mp4", "mimeType": "video/mp4"}}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg", "mimeType": "image/jpeg"}}]}], "generationConfig": {"temperature": 0.9, "topP": 1, "maxOutputTokens": 256}}}

הורדת קובץ לדוגמה של בקשת Batch

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

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

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

המסוף

  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.5-flash, או שם נקודת הקצה המותאמת, לדוגמה projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, כאשר MODEL_ID הוא מזהה המודל של המודל המותאם.
  • ‫INPUT_URI: המיקום ב-Cloud Storage של קלט הסקת הנתונים באצווה בפורמט JSONL, למשל gs://bucketname/path/to/file.jsonl.
  • ‫OUTPUT_FORMAT: כדי להוציא פלט לקטגוריה של 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 צריך להיות זהה לאזור של משימת ההיסק של אצווה בפלטפורמת הסוכן. ב-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-cloud-storage-batch-inference-job",
  "model": "MODEL_PATH",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris" : "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. למידע נוסף, קראו את המאמר מעקב אחרי סטטוס המשימה.

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 = "gs://your-bucket/your-prefix"

# See the documentation: https://googleapis.github.io/python-genai/genai.html#genai.batches.Batches.create
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",
    # Source link: https://storage.cloud.google.com/cloud-samples-data/batch/prompt_for_batch_gemini_predict.jsonl
    src="gs://cloud-samples-data/batch/prompt_for_batch_gemini_predict.jsonl",
    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. מעקב אחרי הסטטוס וההתקדמות של המשימה

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

המסוף

  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

תיאורים של סטטוסי מצב המשימה מופיעים במאמר בנושא JobState.

4. אחזור פלט של אצווה

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

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

דוגמאות לפלט

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

{
  "status": "",
  "processed_time": "2024-11-01T18:13:16.826+00:00",
  "request": {
    "contents": [
      {
        "parts": [
          {
            "fileData": null,
            "text": "What is the relation between the following video and image samples?"
          },
          {
            "fileData": {
              "fileUri": "gs://cloud-samples-data/generative-ai/video/animals.mp4",
              "mimeType": "video/mp4"
            },
            "text": null
          },
          {
            "fileData": {
              "fileUri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg",
              "mimeType": "image/jpeg"
            },
            "text": null
          }
        ],
        "role": "user"
      }
    ]
  },
  "response": {
    "candidates": [
      {
        "avgLogprobs": -0.5782725546095107,
        "content": {
          "parts": [
            {
              "text": "This video shows a Google Photos marketing campaign where animals at the Los Angeles Zoo take self-portraits using a modified Google phone housed in a protective case. The image is unrelated."
            }
          ],
          "role": "model"
        },
        "finishReason": "STOP"
      }
    ],
    "modelVersion": "gemini-2.0-flash-001@default",
    "usageMetadata": {
      "candidatesTokenCount": 36,
      "promptTokenCount": 29180,
      "totalTokenCount": 29216
    }
  }
}

דוגמה לטעינה שנכשלה

{
  "status": "Bad Request: {\"error\": {\"code\": 400, \"message\": \"Please use a valid role: user, model.\", \"status\": \"INVALID_ARGUMENT\"}}",
  "processed_time": "2025-07-09T19:57:43.558+00:00",
  "request": {
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ],
        "role": "tester"
      }
    ]
  },
  "response": {}
}

המשך של משימה באצווה שלא הושלמה

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

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