VSCode 调试大模型训练代码的三种高效方法

关键参数说明：

• module: 指定要运行的模块，这里是 torch.distributed.run。
• args: 对应命令行参数，注意数组中的每个参数都是独立的字符串。
• env: 环境变量，如 CUDA_VISIBLE_DEVICES 用于指定可见显卡。
• justMyCode: 设置为 false 允许调试第三方库代码，这对排查框架底层问题很重要。

步骤三：开始调试

1. 在需要调试的代码处设置断点。
2. 点击左上角的绿色箭头（或按下 F5）开始调试。
3. 观察集成终端输出，确认进程启动成功。

方法二：监听端口调试

这种方法需要修改训练代码，适用于特定场景，例如当无法直接修改启动脚本时。

步骤一：添加调试代码

在训练的主函数（例如 train/tuner.py 入口）开始处，添加以下代码：

import os
import debugpy

# 只在 rank 0 进程中启动调试器
if int(os.environ.get('LOCAL_RANK', '0')) == 0:
    debugpy.listen(("localhost", 5678))
    print("⏳ 等待调试器附加...")
    debugpy.wait_for_client()
    print("🚀 调试器已附加！继续执行...")

注意： 这段代码会阻塞程序执行，直到 VSCode 连接上为止。务必确保端口未被占用。

步骤二：配置 launch.json

创建一个 Attach 类型的配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger: Attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "justMyCode": false
        }
    ]
}

步骤三：启动调试

1. 正常启动训练脚本，例如：

   CUDA_VISIBLE_DEVICES=6,7 llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml
   

2. 当看到"⏳ 等待调试器附加…"时，在 VSCode 中选择"Python Debugger: Attach"。
3. 点击开始调试按钮。

方法三：命令行参数调试

这种方法不需要修改代码，但只支持单卡调试，适合快速验证逻辑。

步骤一：配置 launch.json

与方法二相同的配置（Attach 模式）。

步骤二：修改启动命令

将原来的启动命令修改为利用 debugpy 作为模块运行：

CUDA_VISIBLE_DEVICES=0 torchrun --nproc_per_node 1 \
    --master_port 23456 \
    -m debugpy \
    --listen 5678 \
    --wait-for-client \
    src/train.py \
    examples/train_lora/llama3_lora_sft.yaml

步骤三：启动调试

1. 运行修改后的命令。
2. 在 VSCode 中选择"Python Debugger: Attach"并开始调试。

调试技巧与进阶

1. 设置条件断点：右键点击断点，可以设置只在特定条件满足时才中断（例如 loss < 0.5）。
2. 查看变量：在调试面板的 Variables 区域可以查看当前所有变量的值，包括张量形状和内容。
3. 监视表达式：添加监视可以实时查看特定表达式的值，无需打断程序流。
4. 使用调试控制台：可以在这里执行 Python 代码，实时查看结果，非常适合测试临时逻辑。
5. 多线程调试：如果涉及多线程数据加载，注意线程上下文切换可能导致的断点失效，建议使用 threading 模块的调试支持。

常见问题与解决方案

1. 端口被占用错误

现象：Address already in use 解决：修改 launch.json 中的 port 或 master_port 为其他未被占用的端口（如 5679, 25645）。

2. 多卡训练时部分进程崩溃

现象：Rank 0 正常，其他 Rank 报错退出。 解决：检查 CUDA_VISIBLE_DEVICES 是否正确映射，确保每个进程分配的 GPU ID 不冲突。同时检查 torch.distributed.init_process_group 初始化是否在所有 Rank 中同步调用。

3. 断点无法命中

现象：程序跳过断点继续运行。 解决：确保 justMyCode 设置为 false，并检查代码是否经过编译优化（.pyc）。尝试删除 __pycache__ 目录后重新运行。

4. 内存泄漏检测

建议：在调试过程中，定期打印显存使用情况（如 torch.cuda.memory_summary()），以便及时发现显存异常增长。

注意事项

1. 方法一支持多卡调试，且配置最为简单，推荐优先使用。
2. 方法二和方法三中，调试器会等待 VSCode 连接，在连接前程序不会继续执行，这可能导致长时间挂起。
3. 使用调试器可能会略微影响训练速度，因为引入了额外的监控开销，但这通常对调试过程的影响可以忽略。
4. 生产环境部署时，请务必移除所有调试相关代码和配置。

总结

通过本文介绍的三种方法，相信你已经可以根据不同场景选择合适的调试方式。特别推荐使用方法一，配合分布式训练框架的标准参数配置，可以快速开始调试工作。掌握这些调试技巧，能显著降低大模型开发中的试错成本，提升迭代效率。