Skip to main content
In practice, a training shape is the user-facing launch input for trainer jobs. Most users only need to choose a training shape ID such as accounts/fireworks/trainingShapes/qwen3-8b-128k and pass it to the API as training_shape_id. The fireworks account is the shared public shape catalog. Shapes published under accounts/fireworks/trainingShapes/<shape> can be referenced by all users. See the full training shapes catalog here. You do not need to know the versioned shape reference, image tag, GPU layout, or linked deployment shape ahead of time. The API resolves those details internally.

​
Concepts

Training shape. A validated trainer configuration for one base model and one training method. It fixes the GPU layout for each trainer replica and the training context limit for that model and method. Shapes exist so you do not have to size distributed training yourself. Shape ID vs. shape version. The shape ID is the stable name you pass, such as accounts/fireworks/trainingShapes/qwen3-8b-128k. Behind it sits a series of pinned versions holding the exact GPU counts, context limit, and trainer image. You pass the ID; the API resolves the validated version at launch. Training shape vs. deployment shape. A training shape configures the trainer. Each one links to a deployment shape that configures the inference instance used for RL rollouts / sampling, and on the shape path that linked shape owns the deployment’s GPU type, node count, and serving engine configuration. You normally do not name a deployment shape at all, because the API reads it from the training shape’s deploymentShapeVersion. Training method. Each shape declares one training method, either LoRA or full-parameter, and a model may offer both. Your lora_rank must agree with the method the shape declares: 0 for a full-parameter shape, a positive integer for a LoRA shape. These are not two independent settings. Changing lora_rank does not convert a shape to the other method, because the method is part of the profile the shape was validated for and it affects the GPU layout and context limit the shape carries. Read the method off the shape card before you launch. For the same model, the LoRA shape and the full-parameter shape often differ in both GPU count and maximum context, so the two are rarely interchangeable.

​
What You Need To Know

For most users, the workflow is:
  1. Pick a training shape ID from the per-model shape cards in the model catalog. In most cases this should be the full shared path accounts/fireworks/trainingShapes/<shape>.
  2. Pass it as training_shape_id to a cookbook recipe’s TrainerConfig, or to FiretitanServiceClient.from_firetitan_config(...).
  3. Let the API resolve the pinned shape version and linked deployment shape.
The shape ID is normally the only shape-specific value you set. Everything else about the shape is resolved for you. Whether you can skip the shape ID depends on which of the two paths you use:
  • Cookbook recipe. You can leave training_shape_id unset, and the recipe picks a validated shape for you from your base_model, lora_rank, and max_seq_len.
  • FiretitanServiceClient directly. Set the shape ID yourself. The recipe layer is what does the picking, so there is nothing to pick for you here.
On either path, set the shape ID yourself when you need a specific GPU layout or context limit.

​
What A Training Shape Controls

A validated shape version can pin every field below. Together these are the launch profile, and none of them are yours to set. The hardware fields size one trainer replica: acceleratorCount × nodeCount is the GPU count for a single replica. The shape resource also carries metadata that does not affect a launch: name, displayName, description, createTime, updateTime, modelType, and parameterCount. Total GPUs for a run are the shape’s per-replica GPUs multiplied by your replica count, so a 4-GPU shape launched with replica_count=2 consumes 8 GPUs. For example, qwen3-8b-128k is the full-parameter shape for Qwen 3 8B. Below is version vnuk8fdq in full. To read the same fields for the version you will actually launch on:

​
What You Can And Can’t Change

You can still configure normal training-loop fields such as:
  • lora_rank, which must match the shape’s training method
  • learning_rate
  • Trainer replica count (TrainerConfig.replica_count or trainer_replica_count)
  • Deployment replica count (DeployConfig.replica_count or replica_count)
Shape-owned infra is locked on the shape path. Do not set accelerator_type, accelerator_count, node_count, or custom_image_tag; the shape supplies all four. The linked deployment shape can be overridden through deployment_shape, but only for deployments you manage outside the normal flow.
Gradient accumulation is not a trainer-launch setting. To accumulate gradients, call forward_backward... multiple times from your client loop before a single optim_step(...); see Loss Functions. For field-level behavior and dataclass details, see the FiretitanServiceClient and Cookbook Reference.

​
Using a Training Shape

At launch, the shape ID resolves in three steps:
  1. You provide the shape ID (e.g. accounts/fireworks/trainingShapes/qwen3-8b-128k), with no version needed.
  2. The API resolves the latest validated version when the service client provisions the trainer.
  3. The API applies the linked deployment shape when you request a sampler deployment.
Pass the shape ID to the SDK-managed service client (FiretitanServiceClient):
Note: You do not need to hand-write a versioned training_shape_ref yourself. Advanced compatibility launches can still use manager-level shape refs and direct infra fields, but take that path only when you know the exact hardware and image configuration.