تم تصميم "وضع المعالجة المجمّعة" في Gemini API لمعالجة كميات كبيرة من الطلبات بشكل غير متزامن بنصف التكلفة العادية. الوقت المستهدف لإتمام العملية هو 24 ساعة، ولكن في معظم الحالات، يكون الوقت أقصر بكثير.
استخدِم "وضع المعالجة المجمّعة" للمهام غير العاجلة على نطاق واسع، مثل المعالجة المسبقة للبيانات أو إجراء التقييمات التي لا تتطلّب ردًا فوريًا.
البدء
يساعدك هذا القسم في بدء إرسال طلباتك الأولى في وضع الدُفعات.
إنشاء مهمة مجمّعة
تتوفّر طريقتان لإرسال طلباتك في "وضع الدُفعات":
- الطلبات المضمّنة: قائمة بعناصر
GenerateContentRequest
مضمّنة مباشرةً في طلب إنشاء المجموعة. هذه الطريقة مناسبة للدفعات الأصغر التي تحافظ على إجمالي حجم الطلب أقل من 20 ميغابايت. الناتج الذي يعرضه النموذج هو قائمة بعناصرinlineResponse
. - ملف الإدخال: ملف JSON Lines (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="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"
}
}
]
}
}
}
}'
يمكنك استخدام أي طلبات تستخدمها في الوضع غير المجمّع (أو التفاعلي). على سبيل المثال، يمكنك تحديد درجة الحرارة أو تعليمات النظام أو حتى تمرير وسائط أخرى. يعرض المثال التالي بعض الطلبات المضمّنة النموذجية التي تحتوي على تعليمات نظام لأحد الطلبات:
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.'}]}}
]
وبالمثل، يمكنك أيضًا تحديد الأدوات التي تريد استخدامها لتنفيذ طلب. يعرض المثال التالي طلبًا يفعّل أداة "بحث Google":
inline_requests_list = [
{'contents': [{'parts': [{'text': 'Who won the euro 1998?'}]}]},
{'contents': [{'parts': [{'text': 'Who won the euro 2025?'}]}], 'tools': [{'google_search ': {}}]}
]
ملف الإدخال
بالنسبة إلى مجموعات الطلبات الأكبر، عليك إعداد ملف JSON Lines (JSONL). يجب أن يكون كل سطر في هذا الملف عبارة عن عنصر JSON يحتوي على مفتاح يحدّده المستخدم وعنصر طلب، حيث يكون الطلب عنصر GenerateContentRequest
صالحًا. يتم استخدام المفتاح الذي يحدّده المستخدم في الردّ للإشارة إلى الناتج الذي يمثّل نتيجة الطلب. على سبيل المثال، سيتمّ التعليق التوضيحي على الاستجابة للطلب الذي تمّ تحديد المفتاح له على أنّه request-1
باسم المفتاح نفسه.
يتم تحميل هذا الملف باستخدام File API. الحد الأقصى لحجم ملف الإدخال المسموح به هو 2 غيغابايت.
في ما يلي مثال على ملف JSONL. يمكنك حفظه في ملف باسم
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?"}]}]}}
كما هو الحال مع الطلبات المضمّنة، يمكنك تحديد مَعلمات أخرى، مثل تعليمات النظام أو الأدوات أو الإعدادات الأخرى، في كل JSON خاص بالطلب.
يمكنك تحميل هذا الملف باستخدام File API كما هو موضّح في المثال التالي. إذا كنت تعمل باستخدام الإدخال المتعدّد الوسائط، يمكنك الرجوع إلى ملفات أخرى تم تحميلها ضمن ملف 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)
يستدعي المثال التالي الطريقة BatchGenerateContent
باستخدام ملف الإدخال الذي تم تحميله باستخدام 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}
}
}
}
}"
عند إنشاء مهمة مجمّعة، سيتم عرض اسم المهمة. استخدِم هذا الاسم لتتبُّع حالة المهمة واسترداد النتائج بعد اكتمالها.
في ما يلي مثال على ناتج يحتوي على اسم وظيفة:
Created batch job from file: batches/123456789
مراقبة حالة مهمة المراقبة
استخدِم اسم العملية الذي تم الحصول عليه عند إنشاء مهمة الدفعات للاطّلاع على حالتها. سيشير حقل الحالة في مهمة الدفعة إلى حالتها الحالية. يمكن أن تكون مهمة الدفعات في إحدى الحالات التالية:
JOB_STATE_PENDING
: تم إنشاء مهمة وتنتظر أن تعالجها الخدمة.JOB_STATE_SUCCEEDED
: اكتملت المهمة بنجاح. يمكنك الآن استرداد النتائج.JOB_STATE_FAILED
: تعذّر إكمال المهمة. راجِع تفاصيل الخطأ للحصول على مزيد من المعلومات.-
JOB_STATE_CANCELLED
: ألغى المستخدم مهمة الطباعة.
يمكنك الاستعلام عن حالة المهمة بشكل دوري للتحقّق من اكتمالها.
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}")
جارٍ استرداد النتائج
بعد أن تشير حالة المهمة إلى أنّ مهمة المعالجة المجمّعة قد نجحت، ستتوفّر النتائج في الحقل 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
إلغاء مهمة مجمّعة
يمكنك إلغاء مهمة مجمّعة قيد التنفيذ باستخدام اسمها. عند إلغاء مهمة، تتوقّف عن معالجة الطلبات الجديدة.
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'
حذف مهمة دفعية
يمكنك حذف مهمة معالجة مجمّعة حالية باستخدام اسمها. عند حذف مهمة، تتوقف معالجة الطلبات الجديدة وتتم إزالتها من قائمة المهام المجمّعة.
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" \
التفاصيل الفنية
- الطُرز المتوافقة: يتوافق "وضع الدُفعات" مع مجموعة من طُرز Gemini. يُرجى الرجوع إلى صفحة الطُرز للاطّلاع على أحدث قائمة بالطُرز المتوافقة. إنّ الوسائط المتوافقة مع "الوضع المجمّع" هي نفسها المتوافقة مع واجهة برمجة التطبيقات التفاعلية (أو الوضع غير المجمّع).
- التسعير: يتم تسعير استخدام "وضع الدُفعات" بنسبة% 50 من التكلفة العادية لواجهة برمجة التطبيقات التفاعلية المكافئة.
- هدف مستوى الخدمة (SLO): تم تصميم مهام المعالجة المجمّعة لتكتمل في غضون 24 ساعة. قد تكتمل العديد من المهام بشكل أسرع بكثير اعتمادًا على حجمها والحمولة الحالية للنظام.
- التخزين المؤقت: تم تفعيل التخزين المؤقت للسياق لطلبات الدفعات. إذا أدّى طلب في دفعتك إلى تطابق مع البيانات المخزّنة مؤقتًا، سيتم تسعير الرموز المميزة المخزّنة مؤقتًا بالطريقة نفسها كما في الزيارات غير المجمّعة.
أفضل الممارسات
- استخدام ملفات الإدخال للطلبات الكبيرة: بالنسبة إلى عدد كبير من الطلبات، استخدِم دائمًا طريقة إدخال الملفات لتسهيل الإدارة وتجنُّب تجاوز حدود حجم الطلبات لمكالمة
BatchGenerateContent
نفسها. يُرجى العِلم أنّ الحدّ الأقصى المسموح به لحجم الملف الواحد هو 2 غيغابايت. - التعامل مع الأخطاء: تحقَّق من
batchStats
بحثًا عنfailedRequestCount
بعد اكتمال مهمة. في حال استخدام إخراج الملف، حلِّل كل سطر للتحقّق مما إذا كانGenerateContentResponse
أو عنصر حالة يشير إلى حدوث خطأ في هذا الطلب المحدّد. - إرسال المهام مرة واحدة: لا يمكن تكرار إنشاء مهمة مجمّعة. إذا أرسلت طلب الإنشاء نفسه مرتين، سيتم إنشاء مهمتَي دفعة منفصلتَين.
- تقسيم الدفعات الكبيرة جدًا: على الرغم من أنّ الوقت المستهدف لإتمام المعالجة هو 24 ساعة، قد يختلف وقت المعالجة الفعلي استنادًا إلى حمل النظام وحجم المهمة. بالنسبة إلى المهام الكبيرة، ننصحك بتقسيمها إلى مجموعات أصغر إذا كنت بحاجة إلى نتائج وسيطة في وقت أقرب.
الخطوات التالية
اطّلِع على دفتر ملاحظات وضع الدُفعات للحصول على مزيد من الأمثلة.