Skip to content

speculators.convert.eagle

Eagle checkpoint conversion utilities.

Modules:

  • eagle3_converter –

    Eagle-3 checkpoint converter with loguru logging.

  • eagle3_legacy_model –

    Legacy model implementation of EAGLE-3. This is deprecated and will be removed in the

  • eagle_converter –

    Eagle checkpoint converter with loguru logging.

  • eagle_legacy_model –

    Speculators implementations providing a unified implementation

  • utils –

    Utility functions for checkpoint conversion operations.

Classes:

  • Eagle3Converter –

    Converter for Eagle3 checkpoints to speculators format.

  • EagleConverter –

    Converter for Eagle/HASS checkpoints to speculators format.

Eagle3Converter

Converter for Eagle3 checkpoints to speculators format.

Handles weight remapping, embeddings replacement, and vLLM compatibility fixes. Produces production-ready models with standardized speculators_config metadata.

EagleConverter

Converter for Eagle/HASS checkpoints to speculators format.

This converter handles the transformation of Eagle-style checkpoints (including HASS variants) into the standardized speculators format. It supports automatic feature detection, weight remapping, and optional validation.

:Example:

>>> converter = EagleConverter()
>>> converter.convert(
...     "yuhuili/EAGLE-LLaMA3.1-Instruct-8B",
...     "./output",
...     "meta-llama/Meta-Llama-3.1-8B-Instruct"
... )

Methods:

  • convert –

    Convert an Eagle checkpoint to speculators format.

convert 

convert(
    input_path: str | Path,
    output_path: str | Path,
    base_model: str,
    fusion_bias: bool = False,
    layernorms: bool = False,
    validate: bool = True,
    cache_dir: str | Path | None = None,
) -> None

Convert an Eagle checkpoint to speculators format.

This method orchestrates the complete conversion process:

  1. Ensures the checkpoint is available locally
  2. Loads the original config and weights
  3. Auto-detects features if not explicitly specified (layernorms, fusion bias)
  4. Builds the speculators configuration
  5. Processes and remaps the weights
  6. Saves the converted checkpoint
  7. Optionally validates the result by running a forward pass

:Example:

>>> # Convert standard Eagle checkpoint
>>> converter = EagleConverter()
>>> converter.convert(
...     "yuhuili/EAGLE-LLaMA3.1-Instruct-8B",
...     "./eagle-converted",
...     "meta-llama/Meta-Llama-3.1-8B-Instruct",
...     validate=True
... )

>>> # Convert HASS checkpoint with layernorms
>>> converter.convert(
...     "nm-testing/Eagle_Speculator_Llama_3_1_8B_TTT",
...     "./hass-converted",
...     "meta-llama/Meta-Llama-3.1-8B-Instruct",
...     layernorms=True
... )

Parameters:

  • input_path

    (str | Path) –

    Path to Eagle checkpoint (local or HuggingFace ID)

  • output_path

    (str | Path) –

    Where to save converted checkpoint

  • base_model

    (str) –

    Base model name (e.g., meta-llama/Llama-3.1-8B-Instruct)

  • fusion_bias

    (bool, default: False ) –

    Enable fusion bias (auto-detected if not specified)

  • layernorms

    (bool, default: False ) –

    Enable extra layernorms (auto-detected if not specified)

  • validate

    (bool, default: True ) –

    Whether to validate the converted checkpoint

  • cache_dir

    (str | Path | None, default: None ) –

    Optional cache directory for downloads

Source code in speculators/convert/eagle/eagle_converter.py 
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def convert(
    self,
    input_path: str | Path,
    output_path: str | Path,
    base_model: str,
    fusion_bias: bool = False,
    layernorms: bool = False,
    validate: bool = True,
    cache_dir: str | Path | None = None,
) -> None:
    """
    Convert an Eagle checkpoint to speculators format.

    This method orchestrates the complete conversion process:

    1. Ensures the checkpoint is available locally
    2. Loads the original config and weights
    3. Auto-detects features if not explicitly specified (layernorms, fusion bias)
    4. Builds the speculators configuration
    5. Processes and remaps the weights
    6. Saves the converted checkpoint
    7. Optionally validates the result by running a forward pass

    :param input_path: Path to Eagle checkpoint (local or HuggingFace ID)
    :param output_path: Where to save converted checkpoint
    :param base_model: Base model name (e.g., meta-llama/Llama-3.1-8B-Instruct)
    :param fusion_bias: Enable fusion bias (auto-detected if not specified)
    :param layernorms: Enable extra layernorms (auto-detected if not specified)
    :param validate: Whether to validate the converted checkpoint
    :param cache_dir: Optional cache directory for downloads

    :Example:

        >>> # Convert standard Eagle checkpoint
        >>> converter = EagleConverter()
        >>> converter.convert(
        ...     "yuhuili/EAGLE-LLaMA3.1-Instruct-8B",
        ...     "./eagle-converted",
        ...     "meta-llama/Meta-Llama-3.1-8B-Instruct",
        ...     validate=True
        ... )

        >>> # Convert HASS checkpoint with layernorms
        >>> converter.convert(
        ...     "nm-testing/Eagle_Speculator_Llama_3_1_8B_TTT",
        ...     "./hass-converted",
        ...     "meta-llama/Meta-Llama-3.1-8B-Instruct",
        ...     layernorms=True
        ... )
    """
    logger.info(f"Converting Eagle checkpoint: {input_path}")

    local_checkpoint_path = ensure_checkpoint_is_local(input_path, cache_dir)

    eagle_config = load_checkpoint_config(local_checkpoint_path)
    weights = load_checkpoint_weights(local_checkpoint_path)
    logger.info(f"Loaded {len(weights)} weights")

    detected_fusion_bias, detected_layernorms = detect_fusion_bias_and_layernorms(
        weights
    )
    fusion_bias = fusion_bias or detected_fusion_bias
    layernorms = layernorms or detected_layernorms

    speculator_config = self._build_eagle_speculator_config(
        eagle_config, base_model, fusion_bias, layernorms
    )

    processed_weights = self._process_checkpoint_weights(weights, layernorms)

    # Save the converted checkpoint using the model's save_pretrained
    saved_path = self._save_converted_checkpoint(
        config=speculator_config, weights=processed_weights, output_dir=output_path
    )

    logger.success(f"Saved to: {saved_path}")

    if validate:
        self._validate_converted_checkpoint(saved_path, verifier_model=base_model)