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

Versionamento e Reversão

Aula 16 de 16 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. Por que versionar os seus modelos
  2. Nomear versões
  3. Manter um registo de modelos
  4. Reverter em segundos
  5. Arquivar os dados, não apenas os modelos
  6. Automatizar o pipeline completo
  7. Limpeza
  8. Pontos-chave
  9. Teste os seus conhecimentos

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ãoO que sinaliza
v1.0Primeiro modelo validado em produção
v1.1Correção de dados (mesmos hiperparâmetros)
v2.0Mudança de modelo base ou estratégia
v2.1Ajuste 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.