企业官网建设流程全解析

1. 为什么在 Windows 10 上折腾 YOLOX 值得单独写一篇

YOLOX 是旷视开源的一套目标检测框架，和 YOLOv5 那种“开箱即用、封装到牙齿”的风格不同，它更接近学术实现，Anchor-Free 的检测头、解耦头设计、SimOTA 标签分配策略，这些在当年都是相当有代表性的改进。很多做视觉项目的朋友第一次接触它，往往是在 Linux 服务器上跑通的，但真正落到自己手头的 Windows 10 工作站上，问题就来了——编译报错、依赖冲突、CUDA 版本对不上、pycocotools 装不上，一套组合拳下来能劝退不少人。

我自己前前后后在 Windows 10 上装过不下十次 YOLOX，从最初的“照着 README 硬怼”到后来总结出一套相对稳定的流程，中间踩的坑足够写满两页纸。这篇内容就是把这套流程完整拆开，讲清楚每一步为什么这么做、参数怎么选、报错怎么排查。适合的人群很明确：手头只有 Windows 机器、想跑通 YOLOX 训练和推理、对 Python 环境管理有一定了解但不算精通的开发者。如果你正好卡在某个报错上，或者准备从零开始搭环境，这篇可以直接抄作业。

需要提前说明的是，YOLOX 官方对 Windows 的支持并不算一等公民，很多脚本默认是 Linux 路径风格，所以整个安装过程的核心思路就是：用最接近官方推荐的依赖版本，把 Windows 上不兼容的部分逐个替换掉。理解了这条主线，后面所有操作都不会觉得突兀。

2. 环境整体设计与版本选型思路

2.1 为什么版本选型比安装步骤更重要

装深度学习框架这件事，很多人习惯直接pip install最新版，结果就是各种莫名其妙的报错。YOLOX 这类项目对版本极其敏感，原因在于它依赖 PyTorch、TorchVision、CUDA、cuDNN、pycocotools 这一整条链路，任何一个环节版本错位，轻则警告，重则直接崩。

我的建议是：先定 CUDA 版本，再定 PyTorch 版本，最后定 Python 版本。这个顺序不能反。因为 CUDA 取决于你显卡驱动支持的最高版本，PyTorch 又必须匹配 CUDA，Python 则要匹配 PyTorch 支持的版本范围。

以我手头一台常见的 Windows 10 工作站为例，显卡是 RTX 3060，驱动版本较新，支持到 CUDA 11.x。那么整套选型可以这样定：

这张表不是随便填的。PyTorch 1.10 是少数几个在 Windows 上同时提供 CUDA 11.3 预编译 wheel 的版本，省去了自己编译的麻烦。Python 3.8 则是 YOLOX 依赖里pycocotools、onnx等库都还有稳定轮子的版本，用 3.9 或 3.10 会遇到部分包没有 Windows 轮子、必须本地编译的窘境。

2.2 虚拟环境：别在 base 环境里乱装

这一点我吃过亏。早期图省事直接在 Anaconda 的 base 环境里装，结果后来装别的项目时依赖打架，只能重装 Anaconda。正确做法是用 conda 单独建一个环境：

conda create -n yolox python=3.8 conda activate yolox

用 conda 而不是 venv 的原因在于，conda 能帮你管理一些非 Python 的二进制依赖，比如某些情况下需要装的ninja、cmake，conda 装起来比 pip 省心。环境名随意，我这里用yolox只是方便记忆。

提示：如果你之前装过 CUDA 但不确定版本，可以在命令行执行nvcc --version查看。如果提示找不到命令，说明 CUDA Toolkit 没装或者没加进 PATH，这时候需要先装 CUDA Toolkit，光有驱动是不够的。

2.3 源码获取方式的选择

YOLOX 的代码建议直接从官方仓库 clone，而不是下载 zip 包。原因有两个：一是 clone 下来的目录结构完整，包含setup.py和yolox包目录，方便后续pip install -e .做可编辑安装；二是后续想切换分支或者拉更新都方便。

git clone https://github.com/Megvii-BaseDetection/YOLOX.git cd YOLOX

如果你网络环境访问 GitHub 不稳定，这一步可能需要多试几次，或者用镜像站。代码拉下来之后先别急着装依赖，把requirements.txt打开看一眼，里面有些包在 Windows 上需要特殊处理，后面会逐个讲。

3. 核心依赖安装与关键细节拆解

3.1 PyTorch 与 TorchVision 的正确装法

这是整个流程里最容易出错的一步。很多人直接pip install torch，装到的是 CPU 版本，跑起来慢得让人怀疑人生。正确做法是去 PyTorch 官网的 Previous Versions 页面，找到对应 CUDA 版本的安装命令。

以 CUDA 11.3 + PyTorch 1.10.0 为例，命令是：

pip install torch==1.10.0+cu113 torchvision==0.11.0+cu113 torchaudio==0.10.0 -f https://download.pytorch.org/whl/cu113/torch_stable.html

注意+cu113这个后缀，它明确指定了 CUDA 版本。装完之后一定要验证：

import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))

如果cuda.is_available()返回 False，说明装成了 CPU 版，或者 CUDA 与 PyTorch 版本不匹配。这时候别急着往下走，先把这个问题解决掉，否则后面训练时会直接报错。

注意：有些教程会让你先装 CUDA Toolkit 再装 PyTorch，其实 PyTorch 的预编译包自带 CUDA 运行时，只要驱动版本够，不装完整 CUDA Toolkit 也能跑。但 YOLOX 编译某些扩展时需要nvcc，所以 Toolkit 还是建议装上。

3.2 pycocotools 在 Windows 上的安装技巧

pycocotools是 YOLOX 评估 COCO 数据集指标时必须的包，但它在 Windows 上装起来很麻烦，因为官方只提供 Linux 的编译好的包，Windows 需要本地编译，而编译又依赖 Visual C++ Build Tools。

我试过几种方案，最稳的是用别人预编译好的 Windows 轮子：

pip install pycocotools-windows

这个包是社区维护的 Windows 版本，接口和官方一致，YOLOX 里from pycocotools.coco import COCO这种导入完全兼容。如果你坚持要用官方版，那就得先装 Visual Studio Build Tools，勾选“使用 C++ 的桌面开发”，然后pip install pycocotools，编译过程大概几分钟，中途可能报各种头文件找不到的错误，不推荐新手走这条路。

3.3 其他依赖的逐个处理

YOLOX 的requirements.txt里还有几个包需要留意：

• onnx和onnxruntime：如果你要做模型导出和推理，这两个必装。Windows 上直接 pip 装就行，注意 onnxruntime 要选 GPU 版本的话用onnxruntime-gpu。
• opencv-python：建议装opencv-python而不是opencv-contrib-python，后者体积大且很多功能用不上。版本选 4.5.x 比较稳。
• tensorboard：训练可视化用，pip 直接装，注意它依赖的protobuf版本，有时候会和别的包冲突，遇到报错就手动降级到 3.20.x。
• loguru、tqdm、thop：这些是工具类包，直接装没问题。

安装命令可以一条条来，也可以直接：

pip install -r requirements.txt

但我不建议直接跑这条，因为里面有些包版本没锁死，可能会装到不兼容的新版本。我的做法是先把requirements.txt里的版本号都看一眼，把明显偏新的包手动降级，再逐个装。

3.4 YOLOX 本体的可编辑安装

依赖装完后，在 YOLOX 根目录执行：

pip install -e .

这个-e表示可编辑安装，意思是把当前目录作为包安装，后续你改代码不用重新装。执行完会看到Successfully installed yolox之类的提示。如果报错说找不到setup.py，检查一下你是不是在 YOLOX 根目录下执行的。

装完之后验证一下：

python -c "import yolox; print(yolox.__version__)"

能打印出版本号就说明装好了。

4. 实操全流程与关键环节记录

4.1 从零开始的完整命令序列

把前面所有步骤串起来，一条完整的安装流程是这样的。我按实际执行顺序写，你可以直接照着敲：

# 1. 创建并激活环境 conda create -n yolox python=3.8 -y conda activate yolox # 2. 安装 PyTorch（CUDA 11.3 版本） pip install torch==1.10.0+cu113 torchvision==0.11.0+cu113 torchaudio==0.10.0 -f https://download.pytorch.org/whl/cu113/torch_stable.html # 3. 验证 PyTorch python -c "import torch; print(torch.cuda.is_available())" # 4. 克隆 YOLOX git clone https://github.com/Megvii-BaseDetection/YOLOX.git cd YOLOX # 5. 安装 pycocotools Windows 版 pip install pycocotools-windows # 6. 安装其他依赖 pip install opencv-python==4.5.5.64 pip install onnx onnxruntime-gpu pip install tensorboard loguru tqdm thop # 7. 可编辑安装 YOLOX pip install -e .

这套流程我在三台不同配置的 Windows 10 机器上跑过，只要显卡驱动版本够，基本都能一次成功。唯一需要注意的是第 2 步，如果你的 CUDA 是 11.6 或更高，PyTorch 版本要相应换成 1.12 或 1.13，命令里的cu113也要改成cu116之类。

4.2 验证安装是否成功的三个测试

装完不代表能用，得跑几个测试确认。第一个是前面说的torch.cuda.is_available()，这个必须为 True。

第二个是跑 YOLOX 自带的 demo：

python tools/demo.py image -n yolox-s -c yolox_s.pth --path assets/dog.jpg --conf 0.25 --nms 0.45 --tsize 640 --save_result --device gpu

这里需要先下载预训练权重yolox_s.pth，放到 YOLOX 根目录。权重文件大概几十兆，下载地址在官方 README 里有。跑通的话会在YOLOX_outputs目录下生成带检测框的图片。

第三个是训练测试，用 COCO 数据集的一小部分或者自己准备几张图，跑一个 epoch 看看能不能正常前向反向传播。这一步能过，说明整个环境彻底没问题了。

4.3 训练自己数据集时的配置修改

YOLOX 训练自定义数据集需要改几个地方，这里简单带一下，因为很多人装完环境就是为了训自己的数据。

首先在datasets目录下按 VOC 或 COCO 格式组织数据，然后在exps/example/yolox_voc或类似目录下复制一份配置文件，修改里面的num_classes、data_dir、train_ann等字段。Windows 上路径要用双反斜杠或者正斜杠，单反斜杠会被当成转义字符。

启动训练的命令：

python tools/train.py -f exps/example/yolox_voc/yolox_voc_s.py -d 1 -b 8 --fp16 -o -c yolox_s.pth

-d 1表示用一张显卡，-b 8是 batch size，显存不够就往下调，--fp16开启混合精度训练能省显存，-c指定预训练权重。

提示：Windows 上如果报DataLoader worker exited unexpectedly，多半是num_workers设太大了，在配置文件里把它改成 0 或 2 试试。这是 Windows 多进程的老问题，Linux 上很少遇到。

5. 常见报错与排查技巧实录

5.1 安装阶段的高频报错

报错一：ERROR: Could not find a version that satisfies the requirement torch==1.10.0+cu113

这个通常是因为 pip 源的问题。PyTorch 的 CUDA 版本包不在默认 PyPI 源里，必须加-f https://download.pytorch.org/whl/cu113/torch_stable.html这个参数。如果加了还报错，检查网络能不能访问这个地址，或者换个时间段再试。

报错二：Microsoft Visual C++ 14.0 or greater is required

这是编译 pycocotools 或其他 C 扩展时报的。解决方案有两个：一是装 Visual Studio Build Tools，勾选 C++ 桌面开发；二是直接用预编译轮子，比如前面说的pycocotools-windows。我推荐后者，省事。

报错三：ImportError: DLL load failed while importing _C

这个多半是 PyTorch 和 CUDA 版本不匹配，或者缺了某个运行时库。先确认torch.cuda.is_available()，如果是 False，重装 PyTorch。如果 True 但还报这个错，装一下vc_redist.x64.exe，微软官网有下载。

5.2 运行阶段的高频报错

报错四：RuntimeError: CUDA out of memory

显存不够。解决办法：把 batch size 调小，开启--fp16，或者用更小的模型（yolox-nano 或 yolox-tiny）。另外检查一下是不是有别的进程占着显存，任务管理器里看看。

报错五：AssertionError: Torch not compiled with CUDA enabled

这个和报错三类似，本质是装成了 CPU 版 PyTorch。卸载重装，注意命令里带+cu113后缀。

报错六：训练时 loss 变成 NaN

学习率太大或者数据有问题。先把学习率降一个数量级试试，检查标注文件里有没有坐标越界或者类别编号超范围的情况。

5.3 排查思路速查表

这张表基本覆盖了我遇到过的九成问题，剩下的疑难杂症多半是环境装乱了，最彻底的办法是删掉 conda 环境重来一遍。

6. 一些踩坑之后才明白的经验

装 YOLOX 这件事，说难不难，说简单也不简单。我最大的体会是：别贪新。很多人看到 PyTorch 出了 2.x 就想装最新版，结果 YOLOX 的代码里有些 API 在新版里改了，跑起来各种警告甚至报错。老老实实用官方验证过的版本组合，能省掉大量排查时间。

另一个经验是关于路径的。Windows 用反斜杠，Linux 用正斜杠，YOLOX 的代码里很多地方是硬编码的正斜杠，在 Windows 上跑一般没问题，但如果你自己写脚本处理路径，记得用os.path.join或者pathlib，别手拼字符串。

还有就是权重文件的下载。官方提供的下载链接有时候速度很慢，可以找国内的镜像源，或者用下载工具挂着慢慢下。权重文件不对会导致加载时报unexpected key之类的错误，这时候检查一下模型名和权重名是否对应，yolox-s 的权重不能拿去加载 yolox-m 的模型。

最后分享一个小技巧：如果你只是想做推理不想训练，其实可以跳过pip install -e .这一步，直接把yolox目录加到sys.path里也能用。但训练的话还是老老实实装，因为训练脚本里有些相对导入依赖包结构。

这套流程后续还可以扩展的方向包括：导出 ONNX 模型做部署、用 TensorRT 加速推理、在 WSL2 里跑一套 Linux 环境做对比。不过那是另一个话题了，先把 Windows 原生环境跑通，后面的事都好说。