歡迎使用 Firebase Data Connect 的向量相似度搜尋功能。這是 Firebase 實作的語意搜尋功能，可與 Google Vertex AI 整合。
這項功能的核心是向量嵌入，也就是代表文字或媒體語意的浮點數陣列。使用輸入向量嵌入執行最鄰近搜尋，即可找出所有語意相似的內容。Data Connect 使用 PostgreSQL 的 pgvector 擴充功能來提供這項功能。
這項強大的語意搜尋功能可支援推薦引擎和搜尋引擎等用途。在生成式 AI 流程中，這也是檢索增強生成的重要元件。如要瞭解詳情，請參閱 Vertex AI 說明文件。
您可以依賴 Data Connect 的內建支援功能，使用 Vertex AI 的 Embeddings API 自動生成向量嵌入，也可以使用該 API 手動生成。
事前準備
為專案設定資料連結。
啟用 Vertex AI API。
設定
您可以選擇本機開發流程 (如果您是網頁、Kotlin Android 或 iOS 開發人員)，或是 IDX 流程 (適用於網頁開發人員)。您可以使用本機資料庫或實際工作環境的 Data Connect 專案，以及該專案的 PostgreSQL 適用的 Cloud SQL 執行個體進行開發。
這些操作說明假設您已Data Connect按照快速入門指南建立專案。
與本機 PostgreSQL 整合
- 設定本機 PostgreSQL 執行個體。
- 授予自己 Vertex AI 使用者 IAM 角色。
- 在環境中設定 Google Cloud 應用程式預設憑證。
- 在本地 PostgreSQL 執行個體中安裝
pgvector擴充功能。 - 按照
pgvector存放區的操作說明，使用CREATE EXTENSION vector啟用擴充功能。
與 IDX 整合
- 使用「資料連結」範本設定 IDX 工作區。
- 授予自己 Vertex AI 使用者 IAM 角色。
- 按照
pgvector存放區的操作說明，使用CREATE EXTENSION vector啟用擴充功能。
設計結構定義
如要執行向量搜尋，請在結構定義中新增 Vector 類型的欄位。舉例來說，如果您想使用電影說明進行語意搜尋，請新增欄位來保存與電影說明相關聯的向量嵌入。在這個結構定義中，descriptionEmbedding 會新增至 description 欄位，用來儲存向量嵌入。
type Movie @table {
id: ID! @col(name: "movie_id") @default(id: ID! @col(name: "movie_id") @default(expr: "uuidV4()")
title: String!
description: String
descriptionEmbedding: Vector! @col(size:768)
// ...
}
生成及擷取嵌入
Data Connect 整合支援向量嵌入，並提供 _embed 伺服器值。這會指示 Data Connect 透過內部呼叫 Vertex AI 的 Embedding API，生成向量嵌入。_embed 伺服器值可用於突變和查詢。
異動
透過 Data Connect 生成及儲存嵌入
在向量搜尋應用程式中，您可能會想在將記錄新增至資料庫後，立即要求生成嵌入。以下 createMovie 變異會在 Movie 資料表中新增電影記錄，並傳遞含有指定嵌入 model 的電影說明。
mutation createMovie($title: String!, $description: String!) {
movie_insert(data: {
title: $title,
description: $description,
descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
})
}
有時你可能需要更新電影說明和嵌入內容。
mutation updateDescription($id: String!, $description: String!) {
movie_update(id: $id, data: {
description: $description,
descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
})
}
如要從用戶端呼叫後者變動，請執行下列操作：
import { updateMovieDescription } from 'lib/dataconnect-sdk/';
await updateMovieDescription({ id: movieId, description: description});
// Use the response
查詢
使用類似下方的查詢擷取向量嵌入。請注意，查詢傳回的 descriptionEmbedding 是浮點數陣列，通常無法供人解讀。因此，Data Connect 產生的 SDK 不支援直接傳回。
如要使用傳回的向量嵌入項目進行相似度搜尋，請參閱下一節。
query getMovieDescription($id: String!) @auth(level: PUBLIC) {
movie(id: $id)
id
description
descriptionEmbedding
}
執行相似度搜尋
現在可以執行相似性搜尋。
針對每個 Vector 欄位，Data Connect 會產生實作相似度搜尋的 GraphQL 函式。這個產生的函式名稱為 ${pluralType}_${vectorFieldName}_similarity。如以下範例和參考清單所示，這項函式支援幾個參數。
您可以定義會叫用相似性搜尋的 GraphQL 函式。如上所述，_embed 伺服器值會指示 Data Connect 使用 Vertex AI 的 Embedding API 生成向量嵌入，在本例中，是為用於與電影說明嵌入進行比較而使用的搜尋字串建立嵌入。
在這個範例中，相似度搜尋最多會傳回 5 部電影，這些電影的說明在語意上與輸入查詢最接近。結果集會依距離遞增排序，從最近到最遠。
query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare_embed: {model: "textembedding-gecko@003", text: $query},
where: {content: {ne: "No info available for this movie."}}, limit: 5)
{
id
title
description
}
}
調整相似度查詢
搜尋參數 (例如 method 和 within) 的預設值適用於大多數用途。不過，如果查詢傳回的結果差異過大，或是缺少您想納入的結果，請嘗試調整這些參數。
如要找出 within 的適當值，我們可以將 _metadata.distance 新增至所選欄位，查看每個結果與查詢向量的距離。根據傳回的 distance 值，我們可以設定 within 參數；只有距離小於 within 值的結果會納入：
query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare_embed: {model: "textembedding-gecko@003", text: $query},
within: 2,
where: {content: {ne: "No info available for this movie."}}, limit: 5)
{
id
title
description
_metadata {
distance
}
}
}
您也可以設定 method 參數，嘗試使用不同的距離函式。
query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare_embed: {model: "textembedding-gecko@003", text: $query},
within: .5,
method: COSINE,
where: {content: {ne: "No info available for this movie."}}, limit: 5)
{
id
title
description
_metadata {
distance
}
}
}
請注意，不同方法傳回的距離值差異很大：如果您已設定 within，變更 method 後，您需要再次調整該值。
呼叫相似度查詢
如要從用戶端程式碼呼叫相似性搜尋：
import { searchMovieDescriptionUsingL2similarity} from 'lib/dataconnect-sdk';
const response = await searchMovieDescriptionUsingL2similarity({ query });
// Use the response
使用自訂嵌入內容
Data Connect 也可讓您直接使用嵌入做為 Vector，而不必使用 _embed 伺服器值來產生嵌入。
儲存自訂嵌入內容
使用 Vertex Embeddings API 時，請指定相符的模型，並要求正確維度的嵌入結果。
接著，將傳回的浮點數陣列轉換為 Vector，傳遞至更新作業以供儲存。
mutation updateDescription($id: String!, $description: String!, $descriptionEmbedding: Vector!) {
movie_update(id: $id, data: {
// title, genre...
description: $description,
descriptionEmbedding: $descriptionEmbedding
})
}
使用自訂嵌入執行相似度搜尋
執行相同作業，擷取搜尋字詞的嵌入，並將其轉換為 Vectors。
接著，呼叫 _similarity 查詢來執行各項搜尋。
query searchMovieDescriptionUsingL2Similarity($compare: Vector!, $within: Float, $excludesContent: String, $limit: Int) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare: $compare,
method: L2,
within: $within,
where: {content: {ne: $excludesContent}}, limit: $limit)
{
id
title
description
}
}
部署至正式環境
部署結構定義和連接器
在典型的 Data Connect 疊代中，最後一個步驟是將資產部署至正式環境。
使用 firebase deploy 指令將含有 Vector 類型的結構定義部署至 Cloud SQL 時，Firebase CLI 會採取必要步驟，在 Cloud SQL 執行個體上啟用以 Vertex AI 為基礎的嵌入項目生成功能。
firebase deploy --only dataconnect如要手動在 CloudSQL 執行個體中啟用嵌入支援功能，或遇到 CLI 錯誤，請按照這些操作說明操作。
向量搜尋語法
結構定義擴充功能
Data Connect 的 Vector 資料類型會對應至 pgvector 擴充功能定義的 PostgreSQL vector 型別。pgvector 的 vector 型別會以單精度浮點數陣列的形式儲存在 PostgreSQL 中。
在 Data Connect 中，Vector 類型會以 JSON 數字陣列表示。輸入內容會強制轉換為 float32 個值的陣列。如果強制轉型失敗，就會發出錯誤。
使用 @col 指令的 size 參數設定向量的尺寸。
type Question @table {
text: String!
category: String!
textEmbedding: Vector! @col(size: 768)
}
size 僅支援 Vector 類型。Vector 作業 (例如相似度搜尋) 需要所有 Vector 具有相同維度數量。
directive @col(
# … existing args
"""
Defines a fixed column size for certain scalar types.
- For Vector, size is required.
- For all other types, size is currently unsupported and hence supplying it will result in a schema error.
"""
size: Int
) on FIELD_DEFINITION
查詢和突變的 _embed 伺服器值
_embed
這個伺服器值會指示 Data Connect 服務使用 Vertex AI 的 Embedding API 生成及儲存嵌入項目。這個伺服器值可用於查詢和變動。
相似度搜尋的參數
method: COSINE|INNER_PRODUCT|L2
用於搜尋鄰近鄰居的距離函式。目前支援的演算法是 pgvector 搜尋演算法的子集。
within: float
最鄰近搜尋的距離限制。
where: FDC filter condition
請參閱結構定義、查詢和變動指南。
limit: int
要傳回的結果數。