טיפול בשגיאות שקשורות למכסה באמצעות קריאה חוזרת לפונקציה ML.GENERATE_TEXT

הפרוצדורה הציבורית המאוחסנת bqutil.procedure.bqml_generate_text ב-BigQuery מאפשרת לבצע איטרציה של קריאות באצווה לפונקציה ML.GENERATE_TEXT, כדי לעבד מערכי נתונים גדולים בלי לחרוג מהמכסות והמגבלות של נקודת הקצה. משימות של שאילתות ב-BigQuery מסתיימות גם אם הפונקציה נכשלת בשורות ספציפיות, לכן נפח בקשות גדול יכול להשאיר בטבלת הפלט RESOURCE EXHAUSTED שגיאות שאפשר לנסות שוב. במדריך הזה תיצרו מודל מרוחק ותריצו את הפרוצדורה המאוחסנת כדי לנסות שוב ושוב שורות שנכשלו, עד שכל הרשומות במערך נתונים ציבורי של חדשות יעובדו.

כדי לבדוק את קוד המקור של הפרוצדורה המאוחסנת ב-GitHub, עיינו בקובץ bqml_generate_text.sqlx. למידע נוסף על הפרמטרים והשימוש בפרוצדורה המאוחסנת, קראו את קובץ ה-README.

מטרות

• יוצרים מערך נתונים ב-BigQuery.
• יוצרים מודל מרוחק של BigQuery ML על מודל gemini-3.5-flash-lite.
• מריצים את הפרוצדורה המאוחסנת bqutil.procedure.bqml_generate_text כדי ליצור טקסט באופן איטרטיבי ממערך הנתונים שגלוי לכולם bigquery-public-data.bbc_news.fulltext.
• בודקים את תוצאות הטקסט שנוצר ומוודאים שאין יותר שגיאות מכסה שאפשר לנסות שוב.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

• BigQuery ML: You incur costs for the data that you process in BigQuery.
• Gemini Enterprise Agent Platform: You incur costs for calls to the Agent Platform model.

בעזרת מחשבון העלויות אתם יכולים להעריך את העלויות בהתאם לשימוש הצפוי.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

למידע נוסף, קראו את המאמרים התמחור ב-BigQuery והתמחור ב-Agent Platform.

לפני שמתחילים

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. מפעילים את ממשקי ה-API הבאים, אם הם עדיין לא מופעלים: BigQuery,‏ BigQuery Connection ו-Agent Platform API.

   התפקידים שנדרשים כדי להפעיל ממשקי API

   כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם אתם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, אתם יכולים לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

   הפעלת ממשקי ה-API

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות להשלמת המדריך, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM:

• יצירה ושימוש במערכי נתונים, בחיבורים ובמודלים של BigQuery: אדמין ב-BigQuery (roles/bigquery.admin) בפרויקט
• לתת הרשאות לחשבון השירות של החיבור: אדמין IAM של פרויקט (roles/resourcemanager.projectIamAdmin) בפרויקט

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

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

ההרשאות הנדרשות

כדי להשלים את המדריך הזה, נדרשות ההרשאות הבאות:

• יוצרים מערך נתונים: bigquery.datasets.create
• יצירה, הקצאה ושימוש בחיבור: bigquery.connections.*
• מגדירים את חיבור ברירת המחדל: bigquery.config.*
• מגדירים את ההרשאות של חשבון השירות:
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy
• יוצרים מודל ומריצים הסקה:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

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

יצירת קבוצת נתונים

כדי ליצור מערך נתונים ב-BigQuery, בוחרים אחת מהאפשרויות הבאות:

המסוף

1. נכנסים לדף BigQuery במסוף Google Cloud .

   כניסה ל-BigQuery

2. בחלונית הימנית, לוחצים על Explorer:

   

   אם החלונית הימנית לא מוצגת, לוחצים על Expand left pane כדי לפתוח אותה.

3. ב-Explorer, מרחיבים את הפרויקט ולוחצים על Datasets.

4. בדף Datasets, לוחצים על Create dataset.

5. בחלונית Create dataset:

   • בשדה Dataset ID, מזינים bqml_tutorial.

   • בקטע Data location (מיקום הנתונים), בוחרים באפשרות US (ארה"ב).

   משאירים את שאר הגדרות ברירת המחדל כמו שהן.

6. לוחצים על Create dataset.

BQ

כדי ליצור קבוצת נתונים חדשה, משתמשים בפקודה bq mk --dataset.

1. יוצרים מערך נתונים בשם bqml_tutorial ומגדירים את מיקום הנתונים ל-US:

   bq mk --dataset \
     --location=US \
     --description "BigQuery ML tutorial dataset." \
     bqml_tutorial

2. מוודאים שמערך הנתונים נוצר:

   bq ls

API

מפעילים את השיטה datasets.insert עם משאב של מערך נתונים מוגדר:

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

יצירת המודל המרוחק

משתמשים בהצהרת CREATE MODEL כדי ליצור מודל מרוחק שמייצג מודל gemini-3.5-flash-lite של Agent Platform שמתארח:

1. נכנסים לדף BigQuery במסוף Google Cloud .

   כניסה ל-BigQuery

2. בעורך השאילתות, מריצים את ההצהרה הבאה:

   CREATE OR REPLACE MODEL `bqml_tutorial.generate_text`
     REMOTE WITH CONNECTION DEFAULT
     OPTIONS (ENDPOINT = 'gemini-3.5-flash-lite');

   השאילתה מסתיימת תוך כמה שניות, ואז המודל generate_text מופיע במערך הנתונים bqml_tutorial בחלונית Explorer. מכיוון שהשאילתה משתמשת בהצהרה CREATE MODEL כדי ליצור מודל, אין תוצאות לשאילתה.

מריצים את התהליך המאוחסן

משתמשים בהצהרת CALL כדי להריץ את הפרוצדורה המאוחסנת bqutil.procedure.bqml_generate_text. הפרוצדורה המאוחסנת הזו חוזרת על קריאות לפונקציה ML.GENERATE_TEXT באמצעות המודל bqml_tutorial.generate_text והטבלה שגלויה לכולם bigquery-public-data.bbc_news.fulltext:

1. נכנסים לדף BigQuery במסוף Google Cloud .

   כניסה ל-BigQuery

2. בעורך השאילתות, מריצים את ההצהרה הבאה:

   CALL `bqutil.procedure.bqml_generate_text`(
       "bigquery-public-data.bbc_news.fulltext",          -- source table
       "PROJECT_ID.bqml_tutorial.news_generated_text",  -- destination table
       "PROJECT_ID.bqml_tutorial.generate_text",        -- model
       "body",                                            -- prompt column
       ["filename"],                                      -- key columns
       '{"flatten_json_output": true}'                    -- optional arguments
   );

   מחליפים את PROJECT_ID במזהה הפרויקט.

   התהליך המאוחסן יוצר את הטבלה bqml_tutorial.news_generated_text כדי להכיל את הפלט של הפונקציה ML.GENERATE_TEXT.

3. כשהשאילתה מסתיימת, מוודאים שאין שורות בטבלה bqml_tutorial.news_generated_text שמכילות שגיאה שניתן לנסות שוב. בעורך השאילתות, מריצים את ההצהרה הבאה:

   SELECT *
   FROM `bqml_tutorial.news_generated_text`
   WHERE ml_generate_text_status LIKE '%A retryable error occurred%';

   השאילתה מחזירה את ההודעה There is no data to display.

4. בעורך השאילתות, מריצים את ההצהרה הבאה כדי לבדוק דוגמה לתוצאות הטקסט הדינמי מבוסס-AI שנוצר:

   SELECT
     filename,
     prompt,
     ml_generate_text_llm_result,
     ml_generate_text_status
   FROM `bqml_tutorial.news_generated_text`
   LIMIT 3;

   הפלט אמור להיראות כך:

   +------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+
   | filename               | prompt                                   | ml_generate_text_llm_result                               | ml_generate_text_status |
   +------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+
   | bbc/tech/209.txt       | A 20-year-old US man is selling...       | It looks like you shared a news article about Andrew...   |                         |
   | bbc/business/375.txt   | South Korea's largest credit card...     | It looks like you shared a news article about the 2004... |                         |
   | bbc/sport/139.txt      | A brave defensive display, led by...     | It looks like you have shared a match report from a...    |                         |
   +------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+
   

הסרת המשאבים

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

מחיקת הפרויקט

זהירות: כשמוחקים פרויקט:

• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המשימות במדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.

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

כדי למחוק פרויקט ב- Google Cloud :

gcloud projects delete PROJECT_ID

מחיקת משאבים ספציפיים

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

המסוף

1. נכנסים לדף BigQuery במסוף Google Cloud .

   כניסה ל-BigQuery

2. מוחקים את מערך הנתונים bqml_tutorial. מחיקת מערך הנתונים מוחקת גם את המודל המרוחק ואת טבלת הפלט:

   1. בחלונית Explorer, מרחיבים את הפרויקט ולוחצים על Datasets.

   2. ברשימה Datasets, לוחצים על מערך הנתונים bqml_tutorial.

   3. בחלונית הפרטים, לוחצים על מחיקה.

   4. בתיבת הדו-שיח Delete dataset, לוחצים על Delete.

BQ

מוחקים את מערך הנתונים bqml_tutorial, את המודל המרוחק ואת טבלת הפלט:

bq rm --dataset --recursive bqml_tutorial

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

• מידע נוסף על הפונקציה ML.GENERATE_TEXT ועל הפונקציה AI.GENERATE_TEXT.
• מידע נוסף על AI גנרטיבי ב-BigQuery
• איך בוחרים פונקציה ליצירת טקסט