本文說明如何使用 Vertex AI Text Embeddings API 建立文字嵌入。
Vertex AI 文字嵌入 API 使用密集向量表示法:以 gemini-embedding-001 為例,使用 3072 維度的向量。密集向量嵌入模型使用的深度學習方法,與大型語言模型類似。稀疏向量通常會直接將字詞對應至數字,而密集向量則旨在更準確地表示一段文字的意義。在生成式 AI 中使用密集向量嵌入的優點是,您不必搜尋直接相符的字詞或語法,而是可以更有效地搜尋與查詢意義一致的段落,即使這些段落使用的語言不同也沒關係。
向量經過正規化,因此您可以使用餘弦相似度、點積或歐氏距離,提供相同的相似度排名。
- 如要進一步瞭解嵌入,請參閱 Embeddings API 總覽。
- 如要瞭解文字嵌入模型,請參閱文字嵌入。
- 如要瞭解各個嵌入模型支援哪些語言,請參閱「支援的文字語言」。
事前準備
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Enable the Vertex AI API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Enable the Vertex AI API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. - 為嵌入工作選擇工作類型。
- PROJECT_ID:您的專案 ID。
- TEXT:要生成嵌入的文字。限制:除了
textembedding-gecko@001
以外,所有模型最多可輸入五段文字,每段文字最多 2,048 個權杖。textembedding-gecko@001
的輸入權杖長度上限為 3072。對於gemini-embedding-001
,每項要求只能包含單一輸入文字。詳情請參閱「文字嵌入限制」。 - AUTO_TRUNCATE:如果設為
false
,文字超出權杖限制會導致要求失敗。預設值為true
。 - 如要進一步瞭解速率限制,請參閱 Vertex AI 的生成式 AI 速率限制。
- 如要取得嵌入的批次預測結果,請參閱「取得文字嵌入的批次預測結果」
- 如要進一步瞭解多模態嵌入,請參閱「取得多模態嵌入」
- 如要調整嵌入,請參閱「調整文字嵌入」一文。
- 如要進一步瞭解
text-embedding-005
和text-multilingual-embedding-002
背後的研發工作,請參閱「Gecko:Versatile Text Embeddings Distilled from Large Language Models」研究論文。
API 上限
每個要求最多只能有 250 個輸入文字。API 的輸入權杖上限為 20,000 個。如果輸入內容超過這項限制,系統就會傳回 400 錯誤。此外,每個輸入文字的詞元數上限為 2048 個,超過上限的文字會遭到截斷。如要停用無聲截斷功能,請將 autoTruncate
設為 false
。
詳情請參閱「文字嵌入限制」。
取得文字片段的文字嵌入
您可以使用 Vertex AI API 或 Python 適用的 Vertex AI SDK,取得文字片段的文字嵌入。
選擇嵌入維度
所有模型預設都會生成完整長度的嵌入向量。以 gemini-embedding-001
來說,這個向量有 3072 個維度,其他模型則會產生 768 維度的向量。不過,使用者可以透過 output_dimensionality
參數,控制輸出嵌入向量的大小。選取較小的輸出維度可節省儲存空間,並提高下游應用程式的運算效率,同時幾乎不會犧牲品質。
下列範例使用 gemini-embedding-001
模型。
Python
安裝
pip install --upgrade google-genai
詳情請參閱 SDK 參考說明文件。
設定環境變數,透過 Vertex AI 使用 Gen AI SDK:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Go
瞭解如何安裝或更新 Go。
詳情請參閱 SDK 參考說明文件。
設定環境變數,透過 Vertex AI 使用 Gen AI SDK:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
REST
使用任何要求資料之前,請先替換以下項目:
HTTP 方法和網址:
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict
JSON 要求主體:
{ "instances": [ { "content": "TEXT"} ], "parameters": { "autoTruncate": AUTO_TRUNCATE } }
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json
的檔案中,然後執行下列指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict"
PowerShell
將要求主體儲存在名為 request.json
的檔案中,然後執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict" | Select-Object -Expand Content
您應該會收到類似如下的 JSON 回應。請注意,為節省空間,values
已遭截斷。
cURL 指令範例
MODEL_ID="gemini-embedding-001"
PROJECT_ID=PROJECT_ID
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/${MODEL_ID}:predict -d \
$'{
"instances": [
{ "content": "What is life?"}
],
}'
支援的模型
下表列出可用的 Google 和開放式文字嵌入模型。
Google 模型
您可以使用下列模型取得文字嵌入:
模型名稱 | 說明 | 輸出維度 | 序列長度上限 | 支援的文字語言 |
---|---|---|---|---|
gemini-embedding-001 |
在英文、多語言和程式碼工作方面表現優異。這項模型整合了先前的專用模型 (例如 text-embedding-005 和 text-multilingual-embedding-002 ),並在各自的領域中展現更出色的效能。詳情請參閱我們的技術報告。 |
最多 3072 個 | 2048 個符記 | 支援的文字語言 |
text-embedding-005 |
專精於英文和程式碼工作。 | 最多 768 個 | 2048 個符記 | 英文 |
text-multilingual-embedding-002 |
擅長處理多語言工作。 | 最多 768 個 | 2048 個符記 | 支援的文字語言 |
如要取得最佳嵌入品質,請使用 gemini-embedding-001
,這是我們設計的大型模型,可提供最高效能。
開放式模型
您可以使用下列模型取得文字嵌入:
模型名稱 | 說明 | 輸出尺寸 | 序列長度上限 | 支援的文字語言 |
---|---|---|---|---|
multilingual-e5-small |
屬於 E5 系列文字嵌入模型。小型變體包含 12 個圖層。 | 最多 384 個 | 512 個權杖 | 支援的語言 |
multilingual-e5-large |
屬於 E5 系列文字嵌入模型。大型變體包含 24 層。 | 最多 1024 個 | 512 個權杖 | 支援的語言 |
如要開始使用,請參閱 E5 系列機型資訊卡。 如要進一步瞭解開放式模型,請參閱「MaaS 適用的開放式模型」
將嵌入項目新增至向量資料庫
生成嵌入後,您可以將嵌入新增至向量資料庫,例如 Vector Search。這有助於縮短擷取作業的延遲時間,而且隨著資料量增加,這項做法也變得越來越重要。
如要進一步瞭解 Vector Search,請參閱 Vector Search 總覽。