Procesamiento por lotes

La API Batch te permite enviar grupos de solicitudes como un solo trabajo que se procesa de forma asíncrona. Esto es útil cuando necesitas ejecutar muchas solicitudes y no requieres resultados inmediatos — por ejemplo, realizar evaluaciones, generar embeddings para un gran conjunto de datos o clasificar contenido en masa. Las solicitudes por lotes se ejecutan dentro de una ventana de finalización de 24 horas y tienen límites de velocidad separados y más altos que las llamadas síncronas a la API.

Endpoints compatibles

Endpoint	Descripción
`/v1/chat/completions`	Solicitudes de completación de chat
`/v1/embeddings`	Generación de embeddings
`/v1/images/generations`	Generación de imágenes

Todas las solicitudes en un solo lote deben dirigirse al mismo endpoint.

Ciclo de vida

Un lote pasa por estos estados:

validating → in_progress → finalizing → completed
     ↓            ↓
   failed     cancelling → cancelled

Estado	Descripción
`validating`	El archivo de entrada está siendo verificado por errores de formato y contenido.
`failed`	La validación falló — el archivo de entrada contiene errores. Consulta `batch.errors` para más detalles.
`in_progress`	Las solicitudes están siendo procesadas.
`finalizing`	Todas las solicitudes han sido procesadas y se están generando los archivos de salida.
`completed`	El lote finalizó. Descarga los resultados desde `output_file_id`.
`cancelling`	Se solicitó una cancelación. Las solicitudes en curso están finalizando.
`cancelled`	El lote fue cancelado. Puede haber resultados parciales disponibles.
`expired`	El lote no se completó dentro de la ventana de 24 horas.

Paso 1 — Prepara el archivo de entrada

Crea un archivo JSONL donde cada línea sea una solicitud. Cada línea tiene cuatro campos:

Campo	Tipo	Descripción
`custom_id`	string	Tu identificador para esta solicitud. Se usa para emparejar la entrada con la salida. Debe ser único dentro del archivo.
`method`	string	`"POST"` — el único método soportado.
`url`	string	La ruta del endpoint — debe coincidir con el `endpoint` que declares al crear el lote.
`body`	object	El cuerpo de la solicitud — los mismos parámetros que enviarías al endpoint síncrono.

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "meetkai:functionary-es-mini", "messages": [{"role": "user", "content": "Summarize the benefits of batch processing in one sentence."}], "max_tokens": 100}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "meetkai:functionary-es-mini", "messages": [{"role": "user", "content": "What is the capital of France?"}], "max_tokens": 100}}
{"custom_id": "request-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "meetkai:functionary-es-mini", "messages": [{"role": "user", "content": "Explain embeddings in one paragraph."}], "max_tokens": 100}}

Un solo lote puede contener hasta 10,000 solicitudes.

Paso 2 — Sube el archivo de entrada

Sube el archivo JSONL usando la API de Archivos con purpose: "batch".

mka1 llm files upload \
  --file ./batch_input.jsonl \
  --purpose batch \
  -H 'X-On-Behalf-Of: <end-user-id>'

Paso 3 — Crea el lote

Pasa el ID del archivo subido, el endpoint de destino y la ventana de finalización.

mka1 llm batches create --body '{
  "input_file_id": "file_abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h"
}'

También puedes adjuntar metadatos para tu propio seguimiento:

mka1 llm batches create --body '{
  "input_file_id": "file_abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "description": "nightly evaluation run",
    "run_id": "eval-2026-03-31"
  }
}'

Paso 4 — Consulta el estado del lote

Consulta el lote hasta que alcance un estado terminal.

mka1 llm batches get --batch-id batch_abc123

Aquí tienes un ayudante para hacer polling y esperar a que el lote termine:

# Consulta un lote hasta que alcance un estado terminal usando --jq y un bucle de shell.
BATCH_ID=batch_abc123
while :; do
  STATUS=$(mka1 llm batches get --batch-id "$BATCH_ID" --jq '.status' --output-format json)
  echo "status: $STATUS"
  case "$STATUS" in
    completed|failed|cancelled|expired) break ;;
  esac
  sleep 2
done

Paso 5 — Descarga los resultados

Una vez que el lote esté completed, descarga el archivo de salida. Es un archivo JSONL donde cada línea contiene el custom_id que proporcionaste, la respuesta y cualquier error.

# Descarga el archivo de salida JSONL
mka1 llm files content \
  --file-id file_xyz789 \
  --output-file ./batch_output.jsonl

# Inspecciona los resultados en línea con jq
mka1 llm files content --file-id file_xyz789 \
  --jq '"\(.custom_id): status=\(.response.status_code)"'

Cada línea en el archivo de salida tiene esta estructura:

{
  "id": "response_abc123",
  "custom_id": "request-1",
  "response": {
    "status_code": 200,
    "request_id": "req_abc123",
    "body": { "...": "same shape as the synchronous endpoint response" }
  },
  "error": null
}

Si una solicitud falló, response es null y error contiene los detalles:

{
  "id": "response_def456",
  "custom_id": "request-2",
  "response": null,
  "error": {
    "code": "processing_error",
    "message": "The request could not be processed."
  }
}

Si alguna solicitud falló, el lote también proporciona un error_file_id que contiene solo las entradas fallidas.

Cancelar un lote

Cancela un lote que aún está en progreso. Las solicitudes que ya se hayan completado permanecen en la salida.

mka1 llm batches cancel --batch-id batch_abc123

El lote pasa a cancelling mientras terminan las solicitudes en curso, y luego a cancelled.

Listar lotes

Recupera todos los lotes de la cuenta actual, del más reciente al más antiguo. Soporta paginación.

mka1 llm batches list --limit 20

Usa el parámetro after con un ID de lote para paginar los resultados.

Ejemplo: embeddings por lote

El mismo flujo funciona para embeddings. Cambia el url en cada línea del JSONL y el endpoint al crear el lote.

{"custom_id": "embed-1", "method": "POST", "url": "/v1/embeddings", "body": {"model": "meetkai:functionary-es-mini", "input": "The quick brown fox"}}
{"custom_id": "embed-2", "method": "POST", "url": "/v1/embeddings", "body": {"model": "meetkai:functionary-es-mini", "input": "jumps over the lazy dog"}}

# Sube el archivo JSONL de embeddings
FILE_ID=$(mka1 llm files upload \
  --file ./embed_batch.jsonl \
  --purpose batch \
  --jq '.id' --output-format json | tr -d '"')

# Crea el lote contra el endpoint de embeddings
mka1 llm batches create --body "{
  \"input_file_id\": \"$FILE_ID\",
  \"endpoint\": \"/v1/embeddings\",
  \"completion_window\": \"24h\"
}"

# Haz polling y descarga los resultados — ver Pasos 4 y 5

Errores de validación

Si el archivo de entrada tiene problemas de formato, el lote pasa a failed inmediatamente. Causas comunes:

JSON inválido — una línea no es un JSON válido.
Campos faltantes — falta custom_id, method, url o body en una línea.
Método incorrecto — method debe ser "POST".
URL no coincide — el url de una línea no coincide con el endpoint declarado al crear el lote.
custom_id duplicado — cada custom_id debe ser único dentro del archivo.

Consulta batch.errors.data para ver los mensajes de error específicos y los números de línea.

mka1 llm batches get --batch-id batch_abc123 \
  --jq '.errors.data[] | "Line \(.line): [\(.code)] \(.message)"'

Ver también

Generar una respuesta para el patrón síncrono de completaciones de chat.
Archivos y almacenes vectoriales para la API de Archivos utilizada para subir entradas por lote.

Documentation Index

​Endpoints compatibles

​Ciclo de vida

​Paso 1 — Prepara el archivo de entrada

​Paso 2 — Sube el archivo de entrada

​Paso 3 — Crea el lote

​Paso 4 — Consulta el estado del lote

​Paso 5 — Descarga los resultados

​Cancelar un lote

​Listar lotes

​Ejemplo: embeddings por lote

​Errores de validación

​Ver también