Index of every page on this site: llms.txt
All skills
nvidia avatar

/jetson-speculative-decoding

@6b75e9e
by NVIDIA Corporationnvidia/skills4.1k stars
547
Run it yourself

Add EAGLE-3 or draft-model speculative decoding to a Jetson vLLM server when TPOT is the bottleneck.

Use this Skill: https://skilld.dev/gh/nvidia/skills/jetson-speculative-decoding

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈32 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈3.4k more on demand in 3 files.

Description uses 1.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈130 characters, or 1.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Jetson Speculative Decoding (vLLM)

Speculative decoding lets a small "draft" model propose tokens that the target model verifies in a single forward pass, reducing per-token latency. On Jetson, the win/loss is dominated by VRAM headroom, not by the draft quality. This skill encodes the parts an LLM won't already know.

Purpose

Tune an existing Jetson vLLM deployment for faster token generation by appending the right --speculative-config and validating whether it improves single-stream decode speed.

When to use

  • TPOT/ITL is the bottleneck (TTFT is fine, output is just slow).
  • Workload is single-stream or low-concurrency (≤2). Speculation usually loses at high concurrency.
  • Jetson family is Thor or AGX Orin. Do not suggest EAGLE-3 on Orin Nano/NX — there is rarely enough VRAM headroom to host both target and draft, and you'll OOM at startup.

When NOT to use

  • High-concurrency serving (≥8): batched decode usually beats speculation; the draft model just steals VRAM.
  • Models without a published EAGLE-3 head — do not train one ad-hoc as a "fix".
  • After applying jetson-inference-mem-tune flags that already pushed --gpu-memory-utilization near the ceiling. Free at least ~2 GB first.

Prerequisites

  • A working vLLM server recipe from jetson-llm-serve.
  • Enough memory headroom for the draft model or EAGLE-3 head in addition to the target model.
  • A benchmark baseline from jetson-llm-benchmark before enabling speculation.
  • A target model with a compatible EAGLE-3 head, or a small same-family draft model for the fallback path.

Instructions

Append --speculative-config to the vllm serve command shown in jetson-llm-serve.

EAGLE-3 (preferred when a head is published for the target model):

--speculative-config '{
  "method": "eagle3",
  "model": "<eagle3-head-repo-id>",
  "num_speculative_tokens": 5,
  "draft_tensor_parallel_size": 1
}'

Draft-model (fallback — pair a small same-family model):

--speculative-config '{
  "method": "draft_model",
  "model": "<small-draft-model-repo-id>",
  "num_speculative_tokens": 4,
  "draft_tensor_parallel_size": 1
}'

Jetson-specific tuning rules

  • num_speculative_tokens: start at 5 on Thor, 3 on AGX Orin. Higher values pay off only if the draft acceptance rate is >0.6.
  • Always pair with the same vLLM runtime path used by jetson-llm-serve: upstream vLLM 0.20+ (vllm/vllm-openai:latest) or validated native vLLM 0.20+ on Thor, upstream vLLM 0.20+ on Orin JetPack 7.2 / L4T r39+, or the NVIDIA-AI-IOT vLLM image on older Orin. Do not use an Orin NVIDIA-AI-IOT vLLM image on Thor. Older runtimes may lack EAGLE-3 or the current --speculative-config shape.
  • Drop --gpu-memory-utilization by ~0.05 vs the non-speculative baseline to give the draft model headroom.

How to verify it actually helped

  1. Run jetson-llm-benchmark (vLLM path) at --concurrency 1 before and after enabling speculation.
  2. Acceptance: target ≥30% improvement in throughput_tok_s and ≥20% drop in tpot_ms_p50 at concurrency 1.
  3. If improvement is <10%, or throughput_tok_s regresses at concurrency 8, disable speculation. The draft model is costing more than it returns.

Limitations

  • Speculative decoding improves decode-heavy workloads; it does not reduce TTFT-dominated latency.
  • High concurrency can erase the benefit because continuous batching already keeps the GPU busy.
  • Orin Nano/NX usually lack enough memory headroom for both target and draft models.
  • Acceptance rate and draft overhead are model-specific, so benchmark before and after instead of assuming a speedup.

Error handling

  • If vLLM rejects --speculative-config, verify that Thor and Orin JetPack 7.2 / L4T r39+ are using vLLM 0.20+ and that older Orin is using a JetPack-matched NVIDIA-AI-IOT vLLM image; then switch back to the non-speculative serving command if the runtime still rejects it.
  • If startup OOMs, lower --gpu-memory-utilization, use a smaller draft, or disable speculation and hand off to jetson-inference-mem-tune.
  • If benchmark throughput regresses, remove --speculative-config; a bad draft path is worse than no speculation.

Hand off to

  • jetson-llm-benchmark to quantify the change.
  • jetson-inference-mem-tune if startup OOMs after enabling speculation.

Source

vLLM speculative decoding docs and the Jetson AI Lab GenAI tutorial.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts5mo3 checks · Risk SAFE
  • Gen Agent Trust Hub5mo

    This skill is a configuration guide for optimizing LLM performance on NVIDIA Jetson hardware. It contains no security risks, malicious code, or unauthorized data access patterns.

  • Socket5mo

    No alerts

  • Snyk5mo

    Risk: LOW · No issues

Signed by skilld at 6b75e9e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 months ago
version
0.0.1
Other metadata
metadata
{
  "author": "Jetson Team",
  "tags": [
    "jetson",
    "llm",
    "speculative-decoding"
  ],
  "languages": [
    "markdown"
  ],
  "data-classification": "public"
}

README badge

README badge for nvidia/skills/jetson-speculative-decoding