Ir al contenido principal
Español— Elegir un idioma
Menú

Formato JSONL y carga mediante la API de archivos

Lección 6 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Procesamiento por lotes con JSONL
  2. Estructura del archivo JSONL
  3. Generar un archivo JSONL en Python
  4. Carga mediante la API de archivos
  5. Crear el lote a partir del archivo
  6. Límites del formato JSONL
  7. Generar un archivo JSONL en JavaScript
  8. Validación y depuración
  9. Puntos clave

Actualizado el 2 de noviembre de 2026 según la documentación de xAI: el descuento por lotes es del 20 % en modelos de texto elegibles (no del 50 %), los ejemplos siguen la API REST y el xai-sdk oficial (client.batch.*; la API de lotes de xAI no utiliza el formato de OpenAI, por lo que el SDK de OpenAI no es aplicable), y la API de Responses tiene prioridad sobre Chat Completions, un punto final heredado en xAI. Fuentes: API de lotes · Referencia REST · Precios de lotes.

Procesamiento por lotes con JSONL

Para grandes volúmenes preparados con antelación, un archivo JSONL es la vía más sencilla. Escribes todas tus solicitudes en un archivo, lo subes a través de la API de archivos y, a continuación, creas el lote a partir de dicho archivo. Un único archivo puede contener hasta 50.000 solicitudes.

Estructura del archivo JSONL

Un archivo JSONL (JSON Lines) contiene un objeto JSON por línea. Cada línea representa una solicitud completa con cuatro campos:

{"custom_id": "req-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Summarize this text in one sentence: ..."}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Classify this ticket: bug, feature, or question. ..."}]}}
{"custom_id": "req-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-4.3", "messages": [{"role": "user", "content": "Translate into English: ..."}]}}
  • custom_id: un identificador único dentro del archivo; se convierte en el batch_request_id en los resultados.
  • method: siempre "POST".
  • url: el punto final de destino, uno de los siete aceptados.
  • body: el cuerpo de la solicitud, que debe coincidir con la referencia de la API para ese punto final.

Cada línea debe ser un JSON válido y autónomo: sin comas separadoras ni corchetes de cierre. Los puntos finales pueden mezclarse en el mismo archivo; cada solicitud se enruta de forma independiente.

Generar un archivo JSONL en Python

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... up to 50,000 documents per file
]

with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
    for doc in documents:
        ligne = {
            "custom_id": doc["id"],
            "method": "POST",
            "url": "/v1/responses",
            "body": {
                "model": "grok-4.3",
                "input": [
                    {"role": "system", "content": "Summarize in three sentences."},
                    {"role": "user", "content": doc["text"]},
                ],
            },
        }
        f.write(json.dumps(ligne, ensure_ascii=False) + "\n")

Carga mediante la API de archivos

Subes el archivo a través del punto final /v1/files, sin ningún otro parámetro:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F file="@batch_requests.jsonl"

Con el SDK de Python:

from xai_sdk import Client

client = Client()

with open("batch_requests.jsonl", "rb") as f:
    fichier = client.files.upload(f, filename="batch_requests.jsonl")
print(f"Uploaded file: {fichier.id}")

Crear el lote a partir del archivo

El archivo no se añade a un lote existente: debes especificarlo en el momento de la creación mediante input_file_id:

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "article_summaries", "input_file_id": "file-abc123"}'
batch = client.batch.create(batch_name="article_summaries", input_file_id=fichier.id)
print(f"Batch created: {batch.batch_id}")

A continuación, el archivo se lee en segundo plano. Si siquiera una línea no es válida, el lote se cancela con un mensaje de error. El seguimiento y la recuperación de resultados funcionan exactamente igual que para un lote enviado a través de la API.

Límites del formato JSONL

  • Máximo 50.000 solicitudes por archivo.
  • Máximo 200 MB por archivo.
  • Un custom_id único por línea.
  • Un lote creado a partir de un archivo está sellado: no puedes añadirle contenido posteriormente a través de la API.

Si tu lote supera estos límites, divídelo en varios archivos y crea un lote por archivo. No hay límite en el número de lotes por equipo.

Generar un archivo JSONL en JavaScript

import fs from "fs";

const documents = [
  { id: "doc-001", text: "First article..." },
  { id: "doc-002", text: "Second article..." },
];

const lines = documents.map(doc => JSON.stringify({
  custom_id: doc.id,
  method: "POST",
  url: "/v1/responses",
  body: {
    model: "grok-4.3",
    input: [
      { role: "user", content: `Summarize: ${doc.text}` }
    ]
  }
}));

fs.writeFileSync("batch_requests.jsonl", lines.join("\n") + "\n");

Validación y depuración

Una sola línea no válida cancela todo el lote: valida el archivo antes de subirlo. Un script sencillo cubre lo esencial:

import json
import os

ENDPOINTS = {
    "/v1/responses", "/v1/chat/completions",
    "/v1/images/generations", "/v1/images/edits",
    "/v1/videos/generations", "/v1/videos", "/v1/videos/edits", "/v1/videos/extensions",
}

def valider_jsonl(chemin: str) -> list[str]:
    erreurs, ids = [], set()
    if os.path.getsize(chemin) > 200 * 1024 * 1024:
        erreurs.append("file larger than 200 MB")
    with open(chemin, encoding="utf-8") as f:
        for i, ligne in enumerate(f, 1):
            try:
                obj = json.loads(ligne)
            except json.JSONDecodeError as e:
                erreurs.append(f"line {i}: invalid JSON ({e})")
                continue
            cid = obj.get("custom_id")
            if not cid or cid in ids:
                erreurs.append(f"line {i}: missing or duplicate custom_id")
            ids.add(cid)
            if obj.get("method") != "POST" or obj.get("url") not in ENDPOINTS:
                erreurs.append(f"line {i}: invalid method or url")
            if not isinstance(obj.get("body"), dict):
                erreurs.append(f"line {i}: missing body")
    if len(ids) > 50_000:
        erreurs.append("more than 50,000 requests")
    return erreurs

print(valider_jsonl("batch_requests.jsonl") or "File is valid")

Puntos clave

  • El formato JSONL contiene un objeto JSON por línea: custom_id, method, url, body.
  • Subes el archivo a través de /v1/files y luego lo especificas al crear el lote (input_file_id).
  • Máximo 50.000 solicitudes y 200 MB por archivo; más allá de eso, un lote por archivo.
  • Un lote creado a partir de un archivo está sellado y una sola línea no válida lo cancela por completo.
  • Valida el archivo antes de subirlo.