多 GPU 与多节点

--tp N 仅选择张量并行，在层内切分权重；--layer-split N 在支持的架构上选择整层放置。两种参数互斥，不支持的请求会在启动时失败。按层切分仅限单节点；只有支持分布式张量并行的架构才能通过 --tp-node-id / --tp-peers 跨节点运行。旧的按层切分命令需将 --tp N 改为 --layer-split N（环境变量：TENSORSHARP_LAYER_SPLIT_DEGREE=N）。

什么时候需要它？

• 模型装不进一张 GPU。每张 GPU 只持有 1/N 的切分权重，因此单卡显存放不下的模型，切到两张或四张卡上就能从容运行。
• 模型装不进一台机器。分布式 TP 把多台主机的 GPU 汇聚成一个逻辑并行组——2 节点 × 4 GPU 即全局并行度 8。
• 希望每个 token 获得更多显存带宽。每张 GPU 处理每个投影的自有切片，逐层矩阵乘是被切分的，而不是排队串行执行。

在 GGML 后端上，融合的按 rank block 计算图让 --tp 2 在本来就装得下单卡的模型上也能快于单 GPU —— Gemma 4 E4B Q8_0 上 51.7 对 37.3 tok/s（2× RTX 2000 Ada）。如果你要的是更高的并发吞吐而非更低的单流延迟，请先看 连续批处理——它默认开启，零成本即可尝试。

选择张量并行或按层切分

张量并行（--tp N）在每层内部切分投影，让 N 张 GPU 并行计算并通过集合通信归约结果。按层切分（--layer-split N）把完整层放到 N 张本地 GPU，在设备边界传递隐状态；它增加容量，但不保证吞吐提升。

Qwen 3.8 Flash Next 在 ggml_cuda 上对满足条件的 FFN 量化支持本地 --tp N，在 GGML CUDA/Vulkan 上支持 --layer-split N。DeepSeek V4.1 在 GGML CUDA 上支持 routed-MoE TP（并行度 2–8），注意力与缓存仍按层放置。DeepSeek V4 与 GLM 5.x 也支持本地整层放置，GLM 还有本地原生 TP。Muse Spark 的原生执行器在 GGML CUDA/Vulkan 上使用 --layer-split N，在 GGML CUDA 上也接受 --tp N，通过上游 ggml 的 meta 后端把每一层切分到 N 张 GPU 上；TS_MUSE_SPARK_NATIVE=0 与 GGML Vulkan 仍使用其逐算子路径上的注意力与专家 TP。MiniMax-M3.1 的原生执行器在 GGML CUDA 上两种模式都支持；它的 --tp N 镜像注意力与缓存并切分 FFN。两种参数互斥，不支持的模式会在模型/后端检查时被拒绝，这些整模型路径不支持多节点组。

# 完整层放到两张本地 GPU；服务端接受相同参数
TensorSharp.Cli/bin/TensorSharp.Cli --model qwen38-flash-next.gguf \
    --backend ggml_cuda --layer-split 2

配置文件等价写法：{ "layer-split": 2 }。环境变量：TENSORSHARP_LAYER_SPLIT_DEGREE=2。不能与张量并行或分布式参数组合；跨节点按层切分尚未实现。

张量并行的工作原理

每个 transformer block 被改写为一对互补的切分方式，因此每半个 block 只需要一次集合通信：

1. 列并行投影

   QKV 与 gate/up 沿输出维度切分——注意力头或 FFN 中间维度分配到各 GPU。此处无需通信：每个 rank 只产出属于自己的那部分激活。

2. 各 rank 独立计算

   注意力（或激活函数）在每张 GPU 上只针对该 GPU 拥有的头运行，使用该 GPU 自己的 KV 缓存。

3. 行并行投影 + AllReduce

   output 与 down 投影沿输入维度切分，因此每个 rank 得到一个部分和。一次 AllReduce 把这些部分和相加，block 结束时每个 rank 都持有完全相同的隐藏状态。

归一化层、词嵌入与 LM head 在各 rank 上复制而非切分——它们体积很小，复制可以从关键路径上省掉一次集合通信。

本地 TP —— 单进程，多张 GPU

本地 TP 运行在单个进程内。在 Direct cuda 后端上，由一个线程顺序向所有 GPU 下发命令，真正的并行由 CUDA stream 提供，AllReduce 通过点对点设备拷贝加逐元素加法内核完成。在 GGML 后端上，则由一个 rank 工作线程池并发驱动各张 GPU —— GGML 的一次算子调用同时完成提交与同步，顺序循环各 rank 会让显卡严格串行执行。

# CLI —— 把模型切分到 2 张 GPU
dotnet TensorSharp.Cli/bin/TensorSharp.Cli.dll --model model.gguf --backend cuda --tp 2

# GGML CUDA 后端上同理
dotnet TensorSharp.Cli/bin/TensorSharp.Cli.dll --model model.gguf --backend ggml_cuda --tp 2

# 指定各 rank 对应的物理 GPU
TENSORSHARP_TP_DEVICES=0,2 dotnet TensorSharp.Cli/bin/TensorSharp.Cli.dll \
    --model model.gguf --backend ggml_cuda --tp 2

# 服务端 —— 同样的参数（TENSORSHARP_TP_DEGREE=2 环境变量也可用）
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll \
    --model model.gguf --backend ggml_cuda --tp 2

也可以写进配置文件：

{ "model": "model.gguf", "backend": "cuda", "tp": 2 }

分布式 TP —— 多台机器

每个节点在自己的本地 GPU 上运行独立进程，并通过带长度前缀的分帧协议与其他所有节点建立 TCP 连接。AllReduce 是分层的：先在节点内通过 P2P 做本地归约，再由各节点代表之间走 TCP 交换，最后逐层广播回去——因此只有 1/tp_local 的数据需要穿过网络。

# 2 节点 × 每节点 2 GPU = 全局 TP 度 4
# 节点 0：
dotnet TensorSharp.Cli/bin/TensorSharp.Cli.dll --model model.gguf --backend cuda --tp 2 \
    --tp-node-id 0 --tp-peers "192.168.1.10:9500,192.168.1.11:9500"

# 节点 1 —— peer 列表相同，节点 ID 不同：
dotnet TensorSharp.Cli/bin/TensorSharp.Cli.dll --model model.gguf --backend cuda --tp 2 \
    --tp-node-id 1 --tp-peers "192.168.1.10:9500,192.168.1.11:9500"

服务端可以作为这样一个集群的前端，但只能是节点 0 —— 即负责采样并对外提供 HTTP 的 driver。其余每个节点都运行一个 TensorSharp.Cli worker，使用相同的模型、后端与 peer 列表。TENSORSHARP_TP_* 环境变量可以替代这些参数。

# 节点 0 —— 服务端 / driver：
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --model model.gguf --backend cuda \
    --tp 2 --tp-node-id 0 --tp-peers "192.168.1.10:9500,192.168.1.11:9500"

# 节点 1 —— CLI worker：
dotnet TensorSharp.Cli/bin/TensorSharp.Cli.dll --model model.gguf --backend cuda --tp 2 \
    --tp-node-id 1 --tp-peers "192.168.1.10:9500,192.168.1.11:9500"

节点通常由人工间隔数秒到数分钟启动，因此先起来的节点会持续重试对外连接（最长 120 秒），而不是在第一次连接被拒绝时就失败。网格建立完成后，每个节点会打印 [TcpCommunicator] Rank r/N connected to all peers.。

支持的架构

TensorSharp 中几乎每一种自回归架构都可以在 TP 下运行，Qwen-Image-2.1 的扩散 Transformer 也可以；异构层各有自己的切分策略。--tp 含义不同的那几个会单独标注。本表描述本地支持；GLM 5.x 没有任何一个版本声明支持分布式/跨节点 TP —— GLM-5.2、GLM-5.3 与 GLM-5.3-Flash 都会在模型构建之前直接拒绝 --tp-node-id/--tp-peers。

MoE 有两种切分方式。专家切分（Direct CUDA，以及各后端上的 GPT OSS / Nemotron-H）让每张 GPU 持有每一个专家权重的 1/tp，router 复制——因此无论 token 选中哪些专家，负载都保持均衡。专家并行（GGML 上的 Qwen 3.5/3.6）则划分整个专家，使每个 rank 每个投影仍然只需一次批量 ggml_mul_mat_id 调度，而不是按 (token, 专家) 循环。GGML 上的 Gemma 4 与 GLM 5.x 用的是第三种：Megatron 切分发生在每个专家内部（gate/up 列并行、down 行并行），于是每个 rank 仍然看得到完整的专家表，一个 token 选中的 id 在全局范围内依旧有效——这正是 ggml_mul_mat_id 的要求，因为它不接受同一 token 的选择里出现重复的专家 id。

要求与约束

• 仅限 GPU 后端。TP 可运行在 cuda、ggml_cuda 与 ggml_vulkan 上；MLX 与 CPU 后端为单设备。
• 整除性。numHeads、numKVHeads 与 intermediateSize 都必须能被 TP 度整除；量化权重的行并行切分还要求 ne0 能被 tp × blockSize 整除。Muse Spark 是例外：它的两条 TP 路径都接受不均匀划分——原生执行器不均匀地分配 KV 组与 256 元素的专家切片，逐算子路径则分配完整的头组与专家——但逐算子路径上量化注意力输出的切分仍须保持完整的量化块。
• TP 下的批处理前向目前实现于 Mistral 3。MoE 模型（Gemma 4、Qwen 3.5/3.6、GPT OSS、Nemotron-H）在 TP 激活时回退到按序列前向，因此连续批处理在这些模型上的增益较小。
• 本地并行度 ≤ 可见 GPU 数。请求的 rank 数超过主机设备数时，启动阶段就会直接失败。
• 多节点仍走逐算子前向。融合的整模 TP 计算图是按 rank、单进程的；分布式运行会回退到逐算子执行。

实测结果

2× RTX 2000 Ada（各 16 GB，PCIe，无 NVLink），--backend ggml_cuda --tp 2，prefill 512 / decode 64，单位 tok/s：

^† 测于 2× RTX PRO 4000 Blackwell（各 24 GB，PCIe），而不是其他各行所用的那对 RTX 2000 Ada —— 两套硬件之间不能直接比较，只能各行与自己的单卡列比较。Muse-Glimmer 是这里唯一在两个阶段上都快过单卡的模型（prefill 1.34×、decode 1.57×）；它的 Q8_0 没有单卡数字，因为 28.2 GB 的权重根本装不进 24 GB 的卡。

但这并不普适。在 3× RTX PRO 6000（PCIe，无 NVLink）上，GLM-5.2 UD-IQ2_XXS 以 prefill 2048 / decode 64 测得：按层切分 915.9 / 43.9 tok/s，而 --tp 3 只有 505.6 / 17.6——78 层里每层都要对 [6144, n_tokens] 的隐状态做两次 all-reduce，在 PCIe 主机上这笔开销超过了拆分省下的算力。TP 还要求每个 rank 各自持有一份全长缓存，能装下的上下文因此从 342,272 掉到 91,136 token；它也改变了归约顺序——对着录制的 llama.cpp 金标准，2-bit MoE 在 --tp 3 下复现 3/6 条提示，而按层切分复现 5/6。那里的 TP 是容量特性而非延迟特性。TP 能带来多少，取决于互连带宽以及一层里究竟有多少能拆。

Decode —— TP 本该受益的访存瓶颈部分 —— 在 Gemma 4 E4B 上达到单卡的 1.39×，在 Qwen 3.5-9B 上为 1.06×，且两个 Gemma 4 模型的输出与单卡运行逐字节一致。Prefill 受计算约束且要承担集合通信开销，因此在单卡装得下的模型上持平或略低于单卡。Qwen 3.5-35B-A3B 在 16 GB 卡上根本装不下 —— 只有 TP 能跑，两张卡上的显存占用为 9.4 + 8.0 GB。

按层切分的实测

按层切分不切分任何权重，因此它既不该有开销，也不该有收益 —— 实测正是如此。2× A100-80GB，Qwen3.8-Flash-Next-UD-Q2_K_XL（73.4 GiB），--layer-split 2 对比单卡：

llama.cpp 在同一台机器上表现相同：-sm layer 把 pp1536 / tg128 从单卡的 1094 / 61.2 提到双卡的 1200 / 61.5 —— prefill 约 10%，decode 几乎为零 —— 而 -sm row 干脆拒绝加载这个架构。所以这里传 --layer-split N 的理由是权重、缓存与上下文装不进一张卡，而不是吞吐。启动时会打印实际使用的模式与每张 GPU 的层数 / 字节划分。TS_Q4E_LAYER_SPLIT=20,28 可为每张 GPU 指定明确的层数（精神上等同 llama.cpp 的 --tensor-split），遇到无法满足的取值会抛错而不是默默忽略 —— 这很有用，因为自动均衡只按权重计价，看不到稍后才加载、并落在 GPU 0 上的视觉塔。

TP 下的 Qwen-Image-2.1 扩散 Transformer

两张分属不同 CPU 插槽的 NVIDIA A40（各 46 GB），它们之间的 peer access 不可用，NCCL 走的是共享内存传输。前缀缓存开启，步时不含第 1 步：

在 Vulkan 上归约要经过主机内存，其开销超过了切分省下的时间，因此在这套硬件上 --tp 反而更慢。TP 改变了每个 block 部分和的相加顺序，因此图像与单卡结果并不逐位一致（在 CUDA 上与单卡图像相比 PSNR 为 34.2–51.5 dB）：构图与质量保持不变，但细节可能移动。细节见仓库中的 docs/models/qwenimage21_zh-cn.md 卡片。

TP 下的 CUDA 图捕获

一个张量并行 token 是几十次按 rank 的小提交，重放它们值约 45% 的 decode 吞吐 —— 因此 TP 下图捕获保持开启（用 TS_GGML_TP_CUDA_GRAPHS=0 关闭）。4×A40 实测：

集合通信的传输方式同样靠实测而非能力标志位决定：启动时该组会验证所宣称的设备对之间的 peer copy 是否真的把数据送到，以及一次真实的 NCCL AllReduce 能否完成，然后选出通过检验的最快传输。有些主机（常见于虚拟化云实例）宣称支持 peer access 却从不兑现，此时会保留 NCCL 集合通信但禁用 peer 传输，而不是干脆放弃它——这在超过两张卡时尤为重要，因为那里用不上 pinned-host 流水线，替代方案是每个层边界都经主机内存归约（4×A40，Qwen 3.5-9B Q8_0 decode：53.5 → 75.1 tok/s）。

调优与诊断

本地 AllReduce 优先使用 CUDA 点对点（P2P）DMA。启动时，并行组会为每一对报告支持 P2P 的设备启用 peer access，随后做一次往返自检——部分拓扑（挂在某些 PCIe 交换机后的 L4、开启 IOMMU 的主机、BAR1 窗口过小）虽然声称支持 P2P，却会静默传输损坏数据，未通过自检的设备对会被永久降级为主机中转。完全不支持 peer access 的硬件（A16 vGPU 配置、大多数消费级显卡）则从一开始就走主机内存中转。这些回退都是自动的；下面的开关用于人为强制走某条路径以便定位问题。

启动日志会明确给出拓扑：本地并行组打印 Tensor parallelism: N GPUs (<设备名>)，设备对被降级时打印 TP: P2P disabled… 或自检告警，每个节点在网格建立完成后打印一条 [TcpCommunicator] Rank r/N connected to all peers.。

集群内的共享状态

当多个服务端进程共同承载同一批负载时，有一类状态可以放到 Redis，而不是各自的进程内存中：

• Responses API 存储——OpenAI Responses 存储从内存变为持久化且共享（--redis-url，环境变量 TS_RESPONSES_STORE_REDIS_URL）。
• 没有共享的 KV 缓存层——没有经 Redis 的跨进程 KV 复用：Redis 只承载 Responses API 存储。每个进程各自维护 radix 前缀缓存，其前缀 checkpoint 持久化在各自二进制旁的 prefix-cache/ 下。

# Responses 存储放在一个共享 Redis 上
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --model model.gguf --backend cuda \
    --redis-url localhost:6379

故障排查