YOLO-World Docker 环境配置与使用指南

YOLO-World Docker 环境配置与使用指南

作者：zzy-swimming
指导：

目录

  1. #前言
  2. #查看电脑状况
  3. #核心概念与软件清单
    • #3.1-所需软件组件
    • #3.2-为什么需要-wsl-2
  4. #安装与配置wsl2
    • #4.1-启用-wsl-和虚拟机平台功能
    • #4.2-安装-linux-发行版
    • #4.3-安装-wsl-2-linux-内核更新包
    • #4.4-将-wsl-2-设置为默认版本
    • #4.5-检查当前wsl状态
  5. #安装-docker-desktop
    • #5.1-前提条件
    • #5.2-下载安装程序
    • #5.3-安装过程
    • #5.4-验证安装
    • #5.5-配置国内镜像加速器
  6. #使用-docker-复现-yolo-world
    • #6.1-拉取-ultralytics-镜像
    • #6.2-准备本地目录
    • #6.3-启动容器并挂载目录
    • #6.4-cpu推理测试
  7. #配置与使用gpu环境
    • #7.1-在您的主机系统上安装nvidia-container-toolkit
    • #7.2-验证gpu环境
    • #7.3-使用支持gpu的docker命令启动容器
    • #7.4-使用gpu运行您的yolo-world脚本
  8. #查看结果
  9. #ps将ubuntu移动到f盘的操作方法

1. 前言

本文档详细介绍了在 Windows 系统上配置 YOLO-World 所需的环境和依赖。通过使用 Docker 和 WSL 2，您可以快速搭建一个稳定、高效的深度学习环境，避免复杂的本地环境配置问题。

2. 查看电脑状况

深度学习的训练对于电脑显卡要求较高，若电脑没有独立显卡（NVIDIA卡）或者是AMD的显卡无法使用GPU进行训练，需用CPU进行训练，会慢很多。若不清楚电脑有无显卡可以打开任务管理器，点击性能往下找GPU，就可以看到是否有独立显卡，不清楚是否为独立显卡则搜索型号。

3. 核心概念与软件清单

3.1 所需软件组件

一、系统功能组件（Windows 功能）

  • Windows Subsystem for Linux (WSL)：用于在 Windows 上运行 Linux 环境的核心功能。
  • 虚拟机平台 (Virtual Machine Platform)：WSL 2 依赖的底层虚拟化功能。

二、核心软件

  • 一个 Linux 发行版 (Linux Distribution)：例如从 Microsoft Store 安装的 Ubuntu (推荐 LTS 版本，如 22.04)。
  • WSL 2 Linux 内核更新包 (wsl_update_x64.msi)：确保 WSL 2 正常运行的微软官方内核补丁。
  • Docker Desktop for Windows：管理和运行 Docker 容器的主要软件。

3.2 为什么需要 WSL 2

在现代 Windows 系统上运行 Docker 有两种传统模式：

  • Docker Toolbox（已废弃）：基于 VirtualBox 虚拟机，性能差，体验不佳
  • Hyper-V 后端：使用 Windows 的 Hyper-V 虚拟化技术创建轻量级 Linux VM

现在，Docker Desktop 官方强烈推荐并默认使用 WSL 2 作为后端，原因如下：

性能巨大提升：

  • 文件系统访问：在 WSL 2 中，对绑定挂载的 Windows 文件的读写速度远超传统的 Hyper-V VM 模式
  • 启动时间：WSL 2 的启动几乎是瞬时的

更好的资源集成：

  • WSL 2 可以更智能地与 Windows 共享 CPU、内存和存储资源

无缝体验：

  • 可以在 Windows 终端和 WSL 2 的 Linux 终端之间无缝切换

4. 安装与配置WSL2

4.1 启用 WSL 和虚拟机平台功能

以管理员身份打开 Windows PowerShell 或命令提示符(CMD)，运行以下命令：

1
2
3
4
5
# 启用"Windows Subsystem for Linux"功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用"虚拟机平台"功能（WSL 2的核心要求）
dism.exe /enable-feature /online /featurename:VirtualMachinePlatform /all /norestart

完成后，按照提示重启电脑。

注意：您注意到没有重启提示，这是因为您使用了 /norestart参数。这个参数的作用是：
/norestart = “不重启” (No Restart)
这个参数明确告诉系统：”完成这个操作后，不要自动重启电脑”

完成后，手动重启电脑。

4.2 安装 Linux 发行版

  1. 打开 Microsoft Store 应用
  2. 搜索 “Ubuntu”（或 “Debian” 等其他发行版）
  3. 选择最新的 Ubuntu LTS 版本（例如 Ubuntu 22.04 LTS），点击”获取”或”安装”
  4. 安装完成后，从开始菜单启动它，设置 UNIX 用户名和密码

4.3 安装 WSL 2 Linux 内核更新包

  1. 访问微软官方下载页面：https://docs.microsoft.com/zh-cn/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package
  2. 下载并运行 wsl_update_x64.msi安装程序
  3. 按照提示完成安装

问题一：实际操作中，我把安装Linux发行版这一步骤忘记了，在安装WSL2 Linux内核更新包时，出现了如下图所示的报错。

[图片: WSL2内核更新包安装错误截图]

错误原因：我跳过了安装 WSL 发行版的步骤，直接尝试安装 WSL 2 内核更新包。但系统检测到您还没有安装任何 WSL 发行版（如 Ubuntu），所以拒绝安装更新。

4.4 将 WSL 2 设置为默认版本

打开 PowerShell（无需管理员权限），输入：

1
wsl --set-default-version 2

此命令会告诉系统，以后任何新安装的 Linux 发行版都默认使用 WSL 2。

4.5 检查当前WSL状态

在PowerShell中运行以下命令，查看当前的WSL配置：

1
2
3
4
5
# 检查WSL状态和版本
wsl --status

# 列出已安装的发行版
wsl --list --verbose

问题二：在实际操作过程中，我跳过了WSL2更新包，直接进入下一步安装 Docker Desktop。

因为我的系统显示 默认版本：2，这证明 WSL 2 已经成功启用。可能的情况是：

  • Windows 更新已经自动安装了所需的组件
  • 或者 Docker Desktop 安装程序会自动处理剩余依赖

目前我仍未可知跳过WSL2更新包的具体原因。

5. 安装 Docker Desktop

5.1 前提条件

  • Windows 10 版本 2004 及以后或 Windows 11
  • 开启 BIOS/UEFI 中的虚拟化支持（Intel VT-x/AMD-V）
  • 确保开启 Hyper-V 和容器功能

5.2 下载安装程序

访问 Docker 官网的 Desktop 下载页面：
https://www.docker.com/products/docker-desktop/

下载 Docker Desktop for Windows 安装程序

选择 AMD64 还是 ARM64 版本的 Docker Desktop，完全取决于您电脑的CPU 处理器架构。绝大多数 Windows 电脑都使用 AMD64 架构。

要最准确地确认，您可以：

  1. 按下 Win + R键
  2. 输入 cmd并按下回车，打开命令提示符
  3. 在黑色的命令提示符窗口中，输入并执行：
1
echo %PROCESSOR_ARCHITECTURE%

查看输出结果：

  • 如果显示 AMD64 → 请下载 AMD64 版本。
  • 如果显示 ARM64 → 请下载 ARM64 版本。

5.3 安装过程

  1. 双击下载好的 Docker Desktop Installer.exe
  2. 按照安装向导的提示进行，所有选项保持默认即可
  3. 安装完成后，重启电脑

5.4 验证安装

  1. 重启后，在开始菜单中找到并运行”Docker Desktop”
  2. 等待 Docker 服务启动（系统托盘会出现一只鲸鱼图标）
  3. 打开命令提示符(CMD)或 PowerShell，输入以下命令：
1
docker --version

如果安装成功，它会返回 Docker 的版本号。

验证WSL2和Docker环境是否正确

在 PowerShell 里运行 docker run hello-world来测试。如果这个命令能成功运行并打印出 “Hello from Docker!”，就证明你的整WSL2和Docker环境是完全正常的。

5.5 配置国内镜像加速器

为了提升拉取镜像的速度，建议配置国内镜像源。

  1. 右键点击任务栏的 Docker 图标，选择 Settings。
  2. 在左侧找到 Docker Engine菜单。
  3. 在右侧的配置窗口中，添加或修改 registry-mirrors项。填入以下国内镜像源之一：
1
2
3
4
5
6
7
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn", // 中国科技大学
    "https://hub-mirror.c.163.com",       // 网易
    "https://mirror.baidubce.com"         // 百度
  ]
}
  1. 点击 Apply & Restart。Docker 会保存配置并重启。

6. 使用 Docker 复现 YOLO-World

6.1 拉取 Ultralytics 镜像

打开终端，执行：

1
docker pull ultralytics/ultralytics:latest

问题三：由于网络问题导致的Docker镜像拉取失败。问题三，说白了，它就是科学上网的问题。你如果拥有自己稳定的科学上网的途径，直接通过那个途径就OK。我个人在尝试了两种方法之后，其实全都遇到了网络方面的问题。像方法一里面的他让你更换镜像。实际上呢，我在更换镜像过后，发现那个镜像依然存在问题。最终我之所以能成，还是因为有维多利亚大学官方提供的VPN。虽然这个VPN限速，但是我把我的电脑搁这儿跑了一上午，也是成功的把它下载下来了。

（鉴于这个网络问题有点抽象，我把我下载下来的文件上传到one drive上面了，别人可以直接下载。链接：https://1drv.ms/f/c/1383ab78469327ac/ErHzib4j221FhN6I4nhFLyoB2XDStTJJolkQj7UT-UYUZg?e=sXkQGb）

问题三解决方案：能成的Docker方案：绕过网络抽风

核心思路：换源+重试+手动构建。我们将采用一种更稳定、更可控的方法来构建Docker环境。

方法一：使用国内镜像源加速拉取

Docker默认从Docker Hub（国外）拉取镜像，速度慢且不稳定。我们可以配置使用国内的镜像加速器。

配置Daemon（守护进程）：

  1. 右键点击任务栏的Docker图标，选择 Settings。
  2. 在左侧找到 Docker Engine菜单。
  3. 在右侧的配置窗口中，找到或添加 registry-mirrors项。填入以下国内常用的镜像源（可以多试几个）：
1
2
3
4
5
6
7
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn", // 中国科技大学
    "https://hub-mirror.c.163.com",       // 网易
    "https://mirror.baidubce.com"         // 百度
  ]
}
  1. 点击 Apply & Restart。Docker会保存配置并重启。

再次执行拉取命令：
配置重启后，重新打开您的CMD窗口，再次执行：

1
docker pull ultralytics/ultralytics:latest

这次速度应该会有显著提升。如果其中一个镜像源不稳定，请尝试修改为另一个，然后重启Docker再试。

方法二：备用方案——手动构建镜像

如果换源后仍然无法拉取，说明该镜像的所有国内缓存可能都有问题。我们直接自己动手，从一个纯净的Python镜像开始，一步步安装所需环境。这虽然看起来步骤多，但成功率是100%。

  1. 在您的 F:\yolo_world_demo目录下，创建一个新文件，命名为 Dockerfile（没有后缀）。
  2. 用记事本或VS Code打开 Dockerfile，将以下内容复制进去：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 使用一个更小的官方Python镜像作为基础
FROM python:3.9-slim

# 设置工作目录
WORKDIR /workspace

# 关键步骤：更换pip源为清华大学源，以加速后续包下载
RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 安装ultralytics库及其核心依赖（如PyTorch、OpenCV等）
RUN pip install ultralytics

# 设置容器启动时自动进入bash
CMD ["/bin/bash"]
  1. 构建您自己的Docker镜像：
    在CMD中，确保位于 F:\yolo_world_demo目录，然后执行以下命令。注意最后有一个点 .表示当前目录。
1
docker build -t my-yolo-world:latest .

这个过程的意义：它会在本地直接从Python官方镜像开始，使用国内的pip源，一步步安装Ultralytics库。由于是分步下载多个小包，即使中断，再次构建也会继续，而不会全部重来。成功率远高于拉取一个巨大的现成镜像。

  1. 使用您自己构建的镜像启动容器：
    构建成功后，您就拥有了一个名为 my-yolo-world的本地镜像。现在用它来启动容器，命令和之前几乎一样：
1
docker run -it --rm -v F:\yolo_world_demo:/workspace my-yolo-world:latest

方法三：从网盘上下载

将链接中的压缩包下载到本地之后，运行如下代码

1
docker load -i ultralytics-latest.tar

加载完成后，运行 docker images就能看到这个镜像，然后就可以直接使用之前运行的命令来启动容器了：

1
docker run -it --rm -v F:\yolo_world_demo:/workspace my-yolo-world:latest

进入容器后怎么做？

无论您通过第一步还是第二步成功进入了容器（看到 root@xxxx:/workspace#提示符），接下来的步骤都是一样的，而且非常简单：

[图片: 成功进入容器截图]

总结：请优先尝试第一步的换源方案，如果不行，第二步的手动构建方案是100%能走通的，因为它将一个大问题分解成了无数个可以断点续传的小问题。您已经非常接近成功了，祝您好运！

6.2 准备本地目录

在电脑上创建文件夹用来存放代码和图片，例如 F:\yolo_world_demo。

在此文件夹中：

  1. 放入一张测试图片，重命名为 bus.jpg
  2. 创建一个名为 test_yolo_world.py的文件，内容如下：
1
2
3
4
5
6
7
8
9
10
11
from ultralytics import YOLOWorld

# Initialize a YOLO-World model
model = YOLOWorld('yolov8s-world.pt')

# Execute inference with the YOLOv8s-world on the specified image
results = model.predict('bus.jpg')

# Show results
results[0].show()
results[0].save("result.jpg")

6.3 启动容器并挂载目录

在终端中，导航到刚创建的目录，然后运行启动命令：

1
2
3
4
5
6
7
8
# 进入目录
cd F:\yolo_world_demo

# 启动容器，并将当前目录挂载到容器的 /workspace
docker run -it --rm -v ${PWD}:/workspace ultralytics/ultralytics:latest bash

# 进入workspace
cd /workspace

成功后会进入容器内部的 Shell，提示符变为 root@...:/workspace#。

6.4 CPU推理测试

6.4.1 普通检测（预定义类别）

运行脚本：

1
python test_yolo_world.py

执行过程：

  • 代码会自动从 Ultralytics 的服务器下载 yolov8s-world.pt模型文件
  • 下载完成后，模型会对 bus.jpg进行推理
  • 结果会显示在屏幕上，并自动保存到同一目录下，名为 result.jpg

6.4.2 行人检测（自定义类别）

修改脚本：
用编辑器修改本地目录下的 test_yolo_world.py文件，在 model.predict行之前，加入设置自定义类别的代码。内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from ultralytics import YOLOWorld

# Initialize a YOLO-World model
model = YOLOWorld('yolov8s-world.pt')

# Define custom classes - 就是这行新代码！
model.set_classes(["person"])

# Execute inference with the YOLOv8s-world on the specified image
results = model.predict('bus.jpg')

# Show results
results[0].show()
results[0].save("result.jpg")

再次运行脚本：

1
python test_yolo_world.py

执行过程：

  • 模型不会重新下载，而是直接使用之前下载好的权重
  • model.set_classes(["person"])将检测的词汇表设置为只包含 “person”（行人）这一类
  • 模型将只检测图片中的行人，并忽略所有其他物体
  • 结果保存为 result.jpg（覆盖上一次的结果）

7. 配置与使用GPU环境

7.1 在您的主机系统上安装NVIDIA Container Toolkit

这是最关键的基础步骤，目的是让Docker有能力识别并使用您主机上的NVIDIA显卡。

操作如下：

确认基础环境：

  • 确保您的主机系统（Windows或Linux）已安装最新版的NVIDIA显卡驱动程序。
  • 确保Docker引擎已安装并正在运行。

安装NVIDIA Container Toolkit：

对于Linux系统（如Ubuntu），请在终端中依次执行以下命令：

1
2
3
4
5
6
7
# 添加NVIDIA的软件包仓库密钥和源
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 更新软件包列表并安装工具包
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

对于Windows系统：
您需要先安装WSL 2和Linux发行版（如Ubuntu）。然后在WSL 2的Linux环境中，执行上述Linux版的安装命令。

配置Docker运行时：
安装完成后，执行以下命令来配置Docker使用NVIDIA作为默认运行时：

1
2
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

7.2 验证GPU环境

在主机终端（不是在Docker容器里）运行以下命令：

1
nvidia-smi

如果安装成功，您将看到一个显示您GPU型号、驱动版本、CUDA版本及当前运行进程的表格。这个命令能运行成功，是后续所有步骤的基础。

完成这一步，您就为Docker容器使用GPU打下了坚实的基础。接下来，您就可以使用 docker run --gpus all命令来启动支持GPU的容器了。

这是打开GPU加速大门的钥匙，请务必确保这一步成功完成。

7.3 使用支持GPU的Docker命令启动容器

7.3.1 请使用以下新命令来启动容器（别忘了替换您的本地路径）：

1
2
3
4
5
# 1. 进入您的项目目录
cd /workspace

# 2. 替换 `/your/local/path` 为您的实际目录，例如 F:\yolo_world_demo 对应的路径
docker run -it --rm --gpus all -v /your/local/path:/workspace ultralytics/ultralytics:latest bash

核心改动：
加入了 --gpus all参数。这个参数告诉Docker，将主机所有的GPU资源暴露给这个容器使用。

7.3.2 或者使用一个确定存在的、更新的 CUDA 镜像标签。请在你的 WSL Ubuntu 终端中尝试以下命令：

1
2
# 测试命令：使用一个标准且常见的标签
docker run --rm --runtime=nvidia --gpus all nvidia/cuda:12.0.0-base-ubuntu20.04 nvidia-smi

[图片: Docker GPU测试命令执行截图]

以上是正常且积极的进度提示！说明您的 Docker GPU 环境配置正确，并且正在按预期工作。

情况解读

Docker 正常工作的标准流程：

  1. 检测镜像：Docker 首先在您本地电脑的镜像仓库中查找 nvidia/cuda:12.0.0-base-ubuntu20.04这个镜像。
  2. 开始下载：因为本地没有（Unable to find image … locally），所以 Docker 自动连接到官方仓库（Docker Hub）开始下载（Pulling）这个镜像。
  3. 分层下载：Docker 镜像由多个”层”组成，截图中的 5acbbc202509: Download complete等行显示的是这些层的下载进度。有的层已经完成，有的正在下载。这是标准的分层下载过程。

总结：您发出的命令已成功触发 Docker 去获取运行所需的环境，系统正在自动配置，请耐心等待下载完成。

接下来会发生什么

当所有”层”下载完毕后，Docker 会自动：

  1. 创建一个新的容器。
  2. 按照 --gpus all的设定，将您的 GPU 资源分配给这个容器。
  3. 在容器内部执行 nvidia-smi命令。

您将在终端里看到一个熟悉的 GPU 信息表格（和您之前在 WSL 中直接运行 nvidia-smi的结果类似）。

命令执行完毕后，容器会按 --rm参数的要求自动清理退出。

只要最后能显示出 GPU 信息表格，就证明您的 Docker 与 GPU 的集成配置大功告成！

请您耐心等待命令执行完成即可。如果下载速度较慢，属于网络问题，与您的配置无关。

7.4 使用GPU运行您的YOLO-World脚本

首先确认您的本地项目文件位置

请检查您的Windows文件资源管理器，确认YOLO-World项目文件是否在 F:\yolo_world_demo目录中，且包含：

  • test_yolo_world.py脚本文件
  • bus.jpg测试图片

重新启动Docker容器并正确挂载目录

在WSL终端中执行以下命令（请替换为您的实际路径）：

1
docker run -it --rm --gpus all -v /mnt/f/yolo_world_demo:/workspace ultralytics/ultralytics:latest bash

重要说明：在WSL中访问Windows的F盘，需要使用 /mnt/f/路径前缀。

验证目录挂载

进入容器后，立即检查是否成功挂载：

1
ls -la /workspace

应该能看到您的Python脚本和图片文件列表。

执行YOLO-World测试

确认文件存在后，运行您的测试脚本：

1
2
cd /workspace
python test_yolo_world.py

路径映射关系总结

  • Windows路径: F:\yolo_world_demo
  • WSL中对应的路径: /mnt/f/yolo_world_demo
  • Docker容器内路径: /workspace

8. 查看结果

所有操作完成后，在本地电脑的挂载目录中，可以找到以下文件：

  • yolov8s-world.pt：下载的模型权重文件
  • bus.jpg：原始测试图片
  • result.jpg：结果图片，上面画着模型检测出的边界框和标签

打开 result.jpg，即可查看模型的检测结果。

[图片: YOLO-World检测结果示例]

PS：将Ubuntu移动到F盘的操作方法

好的，将 WSL 2 的 Ubuntu 发行版从 C 盘迁移到 F 盘是一个常见且有效的释放系统盘空间的方法。官方提供了非常简单的命令来完成这个操作。

请严格按照以下步骤执行，整个过程非常安全。

迁移步骤

1. 首先，终止所有 WSL 实例

在开始操作前，确保 Ubuntu 或其他 WSL 发行版没有在后台运行。以管理员身份打开 Windows PowerShell 或命令提示符 (CMD)，运行：

1
wsl --shutdown

这条命令会终止所有正在运行的 WSL 发行版。

2. 查看已安装的 WSL 发行版及其存放位置

在 PowerShell/CMD 中运行以下命令，查看你安装的发行版的确切名称：

1
wsl --list -v

输出结果会显示所有发行版及其状态。请记下你的 Ubuntu 发行版的准确名称（例如 Ubuntu、Ubuntu-20.04或 Ubuntu-22.04）。

3. 将目标发行版导出到一个备份文件

注意：此命令会将你的整个系统（包括所有设置、文件、已安装的软件和项目）打包成一个文件。请将 <DistroName>替换为上一步中你记下的名称（例如 Ubuntu-22.04），并指定一个 F 盘上的路径和文件名（如 F:\wsl-ubuntu-backup.tar）。

1
wsl --export <DistroName> F:\wsl-ubuntu-backup.tar

例如：

1
wsl --export Ubuntu-22.04 F:\wsl-ubuntu-backup.tar

这个过程需要一些时间，请耐心等待直到命令完成。

4. 注销（卸载）原来的发行版

警告： 此操作会删除 C 盘上的原始发行版文件。但因为你已经完成了备份，所以数据是安全的。

wsl --unregister