Modaliteti Batch i Gemini API është krijuar për të përpunuar vëllime të mëdha kërkesash në mënyrë asinkrone me 50% të kostos standarde . Koha e kthimit të synuar është 24 orë, por në shumicën e rasteve, është shumë më e shpejtë.
Përdorni Batch Mode për detyra të shkallës së gjerë, jo urgjente, si p.sh. përpunimi paraprak i të dhënave ose ekzekutimi i vlerësimeve, ku nuk kërkohet një përgjigje e menjëhershme.
Fillimi
Ky seksion ju ndihmon të filloni me paraqitjen e kërkesave tuaja të para në modalitetin e grupit.
Krijimi i një pune grupi
Ju keni dy mënyra për të paraqitur kërkesat tuaja në Batch Mode:
- Kërkesat në linjë : Një listë e objekteve
GenerateContentRequest
të përfshira drejtpërdrejt në kërkesën tuaj për krijimin e grupit. Ky është i përshtatshëm për grupe më të vogla që mbajnë madhësinë totale të kërkesës nën 20 MB. Dalja e kthyer nga modeli është një listë e objekteveinlineResponse
. - Skedari hyrës : Një skedar JSON Lines (JSONL) ku çdo rresht përmban një objekt të plotë
GenerateContentRequest
. Kjo metodë rekomandohet për kërkesa më të mëdha. Prodhimi i kthyer nga modeli është një skedar JSONL ku çdo rresht është ose njëGenerateContentResponse
ose një objekt statusi.
Kërkesat inline
Për një numër të vogël kërkesash, ju mund të futni drejtpërdrejt objektet GenerateContentRequest
brenda BatchGenerateContentRequest
. Shembulli i mëposhtëm thërret metodën BatchGenerateContent
me kërkesa 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}")
PUSHIMI
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"
}
}
]
}
}
}
}'
Ju mund të përdorni çdo kërkesë që do të përdorni në modalitetin jo grupor (ose interaktiv). Për shembull, mund të specifikoni temperaturën, udhëzimet e sistemit apo edhe të kaloni në modalitete të tjera. Shembulli i mëposhtëm tregon disa shembuj të kërkesave inline që përmbajnë një udhëzim të sistemit për një nga kërkesat:
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.'}]}}
]
Në mënyrë të ngjashme mund të specifikoni gjithashtu mjete për t'u përdorur për një kërkesë. Shembulli i mëposhtëm tregon një kërkesë që mundëson veglën e Kërkimit të Google :
inline_requests_list = [
{'contents': [{'parts': [{'text': 'Who won the euro 1998?'}]}]},
{'contents': [{'parts': [{'text': 'Who won the euro 2025?'}]}], 'tools': [{'google_search ': {}}]}
]
Skedari hyrës
Për grupe më të mëdha kërkesash, përgatitni një skedar JSON Lines (JSONL). Çdo rresht në këtë skedar duhet të jetë një objekt JSON që përmban një çelës të përcaktuar nga përdoruesi dhe një objekt kërkese, ku kërkesa është një objekt i vlefshëm GenerateContentRequest
. Çelësi i përcaktuar nga përdoruesi përdoret në përgjigje për të treguar se cili dalje është rezultat i cilës kërkesë. Për shembull, kërkesa me çelësin e përcaktuar si request-1
do të ketë përgjigjen e saj të shënuar me të njëjtin emër kyç.
Ky skedar ngarkohet duke përdorur API-në e skedarit . Madhësia maksimale e lejuar e skedarit për një skedar hyrës është 2 GB.
Më poshtë është një shembull i një skedari JSONL. Mund ta ruani në një skedar të quajtur 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?"}]}]}}
Ngjashëm me kërkesat inline, mund të specifikoni parametra të tjerë si udhëzimet e sistemit, veglat ose konfigurimet e tjera në secilën kërkesë JSON.
Ju mund ta ngarkoni këtë skedar duke përdorur API-në e skedarit siç tregohet në shembullin e mëposhtëm. Nëse jeni duke punuar me hyrje multimodale, mund t'i referoheni skedarëve të tjerë të ngarkuar brenda skedarit tuaj 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}")
PUSHIMI
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)
Shembulli i mëposhtëm thërret metodën BatchGenerateContent
me skedarin hyrës të ngarkuar duke përdorur 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}")
PUSHIMI
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}
}
}
}
}"
Kur krijoni një punë grupore, do t'ju kthehet një emër pune. Përdoreni këtë emër për të monitoruar statusin e punës, si dhe për të marrë rezultatet pasi të përfundojë puna.
Më poshtë është një shembull i prodhimit që përmban një emër pune:
Created batch job from file: batches/123456789
Monitorimi i statusit të punës
Përdorni emrin e operacionit të marrë kur krijoni punën e grupit për të anketuar statusin e saj. Fusha e gjendjes së punës së grupit do të tregojë statusin e saj aktual. Një punë grupore mund të jetë në një nga gjendjet e mëposhtme:
-
JOB_STATE_PENDING
: Puna është krijuar dhe është në pritje për t'u përpunuar nga shërbimi. -
JOB_STATE_SUCCEEDED
: Puna përfundoi me sukses. Tani mund t'i rikuperoni rezultatet. -
JOB_STATE_FAILED
: Puna dështoi. Kontrolloni detajet e gabimit për më shumë informacion. -
JOB_STATE_CANCELLED
: Puna u anulua nga përdoruesi.
Ju mund të anketoni statusin e punës në mënyrë periodike për të kontrolluar për përfundimin.
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}")
Marrja e rezultateve
Pasi statusi i punës tregon se puna juaj në grup ka pasur sukses, rezultatet janë të disponueshme në fushën 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}")
PUSHIMI
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
Anulimi i një pune grupore
Ju mund të anuloni një punë grupore në vazhdim duke përdorur emrin e saj. Kur një punë anulohet, ajo ndalon përpunimin e kërkesave të reja.
Python
# Cancel a batch job
client.batches.cancel(name=batch_job_to_cancel.name)
PUSHIMI
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'
Fshirja e një pune grupore
Ju mund të fshini një punë të grupit ekzistues duke përdorur emrin e saj. Kur një punë fshihet, ajo ndalon përpunimin e kërkesave të reja dhe hiqet nga lista e punëve në grup.
Python
# Delete a batch job
client.batches.delete(name=batch_job_to_delete.name)
PUSHIMI
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" \
Detaje teknike
- Modelet e mbështetura: Batch Mode mbështet një sërë modelesh Gemini. Referojuni faqes Modele për listën më të fundit të modeleve të përputhshme. Modalitetet e mbështetura për Batch Mode janë të njëjta me ato që mbështeten në API-në interaktive (ose jo-batch).
- Çmimi: Përdorimi i modalitetit të grupit kushton 50% të kostos standarde të API interaktive për modelin ekuivalent.
- Objektivi i Nivelit të Shërbimit (SLO): Punët e grupit janë krijuar për t'u përfunduar brenda një kohe kthimi 24-orësh. Shumë punë mund të përfundojnë shumë më shpejt në varësi të madhësisë së tyre dhe ngarkesës aktuale të sistemit.
- Caching: Memoria e përmbajtjes është aktivizuar për kërkesat e grupit. Nëse një kërkesë në grupin tuaj rezulton në një goditje të memories së memories, shenjat e ruajtura në memorie kanë të njëjtin çmim si për trafikun në modalitetin jo të grupit.
Praktikat më të mira
- Përdorni skedarët e hyrjes për kërkesa të mëdha: Për një numër të madh kërkesash, përdorni gjithmonë metodën e futjes së skedarit për menaxhim më të mirë dhe për të shmangur goditjen e kufijve të madhësisë së kërkesës për vetë thirrjen
BatchGenerateContent
. Vini re se ekziston një kufi i madhësisë së skedarit prej 2 GB për skedar hyrës. - Trajtimi i gabimit: Kontrolloni
batchStats
përfailedRequestCount
pasi të përfundojë një punë. Nëse përdorni daljen e skedarit, analizoni çdo rresht për të kontrolluar nëse është njëGenerateContentResponse
ose një objekt statusi që tregon një gabim për atë kërkesë specifike. - Paraqisni punë një herë: Krijimi i një pune grupi nuk është i pafuqishëm. Nëse dërgoni dy herë të njëjtën kërkesë krijimi, do të krijohen dy punë të veçanta grupore.
- Ndarja e tufave shumë të mëdha: Ndërsa koha e synuar e kthimit është 24 orë, koha aktuale e përpunimit mund të ndryshojë në bazë të ngarkesës së sistemit dhe madhësisë së punës. Për punë të mëdha, merrni parasysh ndarjen e tyre në grupe më të vogla nëse nevojiten më shpejt rezultate të ndërmjetme.
Çfarë është më pas
Shikoni fletoren e modalitetit të grupit për më shumë shembuj.