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

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 硬件要求组件最低要求推荐CPU4核8核内存16GB32GB硬盘100GB 可用空间200GB SSD显卡NVIDIA GTX 1060RTX 系列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||true2.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 源echodeb [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/null2.3 安装 Docker Enginesudoapt-getupdatesudoapt-getinstall-ydocker-ce docker-ce-cli containerd.io# 验证安装sudodockerversion2.4 启动 Docker 并设置开机自启sudosystemctl startdockersudosystemctlenabledockersudosystemctl statusdocker# 看到 active (running) 即成功2.5 将当前用户加入 docker 组免 sudosudogroupadddocker2/dev/null||truesudousermod-aGdocker$USERnewgrpdocker# 验证不再需要 sudodockerps2.6 配置 Docker 镜像加速国内加速sudomkdir-p/etc/dockersudotee/etc/docker/daemon.jsonEOF { 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 restartdocker3. 安装 NVIDIA Container Toolkit重点/踩坑⚠️这是本文最关键的章节也是国内环境最容易卡住的步骤。3.1 为什么需要 NVIDIA Container ToolkitDocker 容器默认无法访问宿主机的 GPU。NVIDIA Container Toolkit 提供了一套运行时钩子让容器可以透传访问 NVIDIA GPU。如果缺少此组件运行--gpus all时会报错docker: Error response from daemon: failed to discover GPU vendor from CDI: no known GPU vendor found3.2 国内安装的问题官方安装方式需要访问nvidia.github.io该地址在国内无法访问导致直接添加官方源 → SSL 连接失败清华镜像mirrors.tuna.tsinghua.edu.cn/libnvidia-container→ 404 Not FoundGitHub Releases 直接下载.deb→ 404 Not Found文件命名不匹配3.3 ✅ 正确方案使用 NVIDIA CUDA 官方 CDN国内可访问developer.download.nvidia.com是 NVIDIA 的官方 CUDA 下载 CDN国内可以正常访问其软件源中包含了 nvidia-container-toolkit。第一步添加 CUDA Keyringcd~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-toolkit1.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--runtimedocker# 重启 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://x5ftpvrftp.horizon.ai/OpenExplorer/v1.2.8_release/docker_openexplorer_ubuntu_20_x5_gpu_v1.2.8.tar.gz\--ftp-passwordx5ftp123$%下载参数说明-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 分钟进度条可能长时间停在某处这是正常现象不要按 CtrlC 中断。成功标志Loaded image: openexplorer/ai_toolchain_ubuntu_20_x5_gpu:v1.2.8-py3106.3 验证镜像dockerimages|grepopenexplorer预期输出openexplorer/ai_toolchain_ubuntu_20_x5_gpu v1.2.8-py310 9833bd0d6e4a 44.4GB 22GB7. 启动 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~/.bashrcEOF # 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~/.bashrc7.2 启动容器dockerrun-it--rm\--gpusall\--shm-size15g\-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-size15g共享内存 15GB防止大模型量化时 OOM-v 宿主路径:容器路径目录挂载数据持久化成功进入容器的标志root535fccc60b01:/open_explorer#8. 验证环境进入容器后依次运行以下验证命令8.1 验证量化工具hb_mapper--version预期输出hb_mapper, version 1.24.38.2 验证 GPU 可用性# 方法1直接查看 GPU 信息nvidia-smi# 方法2用 PyTorch 验证 CUDApython3-cimport torch; print(CUDA可用:, torch.cuda.is_available()); print(GPU型号:, torch.cuda.get_device_name(0))预期输出CUDA可用: True GPU型号: NVIDIA GeForce RTX 50808.3 验证 Python 环境python3--versionpip list|grep-Eonnx|torch|numpy至此GPU 量化环境搭建完成 ✅9. 常见问题排查❌ 问题1failed to discover GPU vendor from CDI: no known GPU vendor found原因nvidia-container-toolkit 未安装或未配置。解决完整执行第3章和第4章的步骤。❌ 问题2nvidia.github.ioSSL 连接失败 / 清华源 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❌ 问题4docker load 导入镜像时长时间无进度原因正常现象镜像解压是 CPU 密集型操作。判断是否卡死新开终端运行htop查看是否有dockerd进程在占用 CPU。有占用说明正常工作耐心等待即可。❌ 问题5容器内 nvidia-smi 报错可能原因Docker daemon 配置未重启生效。解决# 退出容器在宿主机执行sudosystemctl restartdocker# 重新启动容器❌ 问题6--gpus all与旧版 Docker 不兼容原因旧版 Docker 19.03不支持--gpus参数。解决升级 Docker或改用dockerrun-it--rm\--runtimenvidia\-eNVIDIA_VISIBLE_DEVICESall\...附录快速启动脚本每次需要进入量化环境时运行以下脚本#!/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-size15g\-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保存并赋予执行权限chmodx ~/start_rdkx5.sh以后每次只需运行bash ~/start_rdkx5.sh即可一键进入量化环境。文档版本v1.0 | 最后更新2026-04-19 | 基于 OpenExplorer v1.2.8-py310