使用 Gemini 模型和 AI.GENERATE_TEXT 函式生成文字

本教學課程說明如何根據 gemini-2.5-flash 模型建立遠端模型，然後使用 AI.GENERATE_TEXT 函式，從 bigquery-public-data.imdb.reviews 公開資料表擷取電影評論中的關鍵字，並進行情緒分析。

必要的角色

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

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

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

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

費用

在本文件中，您會使用下列 Cloud de Confiance by S3NS的計費元件：

• BigQuery ML: You incur costs for the data that you process in BigQuery.
• Vertex AI: You incur costs for calls to the Vertex AI service that's represented by the remote model.

如要進一步瞭解 BigQuery 定價，請參閱 BigQuery 說明文件中的「BigQuery 定價」一文。

如要進一步瞭解 Vertex AI 定價，請參閱 Vertex AI 定價頁面。

事前準備

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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.

   Go to project selector

2. Verify that billing is enabled for your Cloud de Confiance project.

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

建立資料集

建立 BigQuery 資料集來儲存機器學習模型。

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

import google.cloud.bigquery

bqclient = google.cloud.bigquery.Client()
bqclient.create_dataset("bqml_tutorial", exists_ok=True)

建立連線

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

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

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

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}`);
    }
  }
}

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

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

為連線的服務帳戶授予 Vertex AI 使用者角色。您必須在「開始前」一節中建立或選取的專案中，授予這項角色。在其他專案中授予角色會導致 bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.s3ns-system.iam.gserviceaccount.com does not have the permission to access resource 錯誤。

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

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

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

2. 按一下 person_add「授予存取權」。

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

4. 在「選取角色」欄位中，選擇「Vertex AI」，然後選取「Vertex AI 使用者」角色。

5. 按一下 [儲存]。

建立遠端模型

建立代表代管 Vertex AI 模型的遠端模型：

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

   前往「BigQuery」

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

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

更改下列內容：

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

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

查詢作業會在幾秒內完成，模型 gemini_model 隨即會顯示在 bqml_tutorial 資料集中。由於查詢使用 CREATE MODEL 陳述式建立模型，因此不會有查詢結果。

執行關鍵字擷取

使用遠端模型和 AI.GENERATE_TEXT 函式，對 IMDB 電影評論執行關鍵字擷取作業：

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

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式，對五則電影評論執行關鍵字擷取作業：

   SELECT
     title, result, review
   FROM
     AI.GENERATE_TEXT(
       MODEL `bqml_tutorial.gemini_model`,
       (
         SELECT
           CONCAT(
             """Extract a list of only 3 key words from this review.
               List only the key words, nothing else. Review: """,
               review) AS prompt,
           *
         FROM
           `bigquery-public-data.imdb.reviews`
         LIMIT 5
       ),
       STRUCT(
         0.2 AS temperature,
         100 AS max_output_tokens));

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

   +--------------+------------------+----------------------------------------+
   | title        | result           | review                                 |
   +--------------+------------------+----------------------------------------+
   | The Guardian | * Costner        | Once again Mr. Costner has dragged out |
   |              | * Kutcher        | a movie for far longer than necessary. |
   |              | * Rescue         | Aside from the terrific sea rescue...  |
   |              |                  |                                        |
   | Trespass     | * Generic        | This is an example of why the majority |
   |              | * Waste          | of action films are the same. Generic  |
   |              | * Cinematography | and boring, there's really nothing...  |
   | ...          | ...              | ...                                    |
   +--------------+------------------+----------------------------------------+
   

執行情緒分析

使用遠端模型和 AI.GENERATE_TEXT 函式，對 IMDB 電影評論執行情緒分析：

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

   前往「BigQuery」

2. 在查詢編輯器中執行下列陳述式，對電影評論執行情緒分析：

   SELECT
     title, result, review
   FROM
     AI.GENERATE_TEXT(
       MODEL `bqml_tutorial.gemini_model`,
       (
         SELECT
           CONCAT(
             """Perform sentiment analysis on the following text and
                return one the following categories: positive, negative: """,
             review) AS prompt,
           *
         FROM
           `bigquery-public-data.imdb.reviews`
         LIMIT 5
       ),
       STRUCT(
         0.2 AS temperature,
         100 AS max_output_tokens));

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

   +----------+----------+------------------------------------------------+
   | title    | result   | review                                         |
   +----------+----------+------------------------------------------------+
   | Quitting | Positive | This movie is amazing because the fact that... |
   | Trespass | Negative | This is an example of why the majority of ...  |
   | ...      | ...      | ...                                            |
   +----------+----------+------------------------------------------------+
   

清除所用資源

1. In the Cloud de Confiance console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.