PythonAI算法
VSCode 调试大模型训练代码的三种高效方法
VSCode 调试大模型训练代码可通过直接启动、端口监听及命令行参数三种方式实现。直接启动法配合 torch.distributed.run 支持多卡且配置简单；端口监听法需修改代码注入 debugpy；命令行法无需改码但仅限单卡。推荐优先使用直接启动法，注意处理环境变量及端口冲突问题，可显著提升调试效率。此外，还需掌握条件断点、变量监视及常见报错排查技巧，以确保训练过程稳定可控。
VSCode 调试大模型训练代码可通过直接启动、端口监听及命令行参数三种方式实现。直接启动法配合 torch.distributed.run 支持多卡且配置简单；端口监听法需修改代码注入 debugpy；命令行法无需改码但仅限单卡。推荐优先使用直接启动法，注意处理环境变量及端口冲突问题，可显著提升调试效率。此外，还需掌握条件断点、变量监视及常见报错排查技巧，以确保训练过程稳定可控。
在开发和调试大模型训练代码时，使用 print 语句进行调试往往效率低下且容易遗漏重要信息。本文将介绍三种使用 VSCode 进行交互式 debug 的方法，让你的调试过程更加高效和精确。
在开始之前，请确保完成以下基础配置：
debugpy 库，通常包含在 python 包中，若未安装可执行 pip install debugpy。这是最简单且功能完整的方法，支持单卡和多卡训练场景，推荐优先使用。
Ctrl+Shift+D）。对于多卡训练，通常使用 torch.distributed.run (旧版为 torchrun)。为了简化配置过程，你可以参考 LLaMA-Factory 等开源项目的最佳实践。
你需要将原始的训练命令转换为 VSCode 可识别的参数列表。一个典型的多卡训练配置如下：
{
"version": "0.2.0",
"configurations": [
{
"name": "debug.llamafactory.cn",
"type": "debugpy",
"request": "launch",
"module": "torch.distributed.run",
"console": "integratedTerminal",
"args": [
"--nproc_per_node",
"4",
"--master_port",
"25644",
"src/llamafactory/launcher.py",
"--model_name",
"llama31",
"--dataset_name",
"data",
"--learning_rate",
"1e-4",
"--size_valid_set",
"0.05",
"--warmup_ratio",
"0.03",
"--optim",
"paged_adamw_32bit",
"--lr_scheduler_type",
"cosine",
"--per_device_train_batch_size",
"16",
"--per_device_eval_batch_size",
"16",
"--lora_alpha",
"16",
"--lora_r",
"8",
"--lora_target_modules",
"W_pack",
"--max_input_length",
"256",
"--max_output_length",
"64",
"--num_train_epochs",
"3",
"--evaluation_strategy",
"steps",
"--logging_steps",
"100",
"--save_steps",
"300",
"--eval_steps",
"500",
"--save_total_limit",
"5",
"--num_workers",
"64",
"--gradient_checkpointing",
"--ddp_find_unused_parameters",
"False",
"--logging_first_step",
"True",
"--output_dir",
"./output",
"--report_to",
"tensorboard"
],
"env": {
"CUDA_VISIBLE_DEVICES": "\"0,1,2,3\""
},
"justMyCode": false
}
]
}
关键参数说明：
module: 指定要运行的模块，这里是 torch.distributed.run。args: 对应命令行参数，注意数组中的每个参数都是独立的字符串。env: 环境变量，如 CUDA_VISIBLE_DEVICES 用于指定可见显卡。justMyCode: 设置为 false 允许调试第三方库代码，这对排查框架底层问题很重要。这种方法需要修改训练代码，适用于特定场景，例如当无法直接修改启动脚本时。
在训练的主函数（例如 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 连接上为止。务必确保端口未被占用。
创建一个 Attach 类型的配置：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python Debugger: Attach",
"type": "debugpy",
"request": "attach",
"connect": {
"host": "localhost",
"port": 5678
},
"justMyCode": false
}
]
}
CUDA_VISIBLE_DEVICES=6,7 llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml
这种方法不需要修改代码，但只支持单卡调试，适合快速验证逻辑。
与方法二相同的配置（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
loss < 0.5）。threading 模块的调试支持。现象：Address already in use
解决：修改 launch.json 中的 port 或 master_port 为其他未被占用的端口（如 5679, 25645）。
现象：Rank 0 正常，其他 Rank 报错退出。
解决：检查 CUDA_VISIBLE_DEVICES 是否正确映射，确保每个进程分配的 GPU ID 不冲突。同时检查 torch.distributed.init_process_group 初始化是否在所有 Rank 中同步调用。
现象：程序跳过断点继续运行。
解决：确保 justMyCode 设置为 false，并检查代码是否经过编译优化（.pyc）。尝试删除 __pycache__ 目录后重新运行。
建议：在调试过程中，定期打印显存使用情况（如 torch.cuda.memory_summary()），以便及时发现显存异常增长。
通过本文介绍的三种方法，相信你已经可以根据不同场景选择合适的调试方式。特别推荐使用方法一，配合分布式训练框架的标准参数配置，可以快速开始调试工作。掌握这些调试技巧，能显著降低大模型开发中的试错成本，提升迭代效率。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online