Работен поток в четири стъпки
На тази страница
Обновено на 2 ноември 2026 г. въз основа на документацията на xAI: отстъпката за пакетна обработка е 20% за допустимите текстови модели (не 50%); примерите използват REST API и официалния
xai-sdk(client.batch.*; Batch API на xAI не следва формата на OpenAI, следователно SDK на OpenAI не се прилага); и Responses API има предимство пред Chat Completions, който е остаряла крайна точка при xAI. Източници: Batch API · REST справка · Цени за пакетна обработка.
Животът на един пакет
Всеки пакет следва един и същ цикъл: създаване, добавяне на заявки, обработка, извличане на резултати. Разбирането на този цикъл е от съществено значение, преди да преминете към внедряване, тъй като всяка стъпка има свои собствени ограничения и най-добри практики.
Стъпка 1: Създаване на пакет
Всичко започва с повикване POST /v1/batches, което изисква едно задължително поле: името на пакета. API връща уникален идентификатор (batch_id), който използвате за всички последващи операции.
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "customer_review_analysis"}'
Отговорът съдържа също датите на създаване и изтичане на пакета (create_time, expire_time) и обект state, чиито броячи все още са нула.
Стъпка 2: Добавяне на заявки
Съществуват два метода:
Чрез API: изпращате заявки с POST /v1/batches/{batch_id}/requests. Всяко повикване носи списък със заявки и можете да продължите да ги добавяте, докато пакетът не бъде отменен. Това е пътят за пакети, изградени постепенно.
Чрез JSONL файл: подготвяте файл, съдържащ всички ваши заявки, качвате го чрез Files API и след това създавате пакета от този файл. Тогава пакетът се запечатва: повече добавяния не са възможни. Това е пътят за големи обеми, подготвени предварително.
Всяка заявка носи уникален идентификатор в рамките на пакета: batch_request_id в API, custom_id в JSONL файла. Ако го пропуснете в API, xAI генерира UUID; предоставете свой собствен вместо това (например ID на база данни): той служи като ключ за съпоставяне между вашите данни и резултатите и гарантира, че дадена заявка се обработва само веднъж.
Стъпка 3: Мониторинг на прогреса
Обработката започва веднага щом пристигнат заявките; няма стъпка „стартиране“. Междувременно GET /v1/batches/{batch_id} връща обекта state и неговите броячи: num_requests (общо), num_pending (в очакване), num_success (успешни), num_error (неуспешни) и num_cancelled (отменени).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Когато num_pending спадне до нула, всички заявки са обработени, успешно или не. Периодичното запитване (polling) е достатъчно: няколко секунди за малък тестов пакет, няколко минути за голям пакет.
Стъпка 4: Извличане на резултати
Резултатите се четат с GET /v1/batches/{batch_id}/results, без да се чака пакетът да приключи: всяка заявка е налична веднага щом бъде обработена. Отговорът е странициран: limit задава размера на страницата (максимум 1000), а върнатият pagination_token се използва за заявка на следващата страница; той е празен на последната страница.
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Всеки резултат носи batch_request_id на своята заявка: това ви позволява да възстановите съпоставянето между вашите входни данни и отговорите на Grok.
Работният поток на практика
В производствен конвейер работният поток обикновено се превръща в два отделни процеса:
- Процес на подаване, който създава пакета, подготвя и добавя заявките, след което съхранява
batch_id - Процес на извличане, който периодично проверява броячите и изтегля резултатите, щом станат налични
Това разделяне ви позволява да интегрирате Batch API в архитектуры, базирани на събития, или в съществуващи конвейери за данни (cron задачи, Apache Airflow, опашки).
Обработка на грешки в работния поток
Един пакет няма глобално състояние „успешен“ или „неуспешен“: вие го четете чрез неговите броячи. Неуспешната заявка увеличава num_error и се появява в резултатите със своето съобщение за грешка, без да блокира останалите. Следователно трябва да разгледате всеки резултат и да обработвате неуспехите случай по случай.
Две събития засягат целия пакет. Първото е отменяне, от ваша страна или от xAI, което тогава го обяснява в полето cancel_by_xai_message. Това се случва по-специално, когато ред в JSONL файл е невалиден. Другото е изтичане (expire_time), след което резултатите вече не са достъпни: извлечете ги своевременно.
Ключови изводи
- Работният поток следва реда: създаване (с име), добавяне, мониторинг, извличане
- Идентификаторът на заявката (
batch_request_idилиcustom_idв JSONL) е вашият ключ за съпоставяне - Прогресът се чете от броячите на
state; всичко е обработено, когатоnum_pendingе нула - Резултатите са страницирани (
limit,pagination_token) и са налични, щом бъдат обработени - Грешките се обработват заявка по заявка; отменянето и изтичането засягат целия пакет