企业官网建设流程全解析

• 科学计算
• 数据分析

导读

本文深入解析 NumPy 的 CPU dispatcher（CPU 调度器）——一套不依赖任何编译器私有扩展、可跨编译器工作的多源编译（multi-source compiling）基础设施。文章以--cpu-baseline/--cpu-dispatch两个构建参数为起点，完整梳理从配置、环境探测、优化验证、主配置头生成，到 dispatch-able 源（可调度源文件）识别、解析、包装与运行时符号分派的全部流程，并给出可直接参考的 C 宏级代码示例。读完本文，你将掌握 NumPy 如何在编译期为同一份源码生成针对不同指令集（SSE/AVX/VSX/ASIMD 等）的多个内核，并在运行时探测 CPU 能力、自动选取最合适的内核执行——这正是 NumPy 在 x86、IBM/Power、ARM 等平台上获得稳定性能的核心机制。

一、总览：三层优化架构中的调度器位置

NumPy 的 SIMD 优化在 doc/source/reference/simd/index.rst 中被描述为三个层次：

1. 编写层：代码使用通用内建函数（universal intrinsics，即一组类型、宏和函数）编写，通过守卫（guards）映射到各受支持的指令集，仅在编译器识别它们时才启用。这样同一功能可生成多个内核，第一个内核对应最小（baseline）CPU 特性，其余内核对应附加（dispatched）CPU 特性。
2. 编译层：通过 CPU 构建选项定义要支持的最小与附加特性（取决于用户选择与编译器支持），叠加平台/架构内建函数，编译出多个内核。
3. 运行导入层：导入 NumPy 时探测 CPU 所支持的特性集合，通过指针获取最合适的内核并调用。

而 CPU dispatcher 正是“编译层”与“运行层”之间的枢纽：它负责把同一份源文件编译成多个内核，并为每个内核打上可识别的符号后缀，供运行时调度。

以下架构图（doc/source/reference/figures/opt-infra.png）直观展示了整个多源编译基础设施的两条路径：优化启用时走“Fetch dispatch-able sources → Handling → Compiling & linking”的完整链路；优化禁用（--disable-optimization）时则只需初始化基础设施并走简化的生成流程；两条路径最终都会经过 Cache 环节以加速重建。

二、核心思想：一份源码，多次编译

NumPy dispatcher 基于多源编译（multi-source compiling）思想：取某一源文件，用不同的编译器标志以及不同的C宏定义对它编译多次，这些宏定义会改变代码路径，从而为每个编译产物按所需优化开启特定指令集，最后将产出的目标文件链接在一起。

这一机制具备两个关键特性：

• 支持所有编译器：不要求任何编译器私有扩展（如 GCC 的targetattribute 或#pragma），只依赖标准的预处理与多目标编译；
• 增加若干编译步骤：相对普通编译，它多出了配置、探测、验证、生成头文件等步骤，下文将逐一展开。

该机制覆盖 x86、IBM/Power、ARM 等主流架构，且全部在 numpy/_core/src/common 的 C 源码中落地实现。

三、五个构建步骤详解

1. 配置（Configuration）

构建前，用户通过两个命令行参数指定所需优化：

在 meson 构建体系下，这两个参数通过-Csetup-args传入，例如在 doc/source/building/cpu_simd.rst 中给出的场景：

# 检测并使用本机全部 CPU 特性 $ python -m pip install . -Csetup-args=-Dcpu-baseline="native" -Csetup-args=-Dcpu-dispatch="none" # 使用无任何 SIMD 优化的低 baseline（适用于非常老的 CPU） $ python -m pip install . -Csetup-args=-Dcpu-baseline="none"

2. 发现环境（Discovering the environment）

检查编译器与平台架构，并缓存部分中间结果以加速后续重建。这正是架构图中Cache环节的意义——配置未变化时跳过重复的探测与生成工作。

3. 验证请求的优化（Validating the requested optimizations）

将请求的优化逐项交给编译器做实际测试，确认编译器能否根据请求生成对应指令集，从而筛选出最终可用的优化子集。

4. 生成主配置头（Generating the main configuration header）

验证通过后，生成主配置头_cpu_dispatch.h，其中包含：

• 所有通过验证的必需优化的宏定义与对应指令集头文件（#include）；
• 用于定义 NumPy Python 层模块属性__cpu_baseline__和__cpu_dispatch__的额外 C 宏。

原文档给出了一个在 x86 机器上由 gcc 动态生成的示例头文件（假设编译器支持--cpu-baseline="sse sse2 sse3"与--cpu-dispatch="ssse3 sse41"），该文件应位于 numpy/_core/src/common/_cpu_dispatch.h：

// The header should be located at numpy/numpy/_core/src/common/_cpu_dispatch.h /**NOTE ** C definitions prefixed with "NPY_HAVE_" represent ** the required optimizations. ** ** C definitions prefixed with 'NPY__CPU_TARGET_' are protected and ** shouldn't be used by any NumPy C sources. */ /******* baseline features *******/ /** SSE **/ #define NPY_HAVE_SSE 1 #include <xmmintrin.h> /** SSE2 **/ #define NPY_HAVE_SSE2 1 #include <emmintrin.h> /** SSE3 **/ #define NPY_HAVE_SSE3 1 #include <pmmintrin.h> /******* dispatch-able features *******/ #ifdef NPY__CPU_TARGET_SSSE3 /** SSSE3 **/ #define NPY_HAVE_SSSE3 1 #include <tmmintrin.h> #endif #ifdef NPY__CPU_TARGET_SSE41 /** SSE41 **/ #define NPY_HAVE_SSE41 1 #include <smmintrin.h> #endif

该示例揭示了宏的两种前缀约定：

• NPY_HAVE_前缀：代表已开启的必需优化；
• NPY__CPU_TARGET_前缀：受保护的内部宏，任何 NumPy C 源文件都不应直接使用。

Baseline features（基线特性）

Baseline features 是通过--cpu-baseline配置的最小必需优化集合。它们在头文件中没有预处理守卫（preprocessor guards），始终开启，可在任何源码中使用。这意味着 NumPy 的基础设施会把这些基线特性的编译器标志传递给所有源文件（dispatch-able 源除外，它们有特殊处理方式）。

一个需要特别关注的问题：如果构建时指定了某些 baseline 特性，但运行时机器连这些特性都不支持怎么办？——NumPy 模块在加载期间会有一个验证步骤来检测这种情况：一旦发现机器不支持编译时假定的基线特性，就抛出 Python 运行时错误告知用户。这样做的目的是防止 CPU 执行非法指令（illegal instruction）而触发段错误（segfault）。

Dispatch-able features（可调度特性）

Dispatch-able features 是通过--cpu-dispatch配置的附加优化集合。它们默认不被激活，总是被NPY__CPU_TARGET_前缀的宏所守卫，并且这些宏只在 dispatch-able 源内部被启用。

5. Dispatch-able 源与配置语句

什么是 dispatch-able 源？

Dispatch-able 源是特殊的C文件，可以被多次编译，每次使用不同的编译器标志和不同的C宏定义。这些宏改变代码路径，从而为每个编译对象按“配置语句”（configuration statements）开启特定指令集。配置语句必须声明在C 注释(/**/)中，并以特殊标记@targets开头，位于每个 dispatch-able 源文件的顶部。

同时，如果通过命令行参数--disable-optimization禁用了优化，dispatch-able 源会被当作普通 C 源处理。

配置语句（Configuration statements）

配置语句是组合在一起的关键字，用于确定 dispatch-able 源所需的优化。例如：

/*@targets avx2 avx512f vsx2 vsx3 asimd asimdhp */ // C code

关键字主要代表通过--cpu-dispatch配置的附加优化，但也可以表示其他选项：

• 目标组（Target groups）：预先配置好的配置语句，用于从 dispatch-able 源外部管理所需优化；
• 策略（Policies）：用于改变默认行为或强制编译器执行特定操作的选项集合（例如影响回调调用排序的$keep_sort策略）；
• "baseline"：一个唯一关键字，代表通过--cpu-baseline配置的最小优化。

基础设施处理 dispatch-able 源的四个步骤

• (A) 识别（Recognition）：与源模板（source templates）和 F2PY 类似，dispatch-able 源需要特殊扩展名来标记：C 文件用*.dispatch.c，C++ 文件用*.dispatch.cpp或*.dispatch.cxx。注意：C++ 目前尚未支持。在仓库中可以看到这类文件的实际分布，例如 numpy/_core/src/umath/loops_unary_fp_le.dispatch.c.src 等。

• (B) 解析与验证（Parsing and validating）：对上一步筛选出的 dispatch-able 源逐个解析并验证其配置语句，以确定各自所需的优化。

• (C) 包装（Wrapping）：这是 NumPy 基础设施采用的、已被证明足够灵活的方法——为每个附加优化创建一个临时C源，该临时源包含相应 C 宏的声明，并通过C 预处理指令#include引入被包装的源文件。以 AVX512F 为例，生成的临时源大致如下：

/* * this definition is used by NumPy utilities as suffixes for the * exported symbols */ #define NPY__CPU_TARGET_CURRENT AVX512F /* * The following definitions enable * definitions of the dispatch-able features that are defined within the main * configuration header. These are definitions for the implied features. */ #define NPY__CPU_TARGET_SSE #define NPY__CPU_TARGET_SSE2 #define NPY__CPU_TARGET_SSE3 #define NPY__CPU_TARGET_SSSE3 #define NPY__CPU_TARGET_SSE41 #define NPY__CPU_TARGET_POPCNT #define NPY__CPU_TARGET_SSE42 #define NPY__CPU_TARGET_AVX #define NPY__CPU_TARGET_F16C #define NPY__CPU_TARGET_FMA3 #define NPY__CPU_TARGET_AVX2 #define NPY__CPU_TARGET_AVX512F // our dispatch-able source #include "/the/absolute/path/of/hello.dispatch.c"

注意其中NPY__CPU_TARGET_CURRENT被 NumPy 工具用作导出符号的后缀，而一连串NPY__CPU_TARGET_*定义是主配置头中 dispatch-able 特性的“蕴含特性”（implied features）——即 AVX512F 隐含支持的较低级指令集。

• (D) 生成可调度配置头（Dispatch-able configuration header）：基础设施为每个 dispatch-able 源生成一个配置头，主要包含两个抽象 C 宏，用于标识生成的对象，使任何 C 源都能对生成对象中的符号进行运行时调度，同时用于前向声明。

生成的配置头以 dispatch-able 源文件名去除扩展名后替换为.h命名。假设有源文件hello.dispatch.c：

// hello.dispatch.c /*@targets baseline sse42 avx512f */ #include <stdio.h> #include "numpy/utils.h" // NPY_CAT, NPY_TOSTR #ifndef NPY__CPU_TARGET_CURRENT // wrapping the dispatch-able source only happens to the additional optimizations // but if the keyword 'baseline' provided within the configuration statements, // the infrastructure will add extra compiling for the dispatch-able source by // passing it as-is to the compiler without any changes. #define CURRENT_TARGET(X) X #define NPY__CPU_TARGET_CURRENT baseline // for printing only #else // since we reach to this point, that's mean we're dealing with // the additional optimizations, so it could be SSE42 or AVX512F #define CURRENT_TARGET(X) NPY_CAT(NPY_CAT(X, _), NPY__CPU_TARGET_CURRENT) #endif // Macro 'CURRENT_TARGET' adding the current target as suffix to the exported symbols, // to avoid linking duplications, NumPy already has a macro called // 'NPY_CPU_DISPATCH_CURFX' similar to it, located at // numpy/numpy/_core/src/common/npy_cpu_dispatch.h // NOTE: we tend to not adding suffixes to the baseline exported symbols void CURRENT_TARGET(simd_whoami)(const char *extra_info) { printf("I'm " NPY_TOSTR(NPY__CPU_TARGET_CURRENT) ", %s\n", extra_info); }

将hello.dispatch.c挂到源码树后，基础设施会生成一个名为hello.dispatch.h的临时配置头，任何源文件都可以引用它，其内容大致如下：

#ifndef NPY__CPU_DISPATCH_EXPAND_ // To expand the macro calls in this header #define NPY__CPU_DISPATCH_EXPAND_(X) X #endif // Undefining the following macros, due to the possibility of including config headers // multiple times within the same source and since each config header represents // different required optimizations according to the specified configuration // statements in the dispatch-able source that derived from it. #undef NPY__CPU_DISPATCH_BASELINE_CALL #undef NPY__CPU_DISPATCH_CALL // nothing strange here, just a normal preprocessor callback // enabled only if 'baseline' specified within the configuration statements #define NPY__CPU_DISPATCH_BASELINE_CALL(CB, ...) \ NPY__CPU_DISPATCH_EXPAND_(CB(__VA_ARGS__)) // 'NPY__CPU_DISPATCH_CALL' is an abstract macro is used for dispatching // the required optimizations that specified within the configuration statements. // // @param CHK, Expected a macro that can be used to detect CPU features // in runtime, which takes a CPU feature name without string quotes and // returns the testing result in a shape of boolean value. // NumPy already has macro called "NPY_CPU_HAVE", which fits this requirement. // // @param CB, a callback macro that expected to be called multiple times depending // on the required optimizations, the callback should receive the following arguments: // 1- The pending calls of @param CHK filled up with the required CPU features, // that need to be tested first in runtime before executing call belong to // the compiled object. // 2- The required optimization name, same as in 'NPY__CPU_TARGET_CURRENT' // 3- Extra arguments in the macro itself // // By default the callback calls are sorted depending on the highest interest // unless the policy "$keep_sort" was in place within the configuration statements // see "Dive into the CPU dispatcher" for more clarification. #define NPY__CPU_DISPATCH_CALL(CHK, CB, ...) \ NPY__CPU_DISPATCH_EXPAND_(CB((CHK(AVX512F)), AVX512F, __VA_ARGS__)) \ NPY__CPU_DISPATCH_EXPAND_(CB((CHK(SSE)&&CHK(SSE2)&&CHK(SSE3)&&CHK(SSSE3)&&CHK(SSE41)), SSE41, __VA_ARGS__))

这个头文件揭示了运行时调度的核心模式：

• NPY__CPU_DISPATCH_BASELINE_CALL(CB, ...)：仅当配置语句中出现baseline关键字时才启用的普通预处理回调；
• NPY__CPU_DISPATCH_CALL(CHK, CB, ...)：抽象分派宏。CHK期望是能在运行时探测 CPU 特性的宏（NumPy 已有NPY_CPU_HAVE满足此要求）；CB是回调宏，会被按所需优化多次调用，依次接收“运行时 CPU 特性检查表达式”、“优化名”（与NPY__CPU_TARGET_CURRENT一致）和宏自身的额外参数；
• 默认情况下回调调用按“最高收益优先”（highest interest）排序，除非配置语句中启用了$keep_sort策略。

以生成的配置头为基础，可以构造完整的运行时调用示例：

// NOTE: The following macros are only defined for demonstration purposes only. // NumPy already has a collections of macros located at // numpy/numpy/_core/src/common/npy_cpu_dispatch.h, that covers all dispatching // and declarations scenarios. #include "numpy/npy_cpu_features.h" // NPY_CPU_HAVE #include "numpy/utils.h" // NPY_CAT, NPY_EXPAND // An example for setting a macro that calls all the exported symbols at once // after checking if they're supported by the running machine. #define DISPATCH_CALL_ALL(FN, ARGS) \ NPY__CPU_DISPATCH_CALL(NPY_CPU_HAVE, DISPATCH_CALL_ALL_CB, FN, ARGS) \ NPY__CPU_DISPATCH_BASELINE_CALL(DISPATCH_CALL_BASELINE_ALL_CB, FN, ARGS) // The preprocessor callbacks. // The same suffixes as we define it in the dispatch-able source. #define DISPATCH_CALL_ALL_CB(CHECK, TARGET_NAME, FN, ARGS) \ if (CHECK) { NPY_CAT(NPY_CAT(FN, _), TARGET_NAME) ARGS; } #define DISPATCH_CALL_BASELINE_ALL_CB(FN, ARGS) \ FN NPY_EXPAND(ARGS); // An example for setting a macro that calls the exported symbols of highest // interest optimization, after checking if they're supported by the running machine. #define DISPATCH_CALL_HIGH(FN, ARGS) \ if (0) {} \ NPY__CPU_DISPATCH_CALL(NPY_CPU_HAVE, DISPATCH_CALL_HIGH_CB, FN, ARGS) \ NPY__CPU_DISPATCH_BASELINE_CALL(DISPATCH_CALL_BASELINE_HIGH_CB, FN, ARGS) // The preprocessor callbacks // The same suffixes as we define it in the dispatch-able source. #define DISPATCH_CALL_HIGH_CB(CHECK, TARGET_NAME, FN, ARGS) \ else if (CHECK) { NPY_CAT(NPY_CAT(FN, _), TARGET_NAME) ARGS; } #define DISPATCH_CALL_BASELINE_HIGH_CB(FN, ARGS) \ else { FN NPY_EXPAND(ARGS); } // NumPy has a macro called 'NPY_CPU_DISPATCH_DECLARE' can be used // for forward declarations any kind of prototypes based on // 'NPY__CPU_DISPATCH_CALL' and 'NPY__CPU_DISPATCH_BASELINE_CALL'. // However in this example, we just handle it manually. void simd_whoami(const char *extra_info); void simd_whoami_AVX512F(const char *extra_info); void simd_whoami_SSE41(const char *extra_info); void trigger_me(void) { // bring the auto-generated config header // which contains config macros 'NPY__CPU_DISPATCH_CALL' and // 'NPY__CPU_DISPATCH_BASELINE_CALL'. // it is highly recommended to include the config header before executing // the dispatching macros in case if there's another header in the scope. #include "hello.dispatch.h" DISPATCH_CALL_ALL(simd_whoami, ("all")) DISPATCH_CALL_HIGH(simd_whoami, ("the highest interest")) // An example of including multiple config headers in the same source // #include "hello2.dispatch.h" // DISPATCH_CALL_HIGH(another_function, ("the highest interest")) }

示例中的DISPATCH_CALL_ALL会依次调用所有满足运行时 CPU 特性检查的导出符号（simd_whoami_AVX512F、simd_whoami_SSE41与 baseline 的simd_whoami）；DISPATCH_CALL_HIGH则用if/else if/else链只选择收益最高且当前机器支持的那一个。宏名中NPY_CAT(NPY_CAT(FN, _), TARGET_NAME)的作用正是把配置头中的目标名拼接到函数名上，与 dispatch-able 源里CURRENT_TARGET的加后缀逻辑一一对应，从而避免链接重复符号。在实际的 NumPy 实现中，这些场景已被 numpy/_core/src/common/npy_cpu_dispatch.h 中现成的宏集合（如NPY_CPU_DISPATCH_CURFX、NPY_CPU_DISPATCH_DECLARE等）所覆盖。

四、运行时验证与安全保证

回到 baseline 特性的运行时问题：编译时假定的 baseline 特性如果在运行时机器上缺失，会产生灾难性后果——编译产物中由编译器基于命令行标志自动向量化（auto-vectorized）的代码一旦被执行到，CPU 会触发非法指令错误并导致段错误。为此，NumPy 在模块加载时内置了验证步骤，通过探测实际 CPU 特性并与编译期 baseline 对比，在不匹配时主动抛出 Python 运行时错误而非让进程崩溃。这一设计贯穿于 numpy/_core/src/common/npy_cpu_features.c 等底层实现中，也是__cpu_baseline__/__cpu_dispatch__两个模块属性得以公开暴露的基础。

五、小结：从构建参数到运行时调度的完整链路

把五个步骤串联起来，NumPy 的 CPU dispatcher 全流程可以概括为：

1. 用户通过--cpu-baseline与--cpu-dispatch声明优化意图；
2. 构建系统探测编译器与平台环境（并缓存中间结果）；
3. 将请求的优化交给编译器逐一验证，剔除不支持的项；
4. 生成主配置头_cpu_dispatch.h，固化NPY_HAVE_*（baseline，无守卫、始终开启）与NPY__CPU_TARGET_*（可调度，仅在 dispatch-able 源中启用）两类宏；
5. 识别*.dispatch.c源，解析其@targets配置语句，通过“包装 +#include”为每个附加优化生成独立编译单元，并为每个 dispatch-able 源生成含NPY__CPU_DISPATCH_CALL/NPY__CPU_DISPATCH_BASELINE_CALL的配置头；
6. 运行时，NPY_CPU_HAVE探测实际 CPU 特性，调度宏按收益优先顺序选出最合适的内核符号并调用；模块加载时对 baseline 做一致性校验，防止非法指令段错误。

这套机制让 NumPy 能够在保持二进制可移植性的同时，为不同 CPU 动态启用尽可能新的指令集（如 x86 上默认以 SSE4.2 为 baseline、运行时再启用 AVX2/AVX512），是理解 NumPy 高性能内核生成与调度的关键入口。更完整的构建参数与使用场景说明，可继续阅读 doc/source/building/cpu_simd.rst，以及描述其设计背景的 doc/neps/nep-0038-SIMD-optimizations.rst。

• 科学计算
• 数据分析