RDK X5 量化工具链环境搭建完整指南（Ubuntu 22.04 LTS + GPU版——RTX5080）

适用场景：物理机 Ubuntu 22.04 LTS + NVIDIA 5080独立显卡，用于地平线 RDK X5 模型量化部署
工具链版本：OpenExplorer v1.2.8-py310
验证环境：Ubuntu 22.04 LTS + NVIDIA GeForce RTX 5080 + Driver 595.58 + CUDA 13.2
作者注：本文基于真实踩坑经验，特别针对国内网络环境优化了所有下载步骤

---

📋 目录

1. 前置条件确认
2. 安装 Docker
3. 安装 NVIDIA Container Toolkit（重点/踩坑）
4. 配置 Docker 使用 NVIDIA Runtime
5. 准备工作目录
6. 下载并导入 OE 工具链镜像
7. 启动 GPU 量化容器
8. 验证环境
9. 常见问题排查

---

1. 前置条件确认

1.1 硬件要求

组件	最低要求	推荐
CPU	4核	8核+
内存	16GB	32GB+
硬盘	100GB 可用空间	200GB+ SSD
显卡	NVIDIA GTX 1060+	RTX 系列

1.2 系统要求

• 操作系统：Ubuntu 22.04 LTS（物理机，非虚拟机）
• NVIDIA 驱动：已安装（520+ 版本推荐，RTX 40/50 系需要 550+）
• 网络：国内网络（本文所有步骤均针对国内环境优化）

1.3 确认驱动状态

在开始之前，先确认 NVIDIA 驱动已正确安装：

nvidia-smi

预期输出示例：

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 595.58.03    Driver Version: 595.58.03    CUDA Version: 13.2    |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
|   0  NVIDIA GeForce RTX 5080  Off | 00000000:01:00.0 On |              N/A |
+-----------------------------------------------------------------------------+

如果此命令报错，请先安装 NVIDIA 驱动再继续后续步骤。

---

2. 安装 Docker

如果已安装 Docker，可跳过此章节，直接到第3章。

2.1 卸载旧版本（可选）

sudo apt-get remove -y docker docker-engine docker.io containerd runc 2>/dev/null || true

2.2 添加 Docker 源（使用阿里云镜像，国内友好）

# 安装依赖
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# 添加 Docker GPG 密钥（阿里云）
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加 Docker APT 源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
  https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

2.3 安装 Docker Engine

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 验证安装
sudo docker version

2.4 启动 Docker 并设置开机自启

sudo systemctl start docker
sudo systemctl enable docker
sudo systemctl status docker
# 看到 "active (running)" 即成功

2.5 将当前用户加入 docker 组（免 sudo）

sudo groupadd docker 2>/dev/null || true
sudo usermod -aG docker $USER
newgrp docker

# 验证（不再需要 sudo）
docker ps

2.6 配置 Docker 镜像加速（国内加速）

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json << EOF
{
    "registry-mirrors": [
        "https://docker.m.daocloud.io",
        "https://mirror.baidubce.com",
        "https://docker.nju.edu.cn",
        "https://hub-mirror.c.163.com"
    ],
    "log-driver": "json-file",
    "log-opts": {
        "max-size": "100m",
        "max-file": "3"
    }
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

---

3. 安装 NVIDIA Container Toolkit（重点/踩坑）

⚠️ 这是本文最关键的章节，也是国内环境最容易卡住的步骤。

3.1 为什么需要 NVIDIA Container Toolkit？

Docker 容器默认无法访问宿主机的 GPU。NVIDIA Container Toolkit 提供了一套运行时钩子，让容器可以透传访问 NVIDIA GPU。

如果缺少此组件，运行 --gpus all 时会报错：

docker: Error response from daemon: failed to discover GPU vendor from CDI: no known GPU vendor found

3.2 国内安装的问题

官方安装方式需要访问 nvidia.github.io，该地址在国内无法访问，导致：

• 直接添加官方源 → SSL 连接失败
• 清华镜像 mirrors.tuna.tsinghua.edu.cn/libnvidia-container → 404 Not Found
• GitHub Releases 直接下载 .deb → 404 Not Found（文件命名不匹配）

3.3 ✅ 正确方案：使用 NVIDIA CUDA 官方 CDN（国内可访问）

developer.download.nvidia.com 是 NVIDIA 的官方 CUDA 下载 CDN，国内可以正常访问，其软件源中包含了 nvidia-container-toolkit。

第一步：添加 CUDA Keyring

cd ~
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb

第二步：更新软件源

sudo apt-get update

更新时你会看到类似输出，说明源已生效：

获取:9 https://developer.download.nvidia.cn/compute/cuda/repos/ubuntu2204/x86_64 InRelease [1,581 B]
获取:10 https://developer.download.nvidia.cn/compute/cuda/repos/ubuntu2204/x86_64 Packages [2,533 kB]

第三步：安装（不要指定版本号，避免依赖冲突）

sudo apt-get install -y nvidia-container-toolkit

⚠️ 常见错误：如果你指定了版本号（如 nvidia-container-toolkit=1.13.5-1），会出现依赖冲突报错：

nvidia-container-toolkit : 依赖: nvidia-container-toolkit-base (= 1.13.5-1) 但是 1.19.0-1 正要被安装

解决方法：去掉版本号，直接 sudo apt-get install -y nvidia-container-toolkit 即可。

---

4. 配置 Docker 使用 NVIDIA Runtime

安装完 Toolkit 后，需要配置 Docker daemon 使用 NVIDIA runtime：

# 配置 runtime
sudo nvidia-ctk runtime configure --runtime=docker

# 重启 Docker 使配置生效
sudo systemctl restart docker

成功后 /etc/docker/daemon.json 会被自动更新，加入 NVIDIA runtime 配置。

---

5. 准备工作目录

# 创建工作目录（建议统一放在 workspace_rdkx5 下）
mkdir -p ~/workspace_rdkx5/rdkx5_dataset/raw_images
mkdir -p ~/workspace_rdkx5/rdkx5_models

# 查看结构
ls ~/workspace_rdkx5/

目录规划说明：

~/workspace_rdkx5/
├── horizon_x5_open_explorer_v1.2.8-py310_20240926/   # OE工具链（解压后）
├── rdkx5_dataset/                                      # 数据集
│   └── raw_images/                                     # 校准用原始图片
└── rdkx5_models/                                       # 模型文件(.pt/.onnx/.bin)

---

6. 下载并导入 OE 工具链镜像

6.1 下载工具链包（FTP方式）

地平线官方提供 FTP 下载，国内速度较快：

cd ~/workspace_rdkx5

# 下载 GPU 版（约10GB，需耐心等待）
wget -c ftp://x5ftp@vrftp.horizon.ai/OpenExplorer/v1.2.8_release/docker_openexplorer_ubuntu_20_x5_gpu_v1.2.8.tar.gz \
  --ftp-password='x5ftp@123$%'

下载参数说明：

• -c：支持断点续传，中断后重新运行同样命令会从断点继续
• 文件约 10GB，校园网/百兆以上带宽约需 2-5 分钟

GPU 版 vs CPU 版选择：

版本	文件名	适用场景
GPU 版	docker_openexplorer_ubuntu_20_x5_gpu_v1.2.8.tar.gz	有 NVIDIA 独立显卡，量化速度更快
CPU 版	docker_openexplorer_ubuntu_20_x5_cpu_v1.2.8.tar.gz	无 GPU 或虚拟机环境

6.2 导入 Docker 镜像

cd ~/workspace_rdkx5

docker load -i docker_openexplorer_ubuntu_20_x5_gpu_v1.2.8.tar.gz

⚠️ 注意：导入过程约需 5-15 分钟，进度条可能长时间停在某处，这是正常现象，不要按 Ctrl+C 中断。

成功标志：

Loaded image: openexplorer/ai_toolchain_ubuntu_20_x5_gpu:v1.2.8-py310

6.3 验证镜像

docker images | grep openexplorer

预期输出：

openexplorer/ai_toolchain_ubuntu_20_x5_gpu   v1.2.8-py310   9833bd0d6e4a   44.4GB   22GB

---

7. 启动 GPU 量化容器

7.1 设置环境变量

export at_toolchain_package_path=~/workspace_rdkx5/horizon_x5_open_explorer_v1.2.8-py310_20240926
export dataset_path=~/workspace_rdkx5/rdkx5_dataset
export models_path=~/workspace_rdkx5/rdkx5_models

持久化（避免每次终端都要重新设置）：

cat >> ~/.bashrc << 'EOF'

# RDK X5 量化环境变量
export at_toolchain_package_path=~/workspace_rdkx5/horizon_x5_open_explorer_v1.2.8-py310_20240926
export dataset_path=~/workspace_rdkx5/rdkx5_dataset
export models_path=~/workspace_rdkx5/rdkx5_models
EOF

source ~/.bashrc

7.2 启动容器

docker run -it --rm \
  --gpus all \
  --shm-size=15g \
  -v "$at_toolchain_package_path":/open_explorer \
  -v "$dataset_path":/data \
  -v "$models_path":/models \
  openexplorer/ai_toolchain_ubuntu_20_x5_gpu:v1.2.8-py310

参数说明：

参数	说明
-it	交互式终端
--rm	退出时自动删除容器（数据保留在宿主机挂载目录）
--gpus all	透传所有 GPU 到容器
--shm-size=15g	共享内存 15GB，防止大模型量化时 OOM
-v 宿主路径:容器路径	目录挂载，数据持久化

成功进入容器的标志：

root@535fccc60b01:/open_explorer#

---

8. 验证环境

进入容器后，依次运行以下验证命令：

8.1 验证量化工具

hb_mapper --version

预期输出：

hb_mapper, version 1.24.3

8.2 验证 GPU 可用性

# 方法1：直接查看 GPU 信息
nvidia-smi

# 方法2：用 PyTorch 验证 CUDA
python3 -c "import torch; print('CUDA可用:', torch.cuda.is_available()); print('GPU型号:', torch.cuda.get_device_name(0))"

预期输出：

CUDA可用: True
GPU型号: NVIDIA GeForce RTX 5080

8.3 验证 Python 环境

python3 --version
pip list | grep -E "onnx|torch|numpy"

至此，GPU 量化环境搭建完成 ✅

---

9. 常见问题排查

❌ 问题1：failed to discover GPU vendor from CDI: no known GPU vendor found

原因：nvidia-container-toolkit 未安装或未配置。

解决：完整执行第3章和第4章的步骤。

---

❌ 问题2：nvidia.github.io SSL 连接失败 / 清华源 404

原因：官方源和清华镜像均不可用（国内网络限制）。

解决：使用本文第3章的 developer.download.nvidia.com 方案。

---

❌ 问题3：指定版本号安装时依赖冲突

错误信息：

nvidia-container-toolkit : 依赖: nvidia-container-toolkit-base (= 1.13.5-1) 但是 1.19.0-1 正要被安装

解决：不指定版本号，直接运行：

sudo apt-get install -y nvidia-container-toolkit

---

❌ 问题4：docker load 导入镜像时长时间无进度

原因：正常现象，镜像解压是 CPU 密集型操作。

判断是否卡死：新开终端运行 htop，查看是否有 dockerd 进程在占用 CPU。有占用说明正常工作，耐心等待即可。

---

❌ 问题5：容器内 nvidia-smi 报错

可能原因：Docker daemon 配置未重启生效。

解决：

# 退出容器，在宿主机执行
sudo systemctl restart docker
# 重新启动容器

---

❌ 问题6：--gpus all 与旧版 Docker 不兼容

原因：旧版 Docker（< 19.03）不支持 --gpus 参数。

解决：升级 Docker，或改用：

docker run -it --rm \
  --runtime=nvidia \
  -e NVIDIA_VISIBLE_DEVICES=all \
  ...

---

附录：快速启动脚本

每次需要进入量化环境时，运行以下脚本：

#!/bin/bash
# 保存为 ~/start_rdkx5.sh
# 运行: bash ~/start_rdkx5.sh

export at_toolchain_package_path=~/workspace_rdkx5/horizon_x5_open_explorer_v1.2.8-py310_20240926
export dataset_path=~/workspace_rdkx5/rdkx5_dataset
export models_path=~/workspace_rdkx5/rdkx5_models

docker run -it --rm \
  --gpus all \
  --shm-size=15g \
  -v "$at_toolchain_package_path":/open_explorer \
  -v "$dataset_path":/data \
  -v "$models_path":/models \
  openexplorer/ai_toolchain_ubuntu_20_x5_gpu:v1.2.8-py310

保存并赋予执行权限：

chmod +x ~/start_rdkx5.sh

以后每次只需运行 bash ~/start_rdkx5.sh 即可一键进入量化环境。

---

文档版本：v1.0 | 最后更新：2026-04-19 | 基于 OpenExplorer v1.2.8-py310