Gemini 中文指南
获取 API 密钥 ↗

Batch API

↓ 下载 MarkdownInteractions API

Gemini Batch API 旨在异步处理大量请求 标准成本的 50%。目标周转时间为 24 小时,但在大多数情况下,它要快得多。

使用 Batch API 执行大规模、非紧急任务,例如不需要立即响应的数据预处理或运行评估。

创建批处理作业 #

您有两种方式在Batch API中提交请求:

  • 内联请求: 清单 GenerateContentRequest 直接包含在批量创建请求中的对象。这适用于将总请求大小保持在 20MB 以下的较小批量。的 输出 从模型返回的是一个列表 inlineResponse 对象。

  • 输入文件: A JSON 行 (JSONL) 文件的每一行都包含一个完整的 GenerateContentRequest 对象。对于较大的请求,建议使用此方法。的 输出 从模型返回的是一个 JSONL 文件,其中每一行都是 GenerateContentResponse 或状态对象。

内联请求 #

对于少量请求,可以直接嵌入 GenerateContentRequest 你体内的物体 BatchGenerateContentRequest。下面的例子调用了 BatchGenerateContent 具有内联请求的方法:

python

from google import genai
from google.genai import types

client = genai.Client()

# A list of dictionaries, where each is a GenerateContentRequest
inline_requests = [
    {
        'contents': [{
            'parts': [{'text': 'Tell me a one-sentence joke.'}],
            'role': 'user'
        }]
    },
    {
        'contents': [{
            'parts': [{'text': 'Why is the sky blue?'}],
            'role': 'user'
        }]
    }
]

inline_batch_job = client.batches.create(
    model="gemini-4-hydrogen",
    src=inline_requests,
    config={
        'display_name': "inlined-requests-job-1",
    },
)

print(f"Created batch job: {inline_batch_job.name}")

输入文件 #

对于较大的请求集,请准备 JSON Lines (JSONL) 文件。该文件中的每一行都必须是一个 JSON 对象,其中包含用户定义的密钥和请求对象,其中请求是有效的 GenerateContentRequest 对象。用户定义的键在响应中用于指示哪个输出是哪个请求的结果。例如,密钥定义为的请求 request-1 将使用相同的键名称注释其响应。

该文件是使用以下方式上传的 文件 API。输入文件允许的最大文件大小为 2GB。

以下是 JSONL 文件的示例。您可以将其保存在名为的文件中 my-batch-requests.json:

json
{"key": "request-1", "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]}}
{"key": "request-2", "request": {"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}}

与内联请求类似,您可以在每个请求 JSON 中指定其他参数,例如系统指令、工具或其他配置。

您可以使用以下方式上传此文件 文件 API 如下例所示。如果您使用多模态输入,则可以在 JSONL 文件中引用其他上传的文件。

python

import json
from google import genai
from google.genai import types

client = genai.Client()

# Create a sample JSONL file
with open("my-batch-requests.jsonl", "w") as f:
    requests = [
        {"key": "request-1", "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]}},
        {"key": "request-2", "request": {"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}}
    ]
    for req in requests:
        f.write(json.dumps(req) + "\n")

# Upload the file to the File API
uploaded_file = client.files.upload(
    file='my-batch-requests.jsonl',
    config=types.UploadFileConfig(display_name='my-batch-requests', mime_type='jsonl')
)

print(f"Uploaded file: {uploaded_file.name}")

下面的例子调用了 BatchGenerateContent 使用文件 API 上传输入文件的方法:

python
from google import genai

# Assumes `uploaded_file` is the file object from the previous step
client = genai.Client()
file_batch_job = client.batches.create(
    model="gemini-4-hydrogen",
    src=uploaded_file.name,
    config={
        'display_name': "file-upload-job-1",
    },
)

print(f"Created batch job: {file_batch_job.name}")

创建批处理作业时,您将获得返回的作业名称。使用此名称 监控 工作状态以及 检索结果 一旦工作完成。

以下是包含作业名称的示例输出:

代码

Created batch job from file: batches/123456789

批量嵌入支持 #

您可以使用 Batch API 与 嵌入模型 以获得更高的吞吐量。使用以下任一方法创建嵌入批处理作业 内联请求 或 输入文件,使用 batches.create_embeddings API 并指定嵌入模型。

python
from google import genai

client = genai.Client()

# Creating an embeddings batch job with an input file request:
file_job = client.batches.create_embeddings(
    model="gemini-embedding-2",
    src={'file_name': uploaded_batch_requests.name},
    config={'display_name': "Input embeddings batch"},
)

# Creating an embeddings batch job with an inline request:
batch_job = client.batches.create_embeddings(
    model="gemini-embedding-2",
    # For a predefined list of requests `inlined_requests`
    src={'inlined_requests': inlined_requests},
    config={'display_name': "Inlined embeddings batch"},
)

阅读嵌入部分 Batch API食谱 了解更多示例。

请求配置 #

您可以包含将在标准非批量请求中使用的任何请求配置。例如,您可以指定温度、系统指令,甚至传递其他模式。以下示例显示了一个示例内联请求,其中包含其中一个请求的系统指令:

python
inline_requests_list = [
    {'contents': [{'parts': [{'text': 'Write a short poem about a cloud.'}]}]},
    {'contents': [{
        'parts': [{
            'text': 'Write a short poem about a cat.'
            }]
        }],
    'config': {
        'system_instruction': {'parts': [{'text': 'You are a cat. Your name is Neko.'}]}}
    }
]

同样可以指定用于请求的工具。以下示例显示了一个请求,该请求启用 Google 搜索工具:

python
inlined_requests = [
{'contents': [{'parts': [{'text': 'Who won the euro 1998?'}]}]},
{'contents': [{'parts': [{'text': 'Who won the euro 2025?'}]}],
 'config':{'tools': [{'google_search': {}}]}}]

您可以指定 结构化输出 以及。以下示例显示如何指定批量请求。

python
import time
from google import genai
from pydantic import BaseModel, TypeAdapter

class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]

client = genai.Client()

# A list of dictionaries, where each is a GenerateContentRequest
inline_requests = [
    {
        'contents': [{
            'parts': [{'text': 'List a few popular cookie recipes, and include the amounts of ingredients.'}],
            'role': 'user'
        }],
        'config': {
            'response_mime_type': 'application/json',
            'response_schema': list[Recipe]
        }
    },
    {
        'contents': [{
            'parts': [{'text': 'List a few popular gluten free cookie recipes, and include the amounts of ingredients.'}],
            'role': 'user'
        }],
        'config': {
            'response_mime_type': 'application/json',
            'response_schema': list[Recipe]
        }
    }
]

inline_batch_job = client.batches.create(
    model="gemini-4-hydrogen",
    src=inline_requests,
    config={
        'display_name': "structured-output-job-1"
    },
)

# wait for the job to finish
job_name = inline_batch_job.name
print(f"Polling status for job: {job_name}")

while True:
    batch_job_inline = client.batches.get(name=job_name)
    if batch_job_inline.state.name in ('JOB_STATE_SUCCEEDED', 'JOB_STATE_FAILED', 'JOB_STATE_CANCELLED', 'JOB_STATE_EXPIRED'):
        break
    print(f"Job not finished. Current state: {batch_job_inline.state.name}. Waiting 30 seconds...")
    time.sleep(30)

print(f"Job finished with state: {batch_job_inline.state.name}")

# print the response
for i, inline_response in enumerate(batch_job_inline.dest.inlined_responses, start=1):
    print(f"\n--- Response {i} ---")

    # Check for a successful response
    if inline_response.response:
        # The .text property is a shortcut to the generated text.
        print(inline_response.response.text)

下面显示了此作业的示例输出:

json
--- Response 1 ---
[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed light brown sugar",
      "1 large egg",
      "1 teaspoon vanilla extract",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1/2 teaspoon salt",
      "1 1/2 cups chocolate chips"
    ]
  },
  {
    "recipe_name": "Oatmeal Raisin Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "1 cup packed light brown sugar",
      "1/2 cup granulated sugar",
      "2 large eggs",
      "1 teaspoon vanilla extract",
      "1 1/2 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon ground cinnamon",
      "1/2 teaspoon salt",
      "3 cups old-fashioned rolled oats",
      "1 cup raisins"
    ]
  },
  {
    "recipe_name": "Sugar Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "1 1/2 cups granulated sugar",
      "1 large egg",
      "1 teaspoon vanilla extract",
      "2 3/4 cups all-purpose flour",
      "1 teaspoon baking powder",
      "1/2 teaspoon salt"
    ]
  }
]

--- Response 2 ---
[
  {
    "recipe_name": "Gluten-Free Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed light brown sugar",
      "2 large eggs",
      "1 teaspoon vanilla extract",
      "2 1/4 cups gluten-free all-purpose flour blend (with xanthan gum)",
      "1 teaspoon baking soda",
      "1/2 teaspoon salt",
      "1 1/2 cups chocolate chips"
    ]
  },
  {
    "recipe_name": "Gluten-Free Peanut Butter Cookies",
    "ingredients": [
      "1 cup (250g) creamy peanut butter",
      "1/2 cup (100g) granulated sugar",
      "1/2 cup (100g) packed light brown sugar",
      "1 large egg",
      "1 teaspoon vanilla extract",
      "1/2 teaspoon baking soda",
      "1/4 teaspoon salt"
    ]
  },
  {
    "recipe_name": "Gluten-Free Oatmeal Raisin Cookies",
    "ingredients": [
      "1/2 cup (1 stick) unsalted butter, softened",
      "1/2 cup granulated sugar",
      "1/2 cup packed light brown sugar",
      "1 large egg",
      "1 teaspoon vanilla extract",
      "1 cup gluten-free all-purpose flour blend",
      "1/2 teaspoon baking soda",
      "1/2 teaspoon ground cinnamon",
      "1/4 teaspoon salt",
      "1 1/2 cups gluten-free rolled oats",
      "1/2 cup raisins"
    ]
  }
]

监控作业状态 #

使用创建批处理作业时获取的操作名称来轮询其状态。批处理作业的状态字段将指示其当前状态。批处理作业可以处于以下状态之一:

  • JOB_STATE_PENDING:作业已创建,正在等待服务处理。
  • JOB_STATE_RUNNING: 工作正在进行中。
  • JOB_STATE_SUCCEEDED: 作业成功完成。您现在可以检索结果。
  • JOB_STATE_FAILED: 作业失败。检查错误详细信息以获取更多信息。
  • JOB_STATE_CANCELLED:作业已被用户取消。
  • JOB_STATE_EXPIRED:作业已过期,因为它运行或挂起的时间超过 48 小时。该作业不会有任何可检索的结果。您可以尝试再次提交作业或将请求分成较小的批次。

您可以定期轮询作业状态以检查是否完成。

python
import time
from google import genai

client = genai.Client()

# Use the name of the job you want to check
# e.g., inline_batch_job.name from the previous step
job_name = "YOUR_BATCH_JOB_NAME" # (e.g. 'batches/your-batch-id')
batch_job = client.batches.get(name=job_name)

completed_states = set([
    'JOB_STATE_SUCCEEDED',
    'JOB_STATE_FAILED',
    'JOB_STATE_CANCELLED',
    'JOB_STATE_EXPIRED',
])

print(f"Polling status for job: {job_name}")
batch_job = client.batches.get(name=job_name) # Initial get
while batch_job.state.name not in completed_states:
  print(f"Current state: {batch_job.state.name}")
  time.sleep(30) # Wait for 30 seconds before polling again
  batch_job = client.batches.get(name=job_name)

print(f"Job finished with state: {batch_job.state.name}")
if batch_job.state.name == 'JOB_STATE_FAILED':
    print(f"Error: {batch_job.error}")

轮询和网络钩子 #

厌倦了投票? Gemini 现在支持 Webhook 用于异步处理完成。而不是不断地打电话 GET / operations, 订阅 batch.succeeded 直接允许 Gemini API 在异步或长时间运行的操作完成时将实时通知推送到您的服务器。

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

webhook = client.webhooks.create(
    name="MyBatchWebhook",
    subscribed_events=["batch.succeeded", "batch.failed"],
    uri="https://my-api.com/gemini-callback",
)

print(f"Created webhook: {webhook.name}")

检索结果 #

一旦作业状态表明您的批处理作业已成功,结果将在 response 场。

python
import json
from google import genai

client = genai.Client()

# Use the name of the job you want to check
# e.g., inline_batch_job.name from the previous step
job_name = "YOUR_BATCH_JOB_NAME"
batch_job = client.batches.get(name=job_name)

if batch_job.state.name == 'JOB_STATE_SUCCEEDED':

    # If batch job was created with a file
    if batch_job.dest and batch_job.dest.file_name:
        # Results are in a file
        result_file_name = batch_job.dest.file_name
        print(f"Results are in file: {result_file_name}")

        print("Downloading result file content...")
        file_content = client.files.download(file=result_file_name)
        # Process file_content (bytes) as needed
        print(file_content.decode('utf-8'))

    # If batch job was created with inline request
    # (for embeddings, use batch_job.dest.inlined_embed_content_responses)
    elif batch_job.dest and batch_job.dest.inlined_responses:
        # Results are inline
        print("Results are inline:")
        for i, inline_response in enumerate(batch_job.dest.inlined_responses):
            print(f"Response {i+1}:")
            if inline_response.response:
                # Accessing response, structure may vary.
                try:
                    print(inline_response.response.text)
                except AttributeError:
                    print(inline_response.response) # Fallback
            elif inline_response.error:
                print(f"Error: {inline_response.error}")
    else:
        print("No results found (neither file nor inline).")
else:
    print(f"Job did not succeed. Final state: {batch_job.state.name}")
    if batch_job.error:
        print(f"Error: {batch_job.error}")

列出批处理作业 #

您可以列出最近的批处理作业。

python
batch_jobs = client.batches.list()

# Optional query config:
# batch_jobs = client.batches.list(config={'page_size': 5})

for batch_job in batch_jobs:
    print(batch_job)

取消批处理作业 #

您可以使用其名称取消正在进行的批处理作业。当作业被取消时,它会停止处理新请求。

python
client.batches.cancel(name=batch_job_to_cancel.name)

删除批处理作业 #

您可以使用其名称删除现有的批处理作业。删除作业后,它将停止处理新请求并从批处理作业列表中删除。

python
client.batches.delete(name=batch_job_to_delete.name)

批量生成图像 #

如果您正在使用 Gemini Nano Banana 并且需要生成大量图像,可以使用Batch API来获得更高的 速率限制 换取最多 24 小时的周转时间。

您可以使用 内联请求 对于小批量请求(20MB 以下)或 JSONL 输入文件 对于大批量(建议用于图像生成):

对图像的内联请求 #

python
import time
import base64
import json
from google import genai
from google.genai import types
from PIL import Image

client = genai.Client(http_options={"api_version": "v1beta"})

# 1. Create batch job with inline requests
inline_requests = [
    {
        'contents': [{'parts': [{'text': 'A big letter A surrounded by animals starting with the A letter'}]}],
        'config': {'response_modalities': ['TEXT', 'IMAGE']}
    },
    {
        'contents': [{'parts': [{'text': 'A big letter B surrounded by animals starting with the B letter'}]}],
        'config': {'response_modalities': ['TEXT', 'IMAGE']}
    }
]

inline_batch_job = client.batches.create(
    model="gemini-3-pro-image-preview",
    src=inline_requests,
    config={
        'display_name': "inlined-image-requests-job-1",
    },
)

print(f"Created batch job: {inline_batch_job.name}")

# 2. Monitor job status
job_name = inline_batch_job.name
print(f"Polling status for job: {job_name}")

completed_states = set([
    'JOB_STATE_SUCCEEDED',
    'JOB_STATE_FAILED',
    'JOB_STATE_CANCELLED',
    'JOB_STATE_EXPIRED',
])

batch_job = client.batches.get(name=job_name) # Initial get
while batch_job.state.name not in completed_states:
  print(f"Current state: {batch_job.state.name}")
  time.sleep(10) # Wait for 10 seconds before polling again
  batch_job = client.batches.get(name=job_name)

print(f"Job finished with state: {batch_job.state.name}")

# 3. Retrieve results
if batch_job.state.name == 'JOB_STATE_SUCCEEDED':
    print("Results are inline:")
    for i, inline_response in enumerate(batch_job.dest.inlined_responses):
        print(f"Response {i+1}:")
        if inline_response.response:
            for part in inline_response.response.candidates[0].content.parts:
                if part.text:
                    print(part.text)
                elif part.inline_data:
                    print(f"Image mime type: {part.inline_data.mime_type}")
                    image = part.as_image()
                    image.save(f"image_{i+1}.png")
        elif inline_response.error:
            print(f"Error: {inline_response.error}")
elif batch_job.state.name == 'JOB_STATE_FAILED':
    print(f"Error: {batch_job.error}")

图像的输入文件 #

python
import json
import time
import base64
from google import genai
from google.genai import types
from PIL import Image

client = genai.Client(http_options={"api_version": "v1beta"})

# 1. Create and upload file
file_name = "my-batch-image-requests.jsonl"
with open(file_name, "w") as f:
    requests = [
        {"key": "request-1", "request": {"contents": [{"parts": [{"text": "A big letter A surrounded by animals starting with the A letter"}]}], "generation_config": {"responseModalities": ["TEXT", "IMAGE"]}}},
        {"key": "request-2", "request": {"contents": [{"parts": [{"text": "A big letter B surrounded by animals starting with the B letter"}]}], "generation_config": {"responseModalities": ["TEXT", "IMAGE"]}}}
    ]
    for req in requests:
        f.write(json.dumps(req) + "\n")

uploaded_file = client.files.upload(
    file=file_name,
    config=types.UploadFileConfig(display_name='my-batch-image-requests', mime_type='jsonl')
)
print(f"Uploaded file: {uploaded_file.name}")

# 2. Create batch job
file_batch_job = client.batches.create(
    model="gemini-3-pro-image-preview",
    src=uploaded_file.name,
    config={
        'display_name': "file-image-upload-job-1",
    },
)
print(f"Created batch job: {file_batch_job.name}")

# 3. Monitor job status
job_name = file_batch_job.name
print(f"Polling status for job: {job_name}")

completed_states = set([
    'JOB_STATE_SUCCEEDED',
    'JOB_STATE_FAILED',
    'JOB_STATE_CANCELLED',
    'JOB_STATE_EXPIRED',
])

batch_job = client.batches.get(name=job_name) # Initial get
while batch_job.state.name not in completed_states:
  print(f"Current state: {batch_job.state.name}")
  time.sleep(10) # Wait for 10 seconds before polling again
  batch_job = client.batches.get(name=job_name)

print(f"Job finished with state: {batch_job.state.name}")

# 4. Retrieve results
if batch_job.state.name == 'JOB_STATE_SUCCEEDED':
    result_file_name = batch_job.dest.file_name
    print(f"Results are in file: {result_file_name}")
    print("Downloading result file content...")
    file_content_bytes = client.files.download(file=result_file_name)
    file_content = file_content_bytes.decode('utf-8')
    # The result file is also a JSONL file. Parse and print each line.
    for line in file_content.splitlines():
      if line:
        parsed_response = json.loads(line)
        if 'response' in parsed_response and parsed_response['response']:
            for part in parsed_response['response']['candidates'][0]['content']['parts']:
              if part.get('text'):
                print(part['text'])
              elif part.get('inlineData'):
                print(f"Image mime type: {part['inlineData']['mimeType']}")
                data = base64.b64decode(part['inlineData']['data'])
        elif 'error' in parsed_response:
            print(f"Error: {parsed_response['error']}")
elif batch_job.state.name == 'JOB_STATE_FAILED':
    print(f"Error: {batch_job.error}")

技术细节 #

  • 支持型号: Batch API 支持一系列 Gemini 型号。请参阅 型号页面 各型号对Batch API的支持。 Batch API 支持的模式与交互式(或非批量)API 支持的模式相同。

  • 定价: Batch API 的使用价格为同等型号标准交互式 API 成本的 50%。请参阅 定价页面 了解详情。请参阅 速率限制页面 有关此功能的速率限制的详细信息。

  • 服务水平目标 (SLO): 批处理作业设计为在 24 小时的周转时间内完成。许多作业可能会更快完成,具体取决于其大小和当前系统负载。

  • 缓存: 上下文缓存 支持批量请求。通过指定重用缓存内容 cached_content 批次中单个请求配置中的资源名称。如果批次中的请求导致缓存命中,您需要支付 标准上下文缓存费率.

最佳实践 #

  • 对大型请求使用输入文件: 对于大量请求,请始终使用文件输入方法以获得更好的可管理性并避免达到请求大小限制 BatchGenerateContent 调用它自己。请注意,每个输入文件的文件大小限制为 2GB。

  • 错误处理: 检查 batchStats 用于 failedRequestCount 作业完成后。如果使用文件输出,请解析每一行以检查它是否是 GenerateContentResponse 或指示该特定请求错误的状态对象。请参阅 故障排除指南 获取完整的错误代码集。

  • 提交作业一次: 批处理作业的创建不是幂等的。如果您两次发送相同的创建请求,则会创建两个单独的批处理作业。

  • 拆分非常大的批次: 虽然目标周转时间为 24 小时,但实际处理时间可能会根据系统负载和作业大小而有所不同。对于大型作业,如果需要尽快获得中间结果,请考虑将其分成较小的批次。

后续步骤 #

搜索标题、API 名称或正文内容