本頁面的部分或所有資訊可能不適用於 S3NS 的 Cloud de Confiance。詳情請參閱「與 Google Cloud 的差異」。

使用 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)。

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

所需權限

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

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

事前準備

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

前往專案選取器
確認專案已啟用計費功能 Cloud de Confiance 。
啟用 BigQuery、BigQuery Connection 和 Vertex AI API。
啟用 API 時所需的角色
如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。
啟用 API

建立資料集

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

控制台

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

前往「BigQuery」
點選左側窗格中的「Explorer」。

如果沒有看到左側窗格，請按一下「展開左側窗格」圖示開啟窗格。
在「Explorer」窗格中，按一下專案名稱。
依序點按「View actions」(查看動作) >「Create dataset」(建立資料集)。
在「建立資料集」頁面中，執行下列操作：
1. 在「Dataset ID」(資料集 ID) 部分，輸入資料集的名稱。
2. 在「位置類型」部分，選取「區域」或「多區域」。
  - 如果選取「區域」，請從「區域」清單中選取位置。
  - 如果選取「多區域」，請從「多區域」清單中選取「美國」或「歐洲」。
3. 點選「建立資料集」。

bq

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

建立連線

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

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

選取下列選項之一：

控制台

前往「BigQuery」頁面。

前往「BigQuery」
點選左側窗格中的「Explorer」。

如果沒有看到左側窗格，請按一下「展開左側窗格」圖示開啟窗格。
在「Explorer」窗格中展開專案名稱，然後按一下「Connections」。
在「Connections」(連線) 頁面中，按一下「Create connection」(建立連線)。
在「連線類型」中，選擇「Vertex AI 遠端模型、遠端函式、BigLake 和 Spanner (Cloud 資源)」。
在「連線 ID」欄位中，輸入連線名稱。
在「位置類型」部分，選取連線位置。連線應與資料集等其他資源位於同一位置。
點選「建立連線」。
點選「前往連線」。
在「連線資訊」窗格中，複製服務帳戶 ID，以便在後續步驟中使用。

SQL

使用 CREATE CONNECTION 陳述式：

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

前往「BigQuery」
在查詢編輯器中輸入下列陳述式：
```
CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
OPTIONS (
  connection_type = "CLOUD_RESOURCE",
  friendly_name = "FRIENDLY_NAME",
  description = "DESCRIPTION"
  );
```
請替換下列項目：
- CONNECTION_NAME：連線名稱，格式為 PROJECT_ID.LOCATION.CONNECTION_ID、LOCATION.CONNECTION_ID 或 CONNECTION_ID。如果省略專案或位置，系統會從執行陳述式的專案和位置推斷。
- FRIENDLY_NAME (選用)：連線的描述性名稱。
- DESCRIPTION (選用)：連線說明。
按一下執行。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

bq

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

更改下列內容：
- REGION：您的連線區域
- PROJECT_ID：您的 Cloud de Confiance 專案 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.s3ns-system.iam.gserviceaccount.com"}

Python

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 BigQuery Python API 參考說明文件。

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

執行程式碼範例前，請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱 BigQuery Node.js API 參考說明文件。

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

執行程式碼範例前，請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

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 {}
}

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

準備 Cloud Shell

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

您只需要為每項專案執行一次這個指令，且可以在任何目錄中執行。
```
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!」訊息。
開啟 Cloud de Confiance 專案即可查看結果。在 Cloud de Confiance 控制台中，前往 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.s3ns-system.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 遠端模型

前往 Cloud de Confiance 控制台的「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
  在 Cloud de Confiance 控制台中查看連線詳細資料時，這是「連線 ID」中顯示的完整連線 ID 最後一個部分的值，例如 projects/myproject/locations/connection_location/connections/myconnection
- ENDPOINT：要使用的 Gemini 模型名稱。對於支援的 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：FLOAT64 範圍內的 FLOAT64 值 ([0.0,1.0]) 有助於判斷所選符記的機率。如要取得較不隨機的回覆，請指定較低的值；如要取得較隨機的回覆，請調高此值。預設值為 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
使用 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));