Saltar para o conteúdo principal
Capítulos do guia de treino Toda a documentação

CLI de treino: comandos e opções

A linha de comandos do SDK 0.2.0, desde a configuração do projeto até à recuperação, avaliação, exportação e códigos de saída com significado.

Capítulos do guia de treino

Os comandos e o código permanecem em inglês em todos os idiomas. Substitua os marcadores em maiúsculas pelos valores da sua conta e da sua tarefa paga; não cole chaves reais em cadernos partilhados nem em registos.

Fluxo de trabalho da linha de comandos

Cada comando tem um efeito específico e um resultado significativo.
  1. init / doctor Criar e verificar o projeto
  2. plan Rever sem treinar
  3. run Treinar dentro dos orçamentos
  4. evaluate Verificar critérios reservados
  5. export Validar e empacotar

Seguir uma sequência clara de comandos

O SDK 0.2.0 inclui o executável fpai-training. A sequência usa o mesmo contrato de projeto da interface Python: inicializar, verificar a compatibilidade, rever o plano de ensaio, executar, avaliar e exportar. Consultar o estado ou um plano não prova que o treino tenha sido bem-sucedido.

  • A autenticação é lida a partir de FUSIONPOINTAI_API_KEY. A chave não é passada como argumento e não fica exposta na lista de processos.
  • Use --help no executável ou num comando. --version mostra a versão instalada do pacote.
  • O plano revisto fixa as definições resolvidas; a CLI não permite alterações ocultas aos hiperparâmetros.
Referência completa dos comandos CLI
Campo ou interfaceTipo ou resultadoPredefinição ou código de saídaComportamento e validação
init --directory PATH command Obrigatório / sem predefinição Cria a estrutura de um projeto novo e um exemplo de configuração; recusa um diretório existente que não esteja vazio. Não executa treino nem chamadas pagas.
doctor --config PATH command Obrigatório / sem predefinição Verifica o esquema, os ficheiros locais do modelo, as dependências, o armazenamento, os dispositivos e a compatibilidade do adaptador. Não atualiza pesos nem gera conteúdo com o professor.
plan --config PATH --dry-run command Obrigatório / sem predefinição Resolve predefinições, fixa impressões digitais e apresenta temas, partilha, orçamentos e resultados. Não otimiza nem executa trabalho pago com o professor.
run --config PATH command Obrigatório / sem predefinição Exige um plano válido e revisto, bem como autorização ativa; bloqueia uma execução e realiza treino efetivo dentro dos orçamentos.
status --run PATH command Obrigatório / sem predefinição Lê o instantâneo local expurgado da execução. Não reinicia processos nem gera pedidos ao professor.
pause --run PATH command Obrigatório / sem predefinição Pede uma pausa segura e aguarda por um checkpoint atómico completo. Só é válido numa execução ativa pertencente ao projeto.
resume --run PATH command Obrigatório / sem predefinição Retoma uma execução pausada/interrompida recuperável apenas após a validação rigorosa do checkpoint e do plano.
cancel --run PATH command Obrigatório / sem predefinição Interrompe os processos próprios, liberta os recursos correspondentes e regista o cancelamento; preserva resultados válidos e diagnósticos.
evaluate --run PATH --split test command Obrigatório / sem predefinição Avalia o modelo fixado com dados de validação ou teste. Não otimiza nem partilha dados reservados.
export --run PATH --format safetensors command Obrigatório / sem predefinição Valida e empacota um resultado suportado e aceite; não o carrega externamente nem efetua uma implementação em produção.
Exemplo · bash 
fpai-training --version
fpai-training --help
fpai-training init --directory ./german-project
# Replace training.json and rubric/data files with your reviewed configuration.
fpai-training doctor --config ./german-project/training.json
fpai-training plan --config ./german-project/training.json --dry-run
# Inspect resolved values, data sharing and budgets BEFORE the next command.
fpai-training run --config ./german-project/training.json
fpai-training status --run ./german-project/runs/german-001
fpai-training evaluate --run ./german-project/runs/german-001 --split test
fpai-training export --run ./german-project/runs/german-001 --format safetensors
# Supply the key through FUSIONPOINTAI_API_KEY, never a command-line argument.

Pausar, retomar ou cancelar em segurança

Os comandos de controlo destinam-se a um único diretório de execução pertencente ao projeto. A pausa aguarda por um checkpoint atómico e pela confirmação do processo de trabalho. A retoma valida o mesmo modelo, dados, configuração, avaliador e topologia distribuída. O cancelamento interrompe apenas os processos dessa execução e regista um cancelamento terminal. Repetir um pedido de controlo não deve iniciar outro processo de treino.

  • Uma execução em pausa pode ser recuperada; não está concluída. Uma execução cancelada não é um resultado aceite.
  • Utilize um segundo terminal para controlar uma execução ativa em primeiro plano.
  • Após um timeout, consulte o estado antes de tentar novamente. Não elimine ficheiros de bloqueio nem termine tarefas GPU alheias.
Opções dos comandos
Campo ou interfaceTipo ou resultadoPredefinição ou código de saídaComportamento e validação
--directory path Obrigatório / sem predefinição Obrigatório para init. Novo diretório de projeto com permissões de escrita.
--config path Obrigatório / sem predefinição Obrigatório para doctor, plan e run. Caminho para um ficheiro completo do esquema 1.0.
--run path Obrigatório / sem predefinição Obrigatório para status, pause, resume, cancel, evaluate e export. Diretório de execução próprio, não um ID de conta/sessão.
--dry-run flag true Opção explícita do plano; plan é sempre só de leitura quanto aos pesos e ao trabalho pago. Não existe um modo de execução false/off.
--split enum "test" Apenas para evaluate: validation ou test. Os dados de teste nunca são utilizados para melhorias.
--format enum "safetensors" Apenas para export: safetensors ou adapters, sujeitos às capacidades do adaptador.
--help flag false Apresenta a ajuda do executável ou do comando sem aceder ao fornecedor.
--version flag false Apresenta os metadados reais da versão instalada, não a versão do esquema de configuração.
Exemplo · bash 
# Run controls from a separate terminal if training is active.
fpai-training pause --run ./german-project/runs/german-001
# Wait for status=paused and a completed atomic checkpoint before stopping a host.
fpai-training status --run ./german-project/runs/german-001
fpai-training resume --run ./german-project/runs/german-001
# Cancellation is terminal; preserve existing artifacts, do not pretend it passed.
fpai-training cancel --run ./german-project/runs/german-001
# Repeat status, not run(), after a timeout. Never kill an unrelated process.

Interpretar em conjunto o estado e os códigos de saída

O código de saída zero significa que a operação pedida foi bem-sucedida; uma consulta de estado, uma pausa ou uma simulação bem-sucedidas não equivalem a um treino aceite. O resultado do treino também exige um estado concluído, um motivo de paragem aceite e o cumprimento de todos os critérios de avaliação obrigatórios. Os objetivos falhados continuam identificados como tal nos relatórios, sem serem reclassificados como sucessos.

  • Os comandos escrevem JSON legível por máquinas em stdout e diagnósticos expurgados em stderr. Nenhum destes fluxos contém segredos.
  • run e resume aguardam um estado terminal ou de pausa; status devolve o instantâneo atual.
  • SIGINT termina com o código 130 após uma tentativa de limpeza dos processos pertencentes à execução. Um processo interrompido não pode fabricar um checkpoint concluído.
Exemplo · text 
SDK 0.2.0 EXIT AND STATE CONTRACT
0   accepted, successful read/control, or successful dry-run; inspect operation.
2   invalid configuration; no training started.
3   incompatible model/runtime/method/export combination.
4   authentication, entitlement or authorized-sharing failure.
5   resource budget exhausted; preserve latest valid checkpoint and report.
6   evaluation requirements not met; not an accepted model.
7   execution, checkpoint, cancellation-control or export failure.
130 interrupted by the caller.

Lifecycle:
planned -> preparing -> training -> evaluating -> completed
training -> pausing -> paused -> training (validated resume)
active -> cancelling -> cancelled
active -> failed

stop_reason: accepted | budget_exhausted | no_progress | regression |
             cancelled | failed
paused is a recoverable state, not an accepted training result.
completed requires stop_reason=accepted and all required criteria passing.
Repeated control requests must read/reuse the owned transition, not spawn workers.
One run lock prevents duplicate execution of the same run directory.