MedGemma X-RayCUDA故障排查：nvidia-smi检测与环境变量校验

MedGemma X-RayCUDA故障排查：nvidia-smi检测与环境变量校验

1. 为什么CUDA问题会卡住你的AI阅片流程？

你刚把MedGemma X-Ray部署好，满怀期待地上传第一张胸部X光片，点击“开始分析”——结果页面卡在加载状态，控制台一片沉默。刷新几次后，日志里反复出现CUDA out of memory或Failed to initialize CUDA这类报错。别急，这不是模型不灵，大概率是底层GPU环境没对上。

MedGemma X-Ray不是纯CPU跑的轻量工具，它依赖CUDA加速来实时处理高分辨率医学影像。一旦GPU不可用、显存不足或设备编号错配，整个推理链路就会断在第一步。而这类问题往往不报错在界面上，只悄悄写进日志末尾，让人摸不着头脑。

本文不讲大模型原理，也不堆参数调优，就聚焦一个最常被忽略却最致命的环节：CUDA可用性验证。我们会带你用三步法快速定位——是GPU根本没识别？是显存被占满？还是环境变量悄悄把你引向了不存在的设备？每一步都附可复制粘贴的命令、真实输出样例和一句话判断逻辑，让你5分钟内从“黑屏焦虑”回到“图像秒出”。

2. 第一步：确认GPU物理存在且驱动就绪（nvidia-smi是唯一真相）

所有CUDA问题排查，必须从nvidia-smi开始。它不是Python库，不是Docker配置，而是直接和NVIDIA驱动对话的“听诊器”。只要它报错，后面所有步骤都是空中楼阁。

2.1 执行基础检测

在终端中运行：

nvidia-smi

正常情况（你该看到的）

+-----------------------------------------------------------------------------+ | NVIDIA-SMI 535.104.05 Driver Version: 535.104.05 CUDA Version: 12.2 | |-------------------------------+----------------------+----------------------+ | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. | |===============================+======================+======================| | 0 NVIDIA A10 On | 00000000:00:1E.0 Off | 0 | | 30% 38C P0 28W / 150W | 1245MiB / 23028MiB | 0% Default | +-------------------------------+----------------------+----------------------+

关键看三处：

• 顶部CUDA Version：显示12.2，说明驱动支持CUDA 12.x，与MedGemma要求的PyTorch 2.7兼容（PyTorch 2.7官方编译基于CUDA 12.1+）
• GPU 0行：Memory-Usage显示1245MiB / 23028MiB，证明显存有剩余；GPU-Util为0%，说明当前无其他进程霸占计算单元
• 没有Error字样：底部无NVIDIA-SMI has failed或Unable to determine the device handle等报错

❌ 异常情况及对策

情况A：命令未找到

bash: nvidia-smi: command not found

→ 驱动根本没装。立即执行：

# 检查是否安装了NVIDIA驱动包 dpkg -l | grep nvidia-driver # Ubuntu/Debian rpm -qa | grep nvidia-driver # CentOS/RHEL

若无输出，需手动安装官方驱动（切勿用系统自带的开源nouveau驱动）。下载地址：https://www.nvidia.com/Download/index.aspx，选择对应GPU型号和Linux发行版。

情况B：驱动版本过低

CUDA Version: 11.2

→ PyTorch 2.7需要CUDA 12.1+。升级驱动：

# Ubuntu示例（以535驱动为例） sudo apt update sudo apt install nvidia-driver-535-server sudo reboot

情况C：GPU显存被占满

Memory-Usage: 22980MiB / 23028MiB

→ 显存几乎耗尽。找出占用者：

nvidia-smi pmon -s u # 实时监控各进程显存使用 # 或查看所有GPU进程 nvidia-smi --query-compute-apps=pid,used_memory,process_name --format=csv

常见占用者：Jupyter Notebook、TensorBoard、其他AI服务。用kill -9 <PID>释放。

3. 第二步：校验CUDA环境变量（一个数字错，全盘皆输）

MedGemma X-Ray通过CUDA_VISIBLE_DEVICES=0指定使用第0号GPU。这个变量看似简单，却是故障高发区——它可能被覆盖、拼写错误，或指向一个根本不存在的设备编号。

3.1 检查当前生效的环境变量

echo $CUDA_VISIBLE_DEVICES

正常输出

0

→ 表明应用将使用GPU 0，与nvidia-smi中显示的设备编号一致。

❌ 异常输出及修复

异常1：输出为空

# （空行）

→ 变量未设置。临时生效：

export CUDA_VISIBLE_DEVICES=0

但要永久生效，需写入启动脚本。编辑/root/build/start_gradio.sh，在python命令前添加：

export CUDA_VISIBLE_DEVICES=0

异常2：输出为-1

-1

→ 等同于禁用GPU，强制CPU模式。这会导致MedGemma启动极慢甚至OOM。立即修改：

export CUDA_VISIBLE_DEVICES=0

异常3：输出为1或2

1

→ 你只有1块GPU（nvidia-smi只显示GPU 0），却让程序去找GPU 1。修改为0。

3.2 验证变量是否被子进程继承

环境变量可能在Shell中设置，但未传递给Python进程。我们直接测试：

# 在Python中检查 /opt/miniconda3/envs/torch27/bin/python -c "import os; print('CUDA_VISIBLE_DEVICES:', os.environ.get('CUDA_VISIBLE_DEVICES', 'NOT SET'))"

输出必须是：

CUDA_VISIBLE_DEVICES: 0

如果仍是NOT SET，说明start_gradio.sh中的export未生效，或被后续source命令覆盖。检查脚本中是否有unset CUDA_VISIBLE_DEVICES或重复export。

4. 第三步：交叉验证PyTorch CUDA可用性（绕过一切中间层）

nvidia-smi和环境变量都正常，不代表PyTorch能用CUDA。因为PyTorch有自己的CUDA运行时，可能因版本不匹配而静默失败。

4.1 运行最小化验证脚本

创建文件/root/build/cuda_test.py：

import torch print("PyTorch版本:", torch.__version__) print("CUDA是否可用:", torch.cuda.is_available()) if torch.cuda.is_available(): print("CUDA设备数量:", torch.cuda.device_count()) print("当前设备索引:", torch.cuda.current_device()) print("设备名称:", torch.cuda.get_device_name(0)) # 尝试分配一小块显存 x = torch.randn(1000, 1000).cuda() print("显存分配成功，张量形状:", x.shape) else: print("CUDA不可用，请检查PyTorch安装")

执行：

/opt/miniconda3/envs/torch27/bin/python /root/build/cuda_test.py

全部通过的输出

PyTorch版本: 2.7.0+cu121 CUDA是否可用: True CUDA设备数量: 1 当前设备索引: 0 设备名称: NVIDIA A10 显存分配成功，张量形状: torch.Size([1000, 1000])

→ 恭喜，CUDA链路完全打通。

❌ 关键失败点

失败1：CUDA是否可用: False→ PyTorch未正确安装CUDA版本。卸载重装：

conda activate torch27 pip uninstall torch torchvision torchaudio pip install torch==2.7.0+cu121 torchvision==0.18.0+cu121 torchaudio==2.7.0+cu121 -f https://download.pytorch.org/whl/torch_stable.html

失败2：RuntimeError: CUDA error: no kernel image is available for execution on the device→ GPU计算能力（Compute Capability）与PyTorch预编译版本不匹配。例如A10计算能力为8.6，需CUDA 11.8+编译的PyTorch。此时必须用源码编译或换镜像。

5. 故障树速查：从现象反推根因

当MedGemma启动失败时，按此顺序排查，避免无效操作：

重要提醒：不要跳过任何一步。曾有用户因nvidia-smi正常就直接重装PyTorch，结果发现是CUDA_VISIBLE_DEVICES=1指向了不存在的GPU，浪费3小时。

6. 预防性加固：让MedGemma更健壮

排查不是终点，预防才是关键。以下三处加固，可避免80%的CUDA类故障：

6.1 启动脚本中加入自动校验

修改/root/build/start_gradio.sh，在启动Python前插入：

# === CUDA健康检查 === echo "[INFO] 正在检查CUDA环境..." if ! command -v nvidia-smi &> /dev/null; then echo "[ERROR] nvidia-smi未找到，请安装NVIDIA驱动" exit 1 fi if [ -z "$CUDA_VISIBLE_DEVICES" ] || [ "$CUDA_VISIBLE_DEVICES" != "0" ]; then echo "[WARN] CUDA_VISIBLE_DEVICES未设为0，已自动修正" export CUDA_VISIBLE_DEVICES=0 fi # 验证PyTorch CUDA if ! /opt/miniconda3/envs/torch27/bin/python -c "import torch; assert torch.cuda.is_available(), 'CUDA不可用'" &> /dev/null; then echo "[ERROR] PyTorch CUDA初始化失败" exit 1 fi echo "[INFO] CUDA环境检查通过" # === 结束校验 ===

6.2 日志中自动记录GPU状态

在gradio_app.py开头添加：

import torch import subprocess import logging # 记录GPU初始状态到日志 logging.info(f"PyTorch CUDA可用: {torch.cuda.is_available()}") if torch.cuda.is_available(): logging.info(f"GPU设备: {torch.cuda.get_device_name(0)}") logging.info(f"GPU显存: {torch.cuda.memory_reserved(0)/1024**3:.2f} GB") # 执行nvidia-smi并记录 try: smi_out = subprocess.check_output(['nvidia-smi', '-q', '-d', 'MEMORY']).decode() logging.info(f"nvidia-smi内存详情:\n{smi_out.split('Memory')[1][:200]}...") except Exception as e: logging.warning(f"无法获取nvidia-smi详情: {e}")

6.3 设置显存自适应分配

在gradio_app.py中，PyTorch初始化后添加：

# 防止显存OOM，启用缓存分配 torch.cuda.empty_cache() # 设置显存增长模式（避免一次性占满） torch.backends.cudnn.benchmark = True

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。