计算后端

后端通过 --backend（CLI 与服务器）选择，决定由哪种硬件运行数学运算。对任何未实现的运算，每个后端都会回退到 CPU，因此各处输出都保持正确 —— 后端只在速度上不同。

我该用哪个后端？

所有后端详解

GGML Metal、GGML CUDA 与 GGML Vulkan

建立在链接 ggml 的原生 C++ 桥接之上的 GPU 路径。

• GGML Metal（ggml_metal，macOS）—— 量化权重经由主机指针缓冲区从 GGUF 文件零拷贝映射进 Metal 命令缓冲，因此常驻内存接近磁盘上的模型大小。
• GGML CUDA（ggml_cuda，Windows/Linux + NVIDIA）—— 量化权重在加载时一次性上传到显存，之后释放主机副本。
• GGML Vulkan（ggml_vulkan，Windows/Linux + AMD/Intel/NVIDIA）—— 与厂商无关的 GPU 路径，支持任何带 Vulkan 1.3 驱动的 GPU，驱动支持时使用 cooperative-matrix（KHR coopmat / NV coopmat2）着色器。权重与 GGML CUDA 一样常驻显存，并复用同样的融合整模型 decode/prefill 图。在多 GPU 主机上（例如同时装有 Intel 集成显卡和 NVIDIA 独立显卡），用 --gpu-device N（或环境变量 TS_GGML_VULKAN_DEVICE）选择设备，用 --list-gpus 列出可见设备。

三者都在不反量化为 FP32 的情况下运行原生量化 matmul（Q4_K_M、Q8_0 ……），并配有驱动 ggml_flash_attn_ext 的原生分页注意力内核。

多 GPU。GGML CUDA 与 GGML Vulkan 同样支持张量并行：--tp N 让每个 rank 在自己的 GPU 上拥有独立的 ggml 后端、权重分片与 KV 缓存，由 rank 工作线程池并发驱动，跨 GPU AllReduce 走 ggml 的集合通信（构建时能找到 NCCL 就用 NCCL），小载荷则在主机内存中归约。融合的按 rank block 计算图让 Gemma 4 上 --tp 2 的 decode 快于单卡，也让超出单卡显存的模型能够完整跑在 GPU 上。

MLX Metal

--backend mlx 是建立在 mlx-c 之上、GPU 加速的 Apple Silicon 路径。它在不反量化为 FP32 的情况下实现量化运算（Q4_K_M、Q8_0、Q5_K、Q6_K、IQ2_XXS、IQ4_XS、IQ4_NL、MXFP4 ……）、融合的 decode/prefill Metal 内核、编译图内核、异步 worker 调度、批量 MoE decode 与 MoE 专家卸载。它通过 mlock(2) 把 GGUF mmap 钉在物理内存中，并根据主机的统一内存容量推导分配器上限。需要 libmlxc（本地构建，或通过 TENSORSHARP_MLX_LIBRARY / TENSORSHARP_MLX_LIBRARY_DIR 定位）。

直接 CUDA

--backend cuda 是一条纯 C# 路径，使用 CUDA Driver API、cuBLAS GEMM，以及常见 float32 运算的 PTX 内核（fill、一元/二元/三元、激活、RMSNorm、softmax、RoPE/RoPEEx、SDPA、GQA prefill/decode、因果掩码、gather/concat），外加受支持量化类型的原生量化 matmul/get-rows。未支持的运算在保留张量语义的前提下走 CPU 回退。它也是MTP 推测解码能获益的纯 C# 后端。

它支持张量并行：--tp N 把一个模型切分到 N 张 CUDA GPU 上，--tp-node-id / --tp-peers 则把并行组扩展到多台机器。GGML CUDA 与 GGML Vulkan 后端同样支持切分（见上文）；MLX 与 CPU 后端为单设备 —— 在多 GPU 主机上它们只会选择其中一张卡（不带 --tp 时 Vulkan 用 --gpu-device），而不会切分模型。→ 多 GPU 与多节点

CPU 后端

• 纯 C# CPU（cpu）—— 无原生依赖的可移植推理，使用托管 GEMM 快路径与融合 SIMD 内核。适合调试与最大可移植性。
• GGML CPU（ggml_cpu）—— 原生 GGML CPU 内核，量化权重从 GGUF 文件零拷贝映射。在多数 CPU 上比纯 C# 更快。

构建原生库

请先按平台安装并验证 .NET 10 SDK。原生 GGML 库会在首次 dotnet build 时自动构建。要手动构建或启用 CUDA：

cd TensorSharp.GGML.Native

# macOS（Metal）
bash build-macos.sh

# Linux —— 仅 CPU、强制启用 CUDA、强制关闭 Vulkan
bash build-linux.sh
bash build-linux.sh --cuda
bash build-linux.sh --no-vulkan

# Windows —— 仅 CPU、强制启用 CUDA、强制关闭 Vulkan
.\build-windows.ps1 --no-cuda
.\build-windows.ps1 --cuda
.\build-windows.ps1 --no-vulkan

GGML Vulkan 后端会自动启用——当主机存在 Vulkan 运行时（Windows 上的 vulkan-1.dll 或 Linux 上的 libvulkan.so.1 loader，近期 GPU 驱动均自带）时即启用；用 --no-vulkan（或 TENSORSHARP_GGML_NATIVE_ENABLE_VULKAN=OFF）退出，且显式选择会经 CMake 缓存在重复构建中保持。Windows 上已安装 LunarG Vulkan SDK 时直接使用；未安装时构建会通过 eng/fetch-vulkan-toolchain.ps1 自动把便携工具链（Vulkan-Headers、由系统 loader 生成的 vulkan-1 导入库、glslc、SPIRV-Headers）准备到 ExternalProjects/vulkan-toolchain/。Linux 上有发行版开发包时直接使用（apt install libvulkan-dev glslc spirv-headers）；否则构建会通过 eng/fetch-vulkan-toolchain.sh 自动补齐缺失部分（Vulkan-Headers、来自 shaderc CI 预编译的 glslc、SPIRV-Headers）。运行时需要支持 Vulkan 1.3 的 GPU 驱动。

在 Windows/Linux 上，脚本会自动检测可见 NVIDIA GPU 的计算能力，并传入一个收窄的 CMAKE_CUDA_ARCHITECTURES（例如 RTX 3080 上的 86-real），从而大幅缩短 CUDA 构建时间。可显式覆盖：

TENSORSHARP_GGML_NATIVE_CUDA_ARCHITECTURES='86-real;89-real' bash build-linux.sh --cuda
bash build-linux.sh --cuda --cuda-arch='86-real;89-real'

你也可以直接在 dotnet build 中请求 CUDA：

TENSORSHARP_GGML_NATIVE_ENABLE_CUDA=ON dotnet build TensorSharp.Cli/TensorSharp.Cli.csproj -c Release

MLX 原生库（仅 macOS）

MLX 后端依赖 libmlxc。一个辅助脚本会获取并构建它：

bash TensorSharp.Backends.MLX/build-native-macos.sh

它会把库写入 TensorSharp.Backends.MLX/Native/dist/。运行时后端会先探测应用目录；用 TENSORSHARP_MLX_LIBRARY 或 TENSORSHARP_MLX_LIBRARY_DIR 指向别处。

平台二进制发行状态

计划中的发行工作流会在全部必需构建 job 成功后生成以下自包含归档：

这些是计划中的产物名称，并不表示文件目前可下载。文件存在时，-cuda 归档仍需 NVIDIA GPU 与兼容驱动；macOS 归档需要 Apple Silicon。