Pipelines
A pipeline submits an ordered sequence of curate, train, and evaluate stages. Use one to run a repeatable training and evaluation process in one submission. A later stage can refer to an earlier stage’s output as @STAGE_NAME wherever it specifies a dataset or model. These references include a train stage’s config.dataset or warmStartModelId, an evaluate stage’s model, and the model in a model: grader. Each stage has a durable identity, so an interrupted pipeline resumes without repeating completed work.
Validate, start, read, resume, and cancel a pipeline:
akka training pipelines start -f pipeline.json --dry-run
akka training pipelines start -f pipeline.json --wait --exit-status
akka training pipelines get PIPELINE_ID
akka training pipelines resume PIPELINE_ID
akka training pipelines cancel PIPELINE_ID--dry-run runs the submission checks and prints the resolved value of each stage without starting the pipeline. Optimize refuses a stage that specifies an unknown base model or dataset. Add --show-resolved to print the resolved configuration and execution settings, including every default, for a train stage whose dataset is already registered:
akka training pipelines start -f pipeline.json --dry-run --show-resolvedA stage that references an earlier stage’s output, such as @curated, has no registered output from which to resolve defaults. --show-resolved therefore prints nothing for that stage. get reports the status of every stage. resume continues a stopped pipeline from the unfinished stage.
A pipeline that trains its own judge
The following pipeline trains a judge, gates it on its own score, and then uses it to grade a supervised run and a reinforcement run:
{
"kind": "pipeline",
"stages": [
{
"type": "train", "name": "judge", "project": "commit-judge",
"baseModel": "Qwen/Qwen3-0.6B",
"config": {"dataset": "commit-messages/judge-train",
"hyperparams": {"lora": {"rank": 8}, "optimizer": {"learningRate": 0.0001}, "training": {"epochs": 3}}}
},
{
"type": "evaluate", "name": "judge-scored",
"model": "@judge", "dataset": "commit-messages/judge-eval", "minMeanScore": 0.7
},
{
"type": "train", "name": "sft", "project": "commit-messages",
"baseModel": "Qwen/Qwen3-0.6B", "grader": "model:@judge",
"config": {"dataset": "commit-messages/train",
"hyperparams": {"lora": {"rank": 8}, "optimizer": {"learningRate": 0.0001}, "training": {"epochs": 3}}}
},
{
"type": "train", "name": "rl", "project": "commit-messages",
"baseModel": "Qwen/Qwen3-0.6B", "warmStartModelId": "@sft", "grader": "model:@judge",
"config": {"dataset": "commit-messages/train", "method": "grpo",
"rlHyperparams": {"groupSize": 4, "maxCompletionLength": 64}}
},
{
"type": "evaluate", "name": "rl-scored",
"model": "@rl", "dataset": "commit-messages/eval", "grader": "model:@judge"
}
]
}The pipeline trains the judge first and checks its score before using it to grade anything. The reinforcement stage warm-starts from the supervised adapter and uses the judge for its reward.
The descriptor
A pipeline descriptor has the following top-level fields:
| Field | Description |
|---|---|
|
|
|
The stages, in the order they run. Required. See Stages. |
|
An ID for this pipeline submission. Optimize derives the pipeline ID from it, so retrying after a dropped connection returns the pipeline started by the first request. The CLI generates a new ID for each command if the descriptor specifies none. |
|
An annotation. It is not part of the pipeline’s identity. |
Stages
Every stage has the following fields:
| Field | Description |
|---|---|
|
|
|
A name that is unique in the pipeline. Required. A later stage refers to the stage’s output as |
The curate stage
A curate stage judges each exchange in a set of uploaded sessions and keeps those that score at or above a threshold. Its output is a dataset of the retained exchanges. It has the following fields:
| Field | Default | Description |
|---|---|---|
|
none |
The uploaded sessions to read, by hash. Required. |
|
none |
The format of the sessions: |
|
|
The language of the exchanges to keep. |
|
A general data-quality instruction |
The instruction the judge scores each exchange with. The judge answers with a score from 0 to 1. |
|
0.7 |
The lowest score an exchange is kept at. From 0 to 1. |
|
none |
The system message for a kept exchange that has none of its own. Required. |
|
none |
The named dataset in the registry that the kept exchanges are registered under, such as |
|
none |
An annotation. |
The train stage
A train stage contains the fields of a run descriptor, except kind and submissionId, plus name. Every train stage names its baseModel. A pipeline that trains a judge and a policy gives each stage its own modelName, so the two are separate named models in the project’s namespace. For the run descriptor, see Training runs.
The evaluate stage
An evaluate stage has the following fields:
| Field | Description |
|---|---|
|
The model to score, by registry reference or as |
|
A selected base model to score as it is, by repository. Use it to measure the model before training. The evaluation job loads the model at the commit the catalog pins. |
|
The training project the score belongs to, by name or ID. A trained model records its training project, so set this for a |
|
The evaluation dataset. Without it, the stage scores a trained model’s training dataset, which measures reproduction rather than generalization. Required for a base model, an imported model, and a model trained on prepared token rows. |
|
The grader. Default |
|
The instructions used by a |
|
A gate. The pipeline fails when the mean score is below this value. |
|
A ceiling on the length of one scored answer. Without it, the answer length is not capped. |
|
An annotation. |
The gate includes unscored examples in its decision. It passes if the score meets the threshold with every unscored example counted as zero. It fails if the score misses the threshold with every unscored example counted as one. Otherwise, it rejects the result as undecided.