Panel controls (top of the command box):
diff --git a/docs_new/demo/deepseek_v4_flash.ipynb b/docs_new/demo/deepseek_v4_flash.ipynb
new file mode 100644
index 000000000..5f2f03495
--- /dev/null
+++ b/docs_new/demo/deepseek_v4_flash.ipynb
@@ -0,0 +1,1104 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "0",
+ "metadata": {},
+ "source": [
+ "# Deploying DeepSeek-V4-Flash with SGLang: Research Paper Synthesis\n",
+ "\n",
+ "This notebook will walk you through how to run the [`deepseek-ai/DeepSeek-V4-Flash`](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash) model on **2× NVIDIA B200s** using [SGLang](https://github.com/sgl-project/sglang), and use its 1M-token context window to synthesize insights across a live bundle of research papers pulled from arXiv.\n",
+ "\n",
+ "[SGLang](https://github.com/sgl-project/sglang) is a fast serving framework for large language models with RadixAttention for efficient KV cache reuse.\n",
+ "\n",
+ "For more details on the model, [click here](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash).\n",
+ "\n",
+ "> **Note on GPU count:** SGLang's validated recipe for DeepSeek-V4-Flash on B200 uses 4 GPUs (`--tp 4`). This notebook runs with 2 GPUs (`--tp 2`) as a starting point — it will work but is not on the fully benchmarked path. To match the validated configuration, change `--tp 2` to `--tp 4` and update `\"device=0,1\"` to `\"device=0,1,2,3\"` accordingly. See the [SGLang DeepSeek-V4 cookbook](https://lmsysorg.mintlify.app/cookbook/autoregressive/DeepSeek/DeepSeek-V4) for all hardware recipes.\n",
+ "\n",
+ "Prerequisites:\n",
+ "- NVIDIA GPU(s) with recent drivers (this notebook uses 2×B200)\n",
+ "- A Hugging Face account with access to [`deepseek-ai/DeepSeek-V4-Flash`](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash)\n",
+ "- Internet access for the arXiv API\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "1",
+ "metadata": {},
+ "source": [
+ "## Overview\n",
+ "\n",
+ "- **Serve** DeepSeek-V4-Flash on 2× NVIDIA B200s using SGLang\n",
+ "- **Fetch** a live bundle of research papers from the arXiv API — no account required\n",
+ "- **Synthesize** a research map, theme clusters, open problems, and cross-paper comparisons\n",
+ "- **Compare** Non-Think and Think-High reasoning modes on a complex synthesis question"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "2",
+ "metadata": {},
+ "source": [
+ "## Table of Contents\n",
+ "\n",
+ "1. **Install dependencies** — client packages\n",
+ "2. **Start the SGLang server** — Docker command with configuration reference\n",
+ "3. **Fetch research papers** — arXiv API search, optional PDF download\n",
+ "4. **Build the research bundle** — context assembly\n",
+ "5. **Research map** — field overview, themes, open problems\n",
+ "6. **Deep-dive questions** — cross-paper methodology and benchmarking analysis\n",
+ "7. **Non-Think vs Think-High** — reasoning mode comparison"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3",
+ "metadata": {},
+ "source": [
+ "## Step 0 — Install Dependencies"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "4",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "%pip install --quiet --upgrade openai arxiv pypdf requests"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "# Paste your token here if you haven't run `huggingface-cli login`\n",
+ "# os.environ[\"HF_TOKEN\"] = \"hf_...\""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "6",
+ "metadata": {},
+ "source": [
+ "## Step 1 — Start the SGLang Server\n",
+ "\n",
+ "Run the following command in a separate terminal before continuing. Leave the server running while this notebook executes.\n",
+ "\n",
+ "### Docker (recommended)\n",
+ "\n",
+ "The `lmsysorg/sglang:latest` image includes the full CUDA toolkit, so FP4/FP8 JIT kernels compile correctly without requiring any additional setup on the host.\n",
+ "\n",
+ "```bash\n",
+ "docker run --gpus '\"device=0,1\"' \\\n",
+ " --shm-size 32g \\\n",
+ " -p 30000:30000 \\\n",
+ " -v ~/.cache/huggingface:/root/.cache/huggingface \\\n",
+ " --ipc=host \\\n",
+ " lmsysorg/sglang:latest \\\n",
+ " sglang serve \\\n",
+ " --trust-remote-code \\\n",
+ " --model-path deepseek-ai/DeepSeek-V4-Flash \\\n",
+ " --tp 2 \\\n",
+ " --moe-runner-backend flashinfer_mxfp4 \\\n",
+ " --speculative-algorithm EAGLE \\\n",
+ " --speculative-num-steps 3 \\\n",
+ " --speculative-eagle-topk 1 \\\n",
+ " --speculative-num-draft-tokens 4 \\\n",
+ " --chunked-prefill-size 4096 \\\n",
+ " --disable-flashinfer-autotune \\\n",
+ " --swa-full-tokens-ratio 0.1 \\\n",
+ " --reasoning-parser deepseek-v4 \\\n",
+ " --host 0.0.0.0 \\\n",
+ " --port 30000\n",
+ "```\n",
+ "\n",
+ "> **Note:** `~/.cache/huggingface` is mounted into the container so that previously downloaded model weights are reused automatically. To use 4 GPUs (the fully validated recipe), change `\"device=0,1\"` to `\"device=0,1,2,3\"` and `--tp 2` to `--tp 4`. See the [SGLang DeepSeek-V4 cookbook](https://lmsysorg.mintlify.app/cookbook/autoregressive/DeepSeek/DeepSeek-V4) for all hardware and recipe combinations.\n",
+ "\n",
+ "### Configuration reference\n",
+ "\n",
+ "| Flag | Purpose |\n",
+ "|---|---|\n",
+ "| `--tp 2` | Tensor-parallel across 2 GPUs (use `--tp 4` for the validated recipe) |\n",
+ "| `--moe-runner-backend flashinfer_mxfp4` | FP4 MoE kernel required for DeepSeek-V4's expert weights |\n",
+ "| `--speculative-algorithm EAGLE` | EAGLE speculative decoding; reduces time-to-first-token at low batch sizes |\n",
+ "| `--chunked-prefill-size 4096` | Chunked prefill for stable long-context processing |\n",
+ "| `--reasoning-parser deepseek-v4` | Parses `...` blocks and exposes `reasoning_content` in responses |\n",
+ "\n",
+ "> **Expected output:** Wait for `The server is fired up and ready to roll!` before continuing. On first run, model weights will be downloaded from Hugging Face; this may take several minutes."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "7",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Waiting... (1/30)\n",
+ "Server ready.\n"
+ ]
+ }
+ ],
+ "source": [
+ "import requests, time\n",
+ "\n",
+ "SGLANG_BASE_URL = \"http://localhost:30000\"\n",
+ "\n",
+ "for attempt in range(30):\n",
+ " try:\n",
+ " if requests.get(f\"{SGLANG_BASE_URL}/health\", timeout=5).status_code == 200:\n",
+ " print(\"Server ready.\")\n",
+ " break\n",
+ " except requests.exceptions.ConnectionError:\n",
+ " pass\n",
+ " print(f\"Waiting... ({attempt + 1}/30)\")\n",
+ " time.sleep(10)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "8",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "['deepseek-ai/DeepSeek-V4-Flash']\n"
+ ]
+ }
+ ],
+ "source": [
+ "from openai import OpenAI\n",
+ "\n",
+ "client = OpenAI(base_url=f\"{SGLANG_BASE_URL}/v1\", api_key=\"not-needed\")\n",
+ "MODEL = \"deepseek-ai/DeepSeek-V4-Flash\"\n",
+ "\n",
+ "print([m.id for m in client.models.list().data])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9",
+ "metadata": {},
+ "source": [
+ "## Step 2 — Fetch Research Papers from arXiv\n",
+ "\n",
+ "The [`arxiv`](https://github.com/lukasschwab/arxiv.py) client retrieves papers through the [arXiv API](https://arxiv.org/help/api/) — no account required.\n",
+ "\n",
+ "The default query targets LLM inference papers, which are directly relevant to the frameworks and model architecture covered in this notebook. Set `SEARCH_QUERY` to any topic of interest. Full arXiv query syntax is documented at [arxiv.org/help/api/user-manual](https://arxiv.org/help/api/user-manual#query_details)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "10",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ " 1. [2026-06-22] Kamera: Unified Position-Invariant Multimodal KV Cache for Training-Free Reuse\n",
+ " Bole Ma, Jan Eitzinger, Harald Koestler, Gerhard Wellein\n",
+ " 2. [2026-06-22] Concordia: JIT-Compiled Persistent-Kernel Checkpointing for Fault-Tolerant LLM Inference\n",
+ " Yuhang Gan, Yiwei Yang, Yuyi Li, Xiangyu Gao, Yichen Wang et al.\n",
+ " 3. [2026-06-22] EnerInfer: Energy-Aware On-Device LLM Inference\n",
+ " Bohua Zou, Nian Liu, Binqi Sun, Matteo Mascherin, Debayan Roy et al.\n",
+ " 4. [2026-06-22] MOCAP: Wafer-Scale-Chip-Oriented Memory-Orchestrated Chunked Pipelining Framework for Prefill-Only LLM Inference\n",
+ " Zichuan Wang, Huizheng Wang, Yuheng Xiao, Haonan Zuo, Taiquan Wei et al.\n",
+ " 5. [2026-06-22] RLM-Cascade: Response-Level Speculative Decoding for Cost-Efficient LLM API Serving\n",
+ " Haifeng Wu, Srinivasan Manoharan, Fangbo Tu, Junhua Zhao, Jian Wan\n",
+ " 6. [2026-06-21] Evidence-Bound Gateway-Path Provenance for Third-Party LLM Inference\n",
+ " Fei Wang, Zebai Tian\n",
+ " 7. [2026-06-20] The Language-Energy Divide: Measuring Energy Costs of Multilingual LLM Inference\n",
+ " Naihao Deng, Alissa Shen, Yiming Feng, Joan Nwatu, Jae-Won Chung et al.\n",
+ " 8. [2026-06-20] Agent-Assisted Side-Channel Attacks on Non-Prefix KV Cache in RAG\n",
+ " He Sun, Shinan Liu, Siyuan Ma, Junhao Li, Mingjun Xiao et al.\n",
+ " 9. [2026-06-19] HERALD: High-Throughput Block Diffusion LLM Serving via CPU-GPU Cooperative KV Cache Retrieval\n",
+ " Omin Kwon, Doyeon Kim, Jongseok Park, Seung Yul Lee, Ion Stoica et al.\n",
+ "10. [2026-06-19] Recency/Frequency Adaptive KV Caching for Large Language Model Serving\n",
+ " Yang Shen, Meghana Madhyastha, Robert Underwood, Bogdan Nicolae, Randal Burns\n",
+ "11. [2026-06-19] Demystifying Numerical Instability in LLM Inference: Achieving Reproducible Inference for Mission-Critical Tasks with HEAL\n",
+ " Zhenting Zhu, Lucas Thai, Shan Yu, Yicheng Liu, Yifan Qiao et al.\n",
+ "12. [2026-06-18] SSD: Spatially Speculative Decoding Accelerates Autoregressive Image Generation\n",
+ " Shilong Xiang, Zirui Zhang, Lijun Yu, Chengzhi Mao\n",
+ "13. [2026-06-18] UltraQuant: 4-bit KV Caching for Context-Heavy Agents\n",
+ " Inesh Chakrabarti, David Limpus, Aditi Ghai Rana, Bowen Bao, Spandan Tiwari et al.\n",
+ "14. [2026-06-18] Navigating Unreliable Parametric and Contextual Knowledge: Explicit Knowledge Conflict Resolution for LLM Inference\n",
+ " Huang Peng, Jiuyang Tang, Weixin Zeng, Hao Xu, Xiang Zhao\n",
+ "15. [2026-06-18] SAC: Disaggregated KV Cache System for Sparse Attention LLMs with CXL\n",
+ " Ruiyang Ma, Teng Ma, Junru Li, Hantian Zha, Xuchun Shang et al.\n",
+ "16. [2026-06-17] EfficientRollout: System-Aware Self-Speculative Decoding for RL Rollouts\n",
+ " Minseo Kim, Minjae Lee, Seunghyuk Oh, Kevin Galim, Donghoon Kim et al.\n",
+ "17. [2026-06-17] From Tokens to Energy Flexibility: Quantization-Enabled Demand Response for Data Centers with LLM Inference Workloads\n",
+ " Bojun Du, Xiaoyi Fan, Ershun Du, Long Chen, Jianpei Han et al.\n",
+ "18. [2026-06-16] Beyond Prediction: Tail-Aware Scheduling for LLM Inference\n",
+ " Yueying Li, Yuanfan Chen, Jiayang Chen, Esha Choukse, Haoran Qiu et al.\n",
+ "19. [2026-06-16] JetFlow: Breaking the Scaling Ceiling of Speculative Decoding with Parallel Tree Drafting\n",
+ " Lanxiang Hu, Zhaoxiang Feng, Yulun Wu, Haoran Yuan, Yujie Zhao et al.\n",
+ "20. [2026-06-16] Latency Prediction for LLM Inference on NPU Systems\n",
+ " Juhyun Park, Seungwoo Jeong, Jingyu Lee, Kyungyong Lee\n"
+ ]
+ }
+ ],
+ "source": [
+ "import arxiv\n",
+ "import time\n",
+ "\n",
+ "SEARCH_QUERY = (\n",
+ " 'ti:\"LLM inference\" OR ti:\"efficient inference\" OR ti:\"speculative decoding\" '\n",
+ " 'OR ti:\"continuous batching\" OR ti:\"KV cache\" OR ti:\"paged attention\"'\n",
+ ")\n",
+ "MAX_PAPERS = 20\n",
+ "MAX_ABSTRACT_CHARS = 2000\n",
+ "\n",
+ "search = arxiv.Search(\n",
+ " query=SEARCH_QUERY,\n",
+ " max_results=MAX_PAPERS,\n",
+ " sort_by=arxiv.SortCriterion.SubmittedDate,\n",
+ " sort_order=arxiv.SortOrder.Descending,\n",
+ ")\n",
+ "\n",
+ "papers = []\n",
+ "for result in arxiv.Client(delay_seconds=3, num_retries=5).results(search):\n",
+ " papers.append(\n",
+ " {\n",
+ " \"id\": result.entry_id.split(\"/\")[-1],\n",
+ " \"title\": result.title,\n",
+ " \"authors\": \", \".join(a.name for a in result.authors[:5])\n",
+ " + (\" et al.\" if len(result.authors) > 5 else \"\"),\n",
+ " \"published\": result.published.strftime(\"%Y-%m-%d\"),\n",
+ " \"abstract\": result.summary.replace(\"\\n\", \" \")[:MAX_ABSTRACT_CHARS],\n",
+ " \"categories\": \", \".join(result.categories),\n",
+ " \"pdf_url\": result.pdf_url,\n",
+ " }\n",
+ " )\n",
+ " time.sleep(1) # extra courtesy delay between results\n",
+ "\n",
+ "for i, p in enumerate(papers, 1):\n",
+ " print(f\"{i:>2}. [{p['published']}] {p['title']}\")\n",
+ " print(f\" {p['authors']}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "11",
+ "metadata": {},
+ "source": [
+ "### Optional — Download Full Paper Text\n",
+ "\n",
+ "Downloads PDFs for the first `N_FULL_PAPERS` results and extracts their text. Skip this step if abstracts are sufficient for your use case."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "12",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "[1/5] Kamera: Unified Position-Invariant Multimodal KV Cache for Training-Fr — 30,000 chars\n",
+ "[2/5] Concordia: JIT-Compiled Persistent-Kernel Checkpointing for Fault-Tole — 30,000 chars\n",
+ "[3/5] EnerInfer: Energy-Aware On-Device LLM Inference — 30,000 chars\n",
+ "[4/5] MOCAP: Wafer-Scale-Chip-Oriented Memory-Orchestrated Chunked Pipelinin — 30,000 chars\n",
+ "[5/5] RLM-Cascade: Response-Level Speculative Decoding for Cost-Efficient LL — 30,000 chars\n"
+ ]
+ }
+ ],
+ "source": [
+ "import pathlib\n",
+ "import pypdf\n",
+ "\n",
+ "N_FULL_PAPERS = 5\n",
+ "MAX_PDF_CHARS = 30_000\n",
+ "PDF_CACHE_DIR = pathlib.Path(\"./arxiv_pdfs\")\n",
+ "PDF_CACHE_DIR.mkdir(exist_ok=True)\n",
+ "\n",
+ "\n",
+ "def download_and_extract(paper: dict) -> str:\n",
+ " cache_path = PDF_CACHE_DIR / f\"{paper['id']}.pdf\"\n",
+ " if not cache_path.exists():\n",
+ " resp = requests.get(paper[\"pdf_url\"], timeout=60)\n",
+ " resp.raise_for_status()\n",
+ " cache_path.write_bytes(resp.content)\n",
+ " text = \"\"\n",
+ " for page in pypdf.PdfReader(str(cache_path)).pages:\n",
+ " text += page.extract_text() or \"\"\n",
+ " if len(text) >= MAX_PDF_CHARS:\n",
+ " break\n",
+ " return text[:MAX_PDF_CHARS]\n",
+ "\n",
+ "\n",
+ "for i, paper in enumerate(papers[:N_FULL_PAPERS]):\n",
+ " try:\n",
+ " paper[\"full_text\"] = download_and_extract(paper)\n",
+ " print(\n",
+ " f\"[{i+1}/{N_FULL_PAPERS}] {paper['title'][:70]} — {len(paper['full_text']):,} chars\"\n",
+ " )\n",
+ " except Exception as e:\n",
+ " paper[\"full_text\"] = None\n",
+ " print(f\"[{i+1}/{N_FULL_PAPERS}] {paper['title'][:70]} — failed: {e}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "13",
+ "metadata": {},
+ "source": [
+ "---\n",
+ "## Step 3 — Build the Research Bundle"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "14",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "185,132 chars | ~46,283 tokens | 5 papers with full text\n"
+ ]
+ }
+ ],
+ "source": [
+ "def format_paper(paper: dict, index: int) -> str:\n",
+ " parts = [\n",
+ " f\"## Paper {index}: {paper['title']}\",\n",
+ " f\"**Authors:** {paper['authors']}\",\n",
+ " f\"**Published:** {paper['published']} | **arXiv ID:** {paper['id']}\",\n",
+ " f\"**Categories:** {paper['categories']}\",\n",
+ " \"\",\n",
+ " \"**Abstract:**\",\n",
+ " paper[\"abstract\"],\n",
+ " ]\n",
+ " if paper.get(\"full_text\"):\n",
+ " parts += [\"\", \"**Full Text (excerpt):**\", paper[\"full_text\"]]\n",
+ " return \"\\n\".join(parts)\n",
+ "\n",
+ "\n",
+ "bundle_sections = [\n",
+ " f\"# Research Bundle: Efficient LLM Inference\\n**Papers:** {len(papers)}\"\n",
+ "]\n",
+ "for i, paper in enumerate(papers, 1):\n",
+ " bundle_sections.append(format_paper(paper, i))\n",
+ "\n",
+ "research_bundle = \"\\n\\n---\\n\\n\".join(bundle_sections)\n",
+ "\n",
+ "print(\n",
+ " f\"{len(research_bundle):,} chars | ~{len(research_bundle) // 4:,} tokens | \"\n",
+ " f\"{sum(1 for p in papers if p.get('full_text'))} papers with full text\"\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "15",
+ "metadata": {},
+ "source": [
+ "## Step 4 — Generate a Research Map\n",
+ "\n",
+ "This is the initial call and the longest — it encodes the full research bundle into the KV cache. Subsequent queries reuse that cache automatically via SGLang's RadixAttention."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "16",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Here is the Research Map based on the provided bundle of 20 papers on efficient LLM inference.\n",
+ "\n",
+ "---\n",
+ "\n",
+ "### 1. Field Overview\n",
+ "\n",
+ "The core problem is that **Large Language Model (LLM) inference is becoming prohibitively expensive and complex** as models scale, context windows lengthen, and deployment moves toward long-running, multi-turn agents. The field is shifting from optimizing for raw throughput to a **holistic systems-level approach** that must jointly manage memory (KV cache), latency (tail & prefill), energy (power & thermal), and reliability (fault tolerance & security) across heterogeneous hardware (GPUs, NPUs, WSCs) and deployment models (cloud, on-device, third-party APIs). This bundle of 2026 papers reflects a mature field where the \"low-hanging fruit\" of basic batching and parallelism has been exhausted, and the frontier is now defined by **specialized, co-designed, and often training-free** techniques that exploit the unique structural properties of LLM inference.\n",
+ "\n",
+ "### 2. Research Themes\n",
+ "\n",
+ "**Theme 1: KV Cache Management & Memory Orchestration**\n",
+ "*Focuses on the KV cache as the primary bottleneck, moving beyond simple eviction to proactive, structured, and hardware-aware management.*\n",
+ "\n",
+ "- **Papers:** 1 (Kamera), 4 (MOCAP), 10 (Recency/Frequency Adaptive), 13 (UltraQuant), 15 (SAC)\n",
+ "- **Key Insight:** The KV cache is not a monolithic buffer but a structured, position-dependent asset. The most impactful optimizations come from **separating the cache's content (what) from its position (where)** (Kamera), **redistributing it across pipeline stages** to balance memory pressure (MOCAP), or **selectively fetching only the active \"sparse\" entries** via low-latency interconnects like CXL (SAC). This represents a shift from reactive eviction (LRU) to proactive, system-aware orchestration.\n",
+ "\n",
+ "**Theme 2: Speculative Decoding & Draft-Verify Pipelines**\n",
+ "*Exploits the asymmetry in cost/speed between a \"draft\" model and a \"verify\" model to accelerate generation or reduce API costs.*\n",
+ "\n",
+ "- **Papers:** 5 (RLM-Cascade), 12 (SSD), 16 (EfficientRollout), 19 (JetFlow)\n",
+ "- **Key Insight:** The core idea has been generalized from **token-level** to **response-level** (RLM-Cascade) and **spatial-level** (SSD). The critical challenge is no longer just the draft-verify mechanism itself, but **managing the \"draft budget\"** : how many tokens to draft, when to stop, and how to handle the evolving distribution of the target model (EfficientRollout). JetFlow breaks the scaling ceiling by using a **causal parallel draft head** that avoids the inefficiency of autoregressive drafting.\n",
+ "\n",
+ "**Theme 3: Energy & Resource-Aware Inference**\n",
+ "*Treats energy, power, and thermal constraints as first-class optimization objectives, not just secondary concerns.*\n",
+ "\n",
+ "- **Papers:** 3 (EnerInfer), 7 (Language-Energy Divide), 17 (From Tokens to Energy Flexibility)\n",
+ "- **Key Insight:** The field is moving from \"fastest is best\" to **\"efficient-enough is best\"** . There is significant, exploitable \"configuration slack\" (EnerInfer) where modestly lowering frequencies preserves QoE but drastically improves energy efficiency. This is a **systemic inequity** (Paper 7) that is not just a hardware problem but is also **model-dependent** (e.g., low-resource languages generate more tokens, compounding the cost).\n",
+ "\n",
+ "**Theme 4: Fault Tolerance & Security for Long-Running Agents**\n",
+ "*Addresses the unique reliability and security challenges of persistent, stateful LLM agents.*\n",
+ "\n",
+ "- **Papers:** 2 (Concordia), 6 (Evidence-Bound Gateway), 8 (Agent-Assisted Side-Channel), 11 (HEAL)\n",
+ "- **Key Insight:** The \"always-on\" nature of agents creates a **new threat model** where state (KV cache, scheduler) is valuable and must be protected. Concordia argues for **GPU-resident, persistent checkpointing** as the substrate for fault tolerance, moving the recovery contract below the framework. HEAL addresses a different, but related, reliability problem: **numerical instability** in mission-critical tasks, where FP16 precision can cause catastrophic output divergence.\n",
+ "\n",
+ "**Theme 5: Systems Co-Design & Hardware-Aware Scheduling**\n",
+ "*Optimizes the entire serving stack by co-designing algorithms with specific hardware (WSCs, NPUs, CXL) and scheduling policies.*\n",
+ "\n",
+ "- **Papers:** 4 (MOCAP), 15 (SAC), 18 (Beyond Prediction), 20 (LENS)\n",
+ "- **Key Insight:** The most effective optimizations are **not portable** across hardware. MOCAP is explicitly designed for the unique communication topology of Wafer-Scale Chips. SAC leverages CXL's cache-line granularity. LENS provides a prediction methodology for **opaque NPU systems** where microarchitecture is undisclosed. This theme highlights the move away from \"one-size-fits-all\" GPU solutions toward **specialized, hardware-aware** frameworks.\n",
+ "\n",
+ "**Theme 6: Cost & Latency Optimization at the API/Service Layer**\n",
+ "*Focuses on the economic and operational realities of serving LLMs through third-party APIs and managing request-level variability.*\n",
+ "\n",
+ "- **Papers:** 5 (RLM-Cascade), 18 (Beyond Prediction), 20 (LENS)\n",
+ "- **Key Insight:** The \"last mile\" of inference is the **API call**. RLM-Cascade shows that response-level speculative decoding can be **cheaper, faster, and more accurate** than a direct call to a frontier model, because the \"SKIPPED\" path (cheap model only) dominates the workload. This is a counter-intuitive result that challenges the assumption that \"better\" models are always better. The key is **routing precision**, not just model quality.\n",
+ "\n",
+ "### 3. Chronological Progression\n",
+ "\n",
+ "- **Superseded Idea: \"Faster is always better.\"** The field has moved from a single-minded focus on maximizing throughput (tokens/s) to a multi-objective optimization that includes energy efficiency (EnerInfer), tail latency (Beyond Prediction), and cost (RLM-Cascade). The idea that \"maximum frequency\" is the default is now recognized as a source of significant inefficiency.\n",
+ "\n",
+ "- **Superseded Idea: \"One-size-fits-all GPU optimization.\"** The success of MOCAP (WSC-specific), SAC (CXL-specific), and LENS (NPU-specific) shows that the most impactful optimizations are now **hardware-specific**. The era of generic \"GPU-optimized\" serving is giving way to specialized, co-designed systems.\n",
+ "\n",
+ "- **Superseded Idea: \"Token-level speculative decoding is the only way.\"** The field has generalized the draft-verify concept to **response-level** (RLM-Cascade) and **spatial-level** (SSD). This opens up new deployment models (e.g., API proxies) and new application domains (e.g., image generation) that were previously inaccessible to the technique.\n",
+ "\n",
+ "- **Superseded Idea: \"KV cache is a simple, linear structure.\"** The work on Kamera (position-invariant), MOCAP (memory-balanced), and SAC (sparse attention) has fundamentally reframed the KV cache as a **complex, structured, and dynamic asset** that can be decomposed, relocated, and selectively accessed, rather than just a contiguous block to be evicted.\n",
+ "\n",
+ "### 4. Open Problems\n",
+ "\n",
+ "1. **The \"Draft Budget\" Problem for Speculative Decoding:** How many tokens should a draft model generate? The optimal budget is highly dynamic, depending on the model, task, and hardware. JetFlow's causal parallel head is a step, but a **general, online, and system-aware** solution for managing the draft budget remains an open problem.\n",
+ "\n",
+ "2. **Cross-Architecture Portability for Hardware-Aware Systems:** MOCAP, SAC, and LENS are all highly specialized. How can the insights from these systems be **generalized** into a portable framework that works across GPUs, NPUs, WSCs, and CXL-based memory pools without requiring a complete re-implementation for each target?\n",
+ "\n",
+ "3. **The \"Energy Divide\" as a First-Class Metric:** Paper 7 shows a 179x energy cost disparity between languages. The field lacks a **standardized, reproducible methodology** for measuring and reporting this cost. Until energy is a standard axis in model cards and leaderboards, this systemic inequity will remain unaddressed.\n",
+ "\n",
+ "4. **Reconciling Memory Deduplication with Security:** SpliceLeak (Paper 8) demonstrates a fundamental conflict: the very mechanisms (chunk alignment, boundary fusion) that enable efficient KV cache sharing also create a **deterministic timing side-channel**. A principled, provably secure solution that preserves the benefits of global cache sharing is an open problem.\n",
+ "\n",
+ "5. **Fault Tolerance for \"Stateless\" Agents:** The Concordia model assumes a persistent, stateful agent. However, many current deployments are \"stateless\" (each request is a fresh context). How can the principles of GPU-resident checkpointing be applied to this **more common, but equally failure-prone**, deployment model without requiring a fundamental redesign of the serving stack?\n",
+ "\n",
+ "### 5. Practitioner Takeaways\n",
+ "\n",
+ "1. **Deploy a \"Response-Level Speculative Decoding\" API Proxy (RLM-Cascade).** This is the most immediately deployable idea. It requires no model internals access, works across any HTTP API, and can be **cheaper, faster, and more accurate** than a direct call to a frontier model. The key is a simple, rule-based router that identifies \"simple\" turns. This is a direct path to reducing API costs by 45-67% in production.\n",
+ "\n",
+ "2. **Adopt a \"Configuration Slack\" Energy Management Policy (EnerInfer).** For on-device or edge deployments, the default \"max frequency\" setting is wasteful. Implement a simple, offline prediction pipeline that maps model structure (e.g., number of layers, heads) to the most energy-efficient NPU/DDR frequency that still meets a user-defined QoE threshold (e.g., 10 tokens/s). This can yield 9-65% energy efficiency improvements with no QoE violation.\n",
+ "\n",
+ "3. **Use a \"Position-Invariant\" KV Cache for Long-Horizon Agents (Kamera).** If your agent repeatedly re-examines the same video frames or documents, the standard prefix cache is a bottleneck. Store the KV cache as a **position-free \"canonical\" chunk** plus a **small, low-rank \"conditioning patch\"** . This allows for O(1) reordering, sliding-window survival, and recall, turning expensive re-prefills into cheap cache edits. The patch is training-free and can be deployed in a production SGLang kernel.\n"
+ ]
+ }
+ ],
+ "source": [
+ "RESEARCH_MAP_PROMPT = \"\"\"\\\n",
+ "Here is a bundle of research papers on efficient LLM inference:\n",
+ "\n",
+ "{bundle}\n",
+ "\n",
+ "---\n",
+ "\n",
+ "Produce a Research Map with these sections:\n",
+ "\n",
+ "1. **Field Overview** (3–5 sentences): The core problem and why it matters now.\n",
+ "\n",
+ "2. **Research Themes**: 4–6 distinct themes across these papers. For each:\n",
+ " - Name and one-sentence description\n",
+ " - Which papers belong to it (by number and title)\n",
+ " - Key insight that defines the theme\n",
+ "\n",
+ "3. **Chronological Progression**: How has the field evolved? What ideas were superseded?\n",
+ "\n",
+ "4. **Open Problems**: 3–5 important unsolved problems.\n",
+ "\n",
+ "5. **Practitioner Takeaways**: Which 3 ideas are most ready to deploy today?\n",
+ "\"\"\"\n",
+ "\n",
+ "response = client.chat.completions.create(\n",
+ " model=MODEL,\n",
+ " messages=[\n",
+ " {\"role\": \"user\", \"content\": RESEARCH_MAP_PROMPT.format(bundle=research_bundle)}\n",
+ " ],\n",
+ " max_tokens=3000,\n",
+ " temperature=0.3,\n",
+ ")\n",
+ "print(response.choices[0].message.content)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "17",
+ "metadata": {},
+ "source": [
+ "## Step 5 — Deep-Dive Cross-Paper Questions\n",
+ "\n",
+ "These queries run against the same context as Step 4. SGLang's RadixAttention reuses the cached KV prefix from the previous call, so each subsequent query is faster than the first.\n",
+ "\n",
+ "Edit `DEEP_DIVE_QUESTIONS` to explore the topics most relevant to your work."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "18",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\n",
+ "[Methodology comparison]\n",
+ "────────────────────────────────────────────────────────────\n",
+ "# Comparative Analysis of Memory Management Strategies in LLM Inference\n",
+ "\n",
+ "## Overview\n",
+ "\n",
+ "The 20 papers in this bundle address memory management at different levels of the LLM inference stack, from low-level KV cache manipulation to system-level memory orchestration across devices. I identify three distinct clusters of shared approach and two genuine departures.\n",
+ "\n",
+ "## Cluster 1: KV Cache as Reusable Content (Papers 1, 8, 9, 10, 13, 15)\n",
+ "\n",
+ "**Shared fundamental approach:** These papers treat the KV cache as a *storable, reusable asset* that can be retained, compressed, or selectively retrieved across inference steps. They all operate on the principle that the KV cache contains redundant information that can be exploited to reduce recomputation.\n",
+ "\n",
+ "**Paper 1 (Kamera)** is the most sophisticated member of this cluster. It introduces **position-invariant KV caching** where chunks are stored with a canonical content channel and a separate positional RoPE rotation. The key innovation is the **low-rank conditioning patch** (Equation 1) that restores cross-chunk binding lost during naive reuse. This is a genuine extension of the reuse paradigm, not a departure—it shares the same \"store and reuse\" philosophy as papers 8, 9, 10, and 13, but adds a *correction term* for the specific failure mode of multi-hop reasoning.\n",
+ "\n",
+ "**Paper 8 (SpliceLeak)** takes the opposite stance: it treats KV cache reuse as a *security vulnerability*. The \"Step-Wave\" timing signature from chunk-aware memory scheduling is exploited for side-channel attacks. This paper shares the same *observation* that KV cache is structured and reusable, but frames it as an attack surface rather than an optimization. It is **not a departure** in approach—it uses the same chunked storage model as Kamera—but it is a departure in *objective*.\n",
+ "\n",
+ "**Paper 9 (HERALD)** and **Paper 15 (SAC)** form a sub-cluster within this group. Both address **sparse attention** models where only a fraction of KV entries are active. HERALD uses block-level consistency across denoising steps to select top-k entries once and reuse them throughout a block. SAC uses CXL's cache-line granularity to fetch only the required top-k entries on demand. Both papers share the **selective retrieval** approach: identify the relevant subset of KV cache and fetch only that. This is a genuine *departure* from the full-cache-reuse paradigm of Papers 1, 10, and 13, because they *do not* attempt to store or reconstruct the full cache—they accept that most entries are irrelevant and optimize for the sparse subset.\n",
+ "\n",
+ "**Paper 10 (Recency/Frequency Adaptive KV Caching)** and **Paper 13 (UltraQuant)** are the most conventional members of this cluster. Paper 10 applies **LRU-like adaptive caching** to KV blocks, distinguishing between recently and frequently occurring blocks. This is a *cache eviction policy* approach, not a content-aware reuse strategy. Paper 13 applies **4-bit quantization** to the KV cache, using TurboQuant-style rotation and codebook quantization. This is a *compression* approach that reduces memory footprint without changing the fundamental storage model. Both are **incremental improvements** to the existing KV cache paradigm, not departures.\n",
+ "\n",
+ "## Cluster 2: Pipeline-Stage Memory Orchestration (Papers 2, 4)\n",
+ "\n",
+ "**Shared fundamental approach:** These papers manage memory *across pipeline stages* in a distributed system, treating KV cache as a *resource to be balanced* rather than reused.\n",
+ "\n",
+ "**Paper 2 (Concordia)** introduces **persistent-kernel checkpointing** for fault tolerance. The key insight is that KV cache and adapter pages change *sparsely* and can be detected on-GPU at HBM bandwidth. The **persistent executor** (Section 3.1) is a device-resident control loop that scans dirty pages and appends to a recovery log. This is a *systems-level* approach to memory management, not a *content-level* one—it cares about *where* the data is and *whether* it changed, not *what* the data means.\n",
+ "\n",
+ "**Paper 4 (MOCAP)** addresses **memory imbalance** in chunked pipelining on wafer-scale chips. The **Memory-Balanced KV Reallocation (MBKR)** (Section 4.1) uses a *fixed cross-half pairing* strategy where stage i is paired with stage i+N/2. This is a *topological* approach to memory management—it cares about *which stage* holds which KV cache, not *which tokens* are in the cache. This is a **genuine departure** from the content-reuse paradigm of Cluster 1, because it treats KV cache as a *distributed resource* to be balanced across physical devices, not as a *semantic structure* to be exploited for reuse.\n",
+ "\n",
+ "## Cluster 3: Energy-Aware Memory Management (Papers 3, 7, 17)\n",
+ "\n",
+ "**Shared fundamental approach:** These papers treat memory *as a component of energy consumption*, optimizing for energy efficiency rather than throughput or latency.\n",
+ "\n",
+ "**Paper 3 (EnerInfer)** is the most explicit member. It proposes **NPU/DDR frequency scaling** as a control knob for energy efficiency. The key insight is that *modestly lowering frequencies* preserves QoE while improving energy efficiency (Figure 4 shows 62% improvement). This is a *hardware-configuration* approach to memory management—it controls *how fast* the memory operates, not *what* is stored in it.\n",
+ "\n",
+ "**Paper 7 (Language-Energy Divide)** measures **energy per output token** across languages, finding up to 8.3× variation. This is a\n",
+ "\n",
+ "[prompt: 45,960 completion: 1,200 tokens]\n",
+ "\n",
+ "[Benchmarking gaps]\n",
+ "────────────────────────────────────────────────────────────\n",
+ "Of the 20 papers in this research bundle, I will analyze the evaluation benchmarks and metrics that appear most frequently, then identify important real-world performance dimensions that are missing from these evaluations.\n",
+ "\n",
+ "## Most Frequently Appearing Benchmarks and Metrics\n",
+ "\n",
+ "### Benchmarks\n",
+ "\n",
+ "1. **MM-NIAH (Multi-Modal Needle-in-a-Haystack)** - Appears in Paper 1 (Kamera) as a cross-chunk binding benchmark for evaluating KV cache reuse quality. Tests multi-hop reasoning across long contexts.\n",
+ "\n",
+ "2. **Video-MME** - Appears in Paper 1 (Kamera) for evaluating video understanding under KV cache reuse.\n",
+ "\n",
+ "3. **EgoSchema** - Appears in Paper 1 (Kamera) for long-form video understanding.\n",
+ "\n",
+ "4. **MileBench** - Appears in Paper 1 (Kamera) for temporal reasoning across cached video clips.\n",
+ "\n",
+ "5. **DPG-Bench / GenEval** - Appears in Paper 12 (SSD) for evaluating autoregressive image generation quality.\n",
+ "\n",
+ "6. **MATH-500** - Appears in Paper 19 (JetFlow) for mathematical reasoning under speculative decoding.\n",
+ "\n",
+ "7. **Claude Code / Agentic coding workloads** - Appears in Paper 5 (RLM-Cascade) as a real-world production workload for evaluating cost savings.\n",
+ "\n",
+ "### Metrics\n",
+ "\n",
+ "1. **Throughput (tokens/s, req/s)** - The most common metric across nearly all papers. Papers 1, 3, 4, 5, 9, 13, 15, 16, 19 all report throughput improvements.\n",
+ "\n",
+ "2. **Latency (TTFT, TBT, P50/P95/P99)** - Appears in Papers 1, 3, 4, 5, 8, 10, 13, 15, 18, 20. Time-to-first-token (TTFT) is the most frequently cited latency metric.\n",
+ "\n",
+ "3. **Energy efficiency (tokens/J)** - Appears in Papers 3 (EnerInfer), 7 (Language-Energy Divide), and 17 (Quantization-Enabled DR).\n",
+ "\n",
+ "4. **KV cache hit rate** - Appears in Papers 1 (Kamera), 10 (Recency/Frequency Adaptive), and 13 (UltraQuant).\n",
+ "\n",
+ "5. **Accuracy / Quality (pass rate, KL divergence, task accuracy)** - Appears in Papers 1, 5, 7, 9, 11, 14, 19.\n",
+ "\n",
+ "6. **Cost savings (USD, % reduction)** - Appears in Papers 5 (RLM-Cascade) and 17 (Quantization-Enabled DR).\n",
+ "\n",
+ "7. **End-to-end latency reduction** - Appears in Papers 4 (MOCAP), 16 (EfficientRollout), 19 (JetFlow).\n",
+ "\n",
+ "8. **Prediction error (%)** - Appears in Paper 20 (LENS) for latency prediction.\n",
+ "\n",
+ "## Patterns in Evaluation\n",
+ "\n",
+ "The papers cluster around several evaluation themes:\n",
+ "- **KV cache efficiency** (Papers 1, 9, 10, 13, 15) - measured by hit rate, memory savings, throughput at reduced cache\n",
+ "- **Speculative decoding speedup** (Papers 5, 12, 16, 19) - measured by end-to-end latency reduction, draft acceptance rate\n",
+ "- **Energy/cost** (Papers 3, 7, 17) - measured by energy per token, cost per request\n",
+ "- **System throughput** (Papers 4, 15, 18) - measured by requests/sec, pipeline efficiency\n",
+ "- **Quality preservation** (Papers 1, 5, 9, 11, 14) - measured by task accuracy, KL divergence from baseline\n",
+ "\n",
+ "## Missing Real-World Performance Dimensions\n",
+ "\n",
+ "### 1. **Multi-tenant interference and isolation**\n",
+ "No paper evaluates how techniques degrade under concurrent, heterogeneous workloads from different tenants. Production systems serve many users simultaneously with varying context lengths, model versions, and latency requirements. Papers 1, 10, and 18 touch on this but do not systematically measure interference.\n",
+ "\n",
+ "### 2. **Cold-start behavior**\n",
+ "Papers focus on steady-state performance after caches are warm. Real deployments face cold-start penalties when models are loaded, caches are empty, or new users arrive. Paper 13 (UltraQuant) mentions \"cache-pressured late rounds\" but does not quantify cold-start overhead.\n",
+ "\n",
+ "### 3. **Long-tail quality under distribution shift**\n",
+ "Paper 18 (Tail-Aware Scheduling) is the only one that explicitly addresses distribution shift. Most papers assume stationary workloads. Real-world LLM traffic has bursty arrivals, changing query types, and evolving user behavior that can invalidate assumptions.\n",
+ "\n",
+ "### 4. **Hardware heterogeneity and portability**\n",
+ "Papers evaluate on specific hardware (H100, Blackwell, RTX PRO 6000, specific phones/boards). No paper measures how techniques transfer across different GPU generations, memory configurations, or cloud vs. edge deployments. Paper 20 (LENS) addresses this for NPU prediction but only for latency.\n",
+ "\n",
+ "### 5. **End-to-end system reliability under failures**\n",
+ "Paper 2 (Concordia) is the only one addressing fault tolerance. Real production systems experience GPU failures, network partitions, and software crashes. No other paper measures recovery time or availability impact.\n",
+ "\n",
+ "### 6. **Memory bandwidth vs. compute trade-off at scale**\n",
+ "Papers report throughput and latency but rarely measure the memory bandwidth utilization or compute-to-memory ratio that determines real-world scaling. Paper 1 (Kamera) notes \"decode is memory-bandwidth-bound\" but does not quantify this.\n",
+ "\n",
+ "### 7. **User-perceived quality beyond token-level metrics**\n",
+ "Papers use token-level metrics (TTFT, TBT, throughput)\n",
+ "\n",
+ "[prompt: 45,953 completion: 1,200 tokens]\n",
+ "\n",
+ "[Implementation guidance]\n",
+ "────────────────────────────────────────────────────────────\n",
+ "Here is a prioritized, actionable engineering roadmap for building a production LLM inference system from scratch, synthesized from the provided research bundle.\n",
+ "\n",
+ "### Executive Summary\n",
+ "\n",
+ "Building a production-grade LLM inference system requires moving beyond a single \"fast decode\" metric. The research bundle reveals a multi-dimensional optimization space where **cost, latency, quality, and reliability** are in constant tension. The most impactful lessons are not about a single breakthrough, but about architecting a system that can **dynamically trade off** these dimensions based on workload, context, and hardware constraints.\n",
+ "\n",
+ "The roadmap is structured into three phases: **Foundation** (building the core, efficient serving stack), **Optimization** (exploiting workload-specific slack for cost and speed), and **Resilience** (ensuring correctness and fault tolerance in production).\n",
+ "\n",
+ "---\n",
+ "\n",
+ "### Phase 1: Foundation – Build a Correct, Efficient, and Predictable Core\n",
+ "\n",
+ "**Goal:** Establish a baseline serving system that is fast, reproducible, and can handle the fundamental memory and compute bottlenecks. This is the non-negotiable foundation.\n",
+ "\n",
+ "#### Priority 1: Master the KV-Cache Bottleneck with a Memory-First Architecture\n",
+ "\n",
+ "**Key Lesson:** The KV cache is the dominant cost and bottleneck. Its management is the central systems problem, not just the model's. (Papers 1, 4, 10, 13)\n",
+ "\n",
+ "- **Actionable Engineering:**\n",
+ " 1. **Adopt a Paged-Attention-like Architecture (vLLM):** This is the de-facto standard. It solves the memory fragmentation problem of naive KV caching, enabling high throughput and dynamic batching. **Do not build your own from scratch**; integrate vLLM or its core principles.\n",
+ " 2. **Implement a Multi-Tiered Cache:** Don't treat all KV cache as equal. Use a **hierarchy**:\n",
+ " - **L1: GPU HBM (Fast, Scarce):** For the current active context window.\n",
+ " - **L2: Host DRAM (Slower, Abundant):** For offloaded, long-lived context (e.g., from RAG). This is critical for long-context workloads. (Paper 9)\n",
+ " - **L3: CXL/Disaggregated Memory (Future):** For scaling beyond a single node. (Paper 15)\n",
+ " 3. **Use a Recency/Frequency (RF) Adaptive Eviction Policy:** Replace the default LRU. An RF policy (Paper 10) is crucial for mixed workloads (e.g., a few long RAG queries interleaved with many short chat turns). It prevents the long-context queries from being evicted by the short ones, directly improving cache hit rate and TTFT.\n",
+ " 4. **Aggressively Quantize the KV Cache:** This is the single most impactful lever for reducing memory pressure.\n",
+ " - **Start with FP8** (the current safe baseline).\n",
+ " - **Target 4-bit (UltraQuant)** for context-heavy agents (Paper 13). This requires careful engineering: use asymmetric K/V quantization, Walsh-Hadamard rotation to reduce outliers, and block-scale scaling. This can yield **3.47x TTFT reduction** in cache-pressured scenarios.\n",
+ "\n",
+ "#### Priority 2: Ensure Numerical Reproducibility for Mission-Critical Tasks\n",
+ "\n",
+ "**Key Lesson:** FP16 inference is not deterministic across different GPUs. For finance, law, and medicine, this is a showstopper. (Paper 11)\n",
+ "\n",
+ "- **Actionable Engineering:**\n",
+ " 1. **Adopt a \"Hybrid Precision\" Strategy (HEAL):** Do not use a global, slow FP32 pipeline. Instead:\n",
+ " - **Quantize Q, K, V to INT16:** This preserves numerical stability without expanding the KV cache footprint.\n",
+ " - **Use Algebraic Error Compensation:** Execute high-precision matrix multiplications on fast FP16 Tensor Cores by correcting the truncation error.\n",
+ " 2. **Implement a Reproducibility Benchmark (MCR-Bench):** Before deploying to production, validate that your system's outputs are deterministic across your target hardware (e.g., A100 vs. H100). This is a **pre-deployment gate**.\n",
+ "\n",
+ "#### Priority 3: Build a Latency Prediction System (LENS)\n",
+ "\n",
+ "**Key Lesson:** You cannot exhaustively profile every configuration. You need a model to predict latency. (Paper 20)\n",
+ "\n",
+ "- **Actionable Engineering:**\n",
+ " 1. **Profile each \"bucket\" (batch size, sequence length) with just 2 end-to-end measurements.** This captures the non-linear latency behavior caused by compiler optimizations and hardware bucketing.\n",
+ " 2. **Use this predictor for system-level decisions:** It enables you to:\n",
+ " - **Optimize batching:** Dynamically choose the optimal batch size for a given request.\n",
+ " - **Tune parallelism:** Decide on the right model parallelism (e.g., tensor vs. pipeline) for a given workload.\n",
+ " - **Schedule requests:** Use predicted latency for better load balancing.\n",
+ "\n",
+ "---\n",
+ "\n",
+ "### Phase 2: Optimization – Exploit Workload-Specific Slack for Cost and Speed\n",
+ "\n",
+ "**Goal:** Move beyond \"max throughput\" to a system that dynamically trades off performance for cost and energy efficiency based on the *user's actual needs*.\n",
+ "\n",
+ "#### Priority 4: Implement a \"Complexity Router\" for Cost-Efficient Serving\n",
+ "\n",
+ "**Key Lesson:** The most expensive model (e.g., Opus) is not needed for most requests. A simple, fast model is often sufficient. (Paper 5)\n",
+ "\n",
+ "- **Actionable Engineering:**\n",
+ " 1. **Build a Rule-Based Router (RLM-Cascade):** This is the most practical starting point. Classify requests in O(1) time:\n",
+ " - **Simple:** \"what is\", \"summarize\", \"hello\n",
+ "\n",
+ "[prompt: 45,960 completion: 1,200 tokens]\n"
+ ]
+ }
+ ],
+ "source": [
+ "DEEP_DIVE_QUESTIONS = [\n",
+ " (\n",
+ " \"Methodology comparison\",\n",
+ " \"Compare the memory management strategies used across the papers. \"\n",
+ " \"Which papers share the same fundamental approach, and which ones represent genuine departures? \"\n",
+ " \"Cite specific paper numbers.\",\n",
+ " ),\n",
+ " (\n",
+ " \"Benchmarking gaps\",\n",
+ " \"Which evaluation benchmarks and metrics appear most often across these papers? \"\n",
+ " \"What important real-world performance dimensions are missing from the evaluations?\",\n",
+ " ),\n",
+ " (\n",
+ " \"Implementation guidance\",\n",
+ " \"A small team wants to build a production LLM inference system from scratch. \"\n",
+ " \"Synthesize the most actionable engineering lessons from this bundle into a prioritized roadmap.\",\n",
+ " ),\n",
+ "]\n",
+ "\n",
+ "for label, question in DEEP_DIVE_QUESTIONS:\n",
+ " print(f\"\\n[{label}]\")\n",
+ " print(\"─\" * 60)\n",
+ " resp = client.chat.completions.create(\n",
+ " model=MODEL,\n",
+ " messages=[\n",
+ " {\n",
+ " \"role\": \"system\",\n",
+ " \"content\": \"Reference specific papers by number and title. Be analytical and concrete.\",\n",
+ " },\n",
+ " {\n",
+ " \"role\": \"user\",\n",
+ " \"content\": f\"Research bundle:\\n\\n{research_bundle}\\n\\n---\\n\\nQuestion: {question}\",\n",
+ " },\n",
+ " ],\n",
+ " max_tokens=1200,\n",
+ " temperature=0.2,\n",
+ " )\n",
+ " print(resp.choices[0].message.content)\n",
+ " print(\n",
+ " f\"\\n[prompt: {resp.usage.prompt_tokens:,} completion: {resp.usage.completion_tokens:,} tokens]\"\n",
+ " )"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "19",
+ "metadata": {},
+ "source": [
+ "## Step 6 — Non-Think vs Think-High\n",
+ "\n",
+ "Complex cross-paper tradeoff questions are where Think-High mode is most useful. This step poses a question that requires weighing conflicting evidence across multiple papers.\n",
+ "\n",
+ "| Mode | Triggered by | When to use |\n",
+ "|---|---|---|\n",
+ "| Non-Think | Default (no `extra_body`) | Summaries, factual retrieval |\n",
+ "| Think-High | `chat_template_kwargs={\"thinking\": True}` in `extra_body` | Conflicting evidence, hard tradeoffs |\n",
+ "| Think-Max | `chat_template_kwargs={\"thinking\": True, \"reasoning_effort\": \"max\"}` in `extra_body` ([see model card](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash)) | Frontier synthesis |\n",
+ "\n",
+ "> **Note:** Reasoning content is returned in `choices[0].message.reasoning_content`; if that field is absent, check `choices[0].message.model_extra` (field name varies by SGLang version)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "20",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "HARD_QUESTION = (\n",
+ " \"Speculative decoding and continuous batching are both presented as solutions to LLM inference latency. \"\n",
+ " \"Based on the papers in this bundle, under what conditions does each approach win? \"\n",
+ " \"Are they complementary or in tension? \"\n",
+ " \"If you had to pick one for a production deployment serving mixed workloads (short and long outputs, \"\n",
+ " \"bursty traffic), which would you recommend and why?\"\n",
+ ")\n",
+ "\n",
+ "base_message = [\n",
+ " {\n",
+ " \"role\": \"user\",\n",
+ " \"content\": f\"Research bundle:\\n\\n{research_bundle}\\n\\n---\\n\\nQuestion: {HARD_QUESTION}\",\n",
+ " }\n",
+ "]\n",
+ "\n",
+ "resp_nothink = client.chat.completions.create(\n",
+ " model=MODEL,\n",
+ " messages=base_message,\n",
+ " max_tokens=1500,\n",
+ " temperature=0.2,\n",
+ ")\n",
+ "\n",
+ "resp_think = client.chat.completions.create(\n",
+ " model=MODEL,\n",
+ " messages=base_message,\n",
+ " max_tokens=4000,\n",
+ " temperature=0.6,\n",
+ " extra_body={\"chat_template_kwargs\": {\"thinking\": True}},\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "21",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "NON-THINK\n",
+ "────────────────────────────────────────────────────────────\n",
+ "Based on the papers in this bundle, here's my analysis of speculative decoding vs. continuous batching for LLM inference latency, and my recommendation for production deployment.\n",
+ "\n",
+ "## When Each Approach Wins\n",
+ "\n",
+ "### Speculative Decoding (Papers 5, 12, 16, 19)\n",
+ "**Wins when:**\n",
+ "- **Draft-verify cost asymmetry is large** — The draft model is significantly cheaper/faster than the verify model (Paper 5: 45.8% cost reduction, 1.83× speedup)\n",
+ "- **Workload has exploitable structure** — Many requests are simple enough for a small draft model (Paper 5: 64-70% SKIPPED path)\n",
+ "- **Output quality is the priority** — Speculative decoding preserves the verify model's distribution (Paper 5: 100% vs 95% pass rate)\n",
+ "- **Latency is secondary to cost** — Accepts TTFT regression (2.1× slower) in exchange for lower end-to-end latency and cost (Paper 5, §6.2)\n",
+ "- **Draft budget can be large** — JetFlow (Paper 19) shows up to 9.64× speedup with parallel tree drafting when acceptance remains high\n",
+ "\n",
+ "**Fails when:**\n",
+ "- Draft and verify models are from different providers with no shared vocabulary (Paper 5's key limitation)\n",
+ "- Draft quality degrades under evolving policies (Paper 16: RL rollouts)\n",
+ "- The workload is dominated by complex, multi-hop reasoning (Paper 1's cross-chunk binding)\n",
+ "\n",
+ "### Continuous Batching (Papers 5, 18)\n",
+ "**Wins when:**\n",
+ "- **Throughput is the primary metric** — Maximizes GPU utilization by batching multiple requests\n",
+ "- **Workload is homogeneous** — Similar-length requests benefit from predictable scheduling\n",
+ "- **Latency variance is acceptable** — Mean-centric metrics improve, but tail latency may suffer\n",
+ "- **Memory pressure is manageable** — KV cache fits within GPU memory\n",
+ "\n",
+ "**Fails when:**\n",
+ "- **Workload has extreme length variability** — Paper 18 shows SRPT with perfect knowledge still has P99 TTLT 35-50% worse than tail-aware scheduling\n",
+ "- **Bursty arrivals** — Continuous batching can't handle sudden spikes without preemption\n",
+ "- **Memory is the bottleneck** — Paper 1 shows KV cache becomes the binding constraint, not compute\n",
+ "\n",
+ "## Are They Complementary or in Tension?\n",
+ "\n",
+ "**They are complementary, not in tension.** \n",
+ "\n",
+ "Speculative decoding operates at the *model level* (draft-verify), while continuous batching operates at the *system level* (request scheduling). They address different bottlenecks:\n",
+ "\n",
+ "- **Speculative decoding** reduces per-request latency by exploiting model asymmetry\n",
+ "- **Continuous batching** improves throughput by exploiting request-level parallelism\n",
+ "\n",
+ "Paper 5 (RLM-Cascade) explicitly shows they can be combined: \"These operate at the model layer and are orthogonal to—and composable with—RLM-Cascade's application-layer response composition\" (§5.3).\n",
+ "\n",
+ "The tension is only in resource allocation: both consume GPU compute, but speculative decoding's draft-verify pipeline adds sequential latency that continuous batching's parallelism can't mask.\n",
+ "\n",
+ "## Recommendation for Production Deployment\n",
+ "\n",
+ "**For a production deployment serving mixed workloads (short and long outputs, bursty traffic), I recommend: Continuous batching with tail-aware scheduling, not speculative decoding.**\n",
+ "\n",
+ "### Why:\n",
+ "\n",
+ "1. **Bursty traffic is the killer** — Paper 18 shows that even with perfect decode-length knowledge, SRPT fails under bursty arrivals. The tail-aware scheduling framework reduces P99 TTLT by 35-50% without requiring prediction.\n",
+ "\n",
+ "2. **Length variability is extreme** — LLM serving exhibits \"extreme length variability\" (Paper 18). Continuous batching with tail-aware scheduling handles this naturally; speculative decoding's draft-verify pipeline breaks when draft quality varies.\n",
+ "\n",
+ "3. **Memory is the bottleneck, not compute** — Paper 1 shows that for multimodal agents, \"Memory, not the nominal window, is the operative bound.\" Continuous batching with KV cache management (Paper 10's adaptive caching) addresses this directly.\n",
+ "\n",
+ "4. **Speculative decoding's TTFT regression is unacceptable** — Paper 5 reports 2.1× slower TTFT. For interactive workloads, this is a deal-breaker. The paper itself acknowledges this as a \"Pareto trade-off\" (§6.2).\n",
+ "\n",
+ "5. **Continuous batching + tail-aware scheduling is proven** — Paper 18 achieves 34-47% TTFT reduction across reasoning-heavy and chat-heavy workloads. This is robust to distribution shifts.\n",
+ "\n",
+ "### The Hybrid Approach\n",
+ "\n",
+ "If you must use both, use **speculative decoding only for the simple, short-output requests** (the 64-70% SKIPPED path in Paper 5) and **continuous batching for the complex, long-output requests**. This is exactly what Paper 5's router does: \"Tool-selection turns are identified by a non-empty tools array and forwarded directly to claude-opus-4-8 with no draft stage\" (§3.5).\n",
+ "\n",
+ "### Practical Deployment\n",
+ "\n",
+ "For a production system:\n",
+ "1. **Primary**: Continuous batching with tail-aware scheduling (Paper 18)\n",
+ "2. **Secondary**: Speculative decoding for simple requests (Paper 5's router)\n",
+ "3. **Fallback**: Direct Opus for complex, schema-critical turns (Paper 5's tool-call carve-out)\n",
+ "\n",
+ "This gives you the throughput of continuous batching with the cost savings of speculative decoding where it works, without the TTFT regression where it doesn't.\n",
+ "\n",
+ "\n",
+ "THINK-HIGH\n",
+ "────────────────────────────────────────────────────────────\n",
+ "[reasoning — 736 words]\n",
+ "\n",
+ "Okay, this is a complex question about comparing speculative decoding and continuous batching for LLM inference. I need to analyze the papers in the bundle to understand their strengths, weaknesses, and how they relate. The user wants to know under what conditions each wins, if they're complementary or in tension, and which to recommend for a production deployment with mixed workloads.\n",
+ "\n",
+ "First, I should recall what each technique is. Speculative decoding uses a small draft model to generate tokens quickly, which a large model verifies in parallel. This reduces latency by making fewer serial passes through the large model. Continuous batching is about processing multiple requests together in a batch, dynamically adding and removing requests as they finish, to improve throughput and GPU utilization.\n",
+ "\n",
+ "Looking at the papers, Paper 5 (RLM-Cascade) is about response-level speculative decoding for API cost reduction. Paper 18 (Beyond Prediction) is about tail-aware scheduling, which relates to batching. Paper 19 (JetFlow) is about improving speculative decoding with parallel tree drafting. Paper 16 (EfficientRollout) is about self-speculative decoding for RL rollouts. There's also Paper 1 (Kamera) about KV cache reuse, which is related to batching efficiency. Paper 10 (Recency/Frequency) about KV caching strategies.\n",
+ "\n",
+ "The key insight is that these two approaches operate at different levels. Speculative decoding reduces the number of serial steps per request by having a drafter predict multiple tokens that get verified. Continuous batching increases throughput by packing multiple requests into a single batch, but each request still goes through its own decoding steps.\n",
+ "\n",
+ "Are they complementary? Yes, they can be. Speculative decoding reduces the effective number of decoding steps per token, which means each request finishes faster. Continuous batching increases the number of requests processed per unit time. They address different bottlenecks: speculative decoding targets the memory-bound decode phase where each step is slow, while continuous batching targets the compute-bound prefill phase where parallelism helps.\n",
+ "\n",
+ "But there's a tension. Speculative decoding works best when the draft model is accurate and the acceptance rate is high. If the draft is poor, you waste compute on verification. Continuous batching works best when there are many requests to batch together. Under bursty traffic, batching helps by filling the GPU, but speculative decoding might be less effective if the draft model can't keep up with the diversity of requests.\n",
+ "\n",
+ "For production with mixed workloads (short and long outputs, bursty traffic), I need to think about which is more robust. Continuous batching is well-established and works across all workloads. Speculative decoding requires a good draft model and can have variable speedups. The papers suggest that speculative decoding can achieve significant speedups (like 9.64x in Paper 19), but that's under ideal conditions. The user's question about \"under what conditions does each approach win\" suggests I need to identify the regimes.\n",
+ "\n",
+ "Looking at Paper 5, RLM-Cascade shows that for simple requests, the draft model can be used directly (SKIPPED path) and that's the majority. For complex requests, the draft-verify pipeline adds latency. So speculative decoding wins when the draft is accurate and the verify overhead is low. Continuous batching wins when there are many requests to batch, which is the case under high load.\n",
+ "\n",
+ "I think the answer is that they are complementary. Speculative decoding reduces per-request latency, continuous batching increases throughput. For a deployment with mixed workloads, I'd recommend continuous batching as the primary mechanism because it's more robust, and then layer speculative decoding on top for the long-output requests where it can help. But the user asks \"if you had to pick one\" - that's a tough choice. I think continuous batching is more fundamental and works across all workloads, while speculative decoding is an optimization that may not always apply. For bursty traffic, continuous batching handles the load better by keeping the GPU busy. For short outputs, speculative decoding might not help much because the verification overhead could outweigh the gain. So for mixed workloads, continuous batching is the safer bet.\n",
+ "\n",
+ "But I need to support this with evidence from the papers. Paper 18 shows that continuous batching with proper scheduling (tail-aware) can reduce P99 latency by 35-50%. That's significant. Paper 19 shows speculative decoding can achieve high speedups but under specific conditions. Paper 16 shows that for RL rollouts, which are long, speculative decoding helps but needs system-aware tuning.\n",
+ "\n",
+ "I'll structure my answer: first explain each approach, then analyze conditions where each wins, discuss complementarity/tension, and finally give a recommendation with reasoning.\n",
+ "\n",
+ "[answer]\n",
+ "\n",
+ "# Speculative Decoding vs. Continuous Batching: Analysis for Production LLM Serving\n",
+ "\n",
+ "Based on the papers in this bundle, I'll analyze the tradeoffs between these two latency-reduction techniques and provide a recommendation for mixed workloads.\n",
+ "\n",
+ "## What Each Approach Does\n",
+ "\n",
+ "**Speculative Decoding** (Papers 5, 16, 19, 12) uses a fast draft model to generate token candidates that a larger verify model accepts in parallel. This reduces the number of serial autoregressive steps. Key variants:\n",
+ "- **Response-level** (Paper 5, RLM-Cascade): Draft entire response, verify with a single API call\n",
+ "- **Self-speculative** (Paper 16, EfficientRollout): Draft from the target model itself (quantized)\n",
+ "- **Tree drafting** (Paper 19, JetFlow): Generate multiple candidate paths for higher acceptance\n",
+ "\n",
+ "**Continuous Batching** (implicit in Papers 18, 10, 15) processes multiple requests simultaneously by dynamically adding/removing sequences from a batch as they complete decode steps. This improves GPU utilization by keeping compute units busy during memory-bound phases.\n",
+ "\n",
+ "## Conditions Where Each Approach Wins\n",
+ "\n",
+ "### Speculative Decoding Wins When:\n",
+ "1. **Draft model is accurate** → high acceptance rate (Paper 5: 88.8% draft-use rate on simple agentic turns)\n",
+ "2. **Outputs are long** → more tokens to speculate over (Paper 19: up to 9.64× speedup on MATH-500)\n",
+ "3. **Draft cost is low** relative to verify cost (Paper 5: DeepSeek costs ~2% of Opus)\n",
+ "4. **Workload is structured** → router can classify simple vs. complex (Paper 5: SKIPPED path dominates at 64-70%)\n",
+ "5. **Latency is acceptable** for the verify path (Paper 5: 2.1× TTFT regression on complex turns)\n",
+ "\n",
+ "**Key insight from Paper 5**: The SKIPPED path actually *replaces* the expensive model for most requests, making the system *faster* overall despite adding a verify stage for complex turns. This counter-intuitive result holds because simple requests dominate.\n",
+ "\n",
+ "### Continuous Batching Wins When:\n",
+ "1. **High concurrency** → many requests to fill the batch (Paper 18: tail-aware scheduling)\n",
+ "2. **Outputs are short** → batching overhead is small relative to per-request gain\n",
+ "3. **Memory pressure is high** → KV cache management matters (Papers 10, 15)\n",
+ "4. **Workload is homogeneous** → predictable decode lengths (Paper 18: SRPT with perfect knowledge)\n",
+ "5. **GPU compute is underutilized** → batching fills idle cycles\n",
+ "\n",
+ "**Key insight from Paper 18**: Prediction-driven policies (like speculative decoding's draft/verify) are *fragile under distribution shifts*—bursty arrivals and memory pressure degrade tail latency. Continuous batching with proper preemption handles this more robustly.\n",
+ "\n",
+ "## Are They Complementary or in Tension?\n",
+ "\n",
+ "**They are complementary**, not in tension. They operate at different levels:\n",
+ "\n",
+ "| Dimension | Speculative Decoding | Continuous Batching |\n",
+ "|-----------|---------------------|---------------------|\n",
+ "| **What it reduces** | Number of serial decode steps per request | Idle GPU time between requests |\n",
+ "| **Bottleneck** | Memory bandwidth (single request) | Compute utilization (many requests) |\n",
+ "| **When applied** | Per-token generation | Request scheduling |\n",
+ "| **Dependency** | Needs accurate draft model | Needs batchable workload |\n",
+ "\n",
+ "Speculative decoding reduces *per-request latency*; continuous batching increases *system throughput*. They can be composed: use speculative decoding to reduce each request's decode steps, then batch those shorter requests together.\n",
+ "\n",
+ "**Tension arises** only if speculative decoding makes outputs *too short* to batch effectively (e.g., Paper 5's SKIPPED path completes in 800-1200ms, which is fast but may leave GPU idle between batches). This is a scheduling optimization, not a fundamental conflict.\n",
+ "\n",
+ "## Recommendation for Production Deployment: Continuous Batching (with caveats)\n",
+ "\n",
+ "For a **mixed workload** (short/long outputs, bursty traffic), I recommend **continuous batching as the primary mechanism**, with speculative decoding as an optional accelerator for long-output requests.\n",
+ "\n",
+ "### Why Continuous Batching Wins for Mixed Workloads\n",
+ "\n",
+ "1. **Robustness to distribution shifts** (Paper 18): Continuous batching with proper scheduling (tail-aware, cache-aware preemption) handles bursty arrivals and memory pressure *without* requiring a draft model that may be mismatched. Speculative decoding's draft quality degrades under distribution shift (Paper 16: \"evolving policy makes any fixed drafter increasingly mismatched\").\n",
+ "\n",
+ "2. **No accuracy risk**: Continuous batching is lossless—it changes only scheduling, not model output. Speculative decoding introduces quality risk (Paper 5: 100% vs 95% on some benchmarks, but the ENHANCED path can *increase* cost on mteb-retrieve).\n",
+ "\n",
+ "3. **Handles short outputs**: Speculative decoding's benefit on short outputs is minimal (Paper 5: 64-70% of requests are simple, but the SKIPPED path's speedup comes from *avoiding* the verify model, not from speculation itself). For short outputs, batching is more impactful.\n",
+ "\n",
+ "4. **Memory efficiency**: Continuous batching with KV cache management (Papers 10, 15) directly addresses the memory bottleneck that limits throughput. Speculative decoding's draft models add memory pressure.\n",
+ "\n",
+ "### When to Add Speculative Decoding\n",
+ "\n",
+ "Use speculative decoding **only for long-output requests** (Paper 5's \"complex\" classification, Paper 19's long-context tasks). This requires:\n",
+ "- A lightweight complexity router (Paper 5's keyword-based approach)\n",
+ "- A fallback mechanism for when the draft is wrong (Paper 5's ENHANCED path)\n",
+ "- Monitoring for cost inversion (Paper 5's mteb-retrieve case)\n",
+ "\n",
+ "### Practical Deployment Strategy\n",
+ "\n",
+ "```\n",
+ "Primary: Continuous batching (vLLM-style)\n",
+ " + Tail-aware scheduling (Paper 18)\n",
+ " + KV cache management (Papers 10, 15)\n",
+ " \n",
+ "Optional: Speculative decoding for long outputs\n",
+ " + Complexity router (Paper 5)\n",
+ " + Self-speculative draft (Paper 16) — no separate model\n",
+ " + Fallback to direct generation when draft quality drops\n",
+ "```\n",
+ "\n",
+ "This hybrid approach gives you the robustness of batching for bursty traffic and the latency reduction of speculation for long outputs, without the fragility of either alone.\n",
+ "\n",
+ "**Final answer**: Continuous batching for robustness, speculative decoding as an accelerator for long-output tails.\n",
+ "\n",
+ "TOKEN SUMMARY\n",
+ " Non-think completion tokens : 1,156\n",
+ " Think-High completion tokens : 2,337\n",
+ " ├─ reasoning block (~words): 736\n",
+ " └─ final answer (~words) : 876\n",
+ " Extra tokens spent thinking : +1,181\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(\"NON-THINK\")\n",
+ "print(\"─\" * 60)\n",
+ "print(resp_nothink.choices[0].message.content)\n",
+ "\n",
+ "think_msg = resp_think.choices[0].message\n",
+ "reasoning = (\n",
+ " getattr(think_msg, \"reasoning_content\", None)\n",
+ " or (think_msg.model_extra or {}).get(\"reasoning_content\")\n",
+ " or (think_msg.model_extra or {}).get(\"reasoning\")\n",
+ ")\n",
+ "\n",
+ "print(\"\\n\\nTHINK-HIGH\")\n",
+ "print(\"─\" * 60)\n",
+ "if reasoning:\n",
+ " print(f\"[reasoning — {len(reasoning.split()):,} words]\\n\")\n",
+ " print(reasoning)\n",
+ " print(\"\\n[answer]\\n\")\n",
+ "print(think_msg.content)\n",
+ "\n",
+ "reasoning_words = len(reasoning.split()) if reasoning else 0\n",
+ "answer_words = len((think_msg.content or \"\").split())\n",
+ "\n",
+ "print(f\"\\nTOKEN SUMMARY\")\n",
+ "print(f\" Non-think completion tokens : {resp_nothink.usage.completion_tokens:>6,}\")\n",
+ "print(f\" Think-High completion tokens : {resp_think.usage.completion_tokens:>6,}\")\n",
+ "print(f\" ├─ reasoning block (~words): {reasoning_words:>6,}\")\n",
+ "print(f\" └─ final answer (~words) : {answer_words:>6,}\")\n",
+ "print(\n",
+ " f\" Extra tokens spent thinking : {resp_think.usage.completion_tokens - resp_nothink.usage.completion_tokens:>+6,}\"\n",
+ ")"
+ ]
+ }
+ ],
+ "metadata": {
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}