בדף הזה מוסבר איך לקבל הסקות באצווה באמצעות 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) |
|---|
|
2. שליחת משימה באצווה
אפשר ליצור משימה באצווה דרך מסוף Google Cloud , Google Gen AI SDK או API בארכיטקטורת REST.
המשימה והטבלה צריכות להיות באותו אזור.
המסוף
- בקטע Agent Platform במסוף Google Cloud , נכנסים לדף Batch Inference.
- לוחצים על יצירה.
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
3. מעקב אחרי הסטטוס וההתקדמות של המשימה
אחרי ששולחים את המשימה, אפשר לבדוק את הסטטוס שלה באמצעות ה-API, ה-SDK ומסוף Google Cloud .
המסוף
- נכנסים לדף Batch Inference.
- בוחרים את המשימה באצווה כדי לעקוב אחרי ההתקדמות שלה.
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
הסטטוס של משימה באצווה יכול להיות אחד מהבאים:
-
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 כקלט למשימה החדשה.