Obtener respuestas por lotes es una forma de enviar de manera eficiente grandes cantidades de solicitudes de incorporación no sensibles a la latencia. A diferencia de las respuestas en línea, en las que estás limitado a una solicitud de entrada a la vez, puedes enviar muchas solicitudes de incorporación en una sola solicitud por lotes. De manera similar a como se realiza la inferencia por lotes para los datos tabulares en Gemini Enterprise Agent Platform, debes determinar la ubicación de salida, agregar la entrada y las respuestas se propagan de forma asíncrona en la ubicación de salida.
Predicción por lotes de Gemini Embedding
La predicción por lotes de Gemini Embedding se basa en la inferencia por lotes de Gemini y usa un esquema actualizado para la entrada y la salida:
- Almacenamiento de entrada y salida: Las entradas y salidas deben tener el formato de archivos JSON Lines (JSONL) almacenados en Cloud Storage. (Las tablas de BigQuery no son compatibles con los modelos de incorporación de Gemini).
- Límites de trabajos: Cada trabajo por lotes admite hasta 1,000,000 de filas y un tamaño de archivo de entrada de hasta 1 GB.
- Cuotas y filas: No hay cuotas de simultaneidad predefinidas. Los trabajos por lotes se programan de forma dinámica según la disponibilidad de recursos y pueden permanecer en la cola hasta por 72 horas, con un tiempo de respuesta objetivo de menos de 24 horas.
Modelos y ubicaciones compatibles
En la siguiente tabla, se enumeran los modelos de embeddings de Gemini y las ubicaciones compatibles para la inferencia por lotes:
| Modelo | ID de modelo | Ubicaciones admitidas |
|---|---|---|
| Embedding de Gemini 001 | gemini-embedding-001 |
us-central1, us-east1, us-east4,
us-west1, us-west4, europe-west1,
europe-west4
|
| Gemini Embedding 2 | gemini-embedding-2 |
Global (global), US multi-region (us),
EU multi-region (eu)
|
Para obtener más información sobre los extremos regionales y globales, consulta Ubicaciones.
Prepara tus entradas
Sube tus datos de entrada por lotes como un archivo JSONL a Cloud Storage, en el que cada línea es un solo objeto JSON que contiene un campo "request".
Embedding de Gemini 001
El modelo gemini-embedding-001 admite una configuración de task_type y title dentro de embed_content_config para cada fila.
{"key": "id_1", "request": {"content": {"parts": [{"text": "Hello World"}]}, "embed_content_config": {"output_dimensionality": 768, "title": "some_title", "task_type": "RETRIEVAL_DOCUMENT"}}}
{"key": "id_2", "request": {"content": {"parts": [{"text": "Hello World again"}]}, "embed_content_config": {"output_dimensionality": 768, "title": "some_title_2", "task_type": "RETRIEVAL_DOCUMENT"}}}
Gemini Embedding 2
El modelo gemini-embedding-2 admite entradas de texto, imágenes, video y audio. A diferencia de gemini-embedding-001, gemini-embedding-2 espera que el tipo y el título de la tarea se incluyan directamente en el texto de la instrucción. Si se pasan task_type o title dentro de embed_content_config, se ignoran de forma silenciosa (lo que coincide con el comportamiento de la API en línea).
Para conocer las restricciones de entrada multimodal y los límites de tokens y archivos, consulta Límites de la API de Multimodal Embeddings.
{"key": "id_1", "request": {"content": {"parts": [{"text": "title: sample | text: Hello World"}]}, "embed_content_config": {"output_dimensionality": 768}}}
{"key": "id_2", "request": {"content": {"parts": [{"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/image/benchmark.jpeg", "mimeType": "image/jpeg"}}]}, "embed_content_config": {"output_dimensionality": 768}}}
Solicitar una respuesta por lotes
Según la cantidad de elementos de entrada que envíes, un trabajo por lotes puede tardar un tiempo en completarse. Puedes enviar un trabajo de embeddings por lotes con la API de REST o el SDK de IA generativa de Google.
REST
Puedes usar la API de REST para crear un trabajo de generación de embeddings por lotes enviando una solicitud POST al extremo batchPredictionJobs.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- ENDPOINT_PREFIX: Es el prefijo de la región o multirregión seguido de
-(por ejemplo,us-central1-,us-oeu-). Si usas el extremoglobal, déjalo en blanco (aiplatform.googleapis.com). - PROJECT_ID: Es el ID de tu proyecto de Cloud de Confiance by S3NS .
- LOCATION: Es una ubicación compatible con el modelo (por ejemplo,
us-central1paragemini-embedding-001, oglobal,usoeuparagemini-embedding-2). - BP_JOB_NAME: Es el nombre visible de tu trabajo por lotes.
- MODEL_ID: Es el ID del modelo de publicador (
gemini-embedding-001ogemini-embedding-2). - INPUT_URI: Es el URI de Cloud Storage de tu archivo JSONL de entrada (por ejemplo,
gs://my-bucket/path/to/input.jsonl). - OUTPUT_URI_PREFIX: Es el prefijo del bucket y el directorio de Cloud Storage en el que se escribirán los archivos JSONL de salida (por ejemplo,
gs://my-bucket/path/to/output/).
Método HTTP y URL:
POST https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs
Cuerpo JSON de la solicitud:
{
"displayName": "BP_JOB_NAME",
"model": "publishers/google/models/MODEL_ID",
"inputConfig": {
"instancesFormat": "jsonl",
"gcsSource": {
"uris": [
"INPUT_URI"
]
}
},
"outputConfig": {
"predictionsFormat": "jsonl",
"gcsDestination": {
"outputUriPrefix": "OUTPUT_URI_PREFIX"
}
}
}
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json.
Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:
cat > request.json << 'EOF'
{
"displayName": "BP_JOB_NAME",
"model": "publishers/google/models/MODEL_ID",
"inputConfig": {
"instancesFormat": "jsonl",
"gcsSource": {
"uris": [
"INPUT_URI"
]
}
},
"outputConfig": {
"predictionsFormat": "jsonl",
"gcsDestination": {
"outputUriPrefix": "OUTPUT_URI_PREFIX"
}
}
}
EOFLuego, ejecuta el siguiente comando para enviar tu solicitud de REST:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs"
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json.
Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:
@'
{
"displayName": "BP_JOB_NAME",
"model": "publishers/google/models/MODEL_ID",
"inputConfig": {
"instancesFormat": "jsonl",
"gcsSource": {
"uris": [
"INPUT_URI"
]
}
},
"outputConfig": {
"predictionsFormat": "jsonl",
"gcsDestination": {
"outputUriPrefix": "OUTPUT_URI_PREFIX"
}
}
}
'@ | Out-File -FilePath request.json -Encoding utf8Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:
$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://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{
"name": "projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID",
"displayName": "BP_JOB_NAME",
"model": "publishers/google/models/MODEL_ID",
"inputConfig": {
"instancesFormat": "jsonl",
"gcsSource": {
"uris": [
"INPUT_URI"
]
}
},
"outputConfig": {
"predictionsFormat": "jsonl",
"gcsDestination": {
"outputUriPrefix": "OUTPUT_URI_PREFIX"
}
},
"state": "JOB_STATE_PENDING",
"createTime": "2026-09-15T19:33:59.153782Z",
"updateTime": "2026-09-15T19:33:59.153782Z",
"modelVersionId": "1"
}
Ejemplos de comandos curl
La respuesta incluye un identificador único para el trabajo por lotes (BATCH_JOB_ID). Puedes enviar un trabajo por lotes y consultar su estado con curl:
Crea un trabajo por lotes:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs"
Estado del trabajo de sondeo:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID"
Python
Instalar
pip install --upgrade google-genai
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa de Google con 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=us-central1 export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
Obtén información para instalar o actualizar Go.
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa de Google con 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=us-central1 export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
Instalar
npm install @google/genai
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa de Google con 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=us-central1 export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
Obtén información para instalar o actualizar Java.
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa de Google con 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=us-central1 export GOOGLE_GENAI_USE_ENTERPRISE=True
Recuperar los resultados por lotes
Cuando se completa una tarea de inferencia por lotes, los archivos JSONL de salida se almacenan en el directorio de salida de Cloud Storage que especificaste en la solicitud.
{"key": "id_1", "request": {...}, "response": {"tokenCount": "2", "embedding": {"values": [-0.015, 0.024, ...]}}}
{"key": "id_2", "request": {...}, "response": {"tokenCount": "3", "embedding": {"values": [-0.075, 0.031, ...]}}}
Recursos adicionales
- Para conocer las opciones de configuración disponibles en
gemini-embedding-001, consulta la Guía de Embeddings de texto. - Para conocer las opciones de configuración disponibles en
gemini-embedding-2, consulta la Guía de Embeddings Multimodales. - Para obtener más información sobre las funciones y las cuotas de la inferencia por lotes de Gemini, consulta Inferencia por lotes con Gemini.
Predicción por lotes de Legacy Embedding
En esta sección, se describen los flujos de trabajo de inferencia por lotes para los modelos heredados de embedding de texto (text-embedding-004, text-embedding-005 y text-multilingual-embedding-002), que se basan en una arquitectura diferente a la de los modelos de embedding de Gemini.
Modelos de incorporación de texto que admiten inferencias por lotes
Todas las versiones estables de los modelos heredados de embedding de texto admiten inferencias por lotes y son totalmente compatibles con los entornos de producción. Para ver la lista completa de modelos de incorporación, consulta Modelo y versiones de incorporación.
Prepara tus entradas para los modelos heredados
La entrada para las solicitudes por lotes heredadas es una lista de instrucciones que se pueden almacenar en una tabla de BigQuery o como un archivo de líneas JSON (JSONL) en Cloud Storage. Cada solicitud puede incluir hasta 30,000 instrucciones.
Ejemplo de JSONL
En esta sección, se muestran ejemplos de cómo dar formato a la entrada y la salida de JSONL para los modelos heredados.
Ejemplo de entrada JSONL
{"content":"Give a short description of a machine learning model:"}
{"content":"Best recipe for banana bread:"}
Ejemplo de salida JSONL
{"instance":{"content":"Give..."},"predictions": [{"embeddings":{"statistics":{"token_count":8,"truncated":false},"values":[0.2,....]}}],"status":""}
{"instance":{"content":"Best..."},"predictions": [{"embeddings":{"statistics":{"token_count":3,"truncated":false},"values":[0.1,....]}}],"status":""}
Ejemplo de BigQuery
En esta sección, se muestran ejemplos de cómo dar formato a la entrada y la salida de BigQuery para los modelos heredados.
Ejemplo de entrada de BigQuery
En este ejemplo, se muestra una tabla de BigQuery de una sola columna.
| contenido |
|---|
| “Proporciona una breve descripción de un modelo de aprendizaje automático:” |
| “Mejor receta de pan de banana”. |
Ejemplo de salida de BigQuery
| contenido | predicciones | estado |
|---|---|---|
| “Proporciona una breve descripción de un modelo de aprendizaje automático:” |
[ { "embeddings": { "statistics": { "token_count": 8, "truncated": false }, "values": [0.1, ...] } } ] |
|
| “Mejor receta de pan de banana”. |
[ { "embeddings": { "statistics": { "token_count": 3, "truncated": false }, "values": [0.2, ...] } } ] |
Solicita una respuesta por lotes para modelos heredados
Según la cantidad de elementos de entrada que hayas enviado, una tarea de predicción por lotes puede tardar un tiempo en completarse.
REST
Puedes usar la API de REST para obtener incorporaciones de texto en lotes para modelos heredados. Para ello, envía una solicitud POST al extremo del modelo de publicador.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- LOCATION: Es la ubicación a la que se enviará tu solicitud (por ejemplo,
us-central1). - PROJECT_ID: Es el ID de tu proyecto de Cloud de Confiance by S3NS .
- BP_JOB_NAME: El nombre del trabajo.
- MODEL_ID: Es el ID del modelo de embedding heredado (por ejemplo,
text-embedding-005). - INPUT_URI: Es el URI de la fuente de entrada. Este es un URI de tabla de BigQuery o un URI de archivo JSONL en Cloud Storage.
- OUTPUT_URI: URI de destino de salida.
Método HTTP y URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs
Cuerpo JSON de la solicitud:
{
"name": "BP_JOB_NAME",
"displayName": "BP_JOB_NAME",
"model": "publishers/google/models/text-embedding-005",
"inputConfig": {
"instancesFormat":"bigquery",
"bigquerySource":{
"inputUri" : "INPUT_URI"
}
},
"outputConfig": {
"predictionsFormat":"bigquery",
"bigqueryDestination":{
"outputUri": "OUTPUT_URI"
}
}
}
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json.
Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:
cat > request.json << 'EOF'
{
"name": "BP_JOB_NAME",
"displayName": "BP_JOB_NAME",
"model": "publishers/google/models/text-embedding-005",
"inputConfig": {
"instancesFormat":"bigquery",
"bigquerySource":{
"inputUri" : "INPUT_URI"
}
},
"outputConfig": {
"predictionsFormat":"bigquery",
"bigqueryDestination":{
"outputUri": "OUTPUT_URI"
}
}
}
EOFLuego, ejecuta el siguiente comando para enviar tu solicitud de REST:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs"
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json.
Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:
@'
{
"name": "BP_JOB_NAME",
"displayName": "BP_JOB_NAME",
"model": "publishers/google/models/text-embedding-005",
"inputConfig": {
"instancesFormat":"bigquery",
"bigquerySource":{
"inputUri" : "INPUT_URI"
}
},
"outputConfig": {
"predictionsFormat":"bigquery",
"bigqueryDestination":{
"outputUri": "OUTPUT_URI"
}
}
}
'@ | Out-File -FilePath request.json -Encoding utf8Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:
$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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{
"name": "projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/123456789",
"displayName": "BP_JOB_NAME",
"model": "projects/PROJECT_ID/locations/LOCATION/models/text-embedding-005",
"inputConfig": {
"instancesFormat": "bigquery",
"bigquerySource": {
"inputUri": "INPUT_URI"
}
},
"modelParameters": {},
"outputConfig": {
"predictionsFormat": "bigquery",
"bigqueryDestination": {
"outputUri": "OUTPUT_URI"
}
},
"state": "JOB_STATE_PENDING",
"createTime": "2023-07-12T20:46:52.148717Z",
"updateTime": "2023-07-12T20:46:52.148717Z",
"labels": {
"owner": "sample_owner",
"product": "llm"
},
"modelVersionId": "1",
"modelMonitoringStatus": {}
}
Ejemplo del comando curl
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs"
Recupera los resultados por lotes para los modelos heredados
Cuando se completa una tarea de inferencia por lotes heredada, el resultado se almacena en el bucket de Cloud Storage o en la tabla de BigQuery que especificaste en la solicitud.
¿Qué sigue?
- Obtén más información para obtener incorporaciones de texto.
- Obtén más información para obtener incorporaciones multimodales.