Obtenir des embeddings de texte

Ce document explique comment créer un embedding textuel à l'aide de l' API Text embeddings de la plate-forme d'agent Gemini Enterprise.

L'API Text embeddings de la plate-forme d'agent Gemini Enterprise utilise des représentations vectorielles denses: par exemple, gemini-embedding-001 utilise des vecteurs de 3 072 dimensions. Les modèles d'embedding vectoriels (ou "plongement vectoriel") denses utilisent des méthodes de deep learning semblables à celles utilisées par les grands modèles de langage. Contrairement aux vecteurs creux, qui ont tendance à mapper directement les mots à des nombres, les vecteurs denses sont conçus pour mieux représenter le sens d'un extrait de texte. L'utilisation d'embeddings denses dans l'IA générative fait qu'au lieu de rechercher des correspondances directes de mots ou de syntaxe, vous pouvez mieux rechercher des passages correspondant au sens de la requête, même si les passages n'utilisent pas la même langue.

Les vecteurs sont normalisés. Vous pouvez donc utiliser la similarité cosinus, le produit scalaire ou la distance euclidienne pour fournir les mêmes classements de similarité.

• Pour en savoir plus sur les embeddings, consultez la présentation des API d'embeddings.
• Pour en savoir plus sur les modèles d'embeddings textuels, consultez Embeddings de texte.
• Pour en savoir plus sur les langues compatibles avec chaque modèle d'embedding, consultez Langues de texte compatibles.

Pour voir un exemple d'obtention d'embeddings textuels, exécutez le notebook "Premiers pas avec les embeddings textuels et la recherche vectorielle de l'Agent Platform" dans l'un des environnements suivants :

Ouvrir dans Colab | Ouvrir dans Colab Enterprise | Ouvrir dans Agent Platform Workbench | Afficher sur GitHub

Avant de commencer

Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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 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 Agent Platform 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. Choisissez un type de tâche pour votre job d'embeddings.

Limites d'API

Pour chaque requête, vous êtes limité à 250 textes d'entrée. L'API a une limite maximale de jetons d'entrée de 20 000. Les entrées qui dépassent cette limite entraînent une erreur 400. Chaque texte d'entrée individuel est également limité à 2 048 jetons. Tout excès est tronqué en mode silencieux. Vous pouvez également désactiver la troncature en mode silencieux en définissant autoTruncate sur false.

Pour en savoir plus, consultez Limites d'embedding textuel.

Obtenir des embeddings de texte pour un extrait de texte

Vous pouvez obtenir des embedding textuels pour un extrait de texte à l'aide de l'API Agent Platform ou du SDK Agent Platform pour Python.

Choisir une dimension d'embedding

Par défaut, tous les modèles produisent un vecteur d'embedding complet. Pour gemini-embedding-001, ce vecteur comporte 3 072 dimensions, et les autres modèles produisent des vecteurs de 768 dimensions. Toutefois, à l'aide du paramètre output_dimensionality, les utilisateurs peuvent contrôler la taille du vecteur d'embedding de sortie. La sélection d'une dimensionnalité de sortie plus petite peut permettre d'économiser de l'espace de stockage et d'accroître l'efficacité de calcul pour les applications en aval, tout en sacrifiant peu de qualité.

Les exemples suivants utilisent le modèle gemini-embedding-001.

Python

Installer

pip install --upgrade google-genai

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :

# 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

Découvrez comment installer ou mettre à jour le Go.

Pour en savoir plus, lisez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :

# 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

Installer

npm install @google/genai

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :

# 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

Découvrez comment installer ou mettre à jour le Java.

Pour en savoir plus, lisez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :

# 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

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

• PROJECT_ID : votre [ID du projet](/resource-manager/docs/creating-managing-projects#identifiers). .
• TEXT : texte pour lequel vous souhaitez générer des embeddings. Limite : cinq textes de 2 048 jetons maximum par texte pour tous les modèles, à l'exception de textembedding-gecko@001. La longueur maximale de jeton d'entrée pour textembedding-gecko@001 est de 3 072. Pour gemini-embedding-001, chaque requête ne peut inclure qu'un seul texte d'entrée. Pour en savoir plus, consultez Limites d'embedding textuel.
• AUTO_TRUNCATE : si la valeur est false, le texte dépassant la limite de jetons entraîne l'échec de la requête. La valeur par défaut est true.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON semblable à la suivante. Notez que values a été tronqué pour gagner de la place.

Réponse

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

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

Modèles compatibles

Les tableaux suivants présentent les modèles d'embedding textuel Google et ouverts disponibles.

Modèles Google

Vous pouvez obtenir des embeddings textuels à l'aide des modèles suivants :

Nom du modèle	Description	Dimensions de sortie	Longueur maximale de la séquence	Langues de texte compatibles
gemini-embedding-001	Performances de pointe pour les tâches en anglais, multilingues et de code. Il unifie les modèles précédemment spécialisés tels que text-embedding-005 et text-multilingual-embedding-002, et offre de meilleures performances dans leurs domaines respectifs. Pour en savoir plus, consultez notre rapport technique.	Jusqu'à 3 072	2 048 jetons	Langues de texte compatibles
text-embedding-005	Spécialisé dans les tâches en anglais et de code.	Jusqu'à 768	2 048 jetons	Anglais
text-multilingual-embedding-002	Spécialisé dans les tâches multilingues.	Jusqu'à 768	2 048 jetons	Langues de texte compatibles

Pour une qualité d'embedding supérieure, gemini-embedding-001 est notre grand modèle conçu pour offrir les meilleures performances.

Modèles ouverts

Vous pouvez obtenir des embeddings textuels à l'aide des modèles suivants :

Nom du modèle	Description	Dimensions de sortie	Longueur maximale de la séquence	Langues de texte compatibles
multilingual-e5-small	Fait partie de la famille de modèles d'embedding textuel E5. La petite variante contient 12 couches.	Jusqu'à 384	512 jetons	Langues disponibles
multilingual-e5-large	Fait partie de la famille de modèles d'embedding textuel E5. La grande variante contient 24 couches.	Jusqu'à 1 024	512 jetons	Langues disponibles

Pour commencer, consultez la fiche du modèle de la famille E5 model card. Pour en savoir plus sur les modèles ouverts, consultez Modèles ouverts pour MaaS.

Ajouter un embedding à une base de données vectorielle

Une fois que vous avez généré votre embedding, vous pouvez en ajouter à une base de données vectorielle, telle que Vector Search. Cela permet une récupération à faible latence, ce qui devient essentiel à mesure que la taille de vos données augmente.

Pour en savoir plus sur Vector Search, consultez la page Présentation de Vector Search.

Étape suivante

• Pour en savoir plus sur les limites de débit, consultez Limites de débit de la plate-forme d'agent.
• Pour obtenir des prédictions par lots pour les embeddings, consultez Obtenir des inférences d'embeddings textuels par lots
  • Pour en savoir plus sur les embeddings multimodaux, consultez Obtenir des embeddings multimodaux.
• Pour régler un embedding, consultez Régler les embeddings textuels.
• Pour en savoir plus sur les recherches concernant text-embedding-005 et text-multilingual-embedding-002, consultez l'étude Gecko : embeddings textuels polyvalents distillés à partir de grands modèles de langage.