Requêtes par lots en Python pour une API LLM compatible OpenAI
Pour les travaux par lots en Python avec l'API LLM, vous n'avez pas besoin d'un endpoint de lot spécial : vous avez besoin d'un pool de travailleurs qui respecte les limites de débit, d'une règle de nouvelle tentative pour les erreurs HTTP 429, et d'un fichier de résultats à partir duquel vous pouvez reprendre. Ce guide construit ces trois éléments avec le SDK OpenAI pointé vers votre URL de base.

Points clés
- L'API dispose de deux méthodes, chat completions et models, donc le regroupement par lots est effectué de votre côté avec un pool de requêtes simultanées.
- Une clé complète permet 8 requêtes concurrentes et 300 par minute ; une clé d'essai en permet 2 et 60. Dimensionnez votre pool en conséquence.
- Réessayez en cas d'erreur 429 en utilisant l'en-tête Retry-After, et distinguez la limite de débit dépassée de la concurrence.
- Écrivez chaque résultat dans un fichier JSONL à mesure qu'il se termine afin qu'une panne ne coûte que quelques minutes, et non toute l'exécution.
Comment fonctionne le batching ici
L'endpoint est compatible OpenAI et expose POST /v1/chat/completions et GET /v1/models. Il n'y a pas d'endpoint de soumission de job séparé qui prend un fichier et retourne plus tard. Un batch est donc une boucle sur des requêtes normales, exécutées simultanément, avec les limites intégrées dans votre code. C'est plus simple que cela n'y paraît, et cela vous donne les résultats à mesure qu'ils se terminent plutôt qu'à la fin.
Les nombres qui façonnent la conception sont les limites. Une clé complète permet 8 requêtes concurrentes et 300 requêtes par minute. Une clé d'essai permet 2 concurrentes et 60 par minute. Le corps de requête maximum est de 8 Mo. Une requête en streaming occupe sa place de concurrence jusqu'à la fin du flux, donc pour les travaux par lots, désactivez le streaming.
Pourquoi ne pas tout envoyer d'un coup ? Parce qu'un lot est un problème de débit avec un plafond, et ce plafond est le vôtre à respecter. Une boucle qui envoie 5 000 requêtes aussi vite que Python peut les créer reçoit un mur de réponses 429, perd du temps sur les nouvelles tentatives et enfouit les erreurs utiles dans le bruit. Un pool qui maintient au plus 8 requêtes en cours fait avancer la ligne à la vitesse autorisée par le service, et c'est le même code que vous ayez 50 lignes ou 500 000. Prévoyez trois éléments : un pool borné, une règle de nouvelle tentative et un fichier de résultats en append-only.
L'ID du modèle est uncensored, l'authentification est Authorization: Bearer <key>, et la base URL est https://api.unfilteredvideo.com/v1. Si vous n'avez pas encore de clé, la page clé API propose un essai de 0,50 $ en un clic.
Installation et configuration
Vous avez besoin de Python 3.9 ou plus récent et du package officiel openai. Placez la clé dans une variable d'environnement plutôt que dans le script.
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"
La liste des modèles devrait afficher uncensored. Préparez maintenant votre entrée sous forme de fichier JSONL, un objet par ligne avec un id et le texte à traiter. L'id est ce qui vous permet de reprendre plus tard.
{"id": "r001", "text": "Summarise this product review in one sentence: ..."}
{"id": "r002", "text": "Summarise this product review in one sentence: ..."}
Un pool de threads qui respecte les limites
Pour la plupart des scripts, un ThreadPoolExecutor est le chemin le plus court. Le client OpenAI est sûr à partager entre les threads, et le travail est lié au réseau, donc les threads conviennent. Définissez la taille du pool à votre limite de concurrence, pas plus : des workers supplémentaires ne font que collecter des erreurs 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()
Cette version ne dispose ni de nouvelle tentative ni de reprise, c'est donc un point de départ. Le client est créé avec max_retries=0 car le SDK effectue des nouvelles tentatives de lui-même par défaut, et vous souhaitez qu'un seul endroit soit responsable de la règle de nouvelle tentative. Les deux sections suivantes ajoutent cette règle et la logique de reprise.
Gérer le 429 correctement
Il existe trois types de 429 sur cette API, et ils appellent des réactions légèrement différentes :
rate_limited: vous avez envoyé trop de requêtes en une minute. Ralentissez. Un pool avec moins de workers, ou une courte pause, corrige le problème.concurrency: trop de requêtes étaient en vol à la fois. Votre pool est plus grand que votre limite, ou vous avez des flux ouverts que vous avez oubliés.- Surcharge temporaire : un 429 avec un en-tête
Retry-After: 5. Rien ne va mal dans votre code. Attendez le temps indiqué et réessayez.
Un seul utilitaire de nouvelle tentative couvre les trois cas. Il attend Retry-After lorsqu'il est présent, puis recule de manière exponentielle avec un peu de jitter. Les requêtes échouées et refusées ne sont pas facturées, donc réessayer est gratuit.
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)
Ne réessayez pas aveuglément à chaque erreur. Un 400 signifie que votre requête est incorrecte, par exemple un corps de plus de 8 Mo ou un message mal formé, et l'envoyer à nouveau échouera de la même manière. Journalisez-le avec l'identifiant de ligne et passez à la suite.
Une version asynchrone avec un sémaphore
Si votre script s'exécute déjà dans une boucle d'événements, ou si vous voulez alimenter un service web, utilisez AsyncOpenAI et un asyncio.Semaphore qui limite les requêtes en vol. Le sémaphore joue le rôle de la taille du pool.
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())
Enveloppez l'appel dans la même logique de retry que ci-dessus, en utilisant await asyncio.sleep au lieu de time.sleep. Une mise en garde : gather avec des dizaines de milliers de coroutines les crée toutes à la fois. Pour les entrées très volumineuses, traitez le fichier par tranches de quelques milliers de lignes.
Rendre l'exécution repriseable
Les jobs longs échouent de manière ennuyeuse : un ordinateur portable se met en veille, une connexion tombe, vous appuyez sur Ctrl+C. Parce que chaque ligne terminée est appendée à output.jsonl avec son id, reprendre signifie sauter les ids que vous avez déjà.
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")
Alimentez todo à l'un ou l'autre pool. Ouvrez le fichier de sortie en mode append, jamais en mode write, ou un redémarrage effacera vos progrès. Écrivez aussi les erreurs dans un deuxième fichier, errors.jsonl, afin de ne relancer que les échecs après avoir lu pourquoi ils ont échoué.
Pour une sortie reproductible sur les reruns, passez un seed fixe avec un temperature faible. Le seed est passé au modèle avec top_p, stop et les pénalités.
Tester sur un petit échantillon d'abord
Exécutez 20 lignes avant d'exécuter 20 000. Choisissez des lignes qui incluent vos pires cas : l'entrée la plus longue, une avec des caractères étranges, une qui est vide. Lisez les sorties à l'œil, vérifiez que usage correspond à votre estimation de coût, et confirmez que le helper de retry se comporte correctement en augmentant temporairement le nombre de workers au-dessus de votre limite. Vous devriez voir un 429 avec le code concurrency dans le log, une attente, et un retry réussi. Il vaut mieux voir cela sur 20 lignes que le découvrir à la ligne 9 000.
Si le job nécessite une sortie structurée, ajoutez le mode JSON avec response_format={"type": "json_object"}, décrivez les clés dans le prompt, et analysez chaque réponse dans un bloc try. Comptez les échecs d'analyse pendant la tranche de test. Un taux supérieur à un ou deux pourcents signifie généralement que le prompt a besoin d'un schéma plus clair, et cela est moins cher à corriger maintenant que de relancer plus tard. Les lignes qui échouent à l'analyse vont dans errors.jsonl avec leur id, et la logique de reprise les traite comme non terminées.
Enfin, définissez un délai d'attente client adapté à votre sortie la plus longue attendue. Le SDK accepte timeout=60 sur le client ou par requête ; une requête bloquée qui ne se termine jamais conservera l'une de vos 8 places aussi longtemps qu'elle sera là.
Dimensionner le pool et estimer le temps
Le débit est borné par deux choses : la concurrence divisée par le temps qu'une requête prend, et le plafond de requêtes par minute. Avec une clé complète, le plafond est de 300 par minute, soit 5 par seconde. Si une requête typique prend 2 secondes, 8 travailleurs produisent 8 / 2 = 4 requêtes par seconde, soit 240 par minute, ce qui est sous le plafond. Si les requêtes prennent 1 seconde, 8 travailleurs essaieraient 8 par seconde et atteindraient le plafond, alors ajoutez un petit délai ou acceptez les 429 occasionnels que votre utilitaire de nouvelle tentative absorbe.
À 4 par seconde, 10 000 lignes prennent 2 500 secondes, soit environ 42 minutes. Sur une clé d'essai, avec 2 requêtes concurrentes et 60 par minute, le plafond est de 1 par seconde, donc les mêmes 10 000 lignes prendraient 10 000 secondes, près de 2 heures 47 minutes. En pratique, le crédit d'essai de 0,50 $ s'épuisera avant cela, ce qui en fait un bon endroit pour tester le script sur quelques centaines de lignes et non un endroit pour exécuter en production.
Le coût d'un grand lot
La tarification est de 0,15 $ par 1M de tokens d'entrée et de 0,50 $ par 1M de tokens de sortie. Prenons un travail de type classification : 50 000 lignes, chacune d'environ 200 tokens d'entrée et 100 tokens de sortie.
- Entrée : 50 000 × 200 = 10 000 000 tokens, ce qui est 10 × 0,15 $ = 1,50 $.
- Sortie : 50 000 × 100 = 5 000 000 tokens, ce qui est 5 × 0,50 $ = 2,50 $.
- Total : 4,00 $, soit 0,00008 $ par ligne.
Le script ci-dessus enregistre in et out pour chaque ligne, donc vous pouvez calculer la même figure à partir de votre exécution réelle. L'en-tête de réponse X-Balance-USD montre aussi le crédit restant, et X-Request-Id est ce à citer si vous demandez de l'aide sur les docs ou les pages de support.
Le crédit est prépayé sous forme de recharges en dollars entiers de 20 $ à 500 $, avec +5 % à partir de 50 $, +10 % à partir de 100 $ et +15 % à partir de 200 $, payés en crypto (USDT sur TRC20 ou USDC sur Base). Il n'expire jamais. La page tarifs contient tous les détails. Une note pour les jeux de données sensibles : les prompts ne sont pas utilisés pour l'entraînement.
Plus de guides
Questions et réponses
L'API a-t-elle un endpoint de lot ?
Non. Il expose les chat completions et une liste de modèles. Vous regroupez en exécutant de nombreuses requêtes normales simultanément depuis votre propre code, dans la limite de 8 requêtes simultanées et de 300 par minute avec une clé complète.
Combien de threads dois-je utiliser ?
Utilisez 8 travailleurs avec une clé complète et 2 avec une clé d'essai, en respectant les limites de concurrence. Plus de travailleurs ne génèrent que des erreurs 429 avec le code concurrency.
Que faire lorsque vous recevez une erreur HTTP 429 ?
Attendez la valeur Retry-After si la réponse en contient une, sinon reculez de quelques secondes, puis réessayez. Les requêtes échouées ne sont pas facturées, donc réessayer ne coûte rien.
Puis-je diffuser les réponses dans un travail par lots ?
Vous le pouvez, mais vous ne devriez pas. Une requête en flux conserve sa place de concurrence jusqu'à la fin du flux, ce qui réduit le débit. Désactivez le flux pour les travaux par lots.
Votre clé est à un formulaire de vous
Créez un compte, copiez la clé, modifiez l'URL de base. C'est toute la configuration.