执行摘要

• 一句话：修复s390x构建以支持Torch 2.11，并更新相关文档。
• 推荐动作：对于从事CPU支持或跨平台构建的工程师，建议精读此PR以了解如何处理特定架构的差异。关注csrc/cpu/utils.hpp中的L2缓存检测设计，以及Dockerfile中的依赖管理策略。

功能与动机

PR body中详细描述了在s390x平台上出现的两个主要问题：一是由于protobuf导致的静默崩溃，二是在推理调用时因L2缓存查找失败而引发的IndexError。错误堆栈显示在CPU注意力元数据构建过程中，cpu_attn_get_scheduler_metadata函数访问无序映射失败，导致构建和推理中断。

实现拆解

1. 核心工具函数增强：在csrc/cpu/utils.hpp中，为s390x架构添加了get_available_l2_size函数的分支处理，通过at::cpu::get_cpu_capabilities()获取缓存大小，失败时回退到sysconf系统调用，并设置默认值256KB，确保L2缓存检测的健壮性。
2. CPU注意力实现扩展：在csrc/cpu/cpu_attn_impl.hpp中，在AttentionMetadata::print方法中添加了ISA::VXE枚举 case，以支持s390x的VXE指令集，提升硬件兼容性。
3. Docker构建基础设施更新：修改docker/Dockerfile.s390x，包括固定Apache Arrow版本至maint-19.0.1、升级numactl至v2.0.19、调整setuptools版本以避免兼容性问题，并修复构建路径错误。
4. 安装文档同步：更新docs/getting_started/installation/cpu.s390x.inc.md，添加对新数据类型（BF16、FP16）的支持说明，更新依赖列表和构建步骤，确保用户指南的准确性。
5. 依赖管理调整：在requirements/common.txt中修改llguidance的平台标记，移除s390x，但根据review反馈可能需进一步处理以避免依赖缺失。
   本次改动不包含测试文件变更，建议后续添加s390x特定测试以验证功能。

关键文件：

• csrc/cpu/utils.hpp（模块 CPU工具层；类别 source；类型 core-logic；符号 get_available_l2_size）: 核心工具函数文件，修复s390x上的L2缓存检测失败问题，确保推理过程中的缓存查找稳定。
• docker/Dockerfile.s390x（模块 Docker构建；类别 infra；类型 infrastructure）: s390x平台专用Dockerfile，更新依赖版本和构建步骤以修复构建问题，提升跨平台构建可靠性。
• csrc/cpu/cpu_attn_impl.hpp（模块 CPU注意力；类别 source；类型 core-logic；符号 AttentionMetadata::print）: CPU注意力实现文件，添加VXE指令集支持以兼容s390x硬件，提升调试信息完整性。
• docs/getting_started/installation/cpu.s390x.inc.md（模块 文档；类别 docs；类型 documentation）: 安装文档文件，更新s390x平台的支持说明和依赖列表，确保用户指南准确。
• requirements/common.txt（模块 依赖管理；类别 docs；类型 documentation）: 依赖管理文件，调整llguidance的平台标记，影响s390x平台的依赖安装。

关键符号：get_available_l2_size, AttentionMetadata::print

关键源码片段

csrc/cpu/utils.hpp

核心工具函数文件，修复s390x上的L2缓存检测失败问题，确保推理过程中的缓存查找稳定。

inline int64_t get_available_l2_size() {
#if defined(__s390x__)
  static int64_t size = []() {
    uint32_t l2_cache_size = 0;
    auto caps = at::cpu::get_cpu_capabilities();
    auto it = caps.find("l2_cache_size");
    if (it != caps.end()) {
      l2_cache_size = static_cast<uint32_t>(it->second.toInt()); // 从能力映射中提取缓存大小
    }
    if (l2_cache_size == 0) {
      long sys_l2 = sysconf(_SC_LEVEL2_CACHE_SIZE); // 回退到系统调用获取 L2 缓存大小
      if (sys_l2 > 0) {
        l2_cache_size = static_cast<uint32_t>(sys_l2);
      }
    }
    if (l2_cache_size == 0) {
      l2_cache_size = 256 * 1024; // 设置默认值 256KB，确保有备无患
    }
    return static_cast<int64_t>(l2_cache_size) >> 1; // 使用 50% 的 L2 缓存作为可用大小
  }();
  return size;
#else
  static int64_t size = []() {
    auto caps = at::cpu::get_cpu_capabilities();
    const uint32_t l2_cache_size = caps.at("l2_cache_size").toInt(); // 非 s390x 平台直接访问
    return l2_cache_size >> 1; // 使用 50% 的 L2 缓存
  }();
  return size;
#endif
}

docker/Dockerfile.s390x

s390x平台专用Dockerfile，更新依赖版本和构建步骤以修复构建问题，提升跨平台构建可靠性。

# 构建 Apache Arrow 的示例步骤，展示关键修复
RUN --mount=type=cache,target=/root/.cache/uv \
  git clone https://github.com/apache/arrow.git -b maint-19.0.1 && \
  cd arrow/cpp && \  # 修复路径：原为 cd cpp，现改为 cd arrow/cpp，避免构建失败
  mkdir release && cd release && \
  cmake -DCMAKE_BUILD_TYPE=Release \
  # ... 其他配置继续

评论区精华

gemini-code-assist[bot]在review中指出了三个关键问题：一是Dockerfile中cd cpp路径错误，应改为cd arrow/cpp以避免构建失败；二是从requirements中移除s390x平台标记可能导致源码安装时llguidance依赖缺失；三是文档中依赖列表不完整，缺少llguidance和pyarrow。这些讨论强调了构建正确性和依赖完整性的重要性，但评论未显示是否已全部修复，存在未解决的疑虑。

• Dockerfile构建路径错误 (correctness): 评论未显示是否修复，可能存在构建失败风险。
• llguidance依赖平台标记移除 (design): 未解决，需确保依赖完整性。
• 文档依赖列表不完整 (documentation): 未解决，文档需要更新。

风险与影响

• 风险：技术风险包括：
  1) 构建失败风险：Dockerfile中的路径错误如果未修复，将导致构建中断；
  2) 依赖缺失风险：移除s390x标记可能使非Docker环境下的源码安装缺少llguidance依赖，影响功能完整性；
  3) 兼容性问题：新增的s390x特定逻辑可能在其他架构上引入意外行为，例如L2缓存检测的默认值设置可能不适用所有场景；
  4) 性能影响：L2缓存大小检测不准确可能影响CPU注意力性能；
  5) 回归风险：修改核心CPU代码可能影响现有CPU功能的正确性。
  • 影响：对用户的影响：s390x平台的用户现在能够更稳定地构建和运行vLLM，文档提供了更清晰的指导。对系统的影响：增强了CPU注意力模块对IBM Z硬件的支持，可能改善推理性能，但增加了代码维护复杂度。对团队的影响：提升了项目的跨平台兼容性，但需持续监控构建和依赖问题。
  • 风险标记：构建路径错误, 依赖缺失, 平台兼容性风险

关联脉络

• PR #39932 [FlashAttention] Don't overwrite flash_attn_interface.py when installing precompiled: 同样涉及构建和安装过程的修复，共享基础设施改进主题，有助于理解跨PR的构建优化趋势。