拿到 Matrix-Game 4.0 之后，先别急着装依赖。判断本地显卡能不能跑，最省事的顺序是：从项目自带文档里抄出运行前提原文，再在自己的机器上取三组读数——驱动版本、显存总量、运行时里框架能否看到 CUDA 设备——最后拿读数去对照文档。三组值都是命令直接输出的，不依赖猜测，也不依赖别人的配置单。缺什么补什么，缺在驱动、缺在显存、缺在运行库，处理方式完全不同。

Matrix-Game 4.0 能否在本地显卡上跑起来，先看三组可测数据：显卡驱动版本、显存总量、Python 运行时里 CUDA 是否可见。把项目文档中的依赖与显存要求原文摘出来，与实测读数逐条对照，才能判断缺口属于驱动、显存还是运行库。缺口没定位前不建议整条工具链一起升级；读数先落成日志，每次只改一项并复测，日志首屏报错原文是后续排查的基线。

在项目自带说明里定位运行前提条目

同事把仓库拉下来后，先看目录结构，不要凭印象猜依赖。运行前提通常散落在几个固定位置，需要逐个打开确认，并把原文句子摘录到自己的笔记里，不要改写成自己的话，否则后面比对时容易失真。

• README.md：关注 Installation、Requirements、Prerequisites、Quick Start 这类小节。
• docs/：安装页、环境配置页、模型卡说明，常写 CUDA、PyTorch、Python 版本与最低显存。
• requirements.txt、environment.yml、pyproject.toml、setup.py：依赖包名与版本约束的原始出处。
• Dockerfile：基础镜像的 CUDA 版本往往就是作者实际验证过的运行时版本。
• configs/*.yaml、示例脚本：设备、精度（fp16/bf16/fp32）、分辨率、批大小等默认值。

可以先用下面这条命令把候选条目一次性捞出来，再回到文件里核对上下文，避免只看到关键词就下判断：

grep -rn -iE 'cuda|driver|vram|显存|gb|python|torch|conda|docker' \
  README.md docs/ requirements*.txt environment*.yml pyproject.toml setup.py Dockerfile 2>/dev/null | head -n 80

遇到“CUDA 12.x”“PyTorch 2.x”“GPU with N GB VRAM”这类写法，原样抄下来即可。文档没写清最低显存时，不要自己补一个数字，记成“文档未给出，需在启动阶段实测”，后面用日志说话。

用显卡查询命令记录当前驱动与显存状态

这一步的目标是拿到三个可复现的值：驱动版本、显存总量、以及运行时是否真的能看到显卡。先取显卡侧：

nvidia-smi
nvidia-smi `--query-gpu`=name,driver_version,memory.total,memory.used `--format`=csv

输出里需要核对的字段：Driver Version（驱动版本）、CUDA Version（这张驱动支持的最高运行时版本，不是已安装的运行时）、Memory-Usage 中的 Total（显存总量）与 Used（已占用，判断当前是否被别的进程吃掉一部分）。

再取运行时侧，确认 Python 环境里的框架看到的和 nvidia-smi 说的是同一张卡：

python -c 'import torch;print(torch.__version__, torch.version.cuda);print(torch.cuda.is_available());print(torch.cuda.get_device_name(0));p=torch.cuda.get_device_properties(0);print(p.total_memory/1024**3, p.major, p.minor)'
nvcc `--version`
pip show torch | grep -iE 'version|location'

若 torch.cuda.is_available() 返回 False，先不要往下走流程，问题通常卡在驱动分支或容器透传（例如容器启动时没有把 GPU 挂进去）。WSL、容器、多卡机器都要单独确认设备可见性，别拿宿主机的 nvidia-smi 结果直接当成运行时结论。

把文档要求与实测读数逐条对照

把第一步抄下来的要求和第二步入手的读数填进同一张表，一行只判断一件事，缺口归属写清楚，后面调整才有方向。下表是填写模板，第三列填自己的实测值：

对照时的常见误判是把 nvidia-smi 里的 CUDA Version 当成已装运行时。那个数字表示驱动能支持的上限，真正生效的是框架链接的运行时版本，两者要分开看。显存总量够但可用显存不足，属于被其他进程占用，不是环境不兼容。

按缺口逐项调整并复测

一次只动一处，是这一步唯一值得坚持的纪律。同时升级驱动、换 CUDA 运行时、改依赖版本，出了问题无法判断是哪一步生效，也无法回退。用固定命令把改动前后的读数存下来再比对：

nvidia-smi `--query-gpu`=driver_version,memory.total `--format`=csv,noheader > gpu_before.txt
python -c 'import torch;print(torch.__version__, torch.version.cuda)' > rt_before.txt
# 只做一项改动，例如更换对应 CUDA 版本的框架发行包，或升级驱动
nvidia-smi `--query-gpu`=driver_version,memory.total `--format`=csv,noheader > gpu_after.txt
python -c 'import torch;print(torch.__version__, torch.version.cuda)' > rt_after.txt
diff gpu_before.txt gpu_after.txt; diff rt_before.txt rt_after.txt

改动记录建议写成三列：改了什么、为什么改（对应表里哪个缺口）、复测后哪一行输出变了。若缺口在显存，优先按文档给出的配置项降低分辨率或批大小、改用文档支持的半精度，而不是靠系统内存或交换分区兜底；那类做法只是避免立即崩溃，不解决显存不足本身。

用最小参数启动一次并观察日志首屏

环境对齐后，先用最小参数跑一次，只为确认依赖能加载、权重能读、设备能分配，不追求出图质量。参数名以仓库的实际入口为准，先看帮助再拼命令：

python <入口脚本> `--help`
python <入口脚本> `--device` cuda:0 `--batch-size` 1 <最小尺寸相关参数> 2>&1 | tee run_first.log

启动后先看首屏，再看关键行：

sed -n '1,60p' run_first.log
grep -nE 'CUDA|cuDNN|device|Loading|Traceback|Error|out of memory|no kernel image|undefined symbol' run_first.log | head -n 40

需要关注的行包括：CUDA 扩展编译或加载是否通过、权重文件是否被完整读取、设备分配打印的是哪张卡、精度设置是否与配置一致。首屏报错通常落在几类形态上：CUDA out of memory 指向显存或参数过大，CUDA driver version is insufficient for CUDA runtime version 指向驱动与运行时不匹配，no kernel image is available for execution on the device 指向框架编译的算力范围不覆盖这张卡，undefined symbol 指向运行库版本冲突。实际报错以自己日志里的原文为准，把首屏这段连同日期一起留在仓库外的笔记里，后面每次改动都拿它做基线对照，避免重复踩同一个坑。