WorldCast 这类项目最容易出问题的地方，是拿自己的提示词直接去试，然后对着报错猜：到底环境没装好，还是模型本来就这样。更省时间的顺序是：先把依赖按仓库说明装完并记下版本组合，再让仓库自带示例脚本完整跑一遍，两步都过了再换自己的提示词。这是因为示例脚本用的是仓库作者维护过的默认输入和默认参数，一旦示例失败，原因基本落在环境、显存或模型加载这几种情况上，与你的提示词无关；而示例通过、换成自己的输入才失败，问题范围就缩小到输入格式和生成参数。

建议把 WorldCast 的排查顺序固定成三段：装依赖并留版本基线、跑通仓库自带示例、最后才替换成自己的提示词。前两步都过，说明环境和模型加载这一层没问题，此时生成效果不理想才适合归到提示词或参数上。任何一步失败，先用日志判断是依赖冲突、显存不足还是参数越界，不要先去改提示词。

按仓库说明安装依赖并记录安装成功的版本组合

依赖安装的目标是留下能回溯的环境基线，仅仅“装完能 import”是不够的。下一轮出问题时，你要能回答：那次成功跑通时，Python、CUDA、torch 和仓库代码分别是哪个状态。

读依赖清单建议按这个顺序：先看 README 里讲环境要求的那一段，确认推荐用 conda 还是 venv；再看 requirements.txt、environment.yml 或 pyproject.toml 里的依赖声明；然后看 setup.py 或 pyproject 里的 install_requires，排除只在开发时才需要的包；最后翻一遍示例脚本头部的 import，确认有没有清单里漏写的隐式依赖。两组信息冲突时，以 README 给出的安装方式为准，并把冲突点记在笔记里。

记录方式建议在装完、且示例还没跑之前立刻执行一次，把输出和仓库 commit 号放在同一个文件里：

python -V
pip -V
nvidia-smi                 # 记下驱动版本、GPU 型号与显存
pip freeze > env-freeze.txt
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
git rev-parse HEAD > repo-commit.txt

这里只记录实际装到的组合，不用去查“应该装哪个版本”。后续对比时，env-freeze.txt 就是判断“是不是我后来多装了什么”的依据。

跑通仓库自带示例脚本确认模型能正常加载

示例脚本的作用是把环境问题和模型问题分开。跑示例时不要改输入、不要调参数，保持仓库默认值。

cd <repo_root>
python -m venv .venv && source .venv/bin/activate   # 或 conda activate <env>
python examples/<demo_script>.py \
  `--config` configs/<default>.yaml \
  `--output` outputs/demo
echo $?

命令里的脚本名、配置文件名和参数名都要换成仓库里实际存在的名字。成功时的输出通常具备这几个特征：日志里有一行明确表示权重或检查点加载完成，路径指向仓库自带目录；全程没有 Traceback，退出码为 0；outputs/demo 下出现了生成文件，且文件大小不为 0；再用默认参数重跑一次，产物结构一致。

如果示例脚本本身失败，就先停在这里，不要往自己的提示词方向排查。此时问题一定出在依赖、显存或模型文件缺失上。

换成自己的提示词做一次最小生成

最小生成的原则是让变量只有一个：提示词。其他参数先对齐示例脚本的默认值，这样出来的结果好坏才有可比性。

提示词常见的替换位置有三处：示例脚本里写死的 prompt 变量、argparse 里的默认字符串、以及 config yaml 里的 prompt 字段。三处只改一处，并记下改的是哪一个；如果仓库支持从命令行覆盖，优先走命令行，便于回退。

# 通用骨架，字段名按仓库实际配置替换
prompt: "一段城市清晨街景，镜头缓慢推进"   # 长度先控制在示例提示词同一量级
seed: 1234
num_steps: <与示例默认值一致>
batch_size: 1
output_dir: outputs/mine

这一轮只要能做到正常结束、产出文件、日志里没有新的告警，就说明自定义输入链路是通的，可以开始评估生成效果了。效果不理想时，先确认是不是参数低于示例默认值，再考虑提示词本身。

把报错日志按依赖、显存、参数三类归档

同一个报错在三个阶段都可能出现，按类别归档是为了以后能快速定位，而不是严格分类，判断时先按日志里最先出现的那一条归类。

• 依赖类关键词：ModuleNotFoundError、ImportError、undefined symbol、Could not find a version、version conflict、CUDA driver version is insufficient。
• 显存类关键词：CUDA out of memory、device-side assert、allocated / reserved 数字、进程被 Killed（系统内存不足也会走到这里）。
• 参数类关键词：KeyError 或 ValueError 指向某个配置字段、unexpected keyword argument、shape mismatch、dtype mismatch、提示词或序列长度超限。

[类别] 依赖 / 显存 / 参数
[阶段] 安装 / 自带示例 / 最小生成
[命令] 实际执行的完整命令
[日志] 报错首行 + traceback 最后 20 行
[环境] python 版本、torch 版本、GPU 型号与显存、仓库 commit
[已排除] 例如：自带示例脚本用默认参数可正常跑通

归档模板里的“已排除”一行更容易被忽略，却能省去重复排查。比如写上“示例脚本可跑通”，下次再遇到相同报错，就不必从依赖装起。