Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

取得文字嵌入

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

Gemini Enterprise Agent Platform 文字嵌入 API 使用密集向量表示法：例如 gemini-embedding-001 使用 3072 維向量。密集向量嵌入模型使用的深度學習方法，與大型語言模型使用的方法類似。稀疏向量通常會直接將字詞對應至數字，而稠密向量則能更準確地表示文字的意義。在生成式 AI 中使用密集向量嵌入的好處是，您不必搜尋直接字詞或語法比對，而是可以更有效地搜尋與查詢意義相符的段落，即使段落不使用相同語言也沒問題。

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

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

事前準備

登入 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.

Go to project selector

Enable the Agent Platform API, if it is not already enabled.

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.

Go to project selector

Enable the Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

選擇嵌入工作的任務類型。

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。。
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 個詞元	支援的文字語言
`gemini-embedding-2`	最適合嵌入長字串，包括多語言和非結構化資料。支援文字、圖片、音訊、影片和 PDF 檔案的組合。	最多 3072	8192 個詞元	支援的文字語言
`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 文字嵌入模型系列的一員。Large 變化版本包含 24 層。	最多 1024 個	512 個詞元	支援的語言

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

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

生成嵌入後，您可以將嵌入新增至向量資料庫，例如向量搜尋。這項功能可縮短檢索延遲時間，在資料量增加時尤其重要。

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

後續步驟

如要進一步瞭解頻率限制，請參閱「Agent Platform 配額和系統限制」。
如要取得嵌入的批次預測，請參閱「取得批次文字嵌入推論」
- 如要進一步瞭解多模態嵌入，請參閱「取得多模態嵌入」
如要調整嵌入，請參閱「調整文字嵌入」
如要進一步瞭解 text-embedding-005 和 text-multilingual-embedding-002 的研究，請參閱研究論文《Gecko: Versatile Text Embeddings Distilled from Large Language Models》(Gecko：從大型語言模型提煉的多功能文字嵌入)。

取得文字嵌入 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

API 限制

取得文字片段的文字嵌入

選擇嵌入維度

Python

安裝

Go

Node.js

安裝

Java

REST

curl

PowerShell

回應

cURL 指令範例

支援的模型

Google 模型

開放式模型

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

後續步驟

取得文字嵌入