在 llama.cpp 中使用多张 GPU

本指南说明如何让 llama.cpp 跨多张 GPU 运行，介绍拆分模式、相关命令行参数、需要了解的限制，以及可用于 llama-cli 和 llama-server 的配置示例。

下面列出的命令行参数适用于这两个工具，也适用于大多数 llama.cpp 可执行程序。

什么时候需要多 GPU

遇到以下情况之一时，可以考虑使用多 GPU：

模型无法装入单张 GPU 的显存。 把权重分散到两张或更多 GPU 后，可以让整个模型都驻留在加速器上。否则，部分模型将不得不在相对较慢的系统内存中运行。
希望获得更高吞吐量。 把计算分配到多张 GPU 后，每张 GPU 承担的工作会减少。是否能改善预填充或 token 生成性能，取决于拆分模式，以及 GPU 之间的互连速度与单张 GPU 计算速度之间的关系。

拆分模式

通过 --split-mode 或 -sm 设置。

模式	工作方式	适用情况
`none`	只使用一张 GPU，通过 `--main-gpu` 选择。	虽然能看到多张 GPU，但明确希望把模型限制在一张 GPU 上。
`layer`（默认）	流水线并行。每张 GPU 保存一段连续的模型层；第 l 层的 KV 缓存保存在拥有第 l 层的 GPU 上。	默认且兼容性最好的多 GPU 选择。需要比单张 GPU 更多的显存，并优先追求较快的预填充；能容忍 GPU 之间较慢的互连。
`row`	已弃用。较早的行拆分张量并行路径，性能相对较差，只在 GPU 间拆分稠密权重。已由 `tensor` 取代；在能够使用 `tensor` 的条件下，后者应当全面优于它。	新部署应避免使用。
`tensor`	实验性。通过“元设备”抽象，在参与计算的 GPU 间同时拆分权重和 KV 缓存的张量并行。	需要比单张 GPU 更多的显存，并优先追求较快的 token 生成。对于大型稠密模型和较快的 GPU 互连，预填充速度可接近流水线并行。该实现不如流水线并行成熟，应按实验性功能对待。使用 CUDA 后端的多张 NVIDIA GPU 预计有较好性能，其他组合不作保证。

流水线并行（layer）把不同层放到不同 GPU 上，让 token 沿流水线依次通过。这种方式可尽量减少 GPU 之间的数据传输，但需要较多 token 才能充分扩展。张量并行（tensor）则把每一层拆分到多张 GPU，每层执行多次跨 GPU 归约；它能并行处理各种工作负载，但更容易受 GPU 互连速度限制。

流水线并行着重提高批处理吞吐量；张量并行着重降低延迟。

命令行参数参考

短参数	长参数	值	默认值	说明
`-sm`	`--split-mode`	`none`、`layer`、`tensor`	`layer`	见上面的模式说明。
`-ts`	`--tensor-split`	逗号分隔的比例，例如 `3,1`	随模式而定	决定各 GPU 分担多少模型。省略时，`layer`/`row` 按显存比例自动拆分，`tensor` 则平均拆分张量片段。两张 GPU 使用 `3,1` 时，GPU 0 分得75%，GPU 1分得25%；值的顺序对应 `--device` 中的设备顺序。
`-mg`	`--main-gpu`	整数设备索引	`0`	`--split-mode none` 使用的单张 GPU。
`-ngl`	`--n-gpu-layers` / `--gpu-layers`	整数、`auto`、`all`	`auto`	最多在显存中保存多少层。用 `999` 或 `all` 将尽可能多的内容放到 GPU。
`-dev`	`--device`	逗号分隔的设备名，或 `none`	auto	限定 llama.cpp 可以使用的设备；设备名见 `--list-devices`。
	`--list-devices`	–	–	输出可用设备及其显存。先运行它，了解可传给 `--device` 的名称。
`-fa`	`--flash-attn`	`on`、`off`、`auto`	`auto`	使用 `--split-mode tensor` 或量化 V 缓存时必需。大多数模型与后端组合支持它，因此默认启用。
`-ctk`	`--cache-type-k`	`f32`、`f16`、`bf16`、`q8_0`、`q4_0`、……	`f16`	K 的 KV 缓存类型。
`-ctv`	`--cache-type-v`	与 `-ctk` 相同	`f16`	V 的 KV 缓存类型。
`-fit`	`--fit`	`on`、`off`	`on`	按设备显存自动调整尚未设置的参数。`tensor` 模式不支持该功能，可能需要手动设置 `--ctx-size` 才能让模型装入显存。

与其他 CUDA 程序一样，可以用环境变量 CUDA_VISIBLE_DEVICES 控制 CUDA 后端使用哪些 GPU。设置后，llama.cpp 只能看到指定的 GPU。再用 --device 从 llama.cpp 可见的 GPU 中进行选择；--device 适用于所有后端。

配置示例

1. 默认配置：跨所有可见 GPU 的流水线并行

llama-cli -m model.gguf
llama-server -m model.gguf

这是最简单的配置。KV 缓存随模型层分布在各张 GPU 上，默认启用的 --fit 会自动调整大小。

2. 自定义拆分比例的流水线并行

llama-cli -m model.gguf -ts 3,1

适用于各 GPU 显存容量不同的情况：GPU 0 分3份，GPU 1分1份。比例会被归一化，因此 -ts 3,1 与 -ts 75,25 等设置等价。

3. 单 GPU 模式：选择指定 GPU

llama-cli --list-devices
llama-cli -m model.gguf -dev CUDA1

仅使用 --list-devices 列表中名为 CUDA1 的设备。

4. 张量并行（实验性）

llama-cli -m model.gguf -sm tensor -ctk f16 -ctv f16

如果设置 --flash-attn off，或因不受支持而使 --flash-attn auto 最终解析为 off，会直接报错。
KV 缓存必须使用未量化的类型：f32、f16 或 bf16。尚未实现量化 KV 缓存支持，尝试使用会报错。
应在相关工具中将这种配置标为实验性，部署前验证输出质量。
--split-mode tensor 尚未为所有架构实现。以下架构会报出 LLAMA_SPLIT_MODE_TENSOR not implemented for architecture '...'：
- MoE／混合架构：Grok、MPT、OLMoE、DeepSeek2、GLM-DSA、Nemotron-H、Nemotron-H-MoE、Granite-Hybrid、LFM2-MoE、Minimax-M2、Mistral4、Kimi-Linear、Jamba、Falcon-H1。
- 状态空间／RWKV 风格架构：Mamba、Mamba2，以及上面列出的 Mamba-attention 混合模型。
- 其他架构：PLAMO2、MiniCPM3、Gemma-3n、OLMo2、BitNet、T5。

5. 使用 NCCL

NCCL 没有运行时开关，而是在构建时选择：-DGGML_CUDA_NCCL=ON，这也是默认设置。CUDA 不会自动附带 NCCL，可能需要手动安装；不确定时，查看 CMake 日志是否找到了该包。llama.cpp 编译时启用了 NCCL 支持后，会在 tensor 模式的跨 GPU 归约中自动使用它。

如果多 GPU 构建中缺少 NCCL，会出现以下一次性警告，性能也会降低：

NVIDIA Collective Communications Library (NCCL) is unavailable, multi GPU performance will be suboptimal

使用 ROCm 后端时——即通过 HIP 将 ggml CUDA 代码转换给 AMD 使用的后端——可以在编译时设置 -DGGML_HIP_RCCL=ON，使用 AMD 对应的 RCCL。RCCL 默认禁用，因为测试中它不像 NCCL 那样普遍带来收益。

6. 使用 CUDA 点对点访问（`GGML_CUDA_P2P`）

CUDA 点对点（P2P）访问允许 GPU 直接互传数据，而不用经由系统内存，通常能改善多 GPU 性能。该功能需要在运行时显式启用：把环境变量 GGML_CUDA_P2P 设为任意值即可。

GGML_CUDA_P2P=1 llama-cli -m model.gguf -sm tensor

P2P 需要驱动支持，通常限制在工作站或数据中心 GPU 上。在某些主板或 BIOS 配置下，它可能导致崩溃或输出损坏，例如启用 IOMMU 时。如果启用后出现不稳定，应取消设置该变量。

故障排查

症状	处理办法
启动时报 `SPLIT_MODE_TENSOR requires flash_attn to be enabled`	添加 `-fa on`，或删除 `-fa off`。
启动时报 `simultaneous use of SPLIT_MODE_TENSOR and KV cache quantization not implemented`	为 `--split-mode tensor` 配置 `-ctk f16 -ctv f16`，或使用 `bf16`/`f32`。
启动时报 `LLAMA_SPLIT_MODE_TENSOR not implemented for architecture 'X'`	该架构不在 TENSOR 支持名单中，改用 `--split-mode layer`。
警告 `NCCL is unavailable, multi GPU performance will be suboptimal`	llama.cpp 构建时未启用 NCCL。可以接受较低性能，或安装 NCCL 后重新构建。
`--split-mode tensor` 启动或预填充时发生 CUDA OOM	该模式禁用了自动适配，需自行减轻显存压力。按影响从小到大的顺序：先减小 `--ctx-size`（`-c`），KV 缓存大小大致与 `n_ctx` 成正比；使用 `llama-server` 时，再减小 `--parallel`（`-np`），每个并发序列都会分配一个槽位的 KV 缓存；最后才减少 `--n-gpu-layers`（`-ngl`），剩余层将由 CPU 运行，推理会慢得多。
多 GPU 性能反而差于单 GPU	瓶颈在 GPU 互连速度。使用 `--split-mode tensor` 时，确认正在使用 NCCL；尝试通信量较少的 `--split-mode layer`；通过增加 PCIe 通道数或在可用时采用 NVLink 等方式，提高 GPU 互连速度。
完全没有使用 GPU	`--n-gpu-layers` 可能为 `0` 或过低，可显式设置 `-ngl all`；也可能通过 `CUDA_VISIBLE_DEVICES=-1` 等环境变量误将 GPU 隐藏，或者构建没有包含对应后端的支持。
设置 `GGML_CUDA_P2P=1` 后崩溃或输出损坏	某些主板和 BIOS 设置（例如启用 IOMMU）不能可靠支持 CUDA 点对点访问。取消设置 `GGML_CUDA_P2P`。

原文未把 row 列入参数参考表的可选值，但仍在模式表解释其弃用状态，本版沿用这一范围。示例中的测试与性能判断属于原作者陈述。

MIT License

Copyright (c) 2023-2026 The ggml authors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

文章版权归作者所有，未经允许请勿转载。

THE END