Inferencia por lotes

La Batch API para Large Language Models permite el procesamiento asíncrono de numerosas solicitudes de inferencia y es totalmente compatible con el estándar de la OpenAI API. La Batch API es una solución rentable cuando no se necesitan resultados de inferencia inmediatos. Proporciona límites de tasa más altos que las llamadas en línea, lo que garantiza que los resultados se entreguen dentro de un plazo razonable de 24 horas. Esta API es ideal para:

Realizar evaluaciones y análisis de datos.
Clasificar conjuntos de datos extensos.
Generar resúmenes de documentos en modo sin conexión.

Modelos admitidos:

Inicio rápido

1. Preparar archivos por lotes

La Batch API utiliza archivos en formato .jsonl como entrada, donde cada línea representa los detalles de una solicitud de inferencia de API. Los endpoints disponibles incluyen /v1/chat/completions y /v1/completions.

Establece el parámetro endpoint en /v1/chat/completions o /v1/completions para la compatibilidad con la OpenAI API.

Cada solicitud debe incluir un custom_id único para localizar los resultados de inferencia en el archivo de salida una vez completado el lote. Los parámetros del campo body de cada línea se envían como parámetros reales de la solicitud de inferencia al endpoint.

Todas las solicitudes dentro de un único archivo JSONL por lotes deben apuntar al mismo modelo. No mezcles solicitudes para diferentes modelos en un solo lote.

A continuación se muestra un archivo de entrada de ejemplo que contiene 2 solicitudes:

{"custom_id": "request-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Hello, world!"}], "max_tokens": 400}}
{"custom_id": "request-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

2. Subir el archivo de entrada por lotes

Sube el archivo de entrada por lotes para garantizar que pueda referenciarse con precisión al crear un lote. Usa la Files API para subir tu archivo .jsonl y establece el purpose en batch. Ten en cuenta que el archivo se conservará durante 15 días.

Para saber cómo obtener una API key, consulta Gestión de API Key.

Ejemplo de código Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch_input_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

print(batch_input_file)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/files \
  --header 'Authorization: Bearer ${API_KEY}' \
  --form 'file=@"/your/batch_input.jsonl"' \
  --form 'purpose="batch"'

Respuesta de ejemplo tras una subida de archivo correcta:

{
    "id": "file_d2co***as73c0cjd0",
    "object": "file",
    "bytes": 238,
    "filename": "batch_input.jsonl",
    "created_at": 1754894162,
    "purpose": "batch",
    "metadata": {
        "total_requests": 2
    }
}

3. Crear un lote

Una vez que el archivo de entrada se haya subido correctamente, puedes iniciar un lote usando el ID del objeto File subido. La ventana de finalización está fijada en 24h y actualmente no se puede ajustar. Ejemplo de código Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch = client.batches.create(
  input_file_id="file_d2cor0es1cas73c0cj60",
  endpoint="/v1/chat/completions",
  completion_window="24h"
)
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/batches \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}' \
  --data '{
      "input_file_id": "file_d2co***as73c0cjd0",
      "endpoint": "/v1/chat/completions",
      "completion_window": "24h"
  }'

Esta solicitud generará un objeto Batch que incluye metadatos sobre tu lote, como se ilustra en el siguiente ejemplo:

{
    "id": "batch_d2cq***73a68lu0",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "input_file_id": "file_d2co***as73c0cjd0",
    "output_file_id": "",
    "error_file_id": "",
    "completion_window": "24h",
    "in_progress_at": null,
    "expires_at": null,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "status": "validating",
    "errors": "",
    "version": 0,
    "created_at": "2025-08-11T16:31:52.949816948+08:00",
    "updated_at": null,
    "created_by": "8f242aa1-f725-4a67-8***9-cb68025e0976",
    "created_by_key_id": "key_cc19f96c***e7390644a37da21",
    "remark": "",
    "total": 0,
    "completed": 0,
    "failed": 0,
    "metadata": null,
    "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
    }
}

4. Comprobar el estado de un lote

Puedes comprobar el estado de un lote en cualquier momento para recibir la información más reciente del lote. Los valores de enumeración de estado del objeto Batch son los siguientes:

Estado	Descripción
VALIDATING	El archivo de entrada se está validando antes de que el lote pueda comenzar
PROGRESS	El lote está en progreso
COMPLETED	El procesamiento por lotes se completó correctamente
FAILED	El procesamiento por lotes falló
EXPIRED	El lote superó la fecha límite
CANCELLING	El lote se está cancelando
CANCELLED	El lote fue cancelado

Ejemplo de código Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)
batch = client.batches.retrieve("batch_d2cq***73a68lu0")
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/batches/{batch_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

5. Recuperar los resultados

Una vez completada la inferencia por lotes, puedes descargar el archivo de salida de resultados usando el campo output_file_id del objeto Batch. El archivo de salida de resultados se eliminará 30 días después de que concluya la inferencia por lotes, así que recupéralo cuanto antes mediante la interfaz. Ejemplo de código Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

content = client.files.content("example-250811-1")
print(content.read())

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/files/{file_id}/content \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

La respuesta devuelve el contenido sin procesar del archivo. Para los archivos de salida por lotes, cada línea contiene una respuesta como esta:

{
  "custom_id": "request-2589",
  "error": null,
  "id": "batch_req_task_d2c",
  "response": {
    "body": {
      "id": "29e1432c-edfb-44a4-b531-c23c600abfae",
      "object": "chat.completion",
      "created": 1754902266,
      "model": "deepseek-test",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! 👋 How can I assist you today? 😊"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 13,
        "total_tokens": 18
      }
    },
    "request_id": "request-2589",
    "status_code": 200
  }
}

Instrucciones

Limitaciones

Cada lote puede contener hasta 50,000 solicitudes.
El tamaño máximo del archivo de entrada por lote es de 100MB.

Manejo de errores

Los errores encontrados durante el procesamiento por lotes se registran en un archivo de errores independiente, accesible mediante el campo error_file_id. Los códigos de error comunes incluyen:

Código de error	Descripción	Solución
400	Formato de solicitud no válido	Comprueba la sintaxis JSONL y los campos obligatorios
401	Error de autenticación	Verifica la API key
404	Lote no encontrado	Comprueba el batch ID
429	Límite de tasa superado	Reduce la frecuencia de las solicitudes
500	Error del servidor	Contáctanos

Expiración de lotes

Los lotes que no se completen en un plazo de 24 horas pasarán a un estado EXPIRED. Las solicitudes no finalizadas se cancelarán, mientras que las solicitudes completadas se proporcionarán mediante un archivo de salida. Solo pagas por los tokens consumidos por las solicitudes completadas. El lote hará todo lo posible por completarse dentro de 24 horas.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Inicio rápido

1. Preparar archivos por lotes

2. Subir el archivo de entrada por lotes

3. Crear un lote

4. Comprobar el estado de un lote

5. Recuperar los resultados

Instrucciones

Limitaciones

Manejo de errores

Expiración de lotes

Toda la Batch API

​Inicio rápido

​1. Preparar archivos por lotes

​2. Subir el archivo de entrada por lotes

​3. Crear un lote

​4. Comprobar el estado de un lote

​5. Recuperar los resultados

​Instrucciones

​Limitaciones

​Manejo de errores

​Expiración de lotes

​Toda la Batch API

Inicio rápido

1. Preparar archivos por lotes

2. Subir el archivo de entrada por lotes

3. Crear un lote

4. Comprobar el estado de un lote

5. Recuperar los resultados

Instrucciones

Limitaciones

Manejo de errores

Expiración de lotes

Toda la Batch API