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

Iniciar o Ajuste Fino através da API

Aula 5 de 16 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. Visão Geral do Processo
  2. Instalar e Configurar o SDK
  3. Carregar Ficheiros
  4. Criar a Tarefa de Ajuste Fino
  5. Acompanhar o Progresso
  6. Utilizar o Modelo Ajustado
  7. Gerir as Suas Tarefas
  8. Custos e Duração
  9. Pontos-chave

Atualização de 2 de novembro de 2026 — Disponibilidade do ajuste fino. O serviço de ajuste fino self-service da OpenAI está a ser descontinuado: desde 7 de maio de 2026, as organizações que nunca executaram uma tarefa de ajuste fino não podem criar novas; 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 novas tarefas. 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.

Visão Geral do Processo

Os seus dados estão prontos, validados e divididos em conjuntos de treino e de validação. A etapa real de treino resume-se a três ações: carregar o ficheiro de dados, criar uma tarefa de ajuste fino e aguardar a conclusão do treino. Tudo ocorre através do SDK oficial para Python, e verá que o código cabe em cerca de trinta linhas — a maior parte do trabalho foi feita anteriormente.

Instalar e Configurar o SDK

O cliente é instanciado sem argumentos: lê automaticamente a variável de ambiente OPENAI_API_KEY.

# Instalação
# pip install openai

from openai import OpenAI

# O cliente utiliza automaticamente a variável de ambiente OPENAI_API_KEY
client = OpenAI()

Certifique-se de que esta variável está definida antes de executar o script; caso contrário, a instanciação falhará no primeiro pedido. Em produção, nunca codifique a sua chave diretamente no código: uma chave escrita em texto simples acaba no histórico do Git, e removê-la depois do facto é muito mais dispendioso do que lê-la a partir do ambiente desde o primeiro dia.

Carregar Ficheiros

O carregamento utiliza purpose="fine-tune", o que informa a OpenAI de que o ficheiro se destina ao treino e aciona as verificações de formato correspondentes. Carregue o ficheiro de validação de imediato: tecnicamente é opcional, mas sem ele o treino corre às cegas, uma vez que nenhuma perda de validação sinalizará sobreajuste enquanto a tarefa estiver em execução.

# Carregar ficheiro de treino
training_file = client.files.create(
    file=open("training_data.jsonl", "rb"),
    purpose="fine-tune"
)

print(f"ID do Ficheiro: {training_file.id}")
print(f"Estado: {training_file.status}")

# Opcional: carregar ficheiro de validação
validation_file = client.files.create(
    file=open("validation_data.jsonl", "rb"),
    purpose="fine-tune"
)

print(f"ID de Validação: {validation_file.id}")

O ficheiro passa por uma fase de processamento no lado da OpenAI. Aguarde até que o estado seja processed antes de iniciar a tarefa: uma tarefa criada num ficheiro ainda em processamento falhará, e perderá alguns minutos à procura de uma causa inexistente no seu JSONL.

Criar a Tarefa de Ajuste Fino

job = client.fine_tuning.jobs.create(
    training_file=training_file.id,
    validation_file=validation_file.id,  # opcional mas recomendado
    model="gpt-5.6-luna",  # ou "gpt-5.6-luna"
    suffix="my-assistant-v1"  # sufixo para identificar o seu modelo
)

print(f"ID da Tarefa: {job.id}")
print(f"Estado: {job.status}")
print(f"Modelo base: {job.model}")

O parâmetro suffix é anexado ao nome do seu modelo ajustado: com "my-assistant-v1", o modelo resultante será nomeado ft:gpt-5.6-luna:your-org::my-assistant-v1:xxxxxxxx. Adquira o hábito de colocar aí o caso de uso e um número de versão. No dia em que três modelos coexistirem na sua conta, essa será a única forma de saber qual faz o quê sem abrir a consola.

Acompanhar o Progresso

Uma tarefa passa por vários estados em sequência, e retrieve fornece-lhe o estado atual a qualquer momento.

# Obter estado da tarefa
job = client.fine_tuning.jobs.retrieve(job.id)
print(f"Estado: {job.status}")
# Estados possíveis: validating_files, queued, running, succeeded, failed, cancelled

O estado por si só permanece lacónico. Os eventos, por outro lado, contam a história: validação do ficheiro, início, progresso passo a passo, fim.

# Ver eventos da tarefa
events = client.fine_tuning.jobs.list_events(
    fine_tuning_job_id=job.id,
    limit=20
)

for event in events.data:
    print(f"[{event.created_at}] {event.message}")

Em vez de chamar retrieve manualmente a cada cinco minutos, envolva a espera num ciclo que devolva o controlo assim que a tarefa atingir um estado terminal. Note que os três casos de saída são tratados separadamente: uma tarefa cancelada não é uma tarefa falhada, e quererá distingui-las nos seus registos.

import time

def track_job(client: OpenAI, job_id: str, interval: int = 30):
    """Acompanha uma tarefa de ajuste fino até à conclusão."""
    while True:
        job = client.fine_tuning.jobs.retrieve(job_id)
        print(f"Estado: {job.status}")

        if job.status == "succeeded":
            print(f"Modelo ajustado: {job.fine_tuned_model}")
            return job

        if job.status == "failed":
            print(f"Falha: {job.error}")
            return job

        if job.status == "cancelled":
            print("Tarefa cancelada.")
            return job

        time.sleep(interval)

# Utilização
final_job = track_job(client, job.id)

Utilizar o Modelo Ajustado

Assim que a tarefa for concluída com sucesso, o seu modelo é chamado exatamente como um modelo padrão. Apenas o valor passado para model muda, o que significa que mudar para o seu modelo personalizado se resume, numa aplicação existente, a modificar uma variável de configuração.

response = client.responses.create(
    model=final_job.fine_tuned_model,  # ex.: "ft:gpt-5.6-luna:org::suffix:xxxxxxxx"
    input="Olá, tenho um problema com a minha encomenda."
)

print(response.output_text)

Gerir as Suas Tarefas

Duas chamadas são suficientes para administrar tudo: listar o que existe e interromper o que está em execução. O cancelamento é útil assim que o monitoramento mostra que o treino está a descarrilar — não vale a pena pagar por tokens de uma tarefa que já sabe que produzirá um mau modelo.

# Listar todas as suas tarefas de ajuste fino
jobs = client.fine_tuning.jobs.list(limit=10)
for j in jobs.data:
    print(f"{j.id} | {j.status} | {j.model} | {j.fine_tuned_model}")

# Cancelar uma tarefa em execução
client.fine_tuning.jobs.cancel(job.id)

Custos e Duração

O treino é faturado pelo número de tokens processados. A duração, por outro lado, depende do tamanho dos seus dados e do número de épocas.

Tamanho do conjunto de dadosDuração do treino
50 exemplosAlguns minutos
500 exemplos15 a 30 minutos
5.000 exemplos1 a 2 horas

Estas ordens de grandeza ajudam principalmente a dimensionar o seu ciclo de trabalho: com alguns minutos por execução, itera na mesma sessão; com duas horas, planeia. Os preços exatos variam consoante o modelo escolhido; consulte a página de preços da OpenAI para as tarifas atuais.

Pontos-chave

  • O fluxo de trabalho é: carregar ficheiro, criar tarefa, aguardar, utilizar o modelo
  • Adicione um suffix descritivo para identificar facilmente os seus modelos
  • Utilize sempre um ficheiro de validação para avaliar a qualidade
  • O modelo ajustado é utilizado exatamente como o modelo base através da API
  • Guarde os IDs das suas tarefas e modelos — precisará deles para o controlo de versões