Por Jerry Fan

JSONL para dados de treinamento de IA

Um guia completo para preparar dados de treinamento em JSONL para IA e aprendizado de máquina. Aborda fine-tuning da OpenAI, Anthropic Claude, datasets da HuggingFace, validação de dados e pipelines de dados em larga escala.

Por que JSONL é o padrão para dados de treinamento de IA

JSONL (JSON Lines) se consolidou como o padrão de fato para dados de treinamento de IA e aprendizado de máquina. Os principais provedores de IA, da OpenAI à Anthropic e à HuggingFace, usam JSONL como formato principal para datasets de fine-tuning. O motivo é simples: JSONL armazena um exemplo por linha, o que facilita a leitura dos dados em streaming durante o treinamento, o embaralhamento dos exemplos, a contagem de registros, a divisão em conjuntos de treino e teste e a inclusão de novas amostras sem precisar reescrever o arquivo inteiro.

Ao contrário de um único array JSON, que precisa ser interpretado por completo antes do uso, os arquivos JSONL podem ser processados linha por linha. Isso faz diferença quando seus datasets de treinamento chegam a milhões de exemplos e ocupam gigabytes. Neste guia, você vai conhecer os formatos JSONL exatos esperados pela OpenAI, pelo Anthropic Claude e pela HuggingFace, aprender a validar e limpar seus dados e preparar datasets em larga escala para treinar modelos em produção.

Valide seus dados de treinamento online

Use nossas ferramentas gratuitas no navegador para validar, formatar e converter seus dados de treinamento em JSONL antes de enviá-los à OpenAI, à Anthropic ou à HuggingFace.

Formato JSONL para fine-tuning da OpenAI

A OpenAI usa JSONL tanto para fine-tuning quanto para a Batch API. No fine-tuning de modelos de chat como GPT-4o-mini, cada linha deve conter um array messages com a estrutura padrão de chat completion. Os três papéis, system, user e assistant, definem a conversa que o modelo deve aprender a reproduzir.

Cada linha corresponde a um exemplo de treinamento. A mensagem system define o comportamento do modelo, a mensagem user fornece a entrada e a mensagem assistant contém a resposta esperada que o modelo deve aprender a gerar.

Formato de treinamento para chat completion
{"messages": [{"role": "system", "content": "You are a helpful customer support agent for an e-commerce platform."}, {"role": "user", "content": "Where is my order #12345?"}, {"role": "assistant", "content": "I can see that order #12345 was shipped on February 10th via FedEx. The tracking number is FX987654321. Based on the latest update, it should arrive by February 14th."}]}
{"messages": [{"role": "system", "content": "You are a helpful customer support agent for an e-commerce platform."}, {"role": "user", "content": "I want to return my purchase."}, {"role": "assistant", "content": "I would be happy to help with your return. Could you please provide the order number and the reason for the return? Our return policy allows returns within 30 days of delivery for most items."}]}

Para conversas com múltiplos turnos, inclua todo o histórico. O modelo aprende com cada resposta de assistant no array messages. É assim que você ensina o modelo a responder a perguntas que dão continuidade à conversa.

Treinamento com conversas de múltiplos turnos
{"messages": [{"role": "system", "content": "You are a Python programming tutor."}, {"role": "user", "content": "What is a list comprehension?"}, {"role": "assistant", "content": "A list comprehension is a concise way to create lists in Python. Instead of writing a for loop to build a list, you can write it in one line: [expression for item in iterable if condition]."}, {"role": "user", "content": "Can you show me an example?"}, {"role": "assistant", "content": "Sure! Here is an example that creates a list of squares for even numbers:\n\nsquares = [x**2 for x in range(10) if x % 2 == 0]\n# Result: [0, 4, 16, 36, 64]\n\nThis is equivalent to:\nsquares = []\nfor x in range(10):\n    if x % 2 == 0:\n        squares.append(x**2)"}]}

A OpenAI exige pelo menos 10 exemplos de treinamento, mas recomenda 50-100 para obter melhorias perceptíveis. Todas as mensagens devem conter os campos role e content. A mensagem system é opcional, mas recomendada para manter um comportamento consistente. Use a CLI da OpenAI para validar seu arquivo antes do upload: openai tools fine_tunes.prepare_data -f training.jsonl

Formato de treinamento do Anthropic Claude

A Anthropic usa JSONL para o fine-tuning dos modelos Claude. O formato organiza a conversa em turnos de human e assistant. Embora o formato exato dependa do método de fine-tuning e da versão da API, a estrutura básica segue a Messages API.

Cada linha contém uma conversa com um prompt de sistema e mensagens alternadas de user/assistant. O modelo aprende a gerar as respostas de assistant com base no contexto da conversa.

Formato de mensagens do Claude
{"system": "You are a medical information assistant. Provide accurate, general health information while always recommending consulting a healthcare professional.", "messages": [{"role": "user", "content": "What are the symptoms of vitamin D deficiency?"}, {"role": "assistant", "content": "Common symptoms of vitamin D deficiency include fatigue and tiredness, bone pain and muscle weakness, mood changes including depression, slow wound healing, and frequent infections. However, many people with mild deficiency may not notice symptoms. A blood test is the only way to confirm your vitamin D levels. I recommend speaking with your doctor who can order the appropriate test and recommend supplementation if needed."}]}
{"system": "You are a medical information assistant. Provide accurate, general health information while always recommending consulting a healthcare professional.", "messages": [{"role": "user", "content": "Is it safe to take ibuprofen daily?"}, {"role": "assistant", "content": "Taking ibuprofen daily for extended periods can carry risks including stomach ulcers and gastrointestinal bleeding, increased risk of heart attack and stroke, kidney problems with long-term use, and potential interactions with other medications. For occasional pain relief, short-term use at recommended doses is generally considered safe for most adults. However, if you find yourself needing daily pain relief, please consult your doctor. They can evaluate the underlying cause and recommend a safer long-term treatment plan."}]}

Nos dados de treinamento com múltiplos turnos, inclua a conversa completa, alternando mensagens de user e assistant. O modelo aprende o fluxo da conversa e como manter o contexto de um turno para o outro.

Conversas de múltiplos turnos com o Claude
{"system": "You are a cooking assistant specializing in Italian cuisine.", "messages": [{"role": "user", "content": "How do I make carbonara?"}, {"role": "assistant", "content": "Authentic carbonara uses just five ingredients: spaghetti, guanciale (cured pork cheek), eggs, Pecorino Romano cheese, and black pepper. The key technique is tempering the egg mixture with the hot pasta water so it creates a creamy sauce without scrambling."}, {"role": "user", "content": "Can I use bacon instead of guanciale?"}, {"role": "assistant", "content": "While guanciale gives the most authentic flavor, pancetta is a closer substitute. Bacon works in a pinch but its smoky flavor changes the dish significantly. If using bacon, choose an unsmoked variety. Whichever you use, cut it into small pieces and render the fat slowly over medium-low heat until crispy."}]}

Datasets da HuggingFace com JSONL

A biblioteca datasets da HuggingFace oferece suporte nativo a JSONL como formato de entrada. Com ela, você pode carregar arquivos JSONL locais, ler datasets remotos em streaming e converter dados entre formatos com facilidade. JSONL é o formato recomendado para compartilhar datasets no HuggingFace Hub.

Use a biblioteca datasets para carregar arquivos JSONL em um objeto Dataset. Assim, você tem acesso eficiente aos dados por mapeamento de memória, recursos integrados para dividir os dados em conjuntos de treino e teste e integração direta com a Trainer API.

Como carregar datasets JSONL
from datasets import load_dataset


# Load a local JSONL file
dataset = load_dataset('json', data_files='training.jsonl')
print(dataset)
# DatasetDict({
#     train: Dataset({
#         features: ['messages', 'system'],
#         num_rows: 5000
#     })
# })


# Load with train/test split
dataset = load_dataset('json', data_files={
    'train': 'train.jsonl',
    'test': 'test.jsonl'
})


# Stream a large remote dataset
dataset = load_dataset(
    'json',
    data_files='https://example.com/large_dataset.jsonl',
    streaming=True
)
for example in dataset['train']:
    print(example)
    break

Converta qualquer dataset da HuggingFace para JSONL e use-o em outros pipelines de treinamento. O método to_json grava cada exemplo em uma linha JSON separada.

Como exportar para JSONL
from datasets import load_dataset


# Load a dataset from the Hub
dataset = load_dataset('squad', split='train')


# Export to JSONL
dataset.to_json('squad_train.jsonl')
print(f'Exported {len(dataset)} examples')


# Export with specific columns
dataset.select_columns(['question', 'context', 'answers']).to_json(
    'squad_filtered.jsonl'
)


# Process and export
def format_for_finetuning(example):
    return {
        'messages': [
            {'role': 'user', 'content': example['question']},
            {'role': 'assistant', 'content': example['answers']['text'][0]}
        ]
    }


formatted = dataset.map(format_for_finetuning, remove_columns=dataset.column_names)
formatted.to_json('squad_chat_format.jsonl')

Validação e limpeza dos dados

A qualidade dos dados de treinamento afeta diretamente o desempenho do modelo. JSON inválido, campos ausentes, exemplos longos demais e registros duplicados podem prejudicar os resultados do fine-tuning. Sempre valide e limpe seus arquivos JSONL antes de iniciar o treinamento.

Este script verifica cada linha do seu arquivo JSONL em busca de problemas comuns: JSON inválido, campos obrigatórios ausentes, conteúdo vazio e quantidade de tokens. Execute-o antes do upload para identificar problemas com antecedência.

Validador de dados de treinamento em JSONL
import json
import sys
from collections import Counter


def validate_training_data(path: str) -> dict:
    """Validate a JSONL file for AI fine-tuning."""
    stats = Counter()
    errors = []


    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            stats['total'] += 1


            # Check valid JSON
            try:
                data = json.loads(line)
            except json.JSONDecodeError as e:
                errors.append(f'Line {line_num}: Invalid JSON - {e}')
                stats['invalid_json'] += 1
                continue


            # Check messages field exists
            if 'messages' not in data:
                errors.append(f'Line {line_num}: Missing "messages" field')
                stats['missing_messages'] += 1
                continue


            messages = data['messages']


            # Check message structure
            for i, msg in enumerate(messages):
                if 'role' not in msg:
                    errors.append(f'Line {line_num}, msg {i}: Missing "role"')
                    stats['missing_role'] += 1
                if 'content' not in msg:
                    errors.append(f'Line {line_num}, msg {i}: Missing "content"')
                    stats['missing_content'] += 1
                elif not msg['content'].strip():
                    errors.append(f'Line {line_num}, msg {i}: Empty content')
                    stats['empty_content'] += 1


            # Check has at least one assistant message
            roles = [m.get('role') for m in messages]
            if 'assistant' not in roles:
                errors.append(f'Line {line_num}: No assistant message')
                stats['no_assistant'] += 1


            stats['valid'] += 1


    return {'stats': dict(stats), 'errors': errors[:50]}


result = validate_training_data('training.jsonl')
print(f"Total: {result['stats'].get('total', 0)}")
print(f"Valid: {result['stats'].get('valid', 0)}")
if result['errors']:
    print(f"\nFirst {len(result['errors'])} errors:")
    for err in result['errors']:
        print(f'  {err}')

Exemplos de treinamento duplicados desperdiçam recursos computacionais e podem enviesar o modelo em favor de padrões que aparecem em excesso. Este script remove duplicatas exatas com base no hash do conteúdo de cada linha.

Script de deduplicação
import json
import hashlib


def deduplicate_jsonl(input_path: str, output_path: str) -> dict:
    """Remove duplicate training examples from a JSONL file."""
    seen_hashes = set()
    total = 0
    unique = 0


    with open(input_path, 'r') as fin, open(output_path, 'w') as fout:
        for line in fin:
            line = line.strip()
            if not line:
                continue
            total += 1


            # Hash the normalized JSON to catch formatting differences
            data = json.loads(line)
            canonical = json.dumps(data, sort_keys=True)
            content_hash = hashlib.sha256(canonical.encode()).hexdigest()


            if content_hash not in seen_hashes:
                seen_hashes.add(content_hash)
                fout.write(json.dumps(data) + '\n')
                unique += 1


    duplicates = total - unique
    print(f'Total: {total}, Unique: {unique}, Removed: {duplicates}')
    return {'total': total, 'unique': unique, 'duplicates': duplicates}


deduplicate_jsonl('training.jsonl', 'training_deduped.jsonl')

Preparação de dados em larga escala

Datasets usados para treinar modelos em produção costumam conter centenas de milhares ou milhões de exemplos. Nessa escala, você precisa de pipelines automatizados para embaralhar, dividir e fragmentar seus dados JSONL. Uma preparação adequada evita problemas de treinamento, como o esquecimento catastrófico, e garante experimentos reproduzíveis.

Este script embaralha os dados aleatoriamente e os divide em conjuntos de treino e teste. Embaralhar os dados é fundamental porque os arquivos JSONL costumam ser gerados em uma sequência ordenada, e treinar com dados nessa ordem pode prejudicar a capacidade de generalização do modelo.

Pipeline de embaralhamento e divisão em conjuntos de treino e teste
import json
import random
from pathlib import Path


def prepare_training_data(
    input_path: str,
    output_dir: str,
    test_ratio: float = 0.1,
    seed: int = 42
) -> dict:
    """Shuffle and split JSONL into train/test sets."""
    random.seed(seed)
    output = Path(output_dir)
    output.mkdir(parents=True, exist_ok=True)


    # Load all examples
    examples = []
    with open(input_path, 'r') as f:
        for line in f:
            line = line.strip()
            if line:
                examples.append(json.loads(line))


    # Shuffle
    random.shuffle(examples)


    # Split
    split_idx = int(len(examples) * (1 - test_ratio))
    train_data = examples[:split_idx]
    test_data = examples[split_idx:]


    # Write output files
    train_path = output / 'train.jsonl'
    test_path = output / 'test.jsonl'


    for data, path in [(train_data, train_path), (test_data, test_path)]:
        with open(path, 'w') as f:
            for example in data:
                f.write(json.dumps(example) + '\n')


    print(f'Train: {len(train_data)} examples -> {train_path}')
    print(f'Test:  {len(test_data)} examples -> {test_path}')
    return {'train': len(train_data), 'test': len(test_data)}


prepare_training_data(
    'all_examples.jsonl',
    './prepared_data/',
    test_ratio=0.1,
    seed=42
)

Quando os datasets são grandes demais para um único arquivo ou você precisa distribuir o treinamento entre várias GPUs, divida o arquivo JSONL em fragmentos menores. Cada fragmento pode ser processado de forma independente.

Fragmentação de arquivos para treinamento distribuído
import json
from pathlib import Path


def shard_jsonl(
    input_path: str,
    output_dir: str,
    shard_size: int = 50000
) -> int:
    """Split a large JSONL file into smaller shards."""
    output = Path(output_dir)
    output.mkdir(parents=True, exist_ok=True)


    shard_num = 0
    line_count = 0
    current_file = None


    with open(input_path, 'r') as fin:
        for line in fin:
            line = line.strip()
            if not line:
                continue


            if line_count % shard_size == 0:
                if current_file:
                    current_file.close()
                shard_path = output / f'shard_{shard_num:04d}.jsonl'
                current_file = open(shard_path, 'w')
                shard_num += 1


            current_file.write(line + '\n')
            line_count += 1


    if current_file:
        current_file.close()


    print(f'Created {shard_num} shards from {line_count} examples')
    return shard_num


shard_jsonl('large_dataset.jsonl', './shards/', shard_size=50000)

Pronto para preparar seus dados de treinamento?

Valide, formate e inspecione seus arquivos JSONL de treinamento diretamente no navegador. Sem uploads, sem cadastro, 100% privado.

Perguntas frequentes

Referências