Soup doctor排错指南：GPU、依赖、环境3类常见报错一键诊断

Soup doctor排错指南：GPU、依赖、环境3类常见报错一键诊断

【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/Soup

Soup是一个"一份 YAML 配置、一条命令微调大模型"的开源命令行工具，其内置的soup doctor健康检查命令可以在 10 秒内自动诊断GPU、依赖、环境三类最常见报错，并直接给出修复命令，是新手训练 LLM 前必跑的第一步（docs/commands.md）。

一键诊断：如何运行 soup doctor

安装完成后，直接在终端输入：

soup doctor

命令会依次输出四个板块：System（Python 版本、操作系统、架构）、GPU、System Resources（内存与磁盘）、Dependencies（22 个依赖包的版本核对表），最后汇总所有问题并附一条"一键修复"的 pip 安装命令。实现逻辑见 doctor.py，官方说明见 docs/backends-and-ops.md。

只要出现红色MISSING、黄色outdated或INCOMPATIBLE标记，照着文末给出的修复提示执行即可。

GPU 类报错：torch 装了 CPU 版、显卡识别不出来

这是新手最高频的坑：nvidia-smi明明能看到显卡，训练却提示没有 CUDA。soup doctor会帮你区分两种情况：

• CPU-only wheel：检测到显卡硬件存在、但当前 torch 是 CPU 构建，报告里会直接给出换装命令（指向 CUDA 12.1 的 torch 轮子）；
• MPS 后端：Apple Silicon 用户会自动识别 MPS 并显示为可用后端；
• 确实没有 GPU：给出"训练将变慢"的黄色警告。

💡 提示：看到 "CPU only" 警告时，按报告给出的pip install torch --index-url ...命令重装带 CUDA 的 torch 即可，无需重装显卡驱动。

多卡用户还可加--nccl参数，实测 NCCL 通信带宽并与 H100 / A100 / RTX 4090 等硬件的理论上限对照，提前发现多卡通信瓶颈。

依赖类报错：版本过旧、缺失或 INCOMPATIBLE

soup doctor会逐一核对 torch、transformers、peft、trl、datasets、bitsandbytes、accelerate 等 12 个必装包与 12 个可选包，状态分三档：

两个细节值得注意：

1. 兼容上限检查：transformers 必须 <6.0.0、peft 与 trl 必须 <1.0.0。PyPI 静默升级导致的"周五能跑、周一就炸"（即所谓 CUDA hell），doctor 会直接标红并给出带区间的安装命令；
2. torchvision 配对检查：torch 2.2 应配 torchvision 0.17.x 等已知兼容组合，版本错位会给出黄色警告。

所有问题修复后重跑soup doctor，看到绿色"All checks passed! Your environment is ready."即代表环境就绪。

环境类报错：内存不足、磁盘类型、双 Python 解释器

环境类问题往往要到训练中途才爆发，doctor 提前暴露它们：

• RAM / Disk：显示可用内存与磁盘剩余空间，容量不足时提前知晓；
• 磁盘介质探测（soup doctor --disk）：Soup 的 Layer Streaming 特性允许 4 GB 显存笔记本训练 8B 模型，其磁盘溢出层需要NVMe硬盘；SATA SSD 与机械盘会被自动拒绝该层。探测一次冷启动约 9 秒，报告结论一目了然；
• 双 Python 解释器警告：当soup运行的解释器与 PATH 上的python不是同一个时，System 面板会黄色提示，避免你用错解释器手动查包时得到"假阴性"结果。

上图即 Layer Streaming 的实际运行预检画面：基座权重驻留内存、逐层喂给 GPU，显存峰值稳定在 3.32 GB——而--disk检查正是为这类工作流做的提前体检。

延伸：另外两个"医生"命令

Soup 还有两个同族命令，可按需使用（docs/commands.md）：

• soup data doctor <数据路径> --model <模型>：训练前检查数据与聊天模板的兼容性，输出 8 项 OK/MINOR/MAJOR 报告；
• soup env lock/soup env check：把当前环境（含 torch、transformers 等 15 个 ABI 敏感包）锁进soup-env.lock，环境漂移时以退出码 3 拒绝训练，适合接入 CI。

小结：遇到 GPU 识别、依赖版本、环境资源三类报错时，先跑soup doctor（需要时加--nccl或--disk），按红色提示逐条修复即可——这正是 Soup "一条命令解决环境疑难" 的设计初衷。

【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/Soup