Embeddings

Les embeddings sont une représentation numérique des entrées de texte qui ouvrent la voie à un certain nombre de cas d'utilisation uniques, tels que le clustering, la mesure de similarité et la récupération d'informations. Pour obtenir une présentation, consultez le guide sur les embeddings.

Contrairement aux modèles d'IA générative qui créent de nouveaux contenus, le modèle Gemini Embedding est uniquement destiné à transformer le format de vos données d'entrée en représentation numérique. Bien que Google soit responsable de la fourniture d'un modèle d'embedding qui transforme le format de vos données d'entrée au format numérique demandé, les utilisateurs conservent l'entière responsabilité des données qu'ils saisissent et des embeddings qui en résultent. En utilisant le modèle Gemini Embedding, vous confirmez que vous disposez des droits nécessaires sur tous les contenus que vous mettez en ligne. Ne générez aucun contenu qui porte atteinte à la propriété intellectuelle ou aux droits au respect de la confidentialité d'autrui. Votre utilisation de ce service est soumise à notre Règlement sur les utilisations interdites et aux Conditions d'utilisation de Google.

Méthode : models.embedContent

Génère un vecteur d'embedding de texte à partir de l'Content d'entrée à l'aide du modèle d'embedding Gemini spécifié.

Point de terminaison

post https://generativelanguage.googleapis.com/v1beta/{model=models/*}:embedContent

Paramètres de chemin d'accès

model string

Obligatoire. Nom de ressource du modèle. Il sert d'ID au modèle.

Ce nom doit correspondre à un nom de modèle renvoyé par la méthode models.list.

Format : models/{model}. Il se présente sous la forme models/{model}.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Champs
content object (Content)

Obligatoire. Contenu à intégrer. Seuls les champs parts.text seront comptabilisés.

taskType enum (TaskType)

Facultatif. Type de tâche facultatif pour lequel les embeddings seront utilisés. Non compatible avec les modèles antérieurs (models/embedding-001).

title string

Facultatif. Titre facultatif du texte. Ne s'applique que lorsque TaskType est défini sur RETRIEVAL_DOCUMENT.

Remarque : Spécifier un title pour RETRIEVAL_DOCUMENT permet d'obtenir des embeddings de meilleure qualité pour la récupération.

outputDimensionality integer

Facultatif. Dimension réduite facultative pour l'embedding de sortie. Si cette option est définie, les valeurs excessives de l'embedding de sortie sont tronquées à la fin. Compatible avec les modèles récents (à partir de 2024) uniquement. Vous ne pouvez pas définir cette valeur si vous utilisez le modèle précédent (models/embedding-001).

Exemple de requête

Python

from google import genai
from google.genai import types

client = genai.Client()
text = "Hello World!"
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=text,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const text = "Hello World!";
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

text := "Hello World!"
outputDim := int32(10)
contents := []*genai.Content{
	genai.NewContentFromText(text, genai.RoleUser),
}
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", 
	contents, &genai.EmbedContentConfig{
		OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(embeddings))

Coquille Rose

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
     "content": {
     "parts":[{
     "text": "What is the meaning of life?"}]}
    }'

Corps de la réponse

Si la requête aboutit, le corps de la réponse contient une instance de EmbedContentResponse.

Méthode : models.batchEmbedContents

Génère plusieurs vecteurs d'embedding à partir de l'entrée Content, qui se compose d'un lot de chaînes représentées sous forme d'objets EmbedContentRequest.

Point de terminaison

post https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents

Paramètres de chemin d'accès

model string

Obligatoire. Nom de ressource du modèle. Il sert d'ID au modèle.

Ce nom doit correspondre à un nom de modèle renvoyé par la méthode models.list.

Format : models/{model}. Il se présente sous la forme models/{model}.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Champs
requests[] object (EmbedContentRequest)

Obligatoire. Requêtes d'intégration pour le lot. Le modèle de chacune de ces requêtes doit correspondre au modèle spécifié BatchEmbedContentsRequest.model.

Exemple de requête

Python

from google import genai
from google.genai import types

client = genai.Client()
texts = [
    "What is the meaning of life?",
    "How much wood would a woodchuck chuck?",
    "How does the brain work?",
]
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const texts = [
  "What is the meaning of life?",
  "How much wood would a woodchuck chuck?",
  "How does the brain work?",
];
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: texts,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

contents := []*genai.Content{
	genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
	genai.NewContentFromText("How much wood would a woodchuck chuck?", genai.RoleUser),
	genai.NewContentFromText("How does the brain work?", genai.RoleUser),
}

outputDim := int32(10)
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", contents, &genai.EmbedContentConfig{
	OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(embeddings))

Coquille Rose

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"requests": [{
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "What is the meaning of life?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How much wood would a woodchuck chuck?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How does the brain work?"}]}, }, ]}' 2> /dev/null | grep -C 5 values

Corps de la réponse

Réponse à une BatchEmbedContentsRequest.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Champs
embeddings[] object (ContentEmbedding)

Uniquement en sortie. Les embeddings pour chaque requête, dans le même ordre que ceux fournis dans la requête par lot.

Représentation JSON
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ]
}

Méthode : models.asyncBatchEmbedContent

Place en file d'attente un lot de models.embedContent requêtes pour le traitement par lot. Nous avons un gestionnaire models.batchEmbedContents dans GenerativeService, mais il était synchronisé. Pour éviter toute confusion, nous allons nommer celui-ci Async.

Point de terminaison

post https://generativelanguage.googleapis.com/v1beta/{batch.model=models/*}:asyncBatchEmbedContent

Paramètres de chemin d'accès

batch.model string

Obligatoire. Nom du Model à utiliser pour générer la complétion.

Format : models/{model}. Il se présente sous la forme models/{model}.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Champs
batch.name string

Uniquement en sortie. Identifiant. Nom de ressource du lot.

Format : batches/{batchId}.

batch.displayName string

Obligatoire. Nom défini par l'utilisateur pour ce lot.

batch.inputConfig object (InputEmbedContentConfig)

Obligatoire. Configuration d'entrée des instances sur lesquelles le traitement par lot est effectué.

batch.output object (EmbedContentBatchOutput)

Uniquement en sortie. Sortie de la requête par lot.

batch.createTime string (Timestamp format)

Uniquement en sortie. Heure à laquelle le lot a été créé.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

batch.endTime string (Timestamp format)

Uniquement en sortie. Heure à laquelle le traitement par lot s'est terminé.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

batch.updateTime string (Timestamp format)

Uniquement en sortie. Heure à laquelle le lot a été mis à jour pour la dernière fois.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

batch.batchStats object (EmbedContentBatchStats)

Uniquement en sortie. Statistiques sur le lot.

batch.state enum (BatchState)

Uniquement en sortie. État du lot.

batch.priority string (int64 format)

Facultatif. Priorité du lot. Les lots ayant une valeur de priorité plus élevée seront traités avant ceux ayant une valeur de priorité plus faible. Les valeurs négatives sont autorisées. La valeur par défaut est "0".

Corps de la réponse

Si la requête aboutit, le corps de la réponse contient une instance de Operation.

EmbedContentRequest

Requête contenant le Content à intégrer au modèle.

Champs
model string

Obligatoire. Nom de ressource du modèle. Il sert d'ID au modèle.

Ce nom doit correspondre à un nom de modèle renvoyé par la méthode models.list.

Format : models/{model}

content object (Content)

Obligatoire. Contenu à intégrer. Seuls les champs parts.text seront comptabilisés.

taskType enum (TaskType)

Facultatif. Type de tâche facultatif pour lequel les embeddings seront utilisés. Non compatible avec les modèles antérieurs (models/embedding-001).

title string

Facultatif. Titre facultatif du texte. Ne s'applique que lorsque TaskType est défini sur RETRIEVAL_DOCUMENT.

Remarque : Spécifier un title pour RETRIEVAL_DOCUMENT permet d'obtenir des embeddings de meilleure qualité pour la récupération.

outputDimensionality integer

Facultatif. Dimension réduite facultative pour l'embedding de sortie. Si cette option est définie, les valeurs excessives de l'embedding de sortie sont tronquées à la fin. Compatible avec les modèles récents (à partir de 2024) uniquement. Vous ne pouvez pas définir cette valeur si vous utilisez le modèle précédent (models/embedding-001).

Représentation JSON
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

EmbedContentResponse

Réponse à un EmbedContentRequest.

Champs
embedding object (ContentEmbedding)

Uniquement en sortie. Représentation vectorielle continue générée à partir du contenu d'entrée.

Représentation JSON
{
  "embedding": {
    object (ContentEmbedding)
  }
}

ContentEmbedding

Une liste de nombres à virgule flottante représentant un embedding.

Champs
values[] number

Valeurs d'embedding.

Représentation JSON
{
  "values": [
    number
  ]
}

TaskType

Type de tâche pour laquelle l'embedding sera utilisé.

Enums
TASK_TYPE_UNSPECIFIED Valeur non définie, qui sera définie par défaut sur l'une des autres valeurs enum.
RETRIEVAL_QUERY Spécifie que le texte donné est une requête dans un contexte de recherche/récupération.
RETRIEVAL_DOCUMENT Spécifie que le texte donné est un document du corpus dans lequel la recherche est effectuée.
SEMANTIC_SIMILARITY Indique que le texte donné sera utilisé pour la STS.
CLASSIFICATION Spécifie que le texte donné sera classifié.
CLUSTERING Spécifie que les embeddings seront utilisés pour le clustering.
QUESTION_ANSWERING Indique que le texte donné sera utilisé pour répondre aux questions.
FACT_VERIFICATION Indique que le texte donné sera utilisé pour la vérification de faits.
CODE_RETRIEVAL_QUERY Indique que le texte donné sera utilisé pour la récupération de code.

EmbedContentBatch

Ressource représentant un lot de requêtes EmbedContent.

Champs
model string

Obligatoire. Nom du Model à utiliser pour générer la complétion.

Format : models/{model}.

name string

Uniquement en sortie. Identifiant. Nom de ressource du lot.

Format : batches/{batchId}.

displayName string

Obligatoire. Nom défini par l'utilisateur pour ce lot.

inputConfig object (InputEmbedContentConfig)

Obligatoire. Configuration d'entrée des instances sur lesquelles le traitement par lot est effectué.

output object (EmbedContentBatchOutput)

Uniquement en sortie. Sortie de la requête par lot.

createTime string (Timestamp format)

Uniquement en sortie. Heure à laquelle le lot a été créé.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

endTime string (Timestamp format)

Uniquement en sortie. Heure à laquelle le traitement par lot s'est terminé.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Uniquement en sortie. Heure à laquelle le lot a été mis à jour pour la dernière fois.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

batchStats object (EmbedContentBatchStats)

Uniquement en sortie. Statistiques sur le lot.

state enum (BatchState)

Uniquement en sortie. État du lot.

priority string (int64 format)

Facultatif. Priorité du lot. Les lots ayant une valeur de priorité plus élevée seront traités avant ceux ayant une valeur de priorité plus faible. Les valeurs négatives sont autorisées. La valeur par défaut est "0".

Représentation JSON
{
  "model": string,
  "name": string,
  "displayName": string,
  "inputConfig": {
    object (InputEmbedContentConfig)
  },
  "output": {
    object (EmbedContentBatchOutput)
  },
  "createTime": string,
  "endTime": string,
  "updateTime": string,
  "batchStats": {
    object (EmbedContentBatchStats)
  },
  "state": enum (BatchState),
  "priority": string
}

InputEmbedContentConfig

Configure l'entrée de la requête par lot.

Champs
source Union type
Obligatoire. Source de l'entrée. source ne peut être qu'un des éléments suivants :
fileName string

Nom du File contenant les requêtes d'entrée.

requests object (InlinedEmbedContentRequests)

Requêtes à traiter dans le lot.

Représentation JSON
{

  // source
  "fileName": string,
  "requests": {
    object (InlinedEmbedContentRequests)
  }
  // Union type
}

InlinedEmbedContentRequests

Requêtes à traiter dans le lot si elles sont fournies dans la requête de création du lot.

Champs
requests[] object (InlinedEmbedContentRequest)

Obligatoire. Requêtes à traiter dans le lot.

Représentation JSON
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

InlinedEmbedContentRequest

Requête à traiter dans le lot.

Champs
request object (EmbedContentRequest)

Obligatoire. Requête à traiter dans le lot.

metadata object (Struct format)

Facultatif. Métadonnées à associer à la requête.

Représentation JSON
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

EmbedContentBatchOutput

Sortie d'une requête par lot. Cette valeur est renvoyée dans le champ AsyncBatchEmbedContentResponse ou EmbedContentBatch.output.

Champs
output Union type
Sortie de la requête par lot. output ne peut être qu'un des éléments suivants :
responsesFile string

Uniquement en sortie. ID du fichier contenant les réponses. Il s'agit d'un fichier JSONL avec une seule réponse par ligne. Les réponses seront des messages EmbedContentResponse au format JSON. Les réponses seront rédigées dans le même ordre que les requêtes d'entrée.

inlinedResponses object (InlinedEmbedContentResponses)

Uniquement en sortie. Réponses aux requêtes du lot. Renvoie la valeur "true" si le lot a été créé à l'aide de requêtes intégrées. Les réponses seront dans le même ordre que les requêtes d'entrée.

Représentation JSON
{

  // output
  "responsesFile": string,
  "inlinedResponses": {
    object (InlinedEmbedContentResponses)
  }
  // Union type
}

InlinedEmbedContentResponses

Réponses aux requêtes du lot.

Champs
inlinedResponses[] object (InlinedEmbedContentResponse)

Uniquement en sortie. Réponses aux requêtes du lot.

Représentation JSON
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

InlinedEmbedContentResponse

Réponse à une seule requête du lot.

Champs
metadata object (Struct format)

Uniquement en sortie. Métadonnées associées à la requête.

output Union type
Résultat de la requête. output ne peut être qu'un des éléments suivants :
error object (Status)

Uniquement en sortie. Erreur rencontrée lors du traitement de la demande.

response object (EmbedContentResponse)

Uniquement en sortie. Réponse à la demande.

Représentation JSON
{
  "metadata": {
    object
  },

  // output
  "error": {
    object (Status)
  },
  "response": {
    object (EmbedContentResponse)
  }
  // Union type
}

EmbedContentBatchStats

Statistiques sur le lot.

Champs
requestCount string (int64 format)

Uniquement en sortie. Nombre de requêtes dans le lot.

successfulRequestCount string (int64 format)

Uniquement en sortie. Nombre de requêtes traitées avec succès.

failedRequestCount string (int64 format)

Uniquement en sortie. Nombre de requêtes qui n'ont pas pu être traitées.

pendingRequestCount string (int64 format)

Uniquement en sortie. Nombre de demandes en attente de traitement.

Représentation JSON
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}