Formato JSONL, custom_id e Carregamento de Ficheiros
Nesta página
Atualizado a 3 de novembro de 2026: Com o SDK
mistralai3.7.0, o métodofiles.uploadesperafile={"file_name": …, "content": …}(passar um tuple gera umValidationErrorantes do envio de quaisquer dados) e o tamanho do ficheiro está disponível emsize_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:
- Aceda a
console.mistral.ai/build/files - Clique em “Upload”
- Selecione o seu ficheiro JSONL
- 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 umbodyque 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=Falsepara francês e caracteres acentuados