> This page is for version Nightly (default).
> For other versions, use one of these documentation indexes:
> - Nightly (default): https://docs.nvidia.com/nemo/automodel/nightly/llms.txt
> - Latest: https://docs.nvidia.com/nemo/automodel/latest/llms.txt
> - 0.7.0 · 26.10: https://docs.nvidia.com/nemo/automodel/v0.7/llms.txt
> - 0.5.0 · 26.06: https://docs.nvidia.com/nemo/automodel/v0.5/llms.txt
> - 0.4.0 · 26.04: https://docs.nvidia.com/nemo/automodel/v0.4/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/automodel/llms.txt.

# nemo_automodel.recipes.speculative_decoding.train_eagle1

EAGLE-1 / EAGLE-2 training recipe for Llama-style dense LLMs (Llama, Phi-3, Qwen3) and MoE backbones (Qwen3-MoE).

## Module Contents

### Classes

| Name                                                                                               | Description                                                                                                |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [`TrainEagle1Recipe`](#nemo_automodel-recipes-speculative_decoding-train_eagle1-TrainEagle1Recipe) | Recipe for EAGLE-1 training on Llama-style dense LLMs (Llama, Phi-3, Qwen3) and MoE backbones (Qwen3-MoE). |

### Functions

| Name                                                                                                     | Description                                                          |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [`_build_feature_noise`](#nemo_automodel-recipes-speculative_decoding-train_eagle1-_build_feature_noise) | Build the EAGLE-1/2 augmentation from the recipe's fixed-width knob. |
| [`main`](#nemo_automodel-recipes-speculative_decoding-train_eagle1-main)                                 | Entrypoint for `TrainEagle1Recipe`.                                  |

### Data

[`logger`](#nemo_automodel-recipes-speculative_decoding-train_eagle1-logger)

### API

```python
class nemo_automodel.recipes.speculative_decoding.train_eagle1.TrainEagle1Recipe(
    cfg
)
```

**Bases:** [SpecDecodeRecipeBase](/nemo/automodel/nemo-automodel/nemo_automodel/recipes/speculative_decoding/_spec_recipe_base#nemo_automodel-recipes-speculative_decoding-_spec_recipe_base-SpecDecodeRecipeBase)

Recipe for EAGLE-1 training on Llama-style dense LLMs (Llama, Phi-3, Qwen3) and MoE backbones (Qwen3-MoE).

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.TrainEagle1Recipe._compute_metrics(
    batch: dict[str, torch.Tensor]
)
```

Run the frozen target and the draft over one micro-batch.

**Parameters:**

**`batch`** `dict[str, torch.Tensor]`

Dataloader batch whose tensors are already on `self.device`.
Carries `input_ids` / `attention_mask` / `loss_mask`, each
of shape \[batch, sequence], plus any packing metadata.

---

**Returns:**

EagleStepMetrics for this micro-batch. Subclasses that feed the draft

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.TrainEagle1Recipe._finalize_setup(
    recipe_cfg,
    target_path: str,
    wandb_name_prefix: str
) -> None
```

Build the optimizer, schedule, checkpointer, and logging around a ready trainer module.

Runs once `self.trainer_module` / `self.draft_model` / the dataloaders
exist, so recipes that assemble those differently (e.g. ViSpec's VLM
target) share the rest of `setup()` instead of copying it.

**Parameters:**

**`recipe_cfg`**

The `recipe_args` config node.

---

**`target_path`** `str`

Target model id or path, used for checkpoint metadata
and the default W\&B run name.

---

**`wandb_name_prefix`** `str`

Prefix for the default W\&B run name.

---

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.TrainEagle1Recipe._load_extra_state(
    ckpt_dir: str
) -> None
```

Restore EAGLE-recipe-specific scalars. Subclasses extend this.

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.TrainEagle1Recipe._loss_components(
    metrics
) -> dict[str, float]
```

Return the per-term losses this recipe logs alongside the total.

**Parameters:**

**`metrics`**

The step metrics returned by `_compute_metrics`.

---

**Returns:** `dict[str, float]`

Mapping of log-suffix to scalar value, logged as `train/<key>`.

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.TrainEagle1Recipe._run_eval()
```

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.TrainEagle1Recipe._save_extra_state(
    path: str,
    epoch: int
) -> None
```

Persist EAGLE-recipe-specific scalars. Subclasses extend this.

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.TrainEagle1Recipe.run_train_validation_loop()
```

Run the training loop.

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.TrainEagle1Recipe.setup()
```

Build target model, draft model, data, optimizer, and trainer module.

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1._build_feature_noise(
    half_width: float
) -> nemo_automodel.components.speculative.eagle.core_v12.FeatureNoiseConfig | None
```

Build the EAGLE-1/2 augmentation from the recipe's fixed-width knob.

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.main(
    config_path: str | None = None
)
```

Entrypoint for `TrainEagle1Recipe`.

```python
nemo_automodel.recipes.speculative_decoding.train_eagle1.logger = logging.getLogger(__name__)
```