{"record":{"id":"6d060fd26ced833b","repo":"sgl-project/sglang","slug":"visionattention-head-size-is-deprecated-use","errorCode":null,"errorMessage":"VisionAttention(head_size=...) is deprecated; use head_dim=...","messagePattern":"VisionAttention\\(head_size=\\.\\.\\.\\) is deprecated; use head_dim=\\.\\.\\.","errorType":"console","errorClass":"DeprecationWarning","httpStatus":null,"severity":"warning","filePath":"python/sglang/srt/layers/attention/vision.py","lineNumber":1067,"sourceCode":"        qkv_bias: bool = True,\n        qk_normalization: bool = False,\n        qk_normalization_by_head_size: bool = False,\n        layer_norm_eps: float = 1e-06,\n        customized_position_embedding_applier: Callable[\n            [torch.Tensor, torch.Tensor, Any, Any], Tuple[torch.Tensor, torch.Tensor]\n        ] = None,\n        use_data_parallel: bool = False,\n        use_dp_attention_reduce: bool = False,\n        aux_stream: Optional[torch.cuda.Stream] = None,\n        workspace_buffer: Optional[torch.Tensor] = None,\n        use_sink: bool = False,\n        window_size: Tuple[int, int] = (-1, -1),\n        **kwargs,\n    ):\n        super().__init__()\n        if head_dim is None and \"head_size\" in kwargs:\n            head_dim = kwargs.pop(\"head_size\")\n            warnings.warn(\n                \"VisionAttention(head_size=...) is deprecated; use head_dim=...\",\n                DeprecationWarning,\n                stacklevel=2,\n            )\n        self.tp_size = 1 if use_data_parallel else get_parallel().attn_tp_size\n        self.tp_rank = 0 if use_data_parallel else get_parallel().attn_tp_rank\n        self.dropout = dropout\n        num_kv_heads = num_kv_heads if num_kv_heads is not None else num_heads\n        self.head_size = head_dim if head_dim is not None else embed_dim // num_heads\n        self.softmax_scale = softmax_scale\n        self.hidden_size_per_attention_head = dist_utils.divide(\n            projection_size, num_heads\n        )\n        self.num_attention_heads_per_partition = dist_utils.divide(\n            num_dummy_heads + num_heads, self.tp_size\n        )\n        self.num_attention_kv_heads_per_partition = dist_utils.divide(\n            num_dummy_heads + num_kv_heads, self.tp_size","sourceCodeStart":1049,"sourceCodeEnd":1085,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/layers/attention/vision.py#L1049-L1085","documentation":"DeprecationWarning raised in VisionAttention.__init__: the constructor argument `head_size` was renamed to `head_dim`. Passing head_size still works (it is popped from kwargs and mapped to head_dim) but warns and will be removed.","triggerScenarios":"Constructing VisionAttention(...) with head_size=N (common when loading checkpoints or instantiating vision towers copied from older code), which triggers the kwargs fallback branch.","commonSituations":"Vision-language model implementations (e.g. custom ViT towers) written before the argument rename; quantized/CPU configs or HF config plumbing passing head_size through kwargs.","solutions":["Rename the keyword argument to head_dim in the VisionAttention(...) call","Update any config-to-kwarg mapping code that injects head_size","Remove other deprecated kwargs from the same call to avoid future breaks"],"exampleFix":"# before\nattn = VisionAttention(head_size=72, ...)\n# after\nattn = VisionAttention(head_dim=72, ...)","handlingStrategy":"validation","validationCode":"kwargs.pop(\"head_size\", None) is None or (_ for _ in ()).throw(ValueError(\"use head_dim\"))","typeGuard":"def uses_vision_attn_new_api() -> bool:\n    import inspect\n    from sglang.srt.layers.attention.vision import VisionAttention\n    return \"head_dim\" in inspect.signature(VisionAttention.__init__).parameters","tryCatchPattern":null,"preventionTips":["Pass head_dim= explicitly","Inspect the signature before constructing attention layers across sglang versions"],"tags":["deprecation","sglang","vision","api-rename"],"backgroundTag":"deprecated-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}