笙亿网络策划

Text Generation WebUI 界面卡在加载模型——是显存不够还是模型路径写错？

约 7 分钟读完 1 阅
文章导读
卡在加载模型，多数时候不是浏览器界面坏了，而是后端进程停在一个具体动作上：读权重、往显存搬、或者干脆在等文件。判断顺序建议是先看启动 WebUI 的终端最后一行日志，再查显卡和磁盘占用，最后才去核对路径、加载器和模型文件。这三类原因的现象有重叠，但卡住的位置通常能区分开，先定位阶段再动手，比反复重启有效。
📋 目录
  1. Ⅰ 看控制台最后一行停在哪：读取权重、分配显存还是等待文件
  2. Ⅱ 用 nvidia-smi 和系统内存占用确认是否 OOM 或磁盘读满
  3. Ⅲ 核对模型路径、文件名和权限
  4. Ⅳ 切换加载器或把 GPU 层数调低再试
  5. Ⅴ 用最小模型或已知可跑模型做交叉验证
A A

卡在加载模型，多数时候不是浏览器界面坏了，而是后端进程停在一个具体动作上：读权重、往显存搬、或者干脆在等文件。判断顺序建议是先看启动 WebUI 的终端最后一行日志，再查显卡和磁盘占用，最后才去核对路径、加载器和模型文件。这三类原因的现象有重叠，但卡住的位置通常能区分开，先定位阶段再动手，比反复重启有效。

如果终端停在 CUDA out of memory，或显存占用涨到某个值后不再变化，优先按显存不足处理；如果停在 Loading checkpoint shards、mmap、reading tensors 这类读取阶段，先核对模型路径、文件名和读权限；如果日志里连模型名都没打印出来，多半是路径没接上或加载器选错。拿一个小模型做交叉验证，能较快区分是模型文件问题还是环境问题。以上判断要结合本机日志和 nvidia-smi 输出确认，不要单凭页面转圈下结论。

看控制台最后一行停在哪：读取权重、分配显存还是等待文件

浏览器页面只有一个转圈或加载条，真正的位置在启动 WebUI 的那个终端里。建议启动时就开着终端，点击 Load 后不要刷新页面，先看终端有没有新行输出。

常见关键字大致分几类：

  • 读取权重阶段：Loading checkpoint、Loading model、gguf_init、map file、reading tensors、Loading shards 1/N。
  • 显存分配阶段：offloading、offload_layers、allocating、kv cache、CUDA、cudaMalloc、ggml_cuda、OOM。
  • 等待文件或路径阶段：日志只打印了模型名或可用模型列表，之后长时间没有新内容。

复现步骤：重启 WebUI 时加上 `--verbose`，或按实际界面和启动脚本开启更详细日志；记下点击 Load 的时间，观察三十到六十秒。十几秒内完全没有新行，先怀疑路径扫描或加载器没接上；日志在逐层 offload 之后停住，方向偏显存。

用 nvidia-smi 和系统内存占用确认是否 OOM 或磁盘读满

卡住时另开一个终端，不要关掉原进程。GPU 侧可以看：

watch -n 1 nvidia-smi
nvidia-smi `--query-gpu`=memory.used,memory.total,utilization.gpu `--format`=csv

系统侧可以看：

Text Generation WebUI 界面卡在加载模型——是显存不够还是模型路径写错？
free -h
df -h /
iostat -x 1
dmesg | tail -n 50

观察时机很关键：显存占用持续上涨然后停住，常见于分配到一半失败；显存从头到尾几乎不动，说明还没进入 GPU 阶段，问题更可能在读文件或加载器。若 dmesg 出现 Killed process 或 Out of memory，通常是系统内存被吃满，和显存不足不是一回事。磁盘方面，df -h 看分区是否接近满，iostat 看 %util 和 await 是否长时间偏高；模型放在网络盘或机械盘时，读权重本身就会慢，加载时间会明显拉长。

核对模型路径、文件名和权限

路径问题容易被界面掩盖。建议直接用命令行确认加载器实际能看到什么：

ls -lh /path/to/models
readlink -f /path/to/models/your-model
stat /path/to/models/your-model
namei -l /path/to/models/your-model

常见路径写法：绝对路径最稳，例如 /home/user/models/xxx.gguf；相对路径在不同加载器下基准目录可能不同，有的相对 WebUI 根目录，有的相对 models 目录，容器部署还要注意挂载后的容器内路径。Windows 下注意反斜杠和大小写，从别处复制过来的文件名可能带多余后缀或空格。

权限验证：用运行 WebUI 的同一个用户去读，例如 sudo -u webui-user test -r /path/to/model && echo ok，或者直接读取文件开头几 KB，看是否报 Permission denied。目录需要可执行权限才能进入，必要时用 chmod 或 chown 调整，但不建议把整个模型目录设成 777。

Text Generation WebUI 界面卡在加载模型——是显存不够还是模型路径写错？

切换加载器或把 GPU 层数调低再试

同一个模型文件，不同加载器对显存和文件格式的要求不一样。界面里常见的加载器选项包括 llama.cpp、llama.cpp_HF、ExLlamav2、ExLlamav2_HF、Transformers、AutoGPTQ、GPTQ-for-LLaMa、AutoAWQ、HQQ 等，具体名称以下拉框实际显示为准。GGUF 一般走 llama.cpp，GPTQ 走 AutoGPTQ 或 ExLlama，加载器选错时可能出现能识别文件但加载不动的情况。

参数骨架大致如下，仅作填写位置参考：

`--model` /path/to/model.gguf
`--loader` llama.cpp
`--n-gpu-layers` 20
`--n`_ctx 2048
`--threads` 8

操作顺序建议：先把 n-gpu-layers 调低，例如从全部层数降到 10 或 0，让模型主要跑在 CPU 上。如果这样能加载成功，说明显存是主要限制；如果仍然卡在同一位置，就更像加载器不匹配或模型文件本身有问题。改完参数重新 Load，再回终端对比最后一行日志是否变化。

用最小模型或已知可跑模型做交叉验证

拿一个体积小的 GGUF 模型，例如 1B 到 3B 的 Q4 量化文件，放到同一个 models 目录，用同样的加载器和接近的参数加载。这是判断模型文件问题还是环境问题最直接的方式。

  1. 把最小模型路径填进模型输入框，保持加载器不变，n-gpu-layers 先设为较小值。
  2. 点击 Load，记录三项：是否成功、终端最后一行日志、nvidia-smi 显存峰值。
  3. 换回原模型，参数保持一致，再记录一次。

分支处理：小模型能跑、原模型卡住，优先检查原模型是否下载完整、量化格式是否被当前加载器支持、以及原模型需要的显存是否超出本机；小模型也卡住，则回到路径、权限、加载器版本和 Python 依赖层面排查。文件完整性的简单验证是比对文件大小与来源页面标注的字节数，或用 sha256sum 与来源提供的校验值对照，没有校验值时就重新下载一次再试。