模型文件已经下载到本地，前端下拉框里却看不到「FLUX 3 Image Klein」，或者一点加载就提示找不到文件，这类情况多数不是采样参数的问题，而是权重文件没有放在前端实际扫描的目录里。可以先确认前端扫描的是哪个目录，再按目录约定把文件放进去，然后刷新节点列表，最后用一个最小工作流把加载链路走通；参数调整留到这一步之后。

遇到模型名不出现或报找不到文件，先查加载路径，不要先动参数。做法是：从启动日志或服务输出里找到模型搜索目录那一行，复制该路径去文件系统核对，按前端约定的子目录和扩展名放好权重，刷新节点列表确认模型名出现，再用最简工作流出图验证。适用场景是本地或自建服务；如果前端跑在容器里或额外指定了模型目录，以实际运行环境的挂载路径为准。

在启动日志里找到模型查找路径那一行

很多人的误区是拿自己下载文件的目录当答案，例如把权重丢在 ~/Downloads 或桌面，然后在界面里刷新半天。刷新只重新扫描前端配置的目录，扫描范围之外的文件夹放多少文件都不会被识别。

启动服务时，终端通常会打印若干条包含 model、path、search、extra_model_paths 字样的输出行，其中就有当前生效的模型根目录以及各子目录的绝对路径。找不到时可以这样过滤：

# 把日志重定向到文件，便于反复查看
python main.py > startup.log 2>&1

# 过滤出与模型路径相关的行
grep -iE 'model|path|search|extra' startup.log | head -n 60

拿到路径后不要凭记忆判断，直接去文件系统核对。把日志里的路径原样复制到终端执行 ls，看目录是否存在、里面有没有你放的文件；也可以反查文件真实落点：

ls -l /日志里给出的模型根目录
find / -name '*.safetensors' -path '*klein*' 2>/dev/null

两条命令的输出互相印证：如果 find 能找到文件，但不在日志给出的目录下，问题就确认是“放错位置”，而不是模型损坏或前端版本不兼容。

按前端目录约定把权重文件放进对应子目录

模型根目录确定之后，还需要放进正确的子目录。不同子目录对应不同类型的加载节点，混放会出现“文件在却扫不到”或者“扫到了但节点不认”的两种情况。常见约定如下，具体名称需要结合你所用的前端版本确认，部分版本会把 unet 改名为 diffusion_models：

文件命名和扩展名同样影响识别：优先使用 .safetensors，文件名避免中文、空格和括号等特殊符号，用短横线或下划线连接；不要为了“看起来像”而手工改扩展名，例如把 .bin 直接改成 .safetensors，这类文件能通过扫描但加载阶段会报格式错误。如果下载的是分片权重，需要把所有分片文件放在同一目录并保持原始文件名，缺一片就会加载失败；下载不完整、体积明显偏小的文件，也建议先校验再排查目录。

刷新后确认模型名出现在可选项里

文件放好后，先做一次刷新，让前端重新扫描目录。界面上通常有刷新节点或刷新模型列表的按钮，点一次即可；如果刷新后仍无变化，就重启服务进程，让启动阶段的扫描逻辑重新执行一遍。

判断依据很直接：在加载节点的模型下拉列表里，能看到目标文件名（多数前端显示为去掉扩展名后的名字）。有三种结果要分开处理：

• 列表里出现目标模型名——路径与命名都没问题，进入下一步验证。
• 列表里没有——回到第一节，确认扫描目录与文件实际所在目录是否一致，以及子目录是否放对。
• 名字出现但选中后报错——说明扫描已经走通，问题在文件本身，重点检查分片完整性、格式与前端版本支持情况。

用一个最小工作流跑出第一张图

这一步的目标不是出好图，而是把“能扫到”推进到“能加载、能推理”。节点连接保持最少：加载主模型的节点接采样器，文本编码器节点接正向与反向提示词，VAE 加载节点接解码，再接一个空 latent 和保存图像节点。链路大致是：

Load Diffusion Model -> KSampler.model
CLIP Text Encode(正向/反向) -> KSampler.positive / negative
Empty Latent Image -> KSampler.latent_image
KSampler -> VAE Decode -> Save Image

必要参数只填几项：采样步数、采样器与调度器、分辨率与批量、随机种子，以及模型要求的引导强度。具体数值以模型附带的说明为准，不要在这一步做参数对比，否则出问题时分不清是路径还是参数导致的。

成功出图的判定标准建议写死三条：控制台或界面没有报错；保存图像节点对应的输出目录里生成了文件；打开文件能看到有内容的画面，而不是纯黑、纯噪点或明显错位的色块。三条都满足，说明加载链路和推理链路都已打通；只满足前两条而画面异常，问题就不在路径上，应转向模型组件是否配套。

把目录约定写进项目说明

这套排查走通之后，建议把结论落到项目里，换机器、换容器或前端升级后可以照单复核，避免重复踩坑。最省事的做法是在模型目录下放一份说明文件，写清目录结构、文件来源和放置规则：

models/
  diffusion_models/   # FLUX 3 Image Klein 主权重，*.safetensors
  text_encoders/      # 文本编码器，与主模型配套
  vae/                # VAE 权重
  loras/              # 适配器，不与主模型混放
# 命名规则：英文小写 + 下划线，不用中文和空格，不改扩展名

再配一份可复用的路径检查步骤，作为排查清单固定下来：查看启动日志中模型路径那一行；用该路径执行 ls 核对目录内容；用 find 反查文件真实落点；确认子目录与文件扩展名符合约定；刷新或重启后确认模型名出现在列表；跑一次最小工作流出图。六步走完仍不成功，再去看模型版本与前端版本的匹配情况，而不是回头怀疑文件名。