取得文字嵌入

本文說明如何使用 Vertex AI Text Embeddings API 建立文字嵌入。

Vertex AI 文字嵌入 API 使用密集向量表示法：以 gemini-embedding-001 為例，使用 3072 維度的向量。密集向量嵌入模型使用的深度學習方法，與大型語言模型類似。稀疏向量通常會直接將字詞對應至數字，而密集向量則旨在更準確地表示一段文字的意義。在生成式 AI 中使用密集向量嵌入的優點是，您不必搜尋直接相符的字詞或語法，而是可以更有效地搜尋與查詢意義一致的段落，即使這些段落使用的語言不同也沒關係。

向量經過正規化，因此您可以使用餘弦相似度、點積或歐氏距離，提供相同的相似度排名。

• 如要進一步瞭解嵌入，請參閱 Embeddings API 總覽。
• 如要瞭解文字嵌入模型，請參閱文字嵌入。
• 如要瞭解各個嵌入模型支援哪些語言，請參閱「支援的文字語言」。

如要查看取得文字嵌入的範例，請在下列其中一個環境中執行「Getting Started with Text Embeddings + Vertex AI Vector Search」(開始使用文字嵌入 + Vertex AI Vector Search) 筆記本：

在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Vertex AI Workbench 中開啟 | 在 GitHub 上查看

事前準備

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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. 為嵌入工作選擇工作類型。

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

from google import genai
from google.genai.types import EmbedContentConfig

client = genai.Client()
response = client.models.embed_content(
    model="gemini-embedding-001",
    contents=[
        "How do I get a driver's license/learner's permit?",
        "How long is my driver's license valid for?",
        "Driver's knowledge test study guide",
    ],
    config=EmbedContentConfig(
        task_type="RETRIEVAL_DOCUMENT",  # Optional
        output_dimensionality=3072,  # Optional
        title="Driver's License",  # Optional
    ),
)
print(response)
# Example response:
# embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
# statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
# metadata=EmbedContentMetadata(billable_character_count=112)

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

import (
	"context"
	"fmt"
	"io"

	"google.golang.org/genai"
)

// generateEmbedContentWithText shows how to embed content with text.
func generateEmbedContentWithText(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	outputDimensionality := int32(3072)
	config := &genai.EmbedContentConfig{
		TaskType:             "RETRIEVAL_DOCUMENT",  //optional
		Title:                "Driver's License",    //optional
		OutputDimensionality: &outputDimensionality, //optional
	}

	contents := []*genai.Content{
		{
			Parts: []*genai.Part{
				{
					Text: "How do I get a driver's license/learner's permit?",
				},
				{
					Text: "How long is my driver's license valid for?",
				},
				{
					Text: "Driver's knowledge test study guide",
				},
			},
			Role: "user",
		},
	}

	modelName := "gemini-embedding-001"
	resp, err := client.Models.EmbedContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	fmt.Fprintln(w, resp)

	// Example response:
	// embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
	// statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
	// metadata=EmbedContentMetadata(billable_character_count=112)

	return nil
}

REST

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：您的專案 ID。
• TEXT：要生成嵌入的文字。限制：除了 textembedding-gecko@001 以外，所有模型最多可輸入五段文字，每段文字最多 2,048 個權杖。textembedding-gecko@001 的輸入權杖長度上限為 3072。對於 gemini-embedding-001，每項要求只能包含單一輸入文字。詳情請參閱「文字嵌入限制」。
• AUTO_TRUNCATE：如果設為 false，文字超出權杖限制會導致要求失敗。預設值為 true。

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

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 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

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 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 已遭截斷。

回應

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": false,
          "token_count": 6
        },
        "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，這是我們設計的大型模型，可提供最高效能。

注意： 請務必使用支援的機型表格中列出的型號。請勿指定不含 @version 後置字元或 @latest 的型號。這些模型名稱無效。

開放式模型

您可以使用下列模型取得文字嵌入：

模型名稱	說明	輸出尺寸	序列長度上限	支援的文字語言
multilingual-e5-small	屬於 E5 系列文字嵌入模型。小型變體包含 12 個圖層。	最多 384 個	512 個權杖	支援的語言
multilingual-e5-large	屬於 E5 系列文字嵌入模型。大型變體包含 24 層。	最多 1024 個	512 個權杖	支援的語言

如要開始使用，請參閱 E5 系列機型資訊卡。 如要進一步瞭解開放式模型，請參閱「MaaS 適用的開放式模型」

將嵌入項目新增至向量資料庫

生成嵌入後，您可以將嵌入新增至向量資料庫，例如 Vector Search。這有助於縮短擷取作業的延遲時間，而且隨著資料量增加，這項做法也變得越來越重要。

如要進一步瞭解 Vector Search，請參閱 Vector Search 總覽。

後續步驟

• 如要進一步瞭解速率限制，請參閱 Vertex AI 的生成式 AI 速率限制。
• 如要取得嵌入的批次預測結果，請參閱「取得文字嵌入的批次預測結果」
  • 如要進一步瞭解多模態嵌入，請參閱「取得多模態嵌入」
• 如要調整嵌入，請參閱「調整文字嵌入」一文。
• 如要進一步瞭解 text-embedding-005 和 text-multilingual-embedding-002 背後的研發工作，請參閱「Gecko：Versatile Text Embeddings Distilled from Large Language Models」研究論文。