在搭建本地AI绘画平台时，随着下载的模型数量不断增加，很多用户会遇到一个令人头疼的问题：明明已经将几十GB的模型文件下载到了本地，但在软件的模型选择下拉列表中却怎么也找不到它们。造成这种模型加载路径错误的核心原因，往往是系统默认的存储路径空间不足，用户将模型转移到了其他磁盘或目录，却没有正确告知主程序这些新路径的位置。此时，extra_model_paths.yaml配置文件就发挥了至关重要的作用，它允许我们挂载外部文件夹，让程序能够顺利识别分散在各个硬盘中的模型文件。
为什么需要配置extra_model_paths.yaml
默认情况下，大多数AI绘图软件会将所有模型文件存放在安装目录下的特定文件夹中。例如，主检查点模型通常放在models/checkpoints目录，而LoRA模型则放在models/loras目录。对于普通用户而言，系统盘的空间往往十分有限。当模型库积累到几百GB甚至TB级别时，继续将它们存放在系统盘不仅会拖慢系统运行速度，甚至会导致磁盘空间爆满而引发程序崩溃。
此外，许多开发者会在同一台电脑上安装多个不同的AI绘图环境。如果每个环境都独立保存一份模型文件，将会造成极大的存储空间浪费。通过配置extra_model_paths.yaml文件，我们可以实现一处存储、多处共享。只需将大容量模型统一存放在一个独立的机械硬盘或固态硬盘中，然后让各个环境都指向这个公共路径，既节省了宝贵的磁盘空间，又极大提升了模型管理的效率。
extra_model_paths.yaml 文件结构与语法详解
extra_model_paths.yaml采用YAML语言格式编写，这种格式以易读性著称，但对缩进和格式有着极其严格的要求。该文件的核心作用是定义一个或多个外部基础路径，并将其映射到软件内部的默认模型分类中。在YAML中，层级关系是通过空格缩进来表示的，绝对不能使用Tab键进行缩进，且每层缩进通常为两个空格。
在配置文件中，我们首先需要定义一个顶级节点，这个节点可以是任意名称，通常用来标识你的外部路径来源。在该节点下，base_path字段指定了外部模型的根目录。随后，通过checkpoints、loras、embeddings等子字段，将具体的模型类别映射到base_path下的相应子目录中。如果某个类别的目录结构与默认的不同，也可以单独指定绝对路径。
# 这是一个正确配置extra_model_paths.yaml的示例
another_model_folder:
base_path: D:\AI\Models
checkpoints: checkpoints/
loras: loras/
embeddings: embeddings/
vae: vae/
在上述配置中，程序会将D:\AI\Models\checkpoints\目录下的所有模型文件扫描并加载到界面的检查点列表中。同理，LoRA模型也会从D:\AI\Models\loras\目录中读取。这种映射方式非常灵活，即使你的外部目录命名与软件默认的不一致，也能通过这种键值对的方式进行完美适配。
常见配置错误与避坑指南
尽管配置过程看似简单，但在实际操作中，仍有大量用户因为细节疏忽导致模型加载失败。最常见的一个错误就是路径中的反斜杠问题。在Windows系统中，复制路径时通常会得到带有反斜杠的格式，如D:\AI\Models。虽然在YAML中直接使用反斜杠有时也能被解析，但为了确保最大的兼容性，建议将反斜杠转换为正斜杠（如D:/AI/Models），或者使用双反斜杠（如D:\\AI\\Models）进行转义。不过，在extra_model_paths.yaml的具体实现中，直接使用单反斜杠D:\AI\Models通常也是被支持的，但必须确保路径本身是真实存在的。
另一个高频错误是缩进混乱。YAML对缩进的层级极为敏感，如果父节点与子节点没有对齐，或者混用了空格和Tab键，解析器就会直接报错，导致整个配置文件失效。此外，在键值对中，冒号后面必须紧跟一个空格，例如checkpoints: checkpoints/是正确的，而checkpoints:checkpoints/则是错误的语法。下面是一个典型的错误配置示例：
# 这是一个包含多处错误的配置示例
wrong_folder:
base_path: E:\AI\SharedModels
checkpoints: /checkpoints # 缩进错误，多了一个层级
loras:loras/ # 语法错误，冒号后缺少空格
vae: vae\
上述代码中，checkpoints字段的缩进比base_path多了一级，会导致解析器认为它不属于base_path的子项；而loras字段冒号后没有空格，直接违反了YAML语法规则。遇到模型无法加载时，首先应当检查控制台输出的日志信息，如果提示YAML解析错误，就需要逐一排查这些格式问题。
验证配置是否生效及调试技巧
修改并保存extra_model_paths.yaml文件后，必须完全重启主程序才能使配置生效。仅仅在软件界面点击刷新按钮通常是不够的，因为配置文件的加载发生在程序启动阶段。重启后，打开命令行控制台，仔细观察启动日志。如果配置正确，你会看到日志中打印出类似Adding extra search path的提示信息，并列出你刚刚配置的绝对路径。
如果日志中没有出现这些路径信息，或者程序直接忽略了该文件，首先检查文件名是否拼写正确，确保没有多出空格或变成.txt后缀。确认文件被正确读取后，进入软件界面，在模型加载下拉菜单中查看是否能找到外部目录中的模型。如果路径配置正确但模型仍未显示，可能是因为该模型文件的扩展名不被支持，或者文件本身已损坏。通过遵循上述步骤和规范，你可以轻松管理庞大的模型库，彻底解决路径配置带来的困扰。
extra_model_paths.yaml模型加载路径配置文件修改时间：2026-08-22 02:12:02