Receber respostas em lote é uma maneira de enviar com eficiência um grande número de solicitações de embeddings não sensíveis à latência. Ao contrário das respostas on-line, em que você está limitado a uma solicitação de entrada por vez, é possível enviar muitas solicitações de incorporação em uma única solicitação em lote. De maneira semelhante à maneira como a inferência em lote é feita para dados tabulares na Gemini Enterprise Agent Platform, você determina o local de saída, adiciona as entradas e as respostas são preenchidas de maneira assíncrona no local de saída.
Predição em lote de embedding do Gemini
A previsão em lote de incorporação do Gemini é criada com base na inferência em lote do Gemini e usa um esquema atualizado para entrada e saída:
- Armazenamento de entrada e saída:as entradas e saídas precisam ser formatadas como arquivos JSON Lines (JSONL) armazenados no Cloud Storage. As tabelas do BigQuery não são compatíveis com modelos de incorporação do Gemini.
- Limites de jobs:cada job em lote aceita até 1.000.000 de linhas e um tamanho de arquivo de entrada de até 1 GB.
- Cotas e filas:não há cotas de simultaneidade predefinidas. Os jobs em lote são programados dinamicamente com base na disponibilidade de recursos e podem permanecer na fila por até 72 horas, com um tempo de resposta desejado de menos de 24 horas.
Modelos e locais compatíveis
A tabela a seguir lista os modelos de incorporação do Gemini e os locais compatíveis para inferência em lote:
| Modelo | ID do modelo | Locais suportados |
|---|---|---|
| Embedding do Gemini 001 | gemini-embedding-001 |
us-central1, us-east1, us-east4,
us-west1, us-west4, europe-west1,
europe-west4
|
| Embedding do Gemini 2 | gemini-embedding-2 |
Global (global), multirregional dos EUA (us), multirregional da UE (eu)
|
Para mais informações sobre endpoints regionais e globais, consulte Locais.
Preparar suas entradas
Faça upload dos dados de entrada em lote como um arquivo JSONL no Cloud Storage, em que cada linha é um único objeto JSON que contém um campo "request".
Embedding do Gemini 001
O modelo gemini-embedding-001 oferece suporte a uma configuração task_type e title dentro de embed_content_config para cada linha.
{"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"}}}
Embedding do Gemini 2
O modelo gemini-embedding-2 aceita entradas de texto, imagem, vídeo e áudio. Ao contrário de gemini-embedding-001, gemini-embedding-2 espera que o tipo e o título da tarefa sejam inseridos diretamente no texto do comando. Se task_type ou title forem transmitidos dentro de embed_content_config, eles serão ignorados silenciosamente (correspondendo ao comportamento da API on-line).
Para restrições de entrada multimodal e limites de token e arquivo, consulte Limites da API 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 uma resposta em lote
Dependendo do número de itens de entrada enviados, um job em lote pode levar algum tempo para ser concluído. É possível enviar um job de incorporação em lote usando a API REST ou o SDK de IA Generativa do Google.
REST
É possível usar a API REST para criar um job de incorporação em lote enviando uma solicitação POST ao endpoint batchPredictionJobs.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- ENDPOINT_PREFIX: o prefixo da região ou multirregião seguido por
-(por exemplo,us-central1-,us-oueu-). Se você estiver usando o endpointglobal, deixe em branco (aiplatform.googleapis.com). - PROJECT_ID: o ID do seu projeto do Cloud de Confiance by S3NS .
- LOCATION: um local compatível para o modelo (por exemplo,
us-central1paragemini-embedding-001ouglobal,usoueuparagemini-embedding-2). - BP_JOB_NAME: um nome de exibição para o job em lote.
- MODEL_ID: o ID do modelo de editor (
gemini-embedding-001ougemini-embedding-2). - INPUT_URI: o URI do Cloud Storage do arquivo JSONL de entrada (por exemplo,
gs://my-bucket/path/to/input.jsonl). - OUTPUT_URI_PREFIX: o bucket do Cloud Storage e o prefixo do diretório em que os arquivos JSONL de saída serão gravados (por exemplo,
gs://my-bucket/path/to/output/).
Método HTTP e URL:
POST https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs
Corpo JSON da solicitação:
{
"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 a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
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"
}
}
}
EOFDepois execute o comando a seguir para enviar a solicitação 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
Salve o corpo da solicitação em um arquivo chamado request.json.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
@'
{
"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 utf8Depois execute o comando a seguir para enviar a solicitação 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
Você receberá uma resposta JSON semelhante a esta:
{
"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"
}
Exemplos de comandos curl
A resposta inclui um identificador exclusivo para o job em lote (BATCH_JOB_ID). É possível enviar um job em lote e sondar o status dele usando curl:
Criar um job em lote:
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"
Status do job de pesquisa:
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 saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a 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
Saiba como instalar ou atualizar o Go.
Para saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a 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 saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a 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
Saiba como instalar ou atualizar o Java.
Para saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a 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 saída em lote
Quando uma tarefa de inferência em lote é concluída, os arquivos JSONL de saída são armazenados no diretório de saída do Cloud Storage especificado na solicitação.
{"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, ...]}}}
Outros recursos
- Para conferir as opções de configuração disponíveis em
gemini-embedding-001, consulte o Guia de embeddings de texto. - Para conferir as opções de configuração disponíveis em
gemini-embedding-2, consulte o Guia de embeddings multimodais. - Para saber mais sobre os recursos e as cotas de inferência em lote do Gemini, consulte Inferência em lote com o Gemini.
Previsão em lote de embeddings legados
Esta seção descreve fluxos de trabalho de inferência em lote para modelos legados de embedding de texto (text-embedding-004, text-embedding-005 e text-multilingual-embedding-002), que são criados em uma arquitetura diferente dos modelos de embedding do Gemini.
Modelos de embeddings de texto compatíveis com inferências em lote
Todas as versões estáveis dos modelos legados de embedding de texto são compatíveis com inferências em lote e têm suporte total para ambientes de produção. Para conferir a lista completa de modelos de embedding, consulte Modelo e versões de embedding.
Preparar suas entradas para modelos legados
A entrada para solicitações em lote legadas é uma lista de comandos que podem ser armazenados em uma tabela do BigQuery ou como um arquivo JSON Lines (JSONL) no Cloud Storage. Cada solicitação pode incluir até 30.000 comandos.
Exemplo de JSONL
Esta seção mostra exemplos de como formatar entradas e saídas JSONL para modelos legados.
Exemplo de entrada JSONL
{"content":"Give a short description of a machine learning model:"}
{"content":"Best recipe for banana bread:"}
Exemplo de saída 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":""}
Exemplo do BigQuery
Esta seção mostra exemplos de como formatar entradas e saídas do BigQuery para modelos legados.
Exemplo de uma entrada do BigQuery
Este exemplo mostra uma tabela do BigQuery de coluna única.
| conteúdo |
|---|
| "Faça uma breve descrição de um modelo de machine learning:" |
| "Melhor receita para pão de banana:" |
Exemplo de uma saída do BigQuery
| conteúdo | previsões | status |
|---|---|---|
| "Faça uma breve descrição de um modelo de machine learning:" |
[ { "embeddings": { "statistics": { "token_count": 8, "truncated": false }, "values": [0.1, ...] } } ] |
|
| "Melhor receita para pão de banana:" |
[ { "embeddings": { "statistics": { "token_count": 3, "truncated": false }, "values": [0.2, ...] } } ] |
Solicitar uma resposta em lote para modelos legados
Dependendo do número de itens de entrada enviados, uma tarefa de previsão em lote pode levar algum tempo para ser concluída.
REST
É possível usar a API REST para receber embeddings de texto em lote para modelos legados enviando uma solicitação POST ao endpoint do modelo do publisher.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- LOCATION: o local para enviar sua solicitação (por exemplo,
us-central1). - PROJECT_ID: o ID do seu projeto do Cloud de Confiance by S3NS .
- BP_JOB_NAME: o nome do job.
- MODEL_ID: o ID do modelo de embedding legado (por exemplo,
text-embedding-005). - INPUT_URI: o URI da origem da entrada. Pode ser um URI de tabela do BigQuery ou um URI de arquivo JSONL no Cloud Storage.
- OUTPUT_URI: URI de destino de saída.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs
Corpo JSON da solicitação:
{
"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 a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
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"
}
}
}
EOFDepois execute o comando a seguir para enviar a solicitação 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
Salve o corpo da solicitação em um arquivo chamado request.json.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
@'
{
"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 utf8Depois execute o comando a seguir para enviar a solicitação 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
Você receberá uma resposta JSON semelhante a esta:
{
"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": {}
}
Exemplo de 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"
Recuperar saída em lote para modelos legados
Quando uma tarefa de inferência em lote legada é concluída, a saída é armazenada no bucket do Cloud Storage ou na tabela do BigQuery especificada na solicitação.
A seguir
- Saiba como usar incorporações de texto.
- Saiba como usar embeddings multimodais.