Formato de dados: conversas em JSONL
Nesta página
Atualização de 2 de novembro de 2026 — Disponibilidade do fine-tuning. O serviço de fine-tuning self-service da OpenAI está a ser descontinuado: desde 7 de maio de 2026, as organizações que nunca o utilizaram já não podem criar jobs; desde 2 de julho, é necessário ter utilizado um modelo com fine-tuning nos últimos 60 dias; e a partir de 6 de janeiro de 2027, nenhum cliente poderá lançar novos jobs. Os modelos já treinados permanecem utilizáveis até que o seu modelo base seja desativado. Este curso mantém a sua utilidade para compreender e aproveitar um modelo existente; para novos projetos, priorize a engenharia de prompts, RAG e avaliações.
O formato JSONL
O JSONL (JSON Lines) é o formato exigido pela API de fine-tuning da OpenAI. Cada linha do ficheiro é um objeto JSON independente que representa um exemplo de treino completo. Esta estrutura permite transmitir em streaming um corpus de dezenas de milhares de exemplos sem nunca carregar o ficheiro inteiro na memória.
{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}
{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}
Regra fundamental: uma linha = um objeto JSON = um exemplo. Não inclua quebras de linha dentro do próprio objeto JSON. Por outras palavras, o JSON formatado com indentação («pretty-printed») do seu editor irá corromper o ficheiro — esta é a causa mais comum de rejeição no upload.
Estrutura da conversa
Cada exemplo é um objeto com uma chave messages que contém um array de mensagens. Cada mensagem possui um role e um content. Apenas três funções (roles) são aceites:
- system: instruções globais para o assistente (opcional, mas recomendado)
- user: a mensagem do utilizador
- assistant: a resposta que o modelo deve aprender a produzir
O formato mínimo consiste numa única troca entre utilizador e assistente. Isto é suficiente quando o comportamento desejado não depende de um enquadramento específico, como no caso de um modelo dedicado a uma única tarefa.
{
"messages": [
{"role": "user", "content": "Olá, como está?"},
{"role": "assistant", "content": "Olá! Estou pronto para ajudar. O que posso fazer por si?"}
]
}
Assim que o modelo necessite de adotar um papel específico, adicione uma mensagem de sistema — e mantenha-a idêntica em todos os seus exemplos. Note no exemplo abaixo que a instrução «oferecer sempre uma demonstração» é efetivamente cumprida na resposta do assistente: a mensagem de sistema descreve uma restrição, e o exemplo mostra como ela se aplica na prática.
{
"messages": [
{
"role": "system",
"content": "É um assistente de vendas da TechCorp. Responda de forma concisa e profissional. Ofereça sempre uma demonstração."
},
{
"role": "user",
"content": "Procuro uma solução de CRM para a minha equipa de 50 pessoas."
},
{
"role": "assistant",
"content": "O nosso CRM TechCorp foi concebido para equipas de 20 a 200 pessoas, com gestão de contactos, pipeline de vendas e relatórios integrados. Para uma equipa de 50, recomendo o plano Business a 29€/utilizador/mês. Gostaria de agendar uma demonstração personalizada esta semana?"
}
]
}
Conversas multi-turno
Pode incluir conversas com múltiplas trocas. O modelo aprende então a manter a consistência ao longo dos turnos: aqui, a segunda resposta constrói sobre o passo 2 anunciado no primeiro, algo que um exemplo isolado não conseguiria ensinar.
{
"messages": [
{
"role": "system",
"content": "É um assistente técnico para uma API de pagamentos."
},
{
"role": "user",
"content": "Como integro a vossa API de pagamentos?"
},
{
"role": "assistant",
"content": "A integração ocorre em 3 passos: 1) Instale o SDK com pip install paycorp-sdk, 2) Configure a sua chave de API, 3) Crie o seu primeiro pagamento. Com qual passo gostaria de começar?"
},
{
"role": "user",
"content": "Como configuro a chave de API?"
},
{
"role": "assistant",
"content": "Obtenha a sua chave no dashboard (Settings > API Keys) e configure-a no seu código:\n\nfrom paycorp import PayCorp\nclient = PayCorp(api_key=\"your_key\")\n\nUtilize a chave de teste (prefixo sk_test_) em desenvolvimento e a chave de produção (sk_live_) em produção. Nunca faça commit das suas chaves no código fonte."
}
]
}
Ponderação com weight
Pode indicar ao modelo quais as mensagens do assistente mais importantes adicionando um campo weight:
{
"messages": [
{"role": "user", "content": "Resuma este documento."},
{"role": "assistant", "content": "Eis o resumo...", "weight": 1}
]
}
Um weight de 0 significa que o modelo não será treinado com essa mensagem específica do assistente; o valor padrão é 1. O caso de uso típico são conversas multi-turno onde apenas o turno final importa: mantém as trocas anteriores porque fornecem o contexto necessário, mas não quer que o modelo aprenda a reproduzi-las — basta defini-las como 0.
Script de criação de ficheiro JSONL
Na prática, nunca escreverá este ficheiro manualmente. A função abaixo serializa uma lista de exemplos e protege-o das duas armadilhas mais comuns: esquecer a quebra de linha final e mishandling do escape de acentos.
import json
def create_jsonl_file(examples: list[dict], path: str):
"""Creates a JSONL file from a list of examples."""
with open(path, "w", encoding="utf-8") as f:
for example in examples:
line = json.dumps(example, ensure_ascii=False)
f.write(line + "\n")
print(f"File created: {path} ({len(examples)} examples)")
# Your examples
examples = [
{
"messages": [
{"role": "system", "content": "Assistente de apoio ao cliente da TechCorp."},
{"role": "user", "content": "A minha conta está bloqueada."},
{"role": "assistant", "content": "Compreendo a sua frustração. Para desbloquear a sua conta, preciso do seu endereço de e-mail de registo. Vou verificar o estado e guiá-lo no processo de reativação."}
]
},
{
"messages": [
{"role": "system", "content": "Assistente de apoio ao cliente da TechCorp."},
{"role": "user", "content": "Como altero a minha palavra-passe?"},
{"role": "assistant", "content": "Para alterar a palavra-passe: vá a Settings > Security > Change Password. Introduza a sua palavra-passe atual e, em seguida, a nova (mínimo de 12 caracteres, com maiúscula, número e caráter especial). Confirme e clique em Save."}
]
}
]
create_jsonl_file(examples, "training_data.jsonl")
Os erros que encontrará são sempre os mesmos e todos podem ser detetados antes do upload. A falta de uma quebra de linha entre dois objetos funde dois exemplos numa única linha ilegível. Um JSON mal formado — aspas em falta, vírgula a mais — falha a linha inteira. Um content vazio desencadeia um erro de validação no lado da OpenAI, tal como uma função (role) inventada: apenas system, user e assistant são aceites. Finalmente, escreva sempre em UTF-8 com ensure_ascii=False, caso contrário, os seus caracteres acentuados transformar-se-ão em sequências de escape que o modelo aprenderá conscientemente a reproduzir.
Pontos-chave
- Uma linha JSONL = um objeto JSON = uma conversa completa
- Cada conversa contém pelo menos uma mensagem
usere uma mensagemassistant - A mensagem
systemé opcional, mas recomendada para consistência - Utilize
weight: 0para excluir certos turnos do treino em conversas multi-turno - Valide sempre o seu ficheiro JSONL antes de fazer o upload