训练常见问题
这一页汇总 VortLab 训练过程中的高频问题，给出排查思路和解决方向。每个问题都按「现象 + 原因 + 处理」的思路写，遇到问题先翻这里。
训练任务卡在「训练中」不动
Q：训练任务一直显示「训练中」，进度不更新怎么办？
最常见的原因是服务器重启或 Docker 容器重建，训练子进程被杀掉了，但数据库里状态还停在 training。
现象：训练日志长时间没新内容，进度条不动，状态显示「训练中」。 原因：服务重启时不会自动恢复训练（避免 OOM 循环 + GPU 资源冲突）。 处理：
- 平台在启动时会自动把卡住的任务标记为
failed，并尝试回填上次的 checkpoint（检测输出目录里的last.pt）。 - 如果任务没自动变成 failed，刷新一下页面再看。
- 任务变 failed 之后，点任务行的「继续训练」按钮，从断点恢复，不用从头开始。详见训练日志与排错。
GPU 训练时提示 CUDA 不可用
Q：创建训练任务时 GPU 显示「不可用」，或训练报 CUDA 错误？
按以下顺序排查：
- 显卡驱动是否正常：在宿主机跑
nvidia-smi，能正常输出说明驱动 OK。报错或找不到命令，重装驱动。 - CUDA / PyTorch / Python 版本是否匹配：推荐组合是 CUDA 12.6 + Python 3.12 + 最新 Ultralytics。版本不匹配会让 PyTorch 找不到 CUDA 运行时。
- Docker 部署是否装了 NVIDIA Container Toolkit：容器内访问宿主机 GPU 必须装这个工具包，否则容器里
nvidia-smi报命令不存在。安装后重启 Docker daemon。 - 多卡机器检查 GPU 占用：有可能其他进程占满了 GPU 显存，新任务分配不到资源。跑
nvidia-smi看显存使用情况。
详细排查见GPU 训练配置。
训练 mAP 一直很低
Q：训练跑完了，但 mAP 很低，怎么调？
mAP 低通常是数据问题，不是超参问题。按这个顺序排查：
- 检查标注质量：抽 20 张图人工看一遍，框 / 多边形是否贴合目标。标注不准是 mAP 低的头号原因。
- 检查数据量是否足够：检测任务每个类别至少 100~300 张图，类别样本严重不平衡会拖低整体指标。
- 检查类别分布：是不是某个类别样本太少？考虑做数据增强或人工补标。
- 检查学习率是否合适：默认 0.01，如果 loss 曲线抖动太大就调小（0.001），太平就调大。详见训练参数详解。
- 尝试更多 epochs：100 轮可能不够，试试 200 或 300。但要看 loss 曲线是否还在下降，不降了就别加了。
- 检查验证集是否合理：验证集太小或分布偏差会给出误导性的 mAP。建议至少 50 张验证图。
绝大多数情况是前两项的问题，先把数据搞干净再调超参。
训练内存不足（OOM）
Q：训练时报 `CUDA out of memory` 怎么办？
显存不够，最直接的解决办法是减小显存占用。优先按以下顺序调整：
- 减小批次大小（batch size）：从 16 改到 8 或 4，显存占用和 batch 成正比，效果最直接。
- 减小图像尺寸（image size）：从 640 改到 512 或 416，显存占用和图像尺寸的平方成正比。
- 关闭矩形训练（如果开了）：rect 模式有时会让显存峰值更高。
- 减少 GPU 卡数：排除多卡通信或显存分配异常。
- 升级硬件：如果调到 batch=4 还是 OOM，说明硬件本身就不够，只能换更大显存的卡。
调整后重新创建训练任务即可。详细思路见训练日志与排错。
训练完成后模型在哪里
Q：训练跑完了，但我找不到模型？
训练完成后产物默认进入「待发布」状态（draft），需要手动发布才会出现在模型管理里。两个查看入口：
- 训练详情面板：点开训练任务，在详情面板顶部有「发布」按钮。点它打开发布对话框，确认后产物注册为对应 Model 下的新 Version。
- 项目工作区 → 模型 Tab：发布后的模型出现在这里。详情见模型管理。
想先测试再决定发不发布？在训练详情面板点「测试此 draft」，可以在交互式检测页直接跑这个未发布的权重。满意再回去点「发布」。
同时运行多个训练任务
Q：能同时跑多个训练任务吗？
分情况：
- GPU 模式：系统会阻止同时运行多个 GPU 训练任务。原因是显存竞争会让两个任务都跑不动，甚至触发 OOM 一起失败。新任务会排队等当前任务结束。
- CPU 模式：可以同时跑，但很慢。CPU 训练本身就慢，并行只会让每个任务更慢，不建议。
如果你确实需要并行训练（比如对比不同超参），有两个选项：
- 串行跑：把多个任务排队，一个跑完自动接下一个。
- 多机训练：部署多个平台实例，每个实例跑独立任务。需要运维支持。
训练日志怎么看
Q：怎么看训练日志？支持多 session 吗？
在训练监控页（项目工作区训练菜单或全局训练总览）的任务行里，点「查看日志」按钮，打开日志弹窗。
日志弹窗是终端样式（绿色等宽字体），训练进行中时每 5 秒自动刷新。支持的操作：
- 按 session 分段查看：训练任务可以多次运行（第一次训练失败后继续训练会生成新 session）。
GET /training/{task_id}/logs?session=N只返回第 N 次运行的日志。 - 清除日志：
DELETE /training/{task_id}/logs清空全部；DELETE /training/{task_id}/logs?session=N仅清空第 N 次，保留其他 session。 - 下载日志：点「下载日志」保存为文本文件，文件名格式
training_logs_{任务ID}.txt，方便发给技术支持。
详见训练日志与排错。
NPU（昇腾）训练怎么配置
Q：华为昇腾 NPU 怎么用来训练？
NPU 训练需要的环境比较挑剔，配置时严格按以下顺序确认：
- 驱动 / 固件 / CANN 版本匹配：昇腾的版本依赖链比较长，驱动、固件、CANN 软件栈、
torch_npu、Python 版本必须严格匹配，不能跨大版本混装。详见昇腾 NPU 训练。 - 创建训练任务时选「华为昇腾 NPU」：如果环境不可用，下拉框会标注「（不可用）」并禁用。说明 NPU 环境没就绪，回到第一步排查。
- NPU 内存限制：选 NPU 后会出现「NPU 内存限制 (MB)」配置项，按硬件显存设置上限。
跑通 NPU 训练通常比 GPU 配置更复杂，建议先在 CPU 模式下跑通流程验证数据，再切到 NPU。