Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

自主生成嵌入

本文說明如何使用自主嵌入生成功能處理資料，讓 BigQuery 根據來源資料欄，維護資料表中的嵌入資料欄。來源資料欄必須包含 STRING 或 ObjectRef 資料類型。您在來源資料欄新增或修改資料時，BigQuery 會使用 Agent Platform 嵌入模型，自動生成或更新該項資料的嵌入資料欄。如果來源資料會定期更新，且您希望 BigQuery 維護嵌入內容，這項功能就非常實用。

嵌入功能對檢索增強生成 (RAG) 等現代生成式 AI 應用程式來說很實用，但建立、管理及查詢嵌入功能可能很複雜。您可以使用自主嵌入生成功能，簡化建立、維護及查詢嵌入的程序，以便用於相似度搜尋和其他生成式 AI 應用程式。

舉例來說，您可以執行類似下列的查詢，建立啟用自主嵌入生成功能的資料表、插入資料，然後執行語意搜尋：

CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) STORED OPTIONS( asynchronous = TRUE ));

# Values in the description_embedding column are automatically generated.
INSERT INTO mydataset.products (name, description) VALUES
  ('Super slingers', 'An exciting board game for the whole family'), ...;

SELECT * FROM AI.SEARCH(TABLE mydataset.products, 'description', 'A really fun toy');

事前準備

如要在表格上啟用自主產生嵌入功能，您必須具備必要權限和連線，並為專案啟用 Vertex AI API。

必要的角色

如要取得啟用自主產生嵌入內容所需的權限，請要求管理員授予您下列 IAM 角色：

如要使用連線資源：連線的「BigQuery Connections User」 (roles/bigquery.connectionUser)
如要建立或變更資料表： BigQuery 資料編輯者 (roles/bigquery.dataEditor) 資料表
將下列角色授予連線的服務帳戶，以便存取 Agent Platform 端點中代管的模型： Agent Platform 使用者 (roles/aiplatform.user) 在具有連線的專案中

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

建立連線並授予服務帳戶權限

如要在表格中啟用自主嵌入生成功能，您必須建立 Cloud 資源連結。然後，授予在建立連線時建立的服務帳戶Agent Platform 使用者角色 (roles/aiplatform.user)。

建立自動生成的嵌入欄

您可以在新資料表中建立自動產生的嵌入資料欄，也可以在現有資料表中新增這類資料欄。

建立含有自動產生嵌入資料欄的資料表

您可以使用自主嵌入生成功能，在 CREATE TABLE 陳述式中使用 AI.EMBED 函式生成嵌入。

SQL

使用 CREATE TABLE 陳述式建立資料表，並自動產生嵌入資料欄。如要建立資料表，請按照下列步驟操作：

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

前往「BigQuery」
在查詢編輯器中輸入下列陳述式：
```
CREATE TABLE DATASET_ID.TABLE (
  [COLUMN, ...]
  SOURCE_COL { STRING | ObjectRef },
  EMBEDDING_COL_NAME STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(
        SOURCE_COL,
        {
          connection_id => CONNECTION_ID,
          endpoint => ENDPOINT |
          model => MODEL
        })
    )
    STORED OPTIONS (asynchronous = TRUE)
);
```
請替換下列項目：
- DATASET_ID：要在其中建立資料表的資料集名稱。
- TABLE：要建立自主嵌入生成功能的資料表名稱。
- COLUMN, ...：除了要自動嵌入的資料欄外，表格應包含的所有資料欄。
- SOURCE_COL：要自動嵌入的 STRING 或 ObjectRef 資料欄名稱。
- EMBEDDING_COL_NAME：系統自動產生的嵌入資料欄名稱。
- CONNECTION_ID：STRING 值，其中包含要使用的連線名稱，例如 my_project.us.example_connection。您必須在建立資料表的專案中，將 Agent Platform 使用者角色授予連線的服務帳戶。
- ENDPOINT：STRING 值，指定要用於文字嵌入模型的支援 Agent Platform 文字嵌入模型端點。您指定的端點值必須包含模型版本，例如 text-embedding-005。如果您指定模型名稱而非網址，BigQuery ML 會自動識別模型，並使用模型的完整端點。
- MODEL (預覽版)：指定內建文字嵌入模型的 STRING 值。目前僅支援embeddinggemma-300m 模型。如果指定這個參數，就無法指定 endpoint 或 connection_id 參數。指定 MODEL 參數後，資料會保留在 BigQuery 中，並使用您的時段建立嵌入內容；系統不會將資料傳送至 Agent Platform，也不會在 Agent Platform 中產生費用。
按一下「執行」。

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

bq

如要使用 bq 指令列工具建立資料表，並自動產生嵌入資料欄，請使用 bq mk 指令，並提供定義資料表結構定義的 JSON 結構定義檔：

建立 JSON 結構定義檔案。以下範例顯示根據來源資料欄建立嵌入資料欄的結構定義。這個範例會使用 Agent Platform 端點生成嵌入內容。

[
  {
    "name": "SOURCE_COL",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "result",
        "type": "FLOAT"
      },
      {
        "name": "status",
        "type": "STRING"
      }
    ],
    "generatedColumn": {
      "generationExpressionInfo": {
        "asynchronous": true,
        "generationExpression": "AI.EMBED(SOURCE_COL, connection_id => 'CONNECTION_ID', endpoint => 'ENDPOINT')",
        "stored": true
      },
      "generatedMode": "GENERATED_ALWAYS"
    },
    "name": "EMBEDDING_COL_NAME",
    "type": "RECORD"
  }
]

如果您使用內建模型而非 Agent Platform 端點，請使用類似下列 generationExpression 的語法： "AI.EMBED(SOURCE_COL, model => 'MODEL')"

如要瞭解可使用的值，請參閱「SQL」分頁中的 SOURCE_COL、EMBEDDING_COL_NAME、CONNECTION_ID、ENDPOINT 和 MODEL 說明。

將結構定義儲存至 schema.json 等檔案。

使用 bq mk --table 指令建立資料表：

bq mk --table DATASET_ID.TABLE schema.json

更改下列內容：

DATASET_ID：要在其中建立資料表的資料集名稱。
TABLE：要建立自主嵌入生成功能的資料表名稱。
COLUMN, ...：除了要自動嵌入的資料欄外，資料表應包含的所有資料欄。
STRING_COL：要自動嵌入的 STRING 資料欄名稱。
EMBEDDING_COL_NAME：系統自動產生的嵌入資料欄名稱。
CONNECTION_ID：STRING 值，其中包含要使用的連線名稱，例如 my_project.us.example_connection。您必須在建立資料表的專案中，將Agent Platform 使用者角色授予連線的服務帳戶。
ENDPOINT：STRING 值，指定要用於文字嵌入模型的支援 Agent Platform 文字嵌入模型端點。您指定的端點值必須包含模型版本，例如 text-embedding-005。如果您指定模型名稱而非網址，BigQuery ML 會自動識別模型，並使用模型的完整端點。
MODEL (預覽版)：指定內建文字嵌入模型的 STRING 值。目前僅支援「embeddinggemma-300m」模型。如果指定這個參數，就無法指定 endpoint 或 connection_id 參數。

指定 MODEL 參數後，資料會保留在 BigQuery 中，並使用您的時段建立嵌入內容；系統不會將資料傳送至 Agent Platform，也不會在 Agent Platform 中產生費用。

在現有資料表中新增自動產生的嵌入資料欄

您也可以使用 ALTER TABLE ADD COLUMN 陳述式，在現有表格中新增自動產生的嵌入欄。

SQL

使用 ALTER TABLE ADD COLUMN 陳述式，在現有資料表中新增自動產生的嵌入資料欄。如要新增資料欄，請按照下列步驟操作：

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

前往「BigQuery」
在查詢編輯器中輸入下列陳述式：
```
ALTER TABLE DATASET_ID.TABLE
  ADD COLUMN EMBEDDING_COL_NAME
    STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(
        SOURCE_COL,
        {
          connection_id => CONNECTION_ID,
          endpoint => ENDPOINT |
          model => MODEL
        })
    )
    STORED OPTIONS (asynchronous = TRUE)
;
```
請替換下列項目：
- DATASET_ID：包含資料表的資料集名稱。
- TABLE：要新增自動生成的嵌入資料欄的資料表名稱。
- EMBEDDING_COL_NAME：系統自動產生的嵌入資料欄名稱。
- SOURCE_COL：要自動嵌入的 STRING 或 ObjectRef 資料欄名稱。
- CONNECTION_ID：STRING 值，其中包含要使用的連線名稱，例如 my_project.us.example_connection。
- ENDPOINT：STRING 值，指定要用於文字嵌入模型的支援 Agent Platform 文字嵌入模型端點。
- MODEL (預覽版)：指定內建文字嵌入模型的 STRING 值。目前僅支援embeddinggemma-300m 模型。如果指定這個參數，就無法指定 endpoint 或 connection_id 參數。指定 MODEL 參數後，資料會保留在 BigQuery 中，並使用您的時段建立嵌入內容；系統不會將資料傳送至 Agent Platform，也不會在 Agent Platform 中產生費用。
按一下「執行」。

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

bq

如要使用 bq 指令列工具，將自動產生的嵌入向量資料欄新增至現有資料表，請使用 bq update 指令，並提供定義更新後資料表結構定義的 JSON 結構定義檔：

取得資料表的目前結構定義，並儲存至 schema.json 等檔案：
```
bq show --schema --format=prettyjson DATASET_ID.TABLE > schema.json
```

編輯 schema.json，加入新自動產生的嵌入欄定義。以下範例顯示根據來源資料欄定義的嵌入資料欄。這個範例會使用 Agent Platform 端點生成嵌入內容。

[
  {
    "name": "SOURCE_COL",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "result",
        "type": "FLOAT"
      },
      {
        "name": "status",
        "type": "STRING"
      }
    ],
    "generatedColumn": {
      "generationExpressionInfo": {
        "asynchronous": true,
        "generationExpression": "AI.EMBED(SOURCE_COL, connection_id => 'CONNECTION_ID', endpoint => 'ENDPOINT')",
        "stored": true
      },
      "generatedMode": "GENERATED_ALWAYS"
    },
    "name": "EMBEDDING_COL_NAME",
    "type": "RECORD"
  }
]

如果您使用內建模型而非 Agent Platform 端點，請使用類似下列 generationExpression 的語法： "AI.EMBED(SOURCE_COL, model => 'MODEL')"

如要瞭解可使用的值，請參閱「SQL」分頁中的 SOURCE_COL、EMBEDDING_COL_NAME、CONNECTION_ID、ENDPOINT 和 MODEL 說明。

使用 bq update --table 指令更新資料表：
```
bq update --table DATASET_ID.TABLE schema.json
```
請替換下列項目：
- DATASET_ID：包含資料表的資料集名稱。
- TABLE：要新增自動生成的嵌入資料欄的資料表名稱。

建立或變更資料表，或是更新來源資料欄中的資料後，系統很快就會啟動背景嵌入生成工作。

如要追蹤嵌入內容生成進度，可以使用類似下列的查詢：

SELECT
  COUNT(*) AS total_num_rows,
  COUNTIF(description_embedding IS NOT NULL
          AND description_embedding.status = '') AS total_num_generated_embeddings
FROM
  PROJECT_ID.DATASET_ID.TABLE;

取得內嵌內容的表格後，您可以在包含自動產生內嵌內容的 STRUCT 欄上建立向量索引。

範例

假設你是一家大型零售商，販售許多不同的產品。你有一份產品名稱和說明表格，希望協助顧客找到所需產品。下列查詢會說明如何設定自主嵌入項目生成功能，協助進行產品說明的語意搜尋。

首先，請建立資料集：

CREATE SCHEMA mydataset;

接著，建立啟用自主嵌入生成功能的資料表，用來儲存產品資訊。系統會根據 description 欄自動產生 description_embedding 欄。

# Create a table of products and descriptions with a generated embedding column.
CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) STORED OPTIONS( asynchronous = TRUE )
);

下列查詢會將一些產品名稱和說明插入資料表。您不必為 description_embedding 指定值，因為系統會自動產生該值。

# Insert product descriptions into the table.
# The description_embedding column is automatically updated.
INSERT INTO mydataset.products (name, description) VALUES
  ("Lounger chair", "A comfortable chair for relaxing in."),
  ("Super slingers", "An exciting board game for the whole family."),
  ("Encyclopedia set", "A collection of informational books.");

您可以視需要在資料表上建立向量索引，加快搜尋速度。向量索引需要三列以上的資料，因此下列查詢假設您已插入額外資料。每次插入資料時，系統都會自動更新 description_embedding 欄。

CREATE VECTOR INDEX my_index
ON mydataset.products(description_embedding)
OPTIONS(index_type = 'IVF');

最後，您可以使用 AI.SEARCH 函式對產品執行語意搜尋，找出有趣的玩具：

# Search for products that are fun to play with.
SELECT base.name, base.description, distance
FROM AI.SEARCH(TABLE mydataset.products, 'description', "A really fun toy");

/*------------------+----------------------------------------------+----------------------+
 | name             | description                                  | distance             |
 +------------------+----------------------------------------------+----------------------+
 | Super slingers   | An exciting board game for the whole family. | 0.80954913893618929  |
 | Lounger chair    | A comfortable chair for relaxing in.         | 0.938933930620146    |
 | Encyclopedia set | A collection of informational books.         | 1.1119297739353384   |
 +------------------+----------------------------------------------+----------------------*/

從 `ObjectRef` 欄生成的嵌入

您可以在表格中為 ObjectRef 資料欄新增產生的嵌入資料欄。

以下範例說明如何建立含有 ObjectRef 資料欄的資料表，然後為該資料欄新增產生的嵌入資料欄：

# Create a table with ObjectRef columns.
CREATE TABLE mydataset.images AS
SELECT
  REGEXP_EXTRACT(ref.uri, r'.*/(.*).jpg$') AS name,
  ref
FROM mydataset.object_table;

# Add a generated embedding column for the ObjectRef column.
ALTER TABLE mydataset.images
ADD COLUMN image_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
GENERATED ALWAYS AS (
  AI.EMBED(
    ref,
    connection_id => "us.my_connection",
    endpoint => "multimodalembedding@001")
)
STORED OPTIONS (asynchronous = true);

取得自動產生的嵌入資料欄相關資訊

如要確認資料欄是否為自動產生的嵌入資料欄，請查詢 INFORMATION_SCHEMA.COLUMNS 檢視畫面。

下列查詢會顯示所有自動產生的嵌入資料欄相關資訊：

SELECT *
FROM PROJECT_ID.DATASET_ID.INFORMATION_SCHEMA.COLUMNS
WHERE is_generated = 'ALWAYS';

generation_expression 欄位會顯示用於在資料欄中生成嵌入的 AI.EMBED 函式呼叫。

使用自己的預留項目

根據預設，BigQuery 會使用隨選運算單元處理維護所產生嵌入資料欄所需的作業。如要確保效能可預測且一致，您可以選擇建立預留項目，並將 job_type 設為 BACKGROUND。如果存在背景預留項目，BigQuery 會改用該項目維護產生的嵌入資料欄。

配額

使用 Agent Platform 端點生成嵌入項目時，請在 AI.EMBED 函式中指定 endpoint 參數，BigQuery 就會將要求傳送至 Agent Platform，生成嵌入項目。這些要求受Agent Platform 配額限制。嵌入模型每分鐘的要求配額會直接影響背景嵌入生成工作的輸送量。如果產生嵌入內容的速度緩慢，請按照「要求增加配額」一文中的說明，為 Agent Platform 申請提高配額上限。如果在 AI.EMBED 函式中指定 model 參數，系統會在 BigQuery 中產生嵌入內容，且不會傳送任何要求至 Agent Platform，因此不適用 Agent Platform 配額。

疑難排解

產生的嵌入資料欄包含兩個欄位：result 和 status。如果 BigQuery 嘗試為資料表中的特定資料列產生嵌入時發生錯誤，result 欄位會顯示 NULL，status 欄位則會說明錯誤。舉例來說，如果來源資料欄是 NULL，則 result 嵌入也是 NULL，狀態為 NULL value is not supported for embedding generation。

如果發生更嚴重的錯誤，可能會導致嵌入生成作業停滯。在這種情況下，您可以查詢INFORMATION_SCHEMA.COLUMNS 檢視中的 async_generation_status 欄，找出造成封鎖的錯誤。

封鎖錯誤可能包括：

權限遭拒錯誤
找不到錯誤
不支援的嵌入模型端點錯誤
Vertex AI API 未啟用錯誤

下一個嵌入生成作業成功後，系統會清除 async_generation_status 欄。

下列查詢顯示如何檢查封鎖錯誤：

SELECT
  column_name,
  async_generation_status
FROM
  mydataset.INFORMATION_SCHEMA.COLUMNS
WHERE
  table_name = 'images';

如果 image_embedding 欄發生封鎖錯誤，結果會類似下列內容：

[
  {
    "column_name": "image_embedding",
    "async_generation_status": {
      "blocking_error": {
        "message": "<service_account> does not have the permission to access resources used by AI.EMBED. Please follow https://cloud.google.com/bigquery/docs/permissions-for-ai-functions to set up permissions.",
        ...
      }
    }
  }
]

您也可以查詢背景工作的 INFORMATION_SCHEMA.JOBS 檢視畫面，並查看 error_result 欄位中的資訊。背景嵌入工作 ID 的前置字串為 gc_。舉例來說，下列查詢會擷取錯誤結果不是 NULL 的所有背景工作：

SELECT * FROM `region-REGION.INFORMATION_SCHEMA.JOBS` j
WHERE EXISTS (
  SELECT 1
  FROM unnest(j.referenced_tables) t
  WHERE
    j.project_id = 'PROJECT_ID'
    AND t.dataset_id = 'DATASET_ID'
    AND t.table_id = 'TABLE'
)
AND starts_with(job_id, 'gc')
AND error_result IS NOT NULL
ORDER BY j.creation_time DESC;

追蹤費用

自主嵌入生成費用分為以下幾類。

BigQuery 背景 DML 費用

系統會使用背景 DML 工作，將生成的嵌入寫入資料表。根據預設，BigQuery 會使用隨選運算單元處理這些工作。系統會按照 DML 以量計價模式，向資料表的專案收取費用。

或者，如要確保效能穩定一致，可以建立預留項目，並將 job_type 設為 BACKGROUND。如果存在背景預留項目，BigQuery 會使用該項目執行背景 DML 工作。背景預留項目會針對背景 DML 工作的運算單元時間用量收費。

如要追蹤資料表背景 DML 作業的 total_slot_ms 和 total_bytes_billed 值，請查詢 INFORMATION_SCHEMA.JOBS 檢視區塊，找出 job_id 前置字元為 gc_ 的作業：

SELECT
  job_id,
  creation_time,
  reservation_id,
  total_slot_ms,
  total_bytes_processed,
  total_bytes_billed
FROM
  `region-REGION.INFORMATION_SCHEMA.JOBS` j
WHERE
  EXISTS (
    SELECT 1
    FROM UNNEST(j.referenced_tables) t
    WHERE
      j.project_id = 'PROJECT_ID'
      AND t.dataset_id = 'DATASET_ID'
      AND t.table_id = 'TABLE'
  )
  AND STARTS_WITH(job_id, 'gc_')
ORDER BY
  j.creation_time DESC;