Skip to content

Add a Speculative decoding models tutorial section - #1936

Merged
cosmicbboy merged 6 commits into
mainfrom
niels/speculative-decoding-tutorial
Nov 7, 2026
Merged

cosmicbboy merged 6 commits into
mainfrom
niels/speculative-decoding-tutorial

Conversation

@cosmicbboy

@cosmicbboy cosmicbboy commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds Tutorials › Speculative decoding models, a new top-level section with a flat list of five pages:

  1. Train an EAGLE-3 draft head: generates training data from Qwen3-8B's own outputs (regenerated chat and recorded tool-calling agent traces), then fine-tunes Red Hat's public EAGLE-3 head with speculators in online mode.
  2. Train a DFlash block drafter: fine-tunes Red Hat's public DFlash head, which drafts 15 tokens in one pass.
  3. Train a DSpark drafter: trains DSpark (DFlash plus Markov and confidence heads) from scratch.
  4. Benchmark draft models: compares eight configurations on identical GPUs: no speculation, n-gram, suffix decoding, and each family's public and trained drafter. It checks losslessness against a noise floor and with GSM8K accuracy.
  5. Serve and retrain draft models: serves any family as a vLLM app, records an agent's traces with flyte.trace, and retrains each family nightly, promoting a candidate only when its acceptance length improves.

The landing page explains speculative decoding, compares the three families, and lists what Flyte and Union provide. Union-only parts are gated: artifacts with model and data cards, and rollback.

Code: unionai/unionai-examples#347, merged into niels/training-rl (#343's branch). The submodule pointer moves to that merge commit, 281fba1, which contains the #343 commit main already pins, so the existing model-training pages keep their examples.

Status: draft until the full benchmark run finishes

The full cross-family run is running on demo.hosted.unionai.cloud. Its numbers go into a results section on the benchmark page before this leaves draft. Smoke runs of every pipeline pass end to end on one L40S per task.

Checks run locally

  • make check-links, check-subpage-cards, check-icon-names: pass
  • check_heading_shortcodes.py, cspell, markdownlint: pass
  • make variant VARIANT=union and VARIANT=flyte: both build with no errors or warnings, and the Union-only sections are absent from the Flyte variant and its Markdown twins.

Merge order

  1. Speculative decoding models: train, benchmark, serve, and retrain EAGLE-3, DFlash, and DSpark drafters unionai-examples#347: merged into niels/training-rl.
  2. Model training and RL user guide examples unionai-examples#343, which now also carries the speculative decoding examples, into examples main.
  3. This PR. It can merge before Cost 30d -> 60d #343 does, pinned to 281fba1 as main is pinned to a niels/training-rl commit today. Bump the pointer to examples main afterwards.

🤖 Generated with Claude Code

cosmicbboy and others added 2 commits November 6, 2026 21:09
A new top-level tutorial section with five pages: train an EAGLE-3 draft
head, train a DFlash block drafter, train a DSpark drafter, benchmark
every family against no speculation and draft-free methods, and serve
and retrain the drafters nightly on an agent's traces. Union-only parts
(artifacts with model and data cards, rollback) are gated.

Bumps unionai-examples to the head of unionai/unionai-examples#347,
which is stacked on #343, the commit this repo already pins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
Points at the merge of unionai/unionai-examples#347 into
niels/training-rl (281fba1), which also carries #343.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

GHA build & deploy preview

Built by .github/workflows/build-pr.yml and deployed to the docs CF Pages project by .github/workflows/deploy-pr-preview.yml.

Branch alias https://pr-1936-niels-speculative-de.docs-dog.pages.dev
This commit https://76d0ec9a.docs-dog.pages.dev
Commit SHA c52ac238d4a258c523d68f2ddb4b33309e04eb34

Updated automatically on every push.

Speedup, acceptance length, prefix agreement against the noise floor, and
GSM8K accuracy for all eight configurations across chat, agent, and math.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
@cosmicbboy
cosmicbboy marked this pull request as ready for review November 7, 2026 08:55
cosmicbboy and others added 3 commits November 7, 2026 07:46
Training reports for EAGLE-3, DFlash, and DSpark, the dataset report, and the
benchmark reports. Correct the DFlash page's claim that its first-position
accuracy is close to EAGLE-3's: it was 78% against 95%.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
The speculative decoding examples merged to main with #343.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
…reenshots

From a validation pass: 250 agent episodes through the EAGLE-3 app, then one
retrain cycle, whose gate kept the current head.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
@cosmicbboy
cosmicbboy merged commit 52099ce into main Nov 7, 2026
17 checks passed
@cosmicbboy
cosmicbboy deleted the niels/speculative-decoding-tutorial branch November 7, 2026 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant