执行摘要

• 一句话：按模型能力门控 CUDA IPC，纯文本模型退回 CPU
• 推荐动作：值得精读。PR 展示了如何在 server args 解析阶段利用 model_config.is_multimodal 做能力门控，以及如何用测试固定自动策略的“默认契约”。实现虽小，但对理解 sglang 多模态特征传输的自动解析路径有帮助，测试写法也有参考价值。

功能与动机

PR body 指出：#30904 添加了多模态特征传输，#32541 在单节点 CUDA 上自动启用 CUDA IPC，无意中也会选中纯文本模型，并记录误导性的 1 GiB 保留日志。由于纯文本模型不会创建多模态处理器，池实际上不会被分配，但自动判定和日志会让用户误以为占用了 GPU 显存。因此需要按模型能力门控自动选择，让纯文本模型留在 CPU 传输路径。

实现拆解

1. 核心逻辑调整：在 python/sglang/srt/server_args.py 的 _handle_multimodal_feature_transport() 自动策略分支中，将条件由 is_cuda() and self.nnodes == 1 and self.disaggregation_mode == "null" 扩展为 self.get_model_config().is_multimodal and ...，确保只有多模态模型才进入 cuda_ipc 自动分支。
2. 参数文档同步：更新 mm_feature_transport 参数的 help 描述，从 “single-node CUDA deployments (without disaggregation) use cuda_ipc” 改为 “multimodal models on single-node CUDA deployments (without disaggregation) use cuda_ipc”，明确自动解析的目标对象。
3. 测试配套：在 test/registered/unit/server_args/test_server_args.py 的 TestMultimodalFeatureTransport 中新增 _set_model_type 静态方法，用 SimpleNamespace(is_multimodal=...) 注入 model_config 以绕开真实模型加载；新增 3 个测试分别验证纯文本模型保持 CPU、多模态模型自动切到 CUDA IPC、language_only=True 但模型能力为多模态时仍走 CUDA IPC。测试中清空 SGLANG_USE_CUDA_IPC_TRANSPORT 并使用 patch.dict 控制环境，确保走默认逻辑；纯文本模型场景还用 assertNoLogs 验证不产生 INFO 日志。

关键文件：

• python/sglang/srt/server_args.py（模块 参数配置；类别 source；类型 core-logic；符号 _handle_multimodal_feature_transport）: 核心逻辑变更：自动传输策略分支加入 is_multimodal 判定，防止纯文本模型误选 CUDA IPC；同时更新 mm_feature_transport 参数帮助文本。
• test/registered/unit/server_args/test_server_args.py（模块 参数测试；类别 test；类型 test-coverage；符号 _set_model_type, test_default_transport_is_cpu_for_text_only_model, test_default_transport_is_cuda_ipc_for_multimodal_model, test_default_transport_is_cuda_ipc_for_language_only_model）: 测试覆盖：新增 _set_model_type 辅助方法及三个默认传输测试，验证纯文本、多模态和 language_only 组合下的自动解析结果，防止回归。

关键符号：_handle_multimodal_feature_transport, _set_model_type

关键源码片段

python/sglang/srt/server_args.py

核心逻辑变更：自动传输策略分支加入 is_multimodal 判定，防止纯文本模型误选 CUDA IPC；同时更新 mm_feature_transport 参数帮助文本。

        # _handle_multimodal_feature_transport 中的自动解析分支
        # 只有多模态模型才自动启用 CUDA IPC；纯文本模型没有多模态处理器，
        # 即使启用也不会分配池，反而会留下“1 GiB 保留”的误导日志。
        elif (
            self.get_model_config().is_multimodal # 模型能力：来自 ModelConfig.is_multimodal
            and is_cuda() # CUDA IPC 池仅 NVIDIA 平台可用
            and self.nnodes == 1 # IPC 句柄仅节点内有效，多节点走 CPU
            and self.disaggregation_mode == "null" # PD 解聚场景也走 CPU
        ):
            requested_transport = "cuda_ipc"
            logger.info(
                "Multimodal feature transport auto-resolved to cuda_ipc "
                "(single-node CUDA). Pass --mm-feature-transport=cpu to "
                "opt out."
            )
        else:
            requested_transport = "cpu"

test/registered/unit/server_args/test_server_args.py

测试覆盖：新增 _set_model_type 辅助方法及三个默认传输测试，验证纯文本、多模态和 language_only 组合下的自动解析结果，防止回归。

class TestMultimodalFeatureTransport(CustomTestCase):
    @staticmethod
    def _set_model_type(server_args, *, is_multimodal):
        # 避免单测真实加载模型配置，直接注入 model_config
        # 让自动策略能读到 is_multimodal 能力位。
        server_args.model_config = SimpleNamespace(is_multimodal=is_multimodal)
​
    @patch("sglang.srt.server_args.is_cuda", return_value=True)
    def test_default_transport_is_cpu_for_text_only_model(self, _mock_is_cuda):
        # 纯文本模型即使在单节点 CUDA 下，也不应自动切到 CUDA IPC。
        server_args = ServerArgs(model_path="dummy")
        self._set_model_type(server_args, is_multimodal=False)
​
        with patch.dict(os.environ, {}, clear=False):
            envs.SGLANG_USE_CUDA_IPC_TRANSPORT.clear()
            # assertNoLogs 确认纯文本模型分支不产生 INFO 日志，
            # 避免用户看到误导性的“auto-resolved to cuda_ipc”。
            with self.assertNoLogs(server_args_module.logger, level="INFO"):
                server_args._handle_multimodal_feature_transport()
​
        self.assertEqual(server_args.mm_feature_transport, "cpu")
        self.assertFalse(envs.SGLANG_USE_CUDA_IPC_TRANSPORT.get())

评论区精华

该 PR 没有 review 评论，b8zhong 直接 APPROVED。核心设计权衡来自 PR body：旧实现依赖“池只有在多模态处理器存在时才分配”的惰性事实来避免实际资源占用，但会留下“1 GiB 保留”的误导日志；新实现把能力检查提前到自动策略判定处，使配置状态与真实情况一致，并用测试巩固这一契约。

• 暂无高价值评论线程

风险与影响

• 风险：
  1. model_config 加载时机依赖：_handle_multimodal_feature_transport() 现在调用 self.get_model_config()，若该函数在 model_config 尚未初始化时被调用，可能导致异常或拿到空配置；现有单测通过手工设置 model_config 规避了真实启动顺序，缺少真实启动路径的集成验证。建议确认所有调用点都发生在模型配置加载之后。
  2. 自动模式行为变更：纯文本部署在自动模式下 mm_feature_transport 会从 cuda_ipc 变为 cpu，SGLANG_USE_CUDA_IPC_TRANSPORT 也不再被设置；若外部脚本或监控依赖该状态值，可能观察到变化。不过由于池本来就不会分配，实际运行资源无差异。
  3. 回归面：显式指定 transport、legacy 环境变量、多模态模型、PD 解聚与多节点路径均保持不变，加之测试覆盖了主要组合，回归风险可控。
     - 影响：影响范围集中在 server args 解析阶段：使用自动模式且运行纯文本模型的部署，将不再出现“auto-resolved to cuda_ipc”的日志和 1 GiB 保留提示，mm_feature_transport 正确显示为 cpu；多模态模型用户无感知。对团队而言，该修复减少了因误导性日志产生的排查成本，也让自动配置逻辑与模型能力保持一致。
     - 风险标记：自动模式行为变更, model_config 加载时机依赖

关联脉络

• PR #30904 Add multimodal feature transport: 本 PR 的传输机制基础，PR body 明确引用其引入了 mm_feature_transport。
• PR #32541 Enable automatic CUDA IPC: 引入单节点 CUDA 自动启用 CUDA IPC 的逻辑，本 PR 修正其对纯文本模型的误选。