取得文字嵌入

本文說明如何使用 Gemini Enterprise Agent Platform Text embeddings API 建立文字嵌入。

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

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

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

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

在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Agent Platform Workbench 中開啟 | 在 GitHub 上查看

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

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 role (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 Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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 role (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 Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

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

API 上限

每個要求最多只能有 250 個輸入文字。API 的輸入權杖上限為 20,000 個。如果輸入內容超過這項限制，系統就會傳回 400 錯誤。此外，每個輸入文字的符記數上限為 2048 個，超出上限的文字會遭到截斷。如要停用無聲截斷功能，請將 autoTruncate 設為 false。

詳情請參閱「文字嵌入限制」。

取得文字片段的文字嵌入

您可以使用 Agent Platform API 或 Agent Platform SDK for Python，取得某段文字的文字嵌入。

選擇嵌入維度

所有模型預設都會生成完整長度的嵌入向量。對於 gemini-embedding-001，這個向量有 3072 個維度，其他模型則會產生 768 維度的向量。不過，使用者可以透過 output_dimensionality 參數，控制輸出嵌入向量的大小。選取較小的輸出維度可節省儲存空間，並提高下游應用程式的運算效率，同時不會犧牲太多品質。

下列範例使用 gemini-embedding-001 模型。

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考文件。

設定環境變數，透過 Vertex AI 使用 Google 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_ENTERPRISE=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 使用 Google 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_ENTERPRISE=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: genai.RoleUser,
		},
	}

	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
}

Node.js

安裝

npm install @google/genai

詳情請參閱 SDK 參考文件。

設定環境變數，透過 Vertex AI 使用 Google 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_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;

async function generateEmbeddingsForRetrieval(
  projectId = GOOGLE_CLOUD_PROJECT
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
  });

  const prompt = [
    "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",
  ];

  const response = await client.models.embedContent({
    model: 'gemini-embedding-001',
    contents: prompt,
    config: {
      taskType: 'RETRIEVAL_DOCUMENT', // Optional
      outputDimensionality: 3072, // Optional
      title: "Driver's License", // Optional
    },
  });

  console.log(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)

  return response;
}

Java

瞭解如何安裝或更新 Java。

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Google 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_ENTERPRISE=True

import com.google.genai.Client;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;
import java.util.List;

public class EmbeddingsDocRetrievalWithTxt {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-embedding-001";
    embedContent(modelId);
  }

  // Shows how to embed content with text.
  public static EmbedContentResponse embedContent(String modelId) {
    // Client Initialization. Once created, it can be reused for multiple requests.
    try (Client client = Client.builder().location("global").vertexAI(true).build()) {

      EmbedContentResponse response =
          client.models.embedContent(
              modelId,
              List.of(
                  "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"),
              EmbedContentConfig.builder()
                  .taskType("RETRIEVAL_DOCUMENT")
                  .outputDimensionality(3072)
                  .title("Driver's License")
                  .build());

      System.out.println(response);
      // Example response:
      // embeddings=Optional[[ContentEmbedding{values=Optional[[-0.035855383, 0.008127963, ... ]]
      // statistics=Optional[ContentEmbeddingStatistics{truncated=Optional[false],
      // tokenCount=Optional[11.0]}]}]],
      // metadata=Optional[EmbedContentMetadata{billableCharacterCount=Optional[153]}]}
      return response;
    }
  }
}

REST

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID： 您的 [專案 ID](/resource-manager/docs/creating-managing-projects#identifiers)。 。
• 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，這是專為提供最高效能而設計的大型模型。

開放式模型

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

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

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

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

生成嵌入後，您可以將嵌入新增至向量資料庫，例如 Vector Search。這可實現低延遲擷取作業，而且隨著資料量增加，這項功能就越顯重要。

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

後續步驟

• 如要進一步瞭解頻率限制，請參閱「Agent Platform 配額和系統限制」。
• 如要取得嵌入的批次預測，請參閱取得批次文字嵌入推論
  • 如要進一步瞭解多模態嵌入，請參閱「取得多模態嵌入」
• 如要調整嵌入，請參閱「調整文字嵌入」一文。
• 如要進一步瞭解 text-embedding-005 和 text-multilingual-embedding-002 背後的研發工作，請參閱「Gecko：Versatile 文字嵌入 蒸餾自 大型語言模型」研究文件。