Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Formato JSONL e carregamento através da API de Ficheiros

Aula 6 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Processamento em massa com JSONL
  2. Estrutura do ficheiro JSONL
  3. Gerar um ficheiro JSONL em Python
  4. Carregamento através da API de Ficheiros
  5. Criar o lote a partir do ficheiro
  6. Limites do formato JSONL
  7. Gerar um ficheiro JSONL em JavaScript
  8. Validação e depuração
  9. Pontos-chave

Atualizado em 2 de novembro de 2026 com base na documentação da xAI: o desconto para lotes é de 20% em modelos de texto elegíveis (não 50%), os exemplos seguem a API REST e o xai-sdk oficial (client.batch.*; a API de Lotes da xAI não utiliza o formato da OpenAI, pelo que o SDK da OpenAI não se aplica), e a API de Respostas tem precedência sobre as Conclusões de Chat, um endpoint legado na xAI. Fontes: API de Lotes · Referência REST · Preços de Lotes.

Processamento em massa com JSONL

Para grandes volumes preparados antecipadamente, um ficheiro JSONL é o caminho mais simples. Escreve todos os seus pedidos num ficheiro, carrega-o através da API de Ficheiros e, em seguida, cria o lote a partir desse ficheiro. Um único ficheiro pode conter até 50.000 pedidos.

Estrutura do ficheiro JSONL

Um ficheiro JSONL (JSON Lines) contém um objeto JSON por linha. Cada linha representa um pedido completo com quatro 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: um identificador único dentro do ficheiro; torna-se no batch_request_id nos resultados
  • method: sempre "POST"
  • url: o endpoint de destino, um dos sete aceites
  • body: o corpo do pedido, correspondendo à referência da API para esse endpoint

Cada linha deve ser um JSON válido e autónomo: sem vírgula de separação, sem parênteses retos de envolvimento. Os endpoints podem ser misturados no mesmo ficheiro; cada pedido é encaminhado independentemente.

Gerar um ficheiro JSONL em 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:
        linha = {
            "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(linha, ensure_ascii=False) + "\n")

Carregamento através da API de Ficheiros

Carrega o ficheiro através do endpoint /v1/files, sem quaisquer outros parâmetros:

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

Com o SDK Python:

from xai_sdk import Client

client = Client()

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

Criar o lote a partir do ficheiro

O ficheiro não é adicionado a um lote existente: especifica-o no momento da criação com 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"}'
lote = client.batch.create(batch_name="article_summaries", input_file_id=ficheiro.id)
print(f"Batch created: {lote.batch_id}")

O ficheiro é então lido em segundo plano. Se mesmo uma linha for inválida, o lote é cancelado com uma mensagem de erro. O acompanhamento e a recuperação de resultados funcionam exatamente como para um lote submetido através da API.

Limites do formato JSONL

  • Máximo de 50.000 pedidos por ficheiro
  • Máximo de 200 MB por ficheiro
  • um custom_id único por linha
  • um lote criado a partir de um ficheiro está selado: não lhe pode adicionar nada posteriormente através da API

Se o seu lote exceder estes limites, divida-o em vários ficheiros e crie um lote por ficheiro. Não existe limite para o número de lotes por equipa.

Gerar um ficheiro JSONL em 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");

Validação e depuração

Uma linha inválida cancela todo o lote: valide o ficheiro antes de o carregar. Um script simples cobre o essencial:

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

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

Pontos-chave

  • O formato JSONL contém um objeto JSON por linha: custom_id, method, url, body
  • Carrega o ficheiro através de /v1/files e especifica-o ao criar o lote (input_file_id)
  • Máximo de 50.000 pedidos e 200 MB por ficheiro; além disso, um lote por ficheiro
  • Um lote criado a partir de um ficheiro está selado e uma linha inválida cancela-o totalmente
  • Valide o ficheiro antes de o carregar