02 · 架构边界CUDA 为何是独立运行期模块一句话引擎不链接CUDA——它把 CUDA 层编成一个独立动态库运行期按固定顺序去找、去绑找到且可用就走 GPU找不到就让所有入口变成无害桩行为与引入前逐字节一致。这么做不是风格偏好而是 Windows 上 nvcc 与引擎的两套 C 运行期根本链接不到一起。前置建议先读 第 01 篇 · 阶段总览。环境x86-64 NVIDIA RTX 5090sm_120· 引擎用 MinGW/GCC 构建CUDA 层用 nvcc/MSVC 构建。一、问题与结论目标只有一句有 GPU 时用 GPU没有时行为不变。这个目标决定了边界必须是「运行期可选的独立模块」而不是「链接期依赖」。目标落地做法判定有 GPU 就用 GPU运行期加载vllm_cuda.dll/libvllm_cuda.so实测可用无 GPU 逐字节零回归未编入 / 模块缺失时所有入口退化成无害桩实测一致见 第 01 篇 阶段一版本错配不「半绑定」任一入口符号缺失即整体放弃missing 1设计约束能分离「初始化副作用」与「输出被真正使用」VLLM_CUDA_FORCE_CPU逃生阀实测见第四节二、背景为什么不直接链接这不是风格问题是 Windows 上的硬约束。约束引擎侧CUDA 侧编译器MinGW-w64 GCCnvccWindows 主机编译器只有 MSVC依赖头pthread.h/unistd.h/__int128MSVC 工具链C 运行期MinGW CRTMSVC CRT_Init_thread_*、ucrt两套 CRT 不能链接到一起。把 MSVC 编译的 CUDA 目标文件塞进 MinGW 二进制会拖入_Init_thread_*/ucrt链接期直接失败。纯 C 的模块边界让两边各用各的 CRT互不干扰。这与 NPU 后端的做法同源librknnrt也是运行期动态加载的树外运行时。CMakeLists.txt的注释把这条写死了CUDA 后端默认OFF只有 x86-64 宿主 独立 GPU 才允许ONaarch64(RK3588) 必须保持OFF。# 文件CMakeLists.txt节选 # 可选 NVIDIA CUDA 加速后端默认 OFF # nvcc 在 Windows 上必须用 MSVC 做宿主编译器而本引擎是 MinGW/GCC 构建 if(VLLM_CUDA) if(CMAKE_SYSTEM_PROCESSOR MATCHES aarch64|arm64|ARM64) message(FATAL_ERROR VLLM_CUDA targets an x86-64 host with a discrete GPU; keep VLLM_CUDAOFF on aarch64 (RK3588)) endif() ... add_compile_definitions(VLLM_HAVE_CUDA1) # 启用运行期加载器 endif()三、核心机制3.1 运行期加载与模块发现顺序引擎启动时按固定顺序去找这个模块1. $VLLM_CUDA_LIB 显式路径调试/多版本用 2. 可执行文件同目录 vllm_cuda.dll / libvllm_cuda.dll 3. 平台加载器搜索路径前两条落在vc_module_open()里先看环境变量再找可执行文件所在目录。第 2 条用vc_exe_dir()求目录——Windows 走GetModuleFileNameALinux 走readlink(/proc/self/exe)。/* 文件src/npu/cuda/vllm_cuda.cvc_module_open节选 */staticvc_lib_tvc_module_open(char*found,size_tcap){#ifdefined(_WIN32)constchar*names[2]{vllm_cuda.dll,libvllm_cuda.dll};#elseconstchar*names[2]{libvllm_cuda.so,vllm_cuda.so};#endifconstchar*envgetenv(VLLM_CUDA_LIB);if(envenv[0]){/* ① 显式路径 */vc_lib_thvc_lib_open(env);if(h){if(found)snprintf(found,cap,%s,env);returnh;}}chardir[1024];if(vc_exe_dir(dir,sizeof(dir))0){/* ② 可执行文件同目录 */for(inti0;i2;i){charp[1200];snprintf(p,sizeof(p),%s/%s,dir,names[i]);vc_lib_thvc_lib_open(p);if(h){if(found)snprintf(found,cap,%s,p);returnh;}}}for(inti0;i2;i){/* ③ 平台搜索路径 */vc_lib_thvc_lib_open(names[i]);if(h){if(found)snprintf(found,cap,%s,names[i]);returnh;}}returnNULL;}模块缺失是正常状态不是错误。vllm_cuda_init()找不到模块时写一条 notemodule not found ...; CPU path然后照常返回 0成功但不可用。3.2 入口点绑定与版本校验模块打开后逐个dlsym/GetProcAddress把vcuda_api_t里的函数指针绑上/* 文件src/npu/cuda/vllm_cuda.cvllm_cuda_init节选 */intmissing0;#defineVC_BIND(field,sym)\do{*(void**)(c-api.field)vc_lib_sym(c-lib,sym);\if(!c-api.field)missing1;}while(0)VC_BIND(dev_create,vcuda_dev_create);VC_BIND(dev_gemm_gw,vcuda_dev_gemm_gw);VC_BIND(dev_gemm_gw_f32,vcuda_dev_gemm_gw_f32);VC_BIND(dev_wcache_window,vcuda_dev_wcache_window);VC_BIND(dev_decode_run,vcuda_dev_decode_run);VC_BIND(dev_moe_preload,vcuda_dev_moe_preload);…任一入口缺失即整体放弃missing 1——这是版本不匹配的护栏。DLL 与 exe 版本错配时宁可不加速也不能半绑定运行导致未定义行为。这里还有一个关库的坑值得记一笔vllm_cuda_destroy()会无条件调用c-api.dev_destroy。如果某个失败分支只关了库却没清空c-api.*这些指针就指向已卸载的模块再一调就是访问违例实测0xC0000005。所以关库前先用vc_api_clear()把整张函数表清零。是否是否是否是 missing1否vllm_cuda_init 启动① VLLM_CUDA_LIB 命中VC_BIND 逐个绑定入口② exe 同目录 dll 命中③ 平台搜索路径 命中无害桩 返回 0 走 CPU任一符号缺失整体放弃 不半绑定available()1 走 GPU图 1模块发现 → 绑定 → 降级的全有或全无链。vc_module_open()依次找$VLLM_CUDA_LIB、可执行文件同目录的vllm_cuda.dll、平台搜索路径找到后VC_BIND逐个dlsym/GetProcAddress绑定入口任一符号缺失即missing 1整体放弃绝不半绑定找不到模块或绑定失败都退化成无害桩并返回 0只有available()1才走 GPU。3.3 透明降级契约vllm_cuda_init()永不失败调用方。设备不可用的所有情况无模块 / 无 GPU / 版本错配 / 显存不足统一通过vllm_cuda_available() 0表达且每个 offload 入口返回 00 调用方必须自己跑 CPU 路径1 已在 GPU 上完成。这条约定被后端所有层次严格遵守。最底层的设备层用的是相反约定0 成功翻译发生在宿主层——例如vllm_cuda_gemm_gw()/* 文件src/npu/cuda/vllm_cuda.cvllm_cuda_gemm_gw节选 */if(!c||!c-ok||!c-api.dev_gemm_gw)return0;if(cuda_force_cpu())return0;…if(2.0*(double)M*(double)N*(double)Kc-flops_threshold)return0;intrcc-api.dev_gemm_gw(c-dev,out,Aq,a_scale,Wq,b_scale,M,N,K,G,prec,wkey);return(rc0)?1:0;/* 设备层 0成功 → 宿主层 1已加速 */对外接口的这一契约在公共头文件里写得很直白include/npu/cuda/vllm_cuda.hReturns 1 if executed on the GPU (out is filled), 0 if the caller must run the CPU path (no device / below FLOPs threshold / unsupported shape / any CUDA error).而且「部分失败」永远不让out处于未定义状态——返回 0调用方按 CPU 内核把每个输出重算一遍。3.4 诊断逃生阀调试「结果不对」时最难分离的是两类原因初始化的副作用vsGPU 输出被真正使用。为此留了VLLM_CUDA_FORCE_CPU/* 文件src/npu/cuda/vllm_cuda.ccuda_force_cpu节选 *//* Diagnostic escape hatch: VLLM_CUDA_FORCE_CPU1 keeps the device initialized * but makes every offload fall back to the CPU - separates init side effect * from GPU output used as the source of a wrong result. */staticintcuda_force_cpu(void){constchar*egetenv(VLLM_CUDA_FORCE_CPU);return(ee[0]e[0]!0);}设备保持初始化显存分配、上传都照做但每个 offload 直接返回 0 走 CPU。于是配置结果结论VLLM_CUDA_FORCE_CPU1输出正确初始化无副作用问题在 GPU 计算/数值VLLM_CUDA_FORCE_CPU1输出也错初始化有副作用问题在状态污染3.5 编译开关与无害桩-DVLLM_HAVE_CUDA决定引入的是真实加载器还是无害桩/* 文件src/npu/cuda/vllm_cuda.c节选 */#else/* !VLLM_HAVE_CUDA *//* Harmless stubs: the engine runs exactly as before this backend existed. */structvllm_cuda_s{intunused;};intvllm_cuda_init(vllm_cuda_t**out,constvllm_cuda_cfg_t*cfg){(void)cfg;if(out)*outNULL;return0;/* success but unavailable: transparent fallback */}intvllm_cuda_available(constvllm_cuda_t*c){(void)c;return0;}未定义该宏VLLM_CUDAOFF、aarch64/RK3588 目标、或模块缺失时走同一套桩。构建侧由tools/build/build_x64.ps1 -Cuda先产出vllm_cuda.dll再以-DVLLM_HAVE_CUDA编入引擎# 文件tools/build/build_x64.ps1节选if($Cuda){$nvccGet-Commandnvcc-ErrorAction SilentlyContinue...$nvcc.Source-O2-arch$CudaArch-cudart static-shared-fmadfalse cudaD -Iinclude/npu/cuda src/npu/cuda/vllm_cuda_kernels.cu-o$dll...$cudaDefs (-DVLLM_HAVE_CUDA)}-arch默认native-fmadfalse是为了不让编译器把乘加合并掉保住数值可复现。四、实测数据VLLM_CUDA_FORCE_CPU的判定表口径同一次运行只切这一个开关配置输出结论标注VLLM_CUDA_FORCE_CPU1正确初始化无副作用问题在 GPU 计算/数值实测VLLM_CUDA_FORCE_CPU1也错初始化有副作用问题在状态污染实测第 10 篇 那个指针越界 bug 就是靠这个开关把范围从「所有 CUDA 代码」收窄到「初始化路径」的。五、边界与已知限制这套边界只覆盖x86-64 宿主 独立 NVIDIA GPUaarch64(RK3588) 目标必须VLLM_CUDAOFF。-Cuda构建需要在「x64 Native Tools Command Prompt for VS」里跑nvcc 要cl.exe做宿主编译器。出厂档与诊断档的 DLL 同名都叫vllm_cuda.dll一旦互相覆盖别人拿到的可能是「名为出厂、实为诊断」的产物——所以诊断用的额外-D默认不允许写进出厂目录。「模块缺失 → 逐字节等价」是本篇边界能成立的前提但它只保证未引入后端时行为不变不能外推为「任何版本错配都安全」——版本错配走的是「整体放弃」而不是「部分可用」。CPU 对照迁移前基线CPU 参考kestrel-llm裸引擎无 CUDA 时每个 offload 由引擎自跑 CPU桩行为与引入后逐字节等价。迁移要点CPU 侧单进程引擎 → CUDA 侧做成纯 C ABI 的独立运行期模块MinGW 与 MSVC 两套 CRT 不可链接任一入口缺失即整体放弃VLLM_CUDA_FORCE_CPU作逃生阀编译加-fmadfalse。真机验证命中 E1E2-Cuda构建成功、模块加载/VC_BIND 生效、selftest 全绿。六、小结可复用结论硬约束决定架构Windows 上 nvcc 只有 MSVC 宿主、引擎是 MinGW/GCC两套 CRT 不可链接因此 CUDA 层必须是纯 C ABI 的独立运行期模块而不是链接期依赖。「任一入口缺失即整体放弃」是护栏宁可完全不加速也不允许半绑定运行——后者是未定义行为的源头。init 永不失败、offload 用 0/1 表达「有 GPU 加速、无 GPU 零回归」这条一致性契约靠统一返回约定贯彻到每一层。VLLM_CUDA_FORCE_CPU是把两类原因分开的最小工具设备照常初始化只是每个 offload 走 CPU一次切换即可判断错在初始化还是错在计算。模块缺失是正常状态加载器找不到模块不是错误写个 note 就返回引擎照常跑 CPU。相关篇目第 01 篇 · 阶段总览、第 03 篇 · 权重条带缓存与融合权重源码与配套资源本仓库 https://gitee.com/pei-xiaoguang/kestrel-llm-cuda.gitCPU 推理源码 https://gitee.com/pei-xiaoguang/kestrel-llm