[Feature] Virtual Width Network Eagle3 (vllm-project#10042)

### What this PR does / why we need it?
We add a customed speculative model "Virtual Width Network Eagle3" with
architecture similar to Seed's work 'Virtual Width Network'
(https://huggingface.co/papers/2511.11238)

We impelmented and trained the 'vwn eagle3' based on 'speculators'
library (https://github.com/vllm-project/speculators); the training
datasets includes 'ultrachat'
(https://huggingface.co/datasets/openbmb/UltraChat) and 'sharegpt'
(https://huggingface.co/collections/bunnycore/sharegpt-datasets).

We used the same setting to train a vwn-eagle3 and an eagle3 model to
compare their performace on longbenchv2, gsm8k, sharegpt, and humaneval;
as well as some man-made fixed-length datasets. The performance is
concluded as following:

Datasets testing result:

| Dataset | Context-Length | E2E Throughput Gain|
| ------ | ------ | ------ | 
| gsm8k   | 1.5k | 7.9%|
| humaneval | 2.5k | 11.94%|
| sharegpt  | 5k | 2.84%|
| longbench_v2| 128k | 18.23%|

Fixed length testing results:

|Input Lenght | Output Length | E2E Throughput Gain|
| ------ | ------ | ------ | 
| 2k   | 2k | 9.83%|
| 3.5k | 1.5k | 2.38%|
| 32k  | 1k | 18.66%|

### Does this PR introduce _any_ user-facing change?

Nope. VWN Eagle3 uses the same interface with eagle3 and can be
distinguished by draft model's config file, thus, the user can simply
use the same setting to start the server:
`--speculative-config '{"method": "eagle3","model":
"/vwn-eagle3-model-path/", "num_speculative_tokens": 3}' `

To reduce redundant codes, we reuse the implementation of
llama_eagle3.py to the greatest extent：

| Component | Provided by Upstream Eagle3 | Overridden/Added by VWN |
Reuse Rate |

|-----------|-----------------------------|------------------------|------------|
| Top-level CausalLM | ✅ forward, embed_input_ids, load_weights | Only
replaces `self.model` | ~80% |
| Model container | ✅ embed, fc, load_weights | Swaps layer type +
simplifies forward | ~50% |
| Decoder Layer | ✅ self_attn, mlp, quant | Adds VWN projections +
rewrites forward | ~40% |
| PreVwnLayerV1 | ❌ No counterpart | Entirely new implementation | 0%
(pure addition) |

### How was this patch tested?
- vLLM-ascend main @ 7cb4484


- vLLM version: v0.22.1
- vLLM main:
vllm-project/vllm@967c5c3

---------

Signed-off-by: YzTongNiar <1667927948@qq.com>
Co-authored-by: wu_yushan <wuyushan1@huawei.com>

Author: YzTongNiar

.github/workflows/misc/model_dataset_list.json

@@ -274,7 +274,8 @@
       "Eco-Tech/GLM-5.1-w8a8",
       "Eco-Tech/Qwen3.5-397B-A17B-w4a8-mtp", 
       "lightseekorg/kimi-k2.5-eagle3",
-      "Eco-Tech/Qwen3.5-122B-A10B-w8a8-mtp"
+      "Eco-Tech/Qwen3.5-122B-A10B-w8a8-mtp",
+      "vllm-ascend/Qwen3-30B-A3B-vwn-eagle-model"
     ],
     "datasets": [
       "vllm-ascend/GSM8K-in1024-bs210",

.github/workflows/scripts/test_config.yaml

@@ -451,11 +451,13 @@
   source_file_dependencies:
     - vllm_ascend/spec_decode/llm_base_proposer.py
     - vllm_ascend/spec_decode/eagle_proposer.py
+    - vllm_ascend/models/llama_eagle3_vwn.py
   tests:
     - tests/e2e/pull_request/one_card/spec_decode/test_eagle.py
     - tests/e2e/pull_request/one_card/spec_decode/test_mtp_eagle_correctness.py
     - tests/e2e/pull_request/two_card/spec_decode/test_spec_decode.py
     - tests/e2e/pull_request/four_card/spec_decode/test_mtp_qwen3_next.py
+    - tests/ut/spec_decode/test_speculators_vwn_eagle3.py
 
 - name: spec_decode_ngram
   optional: false

tests/e2e/pull_request/two_card/spec_decode/test_spec_decode.py

@@ -46,11 +46,19 @@
     },
 }
 
+VWN_EAGLE3_MODELS = {
+    "vwn_eagle3": {
+        "main": "Qwen/Qwen3-30B-A3B",
+        "spec": "vllm-ascend/Qwen3-30B-A3B-vwn-eagle-model",
+    },
+}
+
 # NOTE: golden may change (eagle_proposer only runs in eager mode currently),
 # thus please update it if ci fails but you have better acceptance
 BASELINES_SP = {
     "eagle3": [0.68, 0.40, 0.18],
     "p-eagle": [0.5625, 0.25, 0.0625, 0.0, 0.0, 0.0, 0.0, 0.0],
+    "vwn_eagle3": [0.75, 0.5, 0.3],
 }
 
 
@@ -327,3 +335,95 @@ def test_p_eagle_acceptance(
         print(f"golden: {golden}")
 
     assert match
+
+
+@patch.dict(os.environ, {"VLLM_ASCEND_ENABLE_FLASHCOMM1": "1"})
+def test_qwen3_vwn_eagle3_tp2():
+    """
+    Test Qwen3-30B-A3B with VWN-Eagle3 speculative decoding acceptance rate.
+    This test verifies that VWN-Eagle3 spec decode works correctly with:
+    - Tensor Parallel size = 4
+    - Expert Parallel enabled (for MoE)
+    - num_speculative_tokens = 3
+    - enforce_eager = True
+    - Acceptance rate matches baseline (tolerance 0.06)
+    """
+    num_speculative_tokens = 3
+    main_model_name = VWN_EAGLE3_MODELS["vwn_eagle3"]["main"]
+    spec_model_name = VWN_EAGLE3_MODELS["vwn_eagle3"]["spec"]
+
+    tokenizer = AutoTokenizer.from_pretrained(
+        main_model_name,
+        trust_remote_code=True,
+    )
+    sampling_params = SamplingParams(
+        temperature=0,
+        ignore_eos=False,
+        max_tokens=256,
+    )
+
+    prompts = [
+        {
+            "role": "user",
+            "content": "Hello, my name is",
+        },
+        {
+            "role": "user",
+            "content": "The capital of France is",
+        },
+        {
+            "role": "user",
+            "content": "The future of AI is",
+        },
+    ]
+    prompts = [
+        tokenizer.apply_chat_template(
+            [prompt],
+            tokenize=False,
+            add_generation_prompt=True,
+        )
+        for prompt in prompts
+    ]
+
+    speculative_config = {
+        "method": "eagle3",
+        "num_speculative_tokens": num_speculative_tokens,
+        "model": spec_model_name,
+    }
+
+    with VllmRunner(
+        main_model_name,
+        enforce_eager=True,
+        max_model_len=2048,
+        disable_log_stats=False,
+        tensor_parallel_size=2,
+        max_num_seqs=16,
+        distributed_executor_backend="mp",
+        gpu_memory_utilization=0.92,
+        speculative_config=speculative_config,
+        enable_expert_parallel=True,
+    ) as llm:
+        _ = llm.generate(prompts, sampling_params)
+        metrics = llm.model.get_metrics()
+
+    # Check acceptance rate
+    num_drafts = 0
+    num_accepted_tokens_per_pos = [0] * num_speculative_tokens
+    for metric in metrics:
+        if metric.name == "vllm:spec_decode_num_drafts":
+            assert isinstance(metric, Counter)
+            num_drafts += metric.value
+        elif metric.name == "vllm:spec_decode_num_accepted_tokens_per_pos":
+            assert isinstance(metric, Vector)
+            for pos in range(len(metric.values)):
+                num_accepted_tokens_per_pos[pos] += metric.values[pos]
+
+    acceptance_per_pos = [n / num_drafts for n in num_accepted_tokens_per_pos]
+    golden = BASELINES_SP["vwn_eagle3"]
+
+    match = all(abs(a - b) < 0.06 for a, b in zip(acceptance_per_pos, golden))
+    if not match:
+        print(f"acceptance_per_pos: {acceptance_per_pos}")
+        print(f"golden: {golden}")
+
+    assert match