Modaliteti i grupit

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 objekteve inlineResponse .
  • 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ër failedRequestCount 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.