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

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
作者注：本文基于真实踩坑经验，特别针对国内网络环境优化了所有下载步骤

📋 目录

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

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 卸载旧版本（可选）

sudoapt-getremove-ydockerdocker-engine docker.io containerd runc2>/dev/null||true

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

# 安装依赖sudoapt-getupdatesudoapt-getinstall-yca-certificatescurlgnupg# 添加 Docker GPG 密钥（阿里云）curl-fsSLhttps://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg|\sudogpg--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"|\sudotee/etc/apt/sources.list.d/docker.list>/dev/null

2.3 安装 Docker Engine

sudoapt-getupdatesudoapt-getinstall-ydocker-ce docker-ce-cli containerd.io# 验证安装sudodockerversion

2.4 启动 Docker 并设置开机自启

sudosystemctl startdockersudosystemctlenabledockersudosystemctl statusdocker# 看到 "active (running)" 即成功

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

sudogroupadddocker2>/dev/null||truesudousermod-aGdocker$USERnewgrpdocker# 验证（不再需要 sudo）dockerps

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

sudomkdir-p/etc/dockersudotee/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" } } EOFsudosystemctl daemon-reloadsudosystemctl restartdocker

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~wgethttps://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.debsudodpkg-icuda-keyring_1.1-1_all.deb

第二步：更新软件源

sudoapt-getupdate

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

获取: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]

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

sudoapt-getinstall-ynvidia-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：

# 配置 runtimesudonvidia-ctk runtime configure--runtime=docker# 重启 Docker 使配置生效sudosystemctl restartdocker

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

5. 准备工作目录

# 创建工作目录（建议统一放在 workspace_rdkx5 下）mkdir-p~/workspace_rdkx5/rdkx5_dataset/raw_imagesmkdir-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-cftp://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_rdkx5dockerload-idocker_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 验证镜像

dockerimages|grepopenexplorer

预期输出：

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

7. 启动 GPU 量化容器

7.1 设置环境变量

exportat_toolchain_package_path=~/workspace_rdkx5/horizon_x5_open_explorer_v1.2.8-py310_20240926exportdataset_path=~/workspace_rdkx5/rdkx5_datasetexportmodels_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 EOFsource~/.bashrc

7.2 启动容器

dockerrun-it--rm\--gpusall\--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 验证 CUDApython3-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--versionpip 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 正要被安装

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

sudoapt-getinstall-ynvidia-container-toolkit

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

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

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

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

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

解决：

# 退出容器，在宿主机执行sudosystemctl restartdocker# 重新启动容器

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

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

解决：升级 Docker，或改用：

dockerrun-it--rm\--runtime=nvidia\-eNVIDIA_VISIBLE_DEVICES=all\...

附录：快速启动脚本

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

#!/bin/bash# 保存为 ~/start_rdkx5.sh# 运行: bash ~/start_rdkx5.shexportat_toolchain_package_path=~/workspace_rdkx5/horizon_x5_open_explorer_v1.2.8-py310_20240926exportdataset_path=~/workspace_rdkx5/rdkx5_datasetexportmodels_path=~/workspace_rdkx5/rdkx5_modelsdockerrun-it--rm\--gpusall\--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