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

Formato JSONL, custom_id e Carregamento de Ficheiros

Aula 2 de 16 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. O Formato JSONL: A Espinha Dorsal da Inferência em Lote
  2. Estrutura do Pedido JSONL
  3. Gerar um Ficheiro JSONL em Python
  4. Carregar o Ficheiro para a Mistral
  5. Validação do Ficheiro
  6. Limites e Restrições
  7. Pontos-chave

Atualizado a 3 de novembro de 2026: Com o SDK mistralai 3.7.0, o método files.upload espera file={"file_name": …, "content": …} (passar um tuple gera um ValidationError antes do envio de quaisquer dados) e o tamanho do ficheiro está disponível em size_bytes.

O Formato JSONL: A Espinha Dorsal da Inferência em Lote

O JSONL (JSON Lines) é o formato padrão que a Mistral utiliza para estruturar pedidos em lote. Cada linha do ficheiro é um objeto JSON independente que representa um único pedido. Este desenho é intencional: pode gerar um ficheiro de um milhão de linhas em fluxo contínuo sem o carregar totalmente na memória, lê-lo linha por linha e inspecionar entradas específicas manualmente quando um pedido falha. Ao contrário de um único массив JSON massivo, que o obriga a carregar o ficheiro inteiro apenas para verificar uma entrada, o JSONL permite-lhe trabalhar ao nível da linha.

Estrutura do Pedido JSONL

Cada linha do seu ficheiro JSONL deve conter dois campos obrigatórios:

{
  "custom_id": "req-001",
  "body": {
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Summarize this document in 3 points."}
    ]
  }
}

O custom_id é um identificador único que você define para cada pedido. É isto que torna os resultados utilizáveis. A Mistral não garante a ordem de processamento: o ficheiro de saída pode começar pelo pedido 8.472. Sem um custom_id, fica com uma pilha de respostas e nenhuma forma de saber a qual documento corresponde cada uma. Adote o hábito de derivar este ID do seu próprio sistema de referência — doc-001, email-2024-03-15-042, product-sku-ABC123 — em vez de usar um contador anónimo. Quando uma resposta causa problemas, consegue rastreá-la até à origem sem executar uma consulta SQL. Aplicam-se aqui duas regras práticas: os IDs devem ser únicos dentro do ficheiro, sob pena de o processamento devolver um erro, e devem ser razoavelmente curtos, pois um identificador de 200 caracteres torna os registos ilegíveis.

O campo body não exige nenhuma aprendizagem nova: contém exatamente a estrutura que utilizaria numa chamada síncrona à API para o endpoint de destino. Se estiver a targeting /v1/chat/completions, o corpo é idêntico ao que passaria numa chamada client.chat.complete(). Um prompt validado interativamente traduz-se diretamente num trabalho em lote.

Gerar um Ficheiro JSONL em Python

Eis como gerar programaticamente um ficheiro JSONL a partir de uma lista de documentos:

import json

documents = [
    {"id": "doc-001", "text": "Artificial intelligence is transforming..."},
    {"id": "doc-002", "text": "Deep neural networks..."},
    {"id": "doc-003", "text": "Natural language processing..."},
]

with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
    for doc in documents:
        request = {
            "custom_id": doc["id"],
            "body": {
                "model": "mistral-small-latest",
                "max_tokens": 200,
                "messages": [
                    {
                        "role": "system",
                        "content": "You are an assistant that summarizes texts."
                    },
                    {
                        "role": "user",
                        "content": f"Summarize this text: {doc['text']}"
                    }
                ]
            }
        }
        f.write(json.dumps(request, ensure_ascii=False) + "\n")

Note o parâmetro ensure_ascii=False. Sem ele, o json.dumps escapa os caracteres acentuados como sequências \uXXXX. O ficheiro permanece válido, mas torna-se impossível de ler para humanos, transformando qualquer depuração num corpus francês num exercício de descodificação. Torne isto no seu padrão desde a primeira linha de código.

Carregar o Ficheiro para a Mistral

Em produção, faça o carregamento através da API Python:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Upload the JSONL file
with open("batch_requests.jsonl", "rb") as f:
    batch_file = client.files.upload(
        file={"file_name": "batch_requests.jsonl", "content": f},
        purpose="batch"
    )

print(f"Uploaded file: {batch_file.id}")
print(f"Size: {batch_file.size_bytes} bytes")
print(f"Purpose: {batch_file.purpose}")

O parâmetro purpose="batch" informa a Mistral de que este ficheiro se destina ao processamento em lote, e não a outras funcionalidades como o fine-tuning ou RAG. Esta declaração de intenção dita o que acontece a seguir: um ficheiro carregado com a finalidade errada será rejeitado pelo trabalho.

Para um teste rápido ou para equipas não técnicas, o AI Studio oferece o mesmo serviço através da interface gráfica:

  1. Aceda a console.mistral.ai/build/files
  2. Clique em “Upload”
  3. Selecione o seu ficheiro JSONL
  4. Escolha a finalidade “Batch Processing”

A interface devolve um file_id, exatamente como a API, e este é o identificador que utiliza para criar o trabalho em lote.

Validação do Ficheiro

Um lote de um milhão de linhas que falha na linha 300 devido a um custom_id duplicado custa-lhe um ciclo de espera completo. Alguns segundos de validação local previnem esta perda. O seguinte script realiza uma única passagem para verificar a validade do JSON, a presença dos dois campos obrigatórios e a unicidade dos IDs:

import json

errors = []
seen_ids = set()

with open("batch_requests.jsonl", "r", encoding="utf-8") as f:
    for line_num, line in enumerate(f, 1):
        try:
            data = json.loads(line)
        except json.JSONDecodeError as e:
            errors.append(f"Line {line_num}: Invalid JSON - {e}")
            continue

        # Check required fields
        if "custom_id" not in data:
            errors.append(f"Line {line_num}: missing custom_id")
        if "body" not in data:
            errors.append(f"Line {line_num}: missing body")

        # Check custom_id uniqueness
        cid = data.get("custom_id")
        if cid in seen_ids:
            errors.append(f"Line {line_num}: duplicate custom_id '{cid}'")
        seen_ids.add(cid)

if errors:
    print(f"{len(errors)} error(s) found:")
    for e in errors:
        print(f"  - {e}")
else:
    print(f"File valid: {len(seen_ids)} requests ready.")

Torne isto num passo sistemático no seu pipeline de preparação, executado imediatamente antes do carregamento.

Limites e Restrições

O agrupamento de ficheiros limita-se a um milhão de linhas por ficheiro, o que significa que deve dividir corpora maiores em múltiplos envios. A codificação deve ser UTF-8 e o formato exige estritamente um objeto JSON por linha: um objeto JSON distribuído por várias linhas, como produzido por um json.dumps(..., indent=2) mal colocado, quebra a análise do lado do servidor. Por fim, lembre-se das duas regras já mencionadas, pois violá-las faz com que o trabalho falhe: o custom_id deve ser único dentro do ficheiro e o body deve corresponder ao esquema do endpoint de destino.

Pontos-chave

  • O JSONL estrutura os seus pedidos em lote com um objeto JSON por linha
  • Cada pedido requer um custom_id único e um body que corresponda ao endpoint de destino
  • Carregue via API Python (client.files.upload) ou através do AI Studio
  • Valide sempre o seu ficheiro antes do envio para evitar erros de processamento
  • Utilize ensure_ascii=False para francês e caracteres acentuados