执行摘要

• 一句话：精简 DeepGEMM 注释并添加集成说明
• 推荐动作：对于关注 DeepGEMM 集成的开发人员，可以阅读集成说明和 TODO 以了解未来架构演进方向；对于普通开发者无需特别关注。

功能与动机

继 PR #41516 合并后，review 要求补充 DeepGEMM 集成的设计背景和待办事项，以提高长期可维护性。PR body 明确说明 'asking for background + TODOs on the DeepGEMM integration'。

实现拆解

1. 添加集成说明块：在 cmake/external_projects/deepgemm.cmake 的 if(DEEPGEMM_ARCHS) 顶部插入一段注释，解释 DeepGEMM 采用按 Python 版本构建的原因（PYBIND11_MODULE 链接私有 CPython 符号，无法生成单个 _C.abi3.so），并列出两个未来清理方向（改用 TORCH_LIBRARY+shim 绑定、AOT 编译 CUDA 内核），TODO 关联追踪 Issue #42431。
2. 精简内联文档：对 tools/build_deepgemm_C.py、tools/setup_deepgemm_pythons.sh、docker/Dockerfile 中的冗长逐行叙述进行压缩，保留关键设计决策，移除多余的过程描述。
3. 更新 TODO 引用：第二提交将占位符 #TBD 替换为真实 Issue 编号 #42431。

关键文件：

• tools/build_deepgemm_C.py（模块 构建脚本；类别 source；类型 documentation）: 作为 DeepGEMM _C 扩展构建脚本，其文档字符串和内联注释被精简，删除了冗余的过程描述，强调了驱动构建的关键设计决策。
• cmake/external_projects/deepgemm.cmake（模块 CMake 配置；类别 other；类型 documentation）: 核心变更文件，新增集成说明块，集中解释按 Python 构建的原因和未来清理方向，并修剪了内联叙述注释。
• tools/setup_deepgemm_pythons.sh（模块 构建脚本；类别 other；类型 documentation）: DeepGEMM 多 Python 运行时环境准备脚本，注释被大幅精简，去除逐个步骤的说明，保留关键前提和用法。
• docker/Dockerfile（模块 Docker 部署；类别 infra；类型 documentation）: Docker 构建文件中 DeepGEMM 相关注释被简化，并引导读者参考 deepgemm.cmake 的整体说明。

关键符号：未识别

关键源码片段

cmake/external_projects/deepgemm.cmake

核心变更文件，新增集成说明块，集中解释按 Python 构建的原因和未来清理方向，并修剪了内联叙述注释。

# DeepGEMM integration notes
# --------------------------
# We vendor DeepGEMM into vllm/third_party/deep_gemm/ and bundle a
# `_C.cpython-X.Y-*.so` for every CPython in `requires-python`. The
# per-Python build is delegated to tools/build_deepgemm_C.py.
#
# Why per-Python: DeepGEMM's binding uses PYBIND11_MODULE, which links
# private CPython symbols — a single `_C.abi3.so` is not viable today
# (see #41476 / #41512 for the failed attempt).
#
# TODOs (tracked in vllm-project/vllm#42431):
# - Replace DeepGEMM's pybind11 binding with a TORCH_LIBRARY + shim
# binding (cf. vllm-flash-attention/csrc/common/pytorch_shim.h) to
# collapse to one `_C.abi3.so`. Needs either an upstream change or
# a maintained binding fork in vLLM.
# - AOT-compile DeepGEMM's CUDA kernels instead of runtime JIT to drop
# the vendored CUTLASS/CCCL headers and the CUDA-toolkit-at-runtime
# requirement.

评论区精华

无实质性技术讨论。自动化 code review 机器人未提出具体反馈，Harry-Chen 直接批准（"LGTM. This will help a lot, thanks!"）。

• 暂无高价值评论线程

风险与影响

• 风险：纯注释变更，无行为变化，风险极低。未来 TODO 引用的 tracking issue 需确保有效（已替换为 #42431）。
• 影响：仅影响构建系统的可读性和可维护性，对运行时行为和用户接口无影响。
• 风险标记：暂无

关联脉络

• PR #41516 [Build] Build bundled DeepGEMM _C per-Python so the wheel imports on every CPython: 本 PR 是 #41516 的后续清理，响应其 review 反馈。