Zapytania wsadowe w Pythonie dla API LLM kompatybilnego z OpenAI
Do pracy wsadowej API LLM w Pythonie nie potrzebujesz specjalnego endpointu batch: potrzebujesz puli wątków respektującej limity zapytań, reguły ponawiania dla HTTP 429 i pliku wyników, od którego można wznowić działanie. Ten przewodnik tworzy wszystkie trzy elementy przy użyciu SDK OpenAI wskazującego na twój Base URL.

Kluczowe punkty
- API ma dwie metody: chat completions i models, więc batchowanie jest realizowane po stronie klienta za pomocą puli zapytań współbieżnych.
- Pełny klucz pozwala na 8 równoległych zapytań i 300 na minutę; klucz próbny pozwala na 2 i 60. Dopasuj rozmiar puli do tych limitów.
- Ponawiaj zapytanie przy błędzie 429, korzystając z nagłówka Retry-After, i rozróżniaj błędy limitu zapytań od limitu współbieżności.
- Zapisuj każdy wynik do pliku JSONL po jego zakończeniu, aby awaria kosztowała minuty, a nie całe uruchomienie.
Jak działa batch w tym miejscu
Endpoint jest kompatybilny z OpenAI i udostępnia POST /v1/chat/completions oraz GET /v1/models. Nie ma osobnego endpointu do zgłaszania zadań, który przyjmuje plik i zwraca wynik później. Batch jest więc pętlą po zwykłych zapytaniach, uruchamianych równolegle, z limitami wbudowanymi w Twój kod. Jest to prostsze, niż się wydaje, i daje Ci wyniki po ich zakończeniu, a nie na końcu.
Liczby kształtujące projekt to limity. Pełny klucz pozwala na 8 równoległych zapytań i 300 zapytań na minutę. Klucz próbny pozwala na 2 równoległe i 60 na minutę. Maksymalny rozmiar ciała zapytania to 8 MB. Strumieniowane zapytanie zajmuje slot concurrency do końca strumienia, więc dla pracy batch pozostaw strumieniowanie wyłączone.
Dlaczego nie wysłać wszystkiego naraz? Ponieważ batch to problem przepustowości z sufitem, a ten sufit musisz respektować. Pętla wysyłająca 5000 zapytań tak szybko, jak Python jest w stanie je tworzyć, otrzymuje ścianę odpowiedzi 429, marnuje czas na ponowne próby i ukrywa użyteczne błędy w szumie. Pula, która utrzymuje maksymalnie 8 zapytań w locie, utrzymuje ruch z prędkością pozwalaną przez usługę, a kod jest ten sam niezależnie od tego, czy masz 50 wierszy, czy 500 000. Zaplanuj trzy elementy: ograniczoną pulę, jedną regułę ponownych prób i plik wyników tylko do dopisywania.
ID modelu to uncensored, uwierzytelnianie to Authorization: Bearer <key>, a Base URL to https://api.unfilteredvideo.com/v1. Jeśli jeszcze nie masz klucza, na stronie klucza API znajduje się jednoklikowy kredyt próbny za $0.50.
Instalacja i konfiguracja
Potrzebujesz Pythona 3.9 lub nowszego oraz oficjalnego pakietu openai. Umieść klucz w zmiennej środowiskowej, a nie w skrypcie.
pip install openai
export API_KEY="paste-your-key-here"
# quick check that the key and base URL work
curl https://api.unfilteredvideo.com/v1/models -H "Authorization: Bearer $API_KEY"
Lista modeli powinna pokazywać uncensored. Teraz przygotuj dane wejściowe jako plik JSONL, jeden obiekt na linię z id i tekstem do przetworzenia. ID pozwala Ci na wznowienie później.
{"id": "r001", "text": "Summarise this product review in one sentence: ..."}
{"id": "r002", "text": "Summarise this product review in one sentence: ..."}
Pula wątków mieszcząca się w limitach
Dla większości skryptów ThreadPoolExecutor jest najkrótszą drogą. Klient OpenAI jest bezpieczny do udostępniania między wątkami, a praca jest związana z siecią, więc wątki pasują. Ustaw rozmiar puli na limit współbieżności, nie wyżej: dodatkowe workerzy tylko zbierają błędy 429.
import json, os
from concurrent.futures import ThreadPoolExecutor, as_completed
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
WORKERS = 8 # use 2 on a trial key
def run_one(row):
resp = client.chat.completions.create(
model=MODEL,
temperature=0.2,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
return {
"id": row["id"],
"output": resp.choices[0].message.content,
"in": resp.usage.prompt_tokens,
"out": resp.usage.completion_tokens,
}
rows = [json.loads(line) for line in open("input.jsonl")]
with ThreadPoolExecutor(max_workers=WORKERS) as pool, open("output.jsonl", "a") as out:
futures = [pool.submit(run_one, r) for r in rows]
for f in as_completed(futures):
out.write(json.dumps(f.result()) + "\n")
out.flush()
Ta wersja nie ma ponownych prób ani wznowienia, więc jest punktem wyjścia. Klient jest tworzony z max_retries=0 na kliencie, ponieważ SDK sam wykonuje ponowne próby domyślnie, a Ty chcesz mieć jedno miejsce, które zarządza regułą ponownych prób. Dwie następne sekcje dodają tę regułę i logikę wznowienia.
Obsługa 429 w odpowiedni sposób
Istnieją trzy rodzaje błędu 429 w tym API, które wymagają nieco innych reakcji:
rate_limited: wysłałeś zbyt wiele zapytań w minutę. Zwolnij. Pula z mniejszą liczbą workerów lub krótkie sleep to naprawia.concurrency: zbyt wiele żądań było w locie naraz. Twoja pula jest większa niż Twój limit albo masz otwarte strumienie, o których zapomniałeś.- Tymczasowe przeciążenie: 429 z nagłówkiem
Retry-After: 5. Z Twoim kodem nie ma nic złego. Poczekaj wskazany czas i spróbuj ponownie.
Jedna funkcja ponownych prób obejmuje wszystkie trzy przypadki. Czekaj na Retry-After, gdy jest obecny, w przeciwnym razie zastosuj backoff wykładniczy z niewielkim jitterem. Nieudane i odrzucone zapytania nie są rozliczane, więc ponowne próby są darmowe.
import random, time
import openai
from openai import OpenAI
client = OpenAI(api_key=__import__("os").environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
def call_with_retry(messages, attempts=6):
for n in range(attempts):
try:
return client.chat.completions.create(model=MODEL, messages=messages, max_tokens=200)
except openai.RateLimitError as e:
wait = e.response.headers.get("Retry-After")
delay = float(wait) if wait else min(60, 2 ** n) + random.random()
print("429", getattr(e, "code", None), "waiting", round(delay, 1), "s")
time.sleep(delay)
except (openai.APIConnectionError, openai.APITimeoutError):
time.sleep(min(30, 2 ** n))
raise RuntimeError("gave up after %d attempts" % attempts)
Nie powtarzaj próby ślepo przy każdym błędzie. 400 oznacza, że Twoje zapytanie jest błędne, na przykład ciało przekraczające 8 MB lub zły format wiadomości, i wysłanie go ponownie zakończy się tym samym błędem. Zaloguj go z id wiersza i przejdź dalej.
Wersja async z semaforem
Jeśli Twój skrypt już działa w pętli zdarzeń lub chcesz zasilić usługę webową, użyj AsyncOpenAI i asyncio.Semaphore, który ogranicza zapytania w locie. Semafor pełni rolę rozmiaru puli.
import asyncio, json, os
from openai import AsyncOpenAI
client = AsyncOpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
sem = asyncio.Semaphore(8)
async def run_one(row, out):
async with sem:
resp = await client.chat.completions.create(
model=MODEL,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
out.write(json.dumps({"id": row["id"], "output": resp.choices[0].message.content}) + "\n")
out.flush()
async def main():
rows = [json.loads(l) for l in open("input.jsonl")]
with open("output.jsonl", "a") as out:
await asyncio.gather(*(run_one(r, out) for r in rows))
asyncio.run(main())
Zawiń wywołanie w tę samą logikę retry co powyżej, używając await asyncio.sleep zamiast time.sleep. Uwaga: gather z dziesiątkami tysięcy korutyn tworzy je wszystkie naraz. Dla bardzo dużych danych przetwarzaj plik w wycinkach po kilka tysięcy wierszy.
Zapewnienie możliwości wznowienia uruchomienia
Długie zadania zawodzą w nudny sposób: laptop przechodzi w uśpienie, połączenie opada, wciskasz Ctrl+C. Ponieważ każdy ukończony wiersz jest dopisywany do output.jsonl z jego id, wznowienie oznacza pominięcie id, które już masz.
import json, os
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1")
MODEL = "uncensored"
def done_ids(path="output.jsonl"):
if not os.path.exists(path):
return set()
return {json.loads(line)["id"] for line in open(path) if line.strip()}
finished = done_ids()
todo = [r for r in map(json.loads, open("input.jsonl")) if r["id"] not in finished]
print(len(finished), "done,", len(todo), "to go")
Przekaż todo do dowolnej z powyższych pul. Otwórz plik wyjściowy w trybie append, nigdy w trybie write, inaczej restart wymaże Twój postęp. Zapisuj również błędy do drugiego pliku errors.jsonl, aby móc ponownie uruchomić tylko niepowodzenia po przeczytaniu przyczyny ich błędu.
Dla powtarzalnego wyniku przy ponownych uruchomieniach przekaż stały seed wraz z niskim temperature. Seed jest przekazywany do modelu wraz z top_p, stop i karami.
Test na małym fragmencie najpierw
Uruchom 20 wierszy, zanim uruchomisz 20 000. Wybierz wiersze, które obejmują Twoje najgorsze przypadki: najdłuższe wejście, jedno z dziwnymi znakami, jedno puste. Przeczytaj wyjścia okiem, sprawdź, czy usage pasuje do Twojej oceny kosztów, i potwierdź zachowanie pomocnika retry, tymczasowo zwiększając liczbę workerów powyżej limitu. Powinieneś zobaczyć 429 z kodem concurrency w logu, oczekiwanie i udaną próbę. Lepiej zobaczyć to na 20 wierszach niż odkryć to przy wierszu 9000.
Jeśli zadanie wymaga wyniku strukturalnego, dodaj tryb JSON z response_format={"type": "json_object"}, opisz klucze w promptcie i zparsuj każdą odpowiedź w bloku try. Policz niepowodzenia parsowania podczas testowego wycinka. Wysoki wynik powyżej procenta lub dwóch oznacza zwykle, że prompt wymaga wyraźniejszego schematu, a to tańsze do naprawienia teraz niż do ponownego uruchomienia później. Wiersze, które nie zostaną sparsowane, idą do errors.jsonl z ich id, a logika resume traktuje je jako nieukończone.
Na koniec ustaw timeout klienta dopasowany do Twojego najdłuższego oczekiwanego wyjścia. SDK akceptuje timeout=60 na kliencie lub na żądanie; utknęłe zapytanie, które nigdy nie zwróci wyniku, w przeciwnym razie zajmie jeden z Twoich 8 slotów tak długo, jak będzie tam siedzieć.
Dopasowanie puli i szacowanie czasu
Przepływność jest ograniczona przez dwie rzeczy: współbieżność podzieloną przez czas trwania jednego zapytania oraz limit zapytań na minutę. Dla pełnego klucza limit wynosi 300 na minutę, czyli 5 na sekundę. Jeśli typowe zapytanie trwa 2 sekundy, 8 wątków generuje 8 / 2 = 4 zapytania na sekundę, czyli 240 na minutę, co mieści się w limicie. Jeśli zapytania trwają 1 sekundę, 8 wątków spróbuje wysłać 8 na sekundę i uderzy w limit, więc dodaj małe opóźnienie lub zaakceptuj okresowe błędy 429, które pochłonie twój mechanizm ponawiania.
Przy 4 zapytaniach na sekundę 10 000 wierszy zajmie 2 500 sekund, czyli około 42 minut. Dla klucza próbnego, z 2 zapytaniami równoległymi i limitem 60 na minutę, maksymalna przepływność to 1 na sekundę, więc te same 10 000 wierszy zajęłoby 10 000 sekund, czyli prawie 2 godziny i 47 minut. W praktyce kredyt próbny za $0,50 wyczerpie się wcześniej, co sprawia, że jest to dobre miejsce do przetestowania skryptu na kilkuset wierszach, a nie do uruchamiania produkcji.
Koszt dużego batcha
Cennik to $0.15 za 1M tokenów wejściowych i $0.50 za 1M tokenów wyjściowych. Weź zadanie klasyfikacyjne: 50 000 wierszy, każdy o około 200 tokenach wejściowych i 100 tokenach wyjściowych.
- Wejście: 50 000 × 200 = 10 000 000 tokenów, co jest 10 × $0.15 = $1.50.
- Wyjście: 50 000 × 100 = 5 000 000 tokenów, co jest 5 × $0.50 = $2.50.
- Razem: $4.00, czyli $0.00008 na wiersz.
Powyższy skrypt zapisuje in i out dla każdego wiersza, więc możesz obliczyć tę samą wartość na podstawie swojego rzeczywistego uruchomienia. Nagłówek odpowiedzi X-Balance-USD pokazuje również pozostały kredyt, a X-Request-Id to wartość, którą należy podać, jeśli poprosisz o pomoc na stronach dokumentacji lub wsparcia.
Kredyt jest doładowywany w całości w dolarach w kwotach od $20 do $500, z bonusem +5% od $50, +10% od $100 i +15% od $200, płatny kryptowalutami (USDT w sieci TRC20 lub USDC na Base). Nigdy nie wygasa. Na stronie z cenami znajdziesz pełne szczegóły. Uwaga dla wrażliwych zbiorów danych: prompty nie są używane do trenowania modeli.
Więcej przewodników
Pytania i odpowiedzi
Czy API ma endpoint do batchowania?
Nie. Udostępnia chat completions i listę modeli. Batchujesz, uruchamiając wiele zwykłych zapytań równolegle we własnym kodzie, w limicie 8 równoległych i 300 na minutę dla pełnego klucza.
Ile wątków powinienem użyć?
Użyj 8 wątków dla pełnego klucza i 2 dla klucza próbnego, dostosowując się do limitów współbieżności. Więcej wątków powoduje tylko błędy 429 z kodem concurrency.
Co zrobić, gdy otrzymam HTTP 429?
Poczekaj na wartość Retry-After, jeśli odpowiedź ją zawiera, w przeciwnym razie odczekaj kilka sekund, a następnie ponów próbę. Nieudane zapytania nie są rozliczane, więc ponowne próby nic nie kosztują.
Czy mogę strumieniować odpowiedzi w zadaniu batch?
Możesz, ale nie powinieneś. Zapytanie strumieniowe trzyma swój slot współbieżności do końca strumienia, co zmniejsza przepływność. Wyłącz strumieniowanie dla pracy wsadowej.
Twój klucz jest o jeden formularz stąd
Utwórz konto, skopiuj klucz, zmień bazowy URL. To cała konfiguracja.