使用 ML.GENERATE_EMBEDDING 函式生成圖像嵌入

本文說明如何建立參照 Vertex AI 嵌入模型的 BigQuery ML遠端模型。接著，您可以使用 ML.GENERATE_EMBEDDING 函式，透過 BigQuery 物件資料表中的資料建立圖片嵌入。

必要的角色

如要建立遠端模型並產生嵌入內容，您需要下列 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) 權限。這是您透過將模型名稱指定為端點所建立遠端模型的目前專案。這是您透過指定網址做為端點所建立遠端模型的網址中，所識別的專案。

  如果您使用遠端模型分析物件資料表中的非結構化資料，且物件資料表使用的 Cloud Storage bucket 與 Vertex AI 端點位於不同專案，您也必須在物件資料表使用的 Cloud Storage bucket 上擁有 Storage Admin (roles/storage.admin)。

• 建立 BigQuery 工作：專案中的 BigQuery 工作使用者 (roles/bigquery.jobUser)。

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

所需權限

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

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

事前準備

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

2. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

建立資料集

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

控制台

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

   前往 BigQuery 頁面

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

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

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

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

   • 在「位置類型」部分，選取資料集的位置。

   • 點選「建立資料集」。

bq

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

   bq --location=LOCATION mk -d DATASET_ID

   更改下列內容：

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

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

   bq ls

建立連線

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

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

選取下列選項之一：

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在「Explorer」窗格中，按一下 「新增資料」：

   

   「新增資料」對話方塊隨即開啟。

3. 在「依條件篩選」窗格的「資料來源類型」部分，選取「商務應用程式」。

   或者，您也可以在「Search for data sources」(搜尋資料來源) 欄位中輸入 Vertex AI。

4. 在「精選資料來源」部分，按一下「Vertex AI」。

5. 按一下「Vertex AI Models: BigQuery Federation」解決方案資訊卡。

6. 在「連線類型」清單中，選取「Vertex AI 遠端模型、遠端函式和 BigLake (Cloud 資源)」。

7. 在「連線 ID」欄位中，輸入連線名稱。

8. 點選「建立連線」。

9. 按一下「前往連線」。

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

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

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 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

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

授予服務帳戶存取權

為連線的服務帳戶授予 Vertex AI 使用者和 Storage 物件檢視者角色。

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

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

在其他專案中授予角色會導致錯誤 [e-mail] does not have the permission to access resource。

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

主控台

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

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

2. 按一下 「新增」。

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

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

4. 在「請選擇角色」欄位中，依序選取「Vertex AI」和「Vertex AI 使用者」。

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。

建立物件資料表

如要分析圖片，但不想將圖片從 Cloud Storage 移出，請建立物件資料表。

如要建立物件資料表，請按照下列步驟操作：

SQL

使用 CREATE EXTERNAL TABLE 陳述式。

1. 前往 Google Cloud 控制台的「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。

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

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

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

     您使用的 Cloud Storage 值區應位於同一個專案，您打算在該專案中建立模型並呼叫 ML.GENERATE_EMBEDDING 函式。如要呼叫ML.GENERATE_EMBEDDING函式，但該函式與物件表格使用的 Cloud Storage 值區不在同一個專案中，您必須在值區層級授予服務帳戶 Storage 管理員角色。[e-mail]

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

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

     如要啟用中繼資料快取功能，請指定介於 30 分鐘至 7 天之間的間隔常值。舉例來說，如要指定 4 小時的過時間隔，請輸入 INTERVAL 4 HOUR。如果資料表在過去 4 小時內重新整理過，針對該資料表執行的作業就會使用快取中繼資料。如果快取中繼資料的建立時間早於該時間，作業會改為從 Cloud Storage 擷取中繼資料。

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

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

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

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

3. 按一下「執行」。

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

bq

使用 bq mk 指令。

bq mk --table \
--external_table_definition=[e-mail]_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

取代下列項目：

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

  您使用的 Cloud Storage 值區應位於同一個專案，您打算在該專案中建立模型並呼叫 ML.GENERATE_EMBEDDING 函式。如要呼叫ML.GENERATE_EMBEDDING函式，但該函式與物件表格使用的 Cloud Storage 值區不在同一個專案中，您必須在值區層級授予服務帳戶 Storage 管理員角色。[e-mail]

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

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

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

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

  如要啟用中繼資料快取功能，請指定介於 30 分鐘至 7 天之間的間隔常值。舉例來說，如要指定 4 小時的過時間隔，請輸入 INTERVAL 4 HOUR。如果資料表在過去 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：物件表格的名稱。

建立模型

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

   前往 BigQuery

2. 使用 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：您建立的連線 ID。

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

   • ENDPOINT：要使用的嵌入模型，在本例中為 multimodalembedding@001。

     如果您在建立遠端模型時指定網址做為端點 (例如 endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/multimodalembedding@001')，請確保網址中指定的專案是您已授予連線 Vertex AI 使用者角色的專案。新建立的服務帳戶

     您建立遠端模型的位置必須提供 multimodalembedding@001 模型。詳情請參閱位置。

生成圖片嵌入

使用物件資料表的圖片資料，透過 ML.GENERATE_EMBEDDING 函式生成圖片嵌入：

  SELECT *
  FROM ML.GENERATE_EMBEDDING(
    MODEL <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>MODEL_NAME</var>,
    TABLE <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>TABLE_NAME</var>,
    STRUCT(FLATTEN_JSON AS flatten_json_output,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );
  

取代下列項目：

• PROJECT_ID：您的專案 ID。
• DATASET_ID：包含模型的資料集 ID。
• MODEL_NAME：multimodalembedding@001 模型上的遠端模型名稱。
• TABLE_NAME：包含要嵌入圖片的物件表格名稱。
• FLATTEN_JSON：BOOL 值，指出是否要將嵌入內容剖析至個別資料欄。預設值為 TRUE。
• OUTPUT_DIMENSIONALITY：INT64 值，指定產生嵌入時要使用的維度數量。有效值為 128、256、512 和 1408。預設值為 1408。舉例來說，如果您指定 256 AS output_dimensionality，則輸出資料欄會為每個輸入值包含 256 個嵌入。ml_generate_embedding_result

範例

以下範例說明如何為 images 物件表格中的圖片建立嵌入內容：

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE `mydataset.images`,
    STRUCT(TRUE AS flatten_json_output, 512 AS output_dimensionality)
  );

後續步驟

• 瞭解如何使用文字和圖片嵌入執行文字轉圖片的語意搜尋。
• 瞭解如何使用文字嵌入進行語意搜尋和檢索增強生成 (RAG)。