[Doc] Add Windows CPU inference guide for YOLO-Master

[Aliferous-spec]

@

Windows CPU 推理配置指南 for YOLO-Master

环境信息

项目	详情
操作系统	Windows 11 版本 10.0.26200.8655
CPU	Intel(R) Core(TM) Ultra 5 225H
Python 版本	Python 3.9.7
运行模式	CPU Only（无 CUDA 显卡）
YOLO-Master 版本	main 分支

---

1. 克隆仓库并创建虚拟环境

git clone https://github.com/Tencent/YOLO-Master.git
cd YOLO-Master
python -m venv venv
.\venv\Scripts\activate

2. 安装 PyTorch CPU 版本（关键步骤）

这是最容易出问题的步骤。Windows + CPU 模式下，如果直接 pip install -r requirements.txt，pip 会默认安装 PyTorch 的 CUDA 版本，导致运行时出现 CUDA 相关错误。

常见错误：

RuntimeError: Could not find CUDA drivers
ImportError: DLL load failed while importing _C: 找不到指定的模块。

正确做法： 先手动安装 PyTorch CPU 版本，再安装其他依赖。

# 安装 PyTorch CPU 版本（适配 Python 3.9 + Windows）
pip install torch==2.0.1 --index-url https://download.pytorch.org/whl/cpu
pip install torchvision==0.15.2 --index-url https://download.pytorch.org/whl/cpu

⚠️ 重要提示：YOLO-Master 的 pyproject.toml 已明确排除 PyTorch 2.4.0 在 Windows 上的使用：

torch>=1.8.0,!=2.4.0; sys_platform == win32

这是因为 PyTorch 2.4.0 在 Windows CPU 环境下存在已知的 DLL 兼容性问题（参见 ultralytics/ultralytics#15049）。建议使用 PyTorch 2.0.x 或 2.1.x 版本。

3. 安装其余依赖

pip install -r requirements.txt

如果安装过程中遇到 peft 版本冲突（peft>=0.18.0,<0.20.0），可以暂时跳过——peft 仅在训练 LoRA 模型时需要，CPU 推理不受影响：

pip install numpy>=1.23.0 matplotlib>=3.3.0 opencv-python>=4.6.0 pillow>=7.1.2 pyyaml>=5.3.1 requests>=2.23.0 scipy>=1.4.1 psutil>=5.8.0 polars>=0.20.0 ultralytics-thop>=2.0.18 tqdm>=4.64.0 pandas>=1.1.4 seaborn>=0.11.0

4. 验证安装

import torch
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")  # Expected: False
print(f"CPU threads: {torch.get_num_threads()}")

from ultralytics import YOLO
print("Ultralytics YOLO loaded successfully!")

预期输出：

PyTorch version: 2.0.1+cpu
CUDA available: False
CPU threads: 16
Ultralytics YOLO loaded successfully!

5. 运行 CPU 推理

下载预训练模型：

python scripts/download_weights.py

图像推理：

python app.py --source path/to/your/image.jpg --weights yolo-master-n.pt --device cpu

或使用 Python API：

from ultralytics import YOLO

model = YOLO("yolo-master-n.pt")
results = model("path/to/image.jpg", device="cpu")

for r in results:
    print(f"Detected {len(r.boxes)} objects")
    r.show()

6. Windows 特定注意事项

1. 路径分隔符：建议在 Python 字符串中使用 / 或原始字符串 r"path\to\file"，避免 \ 被解释为转义字符。
2. 多进程：CPU 推理时建议设置 workers=0 以避免 Windows 下多进程序列化问题：

   results = model("image.jpg", device="cpu", workers=0)

3. 内存占用：CPU 推理时内存占用较高。Intel Core Ultra 5 225H（16 线程）足以流畅运行 YOLO-Master-N/S 等轻量模型，建议关闭其他大型应用以释放内存。
4. OpenCV 显示问题：如果 cv2.imshow() 窗口无响应，可改用 results.save() 直接保存结果图片。

参考链接

• Ultralytics YOLO 官方文档
• YOLO-Master (CVPR 2026)
• PyTorch CPU 版本安装
• Windows PyTorch 2.4.0 兼容性问题

---

我想提交永久居民申请，把这个添加为文档文件。
@

[Aliferous-spec]

我想提交永久居民申请，把这个添加为文档文件。