Limity przepustowości i najlepsze praktyki
Na tej stronie
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
| Ograniczenie | Wartość | Zakres |
|---|---|---|
| Tworzenie zadań wsadowych | 2 na sekundę | Na zespół |
| Liczba zadań wsadowych | Nielimitowana | Na zespół |
| Wywołania dodawania żądań | 1000 na 30 sekund | Okno przesuwne, współdzielone przez wszystkie zadania zespołu |
| Rozmiar żądania | 25 MB | Na pojedyncze żądanie |
| Żądań na zadanie wsadowe | Teoretycznie nielimitowane | Powyż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
| Ograniczenie | Wartość |
|---|---|
| Żądań na plik | Maksymalnie 50 000 |
| Rozmiar pliku | Maksymalnie 200 MB |
| Dodawanie po utworzeniu | Niemoż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.