En esta guía, se muestra cómo usar la API de Text Embeddings para convertir texto en vectores numéricos. En este documento, se incluyen los siguientes temas: La API de Text embeddings convierte texto en vectores numéricos llamados embeddings. Estas representaciones vectoriales capturan el significado semántico y el contexto del texto. Modelos compatibles: Puedes obtener incorporaciones de texto con los siguientes modelos: Para obtener una calidad de incorporación superior, En la siguiente tabla, se describen los valores del parámetro Respuesta de muestra En el siguiente ejemplo, se muestra cómo obtener la incorporación de una cadena de texto.
Después de configurar tu entorno, puedes usar REST para probar una instrucción de texto. En el siguiente ejemplo, se envía una solicitud al extremo del modelo de publicador.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
HTTP method and URL:
Cuerpo JSON de la solicitud: Para enviar tu solicitud, elige una de estas opciones: Guarda el cuerpo de la solicitud en un archivo llamado Guarda el cuerpo de la solicitud en un archivo llamado Deberías recibir una respuesta JSON similar a la que se muestra a continuación: Ten en cuenta que Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python.
Para obtener más información, consulta la
documentación de referencia de la API de Python.
Antes de probar este ejemplo, sigue las instrucciones de configuración para Go incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente.
Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Go.
Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación.
Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente.
Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Java.
Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación.
Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente.
Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Node.js.
Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación.
Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Todos los modelos de incorporación de texto admiten texto en inglés y se evaluaron en él. El modelo El modelo Para usar un modelo estable actual, especifica el número de versión del modelo, por ejemplo, No se recomienda especificar un modelo sin un número de versión, ya que es un puntero heredado a otro modelo y no es estable. Para obtener más información, consulta Versiones de modelo y ciclo de vida Obtén más información sobre las incorporaciones de texto:
Nombre del modelo
Descripción
Dimensiones de salida
Longitud de secuencia máxima
Lenguajes de texto admitidos
gemini-embedding-001
Rendimiento de vanguardia en tareas de inglés, multilingües y de código Unifica los modelos especializados anteriores, como
text-embedding-005
y text-multilingual-embedding-002
, y logra un mejor rendimiento en sus respectivos dominios. Lee nuestro Informe técnico para obtener más detalles.hasta 3072
2,048 tokens
Idiomas de texto admitidos
text-embedding-005
Se especializa en tareas de código y en inglés.
Hasta 768
2,048 tokens
Inglés
text-multilingual-embedding-002
Se especializa en tareas multilingües.
Hasta 768
2,048 tokens
Idiomas de texto admitidos
gemini-embedding-001
es nuestro modelo grande diseñado para proporcionar el mayor rendimiento. Ten en cuenta que gemini-embedding-001
admite una instancia por solicitud.Sintaxis
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(...)
Solicitud y respuesta
Cuerpo de la solicitud
{
"instances": [
{
"task_type": "RETRIEVAL_DOCUMENT",
"title": "document title",
"content": "I would like embeddings for this text!"
},
]
}
parámetros de solicitud
instances
: Obligatorio. Es una lista de objetos que contienen el texto que se incorporará. Se admiten los siguientes campos:
content
(string
): Es el texto para el que se generarán las incorporaciones.task_type
(string
): Opcional. Especifica la aplicación descendente prevista para ayudar al modelo a producir incorporaciones de mejor calidad. Si no especificas un valor, el valor predeterminado es RETRIEVAL_QUERY
. Para obtener más información sobre los tipos de tareas, consulta Elige un tipo de tarea de embeddings.title
(string
): Opcional. Es un título para el contenido de texto. Este campo solo se aplica cuando task_type
es RETRIEVAL_DOCUMENT
.parameters
: Opcional Objeto que contiene los siguientes campos:
autoTruncate
(bool
): Si es true
, el texto de entrada se trunca si es más largo que la longitud máxima del modelo. Si es false
, se muestra un error para la entrada demasiado grande. El valor predeterminado es true
.outputDimensionality
(int
): Es el tamaño de embedding deseado. Si se establece, los embeddings de salida se truncan a esta dimensión.Tipos de tareas
task_type
y sus casos de uso:
task_type
Descripción
Caso de uso
RETRIEVAL_QUERY
El texto de entrada es una búsqueda en un parámetro de configuración de búsqueda o recuperación.
Se usa para el texto de la búsqueda cuando se busca en una colección de documentos. Vincula con
RETRIEVAL_DOCUMENT
para los documentos.
RETRIEVAL_DOCUMENT
El texto de entrada es un documento en un parámetro de configuración de búsqueda o recuperación.
Se usa para los documentos de una colección en la que se realizará la búsqueda. Se vincula con
RETRIEVAL_QUERY
para la búsqueda.
SEMANTIC_SIMILARITY
El texto de entrada se usa para la similitud textual semántica (STS).
Comparar dos fragmentos de texto para determinar su similitud en significado
CLASSIFICATION
La incorporación se usará para tareas de clasificación.
Entrenar un modelo para categorizar texto en clases predefinidas
CLUSTERING
El embedding se usará para tareas de agrupamiento en clústeres.
Agrupa textos similares sin etiquetas predefinidas.
QUESTION_ANSWERING
El texto de entrada es una búsqueda para un sistema de respuesta a preguntas.
Encontrar respuestas a preguntas dentro de un conjunto de documentos Usa
RETRIEVAL_DOCUMENT
para los documentos.
FACT_VERIFICATION
El texto de entrada es una afirmación que se verificará en función de un conjunto de documentos.
Verificar la precisión fáctica de una declaración Usa
RETRIEVAL_DOCUMENT
para los documentos.
CODE_RETRIEVAL_QUERY
El texto de entrada es una búsqueda para recuperar fragmentos de código relevantes (Java y Python).
Buscar funciones o fragmentos relevantes en una base de código Usa
RETRIEVAL_DOCUMENT
para los documentos de código.
task_type=RETRIEVAL_QUERY
para el texto de entrada que es una búsqueda.task_type=RETRIEVAL_DOCUMENT
para el texto de entrada que forma parte de la colección de documentos que se busca.
task_type=SEMANTIC_SIMILARITY
para ambos textos de entrada para evaluar su similitud general en significado.SEMANTIC_SIMILARITY
no está diseñado para casos de uso de recuperación, como la búsqueda de documentos y la recuperación de información. Para estos casos de uso, usa RETRIEVAL_DOCUMENT
, RETRIEVAL_QUERY
, QUESTION_ANSWERING
y FACT_VERIFICATION
.Cuerpo de la respuesta
{
"predictions": [
{
"embeddings": {
"statistics": {
"truncated": boolean,
"token_count": integer
},
"values": [ number ]
}
}
]
}
Parámetros de respuesta
predictions
: Es una lista de objetos, en la que cada objeto corresponde a una instancia de entrada de la solicitud. Cada objeto contiene el siguiente campo:
embeddings
: Es el embedding generado a partir del texto de entrada. Contiene los siguientes campos:
values
: Es una lista de números de punto flotante que representa el vector de incorporación del texto de entrada.statistics
: Son las estadísticas calculadas a partir del texto de entrada. Contiene los siguientes campos:
truncated
(bool
): true
si el texto de entrada se truncó porque era más largo que la cantidad máxima de tokens permitidos por el modelo.token_count
(int
): Es la cantidad de tokens en el texto de entrada.{
"predictions": [
{
"embeddings": {
"values": [
0.0058424929156899452,
0.011848051100969315,
0.032247550785541534,
-0.031829461455345154,
-0.055369812995195389,
...
],
"statistics": {
"token_count": 4,
"truncated": false
}
}
}
]
}
Ejemplos
Incorpora una cadena de texto
REST
textembedding-gecko@001
. La longitud máxima del token de entrada para textembedding-gecko@001
es 3,072. En el caso de gemini-embedding-001
, cada solicitud solo puede incluir un texto de entrada. Para obtener más información, consulta Límites de los embeddings de texto.
false
, el texto que excede el límite del token hace que la solicitud falle. El valor predeterminado es true
.POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict
{
"instances": [
{ "content": "TEXT"}
],
"parameters": {
"autoTruncate": AUTO_TRUNCATE
}
}
curl
request.json
y ejecuta el siguiente comando: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
request.json
y ejecuta el siguiente comando:$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 Contentvalues
se truncó para ahorrar espacio.
generateContent
para solicitar que la respuesta se muestre después de que se haya generado por completo.
Para reducir la percepción de latencia a un público humano, transmite la respuesta a medida que se genera; para ello, usa el método streamGenerateContent
.
gemini-2.0-flash
). Esta muestra también puede admitir otros
modelos.
Python
Go
Java
Node.js
Lenguajes de texto admitidos
text-multilingual-embedding-002
también admite los siguientes idiomas. Se evaluó en los idiomas de la lista Idiomas evaluados.
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)
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
.gemini-embedding-001
admite los siguientes idiomas:Arabic
, Bengali
, Bulgarian
, Chinese (Simplified and Traditional)
, Croatian
, Czech
, Danish
, Dutch
, English
, Estonian
, Finnish
, French
, German
, Greek
, Hebrew
, Hindi
, Hungarian
, Indonesian
, Italian
, Japanese
, Korean
, Latvian
, Lithuanian
, Norwegian
, Polish
, Portuguese
, Romanian
, Russian
, Serbian
, Slovak
, Slovenian
, Spanish
, Swahili
, Swedish
, Thai
, Turkish
, Ukrainian
, Vietnamese
, Afrikaans
, Amharic
, Assamese
, Azerbaijani
, Belarusian
, Bosnian
, Catalan
, Cebuano
, Corsican
, Welsh
, Dhivehi
, Esperanto
, Basque
, Persian
, Filipino (Tagalog)
, Frisian
, Irish
, Scots Gaelic
, Galician
, Gujarati
, Hausa
, Hawaiian
, Hmong
, Haitian Creole
, Armenian
, Igbo
, Icelandic
, Javanese
, Georgian
, Kazakh
, Khmer
, Kannada
, Krio
, Kurdish
, Kyrgyz
, Latin
, Luxembourgish
, Lao
, Malagasy
, Maori
, Macedonian
, Malayalam
, Mongolian
, Meiteilon (Manipuri)
, Marathi
, Malay
, Maltese
, Myanmar (Burmese)
, Nepali
, Nyanja (Chichewa)
, Odia (Oriya)
, Punjabi
, Pashto
, Sindhi
, Sinhala (Sinhalese)
, Samoan
, Shona
, Somali
, Albanian
, Sesotho
, Sundanese
, Tamil
, Telugu
, Tajik
, Uyghur
, Urdu
, Uzbek
, Xhosa
, Yiddish
, Yoruba
, Zulu
.Versiones del modelo
gemini-embedding-001
.¿Qué sigue?
API de embeddings de texto
Salvo que se indique lo contrario, el contenido de esta página está sujeto a la licencia Atribución 4.0 de Creative Commons, y los ejemplos de código están sujetos a la licencia Apache 2.0. Para obtener más información, consulta las políticas del sitio de Google Developers. Java es una marca registrada de Oracle o sus afiliados.
Última actualización: 2025-08-19 (UTC)