MedGemma X-Ray故障排查手册：端口占用/CUDA错误/进程僵死处理

MedGemma X-Ray故障排查手册：端口占用/CUDA错误/进程僵死处理

1. 为什么你需要这份手册

MedGemma X-Ray 是一款基于前沿大模型技术开发的医疗影像智能分析平台。它致力于将人工智能的强大理解能力应用于放射科影像，协助用户快速、准确地解读胸部 X 光片。无论是医学教育、模拟研究还是初步阅片辅助，MedGemma 都能提供极具参考价值的结构化分析报告。

你可能已经成功部署了系统，也上传过几张X光片，看到过AI生成的“胸廓对称、肺野清晰、膈肌光滑”这类专业描述——但当某天点击“开始分析”后页面一直转圈，或者浏览器打不开 http://服务器IP:7860，又或者终端里反复报出CUDA out of memory错误时，你会怎么办？

这不是代码写错了，也不是模型坏了，而是典型的运行时环境异常。这类问题不常发生，但一旦出现，往往卡在最关键的操作环节，让人无从下手。本手册不讲原理、不堆参数，只聚焦三类最常遇到、最影响使用的实际问题：端口被占、CUDA报错、进程僵死。每一种都配真实命令、可复制操作、明确判断逻辑，让你5分钟内定位问题，10分钟内恢复服务。

2. 故障前的三个关键确认动作

在跳进具体问题之前，请先花2分钟做三件小事。它们看似简单，却能帮你避开80%的“以为出错了，其实只是没启动”的尴尬场景。

2.1 确认应用当前状态

别猜，直接看。运行这行命令：

bash /root/build/status_gradio.sh

它会一次性告诉你四件事：

• 应用是否正在运行（Running: Yes/No）
• 当前进程PID是多少（比如PID: 12345）
• 7860端口是否被监听（Listening on port 7860: Yes/No）
• 最近10行日志里有没有明显报错（比如OSError,CUDA,Connection refused）

如果显示Running: No且Listening on port 7860: No，那问题很简单：你还没启动。跳到第5节直接执行启动脚本即可。

2.2 检查GPU是否在线

MedGemma X-Ray 依赖GPU加速推理。如果显卡没识别到，系统会退回到CPU模式，但性能极低，甚至直接报错退出。运行：

nvidia-smi

正常输出应包含：

• 顶部显示驱动版本和CUDA版本（如CUDA Version: 12.1）
• 中间表格列出GPU型号（如A10）、显存使用（Memory-Usage: 1200MiB / 23028MiB）和温度（Temp: 42C）

如果提示NVIDIA-SMI has failed或完全没输出，说明GPU驱动未加载或硬件异常。此时CUDA相关错误必然出现，需优先解决GPU问题。

2.3 快速翻看最新日志

日志是系统最诚实的“日记”。不要等报错才看，养成启动后随手查的习惯：

tail -20 /root/build/logs/gradio_app.log

重点关注最后几行是否包含：

• Starting Gradio app on http://0.0.0.0:7860→ 启动成功
• Model loaded successfully→ 模型加载完成
• Traceback或Error:开头的行 → 明确失败点

如果日志里最后一句是Loading model...就停住了，大概率是显存不足或模型文件损坏；如果是Address already in use，那就是端口冲突了。

3. 端口被占用：浏览器打不开的真正原因

你输入http://服务器IP:7860，浏览器显示“无法访问此网站”或“连接被拒绝”，第一反应可能是网络不通。但更大概率是：7860端口正被另一个程序悄悄占着。

Gradio默认绑定0.0.0.0:7860，这个地址意味着“本机所有网卡都监听7860端口”。只要有一个进程抢先绑定了它，MedGemma就再也无法启动。

3.1 两步定位谁在抢端口

不用猜，用命令直接揪出来：

ss -tlnp | grep ':7860'

推荐用ss而非netstat：更快、更轻量、在多数新系统中预装

输出示例：

LISTEN 0 128 *:7860 *:* users:(("python",pid=8890,fd=7))

这里清楚写着：pid=8890的python进程正在占用7860端口。

如果没输出，说明端口空闲，问题不在这里；如果有输出，记下那个PID（比如8890），进入下一步。

3.2 安全清理：先尝试优雅停止，再考虑强制

别一上来就kill -9。先给进程体面退出的机会：

kill 8890

等待3秒，再运行ss -tlnp | grep ':7860'。如果输出消失，说明已释放；如果还在，说明进程僵死，需要强制终止：

kill -9 8890 rm -f /root/build/gradio_app.pid

注意：rm -f是必须的。PID文件残留会导致后续启动脚本误判“已有实例在运行”，从而拒绝启动。

3.3 预防下次再撞车：改个端口很简单

如果你经常需要同时跑多个AI服务（比如还部署了Stable Diffusion WebUI），7860端口太热门。修改方法只需一行：

打开/root/build/gradio_app.py，找到类似这行代码：

demo.launch(server_name="0.0.0.0", server_port=7860)

把7860改成7861或其他未被占用的端口（建议选7000–9000之间），保存后重启即可。

验证新端口是否可用：

ss -tlnp | grep ':7861' # 应无输出 bash /root/build/start_gradio.sh

4. CUDA错误：显存不够、设备不可见、版本不匹配

当你看到CUDA out of memory、CUDA driver version is insufficient或no CUDA-capable device is detected这类报错时，别急着重装驱动。MedGemma X-Ray 对CUDA环境有明确要求，绝大多数问题出在配置错位，而非硬件故障。

4.1 显存爆了？先看真实占用，再调小批量

CUDA out of memory是最常见报错。但它不一定代表显存真不够——更可能是模型加载时申请了过多显存，而你的GPU只有24GB（如A10），却被要求分配32GB。

先确认当前显存真实压力：

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

输出类似：

memory.used [MiB], memory.total [MiB] 1200 MiB, 23028 MiB

说明还有21GB空闲，那问题不在物理显存，而在模型推理时的峰值显存申请策略。

解决方法：修改/root/build/gradio_app.py，在模型加载部分加入显存控制参数。找到pipeline = pipeline(...)或model = AutoModelForSeq2SeqLM.from_pretrained(...)这类行，在后面添加：

device_map="auto", torch_dtype=torch.float16, load_in_4bit=True, # 关键！启用4位量化

4位量化可将显存占用降低60%以上，对推理质量影响极小，是医疗影像分析场景的首选方案。

4.2 “找不到GPU”？检查环境变量和可见性

如果nvidia-smi能看到GPU，但MedGemma启动时报no CUDA-capable device，大概率是环境变量没生效。

检查当前Shell是否设置了CUDA_VISIBLE_DEVICES：

echo $CUDA_VISIBLE_DEVICES

正常应输出0。如果为空或输出""，说明启动脚本没正确加载环境变量。

修复方法：编辑/root/build/start_gradio.sh，在python命令执行前，确保有这行：

export CUDA_VISIBLE_DEVICES=0

并确认它位于python /root/build/gradio_app.py这行命令之前。

4.3 驱动/CUDA版本不匹配？用官方组合最稳

MedGemma X-Ray 基于 PyTorch 2.0+ 和 CUDA 12.1 构建。如果你的系统装了CUDA 11.8或12.4，可能出现兼容问题。

验证当前CUDA版本：

nvcc --version # 或 cat /usr/local/cuda/version.txt

推荐组合（经实测稳定）：

如版本不符，最稳妥方式是重装CUDA Toolkit 12.1（官网下载链接），而非降级驱动。

5. 进程僵死：点击停止没反应，杀不死、删不掉

你执行了bash /root/build/stop_gradio.sh，终端返回Stopped successfully，但ss -tlnp | grep 7860依然显示端口被占；或者ps aux | grep gradio_app.py仍能看到进程，kill却提示No such process——这就是典型的进程僵死（Zombie Process）。

它不是在运行，而是卡在内核态，等待父进程回收资源，但父进程已退出。此时它不消耗CPU，但会持续占用端口和PID，导致无法重启。

5.1 识别僵死进程：一眼看出“假活”

运行：

ps aux | grep gradio_app.py | grep -v grep

观察输出中的STAT列（状态列）：

• R（Running）或S（Sleeping）→ 正常进程
• Z（Zombie）→ 僵死进程，需特殊处理
• <（High-priority）或N（Low-priority）→ 无关紧要

如果看到Z，例如：

root 12345 0.0 0.0 0 0 ? Z 10:22 00:00:00 [python] <defunct>

说明PID 12345 已僵死。

5.2 彻底清理：两步清零法

僵死进程无法用kill终止，必须让其父进程（通常是init，PID=1）回收。执行：

# 第一步：强制向init发送SIGCHLD信号，触发回收 kill -s SIGCHLD 1 # 第二步：手动删除残留PID文件（避免启动脚本误判） rm -f /root/build/gradio_app.pid

这比重启服务器快10倍，且不影响其他服务。

执行后再次ps aux | grep gradio_app.py，僵死进程应彻底消失。

5.3 防止复发：给启动脚本加超时保护

根本原因是stop_gradio.sh在进程无响应时未设置强制超时。编辑该脚本，在kill $PID后添加：

# 等待5秒，若进程仍在，强制杀死 sleep 5 if kill -0 $PID 2>/dev/null; then kill -9 $PID echo "Force killed stale process $PID" fi

这样下次停止时，即使进程卡住，也会在5秒后被干净清除。

6. 一套组合拳：从启动失败到稳定运行的完整流程

现在，把前面所有知识点串起来，走一遍最可能遇到的“启动失败”全流程诊断。这不是理论，而是你明天早上面对黑屏终端时的真实操作路径。

6.1 场景还原：你执行了启动命令，但没反应

bash /root/build/start_gradio.sh # 终端只返回一行：Checking Python environment... Done. # 然后就卡住，无后续输出，浏览器也打不开

6.2 分步诊断与修复（按顺序执行）

第一步：查状态

bash /root/build/status_gradio.sh

→ 如果显示Running: No且Listening on port 7860: No，说明启动脚本中途退出了。

第二步：看日志末尾

tail -30 /root/build/logs/gradio_app.log

→ 如果最后几行是OSError: [Errno 98] Address already in use，跳到第3节处理端口； → 如果是torch.cuda.is_available() returned False，跳到第4.2节检查环境变量； → 如果是RuntimeError: CUDA out of memory，跳到第4.1节加4位量化。

第三步：手动启动，暴露原始错误

cd /root/build /opt/miniconda3/envs/torch27/bin/python gradio_app.py

→ 此时错误会直接打印在终端，比日志更实时。常见如ModuleNotFoundError: No module named 'transformers'，说明Python环境缺失包，运行：

/opt/miniconda3/envs/torch27/bin/python -m pip install transformers accelerate bitsandbytes

第四步：确认GPU可用性

nvidia-smi /opt/miniconda3/envs/torch27/bin/python -c "import torch; print(torch.cuda.is_available(), torch.cuda.device_count())"

→ 两个命令都必须返回True和1，否则CUDA链路断开。

第五步：终极验证——最小化启动临时修改gradio_app.py，注释掉所有模型加载代码，只留一个空白界面：

import gradio as gr gr.Interface(lambda x: "OK", "text", "text").launch(server_name="0.0.0.0", server_port=7860)

→ 如果此时能打开网页，证明Gradio和端口没问题，问题100%出在模型加载环节。

7. 总结：让MedGemma X-Ray始终在线的三个习惯

故障排查不是救火，而是建立一套可持续的运维习惯。以下三点，坚持一周，你会发现大部分问题在发生前就被拦截了。

7.1 每次启动后，必做三查

• 查状态：bash /root/build/status_gradio.sh→ 确认Running和Listening均为Yes
• 查日志：tail -10 /root/build/logs/gradio_app.log→ 确认最后是Starting Gradio app...
• 查GPU：nvidia-smi→ 确认显存使用率在合理范围（<80%）

7.2 日志不积压，每周清理一次

日志文件会持续追加，几个月后可达GB级，拖慢磁盘IO。加个简单定时任务：

# 编辑crontab crontab -e # 添加这一行（每周日凌晨2点压缩旧日志） 0 2 * * 0 find /root/build/logs/ -name "gradio_app.log.*" -mtime +7 -delete

7.3 备份关键配置，5秒回滚

gradio_app.py和start_gradio.sh是核心。每次修改前，执行：

cp /root/build/gradio_app.py /root/build/gradio_app.py.bak_$(date +%Y%m%d) cp /root/build/start_gradio.sh /root/build/start_gradio.sh.bak_$(date +%Y%m%d)

万一改崩了，cp /root/build/gradio_app.py.bak_20240520 /root/build/gradio_app.py一键还原。

获取更多AI镜像

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