docs + bounded-thinking: roll new context defaults across user-facing surfaces
Following 1a931b4 (long-text 130K + 0.95, long-vision 120K + 0.94), this
brings the rest of the user-visible surface in line:
bounded-thinking.yml gets the same backoff (was 218K + 0.985 → 130K + 0.95)
plus full patch parity with long-text (P37, PN17, compile-safe sidecar
mount + apply step, P104 already present).
User-facing docs updated:
- engines/VLLM.md TL;DR + KV cache table commentary.
- engines/LLAMA_CPP.md "when to use vLLM instead" (was citing 218K
text-only; now 130K).
- STRUCTURED_COT.md "When to pick this over the standard long-text"
(was 218K; now 130K).
- SINGLE_CARD.md picker table, the prominent ⚠️ box, the activation-
budget rationale, and the long-vision / long-text per-variant blurbs.
- models/qwen3.6-27b/README.md long-text/long-vision/bounded-thinking
one-liners.
Historical references (CLIFFS.md "Update 2026-04-30 PM" section, etc.)
left intact as record of what shipped at each pin.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
This commit is contained in:
co-authored by
Claude Opus 4.7
parent
1a931b4042
commit
d803278ebc
+9
-9
@@ -10,9 +10,9 @@ Four recommended options:
|
||||
|
||||
| What you're doing | Compose | Max ctx | Narr / Code TPS | VRAM (24 GB / card) |
|
||||
|---|---|---|---|---|
|
||||
| **Long ctx + vision** (chat, agents, image input) | [`long-vision.yml`](../models/qwen3.6-27b/vllm/compose/docker-compose.long-vision.yml) | **198K** | 51 / 68 | ~22.3 GB (mem-util 0.98) |
|
||||
| **Long ctx, text-only** (RAG, codebase, books) | [`long-text.yml`](../models/qwen3.6-27b/vllm/compose/docker-compose.long-text.yml) | **218K** | 50 / 66 | ~22.5 GB (mem-util 0.985) |
|
||||
| **Bounded thinking** (coding agents, structured-CoT, cost-bounded thinking) — see [STRUCTURED_COT.md](STRUCTURED_COT.md) | [`bounded-thinking.yml`](../models/qwen3.6-27b/vllm/compose/docker-compose.bounded-thinking.yml) | **218K** | ~53 / ~57 | ~22.5 GB (mem-util 0.985) |
|
||||
| **Long ctx + vision** (chat, agents, image input) | [`long-vision.yml`](../models/qwen3.6-27b/vllm/compose/docker-compose.long-vision.yml) | **120K** | ~50 / ~67 | ~22.1 GB (mem-util 0.94) |
|
||||
| **Long ctx, text-only** (RAG, codebase, books) | [`long-text.yml`](../models/qwen3.6-27b/vllm/compose/docker-compose.long-text.yml) | **130K** | ~50 / ~66 | ~22.4 GB (mem-util 0.95) |
|
||||
| **Bounded thinking** (coding agents, structured-CoT, cost-bounded thinking) — see [STRUCTURED_COT.md](STRUCTURED_COT.md) | [`bounded-thinking.yml`](../models/qwen3.6-27b/vllm/compose/docker-compose.bounded-thinking.yml) | **130K** | ~52 / ~56 | ~22.4 GB (mem-util 0.95) |
|
||||
| **Bulletproof, no cliffs** (production service, unpredictable inputs) | [`llamacpp/default`](../models/qwen3.6-27b/llama-cpp/compose/docker-compose.yml) | **262K** | 21 / 21 | ~20 GB |
|
||||
|
||||
Run via `bash scripts/launch.sh` (interactive) or `bash scripts/switch.sh <variant>`.
|
||||
@@ -21,11 +21,11 @@ Run via `bash scripts/launch.sh` (interactive) or `bash scripts/switch.sh <varia
|
||||
>
|
||||
> **vLLM single-card variants will crash if you send a single prompt above ~50K tokens.**
|
||||
>
|
||||
> This is Cliff 2 — DeltaNet GDN forward OOMs at 50–60K single-shot regardless of how much VRAM you have left. Both `long-vision.yml` (198K) and `long-text.yml` (218K) are designed for **steady-state accumulation across many turns** — context that builds up across tool calls, replies, retrieved chunks. They are NOT designed for "paste an 80K-token document and ask one question."
|
||||
> This is Cliff 2 — DeltaNet GDN forward OOMs at 50–60K single-shot regardless of how much VRAM you have left. Both `long-vision.yml` (120K) and `long-text.yml` (130K) are designed for **steady-state accumulation across many turns** — context that builds up across tool calls, replies, retrieved chunks. They are NOT designed for "paste an 80K-token document and ask one question."
|
||||
>
|
||||
> **If your workload ever sends single big prompts:** use `llamacpp/default` (262K, no cliffs anywhere — different engine entirely) or move to dual-card (`dual.yml` TP=2, verified at 237K).
|
||||
>
|
||||
> Cliff 1 (the 25K-token tool-prefill OOM that historically blocked these variants) is closed as of 2026-04-30 PM via the PN12 anchor sidecar. Tool-using agents that send big tool returns are fine on `long-vision` / `long-text`.
|
||||
> Cliff 1 mech B (FFN intermediate-buffer activation peak) was largely closed by PN12 + PN17 + P38 + our compile-safe sidecar. The downstream FA varlen workspace cliff at 50K-token tool prefills then surfaced — backing off to 130K + 0.95 (long-text) / 120K + 0.94 (long-vision) gives the necessary activation headroom. Re-push criteria in [`docs/CLIFFS.md`](CLIFFS.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -46,7 +46,7 @@ What this says about single-card constraints:
|
||||
- **Model weights** consume ~14 GB (AutoRound INT4 / GGUF Q3_K_XL). Half the card.
|
||||
- **KV cache** is the next biggest line; its size depends on `--kv-cache-dtype` × ctx. fp8 ≈ 1 byte/token/(layer×head); TQ3 ≈ 0.4 bytes/token/(layer×head); fp16 ≈ 2 bytes/token/(layer×head).
|
||||
- **Vision tower** (mmproj) costs ~0.5–1.0 GB extra when on.
|
||||
- **Activations + cudagraph pools** is what's left. At `--gpu-memory-utilization 0.92` (default 48K) you have 2-3 GB of activation headroom — comfortable. At 0.98–0.985 (long-vision / long-text), <0.5 GB — historically where Cliff 1 fired. **As of 2026-04-30 PM**, anchor-fixed PN12 (which actually pools FFN intermediates instead of fresh-allocating per layer) cuts allocator churn enough that long-vision survives 0.98 + 198K and long-text survives 0.985 + 218K. Pushing mem-util past 0.985 fails on this hardware (driver/system reserves ~440 MiB).
|
||||
- **Activations + cudagraph pools** is what's left. At `--gpu-memory-utilization 0.92` (default 48K) you have 2-3 GB of activation headroom — comfortable. **2026-05-01 PM** — long-vision / long-text were previously shipped at 0.98 / 0.985 mem-util but P37/P38 testing surfaced a downstream FA varlen workspace cliff at 50K-token tool prefills that none of our patches reach. Backed off to 130K + 0.95 (long-text) / 120K + 0.94 (long-vision) — adds ~1.5 GiB activation headroom which the FA workspace can grow into. Re-push criteria in [`docs/CLIFFS.md`](CLIFFS.md).
|
||||
|
||||
For the cross-card TP=2 picture, see [`DUAL_CARD.md`](DUAL_CARD.md).
|
||||
|
||||
@@ -58,13 +58,13 @@ For the cross-card TP=2 picture, see [`DUAL_CARD.md`](DUAL_CARD.md).
|
||||
|
||||
**Workload:** chat with images, vision-aware coding agents, multimodal RAG. Anything where the user might paste a screenshot.
|
||||
|
||||
198K + vision tower + TQ3 KV + Genesis MTP n=3 + PN12 anchor sidecar + P104 sidecar. Cliff 1 closed (25K-token tool prefills survive). `verify-full.sh` all 8 checks pass; `verify-stress.sh` tool-prefill passes at 643 chars.
|
||||
120K + vision tower + TQ3 KV + Genesis MTP n=3 + PN17 + P104 + P37/P38 + compile-safe sidecar at mem-util 0.94. `verify-full.sh` 8/8 (MTP AL 3.09); `verify-stress.sh` 130K-char tool-prefill OK. 200K-char tool-prefill (50K tokens) still cliffs — vision tower's persistent overhead tightens the margin.
|
||||
|
||||
### Long ctx, text-only — `long-text.yml` ⭐
|
||||
|
||||
**Workload:** RAG ingest, codebase analysis, book/document Q&A, long conversations without image input.
|
||||
|
||||
218K + no vision + TQ3 KV + same sidecars. Vision drop frees ~1 GB, lifting the ceiling 20K above long-vision (198K → 218K) and letting us run at 0.985 mem-util. Same Cliff 1 closure mechanism. MTP AL 2.66, VRAM 23.7/24 GB.
|
||||
130K + no vision + TQ3 KV + same patch stack at mem-util 0.95. `verify-full.sh` 8/8 (MTP AL 3.22); `verify-stress.sh` passes 200K-char tool-prefill (50K tokens) — the regime where 218K + 0.985 cliffed before the backoff. Vision drop adds ~1 GB headroom over long-vision so this variant survives the heavier prefills.
|
||||
|
||||
### Bulletproof / no cliffs — `llamacpp/default` ⭐
|
||||
|
||||
@@ -88,7 +88,7 @@ Re-tested 2026-04-30 PM against [`Luce-Org/lucebox-hub`](https://github.com/Luce
|
||||
|
||||
Measured TPS on this rig (RTX 3090, greedy, single-stream, n_gen=1000):
|
||||
|
||||
| Workload | Luce DFlash 3.6+3.6 (TQ3 KV, max_ctx=65K) | vLLM long-text 218K |
|
||||
| Workload | Luce DFlash 3.6+3.6 (TQ3 KV, max_ctx=65K) | vLLM long-text 130K |
|
||||
|---|---|---|
|
||||
| Narrative essay | 37–47 TPS (mean ~40) | 50 TPS |
|
||||
| Code (heap/LRU/AST) | 63–76 TPS (mean ~72) | 66 TPS |
|
||||
|
||||
@@ -49,7 +49,7 @@ andthattoo's headline numbers were on Qwen3.6-35B-A3B MoE Q4_K_M / H100 / llama.
|
||||
|
||||
Our FSM pass@1 lands within 2pp of theirs on both benchmarks — the technique reproduces cleanly across the model+quant+engine substitution. Our accuracy *delta* is bigger because our FREE baseline is weaker (more on this in Caveats).
|
||||
|
||||
## When to pick this over the standard `long-text` 218K
|
||||
## When to pick this over the standard `long-text` 130K
|
||||
|
||||
Pick `bounded-thinking` when **all three** of:
|
||||
|
||||
@@ -57,7 +57,7 @@ Pick `bounded-thinking` when **all three** of:
|
||||
2. You want bounded thinking cost as a structural guarantee (not just "the prompt asks nicely").
|
||||
3. Your workload tolerates a ~10% per-token TPS hit in exchange for ~30× cheaper think output (per-problem wall-clock is faster, not slower).
|
||||
|
||||
Pick `long-text` (the regular variant) when none of those apply. The two composes are otherwise identical (same 218K context, same MTP n=3, same TQ3 KV, same patches). The only difference is one vLLM flag — `--structured-outputs-config.enable_in_reasoning true`, which is what makes grammar enforcement actually fire inside the `<think>` block on this stack.
|
||||
Pick `long-text` (the regular variant) when none of those apply. The two composes are otherwise identical (same 130K context, same MTP n=3, same TQ3 KV, same patches). The only difference is one vLLM flag — `--structured-outputs-config.enable_in_reasoning true`, which is what makes grammar enforcement actually fire inside the `<think>` block on this stack.
|
||||
|
||||
## How to use it
|
||||
|
||||
|
||||
@@ -244,7 +244,7 @@ The q8 → q4_0 jump is **counter-intuitive** because q8 is "higher precision"
|
||||
## When to use vLLM instead
|
||||
|
||||
- You need full OpenAI API parity (tools, streaming, structured output)
|
||||
- You want max context (>218K) on a single 3090 — vLLM single-card tops out at 218K text-only; llama.cpp goes to 262K
|
||||
- You want max context (>130K) on a single 3090 — vLLM single-card currently ships 130K text-only / 120K with vision (backed off from 218K/198K for activation-headroom safety; see [docs/CLIFFS.md](../CLIFFS.md)); llama.cpp goes to 262K
|
||||
- You need concurrent serving (multi-tenant)
|
||||
- You want MTP spec-decode (the integrated head, not DFlash)
|
||||
- You're hitting llama.cpp's Qwen3-Next limitations and want the actively-developed path
|
||||
|
||||
@@ -10,7 +10,7 @@ This is what the repo's [Quick start](../../README.md#quick-start) ships. Everyt
|
||||
- ✅ Full feature set: vision, tools, streaming, thinking, MTP n=3, TurboQuant 3-bit KV
|
||||
- ✅ Full OpenAI API parity
|
||||
- 51-55 narr / 67-70 code TPS on a single 3090
|
||||
- 48K default ctx · 198K with vision · 218K text-only (Cliff 2 still applies single-prompt >50–60K)
|
||||
- 48K default ctx · 120K with vision · 130K text-only (backed off from earlier 198K/218K — see [docs/CLIFFS.md](../CLIFFS.md) "vLLM pin compatibility status" for why; Cliff 2 still applies single-prompt >50–60K)
|
||||
|
||||
---
|
||||
|
||||
@@ -49,7 +49,7 @@ bash scripts/bench.sh # 3 warmups + 5 measured (narr + code)
|
||||
| Pro | Detail |
|
||||
|---|---|
|
||||
| **Deepest Qwen3-Next feature support** | Vision tower, MTP head, all attention variants supported upstream. |
|
||||
| **TurboQuant 3-bit KV** | Lets us reach 198K + vision or 218K text-only on 24 GB. No equivalent in llama.cpp; SGLang has it but blocked by other bugs. |
|
||||
| **TurboQuant 3-bit KV** | Lets us reach 120K + vision or 130K text-only on 24 GB at the current safety-first config. No equivalent in llama.cpp; SGLang has it but blocked by other bugs. |
|
||||
| **MTP speculative decoding** | Works out of the box on the Lorbus quant; mainline llama.cpp doesn't expose MTP. |
|
||||
| **Active development** | Bugs we hit get triaged within days. We've contributed back. |
|
||||
| **Full OpenAI API parity** | Tools, streaming, vision-in-message, reasoning-mode, structured output — everything works. |
|
||||
@@ -80,7 +80,7 @@ Control context vs activation headroom. See the [Activation-memory caveat](../..
|
||||
| `turboquant_4bit_nc` | ~23 KB | ~84K | Untested by us — should work |
|
||||
| `turboquant_3bit_nc` ⭐ | ~17 KB | ~125K | Default v7.14 variant |
|
||||
|
||||
Lower bytes/token = more context, but more dequant scratch + activation pressure. The 3-bit variant is what enables the 198K + vision and 218K text-only tiers.
|
||||
Lower bytes/token = more context, but more dequant scratch + activation pressure. The 3-bit variant is what makes the 120K + vision and 130K text-only tiers reachable on 24 GB.
|
||||
|
||||
### Spec-decode (`--speculative-config`)
|
||||
|
||||
|
||||
@@ -50,9 +50,9 @@ How each config splits the 24 GB / card budget — weights, KV cache, vision tow
|
||||

|
||||
|
||||
As of 2026-04-30 PM, single-card recommended options (see [`docs/SINGLE_CARD.md`](../../docs/SINGLE_CARD.md)):
|
||||
- **`long-text.yml` — 218K text-only** at 0.985 mem-util. Verified cliff-safe via anchor-fixed PN12 + P104 sidecars.
|
||||
- **`long-vision.yml` — 198K + vision** at 0.98 mem-util. Same sidecars; vision tower's persistent ~1 GB makes 0.985 too tight here.
|
||||
- **`bounded-thinking.yml` — 218K text-only + structured-CoT grammar in reasoning** at 0.985 mem-util. Same patches as long-text plus `--structured-outputs-config.enable_in_reasoning true`. ~30× cheaper think output on coding workloads with **+4.3pp HE+ / +24pp LCB v6** vs FREE thinking. See [`docs/STRUCTURED_COT.md`](../../docs/STRUCTURED_COT.md).
|
||||
- **`long-text.yml` — 130K text-only** at 0.95 mem-util. Backed off from 218K + 0.985 on 2026-05-01 PM after P37/P38 testing showed the FA varlen workspace cliff at 50K-token tool prefills. P37/P38 + PN17 + P104 + compile-safe sidecar all on; Mamba block alignment forbids smaller chunk size, so the lever is context + mem-util. Re-push criteria in [`docs/CLIFFS.md`](../../docs/CLIFFS.md).
|
||||
- **`long-vision.yml` — 120K + vision** at 0.94 mem-util. Same backoff rationale; vision tower's persistent ~1 GB caps margin slightly tighter than text-only.
|
||||
- **`bounded-thinking.yml` — 130K text-only + structured-CoT grammar in reasoning** at 0.95 mem-util. Same patches as long-text plus `--structured-outputs-config.enable_in_reasoning true`. ~30× cheaper think output on coding workloads with **+4.3pp HE+ / +24pp LCB v6** vs FREE thinking. See [`docs/STRUCTURED_COT.md`](../../docs/STRUCTURED_COT.md).
|
||||
- **`llamacpp/default` — 262K + vision** at ~21 TPS. Different engine, no cliffs anywhere — production-safe for unpredictable inputs.
|
||||
|
||||
The **single shipped limitation** on the vLLM variants: Cliff 2 still fires on single prompts >50–60K (DeltaNet GDN forward OOM). Use llama.cpp single or dual-card for one-shot big prompts. See [`docs/CLIFFS.md`](../../docs/CLIFFS.md).
|
||||
|
||||
@@ -81,6 +81,7 @@ services:
|
||||
- ../patches/genesis/vllm/_genesis:/usr/local/lib/python3.12/dist-packages/vllm/_genesis:ro
|
||||
- ../patches/patch_tolist_cudagraph.py:/patches/patch_tolist_cudagraph.py:ro
|
||||
- ../patches/patch_pn12_ffn_pool_anchor.py:/patches/patch_pn12_ffn_pool_anchor.py:ro
|
||||
- ../patches/patch_pn12_compile_safe_custom_op.py:/patches/patch_pn12_compile_safe_custom_op.py:ro
|
||||
- ../patches/patch_fa_max_seqlen_clamp.py:/patches/patch_fa_max_seqlen_clamp.py:ro
|
||||
environment:
|
||||
# Uncomment the next line to pin to a specific GPU (e.g. GPU 0):
|
||||
@@ -108,6 +109,13 @@ services:
|
||||
- GENESIS_ENABLE_PN12_FFN_INTERMEDIATE_POOL=1
|
||||
- GENESIS_ENABLE_PN13_CUDA_GRAPH_LAMBDA_ARITY=1
|
||||
- GENESIS_ENABLE_FA_MAX_SEQLEN_CLAMP=1
|
||||
# 2026-05-01 — patch parity with long-text.yml. PN17 = Sandermage's
|
||||
# anchored FA softmax_lse clamp (covers flash_attn.py; P104 covers
|
||||
# turboquant_attn.py — keep both). P37 activates the buffer-manager
|
||||
# mode that P38 (TQ _continuation_prefill persistent workspace) uses
|
||||
# in shared mode. See long-text.yml for the full rationale.
|
||||
- GENESIS_ENABLE_PN17_FA2_LSE_CLAMP=1
|
||||
- GENESIS_ENABLE_P37=1
|
||||
shm_size: "16gb"
|
||||
ipc: host
|
||||
deploy:
|
||||
@@ -134,6 +142,7 @@ services:
|
||||
fi
|
||||
python3 -m vllm._genesis.patches.apply_all
|
||||
python3 /patches/patch_pn12_ffn_pool_anchor.py
|
||||
python3 /patches/patch_pn12_compile_safe_custom_op.py
|
||||
python3 /patches/patch_fa_max_seqlen_clamp.py
|
||||
python3 /patches/patch_tolist_cudagraph.py
|
||||
exec vllm serve "$@"
|
||||
@@ -149,10 +158,14 @@ services:
|
||||
- float16
|
||||
- --tensor-parallel-size
|
||||
- "1"
|
||||
# 130K + 0.95 — patch parity with long-text.yml (was 218K + 0.985).
|
||||
# Same FA varlen workspace cliff at 50K-token tool prefills; same
|
||||
# rationale; same backoff. See long-text.yml for the full trade-off
|
||||
# discussion and re-push criteria.
|
||||
- --max-model-len
|
||||
- "218000"
|
||||
- "130000"
|
||||
- --gpu-memory-utilization
|
||||
- "0.985"
|
||||
- "0.95"
|
||||
- --max-num-seqs
|
||||
- "1"
|
||||
- --max-num-batched-tokens
|
||||
|
||||
Reference in New Issue
Block a user