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

Ограничения на честотата на заявките и най-добри практики

Урок 12 от 12 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Ограничения, които трябва да знаете
  2. Ограничения на честотата на заявките (Rate limits)
  3. Ограничения за JSONL файлове
  4. Изтичане на срока на валидност на URL адресите
  5. Най-добри практики за продукционна среда
  6. Контролен списък преди внедряване
  7. Ключови изводи
  8. Проверете знанията си

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

Ограничения, които трябва да знаете

Batch API налага технически лимити, които трябва да отчетете във вашата архитектура. Пренебрегването им води до отхвърляне, анулиране на пакети или загуба на резултати. Този урок обобщава ограниченията, документирани от xAI, и най-добрите практики за продукционна употреба.

Ограничения на честотата на заявките (Rate limits)

ОграничениеСтойностОбхват
Създаване на пакет2 на секундаНа екип
Брой пакетиНеограниченНа екип
Извиквания за добавяне на заявки1 000 на 30 секундиПлъзгащ се прозорец, споделен за всички пакети на екипа
Размер на заявката25 MBНа индивидуална заявка
Заявки на пакетТеоретично неограничениНад 100 000 обработката може да бъде по-бавна

Създаване на пакет: лимитът от 2 създавания в секунда рядко представлява проблем, тъй като обикновено създавате един пакет на операция.

Добавяне на заявки: лимитът се отнася за извикванията, като всяко извикване носи списък със заявки. При групи от 100 заявки, това вече позволява повече от 3 000 заявки в секунда.

Размер на заявката: лимитът от 25 MB засяга основно заявките, натоварени с изображения в кодиране base64; една текстова заявка рядко надвишава няколко килобайта.

Обратно, пакетните заявки не се броят към ограниченията на честотата на реалновременното API: един голям пакет не забавя вашето интерактивно приложение.

Ограничения за JSONL файлове

ОграничениеСтойност
Заявки на файлМаксимум 50 000
Размер на файлаМаксимум 200 MB
Добавяния след създаванеНевъзможно: пакетът е запечатан

Ако вашият пакет надвишава тези лимити, разделете го на няколко файла и създайте един пакет на файл; след това ще агрегирате резултатите.

Изтичане на срока на валидност на URL адресите

Подписаните URL адреси за резултати от изображения и видео изтичат след един час. Това е най-критичното ограничение за обработка в продукционна среда: вашият процес на извличане трябва да изтегли медиите незабавно, без ръчна намеса (функцията telecharger_medias от урок 9). За пакета също така следете expire_time, след което няма достъп до резултати.

Най-добри практики за продукционна среда

Детерминирани идентификатори

Изведете вашите ID на заявки (batch_request_id или custom_id в JSONL) от вашите входни данни. Ако трябва да изпратите пакет отново, същите данни ще произведат същите ID, което улеснява дедупликацията:

import hashlib


def identifiant_requete(document_id: str, operation: str) -> str:
    """Генерира детерминиран ID на заявката."""
    brut = f"{document_id}:{operation}"
    return hashlib.sha256(brut.encode()).hexdigest()[:16]

Обработка на частични грешки

Един напълно обработен пакет все още може да съдържа неуспешни заявки. Винаги проверявайте всеки резултат:

reussies, echouees = [], []
jeton = None
while True:
    page = client.batch.list_batch_results(
        batch_id=batch_id, limit=1000, pagination_token=jeton
    )
    reussies.extend(page.succeeded)
    echouees.extend(page.failed)
    if page.pagination_token is None:
        break
    jeton = page.pagination_token

if echouees:
    print(f"{len(echouees)} failed requests to resubmit in a new batch")

Проследяване на разходите

Всеки пакет проследява общата си стойност в ticks (една десетмилиардна част от долара):

batch = client.batch.get(batch_id=batch_id)
print("Total cost: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))

Чрез REST API, цената на всяка текстова заявка се появява в нейния резултат, в полето usage.cost_in_usd_ticks.

Журнали и проследимост

Журналирайте всяка операция, за да можете да диагностицирате проблеми:

import logging

logger = logging.getLogger("batch_api")

logger.info("Batch created: %s", batch_id)
logger.info("File uploaded: %s, %d requests", file_id, len(documents))
logger.info("Results: %d succeeded, %d failed", len(reussies), len(echouees))

Повторни опити с експоненциално забавяне (Backoff)

За преходни грешки (изтичане на времето, лимит на честотата, грешка на сървъра) правете повторни опити с нарастващо забавяне:

import time


def appel_avec_retry(fonction, max_essais=3):
    for essai in range(max_essais):
        try:
            return fonction()
        except Exception as e:
            if essai == max_essais - 1:
                raise
            attente = 2 ** essai
            print(f"Retrying in {attente} s: {e}")
            time.sleep(attente)

Контролен списък преди внедряване

Преди да внедрите конвейер на Batch API в продукционна среда, проверете:

  • Моделът приема пакетна обработка и се появява в списъка с модели с отстъпка, ако цената има значение
  • ID на заявките са уникални и детерминирани
  • JSONL файлът е валидиран преди качване (един невалиден ред анулира целия пакет)
  • Изтеглянето на мултимодни резултати е автоматизирано и се извършва в рамките на един час
  • Частичните грешки се откриват и се изпращат отново в нов пакет
  • Резултатите се извличат преди expire_time
  • Журналите обхващат всяка стъпка от работния процес
  • API ключът се чете от променлива на средата, никога не е вграден в кода

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

  • Лимити: 2 създавания в секунда, 1 000 извиквания за добавяне на заявки на 30 секунди, 25 MB на заявка
  • JSONL файлове: максимум 50 000 заявки и 200 MB, един пакет на файл
  • URL адресите за изображения и видео изтичат за един час: изтеглете ги незабавно
  • Детерминирани ID, проверка на всеки резултат, проследяване на разходите в ticks
  • Журнали, повторни опити с експоненциално забавяне и максимален таймаут за продукционна среда

Проверете знанията си

Масова обработка: Batch API без сиви зони.

1. Кога Batch API е правилният избор?

Отговор: За големи обеми без изисквания за реално време: класификация, обогатяване, оценки, масово генериране. Пакетните заявки не се броят към ограниченията на честотата, а допустимите текстови модели получават отстъпка от 20%.

2. Какъв е работният процес от четири стъпки?

Отговор: Създаване на именуван пакет, добавяне на заявки към него (чрез API или чрез създаване на пакет от качен JSONL файл), проследяване на броячите му и след това извличане на резултатите, докато постъпват или в края. Обработката стартира сама, без стъпка за стартиране.

3. Какво можете да поставите в пакет?

Отговор: Заявки за Responses (препоръчително) и Chat Completions (остаряло), със сървърни инструменти и извикване на функции, както и генериране и редактиране на изображения и видеоклипове, и разширения за видео. Само текстовите токени за допустимите модели получават отстъпката.

4. Как проследявате изпълнението?

Отговор: Чрез броячите на пакета (num_pending, num_success, num_error…), статуса на всяка заявка (pending, succeeded, failed, cancelled) и страницираните резултати, които разделят успехите от грешките. Пакетът е напълно обработен, когато num_pending е нула.

5. Кои най-добри практики се прилагат за лимитите?

Отговор: Добавяне на заявки на групи, разделяне на големи файлове на един пакет на файл, изтегляне на медии в рамките на един час, извличане на резултати преди expire_time и повторно изпращане на грешките в нов пакет: проектирайта пакета като надежден конвейер, а не като сляпо масово подаване.

Добре оформени пакети, проследени броячи, повторени неуспешни опити: Batch API превръща обема в рутина, на най-добрата цена.