VSCode远程调试机器学习代码卡顿原因及无需退出的解决方法

卡顿定义与异常判定 #

该卡顿表现为调试会话全程无响应，步进、暂停、终止调试、变量面板刷新等所有调试相关操作均无反馈，属于调试异常，不属于正常行为。正常调试场景下，即使代码本身需要长时间执行，调试控制器的终止、暂停按钮仍可响应，完全无响应状态可明确判定为调试链路或运行环境触发的异常。

核心诱因 #

• 内存超限：机器学习代码加载大批次数据集、全量模型参数时，内存占用超出远程服务器配额或VSCode调试适配器（debugpy）的内存阈值，导致调试适配器被系统OOM策略杀死或进入阻塞状态
• 远程链路传输超时：弱网环境下SSH连接丢包率过高，若调试过程中需要传输大体积张量、数组等变量值，会出现传输超时，进而导致本地VSCode调试界面卡住
• 变量自动加载冲突：VSCode调试默认会自动加载当前作用域内所有变量的值展示，若作用域内存在GB级张量、大型DataFrame等数据，变量序列化+传输过程会直接占满带宽或调试进程资源，触发无响应
• 版本兼容问题：Python调试组件debugpy版本与VSCode远程插件、本地VSCode版本不兼容，触发已知死锁bug
• GPU资源异常：代码调用GPU训练时，CUDA上下文崩溃或被其他进程抢占，导致调试进程挂起，无法返回状态给调试适配器

无需断开远程连接的解决方法 #

• 手动终止调试进程：SSH登录远程服务器，执行ps aux | grep debugpy查询对应调试进程ID，执行kill -9 <进程ID>杀掉进程，本地VSCode调试会话会自动终止，无需断开整个远程连接
• 关闭高负载调试配置：在调试配置文件launch.json中添加以下配置项，关闭大容量变量自动加载等功能：

  "justMyCode": true,
  "showReturnValue": false,
  "variablesReference": 0
  

  可避免后续调试再次触发同类问题
• 重置远程服务进程：按Ctrl+Shift+P调出命令面板，执行「Remote-SSH: Kill VS Code Server on Host...」选择对应远程主机，清理卡住的远程服务进程，之后重新连接即可，不会影响远程服务器上其他运行的进程
• 强制CPU运行调试：若调试阶段不需要执行实际训练，可在代码入口添加os.environ["CUDA_VISIBLE_DEVICES"] = "-1"强制使用CPU运行，排除CUDA上下文挂起导致的卡顿
• 匹配debugpy版本：安装稳定版debugpy解决兼容问题，执行命令pip install debugpy==1.6.7即可，该版本适配绝大多数VSCode发行版

内容的提问来源于stack exchange，提问作者user16472431