技术教程

Vulkan 环境配置指南 ​

本文档介绍如何在开发机上配置和验证 Vulkan 环境。

配置步骤 ​

1. 检查 NVIDIA 库文件是否存在 ​

bash
ls -l /lib/x86_64-linux-gnu/libEGL_nvidia.so.0

预期输出示例：

lrwxrwxrwx 1 root root 26 Jan 25 12:00 /lib/x86_64-linux-gnu/libEGL_nvidia.so.0 -> libEGL_nvidia.so.<驱动版本>

注意：libEGL_nvidia.so.0 通常是一个符号链接，指向实际的驱动版本文件（如 libEGL_nvidia.so.535.161.08 或 libEGL_nvidia.so.580.76.05）

如果文件不存在，请检查 NVIDIA 驱动是否正确安装：

bash
nvidia-smi

如果驱动存在，但是没有文件，请联系客服处理

2. 安装 Vulkan 工具和依赖库 ​

bash
apt update && apt install -y vulkan-tools libvulkan1 libsm6 libegl1

包说明：

  • vulkan-tools - Vulkan 命令行工具（包括 vulkaninfo）
  • libvulkan1 - Vulkan 加载器库
  • libsm6 - X11 会话管理库
  • libegl1 - EGL 运行时库

3. 创建 Vulkan ICD 配置文件 ​

检查配置文件是否已存在：

bash
cat /etc/vulkan/icd.d/nvidia_icd.json

如果文件不存在，创建配置文件：

bash
mkdir -p /etc/vulkan/icd.d

cat > /etc/vulkan/icd.d/test_nvidia_icd.json <<'EOF'
{
    "file_format_version" : "1.0.0",
    "ICD": {
        "library_path": "/lib/x86_64-linux-gnu/libEGL_nvidia.so.0",
        "api_version" : "1.3.0"
    }
}
EOF

4. 验证 Vulkan 配置 ​

bash
vulkaninfo --summary | grep -E "deviceName|deviceType|driverName"

预期输出（成功）：

        deviceType         = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
        deviceName         = NVIDIA GeForce RTX 4090
        driverName         = NVIDIA

5. 清理自定义配置文件（验证成功后） ​

验证成功后，系统会自动创建 /etc/vulkan/icd.d/nvidia_icd.json 配置文件。此时需要删除之前手动创建的自定义配置文件：

bash
# 确认自动生成的配置文件已存在
ls -l /etc/vulkan/icd.d/nvidia_icd.json

# 删除临时的自定义配置文件
rm /etc/vulkan/icd.d/test_nvidia_icd.json

说明：test_nvidia_icd.json 仅用于初始测试和触发系统自动创建正式的配置文件。验证成功后应删除，避免配置冲突。

故障排查 ​

找不到 libEGL_nvidia.so.0 ​

查找实际的 NVIDIA 库文件：

bash
find /usr/lib /lib -name 'libEGL_nvidia.so*' 2>/dev/null

使用找到的实际文件路径更新 ICD 配置文件中的 library_path。

vulkaninfo 只显示 llvmpipe (CPU 渲染) ​

检查驱动和配置：

bash
# 检查驱动状态
nvidia-smi

# 检查 ICD 配置
cat /etc/vulkan/icd.d/nvidia_icd.json

# 检查库文件
ls -la /lib/x86_64-linux-gnu/libEGL_nvidia.so.0

显示警告 "DISPLAY environment variable not set" ​

这是正常现象，不影响 Vulkan 功能。可选择性消除：

bash
export DISPLAY=:0
export XDG_RUNTIME_DIR=/tmp