BigQuery bqutil.procedure.bqml_generate_text 公開儲存程序可讓您疊代批次呼叫 ML.GENERATE_TEXT 函式,以便處理大型資料集,而不會超過端點配額和限制。即使函式在個別資料列上失敗,BigQuery 查詢工作仍會完成,因此大量要求可能會在輸出資料表中留下 RESOURCE EXHAUSTED 個可重試的錯誤。在本教學課程中,您將建立遠端模型並執行預存程序,反覆重試失敗的資料列,直到處理完公開新聞資料集中的所有記錄。
如要在 GitHub 中查看預存程序的原始碼,請參閱 bqml_generate_text.sqlx。如要進一步瞭解預存程序參數和用法,請參閱 README 檔案。
目標
- 建立 BigQuery 資料集。
- 在
gemini-3.5-flash-lite模型上建立 BigQuery ML 遠端模型。 - 執行
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.
您可以使用 Pricing Calculator,根據預測用量估算費用。
詳情請參閱 BigQuery 定價和 Agent Platform 定價。
事前準備
- 登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud,歡迎建立帳戶,親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額,用於執行、測試及部署工作負載。
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
啟用 BigQuery、BigQuery Connection 和 Agent Platform API (如有尚未啟用的 API)。
啟用 API 所需的角色
如要啟用 API,您必須具備
serviceusage.services.enable權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
必要的角色
如要取得完成本教學課程所需的權限,請要求管理員授予您下列 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
-
建立資料集
如要建立 BigQuery 資料集,請選取下列其中一個選項:
控制台
前往 Google Cloud 控制台的「BigQuery」頁面。
點選左側窗格中的 「Explorer」。

如果沒有看到左側窗格,請按一下 「Expand left pane」(展開左側窗格),開啟窗格。
在「Explorer」中展開專案,然後按一下「資料集」。
在「Datasets」(資料集) 頁面,按一下「Create dataset」(建立資料集)。
在「建立資料集」窗格中,執行下列操作:
在「Dataset ID」(資料集 ID) 中輸入
bqml_tutorial。在「資料位置」部分,選取「US」。
其餘預設設定則保持不變。
點選「建立資料集」。
bq
如要建立新的資料集,請使用 bq mk --dataset 指令。
建立名為
bqml_tutorial的資料集,並將資料位置設為US:bq mk --dataset \ --location=US \ --description "BigQuery ML tutorial dataset." \ bqml_tutorial
確認資料集已建立:
bq ls
API
使用定義的資料集資源呼叫 datasets.insert 方法:
{ "datasetReference": { "datasetId": "bqml_tutorial" } }
建立遠端模型
使用 CREATE MODEL 陳述式建立遠端模型,代表託管的 Agent Platform gemini-3.5-flash-lite 模型:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中執行下列陳述式:
CREATE OR REPLACE MODEL `bqml_tutorial.generate_text` REMOTE WITH CONNECTION DEFAULT OPTIONS (ENDPOINT = 'gemini-3.5-flash-lite');
查詢會在幾秒內完成,之後
generate_text模型就會顯示在「Explorer」窗格的bqml_tutorial資料集中。由於查詢使用CREATE MODEL陳述式建立模型,因此不會有查詢結果。
執行預存程序
使用 CALL 陳述式執行 bqutil.procedure.bqml_generate_text 預存程序。這個預存程序會使用 bqml_tutorial.generate_text 模型和 bigquery-public-data.bbc_news.fulltext 公開資料表,反覆呼叫 ML.GENERATE_TEXT 函式:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中執行下列陳述式:
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替換為專案 ID。預存程序會建立
bqml_tutorial.news_generated_text資料表,用於存放ML.GENERATE_TEXT函式的輸出內容。查詢執行完畢後,請確認
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訊息。在查詢編輯器中執行下列陳述式,檢查生成的文字結果範例:
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 收取費用,請刪除含有相關資源的專案,或者保留專案但刪除個別資源。
刪除專案
刪除 Google Cloud 專案:
gcloud projects delete PROJECT_ID
刪除個別資源
如要重複使用專案,請刪除您為本教學課程建立的資源:
控制台
前往 Google Cloud 控制台的「BigQuery」頁面。
刪除
bqml_tutorial資料集。刪除資料集也會一併刪除遠端模型和輸出資料表:在「Explorer」窗格中展開專案,然後點選「資料集」。
在「Datasets」(資料集) 清單中,點選
bqml_tutorial資料集。在詳細資料窗格中,按一下「 刪除」。
在「Delete dataset」(刪除資料集) 對話方塊中,按一下「Delete」(刪除)。
bq
刪除 bqml_tutorial 資料集、遠端模型和輸出表格:
bq rm --dataset --recursive bqml_tutorial
後續步驟
- 進一步瞭解
ML.GENERATE_TEXT函式和AI.GENERATE_TEXT函式。 - 進一步瞭解 BigQuery 的生成式 AI。
- 瞭解如何選擇文字生成函式。