本頁面由 Cloud Translation API 翻譯而成。

使用 AI.GENERATE_TABLE 函式產生結構化資料

本文說明如何使用 Gemini 模型生成結構化資料，然後使用 SQL 結構定義設定模型回覆的格式。

方法是完成下列工作：

透過任何正式推出或搶先體驗的 Gemini 模型，建立 BigQuery ML 遠端模型。
使用 AI.GENERATE_TABLE 函式，根據標準表格中的資料產生結構化資料。

必要的角色

如要建立遠端模型並使用 AI.GENERATE_TABLE 函式，您需要下列 Identity and Access Management (IAM) 角色：

建立及使用 BigQuery 資料集、資料表和模型：專案中的 BigQuery 資料編輯者 (roles/bigquery.dataEditor)。
建立、委派及使用 BigQuery 連線：專案的 BigQuery 連線管理員 (roles/bigquery.connectionsAdmin)。

如果沒有設定預設連線，您可以在執行 CREATE MODEL 陳述式時建立並設定連線。如要執行這項操作，您必須具備專案的 BigQuery 管理員角色 (roles/bigquery.admin)。詳情請參閱「設定預設連線」。
將權限授予連線的服務帳戶：在包含 Vertex AI 端點的專案中，授予專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 權限。這是您透過將模型名稱指定為端點所建立遠端模型的目前專案。這是您透過指定網址做為端點所建立遠端模型的網址中，所識別的專案。
建立 BigQuery 工作：專案中的 BigQuery 工作使用者 (roles/bigquery.jobUser)。

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

所需權限

建立資料集：bigquery.datasets.create
建立、委派及使用連線： bigquery.connections.*
設定服務帳戶權限： resourcemanager.projects.getIamPolicy 和 resourcemanager.projects.setIamPolicy
建立模型並執行推論：
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata
查詢資料表資料：bigquery.tables.getData

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

事前準備

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

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
Make sure that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Enable the APIs

建立資料集

建立 BigQuery 資料集來存放資源：

控制台

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

前往 BigQuery 頁面
在「Explorer」窗格中，按一下專案名稱。
依序點按「View actions」(查看動作) >「Create dataset」(建立資料集)。
在「建立資料集」頁面中，執行下列操作：
- 在「Dataset ID」(資料集 ID) 部分，輸入資料集的名稱。
- 在「位置類型」部分，選取資料集的位置。
- 點選「建立資料集」。

bq

如要建立新的資料集，請使用 bq mk 指令搭配 --location 旗標：
```
bq --location=LOCATION mk -d DATASET_ID
```
更改下列內容：
- LOCATION：資料集的位置。
- DATASET_ID 是您要建立的資料集 ID。
確認資料集已建立完成：
```
bq ls
```

建立連線

如果已設定預設連線，或您具備 BigQuery 管理員角色，則可略過這個步驟。

建立供遠端模型使用的Cloud 資源連線，並取得連線的服務帳戶。在與上一步建立的資料集相同的位置中建立連線。

選取下列選項之一：

主控台

前往「BigQuery」頁面

前往 BigQuery
在「Explorer」窗格中，按一下「新增資料」：

「新增資料」對話方塊隨即開啟。
在「依條件篩選」窗格的「資料來源類型」部分，選取「商務應用程式」。

或者，您也可以在「Search for data sources」(搜尋資料來源) 欄位中輸入 Vertex AI。
在「精選資料來源」部分，按一下「Vertex AI」。
按一下「Vertex AI Models: BigQuery Federation」解決方案資訊卡。
在「連線類型」清單中，選取「Vertex AI 遠端模型、遠端函式和 BigLake (Cloud 資源)」。
在「連線 ID」欄位中，輸入連線名稱。
點選「建立連線」。
按一下「前往連線」。
在「連線資訊」窗格中，複製服務帳戶 ID，以供後續步驟使用。

bq

在指令列環境中建立連線：
```
bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID
```
--project_id 參數會覆寫預設專案。

更改下列內容：
- REGION：您的連線區域
- PROJECT_ID：您的 Google Cloud 專案 ID
- CONNECTION_ID：連線的 ID
建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並將其與連線建立關聯。

疑難排解：如果收到下列連線錯誤訊息，請更新 Google Cloud SDK：
```
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
```

擷取並複製服務帳戶 ID，以供後續步驟使用：

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

輸出結果會與下列內容相似：

name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Terraform

使用 google_bigquery_connection 資源。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會在 US 地區中建立名為 my_cloud_resource_connection 的 Cloud 資源連線：


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

啟動 Cloud Shell。
設定要套用 Terraform 設定的預設 Google Cloud 專案。

每項專案只需要執行一次這個指令，且可以在任何目錄中執行。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

將範例程式碼複製到新建立的 main.tf。

視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您使用這個方法。
查看並修改範例參數，套用至您的環境。
儲存變更。
初始化 Terraform。每個目錄只需執行一次這項操作。
```
terraform init
```
如要使用最新版 Google 供應商，請加入 -upgrade 選項：
```
terraform init -upgrade
```

套用變更

檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：
```
terraform plan
```
視需要修正設定。
執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：
```
terraform apply
```
等待 Terraform 顯示「Apply complete!」訊息。
開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

授予服務帳戶存取權

為連線的服務帳戶授予 Vertex AI 使用者角色。

如果您打算在建立遠端模型時將端點指定為網址 (例如 endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-2.5-flash')，請在網址指定的專案中授予這個角色。

如果您打算在建立遠端模型時使用模型名稱指定端點 (例如 endpoint = 'gemini-2.5-flash')，請在您打算建立遠端模型的專案中授予這個角色。

在其他專案中授予角色會導致錯誤 bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource。

如要授予角色，請按照下列步驟操作：

主控台

前往「IAM & Admin」(IAM 與管理) 頁面。

前往「IAM & Admin」(IAM 與管理)
按一下「新增」圖示。

「新增主體」對話方塊隨即開啟。
在「新增主體」欄位，輸入先前複製的服務帳戶 ID。
在「請選擇角色」欄位中，依序選取「Vertex AI」和「Vertex AI 使用者」。
按一下 [儲存]。

gcloud

使用 gcloud projects add-iam-policy-binding 指令。

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

取代下列項目：

PROJECT_NUMBER：您的專案編號
MEMBER：您先前複製的服務帳戶 ID

建立 BigQuery ML 遠端模型

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

前往 BigQuery
使用 SQL 編輯器建立遠端模型：
```
CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (ENDPOINT = 'ENDPOINT');
```
取代下列項目：
- PROJECT_ID：您的專案 ID
- DATASET_ID：要包含模型的資料集 ID。這個資料集必須與您使用的連線位於相同的位置
- MODEL_NAME：模型名稱
- REGION：連線使用的區域
- CONNECTION_ID：BigQuery 連線的 ID
  在 Google Cloud 控制台中查看連線詳細資料時，這是「連線 ID」中顯示的完整連線 ID 最後一部分的值，例如 projects/myproject/locations/connection_location/connections/myconnection
- ENDPOINT：要使用的 Gemini 模型名稱。詳情請參閱 ENDPOINT。

產生結構化資料

使用AI.GENERATE_TABLE 函式搭配遠端模型，並使用資料表欄中的提示資料，產生結構化資料：

SELECT *
FROM AI.GENERATE_TABLE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  [TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` / (PROMPT_QUERY)],
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p, STOP_SEQUENCES AS stop_sequences,
  SAFETY_SETTINGS AS safety_settings,
  OUTPUT_SCHEMA AS output_schema)
);

取代下列項目：

PROJECT_ID：您的專案 ID。
DATASET_ID：包含模型的資料集 ID。
MODEL_NAME：模型名稱。
TABLE_NAME：包含提示的資料表名稱。這個資料表必須有名為 prompt 的資料欄，或者您可以使用別名來使用名稱不同的資料欄。
PROMPT_QUERY：產生提示資料的 GoogleSQL 查詢。提示值本身可以從資料欄中提取，也可以指定為結構體值，其中包含任意數量的字串和資料欄名稱子欄位。例如：SELECT ('Analyze the sentiment in ', feedback_column, 'using the following categories: positive, negative, neutral') AS prompt。
TOKENS：INT64 值，用於設定回覆中可生成的詞元數量上限。這個值必須在 [1,8192] 範圍內。如要取得較短的回覆，請指定較低的值；如要取得較長的回覆，請調高此值。預設值為 128。
TEMPERATURE：介於 [0.0,2.0] 之間的 FLOAT64 值，可控制選取詞元時的隨機程度。預設值為 1.0。
如果您想藉由提示生成更具確定性、較不具開放性和創意性的回覆，建議調低 temperature 的值。另一方面，如果 temperature 的值較高，則可能產生較多元或有創意的結果。0 的 temperature 值具有確定性，即模型一律會選取可能性最高的回覆。
TOP_P：[0.0,1.0] 範圍內的 FLOAT64 值有助於判斷所選權杖的機率。如要取得較不隨機的回覆，請指定較低的值；如要取得較隨機的回覆，請調高此值。預設值為 0.95。
STOP_SEQUENCES：ARRAY<STRING> 值，可移除模型回覆中包含的指定字串。字串必須完全相符，包括大小寫。預設值為空陣列。
SAFETY_SETTINGS：ARRAY<STRUCT<STRING AS category, STRING AS threshold>> 值，可設定內容安全門檻來篩選回應。結構體中的第一個元素會指定有害類別，第二個元素則會指定對應的封鎖門檻。模型會過濾違反這些設定的內容。每個類別只能指定一次。舉例來說，您無法同時指定 STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_MEDIUM_AND_ABOVE' AS threshold) 和 STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_ONLY_HIGH' AS threshold)。如果特定類別沒有安全設定，系統會使用 BLOCK_MEDIUM_AND_ABOVE 安全設定。

支援的類別如下：
- HARM_CATEGORY_HATE_SPEECH
- HARM_CATEGORY_DANGEROUS_CONTENT
- HARM_CATEGORY_HARASSMENT
- HARM_CATEGORY_SEXUALLY_EXPLICIT
支援的門檻如下：
- BLOCK_NONE (受限)
- BLOCK_LOW_AND_ABOVE
- BLOCK_MEDIUM_AND_ABOVE (預設)
- BLOCK_ONLY_HIGH
- HARM_BLOCK_THRESHOLD_UNSPECIFIED
詳情請參閱「有害類別」和「如何設定內容篩選器」。
OUTPUT_SCHEMA：STRING 值，指定模型回覆的格式。output_schema 值必須是 SQL 結構定義，類似於 CREATE TABLE 陳述式中使用的結構定義。支援的資料類型如下：
- INT64
- FLOAT64
- BOOL
- STRING
- ARRAY
- STRUCT
如果是 Gemini 1.5 模型，只有在確定傳回值不會是整數時，才指定 FLOAT64 資料型別。有時，這些模型可能會針對整數傳回 INT64 值，而非 FLOAT64 值，例如 2 而非 2.0，這可能會導致查詢發生剖析錯誤。

使用 output_schema 引數，根據表格中的提示生成結構化資料時，請務必瞭解提示資料，以便指定適當的結構定義。

舉例來說，假設您要分析某個資料表中的電影評論內容，該資料表包含下列欄位：
- movie_id
- review
- 提示
接著，您可以執行類似下列的查詢，建立提示文字：
```
UPDATE mydataset.movie_review
SET prompt = CONCAT('Extract the key words and key sentiment from the text below: ', review)
WHERE review IS NOT NULL;
```
您可能會指定類似 "keywords ARRAY<STRING>, sentiment STRING" AS output_schema 的 output_schema 值。

範例

以下範例顯示的要求會從表格中擷取提示資料，並提供 SQL 結構定義來設定模型回覆的格式：

SELECT
*
FROM
AI.GENERATE_TABLE( MODEL `mydataset.gemini_model`,
  TABLE `mydataset.mytable`,
  STRUCT("keywords ARRAY<STRING>, sentiment STRING" AS output_schema));

以下範例顯示的要求會從查詢中取得提示資料，並提供 SQL 結構定義來設定模型回覆的格式：

SELECT *
FROM
  AI.GENERATE_TABLE(
    MODEL `mydataset.gemini_model`,
    (
      SELECT
        'John Smith is a 20-year old single man living at 1234 NW 45th St, Kirkland WA, 98033. He has two phone numbers 123-123-1234, and 234-234-2345. He is 200.5 pounds.'
          AS prompt
    ),
    STRUCT("address STRUCT<street_address STRING, city STRING, state STRING, zip_code STRING>, age INT64, is_married BOOL, name STRING, phone_number ARRAY<STRING>, weight_in_pounds FLOAT64"
        AS output_schema, 8192 AS max_output_tokens));