> ## Documentation Index
> Fetch the complete documentation index at: https://fireworks.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# The Cookbook

> Overview of the Training API cookbook: ready-to-run recipes for supervised fine-tuning, DPO, GRPO reinforcement learning, and distillation on Fireworks.

## What is the Cookbook?

The [Fireworks Cookbook](https://github.com/fw-ai-external/cookbook/tree/main/training) is a collection of training recipes and utilities built on top of the [Training API](https://fireworks.ai/docs/fine-tuning/training-api/introduction.md). It provides config-driven training loops that handle trainer provisioning, data loading, tokenization, gradient accumulation, checkpointing, and cleanup automatically.

The cookbook is **optional** — everything it does can be done with the API directly. Use the cookbook when you want a working training loop quickly; use the API when you need full control.

> [!TIP]
>
> New to training on Fireworks? [Cookbook: Muse Glimmer First Fine-Tune](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/muse-glimmer.md) runs a free LoRA SFT job on preloaded example data and compares base versus tuned.

## Installation

Use Python 3.11 or newer. Install the published cookbook to import its recipes and utilities:

```bash theme={null}
python -m pip install --upgrade fireworks-training-cookbook
```

The distribution is [`fireworks-training-cookbook`](https://pypi.org/project/fireworks-training-cookbook/); Python imports remain `training.*`, such as `from training.recipes.sft_loop import Config, main`. It installs the Fireworks SDK and the cookbook's runtime dependencies.

The cookbook and SDK have separate release versions. Cookbook `2026.11.5.1` uses calendar versioning; SDK `1.2.31` is published as `fireworks-ai`. To reproduce those releases:

```bash theme={null}
python -m pip install "fireworks-ai[training]==1.2.31" "fireworks-training-cookbook==2026.11.5.1"
```

### Edit recipes or run source examples

Clone the [public repository](https://github.com/fw-ai-external/cookbook) when you want to modify a recipe or follow an example that runs from the checkout:

```bash theme={null}
git clone https://github.com/fw-ai-external/cookbook.git
cd cookbook
python -m pip install -e ./training
```

An editable install uses your checkout, which can include changes newer than the published PyPI release. For a reproducible source checkout, check out the matching [release tag](https://github.com/fw-ai-external/cookbook/releases/tag/cookbook-v2026.11.5.1) before installing.

### Verify the installation

```bash theme={null}
python -c "from importlib.metadata import version; import training; print(version('fireworks-training-cookbook'))"
```

This prints the installed cookbook version. With the pinned release above, it prints `2026.11.5.1`.

### Authentication

Before running a training job, set your credentials:

```bash theme={null}
export FIREWORKS_API_KEY="your-api-key"
```

### Update an existing checkout

The cookbook's canonical repository is now [`fw-ai-external/cookbook`](https://github.com/fw-ai-external/cookbook). In an existing cookbook clone, update the remote:

```bash theme={null}
cd cookbook
git remote set-url origin https://github.com/fw-ai-external/cookbook.git
```

To use PyPI releases instead of a local checkout, install the package in a fresh Python environment. To update coding-agent skills, use the [current installation commands](https://fireworks.ai/docs/fine-tuning/agent/use-with-coding-agents.md). Skills are installed from GitHub separately from the Python package.

## Available recipes

| Recipe | Module | Use case |
| - | - | - |
| **RL** *(primary, experimental)* | `training.recipes.async_rl_loop` | Reinforcement learning — you write a rollout function, and the recipe owns completion-driven rollout production, bounded off-policy admission, ready-group training submission, and weight publication. See [Cookbook RL](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/rl.md). **No backward-compatibility guarantee.** |
| **Serverless async RL** *(experimental)* | `training.recipes.experiment.async_rl_loop_serverless` | The same rollout and scheduling contract on the shared serverless training and sampling pool. See [Serverless Training](https://fireworks.ai/docs/fine-tuning/training-api/serverless.md). **No backward-compatibility guarantee.** |
| **Agentic RL integration** | Either async loop plus your rollout adapter | Multi-turn rollouts. The structured Cookbook path uses Pi, OpenCode, or Mini-SWE-Agent with Harbor and an environment-local TITO sidecar in Docker or E2B. See [Cookbook Agentic RL](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/agentic-rl.md). |
| **HUD RL training** | `hud-python/cookbooks/fireworks-rl-training` | Train a Serverless Training LoRA from one-turn HUD environment rewards. See [Fireworks x HUD RL Training](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/hud-rl-training.md). |
| **RL** *(simpler, synchronous)* | `training.recipes.rl_loop` | Synchronous on-policy GRPO scaffold — reach for it when you don't need rollout/train overlap |
| **IGPO** | `rl_loop` with `igpo.prepare_batch` | Turn-level information-gain advantages for multi-turn trajectories; see the [multi-hop example](https://github.com/fw-ai-external/cookbook/tree/main/training/examples/rl/multihop_qa). |
| **DPO** | `training.recipes.dpo_loop` | Direct preference optimization from chosen/rejected pairs. `serverless=True` uses the shared pool. |
| **SFT** | `training.recipes.sft_loop` | Supervised fine-tuning with cross-entropy loss. `serverless=True` uses the shared pool. |
| **Distillation** | `training.recipes.distillation_loop` | On-policy distillation from a frozen teacher’s sampled-token scores |
| **SDFT** | [External SDFT cookbook](https://github.com/fw-ai-external/tinker-cookbook) | Top-K self-distillation on serverless. Maintained outside this cookbook; see the [SDFT guide](https://github.com/fw-ai-external/cookbook/blob/main/training/docs/sdft.md). |
| **ORPO** | `training.recipes.orpo_loop` | Odds ratio preference optimization. The recipe runs on dedicated trainers only. |

Each recipe follows the same pattern: import `Config` and `main`, set your config, and call `main(cfg)`. Dedicated recipes attach or create trainer and deployment resources from `TrainerConfig` / `DeployConfig`. Serverless recipes attach to the shared pool and publish session-scoped sampler snapshots instead of provisioning a deployment.

All launch examples below use `trainer=TrainerConfig(training_shape_id=...)` for explicit shape selection. Cookbook recipes can also auto-select validated shapes when `training_shape_id` is unset. The main run-level trainer knob you may set alongside a shape is `replica_count` for replicated HSDP launches; reference shapes can usually be left unset because the cookbook auto-selects or uses a shared-session reference when appropriate.

If you want field-level details about what a training shape controls and what stays configurable, see [Training shapes](https://fireworks.ai/docs/fine-tuning/training-api/training-shapes.md) and the [Cookbook Reference](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/reference.md).

> [!NOTE]
>
> `InfraConfig` and the standalone `setup_infra` / `ResourceCleanup` helpers are **deprecated and removed from the recipe surface**. Recipes now take `trainer=TrainerConfig(...)` (and `deployment=DeployConfig(...)` for RL). See [Migrating from the deprecated managed infra](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/reference.md#deprecated-managed-infra-infraconfig).

## Quick example: SFT

```python theme={null}
from training.recipes.sft_loop import Config, main
from training.utils import TrainerConfig

cfg = Config(
    log_path="./sft_quickstart",
    base_model="accounts/fireworks/models/qwen3-8b",
    dataset="/path/to/training_data.jsonl",
    tokenizer_model="Qwen/Qwen3-8B",
    max_seq_len=4096,
    epochs=1,
    batch_size=4,
    trainer=TrainerConfig(
        training_shape_id="accounts/fireworks/trainingShapes/qwen3-8b-128k",
    ),
)

main(cfg)
```

## Quick example: GRPO

```python theme={null}
from training.recipes.rl_loop import Config, main
from training.utils import DeployConfig, TrainerConfig

cfg = Config(
    log_path="./grpo_quickstart",
    base_model="accounts/fireworks/models/qwen3-8b",
    dataset="/path/to/prompts.jsonl",
    max_rows=100,
    trainer=TrainerConfig(
        training_shape_id="accounts/fireworks/trainingShapes/qwen3-8b-128k",
    ),
    deployment=DeployConfig(
        deployment_id="grpo-serving",
        tokenizer_model="Qwen/Qwen3-8B",
    ),
)

main(cfg)
```

## W\&B logging

All cookbook recipes accept a `WandBConfig` to stream metrics to [Weights & Biases](https://wandb.ai):

```python theme={null}
from training.utils import WandBConfig

cfg = Config(
    # ... same config as above ...
    wandb=WandBConfig(
        entity="my-team",
        project="grpo-experiment",
        run_name="qwen3-8b-sft-v1",  # optional, auto-generated if omitted
    ),
)

main(cfg)
```

## Vision-language model support

For vision-language training, choose a supported VLM recipe, training shape, and matching tokenizer, and provide multimodal datasets with `image_url` content. See [Vision Inputs](https://fireworks.ai/docs/fine-tuning/models.md) for dataset format and examples.

## Embedding loop

The [`embedding_loop`](https://github.com/fw-ai-external/cookbook/blob/main/training/recipes/embedding_loop.py) recipe trains embedding models with contrastive or supervised embedding objectives. Use it when your base model is an embedding endpoint rather than a chat completion model.

## Next steps

* [Cookbook SFT](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/sft.md) — supervised fine-tuning
* [Cookbook DPO](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/dpo.md) — preference optimization with pairwise data
* [Cookbook RL (GRPO)](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/rl.md) — full GRPO walkthrough with reward functions
* [Cookbook Agentic RL](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/agentic-rl.md) — multi-turn trajectory, token ancestry, and session design
* [Fireworks x HUD RL Training](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/hud-rl-training.md) — train a LoRA adapter from HUD environment rewards
* [Cookbook Distillation](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/distillation.md) — on-policy distillation (OPD) and where to find top-K SDFT
* [Vision Inputs](https://fireworks.ai/docs/fine-tuning/models.md) — train VLMs with image and text data
* [Cookbook Reference](https://fireworks.ai/docs/fine-tuning/training-api/cookbook/reference.md) — all config classes and parameters


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.