L'API d'embedding textuel (ou plongement textuel) convertit des données textuelles en vecteurs numériques. Ces représentations vectorielles sont conçues pour capturer la signification sémantique et le contexte des mots qu'elles représentent.
Modèles compatibles :
Modèles en anglais | Modèles multilingues |
---|---|
textembedding-gecko@001 |
textembedding-gecko-multilingual@001 |
textembedding-gecko@003 |
text-multilingual-embedding-002 |
text-embedding-004 |
Syntaxe
curl
PROJECT_ID = PROJECT_ID REGION = us-central1 MODEL_ID = MODEL_ID curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:predict -d \ '{ "instances": [ ... ], "parameters": { ... } }'
Python
PROJECT_ID = PROJECT_ID REGION = us-central1 MODEL_ID = MODEL_ID import vertexai from vertexai.language_models import TextEmbeddingModel vertexai.init(project=PROJECT_ID, location=REGION) model = TextEmbeddingModel.from_pretrained(MODEL_ID) embeddings = model.get_embeddings(...)
Liste des paramètres
Paramètres | |
---|---|
|
Chaque instance représente une seule partie de texte à intégrer. |
|
Texte pour lequel vous souhaitez générer des embeddings. |
|
Facultatif : Si cette valeur est définie sur "true", le texte d'entrée est tronqué. Lorsque la valeur est "false", une erreur est renvoyée si le texte d'entrée dépasse la longueur maximale acceptée par le modèle. La valeur par défaut est "true". |
|
Facultatif : Permet de spécifier la taille de l'embedding de sortie. Si cette option est définie, les embeddings de sortie sont tronqués à la taille spécifiée. |
Corps de la requête
{
"instances": [
{
"task_type": "RETRIEVAL_DOCUMENT",
"title": "document title",
"content": "I would like embeddings for this text!"
},
]
}
Paramètres | |
---|---|
|
Texte pour lequel vous souhaitez générer des embeddings. |
|
Facultatif : Utilisé pour transmettre l'application en aval prévue afin d'aider le modèle à produire de meilleurs embeddings. Il doit s'agir de l'une des options suivantes :
Le paramètre |
|
Facultatif : Utilisé pour aider le modèle à produire de meilleurs embeddings.
Valide uniquement avec |
taskType
Le tableau suivant décrit les valeurs du paramètre task_type
et leurs cas d'utilisation :
task_type |
Description |
---|---|
RETRIEVAL_QUERY |
Spécifie que le texte donné est une requête dans un contexte de recherche ou de récupération. |
RETRIEVAL_DOCUMENT |
Spécifie que le texte donné est un document dans un contexte de recherche ou de récupération. |
SEMANTIC_SIMILARITY |
Indique que le texte donné est utilisé pour la similarité textuelle sémantique (STS). |
CLASSIFICATION |
Spécifie que l'embedding est utilisé pour la classification. |
CLUSTERING |
Spécifie que l'embedding est utilisé pour le clustering. |
QUESTION_ANSWERING |
Spécifie que l'embedding de la requête est utilisé pour répondre aux questions. Utilisez RETRIEVAL_DOCUMENT pour le côté document. |
FACT_VERIFICATION |
Indique que l'embedding de la requête est utilisé pour la vérification des faits. |
Tâches de récupération :
Requête : utilisez task_type=RETRIEVAL_QUERY
pour indiquer que le texte d'entrée est une requête de recherche.
Corpus : utilisez task_type=RETRIEVAL_DOCUMENT
pour indiquer que le texte d'entrée fait partie de la collection de documents en cours de recherche.
Tâches de similarité :
Similarité sémantique : utilisez "task_type= SEMANTIC_SIMILARITY
" pour les deux textes d'entrée afin d'évaluer leur similarité globale.
Corps de la réponse
{
"predictions": [
{
"embeddings": {
"statistics": {
"truncated": boolean,
"token_count": integer
},
"values": [ number ]
}
}
]
}
Élément de réponse | Description |
---|---|
embeddings |
Résultat généré à partir du texte d'entrée. |
statistics |
Statistiques calculées à partir du texte d'entrée. |
truncated |
Indique si le texte d'entrée était plus long que le nombre maximal de jetons autorisés et tronqué. |
tokenCount |
Nombre de jetons du texte d'entrée. |
values |
Le champ values contient les vecteurs d'embedding correspondant aux mots du texte d'entrée. |
Exemple de réponse
{
"predictions": [
{
"embeddings": {
"values": [
0.0058424929156899452,
0.011848051100969315,
0.032247550785541534,
-0.031829461455345154,
-0.055369812995195389,
...
],
"statistics": {
"token_count": 4,
"truncated": false
}
}
}
]
}
Examples
Intégrer une chaîne de texte
Cas d'utilisation de base
L'exemple suivant montre comment obtenir l'embedding d'une chaîne de texte.
REST
Après avoir configuré votre environnement, vous pouvez utiliser REST pour tester une requête textuelle. L'exemple suivant envoie une requête au point de terminaison du modèle du diffuseur.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : l'ID de votre projet.
- 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 pourtextembedding-gecko@001
est de 3 072. - 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 esttrue
.
Méthode HTTP et URL :
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004: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
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/text-embedding-004:predict"
PowerShell
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/text-embedding-004:predict" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON semblable à la suivante. Notez que values
a été tronqué pour économiser de l'espace.
- Utilisez la méthode
generateContent
pour demander que la réponse soit renvoyée une fois qu'elle a été entièrement générée. Pour réduire la perception de la latence auprès d'un public humain, diffusez la réponse en streaming à l'aide de la méthodestreamGenerateContent
lorsqu'elle est générée. - L'ID du modèle multimodal se trouve à la fin de l'URL avant la méthode (par exemple,
gemini-1.5-flash
ougemini-1.0-pro-vision
). Cet exemple est également compatible avec d'autres modèles.
Python
Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API Python.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Go.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Avant d'essayer cet exemple, suivez les instructions de configuration pour Java décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Java.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Node.js.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Cas d'utilisation avancé
L'exemple suivant illustre certaines fonctionnalités avancées.
- Utilisez
task_type
ettitle
pour améliorer la qualité des embeddings. - Utilisez des paramètres pour contrôler le comportement de l'API.
REST
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : l'ID de votre projet.
- TEXT : texte pour lequel vous souhaitez générer des embeddings. Limite : cinq textes de 3 072 jetons maximum par texte.
- TASK_TYPE : utilisé pour transmettre l'application en aval prévue afin d'aider le modèle à produire de meilleurs embeddings.
- TITLE : utilisé pour aider le modèle à produire de meilleurs embeddings.
- 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 esttrue
. - OUTPUT_DIMENSIONALITY : permet de spécifier la taille de l'embedding de sortie. Si cette option est définie, les embeddings de sortie sont tronqués à la taille spécifiée.
Méthode HTTP et URL :
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict
Corps JSON de la requête :
{ "instances": [ { "content": "TEXT", "task_type": "TASK_TYPE", "title": "TITLE" }, ], "parameters": { "autoTruncate": AUTO_TRUNCATE, "outputDimensionality": OUTPUT_DIMENSIONALITY } }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
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/textembedding-gecko@003:predict"
PowerShell
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/textembedding-gecko@003:predict" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON semblable à la suivante. Notez que values
a été tronqué pour économiser de l'espace.
Python
Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API Python.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Go.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Avant d'essayer cet exemple, suivez les instructions de configuration pour Java décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Java.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Node.js.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Langues de texte acceptées
Tous les modèles d'embedding textuel sont compatibles avec le texte en anglais et ont été évalués sur ce type de texte. Les modèles textembedding-gecko-multilingual@001
et text-multilingual-embedding-002
sont également compatibles et ont été évalués dans les langages suivants :
- Langues évaluées :
Arabic (ar)
,Bengali (bn)
,English (en)
,Spanish (es)
,German (de)
,Persian (fa)
,Finnish (fi)
,French (fr)
,Hindi (hi)
,Indonesian (id)
,Japanese (ja)
,Korean (ko)
,Russian (ru)
,Swahili (sw)
,Telugu (te)
,Thai (th)
,Yoruba (yo)
,Chinese (zh)
- Langues compatibles :
Afrikaans
,Albanian
,Amharic
,Arabic
,Armenian
,Azerbaijani
,Basque
,Belarusiasn
,Bengali
,Bulgarian
,Burmese
,Catalan
,Cebuano
,Chichewa
,Chinese
,Corsican
,Czech
,Danish
,Dutch
,English
,Esperanto
,Estonian
,Filipino
,Finnish
,French
,Galician
,Georgian
,German
,Greek
,Gujarati
,Haitian Creole
,Hausa
,Hawaiian
,Hebrew
,Hindi
,Hmong
,Hungarian
,Icelandic
,Igbo
,Indonesian
,Irish
,Italian
,Japanese
,Javanese
,Kannada
,Kazakh
,Khmer
,Korean
,Kurdish
,Kyrgyz
,Lao
,Latin
,Latvian
,Lithuanian
,Luxembourgish
,Macedonian
,Malagasy
,Malay
,Malayalam
,Maltese
,Maori
,Marathi
,Mongolian
,Nepali
,Norwegian
,Pashto
,Persian
,Polish
,Portuguese
,Punjabi
,Romanian
,Russian
,Samoan
,Scottish Gaelic
,Serbian
,Shona
,Sindhi
,Sinhala
,Slovak
,Slovenian
,Somali
,Sotho
,Spanish
,Sundanese
,Swahili
,Swedish
,Tajik
,Tamil
,Telugu
,Thai
,Turkish
,Ukrainian
,Urdu
,Uzbek
,Vietnamese
,Welsh
,West Frisian
,Xhosa
,Yiddish
,Yoruba
,Zulu
.
Versions de modèle
Pour utiliser une version de modèle stable, indiquez le numéro de version du modèle, par exemple text-embedding-004
.
Chaque version stable est disponible pendant six mois après la date de disponibilité de la version stable suivante.
Le tableau suivant contient les versions de modèle stable disponibles :
Nom du modèle | Date de disponibilité | Date d'arrêt |
---|---|---|
text-embedding-004 | 14 mai 2024 | À déterminer |
text-multilingual-embedding-002 | 14 mai 2024 | À déterminer |
textembedding-gecko@003 | 12 décembre 2021 | 14 mai 2025 |
textembedding-gecko-multilingual@001 | 2 novembre 2023 | 14 mai 2025 |
textembedding-gecko@002 (régressif, mais encore compatible) |
2 novembre 2023 | 12 décembre 2024 |
textembedding-gecko@001 (régressif, mais encore compatible) |
7 juin 2023 | 2 novembre 2024 |
multimodalembedding@001 | 12 février 2024 | À déterminer |
Pour en savoir plus, consultez la page Versions et cycle de vie des modèles.
Étape suivante
Pour obtenir une documentation détaillée, consultez les pages suivantes :