Skip to main content
Training guide chapters All documentation

Create and run a training project

Install SDK 0.2.0, configure a project, review its plan and train a local model.

Training guide chapters

Commands and code stay in English in every language. Replace uppercase placeholders with values from your own account and paid job; do not paste real keys into shared notebooks or logs.

Create and run a project

Inspect the plan and evaluation before using the local artifact.
  1. Install Python environment
  2. Configure Model, data and rubric
  3. Plan Compatibility and budgets
  4. Train Local optimization
  5. Inspect Evaluation and artifact

Prepare your environment

Use Python 3.10 or later in a dedicated virtual environment. Install the training extra and a runtime-compatible PyTorch build. TrainingProject uses an existing Transformers causal-language-model adapter with SFT, LoRA or QLoRA capability checks. You need an account API key, active paid reference access for teacher operations, a compatible local model, approved data and enough storage. Selecting a runtime does not provision hardware.

  • The base package provides TrainingClient and the project API; the train extra installs local model-training dependencies.
  • Keep API keys in the runtime secret environment, not in project files or command arguments.
  • QLoRA requires a compatible CUDA runtime and quantization dependencies.
Example · bash 
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
# Install the GPU-compatible PyTorch build for your runtime first.
python -m pip install 'fusionpointai-training[train] @ https://fusionpointai.com/downloads/fusionpointai-training.zip'
# API-only use without local training dependencies:
# python -m pip install 'fusionpointai-training @ https://fusionpointai.com/downloads/fusionpointai-training.zip'

Configure and review the project

Create a project directory, prepare training, validation and final-test JSONL files, then edit training.json and rubric.json. Set the local student model path, provider and included reference_model_id. The plan validates the configuration, model compatibility, data fingerprints, sharing policy, budgets and outputs without changing weights or calling the teacher.

  • Use schema_version 1.0; this is the configuration schema, not the package version.
  • Use project-relative paths that resolve inside the project root.
  • A run needs a new output directory; resume is a separate operation with strict fingerprint checks.
Example · bash 
# Enter the key using a secure runtime secret facility or this history-safe prompt.
read -rs -p 'FusionPointAI API key: ' FUSIONPOINTAI_API_KEY
export FUSIONPOINTAI_API_KEY
printf '\n'
python --version
fpai-training --version
# After the project run, clear the shell value: unset FUSIONPOINTAI_API_KEY
Example · json 
{
  "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"}
}
Example · python 
import os
from fusionpointai_training import TrainingProject

project = TrainingProject.from_file(
    "./support-project/training.json",
    api_key=os.environ["FUSIONPOINTAI_API_KEY"],
)
plan = project.plan(dry_run=True)
print("Topics:", plan["topics"], "Budgets:", plan["budgets"])
result = project.run()
print("Run:", result["run_id"], result["status"], result["stop_reason"])
evaluation = project.evaluate(split="test")
print("Accepted:", evaluation["accepted"], evaluation["report_path"])
artifact = project.export(format="safetensors")
print("Artifact:", artifact["artifact_path"], artifact["sha256"])

Check evaluation and the local artifact

Training runs an untouched-model baseline and a final evaluation on local held-out rows. The reports record measured criteria, regressions, fingerprints, budgets and unmet requirements. Export validates a local safetensors model or adapter package and writes a manifest. An adapter still needs its exact pinned base model and tokenizer. A successful run does not guarantee task quality beyond the measured rubric.

  • Keep baseline and final held-out files separate from training and teacher inputs.
  • Inspect evaluation-report.json and artifact-manifest.json before using outputs.
  • Export does not upload a model or deploy production inference.
Example · bash 
cat ./support-project/runs/support-001/training-report.json
cat ./support-project/runs/support-001/evaluation-report.json
cat ./support-project/runs/support-001/artifact-manifest.json
sha256sum ./support-project/runs/support-001/exports/safetensors/artifact-manifest.json
# Compare the digest with the value returned by project.export().
# Adapter exports also require the matching base model and tokenizer.