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 objekinlineResponse
. - 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 berupaGenerateContentResponse
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
untukfailedRequestCount
setelah tugas selesai. Jika menggunakan output file, parsing setiap baris untuk memeriksa apakah ituGenerateContentResponse
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.