Los desarrolladores a menudo enfrentan tiempos de respuesta lentos y altos costos de red al enviar miles de llamadas API separadas. Batch API aborda esto combinando múltiples solicitudes independientes en una sola operación, reduciendo la latencia, el uso de ancho de banda y la sobrecarga de conexión.
Este artículo explica qué es Batch API, en qué se diferencia de las API estándar y cómo Novita AI’s Batch API permite la inferencia asíncrona a gran escala mediante entrada JSONL estructurada, manejo eficiente de archivos y seguimiento confiable de errores. También describe factores clave de eficiencia como costo, latencia y rendimiento, y proporciona una guía concisa para la implementación y monitoreo.
[Prueba la inferencia por lotes con un 50% de descuento
Ejecuta predicciones a gran escala más rápido y más barato con los modelos compatibles:
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-fp8.](https://novita.ai/docs/guides/llm-batch-api)
Prueba la inferencia por lotes con un 50% de descuento
Ejecuta predicciones a gran escala más rápido y más barato con los modelos compatibles:
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-f
¿Qué es Batch API？
Batch API: Combina múltiples llamadas API independientes (por ejemplo, GET, POST, PUT, DELETE) en una única solicitud HTTP.
Estructura de respuesta: El servidor devuelve los resultados de todas las sub-solicitudes en orden, indicando éxito o fallo para cada una.
Diferencia clave entre Batch API y API estándar
Solicitudes normales
Client
├──► Request 1 (/user/1)
│ └──► Server Response 1
├──► Request 2 (/user/2)
│ └──► Server Response 2
└──► Request 3 (/order)
└──► Server Response 3
Solicitud por lotes
Client
└──► Single Request (/batch)
├─ Sub-request 1: GET /user/1
├─ Sub-request 2: GET /user/2
└─ Sub-request 3: POST /order
↓
Server processes all
↓
Combined Response:
[Result1, Result2, Result3]
Batch API puede ayudar:
Reducir la latencia de red al enviar una solicitud combinada en lugar de muchas.
Reducir el ancho de banda y la sobrecarga de conexión, ya que los encabezados y los handshakes se comparten.
Mejorar el rendimiento del cliente, especialmente en redes móviles o lentas.
Simplificar la lógica transaccional, permitiendo manejo de errores unificado o reversión.
Optimizar el rendimiento de API Gateway, evitando la inundación de solicitudes.
Casos de uso típicos de Batch API
| Escenario | Descripción |
|---|---|
| 1. Consultas masivas de datos | Recuperar múltiples usuarios, productos o publicaciones de una vez para evitar solicitudes repetidas. |
| 2. Escritura o actualización masiva | Crear o actualizar múltiples registros en una operación (por ejemplo, carga por lotes, actualización de inventario). |
| 3. Optimización del rendimiento front-end | Reducir el número de llamadas HTTP desde navegadores o aplicaciones móviles para tiempos de carga más rápidos. |
| 4. Agregación de tareas backend | En sistemas de microservicios, fusionar varias llamadas API internas en una llamada externa. |
| 5. Sincronización de datos | Sincronizar múltiples estados de recursos o ejecutar operaciones por lotes (por ejemplo, etiquetado, eliminación). |
| 6. Optimización de límite de velocidad | Reducir la carga de API Gateway y ahorrar ancho de banda consolidando solicitudes. |
Factores clave que afectan la eficiencia de Batch API
¿Cuánto costo pueden ahorrar las API por lotes en comparación con las API en tiempo real?
El análisis de la industria (Growth-onomics) muestra reducciones de costos de aproximadamente 20–45%, principalmente debido a menos viajes de ida y vuelta en la red, menor sobrecarga de conexión y procesamiento concentrado, aunque los ahorros exactos dependen de la frecuencia de llamadas, el tamaño del lote y el diseño del sistema.
¿Qué pasa con la latencia? ¿Las API por lotes realmente pueden terminar “en 24 horas”?
Las API por lotes generalmente se ejecutan de forma asíncrona con una latencia mucho mayor que las API en tiempo real; muchos sistemas se ejecutan cada hora o diariamente, por lo que “en 24 horas” depende del SLA más que de una garantía.
¿El tamaño del lote o del archivo afecta la velocidad?
Sí. Los lotes más grandes (por ejemplo, más líneas JSONL) aumentan el tiempo de transferencia y análisis casi linealmente; aunque el rendimiento mejora, el tiempo total de finalización por lote crece.
¿Por qué las API por lotes son mejores para cargas de trabajo de alto rendimiento?
Al agregar miles de solicitudes en un solo proceso, las API por lotes reducen la sobrecarga por llamada y permiten la ejecución en paralelo o la reutilización de caché, a menudo mejorando el rendimiento en un 17–92% en operaciones a gran escala, aunque esto tiene el costo de una mayor latencia.
¿Cómo usar Batch API?
La API por lotes de Novita es altamente compatible con la interfaz de OpenAI, compatible con
/v1/chat/completionsy/v1/completionspara que el código existente pueda reutilizarse con cambios mínimos. Acepta archivos de entrada.jsonldonde cada línea representa una solicitud individual al mismo modelo, identificada por uncustom_idúnico para un fácil seguimiento. La salida también está en formato JSONL, lo que hace que el procesamiento posterior a gran escala, el análisis y la integración sean sencillos y eficientes.
1. Prepara tu archivo de entrada por lotes
Crea un archivo .jsonl, donde cada línea es una solicitud API en formato JSON.
Ejemplo (batch_input.jsonl):
{"custom_id": "req-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Summarize: batch API basics"}], "max_tokens": 200}}
{"custom_id": "req-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are concise."},{"role": "user", "content": "List 3 batch API use cases"}], "max_tokens": 150}}
Reglas:
- Una solicitud por línea.
- Todas las solicitudes deben usar el mismo modelo.
- Cada línea debe incluir un
custom_idúnico.
2. Sube el archivo de entrada y crea un lote
Usa Python o curl para subir el archivo e iniciar inmediatamente el trabajo por lotes.
Python
from openai import OpenAI
client = OpenAI(base_url="https://api.novita.ai/openai/v1", api_key="YOUR_API_KEY")
# Upload + create batch
uploaded = client.files.create(file=open("batch_input.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
input_file_id=uploaded.id,
endpoint="/v1/chat/completions",
completion_window="48h"
)
print("file_id:", uploaded.id)
print("batch_id:", batch.id)
curl
export API_KEY="YOUR_API_KEY"
# Upload file
upload_response=$(curl -s -X POST \
-H "Authorization: Bearer ${API_KEY}" \
-F 'file=@batch_input.jsonl' -F 'purpose=batch' \
https://api.novita.ai/openai/v1/files)
# Extract file_id and start batch
file_id=$(echo $upload_response | jq -r '.id')
curl -X POST https://api.novita.ai/openai/v1/batches \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"input_file_id\": \"$file_id\", \"endpoint\": \"/v1/chat/completions\", \"completion_window\": \"48h\"}"
3. Verifica el estado del lote
Puedes verificar el progreso en cualquier momento usando el ID del lote.
batch = client.batches.retrieve("batch_xxx")
print(batch.status)
Los estados incluyen:
VALIDATING– archivo de entrada siendo verificadoPROGRESS– ejecutándoseCOMPLETED– finalizado exitosamenteFAILED– fallóEXPIRED– excedió la ventana de 48 h
4. Recupera los resultados
Una vez completado, descarga el archivo de resultados mediante output_file_id:
output = client.files.content("file_xxx")
print(output.read().decode("utf-8"))
Cada línea en la salida corresponde a una entrada, emparejada por custom_id.
Consejos:
solo compatible con
deepseek/deepseek-r1-0528Hasta 50 000 solicitudes por lote
Archivo de entrada ≤ 100 MB
Ventana de finalización fijada en 48 horas
Salida retenida durante 30 días
¿Cómo deben manejarse las solicitudes fallidas en una API por lotes?
Los errores encontrados durante el procesamiento por lotes se registran en un archivo de error separado, accesible mediante el campo error_file_id. Cada sub-solicitud fallida incluye un código de error y una descripción. Ejemplos comunes:
| Código de error | Descripción | Solución |
|---|---|---|
| 400 | Formato de solicitud inválido | Verificar sintaxis JSONL y campos requeridos |
| 401 | Autenticación fallida | Verificar clave API |
| 404 | Lote no encontrado | Verificar ID del lote |
| 429 | Límite de velocidad excedido | Reducir frecuencia de solicitudes |
| 500 | Error del servidor | Contactar al proveedor o reintentar más tarde |
Los desarrolladores deberían reprocesar solo las entradas fallidas utilizando una cola de reintentos o un lote de seguimiento más pequeño, en lugar de reenviar todo el archivo original.
¿Qué endpoints proporciona Novita AI para las operaciones de API por lotes?
| Endpoint | Propósito |
|---|---|
| Crear lote | Enviar un nuevo trabajo por lotes que contenga múltiples solicitudes. |
| Recuperar lote | Obtener el estado o los resultados de un lote específico por su ID. |
| Cancelar lote | Detener un trabajo por lotes en ejecución antes de su finalización. |
| Listar lotes | Listar todos los trabajos por lotes enviados para la cuenta. |
| Subir archivo | Subir archivos de datos de entrada (por ejemplo, JSONL). |
| Listar archivos | Ver todos los archivos subidos. |
| Recuperar archivo | Obtener metadatos del archivo por ID de archivo. |
| Eliminar archivo | Eliminar un archivo subido. |
| Recuperar contenido del archivo | Descargar el contenido real de un archivo (por ejemplo, resultados o registro de errores). |
Batch API consolida muchas solicitudes pequeñas en un flujo de trabajo eficiente. Al usar Novita AI’s Batch API, los desarrolladores pueden reducir los costos de red hasta en un 45%, escalar el rendimiento para hasta 50 000 solicitudes por lote y simplificar el manejo de errores a través del registro incorporado y los endpoints de recuperación. Aunque sacrifica la velocidad en tiempo real, ofrece una eficiencia excepcional para cargas de trabajo de inferencia masiva, sincronización y procesamiento de datos.
Novita AI es una plataforma en la nube de IA que ofrece a los desarrolladores una forma sencilla de implementar modelos de IA utilizando nuestra API simple, al mismo tiempo que proporciona una nube de GPU asequible y confiable para construir y escalar.
