{ "hf_id": "poolside/Laguna-S-2.1", "meta": { "title": "Laguna S-2.1", "slug": "laguna-s-2.1", "provider": "Poolside", "description": "Poolside's 118B total / 8B activated MoE coding model with mixed sliding-window + global attention, native interleaved reasoning, and 256K context — the larger sibling of Laguna XS-2.1, tuned for agentic coding.", "date_added": "2026-07-21", "date_updated": "2026-07-22", "tasks": [ "text" ], "performance_headline": "118B/8B-A MoE for agentic coding with interleaved thinking and tool use", "related_recipes": [ "poolside/Laguna-XS-2.1", "poolside/Laguna-M.1" ], "hardware": { "h200": "verified", "mi325x": "verified" } }, "recommended_command": { "hardware": "h200", "strategy": "single_node_tp", "variant": "default", "node_count": 1, "deploy_type": "single_node", "env": {}, "docker_image": "vllm/vllm-openai:latest", "command": "vllm serve poolside/Laguna-S-2.1 \\\n --trust-remote-code \\\n --tensor-parallel-size 8 \\\n --enable-auto-tool-choice \\\n --tool-call-parser poolside_v1 \\\n --reasoning-parser poolside_v1", "argv": [ "vllm", "serve", "poolside/Laguna-S-2.1", "--trust-remote-code", "--tensor-parallel-size", "8", "--enable-auto-tool-choice", "--tool-call-parser", "poolside_v1", "--reasoning-parser", "poolside_v1" ], "docker_command": "docker run --gpus all \\\n --privileged --ipc=host -p 8000:8000 \\\n -v ~/.cache/huggingface:/root/.cache/huggingface \\\n vllm/vllm-openai:latest poolside/Laguna-S-2.1 \\\n --trust-remote-code \\\n --tensor-parallel-size 8 \\\n --enable-auto-tool-choice \\\n --tool-call-parser poolside_v1 \\\n --reasoning-parser poolside_v1", "docker_argv": [ "docker", "run", "--gpus", "all", "--privileged", "--ipc=host", "-p", "8000:8000", "-v", "~/.cache/huggingface:/root/.cache/huggingface", "vllm/vllm-openai:latest", "poolside/Laguna-S-2.1", "--trust-remote-code", "--tensor-parallel-size", "8", "--enable-auto-tool-choice", "--tool-call-parser", "poolside_v1", "--reasoning-parser", "poolside_v1" ], "strategy_spec": { "name": "single_node_tp", "deploy_type": "single_node", "display_name": "Tensor Parallel", "short_label": "TP", "orientation": "latency", "description": "Single-node tensor parallel. Splits the model across all local GPUs. TP size is set to the GPU count at deploy time. The simplest multi-GPU strategy — works for all model architectures.\n", "hardware_match": { "min_gpus": 1, "max_gpus": 8, "multi_node": false }, "vllm_args": [], "parallel_flag": "--tensor-parallel-size" }, "hardware_profile": { "brand": "NVIDIA", "generation": "hopper", "compute_arch": "sm90", "display_name": "H200", "description": "NVIDIA H200 SXM 141 GB HBM3e · 8-GPU HGX node", "gpu_count": 8, "vram_gb": 1128, "multi_node": false }, "alternatives": { "single_node_tep": "/poolside/Laguna-S-2.1/strategies/single_node_tep.json", "single_node_dep": "/poolside/Laguna-S-2.1/strategies/single_node_dep.json", "kv_store_centralized_mooncake": "/poolside/Laguna-S-2.1/strategies/kv_store_centralized_mooncake.json", "kv_store_distributed_mooncake": "/poolside/Laguna-S-2.1/strategies/kv_store_distributed_mooncake.json" }, "by_hardware": { "h200": "/poolside/Laguna-S-2.1/hw/h200.json", "h100": "/poolside/Laguna-S-2.1/hw/h100.json", "b200": "/poolside/Laguna-S-2.1/hw/b200.json", "gb200": "/poolside/Laguna-S-2.1/hw/gb200.json", "b300": "/poolside/Laguna-S-2.1/hw/b300.json", "gb300": "/poolside/Laguna-S-2.1/hw/gb300.json", "mi300x": "/poolside/Laguna-S-2.1/hw/mi300x.json", "mi325x": "/poolside/Laguna-S-2.1/hw/mi325x.json", "mi350x": "/poolside/Laguna-S-2.1/hw/mi350x.json", "mi355x": "/poolside/Laguna-S-2.1/hw/mi355x.json" } }, "model": { "model_id": "poolside/Laguna-S-2.1", "min_vllm_version": "0.25.0", "architecture": "moe", "parameter_count": "118B", "active_parameters": "8B", "context_length": 262144, "base_args": [ "--trust-remote-code" ], "base_env": {}, "install": { "pip": { "command": "uv venv\nsource .venv/bin/activate\nuv pip install -U vllm --torch-backend auto" }, "docker": { "command": "docker pull vllm/vllm-openai:latest" } } }, "features": { "tool_calling": { "description": "Enable automatic tool choice with Poolside's tool-call parser", "args": [ "--enable-auto-tool-choice", "--tool-call-parser", "poolside_v1" ] }, "reasoning": { "description": "Enable interleaved thinking with Poolside's reasoning parser", "args": [ "--reasoning-parser", "poolside_v1" ] }, "spec_decoding": { "description": "DFlash speculative decoding with the Laguna-S-2.1 draft model (15 tokens, greedy)", "args": [ "--speculative-config", "{\"model\":\"poolside/Laguna-S-2.1-DFlash\",\"num_speculative_tokens\":15,\"method\":\"dflash\"}", "--moe-backend", "triton" ] } }, "opt_in_features": [ "spec_decoding" ], "variants": { "default": { "precision": "bf16", "vram_minimum_gb": 282, "description": "BF16 weights (~235GB) — needs a multi-GPU node (≥2× H200/B200, or a full HGX node)", "hardware_overrides": { "mi325x": { "extra_env": { "VLLM_ROCM_USE_AITER": "1", "VLLM_ROCM_USE_AITER_FUSION_SHARED_EXPERTS": "1", "VLLM_ROCM_QUICK_REDUCE_QUANTIZATION": "INT4" } } } }, "fp8": { "model_id": "poolside/Laguna-S-2.1-FP8", "precision": "fp8", "vram_minimum_gb": 145, "description": "Block-FP8 weights + FP8 KV cache (~121GB) — a hair over one 141GB H200, so TP2 (or a single 268GB B300)", "extra_env": { "VLLM_BLOCKSCALE_FP8_GEMM_FLASHINFER": "0" }, "hardware_overrides": { "mi325x": { "extra_env": { "VLLM_ROCM_USE_AITER": "1", "VLLM_ROCM_USE_AITER_MOE": "0", "VLLM_ROCM_USE_AITER_FUSION_SHARED_EXPERTS": "1", "VLLM_ROCM_QUICK_REDUCE_QUANTIZATION": "INT4" } } }, "json": "/poolside/Laguna-S-2.1-FP8.json" }, "nvfp4": { "model_id": "poolside/Laguna-S-2.1-NVFP4", "precision": "nvfp4", "vram_minimum_gb": 86, "description": "NVFP4 weights + FP8 KV cache (~72GB, Blackwell only) — fits a single B200/B300", "json": "/poolside/Laguna-S-2.1-NVFP4.json" }, "int4": { "model_id": "poolside/Laguna-S-2.1-INT4", "precision": "int4", "vram_minimum_gb": 86, "description": "INT4 (W4A16) weights + FP8 KV cache (~72GB) — fits a single 96GB+ GPU (H200/B200)", "json": "/poolside/Laguna-S-2.1-INT4.json" } }, "hardware_overrides": {}, "guide": "## Overview\n\n[Laguna S-2.1](https://huggingface.co/poolside/Laguna-S-2.1) is Poolside's\n118B-total / 8B-activated Mixture-of-Experts model — the larger sibling of\n[Laguna XS-2.1](https://huggingface.co/poolside/Laguna-XS-2.1), built for\nagentic coding and long-horizon work. It shares the `laguna` architecture:\nmixed sliding-window + global attention (3:1 across 48 layers) with softplus\nper-head gating and an FP8 KV cache, plus native interleaved reasoning and\ntool calling.\n\n### Key features\n- **Mixed SWA + global attention**: 36 sliding-window layers (window=512)\n interleaved with 12 global-attention layers (3:1), each with per-layer\n rotary scaling.\n- **256 experts + 1 shared expert** with top-10 routing.\n- **Grouped-query attention**: 8 KV heads, head dim 128, per-head softplus\n output gating.\n- **Native FP8 KV cache** to reduce memory per token.\n- **Interleaved reasoning**: thinking blocks emitted between tool calls;\n toggled per-request via `enable_thinking`.\n- **Tool calling**: Poolside's XML-style tool-call protocol, parsed via\n `poolside_v1`.\n\nSame architecture as XS-2.1, so vLLM needs no S-specific code — support\nlands with the shared `laguna` implementation.\n\n## Prerequisites\n\n### pip\n```bash\nuv pip install -U 'vllm>=0.25.0'\n```\n\n### Docker\n```bash\ndocker pull vllm/vllm-openai:latest\n```\n\n## Variants and VRAM\n\nLaguna S-2.1 is large: the BF16 weights are ~235GB, so unlike XS-2.1 the\ndefault **does not fit a single GPU** — plan for a multi-GPU node or pick a\nquantized checkpoint. Select one with the **Variant** control above:\n\n| Variant | Checkpoint | Weights | ~Size | Fits on |\n|---------|-----------|---------|-------|---------|\n| BF16 | [Laguna-S-2.1](https://huggingface.co/poolside/Laguna-S-2.1) | BF16 | 235 GB | ≥2× H200/B200, or a full HGX node |\n| FP8 | [Laguna-S-2.1-FP8](https://huggingface.co/poolside/Laguna-S-2.1-FP8) | Block-FP8 | 121 GB | TP2 on H200, or one B300; set `VLLM_BLOCKSCALE_FP8_GEMM_FLASHINFER=0` |\n| NVFP4 | [Laguna-S-2.1-NVFP4](https://huggingface.co/poolside/Laguna-S-2.1-NVFP4) | NVFP4 | 72 GB | single B200/B300 (Blackwell only) |\n| INT4 | [Laguna-S-2.1-INT4](https://huggingface.co/poolside/Laguna-S-2.1-INT4) | INT4 (W4A16) | 72 GB | single H200/B200 |\n\nQuantization is detected automatically from each checkpoint's\n`quantization_config`, so the launch command is identical — just swap the\nmodel ID. All three quantized checkpoints ship an **FP8-quantized KV cache**.\n\nPrecision-matched DFlash speculators ship for each quantization —\n[DFlash-FP8](https://huggingface.co/poolside/Laguna-S-2.1-DFlash-FP8),\n[DFlash-NVFP4](https://huggingface.co/poolside/Laguna-S-2.1-DFlash-NVFP4),\n[DFlash-INT4](https://huggingface.co/poolside/Laguna-S-2.1-DFlash-INT4) — to\npair speculative decoding with a quantized base at matching precision.\n\n> **Context length.** The BF16 checkpoint supports up to 1,048,576 tokens;\n> the quantized checkpoints are configured for 256K. The commands below use\n> `--max-model-len 262144`; raise or lower it to trade context for KV memory.\n\n## Launch command\n\n### Multi-GPU node (H200/B200, BF16)\n```bash\nvllm serve poolside/Laguna-S-2.1 \\\n --trust-remote-code \\\n --tensor-parallel-size 8 \\\n --max-model-len 262144 \\\n --enable-auto-tool-choice \\\n --tool-call-parser poolside_v1 \\\n --reasoning-parser poolside_v1\n```\n\n### AMD ROCm — 8× MI325X\n\nFor FP8, the MI325X override disables AITER MoE because its blockscale kernel\ncurrently corrupts logits; other AITER operators remain enabled, while vLLM\nuses Triton MoE.\n\n### Single GPU (INT4 on H200, or NVFP4 on B200)\n```bash\nvllm serve poolside/Laguna-S-2.1-INT4 \\\n --trust-remote-code \\\n --max-model-len 262144 \\\n --enable-auto-tool-choice \\\n --tool-call-parser poolside_v1 \\\n --reasoning-parser poolside_v1\n```\n\n## Controlling reasoning\n\nReasoning is **off by default** in the chat template. Enable it per-request:\n\n```python\nfrom openai import OpenAI\nclient = OpenAI(base_url=\"http://localhost:8000/v1\", api_key=\"EMPTY\")\n\nresp = client.chat.completions.create(\n model=\"poolside/Laguna-S-2.1\",\n messages=[{\"role\": \"user\", \"content\": \"Write a Python retry wrapper with exponential backoff.\"}],\n extra_body={\"chat_template_kwargs\": {\"enable_thinking\": True}},\n temperature=0.7,\n top_p=1.0,\n extra_query={\"top_k\": 20},\n)\nprint(resp.choices[0].message.reasoning)\nprint(resp.choices[0].message.content)\n```\n\nOr default-on with `--default-chat-template-kwargs '{\"enable_thinking\": true}'`.\n\nThe model's `generation_config.json` sets `top_k 20` (eval-certified\ntruncation) so clients that send no sampling params still get sane output.\nDo **not** add `min_p` when speculative decoding is on — vLLM rejects\n`min_p`/`logit_bias` with speculation; use `top_k`/`top_p`.\n\n## Speculative decoding (DFlash)\n\nEnable the **Spec Decoding** toggle above to attach Poolside's\n[DFlash draft model](https://huggingface.co/poolside/Laguna-S-2.1-DFlash) — a\nparallel drafter that proposes up to 15 draft tokens per step. Measured mean\naccepted length is ~3.1 tokens/step on natural text (higher on code),\nmatching Poolside's production deployment.\n\nRequires:\n- DFlash drafter support for Laguna, merged in\n [PR #46853](https://github.com/vllm-project/vllm/pull/46853) (2026-07-03) —\n use a vLLM build that includes it (validated on 0.25.1).\n- `--moe-backend triton` — the default DeepGEMM MoE backend is incompatible\n with the DFlash draft path. Enabling the toggle adds this flag.\n\n```bash\nvllm serve poolside/Laguna-S-2.1 \\\n --trust-remote-code \\\n --tensor-parallel-size 8 \\\n --max-model-len 16384 \\\n --enable-auto-tool-choice \\\n --tool-call-parser poolside_v1 \\\n --reasoning-parser poolside_v1 \\\n --speculative-config '{\"model\":\"poolside/Laguna-S-2.1-DFlash\",\"num_speculative_tokens\":15,\"method\":\"dflash\"}' \\\n --moe-backend triton\n```\n\n### DGX Spark (GB10)\n\nThe NVFP4 checkpoint is validated on a single DGX Spark (GB10, `sm_121a`) with\nvLLM 0.25.1 + a FlashInfer nightly and DFlash — see the\n[Laguna-S-2.1-NVFP4 model card](https://huggingface.co/poolside/Laguna-S-2.1-NVFP4)\nfor the full one-box recipe.\n\n## References\n\n- [Model card](https://huggingface.co/poolside/Laguna-S-2.1)\n- [DFlash draft model](https://huggingface.co/poolside/Laguna-S-2.1-DFlash)\n- [vLLM DFlash spec-decoding PR #46853](https://github.com/vllm-project/vllm/pull/46853)\n- [Laguna XS-2.1 recipe](https://huggingface.co/poolside/Laguna-XS-2.1)\n", "source": { "source": "vllm", "repo": "vllm-project/vllm", "ref": "main", "sha": "389ffebe555705c85337025d5df108d0384d365e", "path": "recipes/models/poolside/Laguna-S-2.1.yaml", "edit_url": "https://github.com/vllm-project/vllm/edit/main/recipes/models/poolside/Laguna-S-2.1.yaml", "overlays": [] } }