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 連線使用者 (roles/bigquery.connectionUser)
如要建立或變更資料表，請在資料表上具備 BigQuery 資料編輯者 (roles/bigquery.dataEditor) 角色
將下列角色授予連線的服務帳戶，以便存取託管於 Agent Platform 端點的模型：在連線所在的專案中，具備 Agent Platform 使用者 (roles/aiplatform.user) 角色

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

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

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

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

建立自動生成的嵌入欄

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

為自動產生的嵌入資料欄定義 AI.EMBED 函式時，如果未指定 task_type 引數，且模型支援 task_type，BigQuery 預設會將 task_type 設為 RETRIEVAL_DOCUMENT。使用 AI.SEARCH 函式或 VECTOR_SEARCH 函式查詢資料表時，BigQuery 會使用下列 task_type 行為即時生成查詢嵌入：

如果資料表的嵌入資料欄使用 RETRIEVAL_DOCUMENT (無論是預設或明確指定)，BigQuery 就會使用 RETRIEVAL_QUERY 嵌入搜尋查詢。
否則，BigQuery 會使用為資料表嵌入資料欄設定的相同 task_type。

建立資料表，並自動生成嵌入欄

您可以使用自主嵌入生成功能，在 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 指令列工具建立資料表，並自動產生嵌入資料欄，請搭配定義資料表結構定義的 JSON 結構定義檔案，使用 bq mk 指令：

建立 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。您必須在建立資料表的專案中，將代理平台使用者角色授予連線的服務帳戶。
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 指令列工具，將自動生成的嵌入欄新增至現有資料表，請搭配定義更新後資料表結構定義的 JSON 結構定義檔案，使用 bq update 指令：

取得資料表目前的結構定義，並儲存至 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_embedding，並以 description 資料欄為基礎。

# 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 函式的呼叫，該函式用於生成資料欄的嵌入，包括預設的 task_type => 'RETRIEVAL_DOCUMENT' 引數 (如果您未針對支援該引數的模型指定 task_type)。

使用自己的預留項目

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

配額

在 AI.EMBED 函式中指定 endpoint 參數，使用 Agent Platform 端點生成嵌入時，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://docs.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;