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

Formato de dados: conversas em JSONL

Aula 3 de 16 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. O formato JSONL
  2. Estrutura da conversa
  3. Conversas multi-turno
  4. Ponderação com weight
  5. Script de criação de ficheiro JSONL
  6. Pontos-chave

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 user e uma mensagem assistant
  • A mensagem system é opcional, mas recomendada para consistência
  • Utilize weight: 0 para excluir certos turnos do treino em conversas multi-turno
  • Valide sempre o seu ficheiro JSONL antes de fazer o upload