批量获取响应是一种高效发送大量非延迟时间敏感类嵌入请求的方法。与在线响应(一次只能有一个输入请求)不同,您可以在单个批量请求中发送多个嵌入请求。与对 Gemini Enterprise Agent Platform 中的表格数据执行批量推理的方式类似,您可以确定输出位置、添加输入,然后响应会异步填充到输出位置。
Gemini Embedding 批量预测
Gemini Embedding 批量预测基于 Gemini 批量推理构建,并使用更新的输入和输出架构:
- 输入和输出存储空间:输入和输出必须采用存储在 Cloud Storage 中的 JSON Lines (JSONL) 文件格式。(Gemini 嵌入模型不支持 BigQuery 表。)
- 作业限制:每个批量作业最多支持 1,000,000 行,输入文件大小上限为 1 GB。
- 配额和排队:没有预定义的并发配额。批处理作业会根据资源可用性动态安排,最多可排队 72 小时,目标周转时间为 24 小时以内。
支持的型号和地区
下表列出了支持批量推理的 Gemini 嵌入模型和位置:
| 模型 | 模型 ID | 支持的位置 |
|---|---|---|
| Gemini Embedding 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)、美国多区域 (us)、欧盟多区域 (eu)
|
如需详细了解区域级端点和全球端点,请参阅位置。
准备输入
将批量输入数据作为 JSONL 文件上传到 Cloud Storage,其中每行都是一个包含 "request" 字段的 JSON 对象。
Gemini Embedding 001
gemini-embedding-001 模型支持在 embed_content_config 内为每行配置 task_type 和 title。
{"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
gemini-embedding-2 模型支持文本、图片、视频和音频输入。与 gemini-embedding-001 不同,gemini-embedding-2 要求将任务类型和标题直接内嵌在提示文本中。如果 task_type 或 title 传递到 embed_content_config 中,则会被静默忽略(与在线 API 行为一致)。
如需了解多模态输入限制以及令牌和文件限制,请参阅多模态嵌入 API 限制。
{"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}}}
请求批量响应
批量作业可能需要一些时间才能完成,具体取决于您提交的输入数据项数量。您可以使用 REST API 或 Google Gen AI SDK 提交批量嵌入作业。
REST
您可以使用 REST API 通过向 batchPredictionJobs 端点发送 POST 请求来创建批量嵌入作业。
在使用任何请求数据之前,请先进行以下替换:
- ENDPOINT_PREFIX:区域或多区域前缀,后跟
-(例如us-central1-、us-或eu-)。如果使用global端点,请留空 (aiplatform.googleapis.com)。 - PROJECT_ID:您的 Cloud de Confiance by S3NS 项目的 ID。
- LOCATION:模型支持的位置(例如,
gemini-embedding-001为us-central1,或gemini-embedding-2为global、us或eu)。 - BP_JOB_NAME:批量作业的显示名称。
- MODEL_ID:发布方模型 ID(
gemini-embedding-001或gemini-embedding-2)。 - INPUT_URI:输入 JSONL 文件的 Cloud Storage URI(例如
gs://my-bucket/path/to/input.jsonl)。 - OUTPUT_URI_PREFIX:将写入输出 JSONL 文件的 Cloud Storage 存储桶和目录前缀(例如
gs://my-bucket/path/to/output/)。
HTTP 方法和网址:
POST https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs
请求 JSON 正文:
{
"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"
}
}
}
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
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"
}
}
}
EOF然后,执行以下命令以发送 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
将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
@'
{
"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 utf8然后,执行以下命令以发送 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
您应该收到类似以下内容的 JSON 响应:
{
"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"
}
curl 命令示例
响应包含批量作业的唯一标识符 (BATCH_JOB_ID)。您可以提交批量作业,并使用 curl 轮询其状态:
创建批量作业:
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"
轮询作业状态:
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
安装
pip install --upgrade google-genai
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 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
了解如何安装或更新 Go。
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 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
安装
npm install @google/genai
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 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
了解如何安装或更新 Java。
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 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
检索批量输出
批量推理任务完成后,输出 JSONL 文件会存储在您在请求中指定的 Cloud Storage 输出目录中。
{"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, ...]}}}
其他资源
- 如需了解
gemini-embedding-001上可用的配置选项,请参阅文本嵌入指南。 - 如需了解
gemini-embedding-2上可用的配置选项,请参阅多模态嵌入指南。 - 如需详细了解 Gemini 批量推理功能和配额,请参阅使用 Gemini 进行批量推理。
旧版嵌入批量预测
本部分介绍了旧版文本嵌入模型(text-embedding-004、text-embedding-005 和 text-multilingual-embedding-002)的批量推理工作流,这些模型基于与 Gemini 嵌入模型不同的架构构建。
支持批量推理的文本嵌入模型
所有稳定版旧版文本嵌入模型都支持批量推理,并且在生产环境中完全受支持。如需查看嵌入模型的完整列表,请参阅嵌入模型和版本。
为旧版模型准备输入
旧版批量请求的输入是可以存储在 BigQuery 表中或作为 JSON 行 (JSONL) 文件存储在 Cloud Storage 中的提示列表。每个请求最多可包含 30,000 项提示。
JSONL 示例
本部分展示了如何为旧版模型设置 JSONL 输入和输出的格式。
JSONL 输入示例
{"content":"Give a short description of a machine learning model:"}
{"content":"Best recipe for banana bread:"}
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":""}
BigQuery 示例
本部分介绍如何设置旧版模型的 BigQuery 输入和输出的格式。
BigQuery 输入示例
此示例展示了一个单列 BigQuery 表。
| 内容 |
|---|
| “提供机器学习模型的简短说明:” |
| “最适合香蕉面包的食谱:” |
BigQuery 输出示例
| 内容 | 预测 | status |
|---|---|---|
| “提供机器学习模型的简短说明:” |
[ { "embeddings": { "statistics": { "token_count": 8, "truncated": false }, "values": [0.1, ...] } } ] |
|
| “最适合香蕉面包的食谱:” |
[ { "embeddings": { "statistics": { "token_count": 3, "truncated": false }, "values": [0.2, ...] } } ] |
为旧版模型请求批量响应
批量生成任务可能需要一些时间才能完成,具体取决于提交的输入数据项数量。
REST
您可以使用 REST API 通过向发布方模型端点发送 POST 请求,批量获取旧版模型的文本嵌入。
在使用任何请求数据之前,请先进行以下替换:
- LOCATION:要将请求发送到的位置(例如
us-central1)。 - PROJECT_ID:您的 Cloud de Confiance by S3NS 项目的 ID。
- BP_JOB_NAME:作业名称。
- MODEL_ID:旧版嵌入模型的模型 ID(例如
text-embedding-005)。 - INPUT_URI:输入源 URI。这是 BigQuery 表 URI 或 Cloud Storage 中的 JSONL 文件 URI。
- OUTPUT_URI:输出目标 URI。
HTTP 方法和网址:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs
请求 JSON 正文:
{
"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"
}
}
}
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
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"
}
}
}
EOF然后,执行以下命令以发送 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
将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
@'
{
"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 utf8然后,执行以下命令以发送 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
您应该收到类似以下内容的 JSON 响应:
{
"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": {}
}
示例 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"
检索旧版模型的批量输出
旧版批量推理任务完成后,输出存储在您在请求中指定的 Cloud Storage 存储桶或 BigQuery 表中。