Премини към основното съдържание
Български— Изберете език
Меню

Проследяване, статус и анулиране

Урок 11 от 12 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Управление на жизнения цикъл на пакета
  2. Две нива на статус
  3. Проверка на броячите
  4. Списък с вашите пакети
  5. Извличане на резултати
  6. Проверка на метаданните на заявката
  7. Анулиране на пакет
  8. Стратегия за периодично запитване (Polling)
  9. Ключови изводи

Обновено на 2 ноември 2026 г. въз основа на документацията на xAI: отстъпката за пакетна обработка е 20% за допустимите текстови модели (не 50%), примерите следват REST API и официалния xai-sdk (client.batch.*; Batch API на xAI не съвпада с формата на OpenAI, следователно OpenAI SDK не се прилага), а Responses API има предимство пред Chat Completions, който е остаряла крайна точка в xAI. Източници: Batch API · REST Reference · Batch Pricing.

Управление на жизнения цикъл на пакета

След като подадете заявките си, трябва да проследявате напредъка на обработката, да четете статусите и да знаете кога и как да анулирате пакет. Този урок обхваща всички налични операции за управление.

Две нива на статус

xAI проследява напредъка на две нива. Самият пакет няма глобален статус като „завършен“ или „неуспешен“: той съдържа броячи в своя обект state. Всяка заявка обаче има собствен статус:

Статус на заявкатаЗначениеДействие
pendingНа опашкаИзчакайте
succeededОбработена, резултатът е наличенИзвлечете резултата
failedГрешка по време на обработкатаПрочетете съобщението, повторете опита, ако е полезно
cancelledАнулирана, например заедно с пакета ѝПодайте отново, ако е необходимо

Пакетът е напълно обработен, когато броячът му num_pending спадне до нула. Той може също да бъде анулиран или да изтече: след expire_time резултатите от него вече не са достъпни.

Проверка на броячите

Извикването GET /v1/batches/{batch_id} връща пакета и неговите броячи:

curl "https://api.x.ai/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $XAI_API_KEY"

Отговорът включва:

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "analyse_avis_clients",
  "state": {
    "num_requests": 500,
    "num_pending": 155,
    "num_success": 342,
    "num_error": 3,
    "num_cancelled": 0
  }
}

Тези броячи проследяват напредъка в реално време, без да се чака приключването на обработката. Чрез SDK ги четете в client.batch.get(batch_id=...).state.

Списък с вашите пакети

За да откриете пакет или да проверите историята:

curl "https://api.x.ai/v1/batches?limit=20" \
  -H "Authorization: Bearer $XAI_API_KEY"

Списъкът се страницира чрез limit и pagination_token. Пакетите остават там до изтичане на срока им. С помощта на SDK, client.batch.list(limit=20) връща списък batches, където всеки елемент носи своите name, batch_id и state. Конзолата на xAI предлага същия изглед във визуална форма.

Извличане на резултати

Можете да извлечете резултати по всяко време, дори по време на обработката:

curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Всеки резултат носи batch_request_id на съответната заявка. Неуспешните заявки се появяват там със своето съобщение; при използване на SDK, свойствата succeeded и failed на всяка страница ги разделят.

Проверка на метаданните на заявката

За да проследите статуса на всяка заявка:

curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
  -H "Authorization: Bearer $XAI_API_KEY"

Всеки запис предоставя идентификатора на заявката, нейната крайна точка, модел, статус, както и датите на създаване и приключване. Това е диагностичният инструмент, когато даден брояч заседне, или за да проверите какво е било успешно добавено.

Анулиране на пакет

Ако трябва да спрете обработката в ход:

curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
  -H "Authorization: Bearer $XAI_API_KEY"

Анулирането е окончателно: чакащите заявки няма да бъдат обработени и вече не можете да добавяте заявки към пакета. Заявките, които вече са обработени, обаче, остават налични в резултатите. Анулирайте, ако:

  • Сте открили грешка във вашите заявки след подаването им
  • Пакетът вече не е необходим (промяна в приоритетите)
  • Искате да подадете отново коригиран пакет

С помощта на SDK: client.batch.cancel(batch_id=...), което връща пакета и неговите броячи към момента на анулирането.

Стратегия за периодично запитване (Polling)

В производствена среда изчакайте приключването чрез периодични запитвания с интервали и максимално забавяне:

import time


def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
    """Wait until all requests in the batch are processed."""
    debut = time.monotonic()
    while time.monotonic() - debut < delai_max:
        batch = client.batch.get(batch_id=batch_id)
        etat = batch.state
        if batch.cancel_by_xai_message:
            raise RuntimeError(f"Canceled by xAI: {batch.cancel_by_xai_message}")
        if etat.num_requests > 0 and etat.num_pending == 0:
            return batch
        print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
              f"{etat.num_pending} pending out of {etat.num_requests}")
        time.sleep(intervalle)
    raise TimeoutError(f"Batch not finished after {delai_max} s")

Интервал от няколко минути е подходящ за големи пакети; документацията на xAI прави запитвания на всеки няколко секунди в своите примери, които обхващат малки пакети. И тъй като резултатите са налични веднага щом пристигнат, нищо не пречи да ги извлечете по време на изчакването.

Ключови изводи

  • Четете пакета чрез неговите броячи (num_pending, num_success, num_error…); всяка заявка има свой статус: pending, succeeded, failed, cancelled
  • GET /v1/batches/{id} дава напредъка, /results – резултатите, /requests – детайлите за заявката
  • Анулирането (POST /v1/batches/{id}:cancel) е необратимо, но запазва вече произведените резултати
  • Списъците и резултатите се страницират с limit и pagination_token
  • Правете запитвания на интервали от няколко минути, с максимално забавяне, и извлечете данните преди expire_time