Iniciar o Ajuste Fino através da API
Nesta página
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 dados | Duração do treino |
|---|---|
| 50 exemplos | Alguns minutos |
| 500 exemplos | 15 a 30 minutos |
| 5.000 exemplos | 1 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
suffixdescritivo 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