# PR #24058 完整报告

- 仓库：`sgl-project/sglang`
- 标题：debug followup
- 合并时间：2026-04-29 23:03
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/24058

---

# 执行摘要

- 一句话：为 Mistral Medium 3.5 添加 EAGLE 推测解码支持
- 推荐动作：建议精读 `mistral_eagle.py` 和 `mistral_utils.py` 中的配置分支设计，了解如何利用已有的 Llama EAGLE 框架支持新模型。该 PR 展示了 weight name remapping 和 quant_config 传递的实践，值得参考。

# 功能与动机

Mistral Medium 3.5 官方提供了 EAGLE draft 模型，SGLang 此前不支持该模型的推测解码。本 PR 旨在利用已有的 Llama EAGLE 基础设施，快速为 Mistral GQA 模型添加 EAGLE 支持，从而提升推理吞吐量，尤其是在低并发延迟敏感场景下。

# 实现拆解

1. **新增 Mistral EAGLE 模型类 **(`python/sglang/srt/models/mistral_eagle.py`)：新建 `MistralEagleModel` 和 `MistralForCausalLMEagle`，继承自 `nn.Module` 和 `LlamaForCausalLMEagle`。其核心差异在于：使用标准 `LlamaDecoderLayer`（而非 layernorm-less 变体）以匹配 Mistral checkpoint 中的 `attention_norm`；使用 `RowParallelLinear` 作为融合层以加载 FP8 权值；实现 `_remap_mistral_to_llama` 将 Mistral 原生权重名映射到 SGLang 格式。
2. **修改配置适配逻辑 **(`python/sglang/srt/utils/hf_transformers/mistral_utils.py`)：在 `adapt_config_dict` 中引入 `is_mla_eagle` 判断，将原 `is_eagle and not is_moe` 分支拆分为 MLA Eagle（走 `MistralLarge3ForCausalLMEagle`）和 GQA Eagle（走 `MistralForCausalLMEagle`，model_type=mistral）。同时更新 `is_mistral_model` 函数，使得包含 'mistral' 和 'eagle' 的模型名也能触发自定义配置解析。
3. **为 llava 添加 embed/head 访问接口 **(`python/sglang/srt/models/llava.py`)：新增 `get_embed_and_head` 和 `set_embed_and_head` 方法，委托给内部的 `language_model`，以便 EAGLE 框架可以与目标模型共享 embed 和 lm_head。
4. **更新交互式部署示例 **(`docs_new/src/snippets/autoregressive/mistral-medium-3-5-deployment.jsx`)：在选项中加入 `speculative` 开关，启用后自动添加 `--dtype bfloat16` 和 EAGLE 相关参数。
5. **更新 cookbook 文档 **(`docs_new/cookbook/autoregressive/Mistral/Mistral-Medium-3.5.mdx`)：新增第 3.3 节，详细说明 EAGLE 的配置命令、注意事项（如必须指定 `--dtype bfloat16`）以及内存开销。

关键文件：
- `python/sglang/srt/models/mistral_eagle.py`（模块 模型层；类别 source；类型 data-contract；符号 MistralEagleModel, __init__, forward, MistralForCausalLMEagle）: 新增文件，包含核心 EAGLE draft 模型实现，是 PR 的核心变更。
- `python/sglang/srt/models/llava.py`（模块 模型层；类别 source；类型 data-contract；符号 get_embed_and_head, set_embed_and_head）: 新增 get_embed_and_head / set_embed_and_head 方法以实现 embed/head 共享，是实现 EAGLE 的必要接口。
- `python/sglang/srt/utils/hf_transformers/mistral_utils.py`（模块 配置适配；类别 source；类型 core-logic；符号 adapt_config_dict, is_mistral_model）: 配置适配层新增 GQA Eagle 分支，区分 MLA 和 GQA 两种 Eagle 模型，是正确加载 Mistral Medium 3.5 Eagle 的关键。
- `docs_new/src/snippets/autoregressive/mistral-medium-3-5-deployment.jsx`（模块 文档；类别 infra；类型 core-logic）: 交互式部署示例新增 EAGLE 开关，方便用户生成带推测解码的启动命令。
- `docs_new/cookbook/autoregressive/Mistral/Mistral-Medium-3.5.mdx`（模块 文档；类别 infra；类型 core-logic）: cookbook 文档新增 EAGLE 部署说明和注意事项，是用户使用的官方指南。

关键符号：MistralEagleModel.__init__, MistralEagleModel.forward, MistralForCausalLMEagle.load_weights, MistralForCausalLMEagle._remap_mistral_to_llama, adapt_config_dict, is_mistral_model, get_embed_and_head, set_embed_and_head

## 关键源码片段

### `python/sglang/srt/models/llava.py`

新增 get_embed_and_head / set_embed_and_head 方法以实现 embed/head 共享，是实现 EAGLE 的必要接口。

```python
# python/sglang/srt/models/llava.py (partial)
    def get_embed_and_head(self):
        # Spec-decode plumbing: expose the LM's embed/head so the EAGLE draft
        # can share them with the target. self.language_model is a Llama-family
        # CausalLM that defines this method.
        return self.language_model.get_embed_and_head()

    def set_embed_and_head(self, embed, head):
        self.language_model.set_embed_and_head(embed, head)

```

### `python/sglang/srt/utils/hf_transformers/mistral_utils.py`

配置适配层新增 GQA Eagle 分支，区分 MLA 和 GQA 两种 Eagle 模型，是正确加载 Mistral Medium 3.5 Eagle 的关键。

```python
# python/sglang/srt/utils/hf_transformers/mistral_utils.py (partial)
    is_eagle = "eagle" in model.lower()
    is_mla_eagle = is_eagle and any(
        config_dict.get(k) is not None
        for k in ("kv_lora_rank", "q_lora_rank", "v_head_dim")
    )
    if is_eagle and not is_moe and is_mla_eagle:
        # Dense MLA EAGLE draft model (e.g. Mistral Small 4 EAGLE).
        config_dict["model_type"] = "deepseek_v3"
        config_dict["architectures"] = ["MistralLarge3ForCausalLMEagle"]
        # ... MoE dummy fields ...
    elif is_eagle and not is_moe:
        # Dense GQA EAGLE draft model (e.g. Mistral Medium 3.5 EAGLE).
        config_dict["architectures"] = ["MistralForCausalLMEagle"]
        config_dict["model_type"] = "mistral"
        config_dict["rope_is_neox_style"] = False
        # Clean up MLA keys that might be None to avoid shadowing defaults
        for mla_key in (
            "q_lora_rank",
            "qk_rope_head_dim",
            "qk_nope_head_dim",
            "kv_lora_rank",
            "v_head_dim",
        ):
            if config_dict.get(mla_key) is None:
                config_dict.pop(mla_key, None)

```

# 评论区精华

该 PR 没有 review 评论，变更直接合并，可能是内部快速跟进。

- 暂无高价值评论线程

# 风险与影响

- 风险：
 1. **配置兼容性**：`mistral_utils.py` 中增加的条件分支可能影响其他 Mistral 模型的加载，尤其是之前被归类为 MLA Eagle 的模型（如 Mistral Small 4）。需要确保 `is_mla_eagle` 的检测键（`kv_lora_rank` 等）在旧 checkpoint 中不存在时才走 GQA 分支。
 2. **embed/head 共享**：`llava.py` 新增的方法依赖于 `language_model` 具有 `get_embed_and_head` 和 `set_embed_and_head`，如果 `language_model` 不是 Llama-family 模型则会失败。当前 llava 的 language_model 通常是 Llama，风险较低。
 3. **文档准确性**：cookbook 中给出的 docker 镜像标签（`dev-mistral-medium-3.5`）尚未在 `latest` 中，用户可能用到过时版本。
 4. **缺少测试**：没有新增的单元测试或集成测试，回归风险主要通过人肉验证。
 - 影响：对用户：支持 Mistral Medium 3.5 的 EAGLE 推测解码，提升延迟性能。对系统：新增一个模型文件，修改两个共享模块（mistral_utils 和 llava），影响范围较小。对团队：为后续添加其他 Mistral EAGLE 模型（如 Mistral Small 4）提供了可复用的模式。影响程度中等。
 - 风险标记：配置分支影响其他 Mistral 模型 , llava 接口依赖隐含假设 , 缺少单元测试 , 文档中 Docker 镜像标签非稳定

# 关联脉络

- PR #24027 Bugfix: 同一作者之前的 PR，修复了 Mistral GQA 相关问题，与本 PR 都涉及 mistral_utils.py 和 mistral_eagle.py（新增）。
- PR #23890 [spec decoding] add extra attribute 'spec_hidden_size': EAGLE 相关的基础设施变更，修改了多处 speculative 文件，为本 PR 中的 EAGLE 支持提供铺垫。