Update LFM2.5-VL-3B-DSpark model card

Update model details, performance results, inference instructions, and model card formatting.

README.md

@@ -22,107 +22,90 @@ tags:
   <div style="display: flex; justify-content: center; gap: 0.5em; margin-bottom: 1em;">
     <a href="https://playground.liquid.ai/"><strong>Try LFM</strong></a> • 
     <a href="https://docs.liquid.ai/lfm/getting-started/welcome"><strong>Docs</strong></a> • 
-    <a href="https://leap.liquid.ai/"><strong>LEAP</strong></a> • 
     <a href="https://discord.com/invite/liquid-ai"><strong>Discord</strong></a>
   </div>
 </div>
 
 # LFM2.5-VL-3B-DSpark
 
-**LFM2.5-VL-3B-DSpark** is an experimental speculative-decoding draft model that brings DSpark to
-vision-language models. It allows [`LiquidAI/LFM2.5-VL-3B`](https://huggingface.co/LiquidAI/LFM2.5-VL-3B)
-to decode substantially faster without changing its output, for a minimal increase in memory footprint.
+**LFM2.5-VL-3B-DSpark** is an experimental speculative-decoding draft model that adapts DSpark for the LFM2.5 vision-language architecture. It allows LFM2.5-VL-3B to run faster without degrading quality.
 
-To our knowledge, this is the first publicly available DFlash/DSpark-style block speculation model for
-vision-language models — speculative decoding has so far been almost exclusively a text-model story.
+To our knowledge, this is the first publicly available DFlash/DSpark-style block speculation model for vision-language models. Until now, speculative decoding work has focused almost entirely on text-only models.
 
-From the drafter's perspective the input modality is irrelevant: by the time tokens reach the hidden
-layers, text and image patches alike are just tensors. Because DSpark taps the target's hidden states
-rather than modifying its architecture, exactly the same drafting algorithm applies to a VLM as to a
-text LFM.
+This is a drafter for [`LiquidAI/LFM2.5-VL-3B`](https://huggingface.co/LiquidAI/LFM2.5-VL-3B). In SGLang on a single H100, decoding runs up to 2.58× faster. On Apple silicon, it reaches up to 3.13× with MLX-VLM on an M5 Max and up to 2.14× with llama.cpp on an M3 Ultra.
 
-<!-- TODO: link the vision DSpark blog post once it is published (www.liquid.ai/blog/<slug>) -->
-Find more information about LFM2.5-DSpark in our [blog post](https://www.liquid.ai/blog/lfm2.5-dspark).
+Find more information about LFM2.5-VL-3B-DSpark in our [blog post](https://www.liquid.ai/blog/lfm2-5-vl-dspark).
 
 ## 🗒️ Model Details
 
 LFM2.5-VL-3B-DSpark is a DSpark speculative-decoding draft model with the following features:
 
 - **Target model**: [`LiquidAI/LFM2.5-VL-3B`](https://huggingface.co/LiquidAI/LFM2.5-VL-3B)
-- **Draft parameters**: **280M** (BF16)
+- **Draft parameters**: **279.5M** (BF16)
 - **Backbone**: 4 full attention layers, `hidden_size=2048`, `intermediate_size=6144` with SiLU/SwiGLU, GQA with `num_attention_heads=32` / `num_key_value_heads=8`, `head_dim=64`
 - **Extra heads**: Markov head (rank 256) + confidence head
-- **Block size**: 9
-- **Target taps**: hidden states from layers `[2, 9, 17, 21, 27]` of the 30-layer target
+- **Block size**: 9 during training; 8 or 9 at inference, depending on hardware
 - **Vocabulary**: 128,000
 
-<!-- TODO: memory-footprint overhead (% increase over the deployed target) — blog draft still has this as XXX -->
+> [!NOTE]
+> On Apple silicon the drafter is run at block size 8 rather than 9.
 
 This drafter pairs with:
 
-| Drafter | Target |
-|---|---|
-| [LFM2.5-VL-3B-DSpark](https://huggingface.co/LiquidAI/LFM2.5-VL-3B-DSpark) | [LFM2.5-VL-3B](https://huggingface.co/LiquidAI/LFM2.5-VL-3B) |
+| Drafter                                                                              | Target                                                                 |
+| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| [LFM2.5-VL-3B-DSpark](https://huggingface.co/LiquidAI/LFM2.5-VL-3B-DSpark)           | [LFM2.5-VL-3B](https://huggingface.co/LiquidAI/LFM2.5-VL-3B)           |
 | [LFM2.5-VL-3B-DSpark-GGUF](https://huggingface.co/LiquidAI/LFM2.5-VL-3B-DSpark-GGUF) | [LFM2.5-VL-3B-GGUF](https://huggingface.co/LiquidAI/LFM2.5-VL-3B-GGUF) |
 
-### Training
-
-The drafter follows the recipe from the text DSpark release: a simplified attention-only draft model,
-with layer count and block size selected by ablation. There are no established data mixtures for
-training multimodal drafters, so the corpus was constructed from ablations — SFT data spanning common
-vision-language tasks, weighted toward expected workloads, with 5% text. Training ran for 10 epochs,
-and the published checkpoint is the epoch with the highest acceptance rate. All ablations and training
-runs were executed exclusively on AMD hardware using Liquid AI's training framework.
-
 ## 📊 Performance
 
-### Quality parity
+### Benchmarks
 
-Speculative decoding is **exact**: the target verifies every proposed token, so the generated text is
-what the target would have produced on its own. Under greedy decoding a draft token is accepted only
-if it matches the target's own choice, and on rejection the target's token takes its place. Benchmark
-accuracy is therefore unchanged — you get the speedup, not a different model.
+Speculative decoding is **exact under greedy decoding**: the target verifies every proposed token, so the generated text is what the target would have produced on its own. Under matched sampling settings at non-zero temperatures, speculative decoding preserves the target model's output distribution. You get the speedup, not a different model.
 
 See [`LiquidAI/LFM2.5-VL-3B`](https://huggingface.co/LiquidAI/LFM2.5-VL-3B) for quality benchmarks.
 
-### Acceptance and speedup
+### Draft acceptance
 
-Following [MMSpec](https://arxiv.org/abs/2603.14989), speedups are measured on diverse vision-language
-tasks. All numbers use 16-bit precision for both the vision encoder and the language backbone;
-acceleration of quantized models is outside the scope of this release.
+This table reports the mean number of draft tokens accepted per target verification pass at batch size 1 and temperature 0. Higher acceptance generally enables greater acceleration, but the measured speedup also depends on hardware and runtime overhead.
 
-| Benchmark | Hardware | Runtime | Accepted tokens / step | Throughput | Speedup |
-|---|---|---|---:|---|---:|
-| MMSpec (testmini) | Apple M4 Max | llama.cpp | 4.04 | 62 → 140.8 tok/s | **2.27×** |
+Following [MMSpec](https://arxiv.org/abs/2603.14989), the evaluation covers General VQA, Text VQA, Image Captioning, Chart VQA, Complex Reasoning, and Multi-turn Conversation.
 
-<!-- TODO: full per-benchmark acceptance + speedup tables for H100 (SGLang) and Apple M4 Max (Metal/MLX).
-     The blog draft still has these figures as TBD. The 2.6B-DSpark card carries two tables here:
-     (1) mean accepted tokens per decoding step by benchmark, and (2) acceptance / H100 speedup /
-     M4 Max speedup. Populate both before publishing. -->
+| Benchmark  | 1×H100 (SGLang, block 9) | Apple M5 Max (MLX-VLM, block 8) | Apple M3 Ultra (llama.cpp, block 8) |
+| ---------- | ------------------------ | ------------------------------- | ----------------------------------- |
+| MMMU-Pro   | 4.00                     | 4.07                            | 4.19                                |
+| Multi-turn | 3.34                     | 3.24                            | 3.31                                |
+| COCO       | 4.38                     | 4.21                            | 4.50                                |
+| CharXiv    | 4.01                     | 4.34                            | 4.04                                |
+| TextVQA    | 3.68                     | 4.08                            | 3.58                                |
+| GQA        | 3.97                     | 3.77                            | 3.93                                |
 
-<!-- TODO: interactivity (throughput vs. concurrency on 1×H100, SGLang) — figure still TBD in the blog draft. -->
+### Measured inference speedup
 
-> [!NOTE]
-> On Apple silicon the drafter is run at block size 8 rather than 9.
+This table reports the resulting runtime performance relative to the same target model without DSpark. Each cell is formatted as **decode / end-to-end**.
 
-## 🏃 Inference
+| Dataset    | 1×H100 (SGLang) | Apple M5 Max (MLX-VLM) | Apple M3 Ultra (llama.cpp) |
+| ---------- | ---------------- | ---------------------- | -------------------------- |
+| MMMU-Pro   | 2.08× / 1.94×    | 2.93× / 2.62×          | 2.03× / 1.74×              |
+| Multi-turn | 2.00× / 1.79×    | 2.30× / 1.91×          | 1.57× / 1.37×              |
+| COCO       | 2.55× / 2.23×    | 3.13× / 2.59×          | 2.14× / 1.77×              |
+| CharXiv    | 2.36× / 1.96×    | 2.94× / 1.71×          | 1.87× / 1.56×              |
+| TextVQA    | 2.17× / 1.65×    | 2.69× / 1.56×          | 1.64× / 1.33×              |
+| GQA        | 2.35× / 1.74×    | 2.67× / 1.93×          | 1.77× / 1.30×              |
 
-LFM2.5-VL-3B-DSpark ships with day-one support across the inference ecosystem.
+All measurements use 16-bit processing for both the vision encoder and language backbone. The H100 results use SGLang on one H100 80GB in BF16 at batch size 1, temperature 0, and block size 9. The Apple results use FP16 weights at batch size 1, temperature 0, block size 8, and up to 2,048 output tokens. Measurements were collected with [Pipette](https://pipette.liquid.ai/).
 
-| Name | Description | Docs |
-|------|-------------|------|
-| [SGLang](https://github.com/sgl-project/sglang) | High-throughput production deployments with GPU. | <!-- TODO: docs.liquid.ai link for DSpark VL on SGLang --> — |
-| [llama.cpp](https://github.com/ggml-org/llama.cpp) | Cross-platform inference with CPU offloading. Use the [GGUF repo](https://huggingface.co/LiquidAI/LFM2.5-VL-3B-DSpark-GGUF). | <!-- TODO: docs.liquid.ai link --> — |
-| [MLX](https://github.com/ml-explore/mlx) | Apple's machine learning framework optimized for Apple Silicon. | <!-- TODO: confirm MLX-VLM support path and add docs link; no MLX repo published yet --> — |
+### Interactivity
 
-### How to run (SGLang)
+On a single H100, DSpark maintains a throughput advantage across all measured concurrency levels. The advantage narrows as concurrency increases and decoding becomes more compute-bound.
+
+## 🏃 Inference
 
-Requires a build of SGLang with DSpark support for LFM2 targets
-([PR #31041](https://github.com/sgl-project/sglang/pull/31041)), plus the VL-serving prerequisite
-(`Lfm2VlForConditionalGeneration` capture-hook delegation).
-<!-- TODO: confirm which SGLang release/PR carries the VL capture-hook delegation and link it. -->
+LFM2.5-VL-3B-DSpark is supported by SGLang for NVIDIA GPUs and MLX-VLM for Apple silicon. For llama.cpp, use the [GGUF checkpoint](https://huggingface.co/LiquidAI/LFM2.5-VL-3B-DSpark-GGUF).
 
-Launch the target with the draft attached:
+### SGLang
+
+Requires [SGLang v0.5.19 or newer](https://github.com/sgl-project/sglang/releases/tag/v0.5.19). Launch the target with the draft attached:
 
 ```bash
 python -m sglang.launch_server \
@@ -134,8 +117,24 @@ python -m sglang.launch_server \
   --disable-radix-cache --mem-fraction-static 0.8 --port 30000
 ```
 
-Then query the OpenAI-compatible endpoint at `http://localhost:30000/v1`. The baseline is the same
-command without the `--speculative-*` flags.
+Then query the OpenAI-compatible endpoint at `http://localhost:30000/v1`. The baseline is the same command without the `--speculative-*` flags.
+
+### MLX-VLM
+
+On Apple silicon, use [MLX-VLM](https://github.com/Blaizzy/mlx-vlm) v0.7.2 or newer. The drafter is detected automatically when passed with `--draft-model`:
+
+```bash
+python -m mlx_vlm.generate \
+  --model LiquidAI/LFM2.5-VL-3B \
+  --draft-model LiquidAI/LFM2.5-VL-3B-DSpark \
+  --draft-block-size 8 \
+  --image /path/to/image.jpg \
+  --prompt "Describe this image." \
+  --max-tokens 256 \
+  --temperature 0
+```
+
+DSpark decoding in MLX-VLM currently uses greedy sampling, so set `--temperature 0`.
 
 ## 📬 Contact
 
@@ -162,4 +161,4 @@ command without the `--speculative-*` flags.
   year = {2026},
   note = {www.liquid.ai/blog/lfm2-5-vl-dspark},
 }
-```
+```