非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

NVIDIA GPU硬件加速教程

本教程指导您如何通过NVENC在NVIDIA GPU上设置完整的视频硬件加速功能。

加速方法

自Maxwell架构起，NVIDIA GPU开始支持硬件加速转码。

在Windows和Linux系统中，NVENC是唯一可用的加速方法。

NVENC/NVDEC是NVIDIA GPU的专有视频编解码API，配合CUDA使用可实现完整的硬件加速。

已知问题和限制请参阅此章节。

备注

NVENC在Windows和Linux上均支持无显示器运行(headless server)，这意味着无需连接物理显示器。

色调映射方法

支持HEVC 10-bit解码的所有NVIDIA GPU均可实现HDR/DV到SDR的硬件加速色调映射。

在Windows和Linux系统中，CUDA是唯一可用的色调映射方法。该方法同时支持杜比视界P5格式和零拷贝技术。

备注

Enable enhanced NVDEC decoder功能可在新版NVDEC和旧版CUVID解码流程之间切换。启用杜比视界支持需勾选此选项以激活NVDEC。

选择GPU硬件

初学者请参考硬件选择指南获取选购建议，高级用户请继续阅读本节内容。

注意

大多数NVIDIA GPU都支持NVENC/NVDEC，但部分低端和移动型号（如GT1030和MX450）属于例外情况。

购买适用于硬件加速的GPU前，可通过NVIDIA GPU编解码支持矩阵查询视频编解码支持情况。

转码H.264

AVC/H.264 8-bit因其出色的兼容性仍被广泛使用。所有支持NVENC/NVDEC的NVIDIA GPU均可对其进行解码/编码。

H.264 8-bit解码与编码 - 任何支持NVENC/NVDEC的NVIDIA GPU

转码HEVC

HEVC/H.265 仍然是存储4K 10-bit、HDR和杜比视界视频的首选格式。得益于x265成熟的软件编码支持，以及2016年后发布的大多数GPU广泛实现的硬件编码支持。

Maxwell及以上架构GPU提供HEVC支持：

HEVC 8-bit解码与编码 - Maxwell第二代(GM206)及更新架构
HEVC 10-bit解码 - Maxwell第二代(GM206)及更新架构
HEVC 10-bit编码 - Pascal及更新架构

备注

请注意，在Maxwell第二代系列中，仅GM206型号支持HEVC 10-bit解码。其继任者Pascal架构则完全支持HEVC 10-bit，并提升了速度与画质。

AV1转码支持

AV1是免版税的未来视频编解码器。其更小的文件尺寸能显著节省存储空间和网络带宽，但缺点是编解码对CPU要求极高。硬件加速使得实时转码AV1流成为可能。AV1编码功能在Jellyfin 10.9及以上版本提供支持。

NVIDIA已在其最新GPU中添加AV1加速支持：

解码 AV1 8/10-bit - Ampere 及更新架构
编码 AV1 8/10-bit - Ada Lovelace 及更新架构

其他编解码器支持

请参考以下资源：

速度与画质表现

编码质量：

H.264 和 HEVC - Blackwell/Ada/Ampere/Turing > Turing TU117/Volta/Pascal > Maxwell
AV1 - 仅限 Ada Lovelace 和 Blackwell

同代架构的解码与编码速度：

多 NVENC/NVDEC 单元型号 > 单 NVENC/NVDEC 单元型号
高 GPU 时钟频率型号 > 低 GPU 时钟频率型号
高显存带宽型号 > 低显存带宽型号

NVENC/NVDEC 性能参考表：

Windows环境配置

推荐使用Windows 10 64位或更高版本。Jellyfin 10.10要求最低NVIDIA驱动版本为522.25。

Windows主机配置步骤

若从 Maxwell 前代 NVIDIA GPU 升级且未执行全新安装，请使用 DDU 彻底清除旧驱动。
从 NVIDIA 驱动下载页面安装最新版驱动。
在 Jellyfin 中启用 NVENC 并取消勾选不支持的编解码器。

Windows 虚拟化配置

NVIDIA Windows 驱动支持在 WSL2 和 Docker 环境中访问 NVENC/NVDEC 及 CUDA。

请参考 Linux 物理机配置和 Linux 虚拟化配置。

Windows 环境验证

在 Jellyfin Web 客户端播放视频，通过降低分辨率或码率触发视频转码。
打开"任务管理器"并切换到 GPU 页面。
按以下方式检查各引擎占用情况：
- 3D - 2D/3D引擎或CUDA/GPGPU工作负载
- Copy - 位块传输/复制引擎工作负载
- Video Decode - 视频解码器工作负载
- Video Encode - 视频编码器工作负载
- Cuda - CUDA/GPGPU工作负载

Linux 环境配置

需要 64 位 Linux 发行版。Jellyfin 10.10 最低要求 NVIDIA 驱动版本为 520.56.06。

Linux 主机配置指南

Debian/Ubuntu 系统

Jellyfin 所需的 jellyfin-ffmpeg* deb 包不包含任何 NVIDIA 专有驱动。

您需要从发行版安装 NVIDIA 驱动程序并配置 jellyfin 用户的权限。

备注

需要 root 权限。

假设您已添加 Jellyfin 仓库至 apt 源列表，并安装了 jellyfin-server 和 jellyfin-web。
安装 jellyfin-ffmpeg7 软件包。若存在冲突依赖可移除废弃的 jellyfin 元包：
```
sudo apt update && sudo apt install -y jellyfin-ffmpeg7
```
通过以下链接安装NVIDIA专有驱动，然后安装两个额外软件包以支持NVENC和NVDEC：
- Debian系统：https://wiki.debian.org/NvidiaGraphicsDrivers
```
sudo apt update && sudo apt install -y libnvcuvid1 libnvidia-encode1
```
- Ubuntu系统：https://ubuntu.com/server/docs/nvidia-drivers-installation
  
  备注
  可能需要将驱动版本作为软件包名称的后缀。
```
sudo apt update && sudo apt install -y libnvidia-decode libnvidia-encode
```

使用 nvidia-smi 检查 NVIDIA GPU 状态：

$ nvidia-smi

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 520.56.06    Driver Version: 520.56.06    CUDA Version: 11.8     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  Off  | 00000000:1C:00.0 Off |                  N/A |
|  0%   44C    P0    N/A /  75W |      0MiB /  1998MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
...

在 Jellyfin 中启用 NVENC 并取消勾选不支持的编解码器。

Linux Mint

Linux Mint 基于 Ubuntu 的软件包体系构建

您可以遵循 Debian 和 Ubuntu Linux 的配置步骤，但需从 Jellyfin 服务器发布页面手动安装所有软件包：jellyfin-server, jellyfin-web 和 jellyfin-ffmpeg7。同时请根据官方版本映射表选择正确的代号。

Arch Linux

备注

需要 root 权限。

安装 Archlinux/extra 仓库的 jellyfin-ffmpeg 包：
```
sudo pacman -Syu jellyfin-ffmpeg
```
通过以下链接安装NVIDIA专有驱动，然后安装额外软件包以支持NVENC和NVDEC：
- https://wiki.archlinux.org/title/NVIDIA#Installation
```
sudo pacman -Syu nvidia-utils
```
使用 nvidia-smi 检查 NVIDIA GPU 状态：
```
nvidia-smi
```
在 Jellyfin 中启用 NVENC 并取消勾选不支持的编解码器。

其他发行版

对于缺乏常规维护的发行版，我们提供便携式 jellyfin-ffmpeg 二进制文件。

可通过以下链接下载：

备注

glibc 和 Linux 内核最低要求：

x86_64 / amd64 架构 - glibc >= 2.28, Linux 内核 >= 4.18 (2018 年及之后发布的主流发行版)

解压后安装到正确路径，并在 Jellyfin 控制台修改 FFmpeg 路径使其匹配：

备注

需要 root 权限。

cd ~/
mkdir -p jellyfin-ffmpeg
wget https://repo.jellyfin.org/releases/ffmpeg/<VERSION>/jellyfin-ffmpeg_<VERSION>_portable_linux64-gpl.tar.xz
tar -xvf jellyfin-ffmpeg_<VERSION>_portable_linux64-gpl.tar.xz -C jellyfin-ffmpeg
sudo mv jellyfin-ffmpeg /usr/lib
sudo ldd -v /usr/lib/jellyfin-ffmpeg/ffmpeg

安装包含以下关键字的 NVIDIA 专有驱动包及其依赖项：

NVIDIA NVDEC CUVID - 解码
NVIDIA NVENC - 编码

Linux 虚拟化环境配置

官方 Docker 镜像

官方 Docker 镜像未包含任何 NVIDIA 专有驱动。

需在宿主机系统安装 NVIDIA 驱动和 NVIDIA Container Toolkit，使 Docker 能访问 GPU。

备注

需要 root 权限。

在宿主机安装 NVIDIA 专有驱动（参考前文说明）
通过以下链接在宿主机上安装NVIDIA Container Toolkit：
- https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#installation-guide

使用Docker命令行或docker-compose：

命令行示例：

docker run -d \
 --name=jellyfin \
 --volume /path/to/config:/config \
 --volume /path/to/cache:/cache \
 --volume /path/to/media:/media \
 --user 1000:1000 \
 --net=host \
 --restart=unless-stopped \
 --runtime=nvidia \
 --gpus all \
 jellyfin/jellyfin

docker-compose配置文件示例（YAML格式）：

services:
  jellyfin:
    image: jellyfin/jellyfin
    user: 1000:1000
    network_mode: 'host'
    volumes:
      - /path/to/config:/config
      - /path/to/cache:/cache
      - /path/to/media:/media
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

备注

若遇到上游问题CUDA_ERROR_NO_DEVICE: no CUDA-capable device is detected，请将这些设备映射到Docker容器：

/dev/nvidia-caps:/dev/nvidia-caps
/dev/nvidia0:/dev/nvidia0
/dev/nvidiactl:/dev/nvidiactl
/dev/nvidia-modeset:/dev/nvidia-modeset
/dev/nvidia-uvm:/dev/nvidia-uvm
/dev/nvidia-uvm-tools:/dev/nvidia-uvm-tools

将用户名加入 video 用户组：
```
sudo usermod -aG video $USER
```

更新动态链接并重启 Docker 服务：

docker exec -it jellyfin ldconfig
sudo systemctl restart docker

使用 nvidia-smi 检查 NVIDIA GPU 状态：
```
docker exec -it jellyfin nvidia-smi
```
如需尝试不稳定版本，请自行承担风险将 jellyfin/jellyfin 替换为 jellyfin/jellyfin:unstable。
在 Jellyfin 中启用 NVENC 并取消勾选不支持的编解码器。

备注

请注意，官方 Jellyfin Docker 镜像已为 NVIDIA GPU 设置所需环境变量。若需自行构建镜像，请勿忘记在 Docker 配置中添加以下两个环境变量：

NVIDIA_DRIVER_CAPABILITIES=all
NVIDIA_VISIBLE_DEVICES=all

Linuxserver.io Docker 方案

LSIO Docker 镜像由 linuxserver.io 维护，请参考其 GitHub 文档：linuxserver/docker-jellyfin。

备注

官方 Docker 镜像与 LSIO Docker 镜像中 Jellyfin 配置文件和数据的存储路径不同，因此无法直接互换使用。

Podman

将CUDA软件仓库添加到包管理器。

浏览以下目录获取适用于您发行版的仓库文件：CUDA软件仓库

将对应的仓库文件安装至包管理器。具体操作方式取决于您的包管理器及操作系统版本。请将下方示例中的仓库URL替换为适配您发行版的正确地址。

a. Fedora/RHEL/CentOS系统：

sudo dnf config-manager addrepo --from-repofile=https://developer.download.nvidia.com/compute/cuda/repos/fedora42/$(uname -m)/cuda-fedora42.repo

b. Debian/Ubuntu系统：

echo "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin stable main" | sudo tee /etc/apt/sources.list.d/cuda-ubuntu2404.list

sudo apt-get update
安装软件包 cuda-toolkit 和 nvidia-container-toolkit-base

a. Fedora, RHEL, CentOS:

sudo dnf install cuda-toolkit nvidia-container-toolkit-base

b. Debian, Ubuntu:

sudo apt-get install -y cuda-toolkit nvidia-container-toolkit-base
生成 CDI 规范文件

sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

另请参阅：容器设备接口支持 — NVIDIA Container Toolkit

调整您的podman命令行或systemd容器文件以使用设备：nvidia.com/gpu=0

例如，您的podman命令行应调整为如下格式：

podman run \
 --detach \
 --label "io.containers.autoupdate=registry" \
 --name myjellyfin \
 --publish 8096:8096/tcp \
 --device nvidia.com/gpu=0 \
 # --security-opt label=disable # Only needed for older versions of container-selinux < 2.226
 --rm \
 --user $(id -u):$(id -g) \
 --userns keep-id \
 --environment=JELLYFIN_DATA_DIR=/var/lib/jellyfin
 --environment=JELLYFIN_CONFIG_DIR=/etc/jellyfin
 --environment=JELLYFIN_LOG_DIR=/var/log/jellyfin
 --environment=JELLYFIN_CACHE_DIR=/var/cache/jellyfin
 --volume=/your/path/to/data:/var/lib/jellyfin      # Replace paths with actual paths on your host's filesystem
 --volume=/your/path/to/config:/etc/jellyfin
 --volume=/your/path/to/logs:/var/log/jellyfin
 --volume=/your/path/to/cache:/var/cache/jellyfin
 --mount type=bind,source=/path/to/media,destination=/media,ro=true,relabel=private \
 docker.io/jellyfin/jellyfin:latest

Systemd配置文件示例：

[Unit]
Description=jellyfin

[Container]
Image=docker.io/jellyfin/jellyfin:latest
AutoUpdate=registry
PublishPort=8096:8096/tcp
UserNS=keep-id
#SecurityLabelDisable=true # Only needed for older versions of container-selinux < 2.226
AddDevice=nvidia.com/gpu=0
Environment=JELLYFIN_DATA_DIR=/var/lib/jellyfin
Environment=JELLYFIN_CONFIG_DIR=/etc/jellyfin
Environment=JELLYFIN_LOG_DIR=/var/log/jellyfin
Environment=JELLYFIN_CACHE_DIR=/var/cache/jellyfin
Volume=/your/path/to/data:/var/lib/jellyfin      # Replace paths with actual paths on your host's filesystem
Volume=/your/path/to/config:/etc/jellyfin
Volume=/your/path/to/logs:/var/log/jellyfin
Volume=/your/path/to/cache:/var/cache/jellyfin

[Service]
# Inform systemd of additional exit status
SuccessExitStatus=0 143

[Install]
# Start by default on boot
WantedBy=default.target

创建以下 udev 规则，确保在容器启动前初始化 GPU 设备

将以下内容保存为 /etc/udev/rules.d/nvidia.rules：

ACTION=="add|bind", ATTR{vendor}=="0x10de", ATTR{class}=="0x03[0-9]*", \
    DRIVER=="nvidia", TEST!="/dev/nvidia-uvm", \
    RUN+="/usr/bin/nvidia-modprobe", \
    RUN+="/usr/bin/nvidia-modprobe -c0 -u", \
    RUN+="/usr/bin/nvidia-modprobe -m"

其他虚拟化方案

其他虚拟化方案未经验证，可能无法在 NVIDIA GPU 上运行

更多信息请参考 Intel GPU 硬件加速教程 - Linux 虚拟化配置。

Linux 系统验证方法

在 Jellyfin Web 客户端播放视频，通过降低分辨率或码率触发视频转码。

使用 nvidia-smi 命令检查 NVIDIA GPU 的占用情况以及每个 jellyfin-ffmpeg 进程的显存使用情况：

$ nvidia-smi

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 520.56.06    Driver Version: 520.56.06    CUDA Version: 11.8     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  Off  | 00000000:1C:00.0 Off |                  N/A |
| 43%   44C    P2    36W /  75W |    274MiB /  1998MiB |     68%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
+-----------------------------------------------------------------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|    0   N/A  N/A      4024      G   /usr/lib/xorg/Xorg                 63MiB |
|    0   N/A  N/A      5837      C   /usr/lib/jellyfin-ffmpeg/ffmpeg   195MiB |
+-----------------------------------------------------------------------------+

加速方法​

色调映射方法​

选择GPU硬件​

转码H.264​

转码HEVC​

AV1转码支持​

其他编解码器支持​

速度与画质表现​

Windows环境配置​

Windows主机配置步骤​

Windows 虚拟化配置​

Windows 环境验证​

Linux 环境配置​

Linux 主机配置指南​

Debian/Ubuntu 系统​

Linux Mint​

Arch Linux​

其他发行版​

Linux 虚拟化环境配置​

官方 Docker 镜像​

Linuxserver.io Docker 方案​

Podman​

其他虚拟化方案​

Linux 系统验证方法​

加速方法

色调映射方法

选择GPU硬件

转码H.264

转码HEVC

AV1转码支持

其他编解码器支持

速度与画质表现

Windows环境配置

Windows主机配置步骤

Windows 虚拟化配置

Windows 环境验证

Linux 环境配置

Linux 主机配置指南

Debian/Ubuntu 系统

Linux Mint

Arch Linux

其他发行版

Linux 虚拟化环境配置

官方 Docker 镜像

Linuxserver.io Docker 方案

Podman

其他虚拟化方案

Linux 系统验证方法