README.md

---
library_name: speculators
tags:
  - eagle3
  - speculative-decoding
  - vllm
  - qwen3.5
  - moe
license: mit
language:
  - en
  - ru
---

# EAGLE3 Speculator for Qwen3.5 MoE (a1-agents)

Trained using [speculators](https://github.com/vllm-project/speculators) library for speculative decoding with vLLM.

## Model Details

- **Verifier:** Qwen3.5 MoE (Qwen3_5MoeForConditionalGeneration), 40 layers, 65.5 GB
- **Draft type:** EAGLE-3, 1 layer, draft vocab size 8192
- **Target layers:** [3, 19, 39]
- **TTT steps:** 3 (predicts 3 speculative tokens)
- **Training data:** 5000 ShareGPT samples
- **Optimizer:** Muon (muon_lr=1e-3, momentum=0.95)
- **Attention:** SDPA (required for GB10/Sm121)

## Validation Metrics

| Position | Accuracy | Loss |
|----------|----------|------|
| 0 | 71.4% | 0.62 |
| 1 | 42.7% | 1.40 |
| 2 | 25.7% | 2.02 |

- Mean acceptance length: 2.02
- Throughput speedup: 1.34x (on GB10, CUDAgraph enabled)

## Usage with vLLM

```python
from vllm import LLM, SamplingParams

llm = LLM(
    model="/path/to/verifier-model",
    speculative_config={
        "method": "eagle3",
        "model": "Ichigec/a1-agents-eagle3-speculator",
        "num_speculative_tokens": 3,
    },
    dtype="bfloat16",
    gpu_memory_utilization=0.65,
    max_model_len=8192,
    enforce_eager=False,  # CUDAgraph works for serving
)
```

Or with vLLM CLI:

```bash
vllm serve /path/to/verifier-model \
  --speculative_config '{"method": "eagle3", "model": "Ichigec/a1-agents-eagle3-speculator", "num_speculative_tokens": 3}' \
  --dtype bfloat16 \
  --gpu-memory-utilization 0.65 \
  --max-model-len 8192
```

## Training Details

Trained on NVIDIA DGX Spark (GB10, 128GB unified memory) using the speculators offline pipeline.