Peticiones por lotes en Python para una API de LLM compatible con OpenAI
Para el trabajo de lotes de API de LLM en Python, no necesitas un endpoint especial: necesitas un grupo de trabajadores que respete los límites de peticiones, una regla de reintento para el 429 HTTP y un archivo de resultados desde el que puedas reanudar. Esta guía construye los tres con el SDK de OpenAI apuntando a tu URL base.

Puntos clave
- La API tiene dos métodos, completions de chat y modelos, por lo que el procesamiento por lotes se realiza en tu lado con un grupo de peticiones simultáneas.
- Una clave completa permite 8 peticiones concurrentes y 300 por minuto; una clave de prueba permite 2 y 60. Ajusta el tamaño de tu grupo para que coincida.
- Reintenta en 429 usando el encabezado Retry-After, y distingue entre limitado por tasa y concurrencia.
- Escribe cada resultado en un archivo JSONL a medida que termina para que un fallo cueste minutos, no toda la ejecución.
Cómo funciona el procesamiento por lotes aquí
El endpoint es compatible con OpenAI y expone POST /v1/chat/completions y GET /v1/models. No hay un endpoint separado para enviar trabajos que tome un archivo y devuelva resultados más tarde. Por tanto, un lote es un bucle sobre peticiones normales, ejecutadas de forma simultánea, con los límites integrados en tu código. Es más sencillo de lo que parece y te da los resultados a medida que terminan en lugar de al final.
Los números que moldean el diseño son los límites. Una clave completa permite 8 peticiones concurrentes y 300 peticiones por minuto. Una clave de prueba permite 2 concurrentes y 60 por minuto. El cuerpo máximo de la petición es de 8 MB. Una petición en streaming mantiene su slot de concurrencia hasta que termina el streaming, por lo que para el trabajo por lotes, desactiva el streaming.
¿Por qué no enviar todo de una vez? Porque un lote es un problema de rendimiento con un techo, y ese techo es tuyo para respetar. Un bucle que envía 5.000 peticiones tan rápido como Python pueda crearlas recibe una pared de respuestas 429, pierde tiempo en reintentos y entierra los errores útiles en el ruido. Un grupo que mantiene como máximo 8 peticiones en vuelo mantiene la línea en movimiento a la velocidad que permite el servicio, y es el mismo código si tienes 50 filas o 500.000. Planifica tres piezas: un grupo acotado, una regla de reintento y un archivo de resultados de solo adición.
El ID del modelo es uncensored, la autenticación es Authorization: Bearer <key> y la URL base es https://api.unfilteredvideo.com/v1. Si aún no tienes clave, la página de clave de API ofrece una prueba de $0.50 con un clic.
Instalación y configuración
Necesitas Python 3.9 o superior y el paquete oficial openai. Pon la clave en una variable de entorno en lugar de en el 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 lista de modelos debería mostrar uncensored. Ahora prepara tu entrada como un archivo JSONL, un objeto por línea con un id y el texto a procesar. El id es lo que te permite reanudar más tarde.
{"id": "r001", "text": "Summarise this product review in one sentence: ..."}
{"id": "r002", "text": "Summarise this product review in one sentence: ..."}
Un grupo de hilos que se mantiene dentro de los límites
Para la mayoría de los scripts, un ThreadPoolExecutor es el camino más corto. El cliente de OpenAI es seguro para compartir entre hilos, y el trabajo está limitado por la red, por lo que los hilos encajan. Establece el tamaño del grupo a tu límite de concurrencia, no más alto: trabajadores extra solo recopilan errores 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()
Esta versión no tiene reintento ni reanudación, por lo que es un punto de partida. El cliente se crea con max_retries=0 en el cliente porque el SDK reintenta por sí mismo por defecto, y quieres un lugar que controle la regla de reintento. Las dos secciones siguientes añaden esa regla y la lógica de reanudación.
Manejar el 429 de la forma correcta
Hay tres tipos de 429 en esta API, y requieren reacciones ligeramente diferentes:
rate_limited: enviaste demasiadas peticiones en un minuto. Ralentiza. Un grupo con menos trabajadores, o una breve pausa, lo soluciona.concurrency: había demasiadas peticiones en vuelo a la vez. Tu grupo es más grande que tu límite, o tienes flujos abiertos que olvidaste.- Sobrecarga temporal: un 429 con un encabezado
Retry-After: 5. No hay nada malo con tu código. Espera el tiempo indicado e inténtalo de nuevo.
Un único ayudante de reintento cubre los tres. Espera a Retry-After cuando esté presente y de lo contrario retrocede exponencialmente con un poco de jitter. Las peticiones fallidas y rechazadas no se cobran, por lo que reintentar es gratis.
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)
No reintentes ciegamente en cada error. Un 400 significa que tu petición es incorrecta, por ejemplo un cuerpo superior a 8 MB o un mensaje mal formado, y enviarlo de nuevo fallará de la misma manera. Regístralo con el id de la fila y continúa.
Una versión asíncrona con un semáforo
Si tu script ya se ejecuta en un bucle de eventos, o quieres alimentar un servicio web, usa AsyncOpenAI y un asyncio.Semaphore que limite las peticiones en vuelo. El semáforo cumple el papel del tamaño del grupo.
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())
Envuelve la llamada en la misma lógica de reintento que arriba, usando await asyncio.sleep en lugar de time.sleep. Una precaución: gather con decenas de miles de corutinas las crea todas a la vez. Para entradas muy grandes, procesa el archivo en fragmentos de unas pocas miles de filas.
Hacer la ejecución reanudable
Los trabajos largos fallan de formas aburridas: un portátil entra en suspensión, una conexión se cae, pulsas Ctrl+C. Como cada fila terminada se añade a output.jsonl con su id, reanudar significa saltarse los ids que ya tienes.
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")
Alimenta all a cualquiera de los dos grupos anteriores. Abre el archivo de salida en modo append, nunca en modo write, o un reinicio borrará tu progreso. También escribe los errores en un segundo archivo, errors.jsonl, para que puedas volver a ejecutar solo los fallos después de leer por qué fallaron.
Para una salida repetible entre reejecuciones, pasa un seed fijo junto con un temperature bajo. El seed se pasa al modelo junto con top_p, stop y las penalizaciones.
Probar primero con una pequeña muestra
Ejecuta 20 filas antes de ejecutar 20.000 filas. Elige filas que incluyan tus peores casos: la entrada más larga, una con caracteres extraños, una que esté vacía. Lee las salidas a ojo, comprueba que usage coincide con tu estimación de coste y confirma que el ayudante de reintento se comporta elevando temporalmente el recuento de trabajadores por encima de tu límite. Deberías ver un 429 con el código concurrency en el registro, una espera y un reintento exitoso. Es mejor ver eso en 20 filas que descubrirlo en la fila 9.000.
Si el trabajo necesita una salida estructurada, añade el modo JSON con response_format={"type": "json_object"}, describe las claves en el prompt y analiza cada respuesta dentro de un bloque try. Cuenta los fallos de análisis durante la muestra de prueba. Una tasa superior a un par de porcientos suele significar que el prompt necesita un esquema más claro, y eso es más barato de arreglar ahora que volver a ejecutar más tarde. Las filas que fallan al analizarse van a errors.jsonl con su id, y la lógica de reanudación las trata como no hechas.
Por último, configura un tiempo de espera del cliente que se ajuste a la salida más larga que se espera. El SDK acepta timeout=60 en el cliente o por petición; una petición atascada que nunca devuelve ocupará una de tus 8 plazas de concurrencia durante todo el tiempo que permanezca ahí.
Dimensionar el grupo y estimar el tiempo
El rendimiento está limitado por dos cosas: la concurrencia dividida por el tiempo que tarda una petición, y el límite de peticiones por minuto. Con una clave completa, el límite es de 300 por minuto, lo que equivale a 5 por segundo. Si una petición típica tarda 2 segundos, 8 trabajadores producen 8 / 2 = 4 peticiones por segundo, o 240 por minuto, lo cual está bajo el límite. Si las peticiones tardan 1 segundo, 8 trabajadores intentarían 8 por segundo y alcanzarían el límite, así que añade un pequeño retraso o acepta 429 ocasionales que tu ayudante de reintento absorberá.
A 4 por segundo, 10.000 filas tardan 2.500 segundos, unos 42 minutos. Con una clave de prueba, con 2 peticiones simultáneas y 60 por minuto, el techo es de 1 por segundo, por lo que las mismas 10.000 filas tardarían 10.000 segundos, casi 2 horas 47 minutos. En la práctica, el crédito de prueba de $0,50 se agotará antes, lo que lo convierte en un buen entorno para probar el script en unas pocas cientos de filas y no un entorno para ejecutar en producción.
Qué cuesta un lote grande
La tarifa es de $0,15 por 1M de tokens de entrada y $0,50 por 1M de tokens de salida. Toma un trabajo de tipo clasificación: 50.000 filas, cada una con unos 200 tokens de entrada y 100 tokens de salida.
- Entrada: 50.000 × 200 = 10.000.000 tokens, que son 10 × $0,15 = $1,50.
- Salida: 50.000 × 100 = 5.000.000 tokens, que son 5 × $0,50 = $2,50.
- Total: $4,00, o $0,00008 por fila.
El script anterior registra in y out para cada fila, por lo que puedes calcular la misma cifra a partir de tu ejecución real. El encabezado de respuesta X-Balance-USD también muestra el crédito restante, y X-Request-Id es lo que debes citar si pides ayuda en las páginas de documentación o soporte.
El crédito es prepago en recargas en dólares enteros de $20 a $500, con +5% desde $50, +10% desde $100 y +15% desde $200, pagado en cripto (USDT en TRC20 o USDC en Base). No caduca. La página de precios tiene todos los detalles. Una nota para conjuntos de datos sensibles: los prompts no se usan para entrenamiento.
Más guías
Preguntas y respuestas
¿La API tiene un endpoint por lotes?
No. Expone chat completions y una lista de modelos. Agrupas peticiones ejecutando muchas peticiones normales de forma simultánea desde tu propio código, con un límite de 8 concurrentes y 300 por minuto con una clave completa.
¿Cuántos hilos debo usar?
Usa 8 workers con una clave completa y 2 con una clave de prueba, ajustándote a los límites de concurrencia. Más workers solo producen errores 429 con el código concurrency.
¿Qué debo hacer cuando recibo un HTTP 429?
Espera el valor de Retry-After si la respuesta lo tiene, de lo contrario, retrocede unos segundos y reintenta. Las peticiones fallidas no se cobran, por lo que reintentar no cuesta nada.
¿Puedo hacer streaming de respuestas en un trabajo por lotes?
Puedes, pero no deberías. Una petición en streaming mantiene su plaza de concurrencia hasta que termina el streaming, lo que reduce el rendimiento. Deja el streaming desactivado para trabajos por lotes.
Tu clave está a un formulario de distancia
Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.