Mode Batch

Mode Batch Gemini API dirancang untuk memproses permintaan dalam volume besar secara asinkron dengan 50% dari biaya standar. Waktu penyelesaian yang ditargetkan adalah 24 jam, tetapi dalam sebagian besar kasus, hasilnya jauh lebih cepat.

Gunakan Mode Batch untuk tugas berskala besar yang tidak mendesak seperti pra-pemrosesan data atau menjalankan evaluasi yang tidak memerlukan respons langsung.

Membuat tugas batch

Anda memiliki dua cara untuk mengirimkan permintaan dalam Mode Batch:

  • Permintaan Inline: Daftar objek GenerateContentRequest yang disertakan langsung dalam permintaan pembuatan batch Anda. Cara ini cocok untuk tumpukan yang lebih kecil yang menjaga ukuran total permintaan di bawah 20 MB. Output yang ditampilkan dari model adalah daftar objek inlineResponse.
  • File Input: File JSON Lines (JSONL) dengan setiap baris berisi objek GenerateContentRequest yang lengkap. Metode ini direkomendasikan untuk permintaan yang lebih besar. Output yang ditampilkan dari model adalah file JSONL dengan setiap barisnya berupa GenerateContentResponse atau objek status.

Permintaan inline

Untuk sejumlah kecil permintaan, Anda dapat menyematkan objek GenerateContentRequest secara langsung dalam BatchGenerateContentRequest Anda. Contoh berikut memanggil metode BatchGenerateContent dengan permintaan inline:

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"                         }                     }                 ]             }         }     } }' 

File masukan:

Untuk kumpulan permintaan yang lebih besar, siapkan file JSON Lines (JSONL). Setiap baris dalam file ini harus berupa objek JSON yang berisi kunci yang ditentukan pengguna dan objek permintaan, dengan permintaan adalah objek GenerateContentRequest yang valid. Kunci yang ditentukan pengguna digunakan dalam respons untuk menunjukkan output mana yang merupakan hasil dari permintaan mana. Misalnya, permintaan dengan kunci yang ditentukan sebagai request-1 akan memiliki respons yang diberi anotasi dengan nama kunci yang sama.

File ini diupload menggunakan File API. Ukuran file input maksimum yang diizinkan adalah 2 GB.

Berikut adalah contoh file JSONL. Anda dapat menyimpannya dalam file bernama 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?"}]}]}} 

Mirip dengan permintaan inline, Anda dapat menentukan parameter lain seperti petunjuk sistem, alat, atau konfigurasi lain dalam setiap JSON permintaan.

Anda dapat mengupload file ini menggunakan File API seperti yang ditunjukkan dalam contoh berikut. Jika Anda bekerja dengan input multimodal, Anda dapat mereferensikan file lain yang diupload dalam file JSONL Anda.

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) 

Contoh berikut memanggil metode BatchGenerateContent dengan file input yang diupload menggunakan 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}             }         }     } }" 

Saat membuat tugas batch, Anda akan mendapatkan nama tugas yang ditampilkan. Gunakan nama ini untuk memantau status tugas serta mengambil hasilnya setelah tugas selesai.

Berikut adalah contoh output yang berisi nama tugas:

 Created batch job from file: batches/123456789  

Konfigurasi permintaan

Anda dapat menyertakan konfigurasi permintaan apa pun yang akan digunakan dalam permintaan non-batch standar. Misalnya, Anda dapat menentukan suhu, petunjuk sistem, atau bahkan meneruskan modalitas lain. Contoh berikut menunjukkan contoh permintaan inline yang berisi instruksi sistem untuk salah satu permintaan:

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.'}]}} ] 

Demikian pula, Anda dapat menentukan alat yang akan digunakan untuk permintaan. Contoh berikut menunjukkan permintaan yang mengaktifkan alat Google Penelusuran:

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

Anda juga dapat menentukan output terstruktur. Contoh berikut menunjukkan cara menentukannya untuk permintaan batch Anda.

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', '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):     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)  

Memantau status tugas

Gunakan nama operasi yang diperoleh saat membuat tugas batch untuk melakukan polling statusnya. Kolom status tugas batch akan menunjukkan statusnya saat ini. Tugas batch dapat berada dalam salah satu status berikut:

  • JOB_STATE_PENDING: Tugas telah dibuat dan menunggu untuk diproses oleh layanan.
  • JOB_STATE_RUNNING: Tugas sedang berlangsung.
  • JOB_STATE_SUCCEEDED: Tugas berhasil diselesaikan. Sekarang Anda dapat mengambil hasilnya.
  • JOB_STATE_FAILED: Tugas gagal. Periksa detail error untuk mengetahui informasi selengkapnya.
  • JOB_STATE_CANCELLED: Tugas dibatalkan oleh pengguna.
  • JOB_STATE_EXPIRED: Tugas telah berakhir karena berjalan atau tertunda selama lebih dari 48 jam. Tugas tidak akan memiliki hasil untuk diambil. Anda dapat mencoba mengirimkan tugas lagi atau membagi permintaan menjadi beberapa batch yang lebih kecil.

Anda dapat melakukan polling status tugas secara berkala untuk memeriksa penyelesaian.

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',     '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}") 

Mengambil hasil

Setelah status tugas menunjukkan bahwa tugas batch Anda berhasil, hasilnya akan tersedia di kolom 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" elif [[ $batch_state == "JOB_STATE_EXPIRED" ]]; then     echo "Batch expired after 48 hours" fi 

Membatalkan tugas batch

Anda dapat membatalkan tugas batch yang sedang berlangsung menggunakan namanya. Jika dibatalkan, tugas akan berhenti memproses permintaan baru.

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' 

Menghapus tugas batch

Anda dapat menghapus tugas batch yang ada menggunakan namanya. Jika dihapus, tugas akan berhenti memproses permintaan baru dan dihapus dari daftar tugas batch.

Python

# Delete a batch job client.batches.delete(name=batch_job_to_delete.name) 

REST

BATCH_NAME="batches/123456" # Your batch job name  # Delete the batch job curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME:delete \ -H "x-goog-api-key: $GEMINI_API_KEY" 

Detail teknis

  • Model yang didukung: Mode Batch mendukung berbagai model Gemini. Lihat halaman Model untuk mengetahui dukungan setiap model terhadap Mode Batch. Modalitas yang didukung untuk Mode Batch sama dengan yang didukung di API interaktif (atau mode non-batch).
  • Harga: Penggunaan Mode Batch dikenai biaya 50% dari biaya API interaktif standar untuk model yang setara. Lihat halaman harga untuk mengetahui detailnya. Lihat halaman batas kapasitas untuk mengetahui detail tentang batas kapasitas untuk fitur ini.
  • Tujuan Tingkat Layanan (SLO): Tugas batch dirancang untuk selesai dalam waktu penyelesaian 24 jam. Banyak tugas dapat diselesaikan lebih cepat bergantung pada ukuran dan beban sistem saat ini.
  • Penyimpanan ke cache: Penyimpanan ke cache konteks diaktifkan untuk permintaan batch. Jika permintaan dalam batch Anda menghasilkan hit cache, token yang di-cache akan dikenai harga yang sama seperti traffic mode non-batch.

Praktik terbaik

  • Gunakan file input untuk permintaan besar: Untuk sejumlah besar permintaan, selalu gunakan metode input file agar lebih mudah dikelola dan untuk menghindari batas ukuran permintaan untuk panggilan BatchGenerateContent itu sendiri. Perhatikan bahwa ada batasan ukuran file 2 GB per file input.
  • Penanganan error: Periksa batchStats untuk failedRequestCount setelah tugas selesai. Jika menggunakan output file, parsing setiap baris untuk memeriksa apakah itu GenerateContentResponse atau objek status yang menunjukkan error untuk permintaan tertentu tersebut. Lihat panduan pemecahan masalah untuk mengetahui kumpulan lengkap kode error.
  • Kirimkan tugas satu kali: Pembuatan tugas batch tidak bersifat idempoten. Jika Anda mengirim permintaan pembuatan yang sama dua kali, dua tugas batch terpisah akan dibuat.
  • Membagi batch yang sangat besar: Meskipun target waktu penyelesaian adalah 24 jam, waktu pemrosesan sebenarnya dapat bervariasi berdasarkan beban sistem dan ukuran tugas. Untuk tugas besar, pertimbangkan untuk membaginya menjadi batch yang lebih kecil jika hasil sementara diperlukan lebih cepat.

Langkah berikutnya

Lihat notebook mode batch untuk contoh lainnya.