如何为 Spirula Studio 添加一个新内核CUDASlangParity 三件套完整指南【免费下载链接】spirula-studioCross-vendor 3D Gaussian Splatting trainer - video to splat to mesh, Vulkan or CUDA.项目地址: https://gitcode.com/GitHub_Trending/sp/spirula-studioSpirula Studio 是一款跨 GPU 厂商的 3D Gaussian Splatting 训练器——从照片/视频到 splat 再到带纹理网格全部在单个自包含二进制中完成支持 NVIDIA、AMD、Intel 和 Apple GPU。它的训练引擎同时拥有CUDA和VulkanSlang两套实现而项目铁律是任何一个内核级改动都必须交付三件套——CUDA 实现、Slang 实现加启动器、以及一个跑两边并比对的 parity对等性测试。本文带你完整走一遍添加新内核的全流程。 先看懂两后端架构为什么要三件套Spirula Studio 的引擎层src/engine/是 CUDA-free 的它只通过backend/api/下生成的启动声明调用内核。也就是说CUDA 后端内核在src/kernels/**/*.cu模板实例化由src/instantiations/111 个生成文件承担Vulkan 后端内核是 Slang 着色器src/backend/vulkan/shaders/*.slang C 启动器src/backend/vulkan/kernels/*.cpp共享设备数学src/shaders/*.slang会被编译两次——一次进src/generated/*.cuh供 CUDA 用一次进 SPIR-V供 Vulkan 用。这套设计的意义是同一份引擎代码驱动两套硬件后端任何一边悄悄改动、另一边没跟上就会编译通过但结果不同。parity 测试就是为此而生的防线。 架构图与职责分布详见 docs/architecture.md后端边界的最权威文档是 src/backend/README.md 和 src/backend/vulkan/README.md。 第一件CUDA 内核src/kernels/family/Kernel.cu每个内核家族一个目录projection、raster、pixelwise、densify……目录里是三兄弟文件角色Name.cu主机端启动器 设备端 kernelName.cuh生成的启动函数声明头引擎侧引用Name_kernel.cuh设备端函数体供模板实例化器读取关键点只有一个导出标记。想让某个启动函数暴露给引擎就在它的定义上方放一行/*[AutoHeaderGeneratorExport]*/然后重跑代码生成。以 densify 家族为例DensifyScoring.cu 中的densify_launch_*函数正是这样逐个导出的。⚠️ 两条硬规则.cuh里有一条分隔线/* AUTO HEADER GENERATOR - DO NOT EDIT THIS LINE... */分隔线以上手写以下只能由生成器重写手工改会被覆盖。一个新的内核家族需要在 tools/codegen/generate_headers.py 的HEADER_SOURCES表里登记哪些.cu向哪个头文件贡献声明——表里列了不存在的文件会直接报错所以重命名不可能悄悄丢掉声明。另外声明区必须保持无 CUDA include要用 src/backend/api/BackendTypes.h 的向量类型因为它要在没有 CUDA 工具链的 Vulkan 构建下也能解析。 第二件Slang 实现 Vulkan 启动器Vulkan 侧对应交付两个文件Slang 着色器src/backend/vulkan/shaders/Name.slang声明 SPIR-V 入口点复用src/shaders/里共享的设备数学函数C 启动器src/backend/vulkan/kernels/Name.cpp创建 pipeline、准备 buffer、派发 dispatch。两个容易踩的坑共享 Slang 不能分叉。src/shaders/下改任何东西都必须重新跑 Slang→SPIR-V 编译CMake 会做但纯手工改src/generated/*.cuh会直接导致两后端计算结果不同网格维度上限。CUDA 的gridDim.y/z上限是 65535Vulkan 任何派发维度都封顶 65535——每图一个槽位的轴要折叠参考 src/kernels/tile/IntersectTile.cu 和vkk::fold_1d的用法。如果 Vulkan 侧暂时没准备好也别硬撑tools/codegen/generate_vulkan_stubs.py会对未移植的内核生成抛异常的空实现让可移植引擎先能链接。这是刻意的 TODO 标记不是完成态。 第三件Parity 测试src/backend/tests/src/backend/tests/ 下每个*_parity.cpp都是一个独立可执行程序同一份源码在 CUDA 和 Vulkan 两种构建下都能编译典型用法是dump 参考值 → compare 对比值# CUDA 构建跑出参考结果 ./densify_parity dump ref.bin # Vulkan 构建逐设备对比 ./densify_parity compare ref.bin以 densify_parity.cpp 为例它体现了 parity 测试的三个精髓分级容差确定性输出走严格 float 通道逐位比较依赖随机数的下游输出走宽松通道只限制违反比例上限跨后端的浮点舍入可能翻转极个别边界样本量化数据按整数码比较量化 packed cell 允许 ±1 个量化步的偏差构造可对比的输入涉及原子压缩、调度依赖的路径用恰好只有一个操作对象的配置把比较退化为逐元素多对象并发由确定性路径覆盖。构建与运行方式详见 docs/testing.mdbash build_develop.bash -DSS_BACKENDcuda -DSS_BUILD_BACKEND_TESTSON ./build_cuda/test_name dump ref.bin bash build_develop.bash -DSS_BACKENDvulkan -DSS_BUILD_BACKEND_TESTSON ./build_vulkan/test_name compare ref.bin⚙️ 收尾代码生成与自检清单改完三件套后从仓库根目录依次跑生成器输出已提交进仓库所以新克隆无需 Python 也能构建见 docs/codegen.md生成器读什么写什么generate_headers.py.cu里的导出标记对应.cuh的声明区generate_kernel_instantiation.py*_kernel.cuh里的 kernel 声明src/instantiations/*.cugenerate_backend_api.py各内核.cuhsrc/backend/api/*.h转发头generate_vulkan_stubs.pyVulkan 构建的链接探测未移植内核的抛异常桩自查清单✅启动函数上方有/*[AutoHeaderGeneratorExport]*/标记新家族已登记进HEADER_SOURCES.cuh声明区无 CUDA includeVulkan 宏下可解析Slang 入口点 src/backend/vulkan/kernels/启动器齐活parity 测试在两个后端下都通过注释符合预算文件头 ≤10 行、块注释 ≤3 行超限会构建失败规则见 AGENTS.md 延伸阅读构建矩阵与各平台说明docs/build.md后端移植风险清单64 位排序键、浮点原子、子组宽度src/backend/README.mdVulkan 设备能力、变体与内存模型src/backend/vulkan/README.md内核家族内部约定示例src/kernels/densify/DensifyCommon.cuh三句话总结标记导出 CUDA 侧、Slang 补齐 Vulkan 侧、parity 测试锁死两边一致——做到这三点你的新内核就是 Spirula Studio 双后端架构的一等公民。【免费下载链接】spirula-studioCross-vendor 3D Gaussian Splatting trainer - video to splat to mesh, Vulkan or CUDA.项目地址: https://gitcode.com/GitHub_Trending/sp/spirula-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考