vllm.model_executor.models.laguna ¶

class LagunaAttention(nn.Module):
    """Laguna attention with optional softplus output gating.

    Supports per-layer sliding window attention when ``config.layer_types``
    is present.  Layers whose type is ``"sliding_attention"`` use
    ``config.sliding_window``; all other layers (typically labelled
    ``"full_attention"``) use full attention.  When ``layer_types`` is
    absent every layer defaults to full attention for backwards
    compatibility.
    """

    def __init__(
        self,
        config,
        hidden_size: int,
        num_heads: int,
        num_kv_heads: int,
        max_position_embeddings: int = 131072,
        head_dim: int | None = None,
        cache_config: CacheConfig | None = None,
        quant_config: QuantizationConfig | None = None,
        prefix: str = "",
        attention_sink: bool = False,
        layer_idx: int | None = None,
        attention_prefix: str | None = None,
    ) -> None:
        super().__init__()
        if layer_idx is None:
            layer_idx = extract_layer_index(prefix)
        if attention_prefix is None:
            attention_prefix = prefix
        self.hidden_size = hidden_size
        tp_size = get_tensor_model_parallel_world_size()
        self.total_num_heads = num_heads
        assert self.total_num_heads % tp_size == 0
        self.num_heads = self.total_num_heads // tp_size
        self.total_num_kv_heads = num_kv_heads
        if self.total_num_kv_heads >= tp_size:
            assert self.total_num_kv_heads % tp_size == 0
        else:
            assert tp_size % self.total_num_kv_heads == 0
        self.num_kv_heads = max(1, self.total_num_kv_heads // tp_size)
        self.head_dim = head_dim or (hidden_size // self.total_num_heads)
        self.q_size = self.num_heads * self.head_dim
        self.kv_size = self.num_kv_heads * self.head_dim
        self.scaling = self.head_dim**-0.5
        self.max_position_embeddings = max_position_embeddings

        # Gating flag
        self.gating = config.gating

        # Per-layer sliding window (follows Gemma2/Cohere2 convention)
        layer_types = getattr(config, "layer_types", None)
        if layer_types is not None:
            is_sliding = layer_types[layer_idx] == "sliding_attention"
            self.sliding_window = config.sliding_window if is_sliding else None
        else:
            self.sliding_window = None

        # QKV projection (no bias for Laguna)
        self.qkv_proj = QKVParallelLinear(
            self.hidden_size,
            self.head_dim,
            self.total_num_heads,
            self.total_num_kv_heads,
            bias=config.qkv_bias,
            quant_config=quant_config,
            prefix=f"{prefix}.qkv_proj",
        )

        # Output projection
        self.o_proj = RowParallelLinear(
            self.total_num_heads * self.head_dim,
            self.hidden_size,
            bias=config.attention_bias,
            quant_config=quant_config,
            prefix=f"{prefix}.o_proj",
        )

        # Gating projection (Laguna-specific, optional)
        # config.gating may be:
        #   - True / "per-element": one gate per (head, head_dim) channel
        #   - "per-head":           one gate per head, broadcast across head_dim
        if self.gating:
            # v5 LagunaConfig uses ``gating=True`` for per-head; older configs
            # used ``"per-head"``. Accept both. ``"per-element"`` (or legacy
            # ``True``) means per-element gating with output size num_heads ×
            # head_dim.
            gate_per_head = self.gating is True or self.gating == "per-head"
            g_out = (
                self.total_num_heads
                if gate_per_head
                else self.total_num_heads * self.head_dim
            )
            self.g_proj = ColumnParallelLinear(
                hidden_size,
                g_out,
                bias=False,
                quant_config=quant_config,
                prefix=f"{prefix}.g_proj",
            )
            self.gate_per_head = gate_per_head
        else:
            self.g_proj = None
            self.gate_per_head = False

        # Attention sinks (learnable per-head bias for SWA layers)
        sinks = None
        if attention_sink:
            self.sink = torch.nn.Parameter(
                torch.empty(self.total_num_heads // tp_size, requires_grad=False)
            )
            sinks = self.sink

        # Resolve rope params per-layer-type. ``config.rope_parameters`` is
        # either a flat dict (legacy) or a nested ``{layer_type: rope_dict}``
        # (v5 Laguna-XS schema). The v5 form is unhashable as-is and would
        # crash `get_rope`'s cache lookup, so always pull out the layer's
        # sub-dict before forwarding.
        layer_type = (
            layer_types[layer_idx] if layer_types is not None else "full_attention"
        )
        is_sliding = layer_type == "sliding_attention"

        top_rope = getattr(config, "rope_parameters", None) or {}
        if any(isinstance(v, dict) for v in top_rope.values()):
            # Nested per-layer-type form.
            base_rope = top_rope.get(layer_type) or top_rope.get("full_attention") or {}
        else:
            base_rope = top_rope

        # Older flat-rope ckpts can carry a separate `swa_rope_parameters`
        # for SWA layers. Prefer it when present; otherwise the nested
        # rope dict above already supplies the correct sub-config.
        swa_rope = getattr(config, "swa_rope_parameters", None)
        if (
            is_sliding
            and swa_rope is None
            and not any(isinstance(v, dict) for v in top_rope.values())
        ):
            logger.warning_once(
                "Laguna config has sliding_attention layers but neither "
                "`swa_rope_parameters` nor a nested per-layer-type "
                "`rope_parameters` — SWA layers will reuse the global rope. "
                "If the checkpoint was trained with distinct SWA rope "
                "(theta / partial_rotary_factor), regenerate its HF config "
                "to include either form."
            )
        rope_params = swa_rope if (is_sliding and swa_rope is not None) else base_rope
        # `partial_rotary_factor` may live on the top-level config (main attention)
        # or on the per-layer rope dict itself (e.g. SWA can differ). Inject the
        # top-level value into `rope_params` if the dict doesn't already set it.
        top_partial = getattr(config, "partial_rotary_factor", None)
        if top_partial is not None and "partial_rotary_factor" not in rope_params:
            rope_params = {**rope_params, "partial_rotary_factor": top_partial}

        # Rotary embeddings (YaRN)
        self.rotary_emb = get_rope(
            head_size=self.head_dim,
            max_position=max_position_embeddings,
            is_neox_style=True,
            rope_parameters=rope_params,
        )

        self.attn = Attention(
            self.num_heads,
            self.head_dim,
            self.scaling,
            num_kv_heads=self.num_kv_heads,
            cache_config=cache_config,
            quant_config=quant_config,
            per_layer_sliding_window=self.sliding_window,
            prefix=f"{attention_prefix}.attn",
            sinks=sinks,
        )

        # QK normalization (like Qwen3)
        self.q_norm = RMSNorm(self.head_dim, eps=config.rms_norm_eps)
        self.k_norm = RMSNorm(self.head_dim, eps=config.rms_norm_eps)

    def forward(
        self,
        positions: torch.Tensor,
        hidden_states: torch.Tensor,
    ) -> torch.Tensor:
        qkv, _ = self.qkv_proj(hidden_states)
        q, k, v = qkv.split([self.q_size, self.kv_size, self.kv_size], dim=-1)

        q_by_head = q.view(*q.shape[:-1], q.shape[-1] // self.head_dim, self.head_dim)
        q_by_head = self.q_norm(q_by_head)
        q = q_by_head.view(q.shape)

        k_by_head = k.view(*k.shape[:-1], k.shape[-1] // self.head_dim, self.head_dim)
        k_by_head = self.k_norm(k_by_head)
        k = k_by_head.view(k.shape)

        q, k = self.rotary_emb(positions, q, k)
        attn_output = self.attn(q, k, v)

        # Apply gating if enabled (compute softplus in float32 for precision)
        if self.gating and self.g_proj is not None:
            gate, _ = self.g_proj(hidden_states)
            gate = F.softplus(gate.float()).type_as(attn_output)
            if self.gate_per_head:
                # gate: [..., num_heads]; broadcast across head_dim
                attn_shape = attn_output.shape
                attn_output = (
                    attn_output.view(*attn_shape[:-1], self.num_heads, self.head_dim)
                    * gate.unsqueeze(-1)
                ).view(attn_shape)
            else:
                attn_output = attn_output * gate

        output, _ = self.o_proj(attn_output)
        return output

class LagunaMLP(nn.Module):
    """Dense MLP for Laguna (used in mlp_only_layers)."""

    def __init__(
        self,
        hidden_size: int,
        intermediate_size: int,
        hidden_act: str,
        quant_config: QuantizationConfig | None = None,
        reduce_results: bool = True,
        prefix: str = "",
    ) -> None:
        super().__init__()
        # gate_proj and up_proj are kept as separate ColumnParallelLinear
        # rather than merged via MergedColumnParallelLinear. The merged form
        # requires per-partition NVFP4 global scales (weight_global_scale,
        # input_global_scale) to be packed into a length-2 PerTensorScaleParameter
        # and then collapsed via .max() in process_weights_after_loading; this
        # doesn't round-trip cleanly through Marlin's NVFP4 stacked-layer code
        # path. Splitting yields one global scale per Linear, exactly matching
        # the standard compressed-tensors per-Linear schema on disk.
        self.gate_proj = ColumnParallelLinear(
            hidden_size,
            intermediate_size,
            bias=False,
            quant_config=quant_config,
            prefix=f"{prefix}.gate_proj",
        )
        self.up_proj = ColumnParallelLinear(
            hidden_size,
            intermediate_size,
            bias=False,
            quant_config=quant_config,
            prefix=f"{prefix}.up_proj",
        )
        self.down_proj = RowParallelLinear(
            intermediate_size,
            hidden_size,
            bias=False,
            quant_config=quant_config,
            reduce_results=reduce_results,
            prefix=f"{prefix}.down_proj",
        )
        if hidden_act != "silu":
            raise ValueError(
                f"Unsupported activation: {hidden_act}. Only silu is supported."
            )

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        gate, _ = self.gate_proj(x)
        up, _ = self.up_proj(x)
        x, _ = self.down_proj(F.silu(gate) * up)
        return x

class LagunaMoE(nn.Module):
    """Sparse MoE block for Laguna with optional shared expert and sigmoid routing.

    Key differences from other MoE implementations:
    - Uses SIGMOID routing activation (not softmax)
    - Shared expert runs in parallel with routed experts (when enabled)
    - Matches HF reference: modular_laguna.py LagunaSparseMoeBlock
    """

    def __init__(
        self,
        config,
        quant_config: QuantizationConfig | None = None,
        prefix: str = "",
        enable_eplb: bool = False,
    ):
        super().__init__()
        self.config = config
        self.num_experts = config.num_experts
        self.top_k = config.num_experts_per_tok

        self.tp_size = get_tensor_model_parallel_world_size()
        self.ep_group = get_ep_group().device_group
        self.ep_rank = self.ep_group.rank()
        self.ep_size = self.ep_group.size()

        self.n_routed_experts = config.num_experts
        self.n_shared_experts = 1 if config.shared_expert_intermediate_size > 0 else 0
        self.routed_scaling_factor = float(
            getattr(config, "moe_routed_scaling_factor", 1.0)
        )

        if self.tp_size > config.num_experts:
            raise ValueError(
                f"Tensor parallel size {self.tp_size} is greater than "
                f"the number of experts {config.num_experts}."
            )

        # Load balancing settings.
        vllm_config = get_current_vllm_config()
        eplb_config = vllm_config.parallel_config.eplb_config
        self.enable_eplb = enable_eplb
        eplb_config.num_redundant_experts = (
            eplb_config.num_redundant_experts
            if eplb_config.num_redundant_experts is not None
            else 0
        )
        self.n_redundant_experts = eplb_config.num_redundant_experts
        self.n_logical_experts = self.n_routed_experts
        self.n_physical_experts = self.n_logical_experts + self.n_redundant_experts
        self.n_local_physical_experts = self.n_physical_experts // self.ep_size
        self.physical_expert_start = self.ep_rank * self.n_local_physical_experts
        self.physical_expert_end = (
            self.physical_expert_start + self.n_local_physical_experts
        )

        # Router gate
        self.gate = ReplicatedLinear(
            config.hidden_size,
            config.num_experts,
            bias=False,
            quant_config=None,
            prefix=f"{prefix}.gate",
        )

        # Shared expert (optional) - passed to FusedMoE for overlap optimization
        self.shared_expert: LagunaMLP | None
        if config.shared_expert_intermediate_size > 0:
            self.shared_expert = LagunaMLP(
                hidden_size=config.hidden_size,
                intermediate_size=config.shared_expert_intermediate_size,
                hidden_act=config.hidden_act,
                quant_config=quant_config,
                reduce_results=False,  # Reduce after shared+routed combine
                prefix=f"{prefix}.shared_expert",
            )
        else:
            self.shared_expert = None

        # Auxiliary-loss-free load-balancing bias (arXiv:2408.15664). The
        # checkpoint stores one [num_experts] tensor per MoE layer at
        # `mlp.experts.e_score_correction_bias`; registering it as a Parameter
        # on the FusedMoE lets the weight loader pick it up and the router
        # add it during top-k selection. The fused top-k bias router requires
        # float32 regardless of model dtype.
        e_score_correction_bias = torch.nn.Parameter(
            torch.zeros(config.num_experts, dtype=torch.float32),
            requires_grad=False,
        )

        # FusedMoE with SIGMOID routing. Passing `shared_experts=` lets the
        # layer overlap the shared-expert compute with the all2all dispatch.
        # `apply_routed_scale_to_output=True` makes FusedMoE handle the
        # routed_scaling_factor, shared+routed combine, and TP all-reduce
        # internally, so forward() just returns the final hidden states.
        self.experts = FusedMoE(
            shared_experts=self.shared_expert,
            num_experts=config.num_experts,
            top_k=config.num_experts_per_tok,
            hidden_size=config.hidden_size,
            intermediate_size=config.moe_intermediate_size,
            renormalize=config.norm_topk_prob,
            quant_config=quant_config,
            prefix=f"{prefix}.experts",
            scoring_func="sigmoid",
            use_grouped_topk=False,
            apply_router_weight_on_input=bool(config.moe_apply_router_weight_on_input),
            e_score_correction_bias=e_score_correction_bias,
            enable_eplb=self.enable_eplb,
            num_redundant_experts=self.n_redundant_experts,
            routed_scaling_factor=self.routed_scaling_factor,
            apply_routed_scale_to_output=True,
        )

    def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
        orig_shape = hidden_states.shape
        hidden_dim = hidden_states.shape[-1]
        hidden_states = hidden_states.view(-1, hidden_dim)

        router_logits, _ = self.gate(hidden_states)
        router_logits = router_logits.float()
        softcap = getattr(self.config, "moe_router_logit_softcapping", 0.0) or 0.0
        if softcap > 0.0:
            router_logits = torch.tanh(router_logits / softcap) * softcap

        final_hidden_states = self.experts(hidden_states, router_logits)
        return final_hidden_states.view(orig_shape)