Chế độ xử lý theo lô của Gemini API được thiết kế để xử lý một lượng lớn yêu cầu không đồng bộ với 50% chi phí tiêu chuẩn. Thời gian xử lý mục tiêu là 24 giờ, nhưng trong phần lớn các trường hợp, thời gian xử lý sẽ nhanh hơn nhiều.
Sử dụng Chế độ hàng loạt cho các tác vụ quy mô lớn, không khẩn cấp, chẳng hạn như xử lý trước dữ liệu hoặc chạy các quy trình đánh giá mà không cần phản hồi ngay lập tức.
Tạo một lô công việc
Bạn có 2 cách để gửi yêu cầu ở Chế độ hàng loạt:
- Yêu cầu nội tuyến: Danh sách các đối tượng
GenerateContentRequest
được đưa trực tiếp vào yêu cầu tạo hàng loạt của bạn. Phương thức này phù hợp với các lô nhỏ hơn, giúp tổng kích thước yêu cầu dưới 20 MB. Đầu ra mà mô hình trả về là một danh sách các đối tượnginlineResponse
. - Tệp đầu vào: Một tệp JSON Lines (JSONL), trong đó mỗi dòng chứa một đối tượng
GenerateContentRequest
hoàn chỉnh. Bạn nên sử dụng phương thức này cho các yêu cầu lớn hơn. Đầu ra mà mô hình trả về là một tệp JSONL, trong đó mỗi dòng là mộtGenerateContentResponse
hoặc một đối tượng trạng thái.
Yêu cầu trực tiếp
Đối với một số ít yêu cầu, bạn có thể nhúng trực tiếp các đối tượng GenerateContentRequest
trong BatchGenerateContentRequest
. Ví dụ sau đây gọi phương thức BatchGenerateContent
bằng các yêu cầu nội tuyến:
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="models/gemini-2.5-flash",
src=inline_requests,
config={
'display_name': "inlined-requests-job-1",
},
)
print(f"Created batch job: {inline_batch_job.name}")
REST
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:batchGenerateContent \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-X POST \
-H "Content-Type:application/json" \
-d '{
"batch": {
"display_name": "my-batch-requests",
"input_config": {
"requests": {
"requests": [
{
"request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]},
"metadata": {
"key": "request-1"
}
},
{
"request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]},
"metadata": {
"key": "request-2"
}
}
]
}
}
}
}'
Tệp đầu vào
Đối với các tập hợp yêu cầu lớn hơn, hãy chuẩn bị một tệp JSON Lines (JSONL). Mỗi dòng trong tệp này phải là một đối tượng JSON chứa một khoá do người dùng xác định và một đối tượng yêu cầu, trong đó yêu cầu là một đối tượng GenerateContentRequest
hợp lệ. Khoá do người dùng xác định được dùng trong phản hồi để cho biết đầu ra nào là kết quả của yêu cầu nào. Ví dụ: yêu cầu có khoá được xác định là request-1
sẽ có phản hồi được chú thích bằng cùng tên khoá.
Tệp này được tải lên bằng File API. Kích thước tệp tối đa được phép cho một tệp đầu vào là 2 GB.
Sau đây là ví dụ về một tệp JSONL. Bạn có thể lưu tệp này vào một tệp có tên là my-batch-requests.json
:
{"key": "request-1", "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}], "generation_config": {"temperature": 0.7}}}
{"key": "request-2", "request": {"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}}
Tương tự như các yêu cầu nội tuyến, bạn có thể chỉ định các tham số khác như hướng dẫn hệ thống, công cụ hoặc các cấu hình khác trong mỗi JSON yêu cầu.
Bạn có thể tải tệp này lên bằng File API như trong ví dụ sau. Nếu đang làm việc với dữ liệu đầu vào đa phương thức, bạn có thể tham chiếu các tệp khác đã tải lên trong tệp JSONL.
Python
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}")
REST
tmp_batch_input_file=batch_input.tmp
echo -e '{"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}], "generationConfig": {"temperature": 0.7}}\n{"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}' > batch_input.tmp
MIME_TYPE=$(file -b --mime-type "${tmp_batch_input_file}")
NUM_BYTES=$(wc -c < "${tmp_batch_input_file}")
DISPLAY_NAME=BatchInput
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files \
-D "${tmp_header_file}" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/jsonl" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${tmp_batch_input_file}" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
Ví dụ sau đây gọi phương thức BatchGenerateContent
bằng tệp đầu vào được tải lên bằng File API:
Python
# Assumes `uploaded_file` is the file object from the previous step
file_batch_job = client.batches.create(
model="gemini-2.5-flash",
src=uploaded_file.name,
config={
'display_name': "file-upload-job-1",
},
)
print(f"Created batch job: {file_batch_job.name}")
REST
BATCH_INPUT_FILE='files/123456' # File ID
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:batchGenerateContent \
-X POST \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type:application/json" \
-d "{
'batch': {
'display_name': 'my-batch-requests',
'input_config': {
'requests': {
'file_name': ${BATCH_INPUT_FILE}
}
}
}
}"
Khi tạo một lô công việc, bạn sẽ nhận được tên công việc được trả về. Sử dụng tên này để giám sát trạng thái công việc cũng như truy xuất kết quả sau khi công việc hoàn tất.
Sau đây là một ví dụ về kết quả chứa tên công việc:
Created batch job from file: batches/123456789
Yêu cầu về cấu hình
Bạn có thể thêm mọi cấu hình yêu cầu mà bạn sẽ sử dụng trong một yêu cầu không theo lô tiêu chuẩn. Ví dụ: bạn có thể chỉ định nhiệt độ, hướng dẫn hệ thống hoặc thậm chí truyền vào các phương thức khác. Ví dụ sau đây cho thấy một ví dụ về yêu cầu nội tuyến có chứa một chỉ dẫn hệ thống cho một trong các yêu cầu:
inline_requests_list = [
{'contents': [{'parts': [{'text': 'Write a short poem about a cloud.'}]}]},
{'contents': [{'parts': [{'text': 'Write a short poem about a cat.'}]}], 'system_instructions': {'parts': [{'text': 'You are a cat. Your name is Neko.'}]}}
]
Tương tự, bạn có thể chỉ định các công cụ cần dùng cho một yêu cầu. Ví dụ sau đây cho thấy một yêu cầu bật công cụ Tìm kiếm của Google:
inline_requests_list = [
{'contents': [{'parts': [{'text': 'Who won the euro 1998?'}]}]},
{'contents': [{'parts': [{'text': 'Who won the euro 2025?'}]}], 'tools': [{'google_search ': {}}]}
]
Bạn cũng có thể chỉ định đầu ra có cấu trúc. Ví dụ sau đây cho thấy cách chỉ định cho các yêu cầu hàng loạt.
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="models/gemini-2.5-flash",
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'):
break
print(f"Job not finished. Current state: {batch_job.state.name}. Waiting 30 seconds...")
time.sleep(30)
print(f"Job finished with state: {batch_job.state.name}")
# print the response
for i, inline_response in enumerate(batch_job_inline.dest.inlined_responses):
print(f"\n--- Response {i+1} ---")
# Check for a successful response
if inline_response.response:
# The .text property is a shortcut to the generated text.
print(inline_response.response.text)
Theo dõi trạng thái của lệnh
Sử dụng tên thao tác nhận được khi tạo lô công việc để thăm dò trạng thái của lô công việc đó. Trường trạng thái của lệnh hàng loạt sẽ cho biết trạng thái hiện tại của lệnh đó. Một lô công việc có thể ở một trong các trạng thái sau:
JOB_STATE_PENDING
: Công việc đã được tạo và đang chờ dịch vụ xử lý.JOB_STATE_SUCCEEDED
: Công việc hoàn tất thành công. Giờ đây, bạn có thể truy xuất kết quả.JOB_STATE_FAILED
: Công việc không thành công. Hãy kiểm tra thông tin chi tiết về lỗi để biết thêm thông tin.JOB_STATE_CANCELLED
: Người dùng đã huỷ lệnh.
Bạn có thể định kỳ thăm dò trạng thái của công việc để kiểm tra xem công việc đã hoàn tất hay chưa.
Python
# 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',
])
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}")
Đang truy xuất kết quả
Sau khi trạng thái công việc cho biết công việc hàng loạt của bạn đã thành công, kết quả sẽ có trong trường response
.
Python
import json
# 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
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}")
REST
BATCH_NAME="batches/123456" # Your batch job name
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type:application/json" 2> /dev/null > batch_status.json
if jq -r '.done' batch_status.json | grep -q "false"; then
echo "Batch has not finished processing"
fi
batch_state=$(jq -r '.metadata.state' batch_status.json)
if [[ $batch_state = "JOB_STATE_SUCCEEDED" ]]; then
if [[ $(jq '.response | has("inlinedResponses")' batch_status.json) = "true" ]]; then
jq -r '.response.inlinedResponses' batch_status.json
exit
fi
responses_file_name=$(jq -r '.response.responsesFile' batch_status.json)
curl https://generativelanguage.googleapis.com/download/v1beta/$responses_file_name:download?alt=media \
-H "x-goog-api-key: $GEMINI_API_KEY" 2> /dev/null
elif [[ $batch_state = "JOB_STATE_FAILED" ]]; then
jq '.error' batch_status.json
elif [[ $batch_state == "JOB_STATE_CANCELLED" ]]; then
echo "Batch was cancelled by the user"
fi
Huỷ một công việc hàng loạt
Bạn có thể huỷ một tác vụ hàng loạt đang diễn ra bằng cách sử dụng tên của tác vụ đó. Khi một lệnh bị huỷ, lệnh đó sẽ ngừng xử lý các yêu cầu mới.
Python
# Cancel a batch job
client.batches.cancel(name=batch_job_to_cancel.name)
REST
BATCH_NAME="batches/123456" # Your batch job name
# Cancel the batch
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME:cancel \
-H "x-goog-api-key: $GEMINI_API_KEY" \
# Confirm that the status of the batch after cancellation is JOB_STATE_CANCELLED
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type:application/json" 2> /dev/null | jq -r '.metadata.state'
Xoá một công việc hàng loạt
Bạn có thể xoá một lô công việc hiện có bằng tên của lô công việc đó. Khi một tác vụ bị xoá, tác vụ đó sẽ ngừng xử lý các yêu cầu mới và bị xoá khỏi danh sách các tác vụ hàng loạt.
Python
# Delete a batch job
client.batches.delete(name=batch_job_to_delete.name)
REST
BATCH_NAME="batches/123456" # Your batch job name
# Cancel the batch
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME:delete \
-H "x-goog-api-key: $GEMINI_API_KEY" \
Chi tiết kỹ thuật
- Các mô hình được hỗ trợ: Chế độ hàng loạt hỗ trợ nhiều mô hình Gemini. Tham khảo trang Mô hình để biết thông tin hỗ trợ Chế độ hàng loạt của từng mô hình. Các phương thức được hỗ trợ cho Chế độ hàng loạt cũng giống như các phương thức được hỗ trợ trên API tương tác (hoặc chế độ không theo lô).
- Giá: Mức giá sử dụng Chế độ xử lý hàng loạt bằng 50% chi phí API tương tác tiêu chuẩn cho mô hình tương đương. Hãy xem trang giá để biết thông tin chi tiết. Hãy tham khảo trang giới hạn về tốc độ để biết thông tin chi tiết về giới hạn tốc độ của tính năng này.
- Mục tiêu mức độ dịch vụ (SLO): Các lệnh hàng loạt được thiết kế để hoàn tất trong vòng 24 giờ. Nhiều công việc có thể hoàn tất nhanh hơn nhiều tuỳ thuộc vào kích thước và mức tải hiện tại của hệ thống.
- Lưu vào bộ nhớ đệm: Đã bật tính năng lưu vào bộ nhớ đệm theo bối cảnh cho các yêu cầu theo lô. Nếu một yêu cầu trong lô của bạn dẫn đến một lượt truy cập vào bộ nhớ đệm, thì các mã thông báo được lưu vào bộ nhớ đệm sẽ có giá tương tự như lưu lượng truy cập ở chế độ không theo lô.
Các phương pháp hay nhất
- Sử dụng tệp đầu vào cho các yêu cầu lớn: Đối với một số lượng lớn yêu cầu, hãy luôn sử dụng phương thức đầu vào tệp để quản lý tốt hơn và tránh vượt quá giới hạn kích thước yêu cầu cho chính lệnh gọi
BatchGenerateContent
. Xin lưu ý rằng mỗi tệp đầu vào có giới hạn kích thước là 2 GB. - Xử lý lỗi: Kiểm tra
batchStats
để tìmfailedRequestCount
sau khi một công việc hoàn tất. Nếu sử dụng đầu ra tệp, hãy phân tích cú pháp từng dòng để kiểm tra xem đó có phải làGenerateContentResponse
hay một đối tượng trạng thái cho biết lỗi cho yêu cầu cụ thể đó hay không. Hãy xem hướng dẫn khắc phục sự cố để biết toàn bộ tập hợp mã lỗi. - Gửi công việc một lần: Việc tạo một công việc hàng loạt không phải là thao tác bất biến. Nếu bạn gửi cùng một yêu cầu tạo hai lần, thì hai công việc hàng loạt riêng biệt sẽ được tạo.
- Chia các lô rất lớn thành nhiều lô nhỏ: Mặc dù thời gian xử lý mục tiêu là 24 giờ, nhưng thời gian xử lý thực tế có thể thay đổi tuỳ thuộc vào tải hệ thống và quy mô công việc. Đối với các công việc lớn, hãy cân nhắc việc chia chúng thành các lô nhỏ hơn nếu bạn cần kết quả trung gian sớm hơn.
Bước tiếp theo
Hãy xem sổ tay ở chế độ hàng loạt để biết thêm ví dụ.