Przejdź do głównej treści
Polski— Wybierz język
Menu

Limity przepustowości i najlepsze praktyki

Lekcja 12 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Ograniczenia, które musisz znać
  2. Limity przepustowości
  3. Ograniczenia plików JSONL
  4. Wygaśnięcie adresów URL
  5. Najlepsze praktyki produkcyjne
  6. Lista kontrolna przed wdrożeniem
  7. Kluczowe wnioski
  8. Sprawdź swoją wiedzę

Zaktualizowano 2 listopada 2026 r. Na podstawie dokumentacji xAI: rabat na przetwarzanie wsadowe wynosi 20% dla kwalifikujących się modeli tekstowych, przykłady opierają się na interfejsie REST API oraz oficjalnym xai-sdk (client.batch.*; Batch API od xAI nie używa formatu OpenAI, więc SDK OpenAI nie ma zastosowania), a Responses API ma pierwszeństwo przed Chat Completions, które są przestarzałym punktem końcowym w xAI. Źródła: Batch API · Referencje REST · Cennik Batch API.

Ograniczenia, które musisz znać

Batch API nakłada ograniczenia techniczne, które musisz uwzględnić w swojej architekturze. Ich ignorowanie prowadzi do odrzucenia żądań, anulowania zadań wsadowych lub utraty wyników. Ta lekcja podsumowuje ograniczenia udokumentowane przez xAI oraz najlepsze praktyki stosowane w środowisku produkcyjnym.

Limity przepustowości

OgraniczenieWartośćZakres
Tworzenie zadań wsadowych2 na sekundęNa zespół
Liczba zadań wsadowychNielimitowanaNa zespół
Wywołania dodawania żądań1000 na 30 sekundOkno przesuwne, współdzielone przez wszystkie zadania zespołu
Rozmiar żądania25 MBNa pojedyncze żądanie
Żądań na zadanie wsadoweTeoretycznie nielimitowanePowyżej 100 000 przetwarzanie może być wolniejsze

Tworzenie zadań wsadowych: limit 2 utworzeń na sekundę rzadko stanowi problem, ponieważ zazwyczaj tworzysz jedno zadanie wsadowe na operację.

Dodawanie żądań: limit dotyczy wywołań, a każde wywołanie przenosi listę żądań. Przy partiach po 100 żądań pozwala to już na przesłanie ponad 3000 żądań na sekundę.

Rozmiar żądania: limit 25 MB dotyczy głównie żądań obciążonych obrazami zakodowanymi w formacie base64; żądanie tekstowe rzadko przekracza kilka kilobajtów.

Co więcej, żądania wsadowe nie są wliczane do limitów przepustowości interfejsu API czasu rzeczywistego: duże zadanie wsadowe nie spowalnia Twojej interaktywnej aplikacji.

Ograniczenia plików JSONL

OgraniczenieWartość
Żądań na plikMaksymalnie 50 000
Rozmiar plikuMaksymalnie 200 MB
Dodawanie po utworzeniuNiemożliwe: zadanie wsadowe jest zamknięte

Jeśli Twoje zadanie wsadowe przekracza te limity, podziel je na kilka plików i utwórz jedno zadanie wsadowe na plik; wyniki scalisz afterward.

Wygaśnięcie adresów URL

Podpisane adresy URL dla wyników zawierających obrazy i wideo wygasają po jednej godzinie. Jest to najważniejsze ograniczenie, którym musisz zarządzać w środowisku produkcyjnym: Twój proces pobierania musi natychmiast ściągnąć multimedia, bez ręcznej interwencji (funkcja telecharger_medias z lekcji 9). W przypadku zadań wsadowych monitoruj również pole expire_time, po którym żadne wyniki nie są dostępne.

Najlepsze praktyki produkcyjne

Deterministyczne identyfikatory

Wyprowadź identyfikatory swoich żądań (batch_request_id lub custom_id w JSONL) z danych wejściowych. Jeśli będziesz musiał ponownie przesłać zadanie wsadowe, te same dane wygenerują te same identyfikatory, co ułatwi deduplikację:

import hashlib


def identifiant_requete(document_id: str, operation: str) -> str:
    """Generuje deterministyczny identyfikator żądania."""
    brut = f"{document_id}:{operation}"
    return hashlib.sha256(brut.encode()).hexdigest()[:16]

Obsługa częściowych niepowodzeń

W pełni przetworzone zadanie wsadowe może nadal zawierać nieudane żądania. Zawsze sprawdzaj każdy wynik:

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)} nieudanych żądań do ponownego przesłania w nowym zadaniu wsadowym")

Śledzenie kosztów

Każde zadanie wsadowe przechowuje informacje o całkowitym koszcie w jednostkach ticks (dziesięciomiliardowych częściach dolara):

batch = client.batch.get(batch_id=batch_id)
print("Całkowity koszt: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))

Poprzez interfejs REST API koszt każdego żądania tekstowego pojawia się w jego wyniku, w polu usage.cost_in_usd_ticks.

Logi i możliwość śledzenia

Rejestruj każdą operację, aby móc diagnozować problemy:

import logging

logger = logging.getLogger("batch_api")

logger.info("Utworzono zadanie wsadowe: %s", batch_id)
logger.info("Przesłano plik: %s, %d żądań", file_id, len(documents))
logger.info("Wyniki: %d udanych, %d nieudanych", len(reussies), len(echouees))

Ponawianie z wycofaniem (backoff)

W przypadku błędów przejściowych (limit czasu, limit przepustowości, błąd serwera) ponów próbę z rosnącym opóźnieniem:

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"Ponawianie za {attente} s: {e}")
            time.sleep(attente)

Lista kontrolna przed wdrożeniem

Przed wdrożeniem potoku Batch API w środowisku produkcyjnym sprawdź:

  • Model obsługuje przetwarzanie wsadowe i znajduje się na liście modeli objętych rabatem, jeśli koszt ma znaczenie
  • Identyfikatory żądań są unikalne i deterministyczne
  • Plik JSONL jest zwalidowany przed przesłaniem (jeden nieprawidłowy wiersz anuluje całe zadanie wsadowe)
  • Pobieranie wyników multimodalnych jest zautomatyzowane i mieści się w jednej godzinie
  • Częściowe niepowodzenia są wykrywane i ponownie przesyłane w nowym zadaniu wsadowym
  • Wyniki są pobierane przed upływem expire_time
  • Logi obejmują każdy etap przepływu pracy
  • Klucz API jest odczytywany ze zmiennej środowiskowej, nigdy nie jest wpisany na sztywno w kodzie

Kluczowe wnioski

  • Limity: 2 utworzenia na sekundę, 1000 wywołań dodawania żądań na 30 sekund, 25 MB na żądanie
  • Pliki JSONL: maksymalnie 50 000 żądań i 200 MB, jedno zadanie wsadowe na plik
  • Adresy URL obrazów i wideo wygasają po jednej godzinie: pobierz je natychmiast
  • Deterministyczne identyfikatory, sprawdzanie każdego wyniku, śledzenie kosztów w jednostkach ticks
  • Logowanie, ponawianie z wycofaniem (backoff) i maksymalny limit czasu dla środowiska produkcyjnego

Sprawdź swoją wiedzę

Przetwarzanie wsadowe: Batch API bez żadnych niedomówień.

1. Kiedy Batch API jest właściwym wyborem?

Odpowiedź: Przy dużych wolumenach danych, gdy nie ma wymogu czasu rzeczywistego: klasyfikacja, wzbogacanie danych, ewaluacje, generowanie masowe. Żądania wsadowe nie są wliczane do limitów przepustowości, a kwalifikujące się modele tekstowe otrzymują 20% rabatu.

2. Jaki jest czterostopniowy przepływ pracy?

Odpowiedź: Utwórz nazwane zadanie wsadowe, dodaj do niego żądania (poprzez API lub tworząc zadanie z przesłanego pliku JSONL), śledź jego liczniki, a następnie pobierz wyniki – w miarę ich pojawiania się lub na końcu. Przetwarzanie uruchamia się samoistnie, bez dodatkowego kroku startowego.

3. Co możesz umieścić w zadaniu wsadowym?

Odpowiedź: Żądania Responses (zalecane) oraz Chat Completions (przestarzałe), z narzędziami serwerowymi i wywoływaniem funkcji, a także generowanie i edycję obrazów oraz wideo, jak również rozszerzenia wideo. Rabat obejmuje tylko tokeny tekstowe dla kwalifikujących się modeli.

4. Jak śledzić wykonanie?

Odpowiedź: Poprzez liczniki zadania wsadowego (num_pending, num_success, num_error…), status każdego żądania (pending, succeeded, failed, cancelled) oraz paginowane wyniki, które oddzielają sukcesy od niepowodzeń. Zadanie wsadowe jest w pełni przetworzone, gdy num_pending wynosi zero.

5. Jakie najlepsze praktyki stosować wobec limitów?

Odpowiedź: Dodawaj żądania w partiach, dziel duże pliki na osobne zadania wsadowe (jeden plik na zadanie), pobieraj multimedia w ciągu jednej godziny, odbieraj wyniki przed upływem expire_time i ponownie przesyłaj nieudane żądania w nowym zadaniu wsadowym: projektuj zadanie wsadowe jako solidny potok, a nie jako ślepe przesyłanie masowe.

Prawidłowo sformułowane zadania wsadowe, monitorowane liczniki i ponawiane niepowodzenia: Batch API zamienia duże wolumeny w rutynę, przy optymalnym koszcie.