Fine-tuning models

Fine-tuning adapts a model's weights to your task using labeled examples. Use it when your model needs to learn recurring distinctions from representative data. Alignment jointly optimizes instructions and model weights; fine-tuning is the part that learns from your labeled dataset.

Fine-tuning supports mo (mo-1.3.1). Mo Fast is inference-only.

Prepare your data

Create a JSONL dataset with one input state and answer per row. Every row must answer the same question ID from your model's schema:

{"state":"Checkout is unavailable","answers":{"urgent":true},"split":"train"}
{"state":"Can I change my invoice address?","answers":{"urgent":false},"split":"validation"}
{"state":"All payment attempts fail","answers":{"urgent":true},"split":"test"}

Use representative examples, consistent labels, and separate train, validation, and test partitions. Keep related or duplicate inputs in the same partition. See the dataset format for supported labels and limits.

Train your model

Choose head_only for head training or lora to train a LoRA adapter as well. For an existing model:

modaic fine-tunes create --model acme/support-priority \
  --training-path train.jsonl --task-id urgent --training-type head_only --wait

The command uploads and validates the dataset before starting training. Check the returned status and error; finishing the wait does not mean training succeeded.

Use the SDK fine-tuning guide for Python and TypeScript examples, or the CLI reference for flags, logs, and cancellation.

Evaluate and use the result

Compare the trained model against the starting version on held-out examples. Check the errors that matter for your application before adopting the result. A successful job publishes a new checkpoint to main by default. You can instead target an existing experiment branch and optionally create an immutable tag. Evaluate that branch or tag, then fast-forward main when you want to promote it.

After artifact validation, the checkpoint is selected in model.json before advisory evaluation begins. Read result.readinessAssessment on the job or readinessAssessment in model.json; held-out model quality reports passed, warning, or unknown. Evaluation infrastructure failure leaves the trained checkpoint published with unknown readiness. Runtime compatibility and serving isolation are verified before deployment rather than reported as per-model readiness. Corrupt or unloadable artifacts and identity mismatches remain hard failures.