Batch API: Масова асинхронна обработка
На тази страница
Обновено на 3 ноември 2026 г. въз основа на ръководството за Batch API и структурата на отговорите на Responses API: четенето на резултатите вече не предполага, че първият елемент на
outputе съобщението (преди него може да има елемент за разсъждение), а ключът за код на грешка, записан без кавички, предизвиквашеNameError. Източник: Batch API.
Размяна на латентност срещу цена
Batch API работи на прост пазарен принцип: приемате, че заявките Ви ще бъдат обработени асинхронно в прозорец от до двадесет и четири часа, а в замяна плащате с петдесет процента по-малко. Всичко, което не трябва да обслужва човек, чакащ пред екрана си, попада в тази категория. В мащаб това не е микрооптимизация; то прерязва бюджетната Ви линия наполовина.
Навикът, който трябва да изградите в екипа, е да питате за всяка нова задача за обработка дали някой чака резултата. Анализ на запас от договори, генериране на продуктови листовки за каталог, стартиране на бенчмарк върху хиляди тестови случаи, класифициране на шестмесечно натрупване на тикети, извличане на полета от партида фактури: във всички тези случаи отговорът попада в табло или база данни, а не в конферентен интерфейс. Забавянето е невидимо, но спестяванията – не.
Изграждане и стартиране на партида
Входният формат е 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")
След това файлът се качва и се използва като референция при създаването на партидата. Метаданните нямат техническа цел, но ще Ви спасят деня, когато три партиди работят паралелно и трябва да разберете коя на коя версия на промпта съответства.
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}")
Мониторингът включва периодично проверяване на партидата, докато излезе от състояние „в процес“, след което се изтегля изходният файл, който също е във формат JSONL. Цикълът по-долу разграничава три крайни резултата – failed, expired, cancelled – и поражда изключение за всеки: изтекла партида е такава, при която двадесет и четиричасовият прозорец е изтекъл, преди всичко да бъде обработено, и третирането ѝ като тих частичен успех би било най-лошият вариант.
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']}")
Планиране на частични грешки
При голяма партида някои заявки ще се провалят: съкратен документ, препълване на контекста или преходна грешка от страна на сървъра. Следователно една партида никога не е просто „успешна“ или „провалена“ – тя е частично успешна и трябва да знаете как да изолирате липсващата част. Моделът, който трябва да приемете, е незабавно да разделите успехите от грешките и да генерирате отново 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 синхронният API представлява базовата цена, Batch API представлява половината от нея, а кеширането на промптове се добавя отгоре, тъй като кешираните токени също се възползват от собственото си намаление. Двата механизма не се конкурират: ако Вашите десет хиляди заявки споделят един и същи дълъг системен промпт, структурирайте го като стабилен префикс и ще умножите двата ефекта.
Накрая идва въпросът за разделянето. Една партида не трябва да бъде безкрайна и е по-удобно да мониторите няколко управляеми партиди, отколкото един монолит, чийто провал струва цял ден. Следната функция разрязва списък със заявки на партиди с ограничен размер.
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за всяка заявка - Планирайте механизъм за повторен опит при неуспешни заявки
- Комбинирайте с кеширане на промптове, за да максимизирате спестяванията