Referência da API 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.

Ciclo de vida dos recursos da API

Uma cotação, uma tarefa paga e uma sessão de treino são recursos distintos.

Cotação Validar a configuração e o preço atual
Tarefa Criar e concluir o pagamento aprovado
Sessão Selecionar o ambiente de execução e a referência incluída
Preparação Produzir manifestos verificados dos conjuntos de dados
Relatório Registar o treino real e os metadados do artefacto

Autenticação e regras dos pedidos

Use HTTPS com Authorization: Bearer e uma chave de API da conta com o âmbito ai:training. Envie Accept: application/json; adicione Content-Type: application/json aos corpos JSON. Todos os recursos pertencem a uma conta. O grupo de rotas tem um limite de 30 pedidos por minuto, além de controlos adicionais quando configurados. Os IDs dos exemplos são marcadores, não recursos partilhados.

IDs de cotação, UUIDs de tarefa, IDs de sessão, IDs de modelo e IDs de artefacto são identificadores diferentes.
Após uma interrupção de rede, leia o estado atual antes de repetir uma gravação.
Não use o texto de páginas públicas nem parâmetros de consulta de preços nos pedidos à API.

export TRAINING_API='https://fusionpointai.com/api/v1/training'
# Set the key securely as shown in Quickstart.
export JOB_UUID='REPLACE_WITH_YOUR_JOB_UUID'
export SESSION_ID='REPLACE_WITH_YOUR_SESSION_ID'
curl --fail-with-body --silent --show-error "$TRAINING_API/jobs" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" -H 'Accept: application/json'

Pedidos, respostas e estado

Crie uma cotação com uma configuração elegível, crie a tarefa a partir dela e conclua o pagamento aprovado antes de abrir uma sessão. Os endpoints do projeto autorizam o acesso pago existente ao modelo de referência e permitem pedir um currículo ou lições sem criar faturas nem alterar preços. As respostas incluem configuração, referência selecionada, manifestos dos dados, passo comunicado e relatório. A preparação e os relatórios são pedidos separados; os estados da tarefa e da sessão também são distintos.

A autorização do projeto requer provider e reference_model_id; os pedidos ao modelo de referência também requerem action e objective.
Os exemplos do modelo de referência limitam-se a material de treino aprovado; as linhas de validação e teste final permanecem locais.
Os relatórios de conclusão descrevem um artefacto local real e incluem dados de integridade e avaliação que devem ser verificados.

POST /api/v1/training/quotes
reference_model_id     required eligible integer model ID
training_plan_id       required public provider-plan integer ID
mode                   automatic | advanced
objective              required string, 10..4000 characters
language               required string, at most 120 characters
performance_criteria   required string, 10..2000 characters
student_release_slug   optional eligible slug, at most 190 characters
method                 optional eligible method, at most 80 characters
dataset_megabytes      optional integer, 1..1000000
gpu_count              optional integer, 1..128
delivery               optional: artifact | hosted
execution_target       optional: fusionpointai_hosting | customer_datacenter | colab

Availability and approved plan policies can impose narrower constraints.
Do not submit price, fixed_total, currency, price_version_id or model_training.

{
  "reference_model_id": 123,
  "training_plan_id": "<INTEGER_FROM_YOUR_PROVIDER_PLAN>",
  "mode": "advanced",
  "objective": "Train a German support-message classifier.",
  "language": "German",
  "performance_criteria": "Evaluate per-class precision and recall on held-out data.",
  "student_release_slug": "<ELIGIBLE_STUDENT_RELEASE_SLUG>",
  "method": "LoRA",
  "dataset_megabytes": 8,
  "gpu_count": 1,
  "delivery": "artifact"
}

# Save the body as quote.json; replace ID placeholders with integers.
# Automatic mode omits student_release_slug and method.
curl --fail-with-body --silent --show-error "$TRAINING_API/quotes" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @quote.json
# Save {"quote":"YOUR_QUOTE_UUID"} as job.json.
# Creates a native job/invoice; this is not payment confirmation.
curl --fail-with-body --silent --show-error "$TRAINING_API/jobs" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @job.json
curl --fail-with-body --silent --show-error "$TRAINING_API/jobs/$JOB_UUID" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" -H 'Accept: application/json'

POST /api/v1/training/quotes: 201
{quote: UUID, currency: ISO_CODE, fixed_total: DECIMAL_STRING, expires_at: ISO_8601}

POST /api/v1/training/jobs: {"quote":"OWNED_QUOTE_UUID"}
201 for a newly created job; 200 when an accepted quote reuses its job.
Job fields:
id                job UUID
status            native job state, such as awaiting_payment
progress_percent  recorded progress, not an independent quality score
invoice_id        owned native invoice ID or null
created_at        ISO 8601 timestamp
completed_at      ISO 8601 timestamp or null
training_session  null or {id, status, step, delivery, verification}

GET /api/v1/training/jobs:
{data: JOB_ARRAY, current_page: INTEGER, last_page: INTEGER, per_page: 50, total: INTEGER}

This is a response-shape reference, not a fabricated live response.

# Save as session.json, using your paid job UUID and optional reference ID:
# {"job":"YOUR_PAID_JOB_UUID","runtime":"customer_datacenter","reference_model_id":123}
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @session.json
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" -H 'Accept: application/json'
# One preparation batch; inspect progress before another request.
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID/prepare" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{}'

Session response fields (shape reference, not a fabricated live result):
id                  session UUID
job                 owned job UUID
status              preparing | ready | running | evaluating | completed | failed | cancelled
configuration       approved method, student_checkpoint, sdk_training and selected reference
reference_model_id  selected integer reference ID
expires_at          ISO 8601 access expiry
step                last reported integer step
datasets[]          {split, rows, bytes, sha256}
report              current report object; event metrics live under report.last_event.metrics
delivery            runtime_local
verification        runtime_reported

curl --fail-with-body --silent --show-error \
  "$TRAINING_API/sessions/$SESSION_ID/datasets/train" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/x-ndjson' --output train.jsonl
# Use /datasets/validation for the other supported split.
sha256sum train.jsonl
# Compare bytes, rows and SHA-256 with the session manifest.
# For published server-side artifacts only, not the local SDK ZIP:
# GET /api/v1/training/jobs/{job}/artifacts/{file}

POST /api/v1/training/sessions/{session}/events
Content-Type: application/json

state         required: running | evaluating | failed
step          required integer: 0..2000
total_steps   required integer: 1..2000
metrics       optional; only loss and eval_loss, each 0..1000000
error_code    optional: training_failed | evaluation_failed | runtime_unavailable |
              dataset_invalid | report_failed

Send actual trainer observations, never sample or invented metrics.

# Build the body from a REAL SDK report; requires jq.
jq '{artifact_name:"model-package.zip",report:.completion_report}' \
  customer-model-run-001/training-report.json > completion.json
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID/complete" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @completion.json
# Cancel eligible service state, not the operating-system process:
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID/cancel" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{}'

curl --fail-with-body --silent --show-error \
  'https://fusionpointai.com/api/v1/training/projects/authorize' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data '{"provider":"openai","reference_model_id":123}'
# The response identifies the owned paid job/grant and access expiry.

curl --fail-with-body --silent --show-error \
  'https://fusionpointai.com/api/v1/training/projects/teacher' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data '{"provider":"openai","reference_model_id":123,"action":"lessons","objective":"Classify support messages into agreed categories.","topic":"ambiguous_requests","count":2,"approved_examples":["A reviewed support training example."]}'
# Send only explicitly approved training examples. Never send held-out rows.
# Curriculum action returns topics; lessons action returns text/topic examples.

import os
from fusionpointai_training import TrainingClient

client = TrainingClient(api_key=os.environ["FUSIONPOINTAI_API_KEY"])
session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
print("Session:", session["id"])
print("Status:", session["status"])
print("Last reported step:", session["step"])
# Inspection is read-only; status and step are server-reported state.

import os
from fusionpointai_training import TrainingClient

client = TrainingClient(api_key=os.environ["FUSIONPOINTAI_API_KEY"])
session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
for manifest in session["datasets"]:
    print(
        manifest["split"],
        "rows:", manifest["rows"],
        "bytes:", manifest["bytes"],
        "sha256:", manifest["sha256"],
    )
# These are server-provided manifest values, not a local integrity pass.

import os
from fusionpointai_training import TrainingClient

client = TrainingClient(api_key=os.environ["FUSIONPOINTAI_API_KEY"])
session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
server_report = session.get("report")
runtime_report = server_report.get("runtime") if isinstance(server_report, dict) else None
if (
    session.get("status") == "completed"
    and isinstance(runtime_report, dict)
    and runtime_report.get("artifact_sha256") == os.environ["LOCAL_ARTIFACT_SHA256"]
    and server_report.get("delivery") == "runtime_local"
    and server_report.get("verification") == "runtime_reported"
):
    print("Server report matches the local artifact digest.")
else:
    print("Completion is not confirmed for this local artifact.")
# Reconcile by reading state; do not repeat training or invent a result.

Erros e integração segura

Use o estado HTTP e os detalhes de validação devolvidos, em vez de presumir que todos os erros são temporários. Espere 401 para pedidos não autenticados, 403 para acesso recusado, 404 para recursos inexistentes ou que não pertencem à conta, 409 para estados incompatíveis, 422 para dados de entrada inválidos e 429 para limitação de pedidos. As falhas do fornecedor ou do ambiente de execução podem devolver outros erros. O SDK expõe APIError sem devolver a resposta bruta do serviço a montante, que poderia conter segredos.

Os eventos aceitam running, evaluating ou failed; as chaves das métricas são loss e eval_loss.
step e total_steps estão limitados a 2000; total_steps tem de ser positivo.
O corpo de complete requer artifact_name e todos os campos do relatório apresentados no exemplo.

401  Authentication missing or invalid
403  Account/key scope or access denied
404  Resource missing, non-owned or intentionally hidden
409  Invalid session transition, runtime, paid-access or model configuration
410  Writable session expired
422  Invalid request fields or completion criteria not met
429  Request rate limited
502  Upstream reference data malformed or preparation failed

Do not retry a write blindly. Read session state and inspect the response.
Keep error_code distinct from the HTTP status. Never log authorization.

POST /api/v1/training/sessions/{session}/complete
artifact_name                 safe filename ending in .zip, max 160 characters
report.training_steps         integer 1..2000
report.weights_before_sha256  lowercase SHA-256 of actual pre-training weights
report.weights_after_sha256   lowercase SHA-256 of actual changed weights
report.artifact_sha256        lowercase SHA-256 of the real local ZIP
report.artifact_bytes         integer 1..107374182400
report.eval_loss_before       finite number >0 and <=1000000
report.eval_loss_after        finite number >=0 and <=1000000
report.base_repository        pinned student repository, max 255 characters
report.base_revision          lowercase immutable 40-character revision
report.method                 SFT | LoRA | QLoRA

Values must match the approved session and actual local training.
Additional report keys are rejected. This body does not upload the ZIP.

import os
from fusionpointai_training import TrainingClient
from fusionpointai_training.errors import APIError

client = TrainingClient(
    api_key=os.environ["FUSIONPOINTAI_API_KEY"],
    timeout=30.0,
    max_get_retries=2,
)
try:
    session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
except APIError:
    # GET retries are bounded. Do not blindly retry a write after an error.
    print("Session inspection failed; check access and current server state.")
else:
    print("Status:", session["status"])
# Never print the API key, authorization headers, or response secrets.