[Model] Add Reflection Beam

.buildkite/test_areas/models_basic.yaml

@@ -11,9 +11,12 @@ steps:
   - "!vllm/distributed/kv_transfer/"
   - tests/models/test_initialization.py
   - tests/models/registry.py
+  - tests/models/test_beam_construction.py
   commands:
     # Run a subset of model initialization tests
     - pytest -v -s models/test_initialization.py::test_can_initialize_small_subset
+    # Exercise Beam construction and generation without a checkpoint download.
+    - pytest -v -s models/test_beam_construction.py
   mirror:
     amd:
       label: ":amd: (MI355 DPX) Basic Models (Initialization)"
@@ -257,6 +260,8 @@ steps:
   - tests/models/test_qwen3_5_mtp_config.py
   - tests/models/test_alice_ai.py
   - tests/models/test_alice_ai_config.py
+  - tests/models/test_beam_weight_mapping.py
+  - tests/models/test_beam_numerics.py
   - tests/models/transformers/fusers/
   - tests/models/transformers/test_dynamic_rope.py
   - tests/model_executor/layers/test_activation.py
@@ -267,7 +272,7 @@ steps:
   - tests/models/transformers/test_layer_registry.py
   device: cpu-small
   commands:
-    - pytest -v -s models/test_utils.py models/test_vision.py models/test_adapters.py models/test_qwen3_5_mtp_config.py models/transformers/fusers/ models/transformers/test_dynamic_rope.py model_executor/layers/test_activation.py models/test_language_model_cache_is_weak.py models/deepseek_v32/test_sequence_parallel.py models/test_deepseek_v4_fi_moe_ep.py models/test_dspark_mla.py models/transformers/test_layer_registry.py models/test_alice_ai.py models/test_alice_ai_config.py
+    - pytest -v -s models/test_utils.py models/test_vision.py models/test_adapters.py models/test_qwen3_5_mtp_config.py models/transformers/fusers/ models/transformers/test_dynamic_rope.py model_executor/layers/test_activation.py models/test_language_model_cache_is_weak.py models/deepseek_v32/test_sequence_parallel.py models/test_deepseek_v4_fi_moe_ep.py models/test_dspark_mla.py models/transformers/test_layer_registry.py models/test_alice_ai.py models/test_alice_ai_config.py models/test_beam_weight_mapping.py models/test_beam_numerics.py
 
 - label: ':amd: (MI355) DeepSeek-V4.1 Mono Decode Numerics'
   key: dsv41-mono-decode-numerics-amd

csrc/fp32_router_gemm.cu

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 //
-// Router GEMM: activation(T) x weight(fp32) -> fp32, M<=32, for the
+// Router GEMM: activation(T) x weight(fp32) -> fp32, M<=48, for the
 // supported (E, H) pairs listed at the bottom of this file.
 // Supports bf16 or fp32 activation; weight is always fp32.
 
@@ -214,8 +214,26 @@ void invokeFp32RouterGemm(float* output, InputT const* mat_a,
   // production-fidelity harness (CUDA-graph replay, per-layer cold weights).
   // Only enabled on the Blackwell family where it was validated; Hopper and
   // other shapes / fp32 activation keep the legacy geometry.
-  if constexpr (std::is_same_v<InputT, __nv_bfloat16> && kNumExperts == 128 &&
-                kHiddenDim == 6144) {
+  if constexpr (std::is_same_v<InputT, __nv_bfloat16> && kNumExperts == 256 &&
+                kHiddenDim == 5120) {
+    if (!isBlackwellFamily()) {
+      launchFp32RouterGemm<InputT, 128, 1, kNumTokens, kNumExperts, kHiddenDim>(
+          output, mat_a, mat_b, stream);
+      return;
+    }
+    if constexpr (kNumTokens > 16 && kNumTokens % 8 == 0) {
+      constexpr int block_size = kNumTokens == 24 ? 160 : 128;
+      launchFp32RouterGemm<InputT, block_size, 2, kNumTokens, kNumExperts,
+                           kHiddenDim, 4>(output, mat_a, mat_b, stream);
+    } else {
+      constexpr int block_size = kNumTokens == 1 ? 64 : 128;
+      constexpr int token_groups = kNumTokens % 2 == 0 ? 2 : 1;
+      launchFp32RouterGemm<InputT, block_size, 1, kNumTokens, kNumExperts,
+                           kHiddenDim, token_groups>(output, mat_a, mat_b,
+                                                     stream);
+    }
+  } else if constexpr (std::is_same_v<InputT, __nv_bfloat16> &&
+                       kNumExperts == 128 && kHiddenDim == 6144) {
     // MiniMax-M3. Legacy 128/1 only fills 128 blocks and pays the same
     // accumulator register cliffs; B300 sweep:
     //   even M in [6, 10] : BS=384, EPB=1, 2 token groups (1.26-1.43x)
@@ -268,8 +286,8 @@ void invokeFp32RouterGemm(float* output, InputT const* mat_a,
 }
 
 // ---------------------------------------------------------------------------
-// Explicit instantiations: M=1..32, for both input types, for the supported
-// (E, H) pairs:  (256, 3072) [MiniMax-M2/M2.5]  and  (128, 6144) [MiniMax-M3].
+// Explicit instantiations for both input types.
+// Supported (E, H) pairs: (256, 3072), (128, 6144), and (256, 5120).
 // ---------------------------------------------------------------------------
 
 #define INSTANTIATE(T, M, E, H)                                    \
@@ -315,5 +333,31 @@ INSTANTIATE_ALL(__nv_bfloat16, 256, 3072)
 INSTANTIATE_ALL(float, 128, 6144)
 INSTANTIATE_ALL(__nv_bfloat16, 128, 6144)
 
+INSTANTIATE_ALL(float, 256, 5120)
+INSTANTIATE_ALL(__nv_bfloat16, 256, 5120)
+
+#define INSTANTIATE_LARGE(T, E, H) \
+  INSTANTIATE(T, 33, E, H)         \
+  INSTANTIATE(T, 34, E, H)         \
+  INSTANTIATE(T, 35, E, H)         \
+  INSTANTIATE(T, 36, E, H)         \
+  INSTANTIATE(T, 37, E, H)         \
+  INSTANTIATE(T, 38, E, H)         \
+  INSTANTIATE(T, 39, E, H)         \
+  INSTANTIATE(T, 40, E, H)         \
+  INSTANTIATE(T, 41, E, H)         \
+  INSTANTIATE(T, 42, E, H)         \
+  INSTANTIATE(T, 43, E, H)         \
+  INSTANTIATE(T, 44, E, H)         \
+  INSTANTIATE(T, 45, E, H)         \
+  INSTANTIATE(T, 46, E, H)         \
+  INSTANTIATE(T, 47, E, H)         \
+  INSTANTIATE(T, 48, E, H)
+
+INSTANTIATE_LARGE(float, 256, 5120)
+INSTANTIATE_LARGE(__nv_bfloat16, 256, 5120)
+
+#undef INSTANTIATE_LARGE
+
 #undef INSTANTIATE_ALL
 #undef INSTANTIATE

csrc/fp32_router_gemm_entry.cu

@@ -25,10 +25,11 @@ inline int getSMVersion() {
 static constexpr int FP32_MAX_TOKENS = 32;
 
 // Supported (hidden_dim, num_experts) pairs (must match the instantiations in
-// fp32_router_gemm.cu): (3072, 256) for MiniMax-M2/M2.5, (6144, 128) for M3.
+// fp32_router_gemm.cu).
 static inline bool fp32_router_gemm_supported(int hidden_dim, int num_experts) {
   return (hidden_dim == 3072 && num_experts == 256) ||
-         (hidden_dim == 6144 && num_experts == 128);
+         (hidden_dim == 6144 && num_experts == 128) ||
+         (hidden_dim == 5120 && num_experts == 256);
 }
 
 // Forward declarations — 4 template params must match fp32_router_gemm.cu
@@ -60,8 +61,7 @@ struct Fp32LoopUnroller<InputT, kNumExperts, kHiddenDim, kEnd, kEnd> {
       invokeFp32RouterGemm<InputT, kEnd, kNumExperts, kHiddenDim>(
           output, mat_a, mat_b, stream);
     } else {
-      throw std::invalid_argument(
-          "fp32_router_gemm: num_tokens must be in [1, 32]");
+      throw std::invalid_argument("fp32_router_gemm: unsupported num_tokens");
     }
   }
 };
@@ -77,6 +77,9 @@ void dispatchFp32RouterGemm(int num_experts, int hidden_dim, int num_tokens,
   } else if (num_experts == 128 && hidden_dim == 6144) {
     Fp32LoopUnroller<InputT, 128, 6144, 1, FP32_MAX_TOKENS>::unroll(
         num_tokens, output, mat_a, mat_b, stream);
+  } else if (num_experts == 256 && hidden_dim == 5120) {
+    Fp32LoopUnroller<InputT, 256, 5120, 1, 48>::unroll(num_tokens, output,
+                                                       mat_a, mat_b, stream);
   } else {
     throw std::invalid_argument(
         "fp32_router_gemm: unsupported (hidden_dim, num_experts) pair");
@@ -111,9 +114,11 @@ void fp32_router_gemm(
   STD_TORCH_CHECK(
       fp32_router_gemm_supported(hidden_dim, num_experts),
       "fp32_router_gemm: supported (hidden_dim, num_experts) pairs are "
-      "(3072, 256) and (6144, 128)");
-  STD_TORCH_CHECK(num_tokens <= FP32_MAX_TOKENS,
-                  "fp32_router_gemm: num_tokens must be in [0, 32]");
+      "(3072, 256), (6144, 128), and (5120, 256)");
+  const int max_tokens =
+      hidden_dim == 5120 && num_experts == 256 ? 48 : FP32_MAX_TOKENS;
+  STD_TORCH_CHECK(num_tokens <= max_tokens,
+                  "fp32_router_gemm: num_tokens exceeds supported range");
   STD_TORCH_CHECK(
       mat_a.scalar_type() == torch::headeronly::ScalarType::Float ||
           mat_a.scalar_type() == torch::headeronly::ScalarType::BFloat16,

docs/features/tool_calling.md

@@ -201,6 +201,30 @@ checkpoint's output format.
 !!! note
     With `tool_choice="auto"`, structural-tag constraints require both `VLLM_ENFORCE_STRICT_TOOL_CALLING=true` (the default) and at least one tool with `strict: true`, or a server-side floor set via `--tool-strict-level`. When these conditions are met and the selected parser supports structural tags, vLLM constrains the tool-call envelope and pins the argument schema of each tool that sets `strict: true` (or of every tool under `--tool-strict-level parameter`). Otherwise, vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function's parameter schema.
 
+### Beam Models (`beam`)
+
+Beam checkpoints describe their output format with `response_template` metadata, so the `beam` parser reads it like the `hf` parser does:
+
+```bash
+vllm serve <model> \
+    --enable-auto-tool-choice \
+    --tool-call-parser beam \
+    --reasoning-parser beam
+```
+
+Unlike `hf`, the `beam` parser also constrains its output. For strict tools, required or named tool choice, and structured outputs, it derives a
+structural-tag grammar from the template. The grammar follows the template's tool call format, pins the arguments of strict tools when their
+encoding can be derived, allows a single call with `parallel_tool_calls=false`, and frames a structured output as the answer. Raw string arguments
+keep the `format` or `pattern` of their schema, as XGrammar keeps them in JSON strings, unless a match could end the value early. With
+`tool_choice="none"`, the grammar allows only reasoning and an answer, so a model that still sees the tools in its prompt cannot call them. When no
+grammar can be derived, required and named tool choice are rejected, and strict tools under `tool_choice="auto"` are left unconstrained with a
+warning.
+
+It also constrains the output of requests without strict tools, forced tool choice, or structured outputs to the template's format: tool calls with
+free arguments or an answer, or just the rest of an answer the prompt already opened. This always-on grammar needs the `xgrammar` structured
+outputs backend, the default, and is disabled with `VLLM_BEAM_ALWAYS_CONSTRAIN_OUTPUT=0`. From the message start, every `beam` grammar opens with
+reasoning that holds visible text, unless `enable_thinking` is false.
+
 ### Hermes Models (`hermes`)
 
 All Nous Research Hermes-series models newer than Hermes 2 Pro should be supported.

docs/models/supported_models.md

@@ -379,6 +379,7 @@ th {
 | `BailingMoeV2ForCausalLM` | Ling | `inclusionAI/Ling-mini-2.0`, etc. | ✅︎ | ✅︎ |
 | `BailingMoeV2_5ForCausalLM` | Ling | `inclusionAI/Ling-2.5-1T`, `inclusionAI/Ring-2.5-1T` | | ✅︎ |
 | `BailingMoeV3ForCausalLM` | Ling | `inclusionAI/Ling-3.0-flash` | | ✅︎ |
+| `BeamForCausalLM` | Beam | `reflection/Beam-1.0-501B-A23B-NVFP4`, etc. | | ✅︎ |
 | `BloomForCausalLM` | BLOOM, BLOOMZ, BLOOMChat | `bigscience/bloom`, `bigscience/bloomz`, etc. | | ✅︎ |
 | `ChatGLMModel`, `ChatGLMForConditionalGeneration` | ChatGLM | `zai-org/chatglm2-6b`, `zai-org/chatglm3-6b`, `thu-coai/ShieldLM-6B-chatglm3`, etc. | ✅︎ | ✅︎ |
 | `CohereForCausalLM`, `Cohere2ForCausalLM` | Command-R, Command-A | `CohereLabs/c4ai-command-r-v01`, `CohereLabs/c4ai-command-r7b-12-2024`, `CohereLabs/c4ai-command-a-03-2025`, `CohereLabs/command-a-reasoning-08-2025`, etc. | ✅︎ | ✅︎ |

rust/src/chat/src/lib.rs

@@ -434,7 +434,7 @@ mod tests {
         )
         .unwrap_err();
 
-        expect_test::expect!["tool parser `definitely_missing_tool_parser` is not registered (choose from: deepseek_v3, deepseek_v31, deepseek_v32, deepseek_v4, deepseek_v41, gemma4, glm45, glm47, granite4, hermes, hf, hy_v3, hy_v4, inkling, internlm, kimi_k2, kimi_k3, llama3_json, llama4_json, mimo, minimax_m2, minimax_m3, mistral, phi4_mini_json, qwen3_coder, qwen3_json, qwen3_xml, seed_oss)"].assert_eq(&error.to_report_string());
+        expect_test::expect!["tool parser `definitely_missing_tool_parser` is not registered (choose from: beam, deepseek_v3, deepseek_v31, deepseek_v32, deepseek_v4, deepseek_v41, gemma4, glm45, glm47, granite4, hermes, hf, hy_v3, hy_v4, inkling, internlm, kimi_k2, kimi_k3, llama3_json, llama4_json, mimo, minimax_m2, minimax_m3, mistral, phi4_mini_json, qwen3_coder, qwen3_json, qwen3_xml, seed_oss)"].assert_eq(&error.to_report_string());
     }
 
     #[test]
@@ -445,6 +445,6 @@ mod tests {
         )
         .unwrap_err();
 
-        expect_test::expect!["reasoning parser `definitely_missing_reasoning_parser` is not registered (choose from: cohere_cmd, deepseek_r1, deepseek_v3, deepseek_v4, deepseek_v41, gemma4, glm45, glm47, hf, hy_v3, hy_v4, inkling, kimi, kimi_k2, kimi_k3, mimo, minimax_m2, minimax_m3, nemotron_v3, qwen3, seed_oss, step3, step3p5)"].assert_eq(&error.to_report_string());
+        expect_test::expect!["reasoning parser `definitely_missing_reasoning_parser` is not registered (choose from: beam, cohere_cmd, deepseek_r1, deepseek_v3, deepseek_v4, deepseek_v41, gemma4, glm45, glm47, hf, hy_v3, hy_v4, inkling, kimi, kimi_k2, kimi_k3, mimo, minimax_m2, minimax_m3, nemotron_v3, qwen3, seed_oss, step3, step3p5)"].assert_eq(&error.to_report_string());
     }
 }

rust/src/chat/src/output/default/mod.rs

@@ -23,7 +23,8 @@ use crate::output::{ChatOutputProcessor, DynChatEventStream, DynDecodedTextEvent
 use crate::parser::reasoning::{ReasoningParser, ReasoningParserFactory};
 use crate::parser::tool::{ToolParser, ToolParserFactory};
 use crate::parser::unified::{
-    HfTemplateError, HfUnifiedParser, ResponseTemplate, UnifiedParserFactory, names,
+    BeamUnifiedParser, HfTemplateError, HfUnifiedParser, ResponseTemplate, UnifiedParserFactory,
+    names,
 };
 use crate::parser::{ParserSelection, ToolStrictLevel};
 use crate::request::{ChatRequest, ChatTool};
@@ -206,17 +207,19 @@ impl DefaultChatOutputProcessor {
             });
         }
 
-        // `hf` is built from the model's template, never by its registry constructor.
-        let parser = if parser_name == names::HF {
-            let template =
-                response_template.as_ref().map_err(|error| Error::ParserInitialization {
-                    kind: "unified",
-                    name: parser_name.to_string(),
-                    error: Box::new(error.clone()),
-                })?;
-            Box::new(HfUnifiedParser::new(template.clone(), tools, tokenizer))
-        } else {
-            factory.create(parser_name, tools, tokenizer)?
+        // Parsers driven by the model's template are built from it, never by
+        // their registry constructors.
+        let template = || {
+            response_template.clone().map_err(|error| Error::ParserInitialization {
+                kind: "unified",
+                name: parser_name.to_string(),
+                error: Box::new(error),
+            })
+        };
+        let parser: Box<dyn UnifiedParser> = match parser_name {
+            names::HF => Box::new(HfUnifiedParser::new(template()?, tools, tokenizer)),
+            names::BEAM => Box::new(BeamUnifiedParser::new(template()?, tools, tokenizer)),
+            _ => factory.create(parser_name, tools, tokenizer)?,
         };
 
         UNIFIED_PARSER_LOG_ONCE.call_once(|| info!(parser_name, "using unified parser"));
@@ -589,6 +592,20 @@ mod tests {
             .assert_eq(&error(invalid_template()));
     }
 
+    #[test]
+    fn explicit_beam_uses_the_model_response_template() {
+        let beam = ParserSelection::Explicit("beam".to_string());
+        crate::parser::validate_parser_overrides(&beam, &beam).unwrap();
+        assert!(keeps_special_tokens("other-model", &loaded_template(), &beam, &beam).unwrap());
+
+        let error =
+            keeps_special_tokens("other-model", &Err(HfTemplateError::Missing), &beam, &beam)
+                .unwrap_err()
+                .to_report_string();
+        expect_test::expect!["failed to initialize unified parser `beam`: the model's tokenizer_config.json provides no response_template"]
+            .assert_eq(&error);
+    }
+
     #[test]
     fn auto_never_selects_hf() {
         let auto = ParserSelection::Auto;

rust/src/chat/src/parser/unified.rs

@@ -6,8 +6,8 @@
 use std::sync::LazyLock;
 
 pub use vllm_parser::unified::{
-    Gemma4UnifiedParser, HfTemplateError, HfUnifiedParser, HyV3UnifiedParser, HyV4UnifiedParser,
-    InklingUnifiedParser, KimiK3UnifiedParser, ResponseTemplate, UnifiedParser,
+    BeamUnifiedParser, Gemma4UnifiedParser, HfTemplateError, HfUnifiedParser, HyV3UnifiedParser,
+    HyV4UnifiedParser, InklingUnifiedParser, KimiK3UnifiedParser, ResponseTemplate, UnifiedParser,
 };
 use vllm_tokenizer::DynTokenizer;
 
@@ -26,6 +26,9 @@ pub mod names {
     /// name resolution only: it is built from the model's template, never by its
     /// registry constructor.
     pub const HF: &str = "hf";
+    /// Beam checkpoints: [`HF`] with Beam's tool-call grammar, built from the
+    /// model's template the same way.
+    pub const BEAM: &str = "beam";
 }
 
 /// Constructor signature for one registered unified parser implementation.
@@ -55,6 +58,7 @@ impl UnifiedParserFactory {
         factory.register_parser::<KimiK3UnifiedParser>(names::KIMI_K3);
         // Opt-in only: no model patterns map to it.
         factory.register_parser::<HfUnifiedParser>(names::HF);
+        factory.register_parser::<BeamUnifiedParser>(names::BEAM);
 
         factory
             .register_pattern("gemma-4", names::GEMMA4)

rust/src/parser/src/output_grammar.rs

@@ -207,7 +207,8 @@ pub(crate) fn full_format_from_builder_for_test(
     )
 }
 
-fn tool_params(tools: &[Tool], strict_level: ToolStrictLevel) -> Vec<ToolParam> {
+/// Tools as builder inputs, strict when the tool or the server floor asks for it.
+pub(crate) fn tool_params(tools: &[Tool], strict_level: ToolStrictLevel) -> Vec<ToolParam> {
     tools
         .iter()
         .map(|tool| {
@@ -240,7 +241,7 @@ pub(crate) fn normalize_tool_choice(
 }
 
 /// Whether the request asks for a tool grammar at all.
-fn tool_grammar_applies(ctx: &OutputGrammarContext<'_>) -> bool {
+pub(crate) fn tool_grammar_applies(ctx: &OutputGrammarContext<'_>) -> bool {
     if ctx.tools.is_empty() {
         return false;
     }