Multi-layer Decoder for Llama3 Draft Model

[xiaoxi-s]

Motivation

Support multiple Llama3DecoderLayers in LlamaForCausalLMEagle3.

Modifications

A LlamaForCausalLMEagle3 instance can now hold a arbitrary number (>=1) of Llama3DecoderLayerss configured via num_hidden_layers option of LlamaConfig. The test for the new config is also updated in tests/test_modeling/test_draft/test_llama3.py.

Related Issues

Sub-issue of #374

Accuracy Test

Tested under tests/test_modeling/test_draft/test_llama3.py.

Benchmark & Profiling

See this comment. We compared the following two architectures. It turns out the w/o embeddings architecture wins in terms of the accept length.

• All additional layers have access to input embeddings (basically a repetition of the existing LlamaDecoderLayer)
• Only the first has access to the input embeddings. The rest only accepts hidden_states as input.

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 @xiaoxi-s, 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 enhances the flexibility of the Llama3 draft decoder by enabling the configuration of multiple Multi-Layer Perceptrons (MLPs) within each decoder layer. Previously limited to a single MLP, the model can now be instantiated with a user-defined number of MLPs, allowing for more complex and potentially more powerful draft model architectures. The changes include adding a new command-line option for specifying the number of MLPs, updating the core model classes to handle this configuration, and ensuring comprehensive test coverage for the new functionality.

Highlights

• Multi-layer MLP Support: The Llama3 draft decoder now supports an arbitrary number of Multi-Layer Perceptrons (MLPs) within its LlamaDecoderLayer, configurable via a new parameter.
• New Command-Line Argument: A --num-draft-hidden-layers argument has been added to scripts/train_eagle3.py to specify the desired number of MLPs for the draft model decoder.
• Architectural Updates: The LlamaDecoderLayer and LlamaForCausalLMEagle3 classes have been modified to incorporate and utilize the num_draft_hidden_layers parameter, replacing a single MLP with a nn.Sequential module containing multiple MLPs.
• Test Coverage: Existing unit tests in tests/test_modeling/test_draft/test_llama3.py have been updated to validate the correct initialization and behavior of the model with the new multi-MLP configuration.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

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 successfully adds support for a multi-layer MLP in the draft decoder, with corresponding changes to the training script and tests. The implementation is consistent and the new functionality is well-tested. I have provided a couple of suggestions to improve the architecture of the multi-layer MLP for better training stability by incorporating residual connections for each MLP block. Additionally, I've pointed out a minor indentation issue in one of the test files.

I am having trouble creating individual review comments. Click here to see my feedback.

specforge/modeling/draft/llama3_eagle.py (1252)

Using nn.Sequential here creates a deep MLP stack without any intermediate normalization or residual connections. This can lead to training instability, especially if num_draft_hidden_layers is large. A more standard and stable approach is to use nn.ModuleList to treat each MLP as a separate block. I'll add a related suggestion on the forward method to complete this change.

        self.mlps = nn.ModuleList([LlamaMLP(config) for _ in range(num_draft_hidden_layers)])

specforge/modeling/draft/llama3_eagle.py (1308-1311)

To accompany the change to nn.ModuleList for self.mlps, the forward pass should be updated to loop through the MLPs. This applies a residual connection around each MLP block, which is a more standard and stable architecture than a single deep MLP. This implementation reuses the same post_attention_layernorm for each block.

        for mlp in self.mlps:
            residual = hidden_states
            hidden_states = self.post_attention_layernorm(hidden_states)
            hidden_states = mlp(hidden_states)
            hidden_states = residual + hidden_states

tests/test_modeling/test_draft/test_llama3.py (63)

This line has incorrect indentation. According to the PEP 8 style guide, indentation should be in multiples of 4 spaces. The line inside the for loop should be indented by 4 more spaces relative to the for statement.

            self.assertIsInstance(model.midlayer.mlps[i], LlamaMLP)

[Dogacel]

I guess for true multi-layer architecture, we should duplicate the decoder, not MLP. Why you wanted to duplicate the MLP instead?

[Dogacel]

This variable can be already set using the model config,

SpecForge/configs/llama3-8B-eagle3.json

Line 15 in 886ab9c

"num_hidden_layers": 1,

Which allows us to save & load models directly with the right number of hidden layers.

[sleepcoo]

@uygnef

[uygnef]

@sleepcoo LGTM

[justadogistaken]

hidden_states = torch.cat((input_emb, hidden_states), dim=-1)

Your implementation will do input_emb & hidden_states fusion every layer. May I ask why not just do fuse them in first layer. Them let others handle hidden_states only.

[xiaoxi-s]

Your implementation will do input_emb & hidden_states fusion every layer. May I ask why not just do fuse them in first layer. Them let others handle hidden_states only.

I believe the way of only iterating on hidden_states on later layers exists mostly in traditional transformer architectures. For the decoder layers used in draft model, this implementation keeps the initial token info available across all decoder layers for better speculative decoding instead of only next-token generation.

[Dogacel]

hidden_states = torch.cat((input_emb, hidden_states), dim=-1)

Your implementation will do input_emb & hidden_states fusion every layer. May I ask why not just do fuse them in first layer. Them let others handle hidden_states only.

I agree, I think input embedding should only be injected in the first layer. Original EAGLE only has 1 decoder layer therefore it didn't matter for them where they have done this injection. Injecting the same data to each layer would result in excessive computations.

However changing this means you have to update some code to make sure your input/output shapes match. For example attention takes 2 * hidden_size and outputs hidden_size.

I think it would be nice to configure if you want to map from (2 * hidden_size -> hidden_size) and save compute on deeper layers, or if you want to keep the full 2 * hidden_size shape and be more expressive.

SpecForge/specforge/modeling/draft/llama3_eagle.py

Lines 527 to 529 in e1e9695

	self.q_proj = nn.Linear(
	self.hidden_size * 2, self.num_heads * self.head_dim, bias=False
	)

[uygnef]

@xiaoxi-s Hi, xiaoxi.
A reviewer noted that input_emb is concatenated to hidden_states in every layer. Could you share the rationale behind this design?

It seems fusing them only in the first layer could be more efficient and less redundant. Have you experimented with or compared both approaches? If not, could we test the alternative to verify performance?

Appreciate your input.

[xiaoxi-s]

It seems fusing them only in the first layer could be more efficient and less redundant. Have you experimented with or compared both approaches? If not, could we test the alternative to verify performance?

Appreciate your input.

Working on the experiments. Will share after it's done.

#449 contains the implementation of the more traditional decoder layer as the additional layers. Will share their benchmarks on SharedGPT after the experiment is done.

[xiaoxi-s]

The attached files contain benchmark results by training one epoch on the shareGPT dataset. The architectures to compare are 1. both hidden_states and input_embeddings as inputs to all draft model's decoder layers (this PR) and 2. only hidden_states as input to multiple layers except the first decoder (PR #449). Both architectures have three decoder layers.

According to the benchmark diffs below, the traditional architecture yields longer accept length and smaller latency. Then shall we merge #449 and its SGLang code changes? @sleepcoo @uygnef @Dogacel .

Benchmark diffs

(base) Desktop % diff w_emb_results_3_layers_20260208_035709.txt wo_emb_results_3_layers_20260209_170526.txt 
10,11c10,11
<                     "latency": 383.7811117080273,
<                     "output_throughput": 153.13937608454404,
---
>                     "latency": 383.9044507519575,
>                     "output_throughput": 153.09017617504225,
28,30c28,30
<                     "latency": 365.8511588460533,
<                     "output_throughput": 164.11318796796454,
<                     "accept_length": 1.6563948355771352,
---
>                     "latency": 284.57163369096816,
>                     "output_throughput": 210.9872977192161,
>                     "accept_length": 2.153550932568149,
48,49c48,49
<                     "latency": 114.32346982206218,
<                     "output_throughput": 148.27226663416747,
---
>                     "latency": 114.29552205302753,
>                     "output_throughput": 148.3085224645596,
66,68c66,68
<                     "latency": 123.72353005502373,
<                     "output_throughput": 136.15841701661807,
<                     "accept_length": 1.4531182610195807,
---
>                     "latency": 94.56808510399424,
>                     "output_throughput": 178.13620717258746,
>                     "accept_length": 1.9009252990295644,
86,87c86,87
<                     "latency": 395.21123192296363,
<                     "output_throughput": 154.03661405014526,
---
>                     "latency": 395.3808778229868,
>                     "output_throughput": 153.97052162764132,
104,106c104,106
<                     "latency": 337.76052550505847,
<                     "output_throughput": 180.05952563301886,
<                     "accept_length": 1.8095450623344937,
---
>                     "latency": 248.29932356998324,
>                     "output_throughput": 244.9342153880605,
>                     "accept_length": 2.48080766877422,
124,125c124,125
<                     "latency": 739.7199332889868,
<                     "output_throughput": 154.16104780760247,
---
>                     "latency": 740.172878019046,
>                     "output_throughput": 154.06670980055236,
142,144c142,144
<                     "latency": 731.892317363061,
<                     "output_throughput": 158.66678368533042,
<                     "accept_length": 1.5894526491561844,
---
>                     "latency": 510.2352287879912,
>                     "output_throughput": 227.59502568226654,
>                     "accept_length": 2.302371228042349,
162,163c162,163
<                     "latency": 20.689986279932782,
<                     "output_throughput": 136.24948619391537,
---
>                     "latency": 20.496201911009848,
>                     "output_throughput": 137.5376770896139,
180,182c180,182
<                     "latency": 25.61382379801944,
<                     "output_throughput": 109.19884598473247,
<                     "accept_length": 1.2656108597285067,
---
>                     "latency": 23.558204637025483,
>                     "output_throughput": 118.72721385584993,
>                     "accept_length": 1.403411941796287,

Their deployment code by SGLang are also updated with the following two PRs on the SGLang repo: with input embeddings and without input embeddings. (The two PRs can point to v0.5.6 because of SpecForge compatibility if required.)

Benchmark files

1. With embeddings: w_emb_results_3_layers_20260208_035709.txt
2. Without embeddings: wo_emb_results_3_layers_20260209_170526.txt

Models

The models are stored on the atlas machine at /home/ubuntu/xiaoxi/dev/SpecForge/outputs. Models with 2 decoder layers are also trained and benchmarked. The machine may be unavailable sometime, but it should be easy to retrain & reproduce the models.

Models on atlas

ubuntu@atlascloud-h100:~/xiaoxi/dev/SpecForge/outputs$ pwd
/home/ubuntu/xiaoxi/dev/SpecForge/outputs
ubuntu@atlascloud-h100:~/xiaoxi/dev/SpecForge/outputs$ ls
llama3-8b-eagle3-sharegpt-main-1layer                llama3-8b-w-emb-multi-layer-eagle3-sharegpt-3layers   llama3-8b-wo-emb-multi-layer-eagle3-sharegpt-3layers
llama3-8b-w-emb-multi-layer-eagle3-sharegpt-2layers  llama3-8b-wo-emb-multi-layer-eagle3-sharegpt-2layers

Below includes some additional benchmarks from 2-layer models and main as the baseline. Under the "without embedding" architecture, the diffs between 2-layer and 3-layer results show multi-layer did improve accept length of draft models. However, under the "with embedding" architecture, the decrease of accept_length indicates that introducing embeddings to all decoder layers tend to overfit the draft models. Hence the traditional architecture is still better. Feel free to examine the attached benchmark results if interested.

Additional benchmark results for the 2 layer models and main

main_results_20260202_111819.txt
wo_emb_results_2_layers_20260210_114557.txt
w_emb_results_2_layers_20260205_101053.txt

[uygnef]

task	latency w/o	latency w/	throughput w/o	throughput w/	accept_len w/o	accept_len w/	acc w/o	acc w/	Δlatency% (w/ vs w/o)	Δthroughput%	Δaccept_len%
mtbench	284.572	365.851	210.987	164.113	2.154	1.656	—	—	+28.6%	-22.2%	-23.1%
gsm8k	94.568	123.724	178.136	136.158	1.901	1.453	0.765	0.765	+30.8%	-23.6%	-23.6%
humaneval	248.299	337.761	244.934	180.060	2.481	1.810	0.000	0.000	+36.0%	-26.5%	-27.1%
math500	510.235	731.892	227.595	158.667	2.302	1.589	0.410	0.410	+43.4%	-30.3%	-31.0%
ceval	23.558	25.614	118.727	109.199	1.403	1.266	0.500	0.500	+8.7%	-8.0%	-9.8%

@sleepcoo Based on @xiaoxi-s’s benchmark (table above), the implementation in #449 shows consistently better performance.
I think it’s worth merging that PR.

[Dogacel]

1.901

Couple things,

1. Using Perfectblend to train a model would be better, based on my personal experience training on ShareGPT and Ultrashare requires fine tuning of hyper-parameters and many epochs (10). I found that model is pretty sensitive to those with a small dataset, but much less on a big diverse dataset. The results we see here could be an artifact of how fast models learn, not how well they perform after the full training.

2. After the full-training, I would love to see comparison with current specforge. I found that 3-layer doesn't have any acceptance length advantage in Llama 3.1 8B. Moreover I found that it performed slightly worse under equal train, however I can't generalize this claim, maybe hyper-parameters could create a slight difference or maybe a bigger model's drafter would benefit more.

Beyond that, I am pretty OK with having some kind of implementation, preferrably no embeddings to start with as it is simpler, baked into specforge. Another option is having some config variable to control this behavior. Future research could show what is ideal, it seems like it is a hard question to answer over a PR.

Thanks for the effort 🙏

[xiaoxi-s]

I think it’s worth merging that PR.

@uygnef Thank you for your comment!

After the full-training, I would love to see comparison with current specforge

The "Additional benchmark results" section contains the training results on main (which has only one decoder layer in the draft model).

Beyond that, I am pretty OK with having some kind of implementation, preferrably no embeddings to start with as it is simpler, baked into specforge. Another option is having some config variable to control this behavior. Future research could show what is ideal, it seems like it is a hard question to answer over a PR.

@Dogacel Agreed. The benchmark comparison also shows the wo. embedding works better. I wouldn't personally bother with configuring w/wo embeddings behavior in the additional layers because exposing the embeddings might have shown too much information for the draft models (even using 1 - 2 additional decoder layers leads to the overfitting problem). But of course, configuring the two kinds of architectures should be addressed on another issue/PR.

Thank you for all the feedback. We can wait for @sleepcoo 's opinion on merging #449.