Referência de configuração do TrainingProject

Definir um projeto e proteger os respetivos dados

Este é o contrato de projeto do esquema 1.0. Guarde o exemplo do modo Automático como training.json. Resolva os caminhos dentro da raiz do projeto, indique o ID do modelo de referência incluído e mantenha a chave de API no ambiente do processo. A configuração seleciona um modelo de referência pago e um modelo aluno treinável de forma independente; nunca transfere os pesos do modelo de referência.

As chaves desconhecidas são rejeitadas. Os caminhos do modelo, dos dados, da grelha e dos resultados têm de permanecer dentro da raiz do projeto.
A partilha com o modelo de referência limita-se às fontes de treino aprovadas. Os dados de validação e do teste final permanecem locais.
O TrainingClient continua disponível para os fluxos existentes de tarefas pagas e sessões.

Projeto, modelo e modelo professor
Campo ou interface	Tipo ou resultado	Predefinição ou código de saída	Comportamento e validação
`schema_version`	`string`	`"1.0"`	Utilize exatamente 1.0. As outras versões do esquema são rejeitadas até serem explicitamente suportadas.
`mode`	`enum`	Obrigatório / sem predefinição	Obrigatório: `automatic` ou `advanced`. O modo Automático resolve predefinições compatíveis; o modo Avançado expõe controlos explícitos.
`objective`	`string`	Obrigatório / sem predefinição	Descrição obrigatória da tarefa, com 10 a 4000 caracteres. Indique o público, as capacidades e o resultado esperado.
`model.path`	`string`	Obrigatório / sem predefinição	Caminho obrigatório para um modelo local dentro da raiz do projeto, ou identificador de repositório associado a uma revisão imutável. Nunca um endpoint de inferência do modelo de referência.
`model.adapter`	`string`	Obrigatório / sem predefinição	ID obrigatório de um adaptador registado. transformers-causal-lm seleciona o adaptador Transformers para modelos de linguagem causal.
`model.revision`	`string \| null`	`null`	Os modelos locais são identificados por impressões digitais. Os repositórios requerem uma revisão imutável de 40 ou 64 caracteres.
`teacher.provider`	`string`	Obrigatório / sem predefinição	Identificador de fornecedor obrigatório, incluído no seu plano pago ativo. Não transfere a propriedade do modelo.
`teacher.reference_model_id`	`integer`	Obrigatório / sem predefinição	Número inteiro positivo obrigatório, escolhido entre os modelos incluídos nesse plano do fornecedor; substitua os marcadores.

Dados e privacidade
Campo ou interface	Tipo ou resultado	Predefinição ou código de saída	Comportamento e validação
`data.sources`	`string[]`	`[]`	Caminhos para fontes locais de treino JSONL com um campo text. As lições geradas pelo modelo de referência podem complementá-las quando teacher_sharing é approved_only.
`data.teacher_sharing`	`enum`	`"approved_only"`	approved_only permite conteúdo de treino revisto; none proíbe o envio de conteúdo de clientes ao professor. Os dados de avaliação reservados são sempre excluídos.
`data.validation_path`	`string \| null`	`null`	Caminho opcional para JSONL de validação independente. Se estiver ausente, o plano revisto define uma divisão determinística antes do treino.
`data.test_path`	`string`	Obrigatório / sem predefinição	Ficheiro de teste final independente obrigatório, nunca utilizado na preparação do professor nem na otimização.
`data.deduplicate`	`boolean`	`true`	Remove exemplos duplicados ou sobrepostos entre divisões e comunica as exclusões sem revelar texto privado.
`data.seed`	`integer`	`42`	Número inteiro não negativo para divisões determinísticas e inicialização reproduzível quando suportadas pelo backend.

{
  "schema_version": "1.0",
  "mode": "automatic",
  "objective": "Classify support messages as billing, account_access or technical_issue.",
  "model": {"path": "./models/student", "adapter": "transformers-causal-lm", "revision": null},
  "teacher": {"provider": "openai", "reference_model_id": 123},
  "data": {
    "sources": ["./data/train.jsonl"], "teacher_sharing": "none",
    "validation_path": "./data/validation.jsonl", "test_path": "./data/test.jsonl",
    "deduplicate": true, "seed": 42
  },
  "runtime": {"target": "customer_datacenter", "devices": "auto"},
  "training": {"method": "auto"},
  "curriculum": {"topics": ["intent", "ambiguous_requests", "class_balance"], "max_improvement_cycles": 3, "stop_on_regression": true},
  "budgets": {"max_training_minutes": 120, "max_teacher_requests": 1000, "max_storage_gib": 20},
  "checkpoints": {"keep_last": 3},
  "evaluation": {"rubric": "./rubric.json", "baseline_required": true},
  "output": {"directory": "./runs/german-001", "format": "safetensors"}
}

Escolher o modo de treino automático ou avançado

O modo automático resolve definições compatíveis uma vez e regista-as no plano revisto. O modo avançado exige definições explícitas e só aceita combinações compatíveis de arquitetura, método, precisão e hardware. As predefinições não garantem memória nem desempenho em todos os casos. As combinações não suportadas falham antes de transferências pesadas ou da atualização dos pesos.

SFT atualiza parâmetros elegíveis do modelo. LoRA e QLoRA criam adaptadores e requerem o modelo-base correspondente.
Em DDP, o iniciador aprovado fornece os ranks dos nós e as definições de rendezvous; todos têm de concordar quanto ao número de processos, versões e impressões digitais.
A arquitetura do modelo, o tokenizador e os limites de contexto continuam a ser obrigatórios. Cada família adicional precisa de um adaptador com capacidades próprias verificadas.

Ambiente de execução e distribuição
Campo ou interface	Tipo ou resultado	Predefinição ou código de saída	Comportamento e validação
`runtime.target`	`enum`	Obrigatório / sem predefinição	Obrigatório: fusionpointai_hosting, customer_datacenter ou colab. Seleciona um ambiente existente; não compra hardware.
`runtime.devices`	`"auto" \| integer[]`	`"auto"`	auto seleciona dispositivos aprovados e compatíveis; uma lista explícita contém índices GPU visíveis, únicos e não negativos.
`runtime.distributed.backend`	`enum`	`"none"`	none para um processo ou ddp com um adaptador suportado e um iniciador de vários processos aprovado.
`runtime.distributed.nodes`	`integer`	`1`	Número inteiro positivo. Mais de um requer DDP, acesso acordado aos nós, ranks e rendezvous seguro; este valor não disponibiliza capacidade.

Definições de treino
Campo ou interface	Tipo ou resultado	Predefinição ou código de saída	Comportamento e validação
`training.method`	`enum`	`"auto"`	Um de: auto, SFT, LoRA ou QLoRA. O modo automático resolve auto; o modo avançado usa um método explícito suportado.
`training.epochs`	`number \| "auto"`	`"auto"`	Número positivo finito ou auto apenas no modo Automático; o número efetivo de passos também é limitado pelo tempo e pelos recursos aprovados.
`training.learning_rate`	`number \| "auto"`	`"auto"`	Número positivo finito inferior a 1 ou auto apenas no modo Automático. As políticas comerciais e do adaptador podem impor limites mais restritos.
`training.batch_size`	`integer \| "auto"`	`"auto"`	Número inteiro positivo por dispositivo ou auto apenas no modo Automático; a adequação à memória é verificada antes da execução.
`training.gradient_accumulation_steps`	`integer \| "auto"`	`"auto"`	Número inteiro positivo ou auto apenas no modo Automático. O tamanho efetivo do lote inclui o número de processos e a acumulação.
`training.max_sequence_length`	`integer \| "auto"`	`"auto"`	Número inteiro positivo dentro dos limites do tokenizador e do modelo, ou auto apenas no modo Automático; nunca prolonga silenciosamente o contexto do modelo.
`training.precision`	`enum`	`"auto"`	auto, fp32, fp16 ou bf16, conforme suportado pelo hardware e pelo backend; explícito no modo Avançado.
`training.lora.rank`	`integer`	`16`	Rank positivo do adaptador. Utilizado apenas com LoRA/QLoRA e módulos-alvo elegíveis.
`training.lora.alpha`	`number`	`32`	Valor positivo finito de escala do adaptador. Utilizado apenas com LoRA/QLoRA.
`training.lora.dropout`	`number`	`0.05`	Valor finito desde 0 inclusive até 1 exclusive. Utilizado apenas com LoRA/QLoRA.
`training.lora.target_modules`	`"auto" \| string[]`	`"auto"`	auto resolve no plano nomes de módulos suportados; em alternativa, forneça uma lista não vazia de nomes elegíveis.

Controlos do currículo
Campo ou interface	Tipo ou resultado	Predefinição ou código de saída	Comportamento e validação
`curriculum.topics`	`string[]`	`[]`	Nomes de temas ordenados. Se estiver vazio, o modo Automático pode propor pré-requisitos; o modo Avançado exige uma sequência explícita e revista.
`curriculum.max_improvement_cycles`	`integer`	`3`	Número inteiro positivo, máximo 10. Pare mais cedo se se aplicarem condições de orçamento esgotado, ausência de progresso ou regressão.
`curriculum.stop_on_regression`	`boolean`	`true`	Quando true, interrompe a melhoria perante uma regressão definida pela grelha. Quando false, uma regressão continua a fazer falhar a aceitação final.

{
  "schema_version": "1.0",
  "mode": "advanced",
  "model": {"path": "./models/student", "adapter": "transformers-causal-lm", "revision": null},
  "teacher": {"provider": "openai", "reference_model_id": 123},
  "objective": "Classify support messages as billing, account_access or technical_issue.",
  "data": {"sources": ["./data/train.jsonl"], "teacher_sharing": "none", "validation_path": "./data/validation.jsonl", "test_path": "./data/test.jsonl"},
  "runtime": {"target": "customer_datacenter", "devices": [0, 1], "distributed": {"backend": "ddp", "nodes": 1}},
  "training": {
    "method": "LoRA",
    "epochs": 3,
    "learning_rate": 0.0002,
    "batch_size": 1,
    "gradient_accumulation_steps": 16,
    "max_sequence_length": 2048,
    "precision": "bf16",
    "lora": {"rank": 16, "alpha": 32, "dropout": 0.05}
  },
  "curriculum": {
    "topics": ["intent", "ambiguous_requests", "class_balance"],
    "max_improvement_cycles": 3,
    "stop_on_regression": true
  },
  "checkpoints": {"every_steps": 100, "keep_last": 3, "resume_validation": "strict"},
  "budgets": {"max_training_minutes": 120, "max_teacher_requests": 1000, "max_storage_gib": 20},
  "evaluation": {"rubric": "./rubric.json", "baseline_required": true},
  "output": {"directory": "./runs/german-advanced-001", "format": "safetensors"}
}

Definir orçamentos finitos e critérios de aceitação mensuráveis

Cada projeto tem orçamentos explícitos de tempo, pedidos ao professor e armazenamento. Pare quando um orçamento se esgotar, uma verificação de integridade falhar, ocorrer uma regressão ou deixar de haver progresso. Guarde um estado de recuperação válido e explique os critérios por cumprir. Uma grelha define tarefas de aceitação independentes; não transforma uma pontuação de exemplo num resultado alcançado.

A grelha de exemplo utiliza uma escala normalizada de 0 a 1 e critérios obrigatórios distintos. Todos os critérios obrigatórios têm de passar.
Alterar dados, modelo, avaliação, topologia ou orçamentos exige um novo plano revisto, em vez de forçar a retoma com definições incompatíveis.
As exportações incluem ficheiros validados do modelo ou do adaptador, o tokenizador e manifestos; não incluem credenciais, dados de cache alheios nem código de modelo não revisto.

Orçamentos, recuperação e resultados
Campo ou interface	Tipo ou resultado	Predefinição ou código de saída	Comportamento e validação
`budgets.max_training_minutes`	`number`	Obrigatório / sem predefinição	Orçamento de execução obrigatório, positivo e finito, em minutos; inclui o tempo decorrido de preparação e avaliação após o início da execução.
`budgets.max_teacher_requests`	`integer`	Obrigatório / sem predefinição	Número inteiro positivo obrigatório; conta as tentativas de preparação, revisão e repetição. Falha em segurança antes de exceder o limite.
`budgets.max_storage_gib`	`number`	Obrigatório / sem predefinição	Orçamento obrigatório, positivo e finito de armazenamento próprio em GiB; abrange dados, checkpoints e artefactos. Nunca elimine ficheiros alheios.
`checkpoints.every_steps`	`integer`	`100`	Intervalo positivo, em passos, entre checkpoints. Guarde também um checkpoint atómico válido quando uma pausa for bem-sucedida.
`checkpoints.keep_last`	`integer`	`3`	Número inteiro entre 1 e 5. Remova apenas checkpoints próprios obsoletos depois de validar um mais recente.
`checkpoints.resume_validation`	`enum`	`"strict"`	Apenas strict. Rejeita alterações nas impressões digitais do modelo, dos dados, da configuração, do avaliador ou da topologia distribuída.
`evaluation.rubric`	`string`	Obrigatório / sem predefinição	Caminho obrigatório para uma grelha válida com avaliadores fixados e critérios obrigatórios mensuráveis.
`evaluation.baseline_required`	`boolean`	`true`	Apenas true neste contrato. Avalie a linha de base intacta antes de atualizar os pesos.
`output.directory`	`string`	Obrigatório / sem predefinição	Novo diretório próprio para a execução, obrigatório. As execuções existentes podem ser consultadas ou retomadas, mas `run` nunca as substitui.
`output.format`	`enum`	`"safetensors"`	safetensors ou adapters, apenas quando suportados. As exportações de adaptadores requerem o modelo-base e o tokenizador fixados.

Campos da grelha de avaliação
Campo ou interface	Tipo ou resultado	Predefinição ou código de saída	Comportamento e validação
`schema_version`	`string`	`"1.0"`	Esquema de grelha 1.0, distinto da versão do pacote.
`name`	`string`	Obrigatório / sem predefinição	Nome de grelha obrigatório e não vazio, utilizado nos relatórios.
`scale.minimum`	`number`	`0`	Limite inferior da pontuação normalizada: 0 neste esquema.
`scale.maximum`	`number`	`1`	Limite superior da pontuação normalizada: 1 neste esquema.
`criteria`	`object[]`	Obrigatório / sem predefinição	Lista não vazia. Todos os critérios obrigatórios têm de passar; os IDs têm de ser únicos.
`criteria[].id`	`string`	Obrigatório / sem predefinição	Identificador estável de critério, obrigatório e preservado nos relatórios.
`criteria[].description`	`string \| null`	`null`	Texto explicativo opcional. A descrição não é um avaliador semântico.
`criteria[].metric`	`string`	Obrigatório / sem predefinição	Métrica registada obrigatória: exact_match, macro_f1, text_similarity, chrf ou um avaliador personalizado registado.
`criteria[].minimum_score`	`number`	Obrigatório / sem predefinição	Limiar obrigatório, finito e entre 0 e 1. Um limiar de exemplo não garante o resultado.
`regression.maximum_score_drop`	`number`	`0.02`	Queda absoluta normalizada máxima permitida face à linha de base intacta, de 0 a 1; avaliada por cada critério retido.
`final_test.path`	`string`	Obrigatório / sem predefinição	Obrigatório; tem de identificar o mesmo ficheiro independente que data.test_path.
`final_test.allow_training_use`	`boolean`	`false`	Apenas false. Rejeita configurações que permitam a utilização de respostas do teste reservado no treino ou como entrada do professor.

SDK 0.2.0 CONFIGURATION RULES
Unknown fields, duplicate IDs, nonfinite numbers and unsafe paths are rejected.
All model, data, rubric and output paths must resolve inside the project root.
Automatic mode resolves "auto" once; save all resolved values in the plan manifest.
Advanced mode requires explicit method, epochs, learning_rate, batch_size,
gradient_accumulation_steps, max_sequence_length and precision.
SFT does not consume LoRA options. LoRA/QLoRA require a compatible adapter.
Model files and pinned revisions are verified within the project root.
Use the CLI for explicit GPU indexes; Python callers can set CUDA_VISIBLE_DEVICES
before starting Python and keep runtime.devices set to auto.
No automatic execution of untrusted model code, shell commands or plugins.
All three budgets must be finite, positive and explicitly supplied.
Storage includes owned checkpoints, datasets and artifacts, not unrelated files.
Held-out test data must not be sent to the teacher or used for weight updates.
CLI overrides are limited to the documented flags; never silently override a plan.
RUBRIC RULES
Every criterion requires a registered metric and minimum_score; descriptions are not semantic evaluators.
Built-in metrics: exact_match, macro_f1, text_similarity and chrf.
Custom deterministic scorers use register_evaluator(name, scorer, version="...").
Evaluator versions and scoring configuration are pinned in the plan.
0 <= minimum_score <= 1 for the example's normalized scale.
All required criteria must pass; do not average away a failed criterion.
The final_test.path must match data.test_path; allow_training_use must be false.
Scores and budgets in examples are requested settings, not measured results.

Da configuração a uma execução reproduzível

Definir um projeto e proteger os respetivos dados

Escolher o modo de treino automático ou avançado

Definir orçamentos finitos e critérios de aceitação mensuráveis

Continue o fluxo de trabalho