feat: Add generic Eagle-3 speculators support

- Updated speculators config detection to check for speculators_model_type key
- Support both eagle and eagle3 in is_speculators_eagle_config
- Handle Eagle-3 specific config fields (draft_vocab_size, target_hidden_size)
- Infer target_hidden_size from transformer config if not provided
- Skip non-existent weights in llama_eagle to handle HASS models gracefully
- Eagle-3 models don't need weight translation (already use correct names)

This enables support for:
- nm-testing/eagle3-llama3.1-8b-instruct-speculators
- nm-testing/EAGLE3-LLaMA3.3-Instruct-70B-speculators

While maintaining backward compatibility with Eagle-1 models.

Signed-off-by: rtuli@redhat.com

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Rahul Tuli <rtuli@redhat.com>

Author: rahul-tuli

vllm/model_executor/models/llama_eagle.py

@@ -135,6 +135,10 @@ def load_weights(self, weights: Iterable[tuple[str,
                     "embed_tokens." in name:
                     continue
 
+                # Skip weights that don't exist in the model
+                if name not in params_dict:
+                    continue
+                    
                 param = params_dict[name]
                 weight_loader = getattr(param, "weight_loader",
                                         default_weight_loader)

vllm/transformers_utils/configs/speculators_eagle.py

@@ -33,7 +33,8 @@ def from_pretrained(
         config_dict, _ = cls.get_config_dict(pretrained_model_name_or_path, **kwargs)
 
         # Check if this is a speculators format config
-        if config_dict.get("speculators_model_type") != "eagle":
+        speculators_type = config_dict.get("speculators_model_type")
+        if speculators_type not in ["eagle", "eagle3"]:
             # Not a speculators config, use standard loading
             return super().from_pretrained(pretrained_model_name_or_path, **kwargs)
 
@@ -47,31 +48,56 @@ def _convert_speculators_to_vllm(cls, speculators_config: dict) -> dict:
         """
         Convert speculators Eagle config format to vLLM format.
         
-        Speculators format:
-        {
-            "speculators_model_type": "eagle",
-            "transformer_layer_config": {...},
-            "layernorms": true/false,
-            "fusion_bias": true/false
-        }
-        
-        vLLM format:
-        {
-            "model_type": "eagle",
-            "model": {...},
-            "eagle_fc_bias": true/false,
-            "truncated_vocab_size": vocab_size
-        }
+        Supports both Eagle and Eagle-3 models based on speculators_model_type.
         """
+        speculators_type = speculators_config.get("speculators_model_type", "eagle")
+        
         # Extract transformer config
         transformer_config = speculators_config.get("transformer_layer_config", {})
 
-        # Handle layernorms flag
-        if speculators_config.get("layernorms", False):
-            transformer_config["add_para_norm"] = True
-            # Ensure skip flags are set correctly for extra layernorms
-            transformer_config["skip_prenorm"] = False
-            transformer_config["skip_output_norm"] = False
+        # Build base vLLM config
+        vllm_config = {
+            "model_type": "eagle",
+            "model": transformer_config,
+            "method": speculators_type,  # Use speculators_model_type as method
+            "num_lookahead_tokens": 5,  # Default number of speculative tokens
+        }
+        
+        # Handle version-specific config
+        if speculators_type == "eagle":
+            # Eagle-1 specific handling
+            # Handle layernorms flag
+            if speculators_config.get("layernorms", False):
+                transformer_config["add_para_norm"] = True
+                # Ensure skip flags are set correctly for extra layernorms
+                transformer_config["skip_prenorm"] = False
+                transformer_config["skip_output_norm"] = False
+            
+            # Eagle-1 specific fields
+            vllm_config["eagle_fc_bias"] = speculators_config.get("fusion_bias", False)
+            vllm_config["truncated_vocab_size"] = transformer_config.get("vocab_size")
+            vllm_config["architectures"] = ["EAGLEModel"]
+            
+        elif speculators_type == "eagle3":
+            # Eagle-3 specific handling
+            # Copy Eagle-3 specific fields from speculators config
+            if "draft_vocab_size" in speculators_config:
+                vllm_config["draft_vocab_size"] = speculators_config["draft_vocab_size"]
+            
+            # Handle target_hidden_size - if not provided, it should be set by vLLM
+            # based on the target model, but we can try to infer from transformer config
+            if "target_hidden_size" in speculators_config and speculators_config["target_hidden_size"] is not None:
+                vllm_config["target_hidden_size"] = speculators_config["target_hidden_size"]
+            else:
+                # Use the draft model's hidden size as target_hidden_size
+                # This will be the same as the target model's hidden size
+                vllm_config["target_hidden_size"] = transformer_config.get("hidden_size", 4096)
+                
+            if "norm_before_residual" in speculators_config:
+                vllm_config["norm_before_residual"] = speculators_config["norm_before_residual"]
+            
+            # Eagle-3 uses different architecture
+            vllm_config["architectures"] = ["Eagle3LlamaForCausalLM"]
 
         # Ensure transformer config has required fields
         if "architectures" not in transformer_config:
@@ -82,25 +108,13 @@ def _convert_speculators_to_vllm(cls, speculators_config: dict) -> dict:
             else:
                 transformer_config["architectures"] = [arch]
 
-        # Build vLLM config
-        vllm_config = {
-            "model_type": "eagle",
-            "model": transformer_config,
-            "eagle_fc_bias": speculators_config.get("fusion_bias", False),
-            "truncated_vocab_size": transformer_config.get("vocab_size"),
-            "method": speculators_config.get("speculators_model_type", "eagle"),  # Use speculators_model_type
-            "num_lookahead_tokens": 5,  # Default number of speculative tokens for Eagle
-        }
-        
         # Preserve any additional fields that might be needed
         for key, value in speculators_config.items():
             if key not in ["speculators_model_type", "transformer_layer_config", 
-                          "layernorms", "fusion_bias", "architectures"]:
+                          "layernorms", "fusion_bias", "architectures",
+                          "draft_vocab_size", "target_hidden_size", "norm_before_residual"]:
                 vllm_config[key] = value
 
-        # Set architectures for vLLM
-        vllm_config["architectures"] = ["EAGLEModel"]
-        
         return vllm_config
 
 
@@ -111,6 +125,8 @@ def is_speculators_eagle_config(config_path: Union[str, os.PathLike]) -> bool:
     try:
         # Use PretrainedConfig to load from both local and HF paths
         config_dict, _ = PretrainedConfig.get_config_dict(config_path)
-        return config_dict.get("speculators_model_type") == "eagle"
+        # Check for speculators format by looking for speculators_model_type key
+        return "speculators_model_type" in config_dict and \
+               config_dict.get("speculators_model_type") in ["eagle", "eagle3"]
     except:
         return False