LocateAnything-3B 目标检测微调

LocateAnything-3B 目标检测微调 —— 完整训练手册目的任何人拿到这份文档从零开始在本机完成数据准备、环境搭建、训练启动、监控、故障排查、产物使用的全流程。最后更新2026-08-29含两次 OOM 根因分析与修复记录目录项目总览硬件与系统架构目录结构说明训练环境搭建从零数据准备训练原理与关键配置日常操作启动 / 监控 / 停止显存优化实录两次 OOM 的根因与修复训练产物与使用故障排查手册常见调参速查1. 项目总览项目内容模型LocateAnything-3BNVIDIA 开源多模态定位/检测基础模型模型构成视觉塔 MoonViT-SO-400Mhidden 1152 / 16 头 / 27 层 / patch 14 / 2×2 merge 语言模型 Qwen2.5-3Bhidden 2048 / 16 头 / 36 层微调方式LoRArank 64冻结 LLM 与视觉主干训练 LoRA MLP 投影层任务电力巡检目标检测77 个缺陷/设备类别数据规模训练 102,198 条样本 / 验证 26,110 条 / 共 33.99 万个框数据来源D:\dataSets_0424COCO 格式此前用于 YOLO / DEIM 训练模型权重D:\localcode\LocateAnything-3B\LocateAnything-3B\本地 safetensors无需联网训练入口Eagle/Embodied/eaglevl/train/locany_finetune_magi_stream.py不要直接运行见第 7 节2. 硬件与系统架构2.1 硬件GPUNVIDIA RTX 309024GB 显存Ampere 架构内存/磁盘充足即可无特殊要求2.2 双系统分工重要先理解再动手┌─────────────────────────────────────────────────────────────┐ │ Windows 本机 │ │ ├─ 推理服务 app.pyFastAPIhttp://127.0.0.1:8000 │ │ │ 启动scripts\start_inference.bat │ │ │ 停止scripts\stop_inference.bat │ │ └─ 日常查看训练日志/文件D 盘是共享的 │ ├─────────────────────────────────────────────────────────────┤ │ WSL2 Ubuntu-22.04root 登录 │ │ └─ 训练triton / deepspeed 仅支持 LinuxWindows 无法训练 │ │ conda 环境locany_trainPython 3.10.21 │ │ 代码路径/mnt/d/localcode/LocateAnything-3B与 Windows │ │ 侧 D:\localcode\LocateAnything-3B 是同一份文件 │ └─────────────────────────────────────────────────────────────┘为什么训练必须在 WSL2训练栈依赖triton融合算子和deepspeedZeRO 显存优化两者都没有 Windows 版本。这两个库由eaglevl包在 import 时无条件加载无法绕过。推理不受影响Windows 原生可用。2.3 进入 WSL# Windows 终端PowerShell / CMD执行wsl-d Ubuntu-22.04进入后默认是 root 用户提示符类似root主机名:~#。退出用exit。注意训练用setsid后台启动退出 WSL 会话不影响训练继续运行。2.4 WSL 发行版来源重建时才需要本机 Ubuntu-22.04 是从清华镜像的 rootfs 导入的微软商店在线安装会超时失败wsl--import Ubuntu-22.04 D:\wsl2\Ubuntu-22.04 D:\wsl2\ubuntu22.04.rootfs.tar.gz--version 2rootfs 备份仍在D:\wsl2\ubuntu22.04.rootfs.tar.gz326MB。3. 目录结构说明D:\localcode\LocateAnything-3B\ ├─ LocateAnything-3B\ # 模型权重 官方推理代码Windows 推理用 │ ├─ model-0000X-of-00002.safetensors │ ├─ config.json # 模型结构配置LLM视觉塔参数 │ ├─ preprocessor_config.json # 图像预处理in_token_limit8192 │ └─ image_processing_locateanything.py ├─ Eagle\Embodied\ # 官方训练代码仓WSL 训练用 │ ├─ eaglevl\ │ │ ├─ train\locany_finetune_magi_stream.py # ★ 训练主程序 │ │ └─ model\ │ │ ├─ locany\modeling_locateanything.py # 模型 forward 主逻辑 │ │ ├─ locany\mask_sdpa_utils.py # ★ 已修复LLM 注意力掩码 │ │ ├─ locany\modeling_qwen2.py # LLM含 MTP packing 注意力 │ │ └─ moon_vit\modeling_vit.py # ★ 已修复视觉塔注意力 │ └─ deepspeed_configs\zero_stage2_config.json # ZeRO-2 配置 ├─ train\ # ★ 我们自己建的训练工作区全在这里 │ ├─ convert_to_locateanything.py # 数据转换脚本 │ ├─ train.jsonl / val.jsonl / train_smoke.jsonl │ ├─ recipe_wsl.json # 正式训练数据配方/mnt/d 路径 │ ├─ recipe_smoke.json # 冒烟测试配方200 条 │ ├─ start_training.sh # ★ 训练启动器日常用这个 │ ├─ monitor_training.sh # 训练监控-f 实时跟踪日志 │ ├─ stop_training.sh # 训练停止 │ ├─ finetune_lora_single_gpu.sh # 底层训练脚本被 start_training.sh 调用 │ ├─ wsl_setup\ # 环境搭建四步脚本见第 4 节 │ ├─ logs\training_run.log # 运行日志 │ └─ work_dirs\locany_lora\ # 训练输出checkpoint 在这 ├─ app.py / inference.py # Windows 推理服务 └─ scripts\start_inference.bat # 推理服务启停4. 训练环境搭建从零环境已搭好并验证过conda 环境locany_train。本节供重建环境时使用日常训练请直接跳到第 7 节。按顺序在Windows 终端执行脚本内部用绝对路径调用避免 Windows PATH 污染# 第 1 步配置镜像源 创建 conda 环境Python 3.10wsl-d Ubuntu-22.04--bash/mnt/d/localcode/LocateAnything-3B/train/wsl_setup/setup_env.sh# 第 2 步安装 PyTorch 2.13.0cu126阿里云镜像wsl-d Ubuntu-22.04--bash/mnt/d/localcode/LocateAnything-3B/train/wsl_setup/install_torch.sh# 第 3 步安装 deepspeed 0.15.4 / triton / transformers 4.57.1 / peft 等训练依赖wsl-d Ubuntu-22.04--bash/mnt/d/localcode/LocateAnything-3B/train/wsl_setup/install_deps.sh# 第 4 步设置 CUDA_HOMEdeepspeed 版本探测用的 nvcc 包装wsl-d Ubuntu-22.04--bash/mnt/d/localcode/LocateAnything-3B/train/wsl_setup/setup_cuda_home.sh关键决策重建时不要改动deepspeed0.15.4用DS_BUILD_OPS0安装纯 Python 版WSL 里没有完整 CUDA toolkit 编译不了 CUDA op但 ZeRO-2 不需要编译 op 就能跑。CUDA_HOME 指向/root/cuda_home里面只有一个回显版本号的 nvcc 包装脚本仅用于 deepspeed 的版本检查不参与编译。eaglevl包用pip install -e . --no-deps安装跳过 gradio 等 UI 依赖。验证环境在 WSL 内执行source/root/miniconda3/etc/profile.d/conda.sh conda activate locany_train python-cimport torch; print(torch.__version__, torch.cuda.is_available())# 应输出 2.13.0cu126 Truepython-cimport deepspeed, triton, transformers, peft; print(deps OK)nvidia-smi# 应能看到 RTX 30905. 数据准备数据已转换完毕。本节供换数据集 / 增量数据时使用。5.1 源数据路径D:\dataSets_0424COCO 格式coco_annotations/train.json、val.json图片在images/train|val/77 个类别cysb_cyg、SF6ylb、ylb、fhz_f 等电力巡检缺陷/设备类5.2 转换命令cd/d/localcode/LocateAnything-3B/train python convert_to_locateanything.py默认参数即对应当前数据集换数据集时修改脚本顶部的路径常量。5.3 输出格式LocateAnything 训练标准JSONL每行一个样本ShareGPT 对话式{conversations:[{from:human,value:Locate all the instances that matches the following description: cysb_lqq.},{from:gpt,value:refcysb_lqq/refbox4110588164/boxbox421604540750/box}],image:images/train/xl_00000003.jpg}要点坐标是 0-1000 的归一化整数像素坐标 ÷ 图片宽/高 × 1000 四舍五入格式boxx1y1x2y2/box输出按类别分组一个ref后跟该类别的所有boxprompt 写法与官方推理worker.detect(img, [类别名])完全一致保证训推一致5.4 数据配方recipe JSONrecipe_wsl.json告诉训练脚本每个 JSONL 文件的路径、图像根目录、重复次数。当前配方 全量训练集 验证集。recipe_smoke.json只含 200 条冒烟集。5.5 校验结论已做过77/77 类别全覆盖、0 非法框、0 未知类别、框数与 COCO 标注一致。类别样本数分布极不均衡最少 86 条 / 最多 17,199 条如效果不佳可在 recipe 里给稀有类别提高repeat_time。6. 训练原理与关键配置6.1 调用链start_training.sh自检 后台启动 └─ finetune_lora_single_gpu.sh设置超参环境变量 └─ torchrun --nproc_per_node1 --master_port29500 └─ eaglevl/train/locany_finetune_magi_stream.py主程序 ├─ StreamPackedDatasetMTP流式读取 JSONL多样本打包成 ~4096 token 的长序列 ├─ MoonViT 视觉塔图像 → patch(14×14) → 2×2 merge → 视觉 token ├─ Qwen2 LLMMTP stream packing 注意力block_size6 └─ DeepSpeed ZeRO-2 LoRA 训练循环6.2 关键超参及理由3090 适配参数值为什么--attn_implementationsdpa官方默认magi分块稀疏注意力仅支持 H100/Blackwell3090 用 PyTorch 原生 SDPA--max_seq_length/--max_num_tokens4096sdpa 短上下文上限magi 才支持 16K也是显存安全值--use_llm_lora64LoRA rank冻结 LLM 原权重只训低秩适配器--freeze_backboneTrue冻结视觉主干--freeze_mlpFalseMLP 投影层必须训练——它负责把视觉特征对齐到新的 77 个类别--grad_checkpointTrue梯度检查点用重算换显存DeepSpeedZeRO-2单卡下主要收益是优化器状态管理 bf16--bf16True3090 支持 bf16显存减半--block_size6MTP 流式打包的块大小官方默认勿改--causal_attnFalse官方检测任务默认勿改--packing_buffer_size32流式打包缓冲区样本数--per_device_train_batch_size1保持 1打包已在数据侧完成「批」的效果--max_steps500010 万图全量一轮 ≈ 10 万步先训 5000 步看效果--save_steps500每 500 步存一个 checkpoint最多保留 3 个6.3 图像预处理影响显存重要图像预处理上限in_token_limit8192见LocateAnything-3B/preprocessor_config.json单张图最多 8192 个 patch经 2×2 merge 后最多2048 个视觉 token一个打包序列≤4096 LLM token里通常装 1~3 张图 → 视觉塔单次 forward 的 token 量 L 约 2000~68007. 日常操作启动 / 监控 / 停止所有命令在WSLwsl -d Ubuntu-22.04内执行。7.1 启动cd/mnt/d/localcode/LocateAnything-3B/train# 冒烟测试200 条 / 20 步几分钟验证链路通不通bashstart_training.sh--smoke# 正式训练全量 10.2 万条 / 5000 步bashstart_training.sh启动器自动执行 6 项自检代码目录 / 依赖 / GPU / 模型权重 / 数据文件 / 29500 端口全部通过后后台启动训练setsid 脱离会话退出 WSL 不受影响并打印 PID / 日志路径。启动后等约 1 分钟模型加载再等 2~3 分钟到首个 step。7.2 监控bashmonitor_training.sh# 单次快照进程/GPU/日志/loss/checkpointbashmonitor_training.sh-f# 快照 实时跟踪日志CtrlC 退出不影响训练tail-flogs/training_run.log# 直接看日志nvidia-smi# 显存占用健康值训练稳定后约 18~21GB / 24GB健康标志日志出现{loss: ..., learning_rate: ..., epoch: ...}的 step 记录且 loss 在前几百步内从 ~2-3 缓慢下降。7.3 停止bashstop_training.sh# 优雅停止TERM → 3 秒后 KILL 兜底清理7.4 从 checkpoint 恢复训练# 找到最新 checkpoint 目录名ls/mnt/d/localcode/LocateAnything-3B/train/work_dirs/locany_lora/# 假设是 checkpoint-1500则恢复训练cd/mnt/d/localcode/LocateAnything-3B/Eagle/Embodiedsource/root/miniconda3/etc/profile.d/conda.shconda activate locany_trainexportCUDA_HOME/root/cuda_homeexportPATH$CUDA_HOME/bin:$PATHbash../../../train/finetune_lora_single_gpu.sh# 修改脚本加 --resume_from_checkpoint 参数或临时执行注finetune_lora_single_gpu.sh目前未内置 resume 变量需要在--max_steps $MAX_STEPS \后追加一行--resume_from_checkpoint $RESUME_CKPT \并export RESUME_CKPT/mnt/d/localcode/LocateAnything-3B/train/work_dirs/locany_lora/checkpoint-1500。8. 显存优化实录两次 OOM 的根因与修复背景RTX 3090 只有 24GB官方训练配置max_num_tokens36864 magi 注意力面向 H100 级别显卡。我们在 sdpa 路径上连续遇到两次首步 OOM均已修复。如果未来换卡 / 升级代码请先读本节。8.1 OOM #1LLM 侧 O(L²) 注意力掩码现象首步 forward 时爆 ~13GB 激活显存梯度检查点确认已生效。根因Eagle/Embodied/eaglevl/model/locany/mask_sdpa_utils.py::create_mtp_packing_mask_4d在梯度检查点之外构造稠密[seq_len, seq_len]掩码。原配置max_num_tokens36864→ 36864² 13.59 亿元素bool 张量每个 1.36GB、bf16 每个 2.72GB多个中间量同时存活峰值 13~15GB。修复已完成改动严格布尔等价删掉causal_attnFalse时恒为全一的mutual_condition省 1.36GBcausal_2d只算一次并复用final_mask改为原地logical_or_/logical_and_返回bool 掩码SDPA 约定 Trueattend替代 bf16 的-inf/0.0掩码省 2.72GB且 bool 掩码走更高效的内核路径8.2 OOM #2视觉塔 O(L²) 掩码 SDPA math 回退现象修复 #1 后重跑首步在视觉编码器报错File .../moon_vit/modeling_vit.py, line 135, in sdpa_attention attn_output F.scaled_dot_product_attention(q, k, v, attention_mask, ...) torch.OutOfMemoryError: CUDA out of memory. Tried to allocate 1.34 GiB. GPU 0 has a total capacity of 24.00 GiB of which 2.22 GiB is free. Of the allocated memory 19.17 GiB is allocated by PyTorch根因modeling_vit.py::sdpa_attention把一个打包批次里所有图片的视觉 token 拼成一条长 L 的序列构造[1, L, L]稠密块对角 bool 掩码喂给 SDPA。问题有两层掩码本身 O(L²)更致命SDPA 拿到非平凡掩码后无法走 flash / memory-efficient 内核回退到 math 路径物化[1, 16头, L, L]的注意力分数张量——单次分配就 1.34GB加上各层中间量总峰值 ~19GB修复已完成重写sdpa_attention为逐图独立注意力——按cu_seqlens切段每张图单独调F.scaled_dot_product_attention(qi, ki, vi)不带掩码。数学上与块对角掩码严格等价图片之间本就互不可见但每次调用都能走高效内核彻底消除所有 O(L²) 内存代价只是一次 Python 循环每层几十张图开销可忽略。同文件里的eager_attention有同样的 O(L²) 问题但未修改当前用不到 eager 路径。若未来切到 eager 会再爆届时套用同样的逐图分段方案。8.3 显存预算参考修复后项占用模型权重 bf16LLM 3B ViT 0.4B~7 GBDeepSpeed ZeRO-2 优化器状态LoRAMLP~1 GB视觉塔/LLM 激活梯度检查点开~8-10 GBWindows 桌面/DWM 固定占用~1 GB合计峰值~18-21 GB / 24 GB结论留了约 3-6GB 余量正常训练不需要动任何参数。9. 训练产物与使用9.1 产物位置train/work_dirs/locany_lora/ ├─ checkpoint-500/ # 每 500 步一个最多保留 3 个save_total_limit3 │ ├─ adapter_model.safetensors # LoRA 权重 │ ├─ adapter_config.json │ ├─ optimizer.pt / scheduler.pt / trainer_state.json / rng_state* │ └─ ... ├─ checkpoint-1000/ ... ├─ runs/ # TensorBoard 日志 └─ training_log.txt # 完整训练日志副本训练正常结束时会执行trainer.save_model()最终 LoRA MLP 投影层权重存到work_dirs/locany_lora/根目录。9.2 看 loss 曲线# WSL 内tensorboard--logdir/mnt/d/localcode/LocateAnything-3B/train/work_dirs/locany_lora/runs--port6006# Windows 浏览器打开 http://localhost:60069.3 用训练结果做推理Windows推理服务app.py当前加载的是原始基座模型。微调完成后停止推理服务scripts\stop_inference.bat修改app.py/inference.py的模型加载逻辑加载 LoRA adapterPEFTPeftModel.from_pretrained(base_model, D:/localcode/LocateAnything-3B/train/work_dirs/locany_lora/checkpoint-XXXX, ...)或先用merge_and_unload()把 LoRA 合并成完整权重再加载重启scripts\start_inference.bat验证用训练集里出现过的类别名调/detect比如cysb_cyg对比合并前的检测效果具体合并/加载代码在拿到第一个 checkpoint 后再补手册待办。10. 故障排查手册10.1 快速判断训练是否健康bash/mnt/d/localcode/LocateAnything-3B/train/monitor_training.sh现象判断处理进程存活 GPU 显存 18-21GB 有 loss 记录✅ 正常不用管进程存活 显存 4-5GB 无 loss加载模型/数据中等 2-3 分钟进程已退出 日志尾部有OutOfMemoryErrorOOM见 10.2进程已退出 日志尾部有CUDA error驱动/硬件异常先nvidia-smi看 GPU 状态重启 WSLWindows 执行wsl --shutdown日志报29500 端口被占用上次训练没退干净bash stop_training.sh后重新启动10.2 OOM 处理阶梯按顺序试cd/mnt/d/localcode/LocateAnything-3B/train# 阶梯 1降低打包序列长度掩码/激活随 L² 收敛最有效MAX_NUM_TOKENS2048MAX_SEQ_LENGTH2048bashstart_training.sh# 阶梯 2再加一档MAX_NUM_TOKENS1024MAX_SEQ_LENGTH1024bashstart_training.sh# 阶梯 3减小打包缓冲PACKING_BUFFER_SIZE16bashstart_training.sh注意降 MAX_NUM_TOKENS 会降低吞吐每步处理的样本变少但能立即解决 OOM。先保训练跑通再考虑效率。10.3 其他常见问题问题原因解决缺少依赖 [xxx]conda 环境没激活source /root/miniconda3/etc/profile.d/conda.sh conda activate locany_train找不到 nvidia-smiWSL GPU 直通失效Windows 执行wsl --shutdown后重进还不行就重启电脑微软商店装 Ubuntu 超时网络问题用第 2.4 节的wsl --import离线导入数据转换后类别缺失recipe 里 jsonl 路径/类别名对不上重跑convert_to_locateanything.py看第 5 节校验项Windows 端同时跑推理导致显存不够推理服务占 ~3GB训练前scripts\stop_inference.bat训完再启deepspeed 报 CUDA_HOME 错环境变量没带export CUDA_HOME/root/cuda_home export PATH$CUDA_HOME/bin:$PATH10.4 训练中断了怎么办有 checkpoint见 7.4 从 checkpoint 恢复没 checkpoint500 步中断直接重新bash start_training.sh损失可忽略日志在train/logs/training_run.logWindows 侧可直接用编辑器打开排查11. 常见调参速查所有参数通过环境变量覆盖无需改脚本MAX_STEPS10000bashstart_training.sh# 训更久LR1e-5bashstart_training.sh# 降学习率过拟合/loss 震荡时USE_LLM_LORA128bashstart_training.sh# 加大 LoRA rank欠拟合时MAX_NUM_TOKENS2048bashstart_training.sh# 降序列长度OOM 时PACKING_BUFFER_SIZE16bashstart_training.sh# 减小打包缓冲OOM 时OUTPUT_DIR/mnt/d/...bashstart_training.sh# 换输出目录META_PATH/mnt/d/.../recipe_xxx.jsonbashstart_training.sh# 换数据配方效果调优建议77 类样本量极不均衡86 ~ 17199 条/类稀有类别召回差时在 recipe JSON 中给稀有类别对应的数据集提高repeat_time5000 步后 loss 仍在明显下降 → 加大 MAX_STEPS 到 10000~20000学习率 2e-5 是 LoRA 微调的常规值若 loss 爆 NaN降到 1e-5 并检查是否 OOM 边缘识别前微调后附修改过的官方代码清单升级/还原时必读文件修改内容原因Eagle/Embodied/eaglevl/model/locany/mask_sdpa_utils.pycreate_mtp_packing_mask_4d消除 O(L²) 中间量返回 bool 掩码OOM #1LLM 侧掩码 13GBEagle/Embodied/eaglevl/model/moon_vit/modeling_vit.pysdpa_attention稠密掩码 → 逐图独立 SDPAOOM #2视觉侧掩码 math 回退 19GBtrain/finetune_lora_single_gpu.sh官方脚本适配 3090sdpa / seq 4096 / 本地路径 / 去 wandb硬件适配app.py/inference.pydevice 自动检测 cudaWindows 推理加速若官方代码更新git pull会覆盖前两个文件OOM 会复现需重新应用修复见第 8 节。