环境与常见问题¶

完整包应保留哪些内容¶

分发完整的软件文件夹，包括主程序、_internal、经典环境目录和异常检测环境目录。客户需要可用的显卡驱动及适配的系统运行库；软件内包含框架运行库，不代表可以替代 NVIDIA 驱动。

MkDocs 只用于开发时生成文档，客户不需要安装 MkDocs、Python 或另一个网页服务器。帮助由软件开启只监听本机地址的轻量服务，五种语言页面及搜索资源随包提供。

帮助网页位于随包的 _internal/help_site。该目录用于帮助入口，不能按普通说明文档随意删掉。软件根目录的 docs 技术说明和 package-manifest.json 仍不是训练/推理的运行依赖；manifest 用于文件完整性排查。

为什么没有 mAP¶

先确认是否有独立验证集，再看是否到了验证轮次。经典 COCO 只有训练集时不运行验证，也不自动分出图片。若已执行验证仍没有有效值，查看原始验证日志，不使用 loss 替代评估。

GPU 利用率不高¶

GPU 百分比取决于实际任务、批次、图片尺寸、数据读取、CPU 预处理和采样间隔。GPU 利用率与显存使用率不是同一概念。检查日志是否真的选中了 GPU，以及 data_cost 是否占据较大比例；经典 Windows 可适度调整 workers，再比较实际吞吐量。

内存或显存不足¶

先减小 batch，再按任务降低图像尺寸。异常检测还可降低候选特征上限、核心集上限或保留比例。不同任务参数含义不同，不要把核心集上限理解成 batch。

经典模型仍在下载预训练权重¶

“使用配置文件中的预训练设置”会沿用 URL，客户机不一定已有缓存。离线时选本地兼容权重或随机初始化。程序结构存在不等于预训练权重已缓存。

权重、类别或预处理不匹配¶

使用与权重一致的任务、配置、类别顺序和预处理。经典模型可从训练实验导入；现代分类要保留模型中的预处理元数据。不要拿普通检测模型到 OBB 页面，或把导出的经典静态模型当作 .pdparams 检查点。

ONNX 为什么在 CPU 上运行¶

当前主推理页面对现代 ONNX 强制使用 CPU，并在原始日志中提示。选择 GPU 不会解除这项现有兼容性策略。

帮助页面或搜索打不开¶

保持软件开启，从侧边栏重新打开帮助，检查默认浏览器和本机访问权限。无需互联网。若提示文档缺失，使用包含 help_site 的完整新版本；旧包不会因为源码新增文档而自动获得帮助。