使用 AI.GENERATE_EMBEDDING 函式生成圖片嵌入

控制台

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

   前往「BigQuery」

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

   

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

3. 在「Explorer」窗格中，按一下專案名稱。

4. 依序點按 more_vert「View actions」(查看動作) >「Create dataset」(建立資料集)。

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

   1. 在「Dataset ID」(資料集 ID) 部分，輸入資料集的名稱。

   2. 在「位置類型」部分，選取「區域」或「多區域」。

      • 如果選取「區域」，請從「區域」清單中選取位置。
      • 如果選取「多區域」，請從「多區域」清單中選取「美國」或「歐洲」。

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

bq

1. 如要建立新的資料集，請使用 bq mk 指令，並加上 --location 旗標：

   bq --location=LOCATION mk -d DATASET_ID

   更改下列內容：

   • LOCATION：資料集的位置。
   • DATASET_ID 是您要建立的資料集 ID。

2. 確認資料集已建立完成：

   bq ls

控制台

1. 前往「BigQuery」頁面。

   前往「BigQuery」

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

   

   如果沒有看到左側窗格，請按一下 last_page「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. 前往 Cloud de Confiance 控制台的「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. 按一下「執行」play_circle。

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

bq

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

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

2. 擷取並複製服務帳戶 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

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

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

1. 啟動 Cloud Shell。

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

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

   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. 開啟 Cloud de Confiance 專案，查看結果。在 Cloud de Confiance 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

控制台

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

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

2. 按一下「新增」person_add。

   「新增主體」對話方塊隨即開啟。

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

4. 在「選取角色」欄位中，依序選取「Vertex AI」和「Agent Platform User」(Agent Platform 使用者)。

5. 按一下 [Add another role] (新增其他角色)。

6. 在「Select a role」(請選擇角色) 欄位中，依序選取「Cloud Storage」和「Storage Object Viewer」(Storage 物件檢視者)。

7. 按一下 [儲存]。

gcloud

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

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

請替換下列項目：

• PROJECT_NUMBER：要授予角色的專案專案編號。
• MEMBER：您先前複製的服務帳戶 ID。

SQL

使用 CREATE EXTERNAL TABLE 陳述式。

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

   前往「BigQuery」

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

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
   WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
   OPTIONS(
     object_metadata = 'SIMPLE',
     uris = ['BUCKET_PATH'[,...]],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE');

   請替換下列項目：

   • PROJECT_ID：您的專案 ID。
   • DATASET_ID：您建立的資料集 ID。
   • TABLE_NAME：物件資料表的名稱。
   • REGION：包含連線的區域或多區域。
   • CONNECTION_ID：您建立的連線 ID。

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

     如要使用 預設連線，請指定 DEFAULT，而非包含 PROJECT_ID.REGION.CONNECTION_ID 的連線字串。

   • BUCKET_PATH：包含圖片的 Cloud Storage bucket 路徑，格式為 ['gs://bucket_name/[folder_name/]*']。

     您使用的 Cloud Storage 值區應位於同一個專案，您打算在該專案中建立模型並呼叫 AI.GENERATE_EMBEDDING 函式。如要呼叫的 AI.GENERATE_EMBEDDING 函式與物件表格使用的 Cloud Storage 值區不在同一個專案中，您必須在值區層級將 Storage Admin 角色授予 service-A@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com 服務帳戶。

   • STALENESS_INTERVAL：指定針對物件表格執行的作業是否使用快取中繼資料，以及作業必須使用多新的快取中繼資料。如要進一步瞭解中繼資料快取注意事項，請參閱「中繼資料快取，提升效能」。

     如要停用中繼資料快取功能，請指定 0。這是目前的預設做法。

     如要啟用中繼資料快取，請指定 間隔常值，值介於 30 分鐘到 7 天之間。舉例來說，如要指定 4 小時的過時間隔，請指定 INTERVAL 4 HOUR。使用這個值時，如果表格作業在過去 4 小時內重新整理過，就會使用快取中繼資料。如果快取中繼資料的更新時間超過 4 小時，作業就會改為從 Cloud Storage 擷取中繼資料。

   • CACHE_MODE：指定中繼資料快取是自動還是手動重新整理。如要進一步瞭解中繼資料快取注意事項，請參閱「中繼資料快取，提升效能」。

     設為 AUTOMATIC，中繼資料快取就會以系統定義的時間間隔重新整理，通常介於 30 到 60 分鐘之間。

     如要依您決定的時間表重新整理中繼資料快取，請設為 MANUAL。在這種情況下，您可以呼叫 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系統程序來重新整理快取。

     如果 STALENESS_INTERVAL 設為大於 0 的值，您就必須設定 CACHE_MODE。

3. 按一下「執行」play_circle。

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

bq

使用 bq mk 指令。

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

請替換下列項目：

• BUCKET_PATH：包含圖片的 Cloud Storage bucket 路徑，格式為 ['gs://bucket_name/[folder_name/]*']。

  您使用的 Cloud Storage 值區應位於同一個專案，您打算在該專案中建立模型並呼叫 AI.GENERATE_EMBEDDING 函式。如要呼叫的 AI.GENERATE_EMBEDDING 函式與物件表格使用的 Cloud Storage 值區不在同一個專案中，您必須在值區層級將 Storage Admin 角色授予 service-A@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com 服務帳戶。

• REGION：包含連線的區域或多區域。
• CONNECTION_ID：您建立的連線 ID。

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

• STALENESS_INTERVAL：指定針對物件表格執行的作業是否使用快取中繼資料，以及作業必須使用多新的快取中繼資料。如要進一步瞭解中繼資料快取注意事項，請參閱「中繼資料快取，提升效能」。

  如要停用中繼資料快取功能，請指定 0。這是目前的預設做法。

  如要啟用中繼資料快取，請指定 間隔常值，值介於 30 分鐘到 7 天之間。舉例來說，如要指定 4 小時的過時間隔，請指定 INTERVAL 4 HOUR。使用這個值時，如果表格作業在過去 4 小時內重新整理過，就會使用快取中繼資料。如果快取中繼資料的更新時間超過 4 小時，作業就會改為從 Cloud Storage 擷取中繼資料。

• CACHE_MODE：指定中繼資料快取是自動還是手動重新整理。如要進一步瞭解中繼資料快取注意事項，請參閱「中繼資料快取，提升效能」。

  設為 AUTOMATIC，中繼資料快取就會以系統定義的時間間隔重新整理，通常介於 30 到 60 分鐘之間。

  如要依您決定的時間表重新整理中繼資料快取，請設為 MANUAL。在這種情況下，您可以呼叫 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系統程序來重新整理快取。

  如果 STALENESS_INTERVAL 設為大於 0 的值，您就必須設定 CACHE_MODE。

• PROJECT_ID：您的專案 ID。
• DATASET_ID：您建立的資料集 ID。
• TABLE_NAME：物件資料表的名稱。