Skip to main content
Supervised Fine Tuning (SFT) trains from labeled conversation data (JSONL). Use this flow when you already have high-quality examples and want deterministic, offline updates.

​
Before You Begin

  • Config: TOML describing data paths, hyperparameters, validation strategy, and model defaults.
  • Data: One or two JSONL files where each line is a training example (optionally a validation set). Store absolute paths or let the CLI help locate them.
  • Secrets: Only SYNTH_API_KEY is required, so a lightweight .env is enough.
  • Optional helpers:
    • --dataset /path/to/train.jsonl to override whatever the config references.
    • --examples 2000 to copy the first N rows into a temporary file (useful for smoke testing before a full run).
    • Multiple .env files can be preloaded with --env-file if you switch between orgs.

​
Run the CLI

uvx synth-ai train \
  --type sft \
  --config configs/sft/instruct.toml \
  --env-file .env.sft
  1. Dataset discovery: If build_sft_payload can’t resolve a dataset, the CLI scans the config directory, datasets/, ft_data/, and repo-level folders. You can also enter a manual path when prompted.
  2. Payload build: Overrides (--dataset, --allow-experimental, --examples) are applied before validation.
  3. Validation: validate_sft_jsonl checks every row for required fields. Fix formatting issues locally before re-running.
  4. Optional truncation: When --examples is set, the CLI writes a temporary JSONL containing only the requested number of rows and points the payload at that file.

​
Upload & Job Creation

  1. Upload training data: Files are sent to POST {backend}/files. The CLI prints the returned file IDs.
  2. Wait for readiness: _wait_for_training_file polls the file endpoint (up to ~10s) so the job doesn’t start before the backend finishes processing.
  3. Create job: The CLI prints a payload preview and calls POST {backend}/learning/jobs followed by POST .../{job_id}/start.

​
Monitoring

  • Leave --poll on to stream sft.progress, validation summaries, and overall status.
  • Use --stream-format chart for a live train.loss graph; CLI mode hides orchestration noise (sft.stage, hatchet.*, etc.).
  • Adjust --poll-timeout and --poll-interval if you expect very long or very short runs.

​
Data Hygiene Checklist

  • Double-check that your JSONL is non-empty and UTF-8 encoded.
  • Keep sensitive data out of .env files; only credentials and dataset paths belong there.
  • Remove the temporary truncated file that --examples creates if you want to keep your workspace clean (the CLI attempts to delete it automatically).

​
Troubleshooting Tips

  • Upload failures usually stem from path issues or zero-byte files—verify the file exists and is readable.
  • If validation keeps failing, run uvx python scripts/check_dataset.py path/to/file.jsonl (if available) or open a few rows manually to confirm schema compliance.
  • Backend 4xx errors on job creation often indicate missing required config fields; review the payload preview printed just before the request and compare it with your config.