SD整合包Lora加载不出来？WebUI模型扫描路径排查指南

1. 先说结论：模型"不见了"，九成不是WebUI的锅

把Lora模型文件丢进models/Lora文件夹，回到WebUI点开Lora标签页，结果列表里空空如也——这个场景我在帮人远程排查SD整合包问题时，遇到的频率高到什么程度呢？大概每十个"为什么我的Lora不生效"的问题里，有六到七个都是这个原因。它属于那种看起来玄学、实则极度机械的问题：WebUI没有做任何智能判断，它只是在启动和刷新时扫描固定目录，扫描到什么就展示什么，扫描不到就一片空白。所以当你看到空白列表时，本质上是"扫描链路"在某个环节断掉了，而绝不可能是模型"坏了"这么简单。

这篇内容我想把这条扫描链路完整摊开讲。它适合三类人：刚拿到SD整合包、第一次往里面塞Lora的新手；已经用过一阵、但遇到多盘符多目录就迷糊的中级用户；以及想把自己那套整合包目录理清楚、不想每次都靠重启碰运气的进阶玩家。核心关键词就几个：SD整合包、Lora模型、models/Lora、webui、加载不出来。我会全程围绕这条主线，从原理讲到具体命令，最后给一张可以照着抄的排查表。

需要提前说明一点：下面的排查思路是基于SD WebUI及其各种整合包的常见运行机制总结的，不同整合包的启动脚本封装程度不一样，具体路径和菜单位置会有差异，但底层逻辑是通用的。你理解了逻辑，换哪个整合包都能自己定位问题，而不是每次都在群里问"为什么又没有"。

2. 从原理出发：WebUI到底是怎么"看见"Lora的

2.1 启动阶段：目录注册与路径确定

WebUI启动的时候，会先确定一批"模型根目录"。对于Lora来说，默认根目录就是整合包根路径下的models/Lora。注意这里的写法，官方代码里这个目录名首字母是大写的Lora，在Windows上大小写不敏感，所以models/lora、models/LORA都能被识别；但如果你把整合包放在Linux服务器或者WSL环境下跑，大小写就变成硬性条件了，models/lora会直接扫不到，这是一个很多人栽过跟头的地方。

启动阶段还有一个容易被忽略的细节：WebUI是通过一个配置对象把"哪个文件夹对应哪种模型"登记下来的，这个登记表可以被命令行参数覆盖，也可以被一个叫extra_model_paths.yaml的配置文件追加。也就是说，你眼睛看到的models/Lora未必是程序真正读取的目录。如果你的整合包是用某个启动器二次封装的，启动器很可能在脚本里塞了--lora-dir参数，把Lora目录指到了别处，你往默认目录放文件，自然是白放。

所以排查的第一步思维不是"文件放对没有"，而是"程序认为的目录到底是哪个"。这个顺序一颠倒，很多人就会在错误的目录里反复折腾。

2.2 运行阶段：列表构建与前端渲染

启动完成后，WebUI会在内存里维护一份模型清单。这份清单在几个时机被重建：程序启动时、你点击Lora标签页右上角那个刷新按钮时、以及切换模型/重载UI的某些操作时。清单重建的过程就是遍历目录、过滤后缀、读取文件信息，然后把每一项渲染成前端的一张卡片。

这里有两个关键点。第一，遍历通常是非递归或者有限递归的，取决于WebUI版本。早期版本的Lora扫描不进入子文件夹，所以你把文件放在models/Lora/我的收藏/xxx.safetensors这种嵌套结构里，它就看不见；较新版本支持子目录递归，但整合包版本参差不齐，很多人的整合包还是老内核。第二，后缀过滤是有白名单的，常见的是.safetensors、.ckpt、.pt，如果你的文件后缀不在白名单里，比如下载工具给它加了尾巴变成.safetensors.part，那它会被直接跳过，连报错都不给。

理解了这两点，你就能明白为什么"文件明明在那里"和"界面里没有"可以同时成立——它们本来就是两套东西，一个是文件系统层面的事实，一个是程序内存清单层面的事实，中间隔着扫描逻辑这道闸门。

2.3 六类典型断点速查表

把断点归类，能省下大量瞎试的时间。下面这张表是我自己排问题时的固定顺序，从高概率到低概率排列：

这张表的价值在于，它把"加载不出来"这个模糊描述拆成了六个可验证的具体假设。排查的本质就是逐个证伪，而不是把文件删了重下——我见过太多人一上来就重新下载模型，结果下了三遍还是不行，因为问题根本不在文件上。

3. 手把手排查：从文件到界面的五个关卡

3.1 第一关：确认手里的是不是真正的Lora文件

这一步听起来废话，但真的有人把大模型主模型（通常几个GB）、VAE、Embedding文件丢进Lora目录，然后奇怪为什么显示出来的东西不太对。Lora文件有个非常朴素的判断标准：体积通常在几十MB到几百MB之间。如果文件只有几KB，那多半是下载中断留下的残片；如果文件有好几个GB甚至十几GB，那几乎肯定是主模型或者某个大体积组件。

在Windows上，最快的验证方式是在资源管理器里把"查看"选项卡里的"文件扩展名"勾上，同时把"隐藏的项目"也打开。你会立刻发现两种情况：一种是文件名显示为xxx.safetensors，正常；另一种显示成xxx.safetensors.txt或者xxx.safetensors.crdownload，这就是浏览器或下载工具没改完名的临时文件，WebUI当然不认。

顺带说一句，很多人纠结.ckpt和.safetensors的区别。简单讲，.safetensors只存张量数据，加载时不执行代码，更稳妥；.ckpt是序列化对象，理论上携带可执行内容。现在的Lora作品绝大多数发的是.safetensors，如果你的整合包内核特别老，反而可能只认.ckpt，这时候不是文件的问题，是版本的问题。判断方法很简单：换一个确定能用的.safetensors放进去，如果它也不显示，那就往版本和路径方向查。

3.2 第二关：路径、大小写与目录层级

这一关是重灾区。先确认整合包根目录结构，标准的形态是这样：

sd-webui-xxx/ ├── webui-user.bat ├── launch.py ├── models/ │ ├── Stable-diffusion/ │ ├── Lora/ <- Lora放这里 │ ├── VAE/ │ ── embeddings/ └── extensions/

最容易出问题的是"多套了一层"。有些人解压整合包时选择"解压到当前文件夹"，结果变成sd-webui-xxx/sd-webui-xxx/models/Lora，而启动脚本在外面那层，实际的models/Lora是一个空目录。这种情况在磁盘里看路径是对的，但相对于程序的工作目录就是错的。

另一个经典坑是"自建子文件夹"。为了分类，很多人会在Lora下再建"人物""风格""服装"等文件夹。这时候要看你整合包的内核版本：支持递归的版本能扫到，不支持的版本一个都看不见。我的建议是，如果不确定版本，先把文件直接放在models/Lora一级目录下测试，能出来再考虑分类。分类这件事本身有价值，但必须建立在"扫描确实递归"这个前提上，否则就是给自己挖坑。

在命令行里验证路径是最干脆的。Windows下用PowerShell或CMD：

# 进入整合包根目录后执行 dir models\Lora # Linux / macOS / WSL ls -lh models/Lora

如果这条命令列出来的文件和你以为的不一致，那问题就锁定了，不用再往下瞎猜。我习惯在排查时先把这条命令跑一遍，输出直接截图，比自己回忆"我到底放哪了"靠谱得多。

3.3 第三关：扩展名与文件名的隐藏陷阱

文件名这一块有三个常见雷区。第一是中文名与特殊字符。绝大多数字体和编码环境下，中文文件名本身是能显示的，但一旦名字里混进了空格、中括号、井号、百分号这些字符，某些版本的WebUI在读取元数据时会出错，表现可能是卡片显示了但缩略图空白，也可能是干脆不显示。稳妥的做法是改成纯英文加数字和下划线，比如character_style_v1.safetensors。

第二是名字过长。有些模型站导出的文件名是一长串带作者名和日期的组合，超过一定长度后，在深层路径下可能触发路径总长度限制，尤其在Windows上如果不开启长路径支持，读取会静默失败，不报错。这种情况的表现非常迷惑：文件明明存在，程序也不报错，就是不显示。缩短文件名往往能立刻解决。

第三是同一目录下的重名。如果两个Lora文件内容不同但文件名相同（一个来自A，一个来自B），系统可能只列出其中一个，或者列表里出现重复项。这个不算严重问题，但会让你以为"我明明放了五个，怎么只显示四个"。

提示：改文件名时，务必保留.safetensors后缀，并且不要用系统自带的"重命名"把后缀一起改掉。Windows默认隐藏扩展名，改完可能变成character_style_v1.safetensors.safetensors，这是最隐蔽的一类错误。

3.4 第四关：刷新、缓存与重启的正确顺序

WebUI的刷新机制不是实时的。你在外部往目录里加文件，程序不会收到任何通知，因为大多数整合包没有做文件系统监听。所以正确顺序是：

1. 打开WebUI的Lora标签页，先点一次刷新按钮，等两三秒。
2. 如果没出现，切换到别的标签页再切回来，看列表有没有变化。
3. 还是没有，直接关掉控制台窗口，重新双击启动脚本，等完全起来后再看。
4. 重启后依然没有，再往下查配置。

为什么不建议一上来就重启？因为重启很慢，而刷新按钮只要几秒钟。更关键的是，如果刷新能出来，说明是缓存问题；如果刷新不出来但重启能出来，说明是启动扫描的有效性问题；如果两者都出不来，方向就锁定在文件本身或者路径配置上。这个顺序其实是在用一个廉价操作获取诊断信息，而不是单纯"试试看"。

顺便说一个浏览器侧的坑。有些整合包会缓存前端页面资源，你重启了后端，但浏览器用的还是旧的页面脚本，导致列表里依然没有新增项。这时候按Ctrl+F5强制刷新页面，或者在无痕窗口打开，往往能解决。这个坑我踩过至少两次，每次都是折腾半天配置，最后发现是浏览器的事。

3.5 第五关：命令行参数与自定义路径配置

如果前面四关都过了还是不显示，那基本就是程序读取的目录和你以为的不是同一个。查两个地方。

第一是启动脚本。打开整合包根目录下的.bat或.sh启动文件，用记事本看一眼里面有没有类似这样的参数：

--lora-dir "D:\some_other_path\Lora"

只要出现这个参数，程序就会去别的目录找，默认的models/Lora就变成摆设了。有些启动器为了把模型统一放到一个大盘，会默认加这类参数，包装得很隐蔽。

第二是配置文件。整合包根目录或者config目录下可能有一个extra_model_paths.yaml，内容形如：

a1111: base_path: D:/SD_Models/ loras: loras

这段配置的意思是，除了默认目录，再去D:/SD_Models/loras里找一遍。注意这里的字段名是loras而不是Lora，这是配置文件的约定，和目录名不是一回事，别被绕晕。

排查到这里，如果发现有额外路径配置，两条路都放着试一遍，哪个能出来就以哪个为准。我个人更推荐把模型集中到一个固定大盘，然后通过这个配置文件挂载，理由写在下一章。

4. 进阶配置：多目录挂载与整合包环境适配

4.1 extra_model_paths.yaml 的正确写法

模型多了之后，models目录会膨胀到几十上百GB，如果整个整合包放在系统盘，很快就会爆盘。这时候把模型挪到数据盘、通过配置挂载是最省事的做法。一个可用的配置长这样：

a1111: base_path: "E:/AI_models/" checkpoints: "stable-diffusion" vae: "vae" loras: "lora" embeddings: "embeddings" controlnet: "controlnet"

base_path是根路径，下面的每一项都是相对这个根的子目录。写的时候有几个细节要盯住：路径分隔符用正斜杠/最稳，反斜杠在YAML里有转义风险；路径末尾不要多加空格，YAML对缩进和尾随空格敏感；中文路径能不用就不用，省得在一堆编码问题上浪费时间。

配好之后重启WebUI，控制台里通常会打印出读取到的模型路径。如果控制台里根本没出现你配置的那条路径，说明YAML没被正确加载，可能是文件名不对、位置不对，或者缩进写坏了。这一步的反馈很明确，比界面上的空白列表好判断得多。

一个实际经验：配置生效后，默认目录和额外目录是叠加关系而不是替换关系。也就是说，你原来放在models/Lora里的东西依然会被读，两边的模型会合并在同一个列表里。所以如果你发现列表里出现了重复项，多半就是两边都放了一份同名文件，删掉一边就行。

4.2 整合包的特殊性：启动脚本与虚拟环境

整合包和官方源码部署最大的区别，是整合包帮你把Python环境、依赖、启动参数全封好了。好处是开箱即用，代价是你不知道它到底动了哪些手脚。常见的手脚包括：自带一个嵌入式Python、预置一批启动参数、把工作目录切换到自己内部、甚至自带一套模型路径映射。

这带来一个直接后果：你在整合包目录里看到的路径，未必是程序运行时的相对路径。如果启动脚本里有类似cd /d "%~dp0"的语句，那工作目录就是脚本所在目录，没问题；如果没有，而你又是从别的地方双击启动的，相对路径就会跑偏。判断方法是在启动后的控制台日志里找几行关键信息，比如它打印的模型路径、配置加载路径，这些行会直接告诉你真相。

另外，整合包升级内核时，如果只覆盖了部分文件，可能出现配置文件里记录的是旧路径、新内核用的是新目录的情况。表现就是"以前能用，升级后不能用了"。这种情况下，把配置文件和模型目录对照着看一遍，通常能找到矛盾点。

4.3 权限、盘符与中文路径

剩下三类问题属于环境层面的，概率不高但确实存在。

权限问题：如果模型放在某个受保护目录，或者从别的机器拷贝过来时继承了奇怪的权限，程序读取会失败。Windows下可以通过文件属性的"安全"标签检查；Linux下用ls -l看权限位，正常应该是当前用户可读。拷贝来的文件在新环境下出现"能看见文件但读不出内容"的情况，优先怀疑权限。

可移动盘符：把模型放在U盘或移动硬盘上，盘符在每次插拔后可能变化，导致原来的路径失效。这类问题排查起来非常气人，因为上次明明好好的。固定盘符或者干脆把模型放到本地固定盘，是最省心的方案。

中文路径：整条路径里只要有一处中文，就可能在某些编码转换环节出问题。这个不是必然发生，但一旦发生就很难定位，因为它在文件系统层面完全正常。我的习惯是整合包路径、模型路径、用户名路径全部保持英文，从源头规避。

5. 模型显示之后：显存、权重与预览图那些事

5.1 Lora显存占用到底怎么算

很多人问过，加载一个Lora会不会额外吃很多显存。简单讲，Lora的原理是在原有的大权重旁边挂一对低秩小矩阵，推理时把它们的乘积按缩放系数加到原权重上。这对矩阵有多小呢？取决于秩（rank）和注入的层数。常见绘画Lora的秩在4到128之间，文件体积从十几MB到两三百MB不等。

显存占用大致可以这样估：加载权重本身占用的大小≈文件体积（转为对应精度后浮动）；推理时每步计算注入项会产生一定的临时开销，通常在百MB量级。所以在常见的8GB显存环境下，同时挂三到五个Lora一般能撑住，挂太多或者和ControlNet、高分辨率修复叠在一起时才会吃紧。真遇到显存告急，优先降分辨率和批次数，而不是先怀疑Lora。

一个实操上的取舍：多个Lora叠加时，权重系数（在界面里通常表现为一个0到1之间的数值）不要都给满。我个人的习惯是把主风格的那个给0.7到0.8，辅助的给0.3到0.5，这样既保住风格又能避免画面糊掉。这个不是硬规则，是大量试出来的手感。

5.2 预览图与元数据：让列表好看又好认

模型能显示之后，下一步就是让它"好认"。默认情况下列表里只有文件名，模型一多根本记不住谁是谁。可以手动给每个Lora配一张同名预览图，放在同一目录下：

models/Lora/ ├── style_a.safetensors ├── style_a.png <- 同名图片 ├── style_b.safetensors ── style_b.png

图片格式用png或jpg都行，文件名必须和模型文件完全一致，只有后缀不同。命名对了，刷新之后卡片上就会显示缩略图。这个技巧很多人不知道，导致列表常年是清一色的文件名，用起来很累。

有些模型文件内部自带触发词等元数据，WebUI能读出来并显示在卡片上，点一下就能插入到提示词框里。如果读不出来，通常说明文件本身没写这些信息，或者你的内核版本不支持解析这种格式，不是文件损坏。这一点要在心里分清，避免误删好文件。

5.3 顺带聊聊大语言模型侧的LoRA显存估算

同属LoRA这个概念，在大语言模型微调场景下的显存需求和绘画场景完全不是一个量级，经常有人把两边搞混。这里给个粗略的估算框架，方便你在做技术选型时有个大概预期。

微调时显存的主要来源有：模型权重本身、可训练的LoRA参数、优化器状态、以及前向激活值。以9B规模模型为例，用半精度加载权重大约需要18GB上下；LoRA本身因为只训练低秩矩阵，参数量占比通常不到百分之一，优化器状态也相应很小，但激活值是个变量，跟序列长度和批次大小强相关。综合下来，在开启梯度检查点、小批次的配置下，单卡24GB级别通常能跑起来；如果再用4位量化加载底座，显存需求能压到8到12GB区间。序列越长、批次越大，激活值线性甚至平方级增长，这就解释了为什么同一个模型有人能跑有人跑不动。

embedding模型微调的情况又不一样，它的层数和隐藏维度通常小得多，同样的配置下压力小很多。这块具体数值依赖框架实现和优化器选择，上面给的只是量级参考，实际跑之前建议先用一个极小的步数试跑，看显存监控曲线再决定正式配置。

6. 常见问题速查表与踩坑心得

6.1 一份可以照着走的排查清单

把前面所有内容压缩成一张按顺序执行的清单，照着走基本能覆盖九成以上的情况：

这张表的设计逻辑是"从内到外、从廉到贵"：先排除文件自身问题，再看路径，再看程序配置，最后才动环境。每一步都有明确的通过标准，避免陷入"试了半天不知道到底改了什么"的状态。

6.2 几条我踩出来的实战心得

第一条，先复制一个已知能用的模型做对照实验。当你怀疑路径配置有问题时，最快的方法是把一个确认能显示的Lora复制到新目录，看它在新位置能否出现。能出现说明新路径可用，不能出现说明新路径本身有问题。这个操作比读十遍文档都快，因为它把变量控制到了单个。

第二条，不要迷信"重装能解决一切"。模型加载不出来这个问题，重装整合包通常解决不了，因为问题大概率不在程序而在你的操作路径上。重装之后你还是会往同一个地方放文件，还是会遇到同一个问题。花半小时理清目录结构，回报远高于重装一整天。

第三条，给模型库建个索引习惯。我自己的做法是在Lora目录旁边放一个文本文件，记录每个模型的来源页面、推荐权重、适配的风格。模型数量上去之后，这份索引的价值会指数级上升，尤其是隔了几个月再回来用的时候，光看文件名根本想不起来每个是干什么的。

第四条，分类文件夹可以建，但要在确认递归可用之后再建。先放一级目录验证，再逐步挪进子目录，每挪一次刷新一次。这样一旦出问题，你能立刻知道是哪一步引入的。一次性建好所有分类目录再批量挪文件，出问题时排查范围就大了。

第五条，留意启动日志里的路径打印。大多数整合包启动时会在控制台输出模型扫描的路径和数量。养成看一眼的习惯，很多时候问题在日志里已经有提示了，只是没人看。日志里写了"找到 0 个 Lora"和"找到 12 个 Lora"，这两种情况指向的排查方向完全不同。

我自己处理这类问题的感受是，它本质上不是技术难题，而是信息不对称：程序知道的事和你知道的事不在一张纸上。你要做的就是把这两张纸对齐，而对齐的抓手就是那条从文件到内存清单的扫描链路。把链路里的每个环节都变成可验证的，问题自然就浮出来了。模型加载不出来这件事，从来都不是"玄学"，只是暂时没找到那个断点而已。