Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Batch API: Μαζική Ασύγχρονη Επεξεργασία

Μάθημα 6 / 20 Ενημερώθηκε 3 Νοεμβρίου 2026 Προχωρημένος
Σε αυτήν τη σελίδα
  1. Ανταλλάξτε τον Χρόνο Απόκρισης με Κόστος
  2. Δημιουργία και Εκκίνηση ενός Batch
  3. Προγραμματίστε τις Μερικές Αποτυχίες
  4. Αυξήστε τις Εξοικονομήσεις σας
  5. Βασικά σημεία

Ενημερώθηκε στις 3 Νοεμβρίου 2026 με βάση τον οδηγό Batch API και τη δομή απόκρισης του Responses API: η ανάγνωση των αποτελεσμάτων δεν υποθέτει πλέον ότι το πρώτο στοιχείο του output είναι το μήνυμα (ένα στοιχείο συλλογισμού μπορεί να προηγείται), και το κλειδί του κωδικού σφάλματος, γραμμένο χωρίς εισαγωγικά, προκαλούσε NameError. Πηγή: Batch API.

Ανταλλάξτε τον Χρόνο Απόκρισης με Κόστος

Το Batch API λειτουργεί με βάση μια απλή αρχή της αγοράς: αποδέχεστε ότι τα αιτήματά σας θα επεξεργαστούν ασύγχρονα εντός ενός παραθύρου έως και είκοσι τεσσάρων ωρών και, σε αντάλλαγμα, πληρώνετε πενήντα τοις εκατό λιγότερο. Οτιδήποτε δεν χρειάζεται να εξυπηρετήσει έναν άνθρωπο που περιμένει μπροστά στην οθόνη του εμπίπτει σε αυτή την κατηγορία. Σε μεγάλη κλίμακα, αυτό δεν είναι μια μικρο-βελτιστοποίηση· μειώνει τον προϋπολογισμό σας στο μισό.

Η συνήθεια που πρέπει να καλλιεργήσετε στην ομάδα σας είναι να ρωτάτε, για κάθε νέα εργασία επεξεργασίας, αν κάποιος περιμένει το αποτέλεσμα. Ανάλυση αποθέματος συμβολαίων, δημιουργία δελτίων προϊόντων για έναν κατάλογο, εκτέλεση benchmark σε χιλιάδες περιπτώσεις δοκιμής, ταξινόμηση ενός backlog εισιτηρίων έξι μηνών, εξαγωγή πεδίων από ένα σύνολο τιμολογίων: σε όλες αυτές τις περιπτώσεις, η απάντηση καταλήγει σε έναν πίνακα ελέγχου ή σε μια βάση δεδομένων, όχι σε μια διεπαφή συνομιλίας. Η καθυστέρηση είναι αόρατη, αλλά η εξοικονόμηση όχι.

Δημιουργία και Εκκίνηση ενός Batch

Η μορφή εισόδου είναι ένα αρχείο JSONL: μία γραμμή ανά αίτημα, όπου κάθε γραμμή αποτελεί ένα πλήρες, ανεξάρτητο αντικείμενο. Το πεδίο custom_id είναι αυτό που σας επιτρέπει να συνδέσετε κάθε απόκριση με το αρχικό της αίτημα, καθώς τίποτα δεν εγγυάται τη σειρά του αρχείου εξόδου. Επιλέξτε ένα ID που είναι σταθερό και ουσιαστικό—ένα ID εγγράφου από τη βάση δεδομένων σας και όχι έναν αριθμό επανάληψης—διαφορετικά η φάση συμφιλίωσης θα μετατραπεί σε εφιάλτη.

import json

requests = [
    {
        "custom_id": f"doc-{i}",
        "method": "POST",
        "url": "/v1/responses",
        "body": {
            "model": "gpt-5.6-luna",
            "input": f"Summarize this document in 3 key points: {doc}",
            "max_output_tokens": 500,
        },
    }
    for i, doc in enumerate(documents_list)
]

# Write the JSONL file
with open("batch_input.jsonl", "w") as f:
    for request in requests:
        f.write(json.dumps(request) + "\n")

Το αρχείο στη συνέχεια μεταφορτώνεται και αναφέρεται κατά τη δημιουργία του batch. Τα μεταδεδομένα δεν εξυπηρετούν κανέναν τεχνικό σκοπό, αλλά θα σας σώσουν όταν τρέχουν τρία batch παράλληλα και πρέπει να βρείτε ποιο αντιστοιχεί σε ποια έκδοση prompt.

import openai

client = openai.OpenAI()

# Upload the file
file_obj = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

# Create the batch
batch = client.batches.create(
    input_file_id=file_obj.id,
    endpoint="/v1/responses",
    completion_window="24h",
    metadata={"project": "contract-analysis", "version": "2.1"},
)

print(f"Batch created: {batch.id}")
print(f"Status: {batch.status}")

Η παρακολούθηση περιλαμβάνει την περιοδική ερώτηση (polling) του batch μέχρι να εξέλθει από την κατάσταση «σε εξέλιξη» και στη συνέχεια τη λήψη του αρχείου εξόδου, το οποίο είναι επίσης σε μορφή JSONL. Ο παρακάτω βρόχος διακρίνει τρία τελικά αποτελέσματα—failed, expired, cancelled—και εγείρει μια εξαίρεση για το καθένα: ένα expired batch είναι εκείνο όπου το παράθυρο των είκοσι τεσσάρων ωρών παρήλθε πριν ολοκληρωθεί η επεξεργασία, και η αντιμετώπισή του ως σιωπηρή μερική επιτυχία θα ήταν η χειρότερη επιλογή.

import time

def wait_for_batch(batch_id: str, interval: int = 60) -> list:
    """Waits for a batch to finish and returns the results."""
    while True:
        batch = client.batches.retrieve(batch_id)
        print(
            f"Status: {batch.status} | "
            f"Completed: {batch.request_counts.completed}/"
            f"{batch.request_counts.total} | "
            f"Failed: {batch.request_counts.failed}"
        )

        if batch.status == "completed":
            break
        elif batch.status in ("failed", "expired", "cancelled"):
            raise RuntimeError(f"Batch failed: {batch.status}")

        time.sleep(interval)

    # Download results
    content = client.files.content(batch.output_file_id)
    results = []
    for line in content.text.strip().split("\n"):
        results.append(json.loads(line))

    return results


results = wait_for_batch(batch.id)

# Process results
for result in results:
    custom_id = result["custom_id"]
    response = result["response"]
    if response["status_code"] == 200:
        # output may contain other elements before the message
        # (reasoning, for example): look for the message text
        text = next(
            part["text"]
            for item in response["body"]["output"] if item["type"] == "message"
            for part in item["content"] if part["type"] == "output_text"
        )
        print(f"{custom_id}: {text[:100]}...")
    else:
        print(f"{custom_id}: ERROR {response['status_code']}")

Προγραμματίστε τις Μερικές Αποτυχίες

Σε ένα μεγάλο batch, ορισμένα αιτήματα θα αποτύχουν: ένα περικομμένο έγγραφο, υπέρβαση του πλαισίου συμφραζομένων (context overflow) ή ένα παροδικό σφάλμα από την πλευρά του διακομιστή. Ένα batch therefore δεν είναι ποτέ απλώς «επιτυχημένο» ή «αποτυχημένο»—είναι μερικώς επιτυχημένο και πρέπει να ξέρετε πώς να απομονώσετε τοmissing μέρος. Το πρότυπο που πρέπει να υιοθετήσετε είναι να διαχωρίζετε άμεσα τις επιτυχίες από τις αποτυχίες και να αναδημιουργείτε ένα αρχείο JSONL έτοιμο για επανεκκίνηση, αντί να ψάχνετε στα αρχεία καταγραφής τρεις μέρες αργότερα για να ανακατασκευάσετε ό,τι λείπει.

def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
    """Separates successes from failures for reprocessing."""
    successes = []
    failures = []

    for r in results:
        if r["response"]["status_code"] == 200:
            successes.append(r)
        else:
            failures.append(r)

    if failures:
        print(f"Warning: {len(failures)} failed requests out of {len(results)}")
        # Rewrite a JSONL file with failures for retry
        with open("batch_retry.jsonl", "w") as f:
            for failure in failures:
                original_request = {
                    "custom_id": failure["custom_id"],
                    "method": "POST",
                    "url": "/v1/responses",
                    "body": failure["request"]["body"],
                }
                f.write(json.dumps(original_request) + "\n")

    return successes, failures

Αυξήστε τις Εξοικονομήσεις σας

Σε μια εκτέλεση επεξεργασίας δέκα χιλιάδων εγγράφων με το GPT-5.6 Luna, το synchronous API αντιπροσωπεύει το βασικό κόστος, το Batch API αντιπροσωπεύει το μισό αυτού, και η προσωρινή αποθήκευση prompt (prompt caching) προστίθεται επιπλέον, καθώς και τα cached tokens επωφελούνται από τη δική τους μείωση. Οι δύο μηχανισμοί δεν ανταγωνίζονται: αν τα δέκα χιλιάδες αιτήματά σας μοιράζονται το ίδιο μεγάλο prompt συστήματος, δομήστε το ως ένα σταθερό πρόθεμα και θα συνδυάσετε και τα δύο εφέ.

Τέλος, υπάρχει το ζήτημα του διαχωρισμού. Ένα batch δεν πρέπει να είναι άπειρο και είναι πιο βολικό να παρακολουθείτε πολλά διαχειρίσιμα batch παρά έναν μονόλιθο του οποίου η αποτυχία κοστίζει μια ολόκληρη ημέρα. Η παρακάτω συνάρτηση τεμαχίζει μια λίστα αιτημάτων σε batch οριοθετημένου μεγέθους.

def create_optimized_batches(
    requests: list[dict],
    max_size: int = 50_000,
) -> list[list[dict]]:
    """Splits into batches of optimal size."""
    batches = []
    current_batch = []

    for request in requests:
        current_batch.append(request)
        if len(current_batch) >= max_size:
            batches.append(current_batch)
            current_batch = []

    if current_batch:
        batches.append(current_batch)

    return batches

Βασικά σημεία

  • Το Batch API προσφέρει μείωση 50% για επεξεργασία μη πραγματικού χρόνου
  • Προετοιμάστε τα αιτήματά σας σε ένα αρχείο JSONL με ένα μοναδικό custom_id ανά αίτημα
  • Σχεδιάστε έναν μηχανισμό επαναδοκιμής για τα αποτυχημένα αιτήματα
  • Συνδυάστε με την προσωρινή αποθήκευση prompt (prompt caching) για μεγιστοποίηση της εξοικονόμησης