反覆呼叫 ML.GENERATE_TEXT，處理配額錯誤

本教學課程說明如何使用 BigQuery bqutil.procedure.bqml_generate_text 公開預存程序，逐一呼叫 ML.GENERATE_TEXT 函式。反覆呼叫函式可解決因超出函式配額和限制而發生的任何可重試錯誤。

如要查看 GitHub 中儲存程序的原始碼，請參閱 bqml_generate_text.sqlx。bqutil.procedure.bqml_generate_text如要進一步瞭解預存程序參數和用法，請參閱 README 檔案。

本教學課程會逐步引導您完成下列工作：

• 透過 gemini-2.5-flash 模型建立遠端模型。
• 透過對 ML.GENERATE_TEXT 函式的呼叫進行疊代，使用遠端模型和 bigquery-public-data.bbc_news.fulltext 公開資料表與 bqutil.procedure.bqml_generate_text 預存程序。

所需權限

如要執行本教學課程，您需要下列 Identity and Access Management (IAM) 角色：

• 建立及使用 BigQuery 資料集、連線和模型：BigQuery 管理員 (roles/bigquery.admin)。
• 將權限授予連線的服務帳戶：專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)。

這些預先定義的角色具備執行本文所述工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

• 建立資料集：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

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

費用

在本文件中，您會使用下列 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.

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

如要進一步瞭解 BigQuery 定價，請參閱 BigQuery 定價。

如要進一步瞭解 Agent Platform 計價方式，請參閱這篇文章。

事前準備

1. 在 Google Cloud 控制台的專案選擇器頁面中，選取或建立 Google Cloud 專案。

   選取或建立專案所需的角色

   • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
   • 建立專案：如要建立專案，您需要「專案建立者」角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。
   注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。

   前往專案選取器

2. 確認專案已啟用計費功能 Google Cloud 。

3. 啟用 BigQuery、BigQuery Connection 和 Agent Platform API。

   啟用 API 時所需的角色

   如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

   啟用 API

建立資料集

建立 BigQuery 資料集來儲存模型和範例資料：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」BigQuery頁面

2. 在「Explorer」窗格中，按一下專案名稱。

3. 依序點按 「View actions」(查看動作)>「Create dataset」(建立資料集)。

4. 在「建立資料集」頁面中，執行下列操作：

   1. 在「Dataset ID」(資料集 ID) 中輸入 sample。

   2. 針對「Location type」(位置類型) 選取「Multi-region」(多區域)，然後選取「US (multiple regions in United States)」(us (多個美國區域))。

   3. 其餘設定請保留預設狀態，然後按一下「建立資料集」。

建立文字生成模型

建立遠端模型，代表託管的 Agent Platform 模型：gemini-2.5-flash

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中執行下列陳述式：

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

   查詢作業會在幾秒內完成，完成後，generate_text模型會顯示在「Explorer」(探索工具) 窗格的 sample 資料集中。由於查詢使用 CREATE MODEL 陳述式建立模型，因此沒有查詢結果。

執行預存程序

執行 bqutil.procedure.bqml_generate_text 預存程序，該程序會使用 sample.generate_text 模型和 bigquery-public-data.bbc_news.fulltext 公開資料表，反覆呼叫 ML.GENERATE_TEXT 函式：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中執行下列陳述式：

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

   將 PROJECT_ID 替換為您在本教學課程中使用的專案 ID。

   預存程序會建立 sample.news_generated_text 資料表，用來存放 ML.GENERATE_TEXT 函式的輸出內容。

3. 查詢執行完畢後，請確認 sample.news_generated_text 資料表中沒有包含可重試錯誤的資料列。在查詢編輯器中執行下列陳述式：

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

   查詢會傳回訊息 No data to display。

清除所用資源

注意：刪除專案會造成以下結果：

• 專案中的所有內容都會遭到刪除。如果使用現有專案來進行本文中的任務，刪除專案將一併移除當中已完成的其他任務'。
• 自訂專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。

如果打算探索多種架構、教學課程或快速入門導覽課程，重複使用專案可避免超出專案配額限制。

1. 前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。

   前往「Manage resources」(管理資源)

2. 在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
3. 在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。