Texteinbettungen abrufen

In diesem Dokument wird beschrieben, wie Sie eine Texteinbettung mit der Vertex AI Text Embeddings API erstellen.

Die Vertex AI Text Embeddings API verwendet dichte Vektordarstellungen: `gemini-embedding-001` verwendet beispielsweise 3072-dimensionale Vektoren. Für dichte Vektoreinbettungsmodelle werden Deep-Learning-Methoden verwendet, die den von Large Language Models verwendeten Methoden ähneln. Im Gegensatz zu spärlichen Vektoren, bei denen Wörter in der Regel direkt Zahlen zugeordnet werden, sind dichte Vektoren so konzipiert, dass sie die Bedeutung eines Textabschnitts besser darstellen. Der Vorteil der dichten Vektoreinbettungen in der generativen KI besteht darin, dass Sie anstelle der direkten Übereinstimmungen mit Wörtern oder Syntaxen besser nach Passagen suchen können, die der Bedeutung der Abfrage entsprechen, selbst wenn die Abschnitte nicht dieselbe Sprache verwenden.

Die Vektoren sind normalisiert, sodass Sie Kosinusähnlichkeit, Punktprodukt oder euklidische Entfernung verwenden können, um dieselben Ähnlichkeitsrankings zu erhalten.

• Weitere Informationen zu Einbettungen finden Sie in der Übersicht über Einbettungen-APIs.
• Weitere Informationen zu Texteinbettungsmodellen finden Sie unter Texteinbettungen.
• Informationen dazu, welche Sprachen die einzelnen Einbettungsmodelle unterstützen, finden Sie unter Unterstützte Text sprachen.

Ein Beispiel für das Abrufen von Texteinbettungen finden Sie im Notebook „Erste Schritte mit Texteinbettungen + Vertex AI Vector Search“ in einer der folgenden Umgebungen:

In Colab öffnen | In Colab Enterprise öffnen | In Vertex AI Workbench öffnen | Auf GitHub ansehen

Hinweis

Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Konto haben Google Cloud, erstellen Sie ein Konto, um zu testen, wie sich unsere Produkte in realen Szenarien schlagen. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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 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 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 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. Wählen Sie einen Aufgabentyp für Ihren Einbettungsjob aus.

API-Limits

Für jede Anfrage sind Sie auf 250 Eingabetexte beschränkt. Die API hat ein maximales Eingabetokenlimit von 20.000. Eingaben, die dieses Limit überschreiten, führen zu einem 400-Fehler. Jeder einzelne Eingabetext ist außerdem auf 2.048 Token beschränkt. Überschüssiges wird stillschweigend abgeschnitten. Sie können die automatische Kürzung auch deaktivieren, indem Sie autoTruncate auf false setzen.

Weitere Informationen finden Sie unter Limits für Texteinbettungen.

Texteinbettungen für ein Text-Snippet abrufen

Sie können Texteinbettungen für ein Snippet aus Text mithilfe der Vertex AI API oder dem Vertex AI SDK für Python abrufen.

Einbettungsdimension auswählen

Alle Modelle erzeugen standardmäßig einen Einbettungsvektor in voller Länge. Für gemini-embedding-001 hat dieser Vektor 3072 Dimensionen. Andere Modelle erzeugen 768-dimensionale Vektoren. Mit dem Parameter output_dimensionality können Nutzer jedoch die Größe des Ausgabeeinbettungsvektors steuern. Wenn Sie eine kleinere Ausgabedimensionalität auswählen, können Sie Speicherplatz sparen und die Recheneffizienz für nachgelagerte Anwendungen steigern, ohne die Qualität wesentlich zu beeinträchtigen.

In den folgenden Beispielen wird das Modell gemini-embedding-001 verwendet.

Python

Installieren

pip install --upgrade google-genai

Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.

Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:

# 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

Informationen zum Installieren oder Aktualisieren von Go

Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.

Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:

# 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: 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

Installieren

npm install @google/genai

Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.

Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:

# 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

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

Informationen zum Installieren oder Aktualisieren von Java

Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.

Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:

# 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 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

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• PROJECT_ID: Ihre Projekt-ID.
• TEXT: Der Text, für den Sie Einbettungen generieren möchten. Limit: fünf Texte mit bis zu 2.048 Tokens pro Text für alle Modelle außer textembedding-gecko@001. Die maximale Länge des Eingabetokens für textembedding-gecko@001 beträgt 3.072. Für gemini-embedding-001 kann jede Anfrage nur einen einzelnen Eingabetext enthalten. Weitere Informationen finden Sie unter Limits für Texteinbettungen.
• AUTO_TRUNCATE: Wenn auf false gesetzt, schlägt Text, der das Tokenlimit überschreitet, fehl. Der Standardwert ist true.

HTTP-Methode und URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict

JSON-Text der Anfrage:

{
  "instances": [
    { "content": "TEXT"}
  ],
  "parameters": { 
    "autoTruncate": AUTO_TRUNCATE 
  }
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt haben, die Sie automatisch in der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten: Beachten Sie, dass values gekürzt wurde, um Speicherplatz zu sparen.

Antwort

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": false,
          "token_count": 6
        },
        "values": [ ... ]
      }
    }
  ]
}

Beispiel: cURL-Befehls

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?"}
  ],
}'

Unterstützte Modelle

In den folgenden Tabellen sind die verfügbaren Google- und Open-Source-Modelle für Texteinbettungen aufgeführt.

Google-Modelle

Sie können Texteinbettungen mit den folgenden Modellen abrufen:

Modellname	Beschreibung	Ausgabedimensionen	Maximale Sequenzlänge	Unterstützte Textsprachen
gemini-embedding-001	Hervorragende Leistung bei Aufgaben in englischer Sprache, mehrsprachigen Aufgaben und Codeaufgaben. Es vereint die bisherigen Spezialmodelle wie text-embedding-005 und text-multilingual-embedding-002 und erzielt in den jeweiligen Bereichen eine bessere Leistung. Weitere Informationen finden Sie in unserem technischen Bericht.	bis zu 3072	2048 Tokens	Unterstützte Textsprachen
text-embedding-005	Spezialisiert auf Aufgaben in englischer Sprache und Codeaufgaben.	bis zu 768	2048 Tokens	Englisch
text-multilingual-embedding-002	Spezialisiert auf mehrsprachige Aufgaben.	bis zu 768	2048 Tokens	Unterstützte Textsprachen

gemini-embedding-001 ist unser großes Modell, das für höchste Leistung entwickelt wurde und eine hervorragende Einbettungsqualität bietet.

Offene Modelle

Sie können Texteinbettungen mit den folgenden Modellen abrufen:

Modellname	Beschreibung	Ausgabedimensionen	Maximale Sequenzlänge	Unterstützte Textsprachen
multilingual-e5-small	Teil der E5-Familie von Modellen für Texteinbettungen. Die kleine Variante enthält 12 Ebenen.	Bis zu 384	512 Tokens	Unterstützte Sprachen
multilingual-e5-large	Teil der E5-Familie von Modellen für Texteinbettungen. Die große Variante enthält 24 Ebenen.	Bis zu 1024	512 Tokens	Unterstützte Sprachen

Informationen zum Einstieg finden Sie auf der Modellkarte der E5-Familie. Weitere Informationen zu offenen Modellen finden Sie unter Offene Modelle für MaaS

Einbettung zu einer Vektordatenbank hinzufügen

Nachdem Sie die Einbettung generiert haben, können Sie sie einer Vektordatenbank wie der Vektorsuche hinzufügen. Dies ermöglicht einen Abruf mit niedriger Latenz und ist von entscheidender Bedeutung, wenn die Größe Ihrer Daten zunimmt.

Weitere Informationen zur Vektorsuche finden Sie unter Übersicht über die Vektorsuche.

Nächste Schritte

• Weitere Informationen zu Ratenlimits finden Sie unter Generative KI auf Vertex AI Ratenlimits.
• Informationen zum Abrufen von Batchvorhersagen für Einbettungen finden Sie unter Vorhersagen für Batch-Texteinbettungen abrufen
  .
  • Weitere Informationen zu multimodalen Einbettungen finden Sie unter Multimodale Einbettungen abrufen.
• Informationen zum Optimieren einer Einbettung finden Sie unter Texteinbettungen abstimmen.
• Weitere Informationen zur Forschung hinter text-embedding-005 und text-multilingual-embedding-002 finden Sie im Forschungsartikel Gecko: Versatile Text Embeddings Distilled from Large Language Models.