SDK Python: métodos, resultados e erros

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.

Uma API de projeto, um único motor subjacente

A CLI e Python têm de concordar quanto à configuração, ao estado e aos resultados entregues.

from_file Carregar sem alterar pesos
plan Inspecionar entradas resolvidas
run / controls Gerir processos e recuperação
evaluate / export Inspecionar resultados locais aceites

Utilizar o mesmo motor a partir de Python

TrainingProject complementa TrainingClient, não o substitui. Carregue a configuração e uma chave de API com o âmbito adequado, reveja o plano e inicie a execução. O objeto do projeto permite consultar e controlar a execução; run não substitui uma execução existente e resume exige um estado recuperável válido.

Os caminhos aceitam cadeias ou objetos os.PathLike. As opções dos métodos são apenas por palavra-chave e argumentos desconhecidos são rejeitados.
from_file valida a configuração local; não atualiza os pesos nem pede conteúdo ao modelo de referência.
As interfaces Python e CLI resolvem as mesmas definições, impressões digitais, orçamentos e resultados.

Referência completa do projeto Python
Campo ou interface	Tipo ou resultado	Predefinição ou código de saída	Comportamento e validação
`TrainingProject.from_file(path, *, api_key)`	`TrainingProject`	Obrigatório / sem predefinição	Carrega e valida o caminho da configuração e uma cadeia secreta não vazia. Devolve um objeto de projeto; não atualiza pesos nem pede conteúdo ao modelo de referência.
`plan(*, dry_run=True)`	`dict`	`true`	Apenas True. Devolve resolved_configuration, compatibility, data_sharing, budgets, topics, artifacts e fingerprints.
`run()`	`dict`	Obrigatório / sem predefinição	Bloqueia até um estado terminal ou de pausa; só devolve o resultado comum da execução se a operação for bem-sucedida; caso contrário, gera o erro correspondente.
`status()`	`dict`	Obrigatório / sem predefinição	Lê run_id, status, stop_reason, report_path e unmet_criteria sem iniciar um processo de trabalho.
`pause()`	`dict`	Obrigatório / sem predefinição	Aguarda a confirmação do processo de trabalho e um checkpoint válido; devolve o resultado comum da execução. Um estado inválido é um erro de configuração.
`resume()`	`dict`	Obrigatório / sem predefinição	Valida todas as impressões digitais e retoma os processos próprios; devolve o resultado comum quando a operação é bem-sucedida.
`cancel()`	`dict`	Obrigatório / sem predefinição	Aguarda que os processos próprios parem e devolve o estado cancelled; gera CancellationError se não for possível confirmar uma terminação segura.
`evaluate(*, split="test")`	`dict`	`"test"`	Aceita validation ou test. Devolve run_id, split, accepted, criteria, regressions e report_path; uma aceitação falhada gera EvaluationFailedError após guardar o relatório.
`export(*, format="safetensors")`	`dict`	`"safetensors"`	Devolve run_id, format, artifact_path, manifest_path e sha256 para um artefacto compatível e aceite.
`register_evaluator(name, scorer, *, version)`	`None`	Obrigatório / sem predefinição	Registe uma função de avaliação de confiança antes do planeamento ou da avaliação. Defina um nome estável e uma versão explícita. A função recebe prediction, target e row e deve devolver um valor finito entre 0 e 1. As métricas integradas não podem ser substituídas.

import os
from fusionpointai_training import TrainingProject

project = TrainingProject.from_file(
    "./german-project/training.json",
    api_key=os.environ["FUSIONPOINTAI_API_KEY"],
)
plan = project.plan(dry_run=True)
print(plan["resolved_configuration"], plan["data_sharing"], plan["budgets"])
# Confirm the reviewed plan before starting real work.
result = project.run()
if result["status"] != "completed" or result["stop_reason"] != "accepted":
    raise RuntimeError("Training was not accepted; inspect the retained report.")
evaluation = project.evaluate(split="test")
# A failed required criterion raises EvaluationFailedError after saving its report.
artifact = project.export(format="safetensors")
print(artifact["manifest_path"])

Consultar resultados estruturados

O contrato de retorno seguinte descreve estruturas, não medições de exemplo. Consulte status, stop_reason e unmet_criteria antes da implementação. Os resultados da avaliação identificam cada critério e regressão. A exportação devolve caminhos locais e metadados de integridade; não carrega automaticamente o modelo nem substitui a inferência em produção.

Os dados de estado e do manifesto têm de poder ser consultados sem gerar outro pedido ao professor.
A avaliação no conjunto de teste final é distinta da validação utilizada durante as melhorias.
O manifesto de artefactos tem de corresponder aos ficheiros reais, caminhos relativos seguros, tamanhos em bytes e valores SHA-256.

TrainingProject return contract (dictionary shapes)
from_file: validates configuration, attaches its owned run; no weight updates.
plan: {schema_version, resolved_configuration, compatibility, data_sharing,
       budgets, topics, artifacts, fingerprints}; dry_run must be true.
run/resume: {run_id, status, stop_reason, report_path, unmet_criteria}.
status/pause/cancel: {run_id, status, stop_reason, report_path, unmet_criteria}.
stop_reason is null until terminal; run/resume block until terminal or paused.
pause blocks until owned workers acknowledge an atomic checkpoint.
cancel blocks until owned workers stop; a failed stop raises CancellationError.
evaluate: {run_id, split, accepted, criteria, regressions, report_path}.
export: {run_id, format, artifact_path, manifest_path, sha256}.
Returned paths are local, resolved paths; no model upload is implied.
Status output is redacted and may be read without opening an API connection.
from_file requires path: str | os.PathLike and a nonempty api_key: str.
plan accepts dry_run=True only; False is ConfigurationError, not execution.
evaluate accepts split="validation" or "test"; defaults to test.
export accepts safetensors or adapters when supported by the selected adapter.
All method keyword options are keyword-only. Unlisted arguments are rejected.

Tratar as falhas sem as ocultar

Os erros do projeto herdam de TrainingError e correspondem aos códigos CLI documentados. Os erros de configuração e compatibilidade surgem antes do treino. Os erros de orçamento ou aceitação mantêm os relatórios e os critérios por cumprir. Uma falha ao parar processos ou gravar um ponto de controlo continua a ser uma falha até a limpeza segura ser confirmada.

Um método concluído com sucesso devolve o dicionário documentado. Se o objetivo não for atingido, é lançado o erro correspondente depois de guardar o relatório.
Nunca registe credenciais, cabeçalhos de autorização, o ambiente completo ou exemplos de treino privados.
Não transforme todas as exceções em novas tentativas automáticas. Consulte primeiro o estado da execução e do serviço.

Erros Python e correspondência dos códigos de saída CLI
Campo ou interface	Tipo ou resultado	Predefinição ou código de saída	Comportamento e validação
`ConfigurationError`	`TrainingError`	`2`	Esquema, argumento, caminho ou estado inválido, ou substituição não suportada. Corrija os dados antes de tentar novamente.
`CompatibilityError`	`TrainingError`	`3`	Adaptador, modelo, hardware, precisão, distribuição ou formato não suportado.
`AuthenticationError`	`TrainingError`	`4`	Chave em falta/expirada, autorização recusada ou partilha com o professor proibida; nunca inclua segredos na mensagem.
`BudgetExceededError`	`TrainingError`	`5`	Um orçamento finito terminou antes da aceitação. Preserve um checkpoint válido e os critérios por cumprir.
`EvaluationFailedError`	`TrainingError`	`6`	Critérios obrigatórios falharam, a melhoria estagnou ou a regressão persistiu. Preserve o relatório de avaliação.
`CheckpointError`	`TrainingError`	`7`	Estado de recuperação inválido, incompleto ou incompatível. Nunca force a retoma.
`CancellationError`	`TrainingError`	`7`	Não foi possível confirmar a terminação segura dos processos próprios; mantenha a limpeza em aberto.
`ExportError`	`TrainingError`	`7`	Artefacto não suportado ou inválido, caminho inseguro ou falha na soma de verificação; não o entregue.
`TrainingError`	`Exception`	`7`	Falha geral de treino. Os erros documentados do projeto herdam desta classe; preserve os diagnósticos expurgados.

import os
from fusionpointai_training import TrainingProject
from fusionpointai_training.errors import (
    AuthenticationError, BudgetExceededError, CompatibilityError,
    ConfigurationError, EvaluationFailedError, TrainingError,
)

try:
    project = TrainingProject.from_file(
        "./german-project/training.json",
        api_key=os.environ.get("FUSIONPOINTAI_API_KEY", ""),
    )
    project.plan(dry_run=True)
    project.run()
    result = project.evaluate(split="test")
except (ConfigurationError, CompatibilityError):
    print("Correct the configuration before starting a new run.")
except AuthenticationError:
    print("Check access without logging the key.")
except BudgetExceededError:
    print("Preserve the checkpoint. A larger approved budget requires a new plan.")
except EvaluationFailedError:
    print("Preserve failed criteria; do not publish this model as accepted.")
except TrainingError:
    print("Inspect redacted diagnostics; do not blindly repeat a write.")
# CancellationError, CheckpointError and ExportError also inherit TrainingError.

from fusionpointai_training import register_evaluator

def category_match(prediction, target, row):
    return float(prediction.strip().casefold() == target.strip().casefold())

register_evaluator("category_match", category_match, version="1")
# Register before project.plan() in the same Python process.
# In rubric.json: "metric": "category_match", "minimum_score": 0.85
# This scorer measures category equality, not open-ended semantic correctness.

Uma API de projeto, um único motor subjacente

Utilizar o mesmo motor a partir de Python

Consultar resultados estruturados

Tratar as falhas sem as ocultar

Continue o fluxo de trabalho