speculators.convert.eagle

Eagle 检查点转换工具。

模块

eagle3_converter –

具有 loguru 日志记录的 Eagle-3 检查点转换器。
eagle3_legacy_model –

EAGLE-3 的旧模型实现。此模型已弃用，将在
eagle_converter –

具有 loguru 日志记录的 Eagle 检查点转换器。
utils –

用于检查点转换操作的实用函数。

类

EagleConverter –

将 Eagle/HASS 检查点转换为 speculators 格式的转换器。

EagleConverter

将 Eagle/HASS 检查点转换为 speculators 格式的转换器。

此转换器处理将 Eagle 风格的检查点（包括 HASS 变体）转换为标准化的 speculators 格式。它支持自动功能检测、权重重新映射和可选验证。

:示例

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

方法

convert –

将 Eagle 检查点转换为 speculators 格式。

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

将 Eagle 检查点转换为 speculators 格式。

此方法协调完整的转换过程

确保检查点在本地可用
加载原始配置和权重
如果未明确指定（layernorms、fusion bias），则自动检测功能
构建 speculators 配置
处理和重新映射权重
保存转换后的检查点
通过运行前向传播来可选地验证结果

:示例

>>> # 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
... )

参数

input_path
(str | Path) –

Eagle 检查点路径（本地或 HuggingFace ID）
output_path
(str | Path) –

保存转换后的检查点的位置
base_model
(str) –

基础模型名称（例如，meta-llama/Llama-3.1-8B-Instruct）
fusion_bias
(bool, 默认值: False ) –

启用融合偏差（如果未指定，则自动检测）
layernorms
(bool, 默认值: False ) –

启用额外的层归一化（如果未指定，则自动检测）
validate
(bool, 默认值: True ) –

是否验证转换后的检查点
cache_dir
(str | Path | None, 默认值: None ) –

可选的下载缓存目录

源代码位于 speculators/convert/eagle/eagle_converter.py

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)

speculators.convert.eagle

EagleConverter

convert

`input_path`

`output_path`

`base_model`

`fusion_bias`

`layernorms`

`validate`

`cache_dir`