Jobs de treinamento

Um job de treinamento faz o fine-tuning de um modelo base com os exemplos que você seleciona e produz um modelo que você pode hospedar, chamar e baixar. Projetos de geração de texto e de embeddings treinam pela mesma API: o tipo do projeto decide qual corpo POST .../training-jobs aceita, e todas as outras rotas (lista, detalhe, tentativas, logs, pausar, retomar, concluir, cancelar, tentar de novo, download) são compartilhadas e retornam o mesmo formato de job.

O treinamento roda em segundo plano. Você inicia um job, acompanha enquanto ele roda e usa o modelo quando model_available for true. Só o tempo de treinamento medido é cobrado; uma execução que nunca começa a treinar é gratuita.

GET  /api/v1/projects/{owner_slug}/{project_slug}/training-jobs
POST /api/v1/projects/{owner_slug}/{project_slug}/training-jobs
GET  /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/estimate-messages   text
GET  /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/profiles            embedding
POST /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/preview             embedding
POST /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/estimate            embedding
GET  /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}
POST /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/pause
POST /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/resume
POST /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/finish
POST /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/cancel
POST /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/retry
GET  /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/retry-estimate
GET  /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/attempts
GET  /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/attempts/{attempt_id}/logs
GET  /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/dataset
GET  /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/download

Cada campo de cada requisição e resposta está na referência da API. POST .../resume e POST .../retry exigem o cabeçalho Idempotency-Key: repetir a requisição com a mesma chave devolve o primeiro resultado em vez de iniciar uma segunda execução. A criação não garante idempotência; após uma resposta incerta, consulte a lista de jobs antes de enviar novamente.

A lista sempre retorna {data, next_cursor, total_count}, com um limit opcional (25 por padrão, no máximo 100). Passe cursor=<next_cursor> sem alterar para a próxima página. Não é necessário ativar um modo de paginação. Um cursor malformado ou de outro projeto responde 400.

Iniciar uma execução de geração de texto

Selecione chats por tag e escolha um modelo base:

{
  "dataset_tags": ["support-clean"],
  "model_name": "<catalog-model-id>",
  "max_seq_length": 2048,
  "num_train_epochs": 3
}

dataset_tags precisa nomear tags existentes exatamente. Várias tags selecionam a união dos seus chats, duplicatas são ignoradas, e uma lista vazia seleciona todos os chats do projeto. Uma tag desconhecida ou vazia responde training_dataset_selection_invalid; uma seleção vazia, training_dataset_empty; uma seleção sem texto treinável, training_dataset_unusable. São 422 na criação e 409 na nova tentativa, e nada é criado nem cobrado.

num_train_epochs é quantas passagens completas a execução faz pelos exemplos selecionados, e aceita frações (0.5 é meia passagem). O servidor converte em passos de treinamento a partir do tamanho da seleção e do formato do lote, e congela o resultado no job como planned_steps:

effective_batch_size = per_device_train_batch_size × gradient_accumulation_steps
steps_per_epoch      = ceil(train_examples / effective_batch_size)
planned_steps        = max(1, ceil(steps_per_epoch × num_train_epochs))

Por exemplo, 152 exemplos de treino com o lote efetivo padrão de 8 levam ceil(152 / 8) = 19 passos por época, ou 57 passos planejados para 3 épocas. Um último lote parcial ainda conta como um passo. max_steps (1 a 100) é a alternativa: um número fixo de passos. Envie um ou outro, nunca os dois.

Outras configurações que você pode enviar: system_prompt, learning_rate, lora_rank, lora_alpha, per_device_train_batch_size, gradient_accumulation_steps, loss_mask (assistant_only ou full_sequence), base_load_precision, warmup_steps, early_stopping_patience e as configurações de avaliação abaixo. Toda configuração omitida é preenchida pelo perfil de treinamento do modelo base e congelada com o job, então um job lido depois informa exatamente com o que rodou. Leia os modelos permitidos e o min, max, default de cada configuração, e se ela aceita frações (integer), em GET /api/v1/base-models em vez de copiá-los. Um valor recusado responde com um code e o field a que se refere.

system_prompt é uma instrução para o job inteiro, adicionada como primeira mensagem de sistema de cada exemplo. Nunca afeta a inferência: um modelo hospedado responde exatamente às messages que você envia. Se um exemplo selecionado já tem a própria mensagem de sistema, criar o job com system_prompt responde 422 e diz quantos conflitam, em vez de misturar dois conjuntos de instruções.

Estimar antes de iniciar

GET /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/estimate-messages?tags=support-clean&model_name=<catalog-model-id>&num_train_epochs=3

tags é uma seleção separada por vírgulas, e a estimativa aceita as mesmas escolhas de carga que a criação: model_name, num_train_epochs ou max_steps, max_seq_length, per_device_train_batch_size, gradient_accumulation_steps, base_load_precision, warmup_steps (inclusive 0; omita para aquecimento automático) e evaluation_cadence_kind com o evaluation_events ou evaluation_interval_steps correspondente.

Ela retorna as contagens da seleção (selected_chats, selected_messages, trainable_chats, nonempty_text_messages, e is_trainable: false para uma seleção vazia ou inutilizável), a divisão exata entre treino e avaliação, os passos e verificações planejados, a duração e os créditos estimados, e duas prévias:

{
  "configuration_preview": {
    "base_load_precision": "4bit",
    "warmup_steps": 2,
    "warmup_source": "automatic"
  },
  "evaluation_preview": {
    "holdout_percent": 5,
    "minimum_validation_examples": 8,
    "selection_examples_required": 160
  }
}

warmup_source é custom quando você enviou warmup_steps e automatic caso contrário. A estimativa usa a mesma aritmética da criação, mas é indicativa: a criação ainda faz a própria verificação final.

Iniciar uma execução de embeddings

Uma execução de embeddings treina com os exemplos de âncora, positivo e negativo opcional de um dataset de embeddings. Quatro chamadas, nesta ordem:

GET  .../training-jobs/profiles    modelos base e limites de cada configuração
POST .../training-jobs/preview     a seleção, a divisão e os passos exatos
POST .../training-jobs/estimate    os créditos necessários para iniciar
POST .../training-jobs             iniciar a execução

Escolha o dataset, um modelo base dos perfis, IDs de tags opcionais para estreitar a seleção e um max_steps de épocas inteiras. A prévia retorna um selection_sha256, a divisão exata entre treino e validação, as contagens de negativos explícitos, os pares e trios agendados por época e planned_steps_per_epoch. A criação exige esse selection_sha256, então uma execução sempre treina com a seleção que você visualizou. Uma prévia de um passo serve para descobrir a contagem de lotes; a estimativa e a criação exigem um número inteiro de épocas.

Um par (um exemplo sem negativo) aprende com as outras passagens do seu lote, e dois exemplos da mesma consulta nunca dividem um lote, porque cada positivo é uma resposta correta para o outro. Quando uma consulta tem vários positivos e nenhum negativo, como acontece em uma busca em que todos os resultados eram relevantes, alguns dos seus pares ficariam sem parceiro de lote. Cada um desses pares recebe então, como negativo, um positivo de outra consulta da mesma divisão de treino (nunca uma passagem que já responde à sua própria consulta) e treina com os trios. O campo borrowed_negative_count da prévia informa quantos pares de treino foram convertidos; as contagens de negativos explícitos continuam descrevendo os exemplos salvos. Seus dados não são alterados. Os pares de validação usam a mesma regra, dentro da divisão de validação. Se um par sem parceiro não tiver uma passagem segura para emprestar na própria divisão, a seleção continua recusada com embedding_batches_infeasible.

A estimativa é provisória: estimated_credits é null, e admission_ceiling_credits é o valor que precisa estar disponível para iniciar a execução, não a cobrança esperada. O cost_credits do job informa o que foi realmente cobrado.

A prévia, a estimativa e a criação também aceitam execution_limit_seconds opcional: um inteiro de pelo menos 5 segundos que não pode ultrapassar o teto da plataforma. O serviço de treinamento precisa aceitar esse limite; um serviço incompatível é recusado em vez de ampliar o prazo. Omitir o campo mantém esse teto. Envie o mesmo limite nas três requisições. A estimativa retorna admission_ceiling_seconds e a autorização de créditos escolhidos; a criação congela esse teto no job. Retry e resume mantêm o valor, mesmo após um aumento do limite da plataforma. Reduzir o teto da plataforma abaixo do valor congelado recusa retry/resume em vez de alterá-lo. O prazo se aplica separadamente a cada tentativa, incluindo a preparação do modelo e dos dados; o tempo na fila é separado. Não é um limite de gasto acumulado entre retries/resumes, e só o tempo de treino medido é cobrado. Um limite curto pode expirar antes do treino ou do checkpoint solicitado. Esta opção da API fica fora de settings; o app usa atualmente o padrão. A confirmação compartilhada GET .../retry-estimate está disponível para jobs de embeddings e calcula a autorização a partir do limite congelado e da tarifa atual, em vez da projeção de trabalho de treinamento de texto. Não é uma previsão do valor cobrado.

Configurações de embeddings

A prévia, a estimativa e a criação aceitam um objeto settings opcional; GET .../profiles publica a faixa e o padrão de cada configuração em setting_bounds, e as opções atuais de cada modelo base. Um valor recusado responde 422 com detail.field.

Configuração	O que faz
learning_rate, warmup_steps	A taxa do otimizador e seu aquecimento.
per_device_train_batch_size	Exemplos por lote. Cada outro exemplo do lote serve como negativo, então lotes maiores dão um sinal de treino mais difícil.
gradient_accumulation_steps	Faz a média dos gradientes de vários lotes. Não acrescenta negativos.
loss_scale	A temperatura da perda contrastiva.
per_device_eval_batch_size	0 escolhe automaticamente a partir do lote de treino e do memory_tokens do perfil.
evaluation_checks	Quantas verificações de validação a execução faz (1 a 10).
early_stopping_patience	Parar depois de tantas verificações sem melhora, mantendo o melhor checkpoint.
max_examples_per_query	O máximo de exemplos com que uma consulta pode contribuir.
lora_rank, lora_alpha, lora_dropout	O formato do adaptador. Um rank maior gera um adaptador maior; ele é aplicado a alpha ÷ rank; o dropout vale só no treino.
query_instruction	Uma linha (até 1.024 caracteres) colocada antes de cada consulta no treino, na validação, na API e na Busca. Documentos nunca a recebem.
output_dimensions	O tamanho de vetor com que o modelo é treinado e que ele retorna.
max_seq_length	Tokens por exemplo de treino. Um modelo treinado acima de 512 aceita entradas até o comprimento de treino; um treinado com 512 ou menos aceita 512.
training_mode	Como o modelo base é mantido enquanto o adaptador treina: qlora_4bit usa menos memória, lora_16bit treina sobre os mesmos pesos que o modelo hospedado usa.
normalize_embeddings	true por padrão. false retorna vetores brutos cujo comprimento tem significado, comparados por produto escalar; exige loss_scale 1.

Com acumulação, max_steps conta passos do otimizador; o planned_steps_per_epoch da prévia dá o número por época.

Configurações de treinamento

Projetos de embeddings usam o mesmo fluxo de Novo treinamento: selecione o dataset e a base, escolha épocas, confira a divisão e ajuste as configurações avançadas disponíveis. Os passos do otimizador são calculados a partir dos lotes planejados e das épocas escolhidas. Predefinições reutilizáveis estão planejadas; não há seletor de receitas para clientes.

Validação e o checkpoint mantido

Cerca de 10% da seleção fica reservada para validação, sempre em grupos inteiros de exemplos que compartilham algum texto, então nada reservado também é treinado. Grupos grandes ficam no treino quando grupos menores podem fornecer validação. A fração real pode diferir de 10% porque os grupos são indivisíveis; confira as contagens na prévia. Versões congeladas existentes mantêm sua divisão original. A execução verifica a perda de validação até dez vezes (a última no passo final): a mesma perda contrastiva usada no treino, calculada nos exemplos reservados no tamanho de vetor e na similaridade com que o modelo é servido (cosseno para vetores normalizados, produto escalar para vetores brutos). Ela mantém o checkpoint com a menor perda, o mais antigo em caso de empate. Com pelo menos quatro verificações, duas seguidas sem novo melhor valor reduzem a taxa de aprendizado à metade; com menos, a taxa cai linearmente. Execuções iniciadas antes desta regra mantêm a sua: elas mantiveram o checkpoint com o melhor nDCG@10 de validação, e a página do job continua mostrando esse valor.

Essa perda só escolhe um checkpoint: ela é medida durante o treino, que pode manter o modelo base em precisão menor que a do modelo hospedado, então não mede qualidade de recuperação. Jobs de avaliação separados para texto e embeddings ficam para uma versão futura; esta versão não inclui os painéis Qualidade de recuperação e Avaliação de recuperação. Um modelo concluído pode ser hospedado sem eles.

Como ler uma execução de embeddings. A página do job desenha a perda de validação a cada verificação (menor é melhor) e marca o checkpoint mantido.

• Ainda caindo na última verificação: mais épocas podem ajudar.
• Caindo, depois estável: mais épocas não vão ajudar; a execução já manteve a melhor verificação.
• Mínimo, depois subindo: o modelo está se ajustando mais aos pares de treino do que aos exemplos reservados. O checkpoint mantido é o ponto mais baixo; na próxima vez, tente menos épocas, uma taxa de aprendizado menor ou parada antecipada.
• Estável desde a primeira verificação: tente uma taxa de aprendizado maior ou mais dados.

Avaliação e parada antecipada

Em uma execução de texto, uma pequena parte de uma seleção grande o bastante fica reservada para avaliação e nunca é treinada. Quais exemplos ficam reservados é uma propriedade do seu dataset: toda execução sobre um dataset inalterado usa os mesmos, o que torna as execuções comparáveis. A política reserva 5% para avaliação, precisa de pelo menos 8 exemplos de avaliação e limita o conjunto a 512:

candidate_eval = floor(usable_examples × 0.05)
eval_examples  = 0 if candidate_eval < 8 else min(candidate_eval, 512)
train_examples = usable_examples - eval_examples

Assim, a avaliação começa em 160 exemplos utilizáveis; uma seleção menor treina com todos os exemplos e não informa perda de avaliação.

Você pode escolher quando a avaliação roda:

{"evaluation_cadence": {"kind": "events", "events": 10}}

ou {"evaluation_cadence": {"kind": "fixed_interval", "interval_steps": 300}}. Um orçamento de eventos vai de 1 a 100, e um intervalo fixo pode resultar em no máximo 100 verificações; ambos incluem o passo final exatamente uma vez. Sem cadência, a execução agenda cerca de dez verificações por época, no mínimo duas e no máximo cinquenta, e o job a mostra como Gerenciada.

O modelo servido é o checkpoint com a menor perda de validação da execução, não necessariamente o último; em caso de empate fica o mais antigo. A perda de validação mede a previsão do próximo token em linhas reservadas que também são usadas para escolher o checkpoint, então é um sinal de seleção, não acurácia na tarefa. Mantenha um conjunto de teste intocado fora da seleção de treino e compare o modelo ajustado com o modelo base nele antes de confiar no resultado.

A parada antecipada fica desligada a menos que você peça. Envie early_stopping_patience (1 ou mais) para parar quando a perda de avaliação não melhorar por tantas verificações. Uma execução que para antes ainda termina succeeded, antes de planned_steps. A estimativa retorna early_stopping_patience_max, duas a menos que as verificações agendadas (a primeira define a referência e a final não pode encurtar a execução), então um agendamento com menos de três verificações permite só 0.

Três configurações controlam como uma passagem de avaliação roda. Elas não mudam quais linhas são avaliadas nem quando, então não mudam o que a execução aprende; existem porque a avaliação é onde uma execução longa tem mais chance de ficar sem memória.

Configuração	Padrão	O que faz
per_device_eval_batch_size	0	Tamanho do lote de avaliação; 0 significa o tamanho do lote de treino. Reduzi-lo é a primeira correção para uma falha de memória na avaliação.
fp16_full_eval	false	Avaliação em meia precisão usa menos memória, mas muda a numérica da perda que escolhe o modelo.
eval_accumulation_steps	1	Buffer de saída da avaliação; veja abaixo.

Buffer de saída da avaliação

eval_accumulation_steps é o controle Buffer de saída da avaliação. O valor 1 significa que a saída da avaliação é reunida ao fim de cada verificação, mostrado no app como Fim da verificação (padrão); não é um intervalo de um passo. Intervalos personalizados vão de 2 a 32. Intervalos menores movem a saída com mais frequência e podem reduzir a memória do buffer, com algum custo de velocidade. O buffer não divide lotes de avaliação: para uma falha de memória na avaliação, reduza primeiro o lote de avaliação, depois considere a avaliação em meia precisão, e só então mude o buffer.

Como ler os gráficos de perda

• Uma perda de treino caindo significa que o modelo se ajusta melhor aos exemplos de treino; isso sozinho não mostra que as respostas melhoraram.
• A perda de validação mede a previsão em exemplos que não atualizaram o modelo; menor é melhor ao comparar checkpoints de uma execução.
• Perda de treino caindo enquanto a de validação sobe sugere sobreajuste: tente menos épocas ou uma taxa de aprendizado menor e compare no mesmo dataset.
• Os gráficos de taxa de aprendizado e norma do gradiente são diagnósticos, não notas: leia o formato dentro de uma execução, não um valor absoluto.

Um job concluído que avaliou tem um bloco evaluation: a menor perda e seu passo, a última perda e passo, quantas verificações rodaram e qual checkpoint é servido. promoted_before_last_eval: true diz que o checkpoint servido é anterior à última verificação. Um job que nunca avaliou informa evaluation: null.

Acompanhar uma execução

O detalhe do job informa status, progress, a configuração congelada, as métricas, cost_credits (a cobrança real; 0 quando nada foi cobrado) e model_available. Cada job tem um number, contado a partir de 1 dentro do projeto e mostrado no app, e um id usado pela API. Para ler um job pelo número:

GET /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{number}?identifier=number

Jobs nunca são excluídos, então os números não mudam; respostas de modelos hospedados e de cobrança mostram o mesmo valor como training_job_number.

Espera por processamento. Um job de embeddings pode ser aceito enquanto os recursos estão ocupados com outra execução. Ele espera por capacidade disponível, e o tempo na fila não é cobrado. Cada conta continua com apenas uma execução de treino ativa.

Preparação. Um job novo primeiro copia os exemplos selecionados, exatamente como estão, para um registro congelado: editar ou excluir esses exemplos depois não muda o que o job treina, e uma nova tentativa treina com os mesmos dados. preparation passa por queued, snapshotting, depois verified, failed ou cancelled; o treino só começa depois de verified. Uma falha de preparação é uma falha de entrada (failure_category: "input") e não é cobrada. Um job criado antes dessa etapa existir informa preparation: null.

Tempo. timing divide a execução em queued_seconds, preparing_seconds, training_seconds, post_processing_seconds e finalizing_seconds, com total_seconds (tempo ativo), elapsed_seconds (tempo de relógio) e idle_seconds (a diferença, como o tempo antes de uma nova tentativa). Uma fase sem marcações confiáveis é omitida em vez de estimada. Estes não são o intervalo cobrado; veja Cobrança.

Por que terminou. Um job concluído traz outcome.stop_reason: completed, max_steps, early_stopping, cancelled ou execution_deadline. outcome.downgrades lista configurações que a execução não pôde aplicar como enviadas, como tokens setting:action:cause (por exemplo early_stopping:disabled:no_eval_set quando a parada antecipada foi pedida sem conjunto de avaliação). outcome: null significa que a execução não informou nada, como em jobs que nunca chegaram ao treino.

Ambiente. O cartão Execução registra o hardware usado (modelo e quantidade de GPUs, memória, versões de driver e framework) e o preço por minuto congelado. Eles explicam por que execuções parecidas podem diferir em preço ou comportamento; não são notas de qualidade.

Os dados com que treinou. O detalhe de um job inclui os primeiros 50 exemplos congelados; o resto é paginado, até 200 por vez:

GET .../training-jobs/{job_id}/dataset?offset=0&limit=25
GET .../training-jobs/{job_id}/dataset?offset=0&limit=25&search=invoice&split=eval
GET .../training-jobs/{job_id}/dataset/{chat_id}

Cada item diz se foi entrada de train ou eval. search busca no texto congelado, e uma página com busca retorna total: null. Essas rotas leem o registro congelado, não seus dados atuais.

Tentativas e logs

Um job roda como uma ou mais tentativas (uma nova tentativa ou uma retomada acrescenta uma). A rota de tentativas retorna o status, as marcações de tempo, o código de falha e os metadados de log de cada tentativa; a rota de logs transmite o log da tentativa como JSON separado por linhas, com offset e limit em bytes.

Status da tentativa	Significado
leased	Capacidade reservada para a tentativa.
accepted	A execução foi aceita.
started	A execução está rodando.
finalizing	O treino terminou; o modelo está sendo verificado e publicado.
succeeded	A tentativa foi concluída.
failed	A tentativa terminou com um código de falha.
cancelled	A tentativa foi cancelada antes de o treino começar.
expired	O contato com a execução foi perdido e a tentativa foi encerrada.
submission_uncertain	Não foi possível confirmar se a execução foi aceita; nenhuma execução duplicada é iniciada.

log_complete: true (e o cabeçalho X-Log-Complete: true) marca um log completo. Depois de uma parada abrupta, o log é a última cópia salva: com integridade verificada, mas possivelmente sem a saída final, marcado com log_complete: false e log_recovered: true.

Estados do job

Status	Significado
pending	Aceito e aguardando para começar.
running	Preparando, treinando ou publicando o modelo.
cancel_requested	Cancelado antes de o treino começar; a execução está sendo encerrada.
pause_requested	Pausando: a execução treina até o próximo checkpoint, e esses passos são cobrados.
paused	Parado em um checkpoint com tudo preservado. Retome ou conclua. Um job pausado não ocupa sua vaga de treino ativo.
succeeded	O modelo foi verificado e publicado.
failed	A execução terminou sem modelo.
cancelled	Cancelado antes de o treino começar: sem modelo, sem cobrança.

Use model_available, não o status, para decidir se um modelo pode ser hospedado ou baixado: alguns jobs antigos que foram parados são cancelled e ainda têm modelo.

Pausar, retomar, concluir e cancelar

O controle disponível depende só de o treino já ter começado:

Fase	Controle	Resultado
Na fila ou preparando	POST .../cancel	O job termina cancelled. Nada foi aprendido, então não há modelo nem cobrança.
Treinando	POST .../pause (Parar no app)	A execução treina até o próximo checkpoint e termina paused.
Publicando	nenhum	O treino acabou e o modelo está a instantes.

O servidor garante esse limite, porque um cliente só vê o progresso depois: cancel responde 409 training_job_already_training quando o treino já começou, e pause responde 409 training_job_not_training_yet antes disso.

Uma pausa não é imediata, e a espera é cobrada. Ela é confirmada na hora, mas a execução continua até o próximo checkpoint, o único ponto de onde pode retomar depois. pause.steps_until_pause e pause.next_boundary_step no job dizem quanto falta, e o app mostra isso antes de você confirmar. Os checkpoints ficam no máximo 25 steps de distância, então uma pausa treina no máximo 25 passos a mais. Pausar antes do primeiro checkpoint funciona e pode levar mais. Quando não resta checkpoint, os dois valores são null (a pausa é então efetivamente o fim da execução); um job sem bloco pause não pode ser pausado. Uma pausa que chega depois do último checkpoint deixa a execução terminar normalmente, e ela termina succeeded com seu modelo.

Um job paused oferece duas operações:

Operação	Resultado
POST .../resume	Continua do checkpoint; gráficos e checkpoint selecionado seguem de onde pararam. Não recebe corpo e exige Idempotency-Key.
POST .../finish	Publica o modelo alcançado e termina succeeded. Gratuito: o tempo de treino foi cobrado quando a pausa se concluiu.

Jobs de embeddings têm os mesmos três controles. Um job de embeddings grava um checkpoint a cada verificação de validação, então pause.next_boundary_step é a próxima verificação antes do passo final, e a distância é a cadência de avaliação do job, não o limite de 25 passos acima. Finalizar publica o checkpoint com a melhor pontuação reservada até ali, o que o job manteria se terminasse nesse ponto, que pode ser anterior ao checkpoint em que a pausa parou. As bases Qwen3-Embedding-0.6B e Qwen3-Embedding-4B permitem parar em um checkpoint e retomar dele. A retomada preserva o checkpoint selecionado mesmo quando ele foi gravado por uma tentativa anterior; arquivos de checkpoint ausentes ou que não passam na verificação são recusados. Um job que falhou também pode ser repetido desde o início.

Ao retomar um job de embeddings, ele mantém a programação da taxa de aprendizado congelada no job. Perfis antigos que não registravam essa programação mantêm o decaimento linear. O checkpoint ainda precisa passar na verificação, e a base congelada precisa continuar elegível para treinamento. Quando a parada antecipada está habilitada, a contagem de avaliações consecutivas sem melhora também continua do checkpoint. Um histórico de avaliação incompleto ou um checkpoint que já atingiu a parada antecipada não pode reiniciar o treinamento. Se um job de embeddings atingir a parada antecipada no checkpoint da pausa solicitada, ele termina com early_stopping em vez de entrar em paused.

Não há cancelamento para um job pausado (409): ele já treinou e já foi cobrado, então descartar o modelo não ajudaria ninguém. Concluir publica o melhor checkpoint verificado ou, em uma execução sem conjunto de avaliação, o último checkpoint: o mesmo modelo que a execução produziria terminando ali. Se a publicação não conseguir verificar o modelo, o job termina failed sem cobrança adicional e pode ser tentado de novo. Retomar e concluir se recusam mutuamente com training_job_finalizing.

Quando uma execução atinge o limite de execução da plataforma, ela para sozinha, mantém o checkpoint que teria selecionado, termina succeeded e informa outcome.stop_reason: "execution_deadline". É cobrada pelo tempo que treinou e pode ser retomada para os passos restantes.

Nova tentativa

Um job failed ou cancelled pode ser tentado de novo. Um job que falha nunca se repete sozinho: a plataforma guarda as evidências e qualquer checkpoint verificado, e você decide se roda de novo.

curl -X POST "https://reopenly.com/api/v1/projects/<owner>/<project>/training-jobs/42/retry" \
  -H "Authorization: Bearer $REOPENLY_API_KEY" \
  -H "Idempotency-Key: 8f8d8ac4-8de5-4c63-a8f4-f0a39db1af4d" \
  -H "Content-Type: application/json" \
  -d '{"resume_from_checkpoint": false}'

Uma nova tentativa reutiliza as configurações e os dados congelados do job; nunca relê o dataset, e um job cujos dados congelados não existem mais não pode ser tentado de novo. resume_from_checkpoint: true continua de um checkpoint verificado da mesma entrada congelada quando existe. GET .../retry-estimate diz se uma nova tentativa é possível e quanto custaria; não inicia nada.

Cobrança e limites

Só o laço de treinamento é cobrado: para cada tentativa, do primeiro passo de treino até o momento em que o treino termina. A fila, a preparação (carregar o modelo, ler e tokenizar seus dados) e a publicação do modelo não são cobradas, e uma execução que nunca começa a treinar é gratuita. Tentativas que falham não são cobradas. cost_credits é a cobrança real, do registro de créditos.

A estimativa é calibrada em execuções medidas com lote efetivo de 8 (per_device_train_batch_size 2 × gradient_accumulation_steps 4) e carregamento em 8 bits. Outros formatos são precificados com margem de segurança, e um lote abaixo de 8 é precificado como 8. Para aumentar o lote efetivo, aumente gradient_accumulation_steps em vez de per_device_train_batch_size: um lote maior por dispositivo precisa de mais memória por passo e, perto do limite do hardware de treino, pode deixar cada passo muito mais lento do que o tamanho sugere. Enviar num_train_epochs em vez de max_steps mantém a duração da execução ligada aos seus dados quando você muda o lote.

A exposição máxima de uma execução precisa caber no limite de execução da plataforma, seis horas por padrão. Leia o valor atual em duration_components.execution_limit_seconds de POST /api/v1/pricing/estimate em vez de fixá-lo no código. Uma execução que não cabe é recusada antes de começar com training_duration_exceeds_limit (422 na criação, 409 na nova tentativa): reduza num_train_epochs, max_seq_length ou a seleção.

Códigos de falha

Os códigos de falha são estáveis, e nenhum traz saída bruta do sistema.

Código	Significado
training_exceeds_provider_limit	A execução é mais longa do que a plataforma consegue executar de uma vez. Nada começou; reduza épocas, comprimento de sequência ou a seleção.
worker_disk_exhausted	A execução ficou sem espaço de armazenamento.
provider_failed	A execução falhou enquanto rodava.
provider_execution_timeout	A execução passou do prazo de execução.
provider_ttl_expired	A execução esperou ou rodou mais do que o permitido e foi encerrada.
provider_callback_missing	A execução parou de informar progresso e foi encerrada.
provider_terminal_callback_missing	A execução terminou sem entregar um modelo verificado.
provider_result_unavailable	Não foi possível obter o resultado da execução.
provider_status_unavailable	Não foi possível confirmar o estado da execução após verificações repetidas.
provider_cancelled	A execução foi parada pela plataforma sem um pedido seu.

Download

Quando model_available for true, baixe o adaptador treinado:

GET /api/v1/projects/{owner_slug}/{project_slug}/training-jobs/{job_id}/download?format=lora

Os adaptadores de embedding incluem manifest.json com checksums SHA256 e tamanhos em bytes dos arquivos do pacote, incluindo os metadados públicos da configuração do adaptador. Você pode usá-lo para verificar os arquivos baixados.

Ele transmite um arquivo compactado com gzip. GET .../training-jobs/{job_id}/download-metadata lista antes os arquivos e o tamanho total, sem baixar. Para chamar o modelo, dê um nome a ele em Modelos hospedados.

As estimativas de treinamento de texto incluem training_plan, o cronograma usado para calcular a cotação. Ele descreve o trabalho de treinamento e avaliação para as configurações selecionadas.