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

AI.GENERATE_TABLE 函式可讓您從非結構化文字中擷取結構化屬性，並放入 BigQuery 的類型資料表資料欄。在本教學課程中，您將透過 Gemini 模型建立遠端模型，並從公開的電影評論資料集擷取情緒和關鍵字。

目標

• 建立資料集和 Cloud 資源連結。
• 將權限授予連線的服務帳戶。
• 建立 BigQuery ML 遠端模型。
• 使用 AI.GENERATE_TABLE 函式，從非結構化文字生成結構化資料。

費用

在本文件中，您會使用下列 Google Cloud計費元件：

• BigQuery: 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 定價」和「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 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

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection, and Agent Platform API APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection, and Agent Platform API APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

1. 確認您具備下列專案角色：BigQuery 管理員、專案 IAM 管理員

   檢查角色

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

      前往「IAM」頁面
   2. 選取專案。

   3. 在「Principal」(主體) 欄中，找出所有代表您或您所屬群組的資料列。如要瞭解您所屬的群組，請與管理員聯絡。

   4. 在指定或包含您的所有資料列中，查看「Role」(角色) 欄，確認角色清單是否包含必要角色。

   授予角色

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

      前往「IAM」頁面
   2. 選取專案。
   3. 按一下「Grant access」(授予存取權)。

   4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。 這通常是指 Google 帳戶的電子郵件地址。

   5. 按一下「Select a role」(選取角色)，然後搜尋角色。
   6. 如要授予其他角色，請按一下「Add another role」(新增其他角色)，然後新增其他角色。
   7. 按一下「Save」(儲存)。

gcloud

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

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

• 選取專案：選取專案時不需要特定 IAM 角色，只要您獲派某個專案的角色，即可選取該專案。
• 建立專案：如要建立專案，您必須具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，不要選取現有專案。如果採用這種做法，當您完成這些步驟後，就可以直接刪除該專案，並移除相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

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

啟用 BigQuery、BigQuery Connection 和 Agent Platform API (如有尚未啟用的 API)：

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

gcloud services enable bigquery.googleapis.com bigqueryconnection.googleapis.com aiplatform.googleapis.com

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

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

• 選取專案：選取專案時不需要特定 IAM 角色，只要您獲派某個專案的角色，即可選取該專案。
• 建立專案：如要建立專案，您必須具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，不要選取現有專案。如果採用這種做法，當您完成這些步驟後，就可以直接刪除該專案，並移除相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

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

啟用 BigQuery、BigQuery Connection 和 Agent Platform API (如有尚未啟用的 API)：

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

gcloud services enable bigquery.googleapis.com bigqueryconnection.googleapis.com aiplatform.googleapis.com

1. 將角色授予使用者帳戶。針對下列各個 IAM 角色執行下列指令一次： roles/bigquery.admin, roles/resourcemanager.projectIamAdmin

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

   更改下列內容：

   • PROJECT_ID：專案 ID。
   • USER_IDENTIFIER：使用者帳戶 ID。 例如：[e-mail]。
   • ROLE：授予使用者帳戶的 IAM 角色。

建立資料集

如要建立 BigQuery 資料集，請選取下列其中一個選項：

控制台

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

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」。

   

   如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

3. 在「Explorer」中展開專案，然後按一下「資料集」。

4. 在「Datasets」(資料集) 頁面，按一下「Create dataset」(建立資料集)。

5. 在「建立資料集」窗格中，執行下列操作：

   • 在「Dataset ID」(資料集 ID) 中輸入 bqml_tutorial。

   • 在「資料位置」部分，選取「US」。

   其餘設定均保留預設值。

6. 點選「建立資料集」。

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

建立連線

在建立資料集的 US 多區域中，建立 Cloud 資源連結。接著取得連線的服務帳戶。

選取下列選項之一：

控制台

1. 前往「BigQuery」頁面。

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」。

   

   如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

3. 在「Explorer」窗格中展開專案名稱，然後點選「Connections」(連線)。

4. 在「Connections」(連線) 頁面，按一下「Create connection」(建立連線)。

5. 在「連線類型」部分，選擇「Vertex AI 遠端模型、遠端函式、BigLake 和 Spanner (Cloud 資源)」。

6. 在「連線 ID」欄位輸入連線名稱。

7. 在「位置類型」部分，選取連線位置。連線應與資料集等其他資源位於相同位置。

8. 點選「建立連線」。

9. 點選「前往連線」。

10. 在「連線資訊」窗格中，複製服務帳戶 ID，以便在後續步驟中使用。

SQL

使用 CREATE CONNECTION 陳述式：

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

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   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 (選用)：連線說明。

3. 按一下「 執行」。

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

bq

1. 在指令列環境中建立連線：

   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...
   

2. 擷取並複製服務帳戶 ID，以便在後續步驟中使用：

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

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

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Python

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

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

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

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

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

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 資源。

注意： 如要使用 Terraform 建立 BigQuery 物件，必須啟用 Cloud Resource Manager API。

如要向 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

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每個專案只需執行這個指令一次，而且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確的值，環境變數就會遭到覆寫。

準備目錄

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

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱必須有 .tf 副檔名，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在進行教學課程，可以複製每個章節或步驟中的程式碼範例。

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

   您也可以從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您採用這種做法。

3. 請查看並修改範例參數，以便套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請視需要加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 查看設定，確認 Terraform 要建立或更新的資源符合預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

注意：Terraform 範例通常會假設 Google Cloud 專案已啟用必要的 API。

將權限授予連線的服務帳戶

將 Agent Platform 使用者 (roles/aiplatform.user) 角色授予連線的服務帳戶。您必須在「事前準備」一節中建立或選取的專案中，授予這個角色。在其他專案中授予角色會導致錯誤 [e-mail] does not have the permission to access resource。

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

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

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

2. 按一下「Grant Access」(授予存取權)。

3. 在「新增主體」欄位，輸入先前複製的服務帳戶 ID。

4. 在「選取角色」欄位中，搜尋「Agent Platform 使用者」角色。

5. 按一下 [儲存]。

建立遠端模型

使用 CREATE MODEL 陳述式建立遠端模型，代表託管的 Agent Platform 模型：

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

   前往「BigQuery」

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

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

   更改下列內容：

   • LOCATION：連線位置
   • CONNECTION_ID：BigQuery 連線 ID

     在 Google Cloud 控制台查看連線詳細資料時，這個值會顯示在「Connection ID」(連線 ID) 中完整連線 ID 的最後一個部分，例如projects/myproject/locations/connection_location/connections/myconnection

   查詢會在幾秒內完成，之後模型 gemini_model 就會顯示在 bqml_tutorial 資料集中。沒有查詢結果。

生成結構化資料

使用 AI.GENERATE_TABLE 函式和遠端模型，從電影評論中擷取結構化情緒和關鍵字：

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

   前往「BigQuery」

2. 在查詢編輯器中執行下列陳述式，從五則電影評論中擷取情緒和關鍵字：

   SELECT
     movie_id,
     sentiment,
     keywords
   FROM
     AI.GENERATE_TABLE(
       MODEL `bqml_tutorial.gemini_model`,
       (
         SELECT
           CONCAT(
             """Analyze the following movie review. Extract a sentiment
             (positive or negative) and up to 3 keywords: """,
             review) AS prompt,
           movie_id
         FROM
           `bigquery-public-data.imdb.reviews`
         LIMIT 5
       ),
       STRUCT(
         "sentiment STRING, keywords ARRAY<STRING>" AS output_schema));

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

   +-----------+-----------+----------------------------------------------+
   | movie_id  | sentiment | keywords                                     |
   +-----------+-----------+----------------------------------------------+
   | tt0369053 | positive  | ["cinematography", "performances", "comedy"] |
   | tt0328400 | negative  | ["disregarded", "disappointing", "poorly"]   |
   | ...       | ...       | ...                                          |
   +-----------+-----------+----------------------------------------------+
   

清除所用資源

為避免因為本教學課程所用資源，導致系統向 Google Cloud 收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

注意：刪除專案會造成以下影響：

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

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

刪除 Google Cloud 專案：

gcloud projects delete PROJECT_ID

刪除個別資源

如要重複使用專案，請刪除為教學課程建立的資源：

控制台

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

   前往「BigQuery」

2. 刪除 bqml_tutorial 資料集。刪除資料集也會一併刪除遠端模型。

   1. 在「Explorer」窗格中展開專案，然後點選「資料集」。

   2. 在「Datasets」(資料集) 清單中，點選 bqml_tutorial 資料集。

   3. 在詳細資料窗格中，按一下「 刪除」。

   4. 在「Delete dataset」(刪除資料集) 對話方塊中，點選「Delete」(刪除)。

3. 刪除連結。

   1. 在「Explorer」窗格中展開專案，然後點選「連線」。

   2. 在「Connections」(連線) 清單中，按一下您建立的連線。

   3. 在詳細資料窗格中，按一下「 刪除」。

   4. 在「Delete connection」(刪除連線) 對話方塊中，輸入 delete 確認刪除。

   5. 點選「刪除」。

gcloud

1. 刪除 bqml_tutorial 資料集和遠端模型：

   bq rm --dataset --recursive bqml_tutorial
   

2. 刪除連線：

   bq rm --connection <var>PROJECT_ID</var>.<var>LOCATION</var>.<var>CONNECTION_ID</var>
   

   更改下列內容：

   • <var>PROJECT_ID</var>：您的 Google Cloud 專案 ID
   • <var>LOCATION</var>：連線位置
   • <var>CONNECTION_ID</var>：連線 ID

後續步驟

• 進一步瞭解 AI.GENERATE_TABLE 函式。
• 進一步瞭解 BigQuery 中的生成式 AI。
• 瞭解如何選擇文字生成函式。