Qwen-Image-Edit-F2P实操手册：如何用stop.sh安全终止进程避免显存泄漏

1. 开箱即用：人脸生成与图像编辑一步到位

Qwen-Image-Edit-F2P 不是那种需要折腾半天才能跑起来的模型。它专为实用而生——下载即解压，启动即可用，尤其在人脸图像生成和精细化编辑场景中表现稳定。你不需要懂 Diffusion 原理，也不用调参改配置，只要有一张示例图、一段描述文字，就能在 Web 界面里完成从“想法”到“成图”的全过程。

它不是玩具级工具，而是基于 Qwen-Image-Edit 模型深度适配的生产就绪版本。背后整合了 DiffSynth-Studio 推理框架与 Gradio 快速 UI，所有依赖已预置、路径已固化、显存策略已优化。你看到的 face_image.png 不仅是示例，更是验证环境是否正常的第一道“测试图”；你点开浏览器访问 http://localhost:7860 看到的界面，就是真正能投入日常使用的编辑工作台。

这种开箱即用，不是省略关键步骤的“伪简化”，而是把部署中90%的重复劳动——环境校验、模型加载、服务注册、日志路由——全部封装进几个清晰脚本里。你负责“做什么”，它负责“怎么做好”。

2. 为什么必须重视 stop.sh：一次未清理的退出可能让下次启动失败

很多人第一次用完 Qwen-Image-Edit-F2P，习惯性关掉浏览器标签页，或者直接按 Ctrl+C 中断终端。看起来服务停了，但其实没那么简单。

Gradio 启动的是一个 Python 进程组，包含主服务、模型加载器、后台推理线程，甚至还有临时缓存管理器。如果只靠强制中断（如 kill -9 或关闭终端），这些子进程可能残留运行，继续占用 GPU 显存。更隐蔽的问题是：显存没释放，但 CUDA 上下文还挂着；模型权重文件锁没解开，日志写入句柄没关闭；下次再执行 start.sh，系统会报错：“CUDA out of memory” 或 “Address already in use”，而你根本找不到是谁占着资源。

stop.sh 就是专治这类“假停止”的工具。它不是简单地 killall python，而是按顺序执行三步操作：

• 先向 Gradio 主进程发送优雅退出信号（SIGTERM），等待其主动释放模型和显存；
• 再检查并清理残留的 CUDA 上下文和临时文件；
• 最后确认 gradio.log 已安全关闭，并输出明确状态提示。

这不是可选项，而是每次结束使用前的必做动作。就像关电脑要点击“关机”而不是直接拔电源——表面看都黑屏了，但内部状态天差地别。

3. stop.sh 实操详解：从执行到验证的完整闭环

3.1 执行 stop.sh 的正确姿势

确保你当前位于项目根目录：

cd /root/qwen_image

然后运行停止脚本：

bash stop.sh

你不会看到大量输出，正常情况下只会返回一行提示：

 Qwen-Image-Edit-F2P 已安全停止，显存已释放

如果出现 未检测到正在运行的服务，说明服务本就没在运行，无需担心；若卡住超过10秒，或提示 timeout，请手动检查进程：

nvidia-smi | grep python
ps aux | grep "app_gradio.py"

3.2 验证是否真正释放显存

光看提示不够，得用数据说话。执行以下命令查看 GPU 显存占用：

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

正常停止后，该命令应返回类似 124（单位 MB）的极低数值。如果仍显示 16256 或接近 18000（即 18GB），说明有残留进程在吃显存。

此时不要急着重启，先查清是谁：

nvidia-smi --query-compute-apps=pid,used_memory --format=csv

找到对应 PID 后，用标准方式清理：

kill -15 <PID>  # 先发优雅退出信号
sleep 2
kill -9 <PID>   # 若仍存活，再强杀（慎用）

3.3 日志里的“停止证据”

stop.sh 会在 gradio.log 末尾追加一条结构化记录，格式如下：

[2026-01-17 21:22:33] STOP: service terminated gracefully. VRAM released: 17.8GB → 0.12GB.

你可以用这条日志反向验证：

• 时间戳是否匹配你的操作时间；
• VRAM released 后的数值是否趋近于零；
• 是否存在 ERROR 或 WARNING 插入其中（如有，说明某环节异常）。

这行日志不是装饰，而是整个停止流程的“数字签名”。

4. start.sh 与 stop.sh 的配对逻辑：像开关一样可靠

start.sh 和 stop.sh 是一对设计严密的“开关组合”，它们共享同一套状态管理机制。理解它们的协作逻辑，能帮你避开80%的启动故障。

4.1 start.sh 做了什么（你未必知道）

当你运行 bash start.sh，它实际执行了以下不可见动作：

• 检查 /tmp/qwen_image.pid 文件是否存在。若存在，读取其中 PID 并确认进程是否活跃；
• 若发现旧进程残留，自动触发 stop.sh 清理，再继续启动；
• 启动后将当前主进程 PID 写入 /tmp/qwen_image.pid，供 stop.sh 读取；
• 设置 CUDA_VISIBLE_DEVICES=0 确保只用指定卡，避免多卡冲突；
• 重定向 stdout/stderr 到 gradio.log，并启用 log rotation（日志轮转）。

也就是说，start.sh 具备一定自愈能力，但它不保证100%清除历史残留——尤其是当上次是 kill -9 强杀时，PID 文件可能残留，而进程早已消失，导致 start.sh 误判为“服务已在运行”。

4.2 stop.sh 如何精准定位目标

stop.sh 不依赖 ps aux | grep 这种模糊匹配，而是严格遵循两个唯一标识：

• 读取 /tmp/qwen_image.pid 获取主进程 PID；
• 校验该 PID 对应进程的启动命令是否包含 app_gradio.py 和当前工作目录 /root/qwen_image。

只有完全匹配，才执行 kill -15 $PID。否则报错：

  PID file exists but process not found or mismatched. Manual cleanup required.

这个设计杜绝了“杀错进程”的风险——比如你同时在跑另一个 Python 项目，killall python 可能误伤，而 stop.sh 只认自己家的孩子。

5. 显存泄漏的典型症状与排查路径

即使你每次都用 stop.sh，也需了解显存泄漏的真实表现。它往往不是立刻崩溃，而是缓慢积累，直到某次启动彻底失败。

5.1 三大典型症状

症状	表现	可能原因
启动变慢	从执行 start.sh 到 Web 页面可访问，耗时从10秒延长至2分钟以上	显存碎片化，CUDA 初始化反复重试
首次生成失败	第一张图提示 CUDA error: out of memory，但 nvidia-smi 显示显存充足	残留上下文占用部分显存，新分配失败
多轮生成后质量下降	后续生成图出现色块、模糊、结构崩坏	显存不足导致 FP8 量化精度丢失，权重加载异常

5.2 三步快速定位法

1. 查 PID 文件状态

   ls -la /tmp/qwen_image.pid
   cat /tmp/qwen_image.pid 2>/dev/null
   

   若文件存在但内容为空，或 PID 对应进程已不存在，说明状态不一致。

2. 查显存真实占用

   nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv
   

   关注 process_name 是否含 python 且 used_memory > 100MB，但 PID 不在 /tmp/qwen_image.pid 中。

3. 查日志末尾异常

   tail -20 gradio.log | grep -E "(ERROR|WARNING|Traceback)"
   

   特别留意 OutOfMemoryError、CUDA context、failed to free 等关键词。

发现任一异常，立即执行 bash stop.sh + 手动清理残留，再重启。

6. 生产环境建议：让 stop.sh 成为你工作流的一部分

在个人开发或小团队试用阶段，stop.sh 是个好习惯；在生产部署中，它必须成为自动化流程的一环。

6.1 终端使用规范（推荐）

• 每次打开新终端窗口，先执行：

  cd /root/qwen_image && source ./env.sh  # 若有环境变量脚本
  

• 启动后，用 tmux 或 screen 保持会话，避免误关终端：

  tmux new -s qwen
  bash start.sh
  # 按 Ctrl+B, D 脱离会话
  

• 结束时，重新进入会话并执行：

  tmux attach -t qwen
  bash stop.sh
  

6.2 定时巡检脚本（可选增强）

将以下内容保存为 /root/qwen_image/health_check.sh，设为每日凌晨执行：

#!/bin/bash
# 检查显存占用是否异常
VRAM_USED=$(nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits | cut -d' ' -f1)
if [ "$VRAM_USED" -gt 2000 ]; then
    echo "$(date): High VRAM usage detected: ${VRAM_USED}MB" >> /root/qwen_image/health.log
    bash /root/qwen_image/stop.sh >> /root/qwen_image/health.log 2>&1
fi

配合 cron 使用：

0 3 * * * /root/qwen_image/health_check.sh

6.3 Docker 化部署提示（进阶）

如果你计划容器化部署，请注意：

• stop.sh 在容器内仍有效，但需确保 --pid=host 或 --ipc=host 模式，否则无法跨命名空间杀进程；
• 更推荐方式是用 docker stop 触发容器内 stop.sh，通过 STOPSIGNAL SIGTERM 配合 CMD ["bash", "start.sh"] 实现优雅退出。

7. 总结：stop.sh 不是脚本，而是显存守门人

stop.sh 看似只是一行命令，但它承载了三个关键角色：

• 资源回收者：确保 GPU 显存、CPU 内存、磁盘句柄、网络端口全部归零；
• 状态校验者：通过 PID 文件与进程特征双重验证，拒绝误操作；
• 行为记录者：在日志中留下可审计的停止证据，为问题回溯提供依据。

它不炫技，不复杂，却直击 AI 工具落地中最容易被忽视的“最后一公里”——如何干净利落地收场。很多用户卡在“为什么第二次启动就报错”，答案往往不在模型或代码里，而在你按下 Ctrl+C 的那一刻。

所以，请把 bash stop.sh 当作和 bash start.sh 一样重要的仪式。不是多此一举，而是对算力资源的基本尊重。

---

获取更多AI镜像

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