用text-generation-webui加载模型时gpu-memory设置与exllama内核的兼容性

文章导读
在text-generation-webui里手动指定gpu-memory,本身是个很常用的操作,但换到ExLlama内核后,很多人会发现同样一个数值,有时候加载直接报错,有时候又像是没生效。我处理过几轮类似问题后,觉得关键不在于把数字调大或调小,而是要先弄清楚这个参数在ExLlama内核里到底怎么解释,以及启动参数里有没有东西在和它抢控制权。
📋 目录
  1. 一 先把gpu-memory的单位和边界弄明白
  2. 二 启动参数:别让ExLlama忽略你的设置
  3. 三 加载后看日志,确认设置真的生效
  4. 四 显存不够时怎么调,边界在哪
  5. 五 两个容易忽略的坑:gpu-layers和容器环境
A A

在text-generation-webui里手动指定gpu-memory,本身是个很常用的操作,但换到ExLlama内核后,很多人会发现同样一个数值,有时候加载直接报错,有时候又像是没生效。我处理过几轮类似问题后,觉得关键不在于把数字调大或调小,而是要先弄清楚这个参数在ExLlama内核里到底怎么解释,以及启动参数里有没有东西在和它抢控制权。

先把gpu-memory的单位和边界弄明白

当使用text-generation-webui的ExLlama内核加载模型时,gpu-memory参数的单位是MiB而非GB,且该值表示显存总量中可供模型权重和KV缓存使用的部分,并非新增分配量。与ExLlama v1不同,ExLlama v2(或Hugging Face的ExLlamaV2)对显存管理更严格,若gpu-memory设置超过显卡物理显存减去约300-500MiB的驱动开销,内核会在初始化阶段直接抛出CUDA out of memory错误,而不是回退到CPU或自动调整。因此,建议先以显存总量的70%作为初始值,观察加载是否成功。

这里“显存总量”指你在系统里能看到的那张卡的总显存,不是剩余显存。如果你拿一张8GB的显卡,先用70%就是约5734MiB。可以先给一个偏保守的值,加载成功后再逐步往上提,比一上来就顶到上限要省事得多。

启动参数:别让ExLlama忽略你的设置

在text-generation-webui的命令行或启动脚本中,设置gpu-memory时务必与-exllama或-exllamav2参数搭配使用。若只设置gpu-memory而未启用ExLlama内核,该参数会被忽略,模型仍按默认加载方式运行。同时,不要同时使用`--auto-devices`与gpu-memory,因为auto-devices会根据模型大小自动分配显存,与手动指定的gpu-memory冲突,可能导致显存分配异常或重复占用。正确做法是单独指定gpu-memory并去掉auto-devices开关。

例如用ExLlama v2加载一个4-bit量化的7B模型,启动命令可以写成:

用text-generation-webui加载模型时gpu-memory设置与exllama内核的兼容性
python server.py `--model` /data/models/llama-2-7b-gptq `--exllamav2` `--gpu-memory` 7168

注意这里的7168是MiB,也就是7GiB。如果之前启动脚本里写了`--auto-devices`,记得把它删掉,否则gpu-memory很可能不会按你给的数值执行。另一个常见问题是端口或API进程没完全退出,导致新配置没生效,改完后最好重启整个服务,而不是只reload模型。

加载后看日志,确认设置真的生效

加载模型后,可以查看text-generation-webui的日志输出,其中会显示ExLlama初始化信息,包括分配的KV缓存大小和实际使用的显存。若日志中出现“ExLlamaV2: Setting max_seq_len to...”或“Allocated memory for weights”等字样,说明内核已正确识别gpu-memory设置。若gpu-memory设置过小,虽然模型能加载,但推理时可能频繁触发显存不足或生成速度极慢,此时可逐步增大gpu-memory值,每次增量不超过512MiB,并反复测试生成响应,直到性能稳定且不报错。

如果日志不是直接打到控制台,可以用tail命令跟踪最近的日志:

tail -f /tmp/text-generation-webui.log | grep -E 'ExLlama|Allocated|KV cache'

看到类似“Allocated memory for weights”这样的行,说明权重已经放进了显存。此时再用nvidia-smi看一眼进程占用,如果显存曲线能稳定在一个区间,而不是瞬间触顶,说明gpu-memory给的比较合适。日志里没有出现ExLlama相关字样时,优先检查启动参数里是否带了-exllamav2,还要确认是不是用了别人封装的启动器,把参数吞掉了。

显存不够时怎么调,边界在哪

ExLlama的gpu-memory并不是越大越好,也不是越小越安全。模型权重本身要占掉一部分显存,KV缓存也需要几百到上千MiB的余量。实际操作中,我一般先按“总显存-500MiB”作为硬上限,再把权重占用估算出来,给KV缓存至少留1024MiB。如果还要同时加载多个LoRA,每个LoRA额外预留256MiB左右。这些预留不会自动算进gpu-memory,需要你手动加进去。

用text-generation-webui加载模型时gpu-memory设置与exllama内核的兼容性

举个例子,8GB显卡跑7B 4-bit模型时,常见的安全区间在6.2GiB到7.2GiB之间,但具体数值取决于量化格式、上下文长度和是否加载LoRA。建议用较小的gpu-memory值先加载,然后跑一次稍长的生成,观察日志里的峰值显存,再往回调整。每次调整幅度控制在512MiB以内,避免一次加太大又触发OOM。

两个容易忽略的坑:gpu-layers和容器环境

很多从llama.cpp转过来的人会把gpu-memory和gpu-layers搞混。gpu-layers表示卸载到GPU的层数,但ExLlama要求模型全部驻留显存,不支持层数卸载。所以text-generation-webui里给ExLlama内核设置gpu-layers是没有意义的,写了也等于没写。启动参数里只需要管gpu-memory,不需要给层数。

另一个容易被忽略的是容器环境。Docker使用时,如果`--gpus`选项没有限制显存,容器内看到的显存还是宿主机那块卡的全部。但ExLlama拿到的显存信息可能和宿主机驱动状态不一致,这时gpu-memory设得再准也可能报错。建议在容器里先跑一下nvidia-smi,确认可见显存大小,再按这个值重新计算gpu-memory,不要把宿主机的数值直接搬进去。

docker run `--gpus` device=0 -it `--rm` `--ipc`=host -v /data/models:/models mytextgen python server.py `--exllamav2` `--gpu-memory` 6144

如果docker启动命令里已经限制了device,但nvidia-smi显示的还是全部显存,多半是容器运行时配置问题。先解决容器可见显存,再回来调gpu-memory,否则两边数据对不上,后面排查会很绕。