Versionamento e Reversão
Nesta página
Atualização de 2 de novembro de 2026 — Disponibilidade do fine-tuning. O fine-tuning de autosserviço da OpenAI está a ser descontinuado: desde 7 de maio de 2026, as organizações que nunca o utilizaram já não podem criar tarefas; 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á lançar novas tarefas. Os modelos já treinados permanecem utilizáveis até que o seu modelo base seja desativado. Este curso continua a ser útil para compreender e aproveitar um modelo existente; para novos projetos, priorize a engenharia de prompts, o RAG e as avaliações.
Por que versionar os seus modelos
Em produção, irá iterar sobre o seu modelo ajustado: novos dados, hiperparâmetros ajustados, novo modelo base. Sem um sistema de versionamento rigoroso, perderá a rastreabilidade e a capacidade de reverter em caso de regressão. O cenário é sempre o mesmo: numa segunda-feira de manhã, o feedback dos utilizadores deteriora-se, ninguém sabe qual o modelo que está realmente em execução nem quais os dados que o produziram, e a equipa passa o dia a reconstruir informações que um ficheiro de poucas linhas teria preservado.
Nomear versões
O parâmetro suffix da tarefa de fine-tuning é a sua primeira ferramenta de rastreabilidade: a cadeia de caracteres que lá colocar acabará no ID final do modelo e permanecerá legível em todo o lado — nos seus registos, na sua configuração, na sua consola. Adote uma convenção e mantenha-a.
# Convenção: {nome}-v{versão_maior}.{versão_menor}
job = client.fine_tuning.jobs.create(
training_file=training_file.id,
model="gpt-5.6-luna",
suffix="support-client-v2.1"
)
O número em si deve transportar informação, não apenas contar tentativas. Uma versão maior muda quando a natureza do modelo muda; uma versão menor, quando melhora sem quebrar funcionalidades. Concretamente, uma correção de dados aplicada com os mesmos hiperparâmetros mantém-se na mesma versão maior, enquanto uma mudança de modelo base exige o início de uma nova.
| Versão | O que sinaliza |
|---|---|
| v1.0 | Primeiro modelo validado em produção |
| v1.1 | Correção de dados (mesmos hiperparâmetros) |
| v2.0 | Mudança de modelo base ou estratégia |
| v2.1 | Ajuste de hiperparâmetros |
Manter um registo de modelos
O nome por si só não basta: não diz nada sobre o que estava no conjunto de dados, os resultados obtidos ou por que razão esta versão foi promovida. Um registo centralizado mantém estes metadados juntamente com o ID técnico e torna-se a fonte única de verdade da sua equipa. A classe abaixo mantém o essencial num ficheiro JSON: regista um modelo candidato, promove um para produção marcando o anterior como desativado, devolve o ID atualmente ativo e exibe o histórico. Dedique tempo a preencher o campo notes: uma única frase sobre o que mudou desde a versão anterior poupar-lhe-á meio dia de arqueologia mais tarde.
import json
import datetime
class ModelRegistry:
"""Registo de modelos ajustados (fine-tuned)."""
def __init__(self, path: str = "model_registry.json"):
self.path = path
try:
with open(path, "r") as f:
self.registry = json.load(f)
except FileNotFoundError:
self.registry = {"models": [], "production": None}
def record(
self,
version: str,
model_id: str,
job_id: str,
dataset_info: dict,
hyperparams: dict,
metrics: dict,
notes: str = ""
):
"""Regista um novo modelo no registo."""
entry = {
"version": version,
"model_id": model_id,
"job_id": job_id,
"date": datetime.datetime.now().isoformat(),
"dataset": dataset_info,
"hyperparameters": hyperparams,
"metrics": metrics,
"notes": notes,
"status": "candidate"
}
self.registry["models"].append(entry)
self._save()
print(f"Modelo {version} registado: {model_id}")
def promote(self, version: str):
"""Promove um modelo para produção."""
old = self.registry["production"]
for m in self.registry["models"]:
if m["version"] == version:
m["status"] = "production"
self.registry["production"] = version
break
if old:
for m in self.registry["models"]:
if m["version"] == old:
m["status"] = "retired"
self._save()
print(f"Produção: {old} -> {version}")
def rollback(self, version: str):
"""Reverte para uma versão anterior."""
self.promote(version)
print(f"Reversão efetuada para {version}")
def production_model(self) -> str:
"""Devolve o ID do modelo em produção."""
version = self.registry["production"]
for m in self.registry["models"]:
if m["version"] == version:
return m["model_id"]
return None
def history(self):
"""Exibe o histórico do modelo."""
print(f"{'Versão':<12} {'Estado':<12} {'Data':<12} {'Val Loss':<10}")
print("-" * 50)
for m in self.registry["models"]:
date = m["date"][:10]
loss = m["metrics"].get("validation_loss", "N/A")
print(f"{m['version']:<12} {m['status']:<12} {date:<12} {loss}")
def _save(self):
with open(self.path, "w") as f:
json.dump(self.registry, f, indent=2, ensure_ascii=False)
Na prática, o ciclo de vida de uma versão resume-se a três chamadas: regista o modelo resultante do treino com os seus números, promove-o quando a avaliação o valida e reverte para a versão anterior se a produção contradisser a avaliação. Esta última linha deve ser tão trivial de escrever como as duas primeiras.
registry = ModelRegistry()
# Registar um novo modelo
registry.record(
version="v2.1",
model_id="ft:gpt-5.6-luna:org::support-v2.1:abc123",
job_id="ftjob-xyz789",
dataset_info={"train": 350, "validation": 45},
hyperparams={"n_epochs": 3, "lr": "auto"},
metrics={"validation_loss": 0.38, "precision_test": 0.93},
notes="Adicionados 50 exemplos de correção para reembolsos"
)
# Promover para produção
registry.promote("v2.1")
# Em caso de problemas, reverter
registry.rollback("v2.0")
Reverter em segundos
Uma reversão só tem valor se for rápida e não exigir reflexão. Como a sua aplicação lê o nome do modelo a partir de uma variável de ambiente, mudar de versão significa alterar essa variável e atualizar o registo — sem nova implementação de código, sem recompilação. A função quick_rollback vai mais longe, contornando totalmente a escolha humana: seleciona a última versão estável disponível e, se nenhuma existir, recua para o modelo base. Este último ramo é a sua rede de segurança absoluta; acione-o voluntariamente uma vez num ambiente de teste, enquanto as apostas são zero.
import os
def deploy_model(version: str, registry: ModelRegistry):
"""Implementa um modelo atualizando a variável de ambiente."""
model_id = None
for m in registry.registry["models"]:
if m["version"] == version:
model_id = m["model_id"]
break
if not model_id:
raise ValueError(f"Versão {version} não encontrada")
# Atualizar configuração
os.environ["OPENAI_FT_MODEL"] = model_id
registry.promote(version)
print(f"Modelo implementado: {version} ({model_id})")
return model_id
def quick_rollback(registry: ModelRegistry):
"""Reverte para a última versão estável."""
production = registry.registry["production"]
versions = [
m for m in registry.registry["models"]
if m["version"] != production and m["status"] != "retired"
]
if not versions:
# Recurso ao modelo base
os.environ["OPENAI_FT_MODEL"] = "gpt-5.6-luna"
print("Reversão para o modelo base")
return
last_stable = versions[-1]
deploy_model(last_stable["version"], registry)
Arquivar os dados, não apenas os modelos
Versionar um modelo sem versionar o que o produziu leva-o apenas até meio caminho. No dia em que quiser entender por que razão a v2.1 manteve melhor o tom do que a v2.2, precisará exatamente dos três ficheiros usados para o treinar, incluindo o conjunto de teste — sem isso, nenhuma comparação subsequente é justa. Arquive-os numa pasta com o número da versão, no exato momento em que regista o modelo.
import shutil
def archive_dataset(version: str, files: list[str], archive_folder: str):
"""Arquiva dados de treino para uma determinada versão."""
folder = f"{archive_folder}/{version}"
os.makedirs(folder, exist_ok=True)
for file in files:
shutil.copy2(file, folder)
print(f"Dados arquivados em {folder}")
archive_dataset(
"v2.1",
["train.jsonl", "validation.jsonl", "test.jsonl"],
"archives/datasets"
)
Automatizar o pipeline completo
Estes passos, executados manualmente, acabam por ser ignorados — especialmente o arquivamento, que vem por último e não bloqueia nada. Agrupe-os num único script que encadeie o upload de ficheiros, o lançamento da tarefa, a espera pela conclusão, o registo no registo e, finalmente, o arquivamento dos dados. O ciclo de espera consulta a tarefa a cada trinta segundos e para num estado terminal; em caso de falha, a função retorna imediatamente em vez de continuar com um modelo inexistente.
def deployment_pipeline(
training_file: str,
validation_file: str,
version: str,
base_model: str = "gpt-5.6-luna",
hyperparams: dict = None
):
"""Pipeline completo: upload, treino, avaliação, registo."""
client = OpenAI()
registry = ModelRegistry()
# 1. Upload
print("A carregar dados...")
train = client.files.create(file=open(training_file, "rb"), purpose="fine-tune")
val = client.files.create(file=open(validation_file, "rb"), purpose="fine-tune")
# 2. Treino
print("A lançar fine-tuning...")
params = {"training_file": train.id, "validation_file": val.id,
"model": base_model, "suffix": version}
if hyperparams:
params["hyperparameters"] = hyperparams
job = client.fine_tuning.jobs.create(**params)
# 3. Aguardar conclusão
import time
while True:
job = client.fine_tuning.jobs.retrieve(job.id)
if job.status in ("succeeded", "failed"):
break
time.sleep(30)
if job.status == "failed":
print(f"Falha: {job.error}")
return None
# 4. Registar
registry.record(
version=version,
model_id=job.fine_tuned_model,
job_id=job.id,
dataset_info={"train": training_file, "validation": validation_file},
hyperparams=hyperparams or {},
metrics={"trained_tokens": job.trained_tokens}
)
# 5. Arquivar dados
archive_dataset(version, [training_file, validation_file], "archives/datasets")
print(f"Pipeline concluído: {job.fine_tuned_model}")
return job.fine_tuned_model
Limpeza
Os modelos ajustados são armazenados na OpenAI e podem ser eliminados quando já não forem necessários. Após uma dúzia de iterações, a lista torna-se ilegível e a triagem manual perigosa. A limpeza automática abaixo mantém as três versões mais recentes e nunca toca na que está em execução em produção. Evite ser demasiado agressivo: é precisamente a penúltima versão, muitas vezes considerada inútil, que o salvará durante uma reversão.
def clean_old_models(registry: ModelRegistry, keep: int = 3):
"""Elimina modelos antigos mantendo os últimos N."""
models = registry.registry["models"]
production = registry.registry["production"]
candidates = [
m for m in models
if m["version"] != production
]
to_delete = candidates[:-keep] if len(candidates) > keep else []
for m in to_delete:
try:
client.models.delete(m["model_id"])
print(f"Eliminado: {m['version']} ({m['model_id']})")
except Exception as e:
print(f"Erro ao eliminar {m['version']}: {e}")
Pontos-chave
- Utilize sufixos versionados para identificar cada modelo
- Mantenha um registo centralizado com métricas e metadados
- Implemente um mecanismo de reversão rápida
- Arquive os dados de treino com cada versão
- Automatize o pipeline e limpe regularmente os modelos antigos: menos erros humanos, menos custos desnecessários
Teste os seus conhecimentos
Antes de versionar os seus modelos, valide o ciclo completo de fine-tuning.
1. Quando é que o fine-tuning é a ferramenta certa — e quando não é?
Resposta: Bom para ancorar um estilo, formato ou comportamento recorrente que o prompting não consegue alcançar de forma fiável; mau para injetar conhecimento novo — essa é a função do RAG.
2. O que torna um conjunto de dados de treino de alta qualidade?
Resposta: Exemplos limpos, consistentes e representativos em formato JSONL conversacional: algumas centenas de exemplos excelentes valem mais do que milhares de exemplos ruidosos.
3. O que traz o DPO em comparação com o fine-tuning supervisionado?
Resposta: Aprendizagem por preferência: fornece pares de respostas preferidas/rejeitadas e o modelo aprende o “melhor” em vez de uma simples imitação — útil para o tom e compromissos finos.
4. Como valida um modelo ajustado (fine-tuned)?
Resposta: Comparando-o com o modelo base num conjunto de avaliação mantido separado do treino e, em seguida, através de testes A/B em métricas de negócio — nunca apenas com base na impressão.
5. Por que versionar e planear a reversão?
Resposta: Cada fine-tuning produz um modelo datado: em caso de regressão em produção, volta imediatamente para a versão anterior — o modelo é gerido como código.
Dados limpos, avaliação honesta, versões controladas: o fine-tuning é uma disciplina de engenharia — este curso deu-lhe o ciclo completo.