Qualidade dos Dados: Limpeza e Validação
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 executaram um trabalho de fine-tuning já não podem criar um; desde 2 de julho, é necessário ter utilizado um modelo ajustado nos últimos 60 dias; e a partir de 6 de janeiro de 2027, nenhum cliente poderá iniciar novos trabalhos. 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, a RAG e as avaliações.
Por que a limpeza é crítica
Um ficheiro JSONL tecnicamente válido não garante um bom fine-tuning. Dados ruidosos, inconsistentes ou mal formatados degradam o desempenho do modelo em vez de o melhorar — e o pior é que não geram qualquer erro. O trabalho será concluído com sucesso, o modelo ficará pronto e só descobrirá o problema em produção. Esta lição abrange as técnicas de limpeza e validação que deve executar antes do carregamento.
Validação técnica do ficheiro
Comece pela mecânica: verifique se o seu ficheiro está sintaticamente correto e se cada linha respeita o contrato esperado. A função abaixo percorre o ficheiro linha por linha, acumulando erros em vez de parar no primeiro (precisa da lista completa, não de idas e voltas para cada problema) e devolve estatísticas úteis pelo caminho, como a presença de mensagens de sistema e conversas multi-turno.
import json
def validate_jsonl(path: str) -> dict:
"""Validates a JSONL file and returns statistics."""
errors = []
stats = {"total": 0, "with_system": 0, "multi_turn": 0}
valid_roles = {"system", "user", "assistant"}
with open(path, "r", encoding="utf-8") as f:
for i, line in enumerate(f, 1):
stats["total"] += 1
try:
obj = json.loads(line.strip())
except json.JSONDecodeError as e:
errors.append(f"Line {i}: Invalid JSON — {e}")
continue
if "messages" not in obj:
errors.append(f"Line {i}: Missing 'messages' key")
continue
messages = obj["messages"]
if not isinstance(messages, list) or len(messages) < 2:
errors.append(f"Line {i}: Minimum 2 messages required")
continue
for j, msg in enumerate(messages):
role = msg.get("role")
if role not in valid_roles:
errors.append(f"Line {i}, msg {j}: Invalid role")
if not msg.get("content", "").strip():
errors.append(f"Line {i}, msg {j}: Empty content")
if not any(m["role"] == "assistant" for m in messages):
errors.append(f"Line {i}: No assistant message")
if messages[0]["role"] == "system":
stats["with_system"] += 1
user_turns = sum(1 for m in messages if m["role"] == "user")
if user_turns > 1:
stats["multi_turn"] += 1
return {"errors": errors, "stats": stats}
result = validate_jsonl("training_data.jsonl")
if result["errors"]:
print(f"Errors: {len(result['errors'])}")
for err in result["errors"][:10]:
print(f" - {err}")
else:
print(f"File valid — {result['stats']['total']} examples")
Limpeza de conteúdo
Entradas exatas ou quase duplicadas enviesam o treino ao sobre-representar certos padrões. Isto acontece naturalmente quando agrega várias exportações: a mesma pergunta frequente aparece trinta vezes nos seus registos e o modelo conclui que merece trinta vezes mais atenção do que as outras. Um hash do conteúdo concatenado das mensagens é suficiente para as eliminar.
import hashlib
def deduplicate(examples: list[dict]) -> list[dict]:
"""Removes duplicates based on message content."""
seen = set()
unique = []
for ex in examples:
content = "|".join(
f"{m['role']}:{m['content']}" for m in ex["messages"]
)
h = hashlib.md5(content.encode()).hexdigest()
if h not in seen:
seen.add(h)
unique.append(ex)
print(f"Duplicates removed: {len(examples) - len(unique)}")
return unique
Segue-se a normalização do texto, que resolve quatro problemas distintos. Múltiplos espaços e quebras de linha supérfluas, herdadas de copiar e colar, devem ser removidas. A codificação deve ser normalizada para UTF-8 com os caracteres de controlo removidos — invisíveis, mas frequentemente presentes em exportações de bases de dados. A pontuação merece verificação: uma resposta truncada a meio ensina o modelo a interromper-se a si próprio. Por fim, garanta a consistência do idioma — se deseja um tratamento formal, verifique se nenhum exemplo usa tratamento informal, pois o modelo reproduzirá fielmente a mistura.
import re
import unicodedata
def normalize_text(text: str) -> str:
"""Normalizes text for training."""
text = unicodedata.normalize("NFC", text)
text = re.sub(r"[\x00-\x09\x0b-\x0c\x0e-\x1f\x7f]", "", text)
text = re.sub(r"[ \t]+", " ", text)
text = re.sub(r"\n{3,}", "\n\n", text)
return text.strip()
Verificações de consistência
Se utilizar uma mensagem de sistema, esta deve ser rigorosamente idêntica em todos os seus exemplos. Duas variantes que diferem por apenas uma palavra são suficientes para diluir o sinal: o modelo deixa de aprender uma instrução específica e começa a aprender uma família difusa de instruções. A verificação é trivial e o resultado é frequentemente surpreendente num corpus construído por várias pessoas.
def check_system_messages(examples: list[dict]):
"""Checks consistency of system messages."""
system_msgs = set()
for ex in examples:
for msg in ex["messages"]:
if msg["role"] == "system":
system_msgs.add(msg["content"].strip())
if len(system_msgs) > 1:
print(f"Warning: {len(system_msgs)} different system messages")
for sm in system_msgs:
print(f" - {sm[:80]}...")
elif len(system_msgs) == 1:
print("System message consistent")
else:
print("No system message used")
A distribuição dos comprimentos das respostas conta a mesma história sob outro ângulo. Respostas altamente heterogéneas sinalizam que várias pessoas escreveram o corpus com ideias diferentes do que constitui uma boa resposta, ou que um valor atípico se infiltrou no lote. O limiar aqui utilizado — um máximo superior a cinco vezes a média — não é absoluto, mas atrai a sua atenção para o local certo.
def analyze_lengths(examples: list[dict]):
"""Analyzes the distribution of response lengths."""
lengths = []
for ex in examples:
for msg in ex["messages"]:
if msg["role"] == "assistant":
lengths.append(len(msg["content"]))
if lengths:
avg = sum(lengths) / len(lengths)
mini, maxi = min(lengths), max(lengths)
print(f"Response length — Avg: {avg:.0f} | Min: {mini} | Max: {maxi}")
if maxi > avg * 5:
print("High dispersion — check for outliers")
Utilização da API de validação da OpenAI
Depois de executar as suas próprias verificações, carregue o ficheiro e deixe a OpenAI validá-lo também. É gratuito, imediato e poupa-o de descobrir um problema de formato quando o trabalho iniciar.
from openai import OpenAI
client = OpenAI()
file = client.files.create(
file=open("training_data.jsonl", "rb"),
purpose="fine-tune"
)
print(f"File uploaded: {file.id}")
print(f"Status: {file.status}")
Se o ficheiro contiver erros, o estado mudará para error com uma mensagem detalhada. Corrija os problemas reportados antes de tentar novamente.
Lista de verificação pré-fine-tuning
Percorra esta lista por ordem antes de criar o trabalho — cada item corresponde a uma verificação abordada acima, exceto o último, que nenhum script pode substituir:
- O ficheiro JSONL é sintaticamente válido
- Sem duplicados
- Texto normalizado (UTF-8, espaços, pontuação)
- Mensagens de sistema consistentes
- Pelo menos 50 exemplos (idealmente 100+)
- Divisão treino/validação realizada
- Distribuição razoável de comprimentos
- Revisão humana de uma amostra aleatória
Pontos-chave
- Valide sempre a sintaxe JSONL antes de carregar
- Remova duplicados para evitar sobreajuste
- A consistência da mensagem de sistema é essencial
- Verifique a distribuição dos comprimentos das respostas
- Peça a um humano que reveja uma amostra — é insubstituível