本頁面由 Cloud Translation API 翻譯而成。

使用向量嵌入 (預先發布版)

MySQL | PostgreSQL | SQL Server

本頁詳細說明如何與 Cloud SQL 互動，建構使用向量嵌入的應用程式。

MySQL 適用的 Cloud SQL 支援儲存向量嵌入。接著，您可以建立向量搜尋索引，並對這些向量嵌入內容以及儲存在 Cloud SQL 中的其餘資料執行相似度搜尋。

向量嵌入儲存空間

您可以在資料表中建立向量嵌入資料欄，使用 MySQL 適用的 Cloud SQL 儲存向量嵌入。特殊向量嵌入資料欄會對應至 VARBINARY 資料類型。與資料表中的其他關聯資料一樣，您可以使用現有的交易保證，存取資料表中的向量嵌入。含有向量嵌入資料欄的資料表是標準的 InnoDB 資料表，因此符合完整性、一致性、獨立性和耐用性 (ACID) 屬性。只有向量搜尋索引查詢會偏離 ACID 屬性。

為向量嵌入設定資料表時，請注意下列事項：

每個資料表最多只能建立一個向量嵌入資料欄，以及一個向量搜尋索引。儲存在同一欄中的每個向量嵌入，都必須與您定義該欄時指定的維度完全相同。向量嵌入的維度上限為 16,000。如果儲存空間和記憶體足夠，您可以在同一個執行個體中，建立具有不同向量嵌入欄和向量搜尋索引的獨立資料表。
雖然資料表可儲存的向量嵌入數量沒有硬性限制，但向量搜尋索引需要記憶體。因此，我們建議您在資料表中儲存的向量嵌入內容不要超過 1 千萬個。
另請參閱「限制」一節。

向量嵌入資料欄的複製方式與其他 MySQL InnoDB 資料欄相同。

相似度搜尋

Cloud SQL 支援使用K 近鄰 (KNN) 和近似近鄰 (ANN) 搜尋查詢進行相似度搜尋。您可以在 Cloud SQL 執行個體中使用這兩種向量搜尋。您只能為 ANN 搜尋建立向量搜尋索引。

K 近鄰 (KNN) 搜尋

Cloud SQL 支援使用 KNN 向量搜尋 (也稱為精確的 K 近鄰搜尋) 查詢。執行 KNN 向量搜尋可提供完美的召回率。您不必建立向量搜尋索引，即可執行 KNN 搜尋。KNN 搜尋是根據執行資料表掃描演算法。

對於 KNN 搜尋，Cloud SQL 也支援下列向量距離搜尋函式：

餘弦
點積
L2 平方距離

如要進一步瞭解如何使用向量搜尋距離函式，請參閱「查詢向量嵌入的距離」。

最鄰近搜尋 (ANN)

Cloud SQL 支援建立向量搜尋索引，並透過這類索引建立及查詢 ANN 搜尋。ANN 向量搜尋索引可讓您著重提升搜尋速度，而非完美召回率。如要進行 ANN 搜尋，Cloud SQL 支援下列索引類型：

BRUTE_FORCE：基礎資料表的預設向量搜尋索引類型，適用於少於 10,000 列的資料表。這類資料最適合在原始資料集的一小部分子集中搜尋。索引使用的記憶體量等於資料集大小。這類索引不會儲存到磁碟。
TREE_SQ：如果基本資料表有 10,000 列以上，預設的向量搜尋索引類型就是這個。這種型別使用的記憶體量最少，約為資料集大小的 25%。TREE_SQ 索引會保留在磁碟上。
TREE_AH：一種向量搜尋索引類型，提供非對稱雜湊搜尋類型演算法。如 Cloud SQL 實作方式所示，這類索引並未針對記憶體用量進行最佳化，也不會保留。

更新向量搜尋索引

MySQL 適用的 Cloud SQL 會即時更新向量搜尋索引。對基礎資料表執行資料操縱語言 (DML) 作業的任何交易，也會將變更傳播至相關聯的向量搜尋索引。向量搜尋索引的變更會立即對所有其他交易顯示，也就是說，隔離等級為 READ_UNCOMMITTED。

如果回溯交易，向量搜尋索引也會發生相應的回溯變更。

複製向量搜尋索引

MySQL 適用的 Cloud SQL 會將向量搜尋索引複製到所有唯讀備用資源。不支援複製篩選器，也不支援將向量搜尋索引複製到串聯式備用資源。

設定執行個體以支援向量嵌入

本節說明如何設定 Cloud SQL 執行個體，以支援向量嵌入的儲存、建立索引及查詢。

Cloud SQL Enterprise 版和 Cloud SQL Enterprise Plus 版執行個體都支援向量嵌入項目。

事前準備

執行個體必須執行 MySQL 適用的 Cloud SQL MySQL 版本 8.0.36.R20240401.03_00 以上。
執行個體必須有足夠的磁碟空間來分配記憶體，才能容納執行個體上的向量嵌入總數。

啟用向量嵌入

如要啟用向量嵌入支援功能，必須設定 MySQL 資料庫旗標。

gcloud sql instances patch INSTANCE_NAME \
  --database-flags=FLAGS

將 INSTANCE_NAME 替換為要啟用向量嵌入支援功能的執行個體名稱。

在 FLAGS 中，為執行個體設定下列 MySQL 標記：

cloudsql_vector：將這個旗標設為 on，即可啟用向量嵌入儲存空間和搜尋支援功能。您可以在執行個體上建立新的向量嵌入欄和向量搜尋索引。
cloudsql_vector_max_mem_size：選用。指定執行個體上所有向量搜尋索引的記憶體分配量上限 (以位元組為單位)。如果您未指定此標記，預設記憶體分配量為 1 GB，這是最低記憶體分配量。如要進一步瞭解如何計算要指定的數量，請參閱設定向量搜尋索引的記憶體配置。

這類專屬記憶體來自於分配給 innodb_buffer_pool_size 的記憶體。可用緩衝區集區也會減少相同數量。此旗標允許的最大值為總 innodb_buffer_pool_size 的 50%。

如果您指定的值大於總容量的 50% innodb_buffer_pool_size，Cloud SQL 會將有效值調降至可用大小的 50%，並記錄執行個體的警告訊息。

設定標記後，指令可能如下所示：

gcloud sql instances patch my-instance \
  --database-flags=cloudsql_vector=on,cloudsql_vector_max_mem_size=4294967296

在 MySQL 適用的 Cloud SQL 中設定向量嵌入支援功能的旗標是靜態旗標。使用標記更新執行個體後，執行個體會自動重新啟動，設定變更才會生效。

如要進一步瞭解如何設定 MySQL 的資料庫標記，請參閱「設定資料庫標記」。

停用向量嵌入

如要停用向量嵌入，請將 cloudsql_vector 標記設為 off。

例如：

gcloud sql instances patch INSTANCE_NAME \
  --database-flags=cloudsql_vector=off

將 INSTANCE_NAME 替換為要停用向量嵌入支援的執行個體名稱。

將 cloudsql_vector 設為 off 後，您就無法建立新的向量嵌入欄和向量搜尋索引。設定這個靜態標記後，執行個體會自動重新啟動，讓設定變更生效。

執行個體重新啟動後，MySQL 適用的 Cloud SQL 會執行下列操作：

從永久磁碟中移除所有持續性 TREE_SQ 向量搜尋索引。
保留已建構向量搜尋索引的資料字典表格項目。不過，MySQL 適用的 Cloud SQL 不會重建索引，且對這些索引的任何搜尋查詢都會傳回錯誤。
繼續在基礎表格中儲存向量嵌入。向量嵌入內容仍可存取。

如果之後重新啟用執行個體的 cloudsql_vector 旗標，Cloud SQL 會根據資料字典表中的項目，在執行個體重新啟動時嘗試重建索引。

唯讀備用資源設定

如果執行個體符合維護版本和旗標啟用條件，Cloud SQL 就會完全支援唯讀備用資源上的向量嵌入。

如果您從已啟用向量嵌入支援的主要執行個體建立備用資源，唯讀備用資源會沿用主要執行個體的向量嵌入支援設定。您必須在現有的唯讀備用資源執行個體上，個別啟用向量嵌入支援功能。

就複製延遲的影響而言，建立及維護向量搜尋索引的運作方式與一般 MySQL 索引相同。

串聯式備用資源不支援向量搜尋索引。

範例：ANN 向量搜尋索引和查詢

下列逐步操作範例說明如何在 Cloud SQL 中建立 ANN 型向量搜尋索引並進行查詢。

生成向量嵌入。您可以手動建立向量嵌入，也可以使用所選的文字嵌入 API。如需使用 Vertex AI 的範例，請參閱「根據列資料產生向量嵌入」。

在 MySQL 適用的 Cloud SQL 中建立資料表，其中包含三維向量嵌入資料欄。

CREATE TABLE books (
id   INTEGER PRIMARY KEY AUTO_INCREMENT,
title VARCHAR(60),
embedding VECTOR(3) USING VARBINARY
);

在資料欄中插入向量嵌入。

INSERT INTO books VALUES (
1,
'book title',
 string_to_vector('[1,2,3]')
);

修訂變更。
```
commit;
```

建立向量搜尋索引。如要建立 TREE_SQ 或 TREE_AH 索引，表格至少要有 1,000 列。

CALL mysql.create_vector_index('vectorIndex',
                               'dbname.books',
                               'embedding',
                               'index_type=BRUTE_FORCE, distance_measure=L2_SQUARED'
                               );

取得最鄰近的項目。

SELECT title FROM books
WHERE
NEAREST(embedding) TO (string_to_vector('[1,2,3]'));

根據資料列資料生成向量嵌入

您可以使用文字嵌入 API (例如 Vertex AI 或 OpenAI)，為指定資料列的資料產生向量嵌入。您可以搭配 Cloud SQL 向量嵌入功能使用任何文字嵌入 API。不過，您必須使用相同的文字嵌入 API 來產生查詢字串向量。您無法合併使用不同的 API 來處理來源資料和查詢向量化。

舉例來說，您可以透過 Vertex AI 生成向量嵌入：

from vertexai.language_models import TextEmbeddingModel

def text_embedding() -> list:
    """Text embedding with a Large Language Model."""
    model = TextEmbeddingModel.from_pretrained("text-embedding-004")
    embeddings = model.get_embeddings(["What is life?"])
    for embedding in embeddings:
        vector = embedding.values
        print(f"Length of Embedding Vector: {len(vector)}")
    return vector

if __name__ == "__main__":
    text_embedding()

儲存向量嵌入

本節提供將向量嵌入儲存在 Cloud SQL 中的範例陳述式。

建立含有向量嵌入資料欄的新資料表

CREATE TABLE books (
  id INTEGER PRIMARY KEY AUTO_INCREMENT,
  title VARCHAR(60),
  embedding VECTOR(3) USING VARBINARY
  );

在現有資料表中新增向量嵌入欄

ALTER TABLE books
ADD COLUMN embedding
VECTOR(3) USING VARBINARY;

插入向量嵌入

INSERT INTO books (
  title,
  embedding
  ) VALUES (
    'book title',
    string_to_vector('[1,2,3]')
);

插入多個向量嵌入

INSERT INTO books (
  title,
  embedding
  ) VALUES (
    'book title',
    string_to_vector('[1,2,3]')),
     ('book title', string_to_vector('[4,5,6]')
);

插入或更新向量嵌入

INSERT INTO books (
  id,
  title,
  embedding
  ) VALUES (
    1,
    'book title',
     string_to_vector('[1,2,3]')
     )
ON DUPLICATE KEY UPDATE embedding = string_to_vector('[1,2,3]');

更新向量嵌入

UPDATE books
SET embedding = string_to_vector('[1,2,3]')
WHERE id = 1;

刪除向量嵌入

DELETE FROM books
WHERE embedding = string_to_vector('[1,2,3]');

使用向量搜尋索引

根據預設，您可以執行確切最鄰近搜尋，提供完美的召回率。您也可以新增索引來使用 ANN 搜尋，這會犧牲部分召回率來換取速度。與一般索引不同，新增近似索引後，查詢會顯示不同的結果。

建議

本節提供使用向量搜尋索引的最佳做法。每個工作負載都不盡相同，您可能需要相應調整。

建立向量搜尋索引前，請務必將資料載入資料表。基準表至少要有 1,000 列資料。這些規定僅適用於 TREE_SQ 和 TREE_AH 搜尋索引類型。如果可用的資料點越多，索引的分區和訓練效果就越好。
監控索引的記憶體用量。如果執行個體記憶體不足，就無法建立或建構任何索引。如果是現有索引，達到門檻後，Cloud SQL 會定期將警告寫入 MySQL 錯誤記錄檔。您可以在 information_schema.innodb_vector_indexes 表格中查看記憶體用量。
如果基礎資料表經過重大 DML 變更，請重建向量搜尋索引。如要取得建構時的索引初始大小和目前的索引大小，請查詢 information_schema.innodb_vector_indexes 資料表。
一般來說，將分區數量留待內部計算是可接受的做法。如果想指定分區數量，則每個分區必須至少有 100 個資料點。

向量搜尋索引作業期間的基本資料表為唯讀

在所有三項向量搜尋索引作業 (建立、變更和捨棄) 期間，基礎資料表會進入唯讀模式。執行這些作業時，您無法對基礎表格執行 DML。

持續性、關機和對維護的影響

只有使用 TREE_SQ 類型的向量搜尋索引，會在執行個體正常關機時保留在磁碟上。使用 TREE_AH 和 BRUTE_FORCE 類型的向量搜尋索引僅限於記憶體內。

執行個體正常關閉後，Cloud SQL 會在執行個體重新啟動時重新載入向量搜尋索引。不過，在系統當機或非正常關機後，Cloud SQL 必須重建向量搜尋索引。舉例來說，每當執行個體發生當機並從備份還原、時間點復原 (PITR) 或高可用性 (HA) 容錯移轉時，Cloud SQL 都會重建向量搜尋索引。發生這類事件時，會出現以下情況：

系統會在背景自動重建索引。
重建期間，基本資料表會處於唯讀模式。
如果自動重建作業無法在特定逾時期間內取得資料表鎖定，重建作業就會失敗。您可能需要改用手動方式重建索引。

重建索引所需的時間可能會增加關機所需的時間，這也可能增加執行個體所需的維護和更新時間。

設定向量搜尋索引的記憶體配置

Cloud SQL 會在記憶體中建構及維護向量搜尋索引。TREE_SQ索引類型會在正常關機時保留，並在執行個體重新啟動後重新載入。在執行階段，所有向量搜尋索引都必須保留在記憶體中。

為確保 Cloud SQL 有足夠的可用記憶體，可將所有向量搜尋索引保留在記憶體中，請使用 cloudsql_vector_max_mem_size 資料庫旗標設定 Cloud SQL 執行個體。cloudsql_vector_max_mem_size 決定 Cloud SQL 執行個體為向量搜尋索引分配多少記憶體。設定旗標值時，請注意下列事項：

預設值和最小值為 1 GB。上限為緩衝區集區大小的 50%。
設定這個標記後，執行個體會自動重新啟動，讓設定變更生效。
如果執行個體已用盡所有設定的記憶體，您就無法建立或變更任何向量搜尋索引。

如要更新例項上為向量搜尋索引分配的記憶體，請變更 cloudsql_vector_max_mem_size 標記的值。

gcloud sql instances patch INSTANCE_NAME \
  --database-flags= cloudsql_vector_max_mem_size=NEW_MEMORY_VALUE

更改下列內容：

INSTANCE_NAME：要變更記憶體配置的執行個體名稱。
NEW_MEMORY_VALUE：向量搜尋索引的更新記憶體配置 (以位元組為單位)。

這項變更會自動重新啟動執行個體，變更才會生效。

計算所需記憶體

索引所需的記憶體量取決於索引類型、向量嵌入的數量和嵌入的維度。您需要考慮兩項記憶體需求：

建構時間記憶體：建構索引時所需的記憶體。
索引記憶體：索引建構完成後佔用的記憶體。

就特定索引而言，資料集大小是指在記憶體中讀取所有向量嵌入時所需的記憶體。由於每個維度都是以浮點數表示，並使用 4 個位元組的記憶體，因此您可以按照下列方式判斷 dataset_size：

dataset_size = <num_embeddings> * (4 * <dimensions>)

舉例來說，如果您有一百萬個 768 維度的嵌入，則 dataset_size 為 3 GB。

根據上一個範例，不同索引類型的記憶體需求如下：

索引類型	建立時間記憶	索引記憶體
`TREE_SQ`	4 GB	1 GB
`TREE_AH`	3.5 GB	3.5 GB
`BRUTE_FORCE`	3 GB	3 GB

如果您使用 TREE_SQ 向量搜尋索引，也必須將執行階段持續性所需的記憶體納入考量。將最大的有效 TREE_SQ 向量搜尋索引所用的索引記憶體量，加到設定中的記憶體總量。

每當儲存向量嵌入的基本資料表進行 DML 作業時，向量搜尋索引就會即時更新。這些更新會改變索引的記憶體用量，視 DML 作業而定，記憶體用量可能會縮減或擴大。您可以查詢 information_schema.innodb_vector_indexes 資料表，監控索引的記憶體用量。如要瞭解如何監控向量搜尋索引的大小，請參閱「監控向量搜尋索引」。

建立向量搜尋索引

建立向量搜尋索引的陳述式使用下列語法：

CALL mysql.create_vector_index('INDEX_NAME',
                                'DB_NAME.TABLE_NAME',
                                'COLUMN_NAME',
                                'PARAMETERS'
                              );

例如：

CALL mysql.create_vector_index('vectorIndex',
                                'db.books',
                                'embedding',
                                'index_type=TREE_SQ, distance_measure=l2_squared'
                               );

您指定的索引名稱在資料庫中不得重複。

向量搜尋索引參數

mysql.create_vector_index 和 mysql.alter_vector_index 函式支援多個參數，您可以使用以半形逗號分隔的鍵/值組合指定參數。所有 mysql.create_vector_index 函式參數都是選用參數。如果您指定空白字串或 NULL，系統會為索引設定預設參數值。

distance_measure：支援的值為 L2_SQUARED、COSINE 和 DOT_PRODUCT。預設為 L2_SQUARED。
num_neighbors：從 ANN 查詢傳回的鄰點數量。執行搜尋查詢時，您也可以覆寫這個參數。預設值為 10。
index_type：指定要建構的索引類型。有效值為：BRUTE_FORCE、TREE_SQ 和 TREE_AH。
- 如果表格的列數少於 10,000 列，系統會預設使用 BRUTE_FORCE
- 如果表格有 10,000 個以上的資料列，系統會預設為 TREE_SQ
如要指定 TREE_AH 或 TREE_SQ 索引類型，基本資料表的大小必須超過 1,000 列。
num_parititions：指定要建構的 K 平均值叢集數量。只有在設定 index_type 時，才能使用這項參數。這個選項不適用於 BRUTE_FORCE。如果指定 TREE_SQ 或 TREE_AH 索引類型，則基本資料表的大小必須大於或等於 num_partitions * 100。

變更向量搜尋索引

CALL mysql.alter_vector_index('DB_NAME.INDEX_NAME', 'PARAMETERS');

alter_vector_index 函式會明確用於重建向量搜尋索引。如要使用這項函式，必須先建立索引。在下列情況中，您可能需要重建索引：

如要使用其他選項重建索引，舉例來說，您可能想使用不同的索引類型或距離測量方式。
由於基本資料表發生重大 DML 變更，因此需要重建索引。舉例來說，您需要根據基礎資料表中的資料重新訓練向量搜尋索引。

重建索引的所有參數都與建立索引時可用的參數相同，而且也是選用參數。如果您在重建索引時指定空字串或 NULL，系統會根據建立索引時指定的參數重建索引。如果在建立索引時未提供任何參數，系統會使用預設參數值。

現有的向量搜尋索引在 alter_vector_index 作業期間仍可使用。您仍可對索引執行搜尋查詢。

捨棄向量搜尋索引

您無法對含有向量搜尋索引的資料表執行 DDL 作業。對資料表執行 DDL 作業前，請務必先捨棄向量搜尋索引。

CALL mysql.drop_vector_index('DB_NAME.INDEX_NAME');

查詢向量嵌入

本節提供範例，說明如何以不同方式查詢向量嵌入。

查看向量嵌入

SELECT vector_to_string(embedding) FROM books;

取得向量嵌入的精確鄰近搜尋結果

SELECT id,cosine_distance(embedding,
   string_to_vector('[1,2,3]')) dist
FROM books
ORDER BY dist
LIMIT 10;

取得向量嵌入的近似鄰近搜尋結果

SELECT title FROM books
WHERE
NEAREST(embedding) TO (string_to_vector('[1,2,3]'), 'num_neighbors=10');

執行 ANN 搜尋時，最多可使用兩個參數。兩者皆為選填。

num_partitions：指定要探查 ANN 向量搜尋的分區數量。如果未指定分區數量，搜尋作業就會根據資料表大小、向量搜尋索引中的分區數量和其他因素，產生一個值。
num_neighbors：指定要傳回的鄰點數量。這個值會覆寫建立向量搜尋索引時設定的值。

篩選向量嵌入

使用額外資料欄做為述詞，微調向量嵌入查詢結果的篩選條件。舉例來說，如果您新增 printyear 欄，即可在查詢中新增特定年份值做為篩選器。

SELECT title FROM books
WHERE
NEAREST(embedding) TO (string_to_vector('[1,2,3]'))
AND printyear > 1991;

查詢向量嵌入的距離

本節提供 KNN 搜尋可用的向量距離函式範例。

取得餘弦距離

SELECT cosine_distance(embedding, string_to_vector('[3,1,2]'))
AS distance FROM books WHERE id=10;

取得點積距離

SELECT dot_product(embedding, string_to_vector('[3,1,2]'))
AS distance FROM books WHERE id=10;

取得 L2 平方距離

SELECT l2_squared_distance(embedding, string_to_vector('[3,1,2]'))
AS distance FROM books WHERE id=10;

取得特定距離內的資料列

SELECT * FROM books
WHERE l2_squared_distance(embedding, string_to_vector('[1,2,3]')) < 10;

可與 ORDER BY 和 LIMIT 搭配使用

SELECT id, vector_to_string(embedding),
       l2_squared_distance(embedding, string_to_vector('[1,2,3]')) dist
FROM books ORDER BY dist LIMIT 10;

監控 Vector Search 索引

如要取得執行個體中所有向量搜尋索引的即時資訊，請使用 information_schema.innodb_vector_indexes 資料表。

如要查看資料表，請執行下列指令：

SELECT * FROM information_schema.innodb_vector_indexes;

輸出範例可能如下所示：

*************************** 1. row ***************************
       INDEX_NAME: test.t4_index
       TABLE_NAME: test.t4_bf
       INDEX_TYPE: BRUTE_FORCE
     DIST_MEASURE: SquaredL2Distance
           STATUS: Ready
            STATE: INDEX_READY_TO_USE
       PARTITIONS: 0
SEARCH_PARTITIONS: 0
     INITIAL_SIZE: 40000
     CURRENT_SIZE: 40000
          QUERIES: 0
        MUTATIONS: 0
     INDEX_MEMORY: 160000
   DATASET_MEMORY: 0

在 information_schema.innodb_vector_indexes 表格中，您可以查看下列資訊：

系統可能生成的選項。換句話說，就是 num_partitions 或要為查詢探測的分區數量。
「STATE」和「STATUS」欄會顯示索引的目前狀態。在建構階段，狀態欄會提供向量搜尋索引在建構階段的進度資訊。
INITIAL_SIZE 欄會提供建立索引時的資料表大小。您可以比較這個大小與 CURRENT_SIZE，瞭解索引自建立以來，因基礎資料表上的 DML 而變更了多少。
QUERIES 和 MUTATIONS 欄會提供索引忙碌程度的即時洞察資訊。
INDEX_MEMORY 和 DATASET_MEMORY 欄會提供索引的記憶體用量資訊。INDEX_MEMORY 表示索引耗用的記憶體量，DATASET_MEMORY 則表示建構期間耗用的額外記憶體量。

如要取得在執行個體上建立的搜尋向量索引清單，可以查看 mysql.vector_indexes 資料字典表。