[feat]Support Multi-Layers eagle.

[Ximingwang-09]

Motivation

https://arxiv.org/pdf/2505.07858 this paper has found Draft Model Layer Scaling Law (Theorem 1.2)
A log-linear relationship exists between the draft model’s decoder layer count ((D)) and speculative decoding acceptance rate, defined as:

• (D): Decoder layer count of the draft model (tested 1–10 layers, ~138M–413M params; other hyperparameters fixed for control).
• Validation: Consistent across LLMs (Llama2/3, Vicuna, Qwen2.5) and benchmarks (MT-bench, HumanEval, GSM8K).

Gains from More Decoder Layers

• Steady acceptance rate growth: Rises quasi-linearly with log-scaled (D) (e.g., improves on code generation, math reasoning, and summarization tasks).
• Sustained optimization: No plateau observed up to 10 layers
• Indirect throughput boost: Higher acceptance reduces verification re-computation, pairing with optimal (top_k) to lift throughput (e.g., Scylla achieves 2× throughput vs. EAGLE2).

Modifications

Related Issues

Accuracy Test

TBD

Benchmark & Profiling

Checklist

• Format your code according to the Code Formatting with Pre-Commit.
• Add unit tests as outlined in the Running Unit Tests.
• Update documentation / docstrings / example tutorials as needed, according to Writing Documentation.
• Provide throughput / latency benchmark results and accuracy evaluation results as needed, according to Benchmark and Profiling and Accuracy Results.
• For reviewers: If you haven't made any contributions to this PR and are only assisting with merging the main branch, please remove yourself as a co-author when merging the PR.
• Please feel free to join our Slack channel at https://sgl-fru7574.slack.com/archives/C09784E3EN6 to discuss your PR.

[gemini-code-assist]

Summary of Changes

Hello @Ximingwang-09, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces significant architectural changes to the eagle model, specifically enhancing its support for multi-layer decoder configurations. This modification is motivated by recent research indicating that increasing the number of decoder layers in draft models can substantially improve speculative decoding acceptance rates and overall throughput. The changes involve refactoring the model to dynamically initialize and manage layer-specific key-value caches and iterating through multiple decoder layers during the forward pass, thereby allowing the eagle model to leverage the benefits of deeper draft models.

Highlights

• Multi-Layer Support for EAGLE Model: The core change enables the eagle model to utilize multiple decoder layers, transitioning from a single midlayer to an iterable layers module list, allowing for deeper draft models.
• Dynamic Cache Initialization: The cache_hidden structure is now dynamically initialized based on the number of hidden layers, ensuring proper and scalable caching for multi-layer configurations within the sdpa attention backend.
• Layer-Specific Key-Value Caching: LlamaAttention and LlamaDecoderLayer now accept and utilize a layer_idx parameter to correctly manage key-value caches for each individual layer, which is essential for the proper functioning of multi-layer models.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces support for multi-layer draft models in Eagle, which is a valuable enhancement based on recent research. The implementation is largely on the right track, but I've identified a few critical issues that will prevent the code from executing correctly. Specifically, there are incorrect usages of getattr on dictionaries in specforge/core/eagle3.py that will lead to AttributeErrors. Additionally, in specforge/modeling/draft/llama3_eagle.py, the cache handling for the new multi-layer architecture is flawed: the cache is indexed incorrectly in the backbone method, which will cause a TypeError, and the forward method has similar indexing issues along with incorrect cache initialization. I've provided detailed comments and suggestions to address these blocking issues.