docs: Add comprehensive V1 engine Eagle support documentation

- Explains all changes needed for speculators Eagle models
- Details the rationale behind each modification
- Includes common questions and answers
- Provides testing examples
- Documents config translation, weight remapping, and V1 detection

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

docs/v1_engine_eagle_support.md

@@ -0,0 +1,207 @@
+# V1 Engine Support for Speculators Eagle Models
+
+This document explains the changes made to enable vLLM's V1 engine to work with speculators-converted Eagle models, including the rationale behind each change.
+
+## Overview
+
+The speculators library provides a unified framework for various speculative decoding models, including Eagle. To enable vLLM's V1 engine to work with speculators-converted Eagle models, we needed to make several key changes across configuration handling, model detection, and weight loading.
+
+## Key Changes
+
+### 1. Speculators Eagle Config Adapter (`vllm/transformers_utils/configs/speculators_eagle.py`)
+
+**What we added:**
+- A new `SpeculatorsEagleConfig` class that translates speculators format to vLLM's expected Eagle format
+- Detection function `is_speculators_eagle_config()` to identify speculators Eagle models
+- Integration into the config loading pipeline
+
+**Why:**
+- Speculators uses a different config structure than vLLM expects
+- Key differences include:
+  - `fusion_bias` → `eagle_fc_bias`
+  - `layernorms` → `model.add_para_norm`
+  - Nested `transformer_layer_config` → flattened `model` config
+- Without this translation, vLLM couldn't understand the model configuration
+
+**Implementation details:**
+```python
+# Key translations in _convert_speculators_to_vllm()
+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"),
+    "num_lookahead_tokens": 5,  # Required for Eagle
+}
+```
+
+### 2. V1 Engine Eagle Detection (`vllm/engine/arg_utils.py`)
+
+**What we changed:**
+- Added speculators Eagle detection in `_is_v1_supported_oracle()`
+- Import and use `is_speculators_eagle_config()` to detect speculators models
+
+**Why:**
+- V1 engine needs to know that Eagle is a supported speculative decoding method
+- Without this, vLLM would fall back to V0 engine with a warning
+- The original code only checked for method names, not speculators format
+
+**Implementation:**
+```python
+# In _is_v1_supported_oracle()
+elif is_speculators_eagle_config(speculative_model):
+    is_eagle_enabled = True
+```
+
+### 3. Automatic Method Detection (`vllm/config.py`)
+
+**What we added:**
+- Detection for `model_type == "eagle"` in the speculative config auto-detection
+
+**Why:**
+- The speculators config sets `model_type: "eagle"` after our translation
+- This ensures the method is properly set to "eagle" for downstream processing
+- Without this, the method would default to "draft_model" which is incorrect
+
+**Implementation:**
+```python
+elif self.draft_model_config.hf_config.model_type == "eagle":
+    self.method = "eagle"
+```
+
+### 4. Weight Name Remapping (`vllm/model_executor/models/eagle.py` and `llama_eagle.py`)
+
+**What we added:**
+- Weight name mapping to handle speculators format:
+  - `fusion_fc.weight` → `fc.weight`
+  - `fusion_fc.bias` → `fc.bias`
+  - `embedding_layernorm.weight` → `enorm.weight`
+  - `pre_lm_head_layernorm.weight` → `hnorm.weight`
+
+**Why:**
+- Speculators uses different weight names than vLLM expects
+- Without remapping, vLLM would throw `KeyError` when loading weights
+- Both `eagle.py` and `llama_eagle.py` needed updates as they handle different Eagle architectures
+
+**Implementation:**
+```python
+speculators_name_map = {
+    "fusion_fc.weight": "fc.weight",
+    "fusion_fc.bias": "fc.bias",
+    "embedding_layernorm.weight": "enorm.weight",
+    "pre_lm_head_layernorm.weight": "hnorm.weight",
+}
+
+# In load_weights()
+if name in speculators_name_map:
+    name = speculators_name_map[name]
+```
+
+### 5. Transformer Weight Handling (`llama_eagle.py`)
+
+**What we changed:**
+- Skip loading `transformer.*` weights in the Eagle head's load_weights()
+
+**Why:**
+- Speculators saves transformer layer weights (like `transformer.mlp.down_proj.weight`)
+- These are loaded through a different mechanism in vLLM's architecture
+- Attempting to load them in the head's load_weights() causes KeyError
+- They're properly loaded when the full model is assembled
+
+**Implementation:**
+```python
+elif name.startswith("transformer."):
+    # Skip transformer weights - they're loaded separately
+    continue
+```
+
+### 6. Required Config Fields
+
+**What we added:**
+- `num_lookahead_tokens: 5` in the speculators config translation
+- `method` field using `speculators_model_type`
+
+**Why:**
+- Eagle models require `num_lookahead_tokens` to specify speculation depth
+- The `method` field is required for V1 engine compatibility checks
+- Without these, model initialization would fail
+
+## Common Questions
+
+### Q: Why create a separate config adapter instead of modifying the existing Eagle config?
+
+**A:** The speculators format is fundamentally different from vLLM's native Eagle format. Creating a separate adapter:
+- Maintains backward compatibility with existing Eagle models
+- Clearly separates speculators-specific logic
+- Makes it easier to support other speculators models in the future
+- Follows the existing pattern in vLLM for handling different config formats
+
+### Q: Why do we need weight remapping in two different files?
+
+**A:** vLLM has two Eagle model implementations:
+- `eagle.py` - The standard EAGLE model
+- `llama_eagle.py` - Eagle specifically for Llama architectures (used by V1)
+
+Both need the remapping because speculators models can be loaded by either, depending on the architecture and engine version.
+
+### Q: Why skip transformer weights instead of remapping them?
+
+**A:** The transformer weights in speculators Eagle models represent the additional decoder layer. In vLLM's architecture:
+- The Eagle head is loaded separately from the main model
+- These weights are loaded when the full model is assembled
+- The exact layer index depends on the target model's layer count
+- Skipping them in the head's load_weights() prevents conflicts
+
+### Q: Why is V1 engine support important for Eagle?
+
+**A:** The V1 engine offers several advantages:
+- Better performance through improved scheduling
+- Support for features like chunked prefill
+- More efficient memory management
+- Future features will be V1-only
+
+### Q: Why set num_lookahead_tokens to 5?
+
+**A:** This is a reasonable default for Eagle models:
+- Eagle typically speculates 3-5 tokens ahead
+- Can be overridden by user configuration
+- Required field that must have a value
+- Matches common Eagle model configurations
+
+## Testing
+
+To verify the implementation works correctly:
+
+```python
+from vllm import LLM, SamplingParams
+
+# Load with speculators Eagle model
+llm = LLM(
+    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
+    speculative_config={
+        "model": "nm-testing/eagle-llama3.1-8b-instruct",
+        "num_speculative_tokens": 5,
+    },
+    trust_remote_code=True,
+    max_model_len=1024,
+)
+
+# Generate text
+output = llm.generate(["The benefits of open source software include"], 
+                      SamplingParams(temperature=0.0, max_tokens=100))
+print(output[0].outputs[0].text)
+```
+
+This should successfully load the model using the V1 engine and generate text with Eagle speculative decoding.
+
+## Summary
+
+The changes enable seamless integration of speculators-converted Eagle models with vLLM's V1 engine by:
+1. Translating configuration formats
+2. Ensuring proper model detection
+3. Remapping weight names
+4. Handling architectural differences
+5. Providing required configuration fields
+
+These changes maintain backward compatibility while extending vLLM's support for the broader ecosystem of Eagle models available through the speculators library.