先跑通一条最小出图链路——再谈 MOSS-Image 的参数细调

拿到 MOSS-Image 仓库后直接照抄一长串参数，出图失败时最难判断的是：到底是依赖没装对、模型路径写错，还是某个采样参数越界。更稳妥的顺序是先把一条最小链路跑通——装依赖、写最小配置、生成一张图、确认文件落盘；链路确认无误，再把参数一个一个加回去，这样每次出错都能定位到具体一层。

判断链路是否跑通，不看「运行不报错」，而看三件事：日志里出现模型加载完成、生成过程结束、写文件成功；产物目录里确实多出一个图片文件；这个文件能被正常打开且尺寸符合预期。这三个条件都满足之前，调采样步数、分辨率、引导系数都是在给变量叠加噪声。建议先用仓库自带示例脚本跑通，再按「一次只改一个参数、保留每轮产物」的方式往上叠。

按仓库说明装依赖，核对 Python 与主要库的版本

这一步的目标只有一个：先排除环境层面的不匹配，避免把装错包、装错版本当成模型问题去查。安装以仓库 README 或 requirements 文件为准，不要凭印象装一套自己熟悉的包。

cd MOSS-Image
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
# 若仓库是包形式，再补一步（以 README 为准）
# pip install -e .

装完立刻核对版本，把输出贴进出图记录里，后续出问题可以直接对比：

python -V
pip list | grep -Ei 'torch|transformers|diffusers|accelerate|safetensors|pillow'
python -c 'import torch; print(torch.__version__, torch.cuda.is_available())'

重点看三处：Python 大版本是否落在仓库说明支持的区间；torch 与 CUDA 驱动是否匹配；diffusers、transformers 这类库是不是被其他环境残留的旧版本顶替。报错时不要只看最后一行，把原始提示完整保留下来，常见的几类差别很大：ModuleNotFoundError: No module named 'xxx' 属于依赖缺失；ImportError 带 undefined symbol 之类字样，通常是二进制与 torch 版本不配套；CUDA out of memory 或驱动版本提示，属于设备侧问题，和参数无关。这几类错误的处理方向完全不同，混在一起查会浪费很多时间。

准备一份最小配置或示例脚本，只保留模型路径和输出目录

先把变量压到最少，让第一次运行只回答一个问题：链路通不通。建议单独建一份最小配置文件，不要直接改仓库里的默认配置，后面调参时还需要一个干净的基线。字段名以仓库实际配置文件为准，下面只是一个形态示例：

# configs/min_run.yaml（字段名请对照仓库示例配置）
model_path: /data/models/MOSS-Image   # 权重所在目录，需与 README 描述的目录结构一致
output_dir: ./outputs/min_run          # 产物落盘目录，先手动建好或确认程序可创建

两个字段各自的作用要清楚：model_path 指向的是权重目录本身，不是某个分片文件名，多分片模型写错一层就会在加载阶段报找不到文件；output_dir 用相对路径时，相对的是执行命令时的工作目录，换目录跑就会把图写到别处去，所以第一次建议用绝对路径或固定在一个位置执行。如果仓库的示例脚本只接受命令行参数，那就对应成 `--model-path` 与 `--output-dir`，不必强套配置文件。文本提示词这一步暂时从命令行传入，不算需要细调的参数。

跑一次单图生成，确认产物落到预期目录且能正常打开

用一个固定的、结构简单的提示词跑单张图，方便肉眼判断结果是否明显异常，比如纯色背景上一个物体。命令形如：

python scripts/infer.py \
  `--config` configs/min_run.yaml \
  `--prompt` 'a red apple on a wooden table'

运行时盯日志里的几类关键行，具体文案以仓库实际输出为准，但信息类型通常是这几种：加载模型时打印的权重路径与加载耗时；设备与精度提示（cpu / cuda、fp16 / fp32）；采样进度条是否从头走到尾；最后一行形如 saved to ... 的写文件记录。如果进度条走完却没有 saved 行，问题在保存环节而不是生成环节；如果加载阶段就中断，回到上一节查依赖和路径。

然后不看日志，直接检查文件本身：

ls -l ./outputs/min_run
file ./outputs/min_run/*.png
python -c "from PIL import Image; im=Image.open('./outputs/min_run/xxx.png'); print(im.size, im.mode)"

文件大小为 0 字节、目录里只有中间态文件、或者图片能打开但尺寸和配置里的分辨率对不上，都说明链路还没真正通，此时不要继续加参数。确认这一张图没问题后，把它连同命令、配置、日志一起留作基线，后面每一轮改动都和它对照。

在跑通的链路上一次只加一个参数，记录每次改动后的变化

调参的价值来自参数与结果的对应关系，而不是参数本身有多花哨。做法是固定基线，每轮只改一个值，产物按可识别的名字存下来，比如 step_20.png、step_40.png、size_512.png，这样回头对比时不用靠记忆。下面是一份按此顺序推进的改动清单，顺序可以按仓库实际情况调整：

随机种子 seed：先固定成同一个值，保证后续对比里只有你改的那一项在变，这是其余所有对照的前提。
采样步数 steps：从小到大各跑一次，观察画面结构是否收敛、耗时如何增长。
输出尺寸 / 分辨率：单独改这一项时同时留意显存占用和显存不足的报错。
引导系数（guidance / CFG 一类）：观察提示词贴合度与画面是否出现过硬、发灰等变化。
批量数或并发数：最后再动，这一项最容易和显存、显存碎片纠缠，留到链路稳定之后。

每轮都填一条记录，宁可只记关键项，也不要凭印象总结：

轮次与改动项：本轮只改了哪个字段，改动前后的取值。
完整命令与配置文件：保证别人能复现同一轮结果。
日志里的关键行：加载耗时、采样是否走完、最终保存路径。
产物文件名与文件信息：尺寸、格式、肉眼可见的差异点。
异常与回退：是否出现显存报错、黑图、尺寸不符；一旦出现，直接退回上一轮基线再改。

如果某一轮结果异常，先用上一轮的配置重跑一次确认可复现，再判断是参数越界还是环境波动。参数名、默认值和取值范围在不同仓库版本间可能变化，取值前回到仓库的配置文件和 `--help` 里核对一次，比照着别人的参数表抄要稳。