尧图网站建设 
immich 硬件转码实战NVENC、Quick Sync、VAAPI 与 RKMPP 的 Docker 配置与源码解析【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich本篇指南基于 immich 官方文档 hardware-transcoding.md讲解如何用 GPU 加速视频转码以降低 CPU 负载覆盖四种硬件加速 APINVENC、Quick Sync、RKMPP、VAAPI的 Docker Compose 配置、immich.json配置文件写法、各硬件平台的前置条件与限制并结合 server/src/utils/media.ts 等源码说明服务端实际生成的 FFmpeg 加速参数。读完本文你可以按硬件型号完成端到端含硬解码的转码加速部署并理解每个配置项在服务端的真实作用。硬件转码是什么代价是什么immich 的硬件转码功能允许服务器使用 GPU 加速视频转码transcoding从而显著降低 CPU 占用。需要明确两个官方提示的事实边界体积与质量硬件转码在相同设置下产生的视频文件明显大于软件转码且通常质量更低。使用更慢的 preset、更高效的编码格式codec可以缩小这一差距实验性质这是相对较新的功能仍处于实验阶段可能无法在所有系统上正常工作。一个重要的免迁移特性启用硬件加速后不需要重跑已有的转码任务。加速设备只用于启用之后新执行的转码任务此前软件转码生成的文件会原样保留。源码视角加速能力的枚举定义在服务端 server/src/enum.ts 中转码硬件加速被定义为如下枚举即管理页面Video transcoding settings下拉框的五个选项来源export enum TranscodeHardwareAcceleration { Nvenc nvenc, Qsv qsv, Vaapi vaapi, Rkmpp rkmpp, Disabled disabled, }与文档Supported APIs一节一一对应NVENCNVIDIA、Quick SyncIntel、RKMPPRockchip、VAAPIAMD / NVIDIA / Intel 通用。此外server/src/constants.ts 中的SUPPORTED_HWA_CODECS常量给出了每种 API 实际允许的目标视频编码与文档Codec support varies的限制说明相互印证加速 API支持的目标视频编码nvencH.264、HEVC、AV1不支持 VP9与文档NVIDIA 与 AMD 不支持 VP9 编码一致qsvH.264、HEVC、VP9、AV1vaapiH.264、HEVC、VP9、AV1rkmpp仅 H.264、HEVCdisabled全部四种编码当管理员选择的targetVideoCodec不在对应列表内时server/src/utils/media.ts 会在构建 FFmpeg 命令时直接抛出Nvenc acceleration does not support codec ...之类的错误因此选型时必须先对照上表。功能限制部署前必读文档明确列出了以下限制本文所有配置步骤均以此为前提文中的指令与配置仅针对 Docker Compose其他容器引擎可能需要不同的配置方式仅支持 Linux 服务器以及通过 WSL2 运行的 Windows 服务器WSL2 下不支持 Quick Sync目前不支持 Raspberry PiTwo-pass 模式仅 NVENC 有效其他 API 会忽略该设置。源码层面server/src/utils/media.ts 中双遍编码的逻辑在accel ! Disabled时会被整体跳过见约 L315 处if (!this.config.twoPass || this.config.accel ! TranscodeHardwareAcceleration.Disabled)与文档描述吻合默认只有编码encoding是硬件加速的解码decoding与 tone-mapping 仍走 CPU。要获得端到端加速需要在视频转码设置中显式开启硬件解码下文accelDecode/ 步骤 5硬件相关限制编码支持因设备而异但 H.264 和 HEVC 通常都受支持较新的设备通常转码质量更高。各硬件平台前置条件NVENC服务器必须安装官方 NVIDIA 驱动Linux 上WSL2 除外还需安装 NVIDIA Container Toolkit使容器能访问 GPU。对应的容器侧配置见 docker/hwaccel.transcoding.ymlnvenc服务段通过deploy.resources.reservations.devices声明driver: nvidia并申请gpu、compute、video三类能力这正是依赖 NVIDIA Container Toolkit 的资源预留写法。QSVQuick Sync文档针对VP9 编码给出额外要求需要第 9 代及以后的 Intel CPU若为 11 代或更早的 CPU可能需要按 Jellyfin 的Low-Power 编码说明修改内核参数Low-Power 模式是 QSV 编码的前提若服务器恰好是 11 代 CPU 且运行 5.15 内核Ubuntu 22.04 LTS 自带版本需要按 Jellyfin 文档升级内核以规避已知问题。RKMPPRockchip必须是受支持的 Rockchip ARM SoC只有 RK3588 支持硬件 tonemapping其他 SoC 在硬件编码的同时使用较慢的软件 tonemappingTonemapping 依赖宿主机上的/usr/lib/aarch64-linux-gnu/libmali.so.1。需要安装与你 Mali GPU 对应的libmali发行版RK3588 对应libmali-valhall-g610-g13p0-gbm然后修改 docker/hwaccel.transcoding.yml在rkmpp段下取消以下三行 OpenCL tonemapping 配置的注释去掉行首#rkmpp: # ... devices: # - /dev/mali0:/dev/mali0 volumes: # - /etc/OpenCL:/etc/OpenCL:ro # - /usr/lib/aarch64-linux-gnu/libmali.so.1:/usr/lib/aarch64-linux-gnu/libmali.so.1:ro仓库中这三行默认即为注释状态见 docker/hwaccel.transcoding.yml且注释说明only required to enable OpenCL-accelerated HDR - SDR tonemapping。rkmpp段还默认挂载了/dev/rga、/dev/dri、/dev/dma_heap、/dev/mpp_service四个设备并放宽了 apparmor 限制这些是 Rockchip 硬件编码链路的基础无需手动改动。基础部署Docker Compose extends步骤一获取 hwaccel.transcoding.yml 并放置如果尚无该文件下载仓库中的 docker/hwaccel.transcoding.yml确保它与docker-compose.yml位于同一目录。该文件定义了五个可挂载的后端服务段services: cpu: {} nvenc: # 通过 deploy.resources 申请 NVIDIA GPU quicksync: # 挂载 /dev/dri rkmpp: # 挂载 Rockchip 设备节点 可注释的 Mali/OpenCL 卷 vaapi: # 挂载 /dev/dri vaapi-wsl: # WSL2 专用额外挂载 /dev/dxg并设置 LIBVA_DRIVER_NAMEd3d12步骤二在 docker-compose.yml 中启用 extends在docker-compose.yml的immich-server服务下取消注释extends段并把cpu改成与你的硬件匹配的后端名称。docker/docker-compose.yml 中该段默认即为注释状态immich-server: # extends: # file: hwaccel.transcoding.yml # service: cpu改为例如service: quicksync即可。注意WSL2 下使用 VAAPI 时务必用vaapi-wsl而不是vaapi。两者差异见 docker/hwaccel.transcoding.ymlvaapi-wsl额外挂载/dev/dxg与/usr/lib/wsl并注入LIBVA_DRIVER_NAMEd3d12环境变量走 DirectX 12 的 VAAPI 兼容路径。步骤三重新部署 immich-server 容器用更新后的配置重新部署immich-server容器使设备挂载生效。步骤四在管理页面选择加速 API打开 Admin 页面 →Video transcoding settings把硬件加速设置改为对应选项nvenc/qsv/vaapi/rkmpp并保存。注意对于 Jasper Lake 与 Elkhart Lake 这类 CPU需要把Hardware Acceleration - Constant quality mode设为CQP。对应服务端枚举CQModeauto/cqp/icq定义在 server/src/enum.ts。步骤五可选开启硬件解码为获得最优性能建议开启硬件解码实现端到端加速。这一步对应 FFmpeg 配置中的accelDecode字段server/src/dtos/config.dto.ts 将其定义为configBool.describe(Accelerated decode)且 server/src/dtos/config.dto.ts 中的默认值为accel: DisabledaccelDecode: true——即默认关闭硬编码、默认开启硬解码与文档默认只有编码是软件的说明一致。开启后server/src/utils/media.ts 会为各 API 生成不同的硬解码参数例如 NVENC 路径使用-hwaccel cuda -hwaccel_output_format cuda见约 L734QSV 路径使用-hwaccel qsv -hwaccel_output_format qsv并配合scale_qsv缩放滤镜约 L781-L918。配置文件方式immich.json 的 accel 选项如果你使用 配置文件方式部署无需改 compose直接在immich.json中用accel选择硬件如 Intel 用qsv、NVIDIA 用nvenc需要硬解码时把accelDecode设为true{ ffmpeg: { accel: qsv, accelDecode: true } }转码相关配置项全景结合 server/src/dtos/config.dto.ts 中的AdminConfigFFmpegSchema管理页面Video transcoding settings里与硬件转码最相关的字段及其约束为字段类型/范围说明acceldisabled/nvenc/qsv/vaapi/rkmpp硬件加速 API默认disabledaccelDecodeboolean是否硬件解码默认truetwoPassboolean双遍编码仅 NVENC 实际生效cqModeauto/cqp/icq恒质量模式Jasper Lake / Elkhart Lake 需cqppresetstring转码 preset硬件转码建议选更慢的 presetcrf整数 0–51恒定质量因子targetVideoCodec视频编码必须在SUPPORTED_HWA_CODECS对应列表内preferredHwDevicestring偏好使用的硬件设备tonemaphable/mobius/reinhard/disabledHDR→SDR tone mapping 算法单文件部署不依赖 extends 的平台部分平台如 Unraid、Portainer截至文档撰写时不支持多个 Compose 文件。替代方案是把 docker/hwaccel.transcoding.yml 中对应后端的配置内联到docker-compose.yml的immich-server服务里去掉extends段。以quicksync段为例该段内容仅为devices: - /dev/dri:/dev/driimmich-server: container_name: immich_server image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release} # 注意没有 extends 段 devices: - /dev/dri:/dev/dri volumes: ...nvenc/rkmpp/vaapi的内联做法同理直接复制 docker/hwaccel.transcoding.yml 中对应服务段的全部键deploy/devices/volumes/security_opt/group_add/environment到immich-server服务即可。完成内联后回到基础部署的步骤三继续重新部署容器并修改管理页面设置。All-In-OneUnraid 专属步骤QSVUnraid Docker 停止Immich 容器 Edit下滑选择Add another Path, Port, Variable, Label or Device下拉菜单选Device任取一个名称值填/dev/dri继续基础部署的步骤四。NVENC在容器应用中添加环境变量KeyNVIDIA_VISIBLE_DEVICESValueall将容器从 Basic Mode 切到 Advanced Mode并在 Extra Parameters 字段添加--runtimenvidia重启容器应用继续基础部署的步骤四。服务端实现从配置到 FFmpeg 命令的调用链理解服务端如何处理硬件转码有助于排查改了设置没生效类问题。命令构建按 API 分发server/src/utils/media.ts 是转码命令的构建核心。其流程为见约 L70-L130若config.accel Disabled走纯软件编码路径校验targetVideoCodec是否在SUPPORTED_HWA_CODECS[config.accel]内否则报错按accel值 switch 分发到NvencHandler/QsvHandler/VaapiHandler/RkmppHandler并且每个 Handler 内部再根据accelDecode选择硬解码输入参数如 CUDA /scale_qsv/scale_vaapi/hwmapderive_devicerkmpp或退化为软件解码 硬件编码。从源码结构看各 Handler 的硬解码参数即 FFmpeg 的硬件管线例如 QSV 会构造-init_hw_device qsvhw,child_device${device}与hwmapderive_deviceqsv滤镜链约 L781、L907RKMPP 则使用-hwaccel rkmpp -hwaccel_output_format drm_prime -afbc rga加hwmapderive_devicerkmpp:modewrite:reverse1约 L1080-L1092。容错回退失败自动降级server/src/services/media.service.ts 展示了转码任务的日志与重试策略每次转码会打印所用模式日志Transcoding video ... with QSV-accelerated encoding and software decoding或...accelerated decoding、without hardware acceleration这本身就可以作为设备是否被真正使用的验证手段若硬件解码路径失败会以硬编码 软解码重试Retrying with QSV-accelerated encoding and software decoding若仍失败则彻底关闭硬件加速重试Retrying with hardware acceleration disabled保证转码任务最终完成而不阻塞队列。这也解释了为什么误配硬件 API 时 immich 不会丢任务——代价只是该次转码退回 CPU 且文件可能更大。调优与验证技巧文档 Tips 一节给出的实践建议结合源码可以进一步落地选更慢的 preset硬件转码的 preset 与软件转码的 preset 含义不同为保持质量与效率建议选比软件转码更慢如slow/slower的档位优先专用 API 而非 VAAPI虽然 VAAPI 可用于 NVIDIA 与 Intel 设备但 NVENCnvenc与 QSVqsv分别为自家设备深度优化应优先选用验证设备确实被使用转码期间用nvtopNVIDIA、intel_gpu_topIntel等工具查看 GPU 利用率同时检查日志无报错参考上文media.service.ts的转码日志也是设备生效的旁证对照 codec 支持表选型若目标是 VP9 编码只能选qsv或vaapiNVENC 选 VP9 会在命令构建阶段直接失败见 server/src/constants.ts。小结immich 的硬件转码通过compose 层设备挂载 配置层 API 选择两条正交链路实现前者决定容器能否看到 GPUdocker/hwaccel.transcoding.yml 的extends或内联设备段后者决定 FFmpeg 走哪条硬件编码/解码管线accelaccelDecode见 server/src/utils/media.ts。按本文的前置条件核对硬件、按对应平台的步骤挂载设备、在管理页面或immich.json中选定 API 并可选开启硬解码即可完成从软件转码到端到端硬件加速的切换且无需重跑任何历史转码任务。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 immich 硬件转码实战：NVENC、Quick Sync、VAAPI 与 RKMPP 的 Docker 配置与源码解析
immich 硬件转码实战NVENC、Quick Sync、VAAPI 与 RKMPP 的 Docker 配置与源码解析【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich本篇指南基于 immich 官方文档 hardware-transcoding.md讲解如何用 GPU 加速视频转码以降低 CPU 负载覆盖四种硬件加速 APINVENC、Quick Sync、RKMPP、VAAPI的 Docker Compose 配置、immich.json配置文件写法、各硬件平台的前置条件与限制并结合 server/src/utils/media.ts 等源码说明服务端实际生成的 FFmpeg 加速参数。读完本文你可以按硬件型号完成端到端含硬解码的转码加速部署并理解每个配置项在服务端的真实作用。硬件转码是什么代价是什么immich 的硬件转码功能允许服务器使用 GPU 加速视频转码transcoding从而显著降低 CPU 占用。需要明确两个官方提示的事实边界体积与质量硬件转码在相同设置下产生的视频文件明显大于软件转码且通常质量更低。使用更慢的 preset、更高效的编码格式codec可以缩小这一差距实验性质这是相对较新的功能仍处于实验阶段可能无法在所有系统上正常工作。一个重要的免迁移特性启用硬件加速后不需要重跑已有的转码任务。加速设备只用于启用之后新执行的转码任务此前软件转码生成的文件会原样保留。源码视角加速能力的枚举定义在服务端 server/src/enum.ts 中转码硬件加速被定义为如下枚举即管理页面Video transcoding settings下拉框的五个选项来源export enum TranscodeHardwareAcceleration { Nvenc nvenc, Qsv qsv, Vaapi vaapi, Rkmpp rkmpp, Disabled disabled, }与文档Supported APIs一节一一对应NVENCNVIDIA、Quick SyncIntel、RKMPPRockchip、VAAPIAMD / NVIDIA / Intel 通用。此外server/src/constants.ts 中的SUPPORTED_HWA_CODECS常量给出了每种 API 实际允许的目标视频编码与文档Codec support varies的限制说明相互印证加速 API支持的目标视频编码nvencH.264、HEVC、AV1不支持 VP9与文档NVIDIA 与 AMD 不支持 VP9 编码一致qsvH.264、HEVC、VP9、AV1vaapiH.264、HEVC、VP9、AV1rkmpp仅 H.264、HEVCdisabled全部四种编码当管理员选择的targetVideoCodec不在对应列表内时server/src/utils/media.ts 会在构建 FFmpeg 命令时直接抛出Nvenc acceleration does not support codec ...之类的错误因此选型时必须先对照上表。功能限制部署前必读文档明确列出了以下限制本文所有配置步骤均以此为前提文中的指令与配置仅针对 Docker Compose其他容器引擎可能需要不同的配置方式仅支持 Linux 服务器以及通过 WSL2 运行的 Windows 服务器WSL2 下不支持 Quick Sync目前不支持 Raspberry PiTwo-pass 模式仅 NVENC 有效其他 API 会忽略该设置。源码层面server/src/utils/media.ts 中双遍编码的逻辑在accel ! Disabled时会被整体跳过见约 L315 处if (!this.config.twoPass || this.config.accel ! TranscodeHardwareAcceleration.Disabled)与文档描述吻合默认只有编码encoding是硬件加速的解码decoding与 tone-mapping 仍走 CPU。要获得端到端加速需要在视频转码设置中显式开启硬件解码下文accelDecode/ 步骤 5硬件相关限制编码支持因设备而异但 H.264 和 HEVC 通常都受支持较新的设备通常转码质量更高。各硬件平台前置条件NVENC服务器必须安装官方 NVIDIA 驱动Linux 上WSL2 除外还需安装 NVIDIA Container Toolkit使容器能访问 GPU。对应的容器侧配置见 docker/hwaccel.transcoding.ymlnvenc服务段通过deploy.resources.reservations.devices声明driver: nvidia并申请gpu、compute、video三类能力这正是依赖 NVIDIA Container Toolkit 的资源预留写法。QSVQuick Sync文档针对VP9 编码给出额外要求需要第 9 代及以后的 Intel CPU若为 11 代或更早的 CPU可能需要按 Jellyfin 的Low-Power 编码说明修改内核参数Low-Power 模式是 QSV 编码的前提若服务器恰好是 11 代 CPU 且运行 5.15 内核Ubuntu 22.04 LTS 自带版本需要按 Jellyfin 文档升级内核以规避已知问题。RKMPPRockchip必须是受支持的 Rockchip ARM SoC只有 RK3588 支持硬件 tonemapping其他 SoC 在硬件编码的同时使用较慢的软件 tonemappingTonemapping 依赖宿主机上的/usr/lib/aarch64-linux-gnu/libmali.so.1。需要安装与你 Mali GPU 对应的libmali发行版RK3588 对应libmali-valhall-g610-g13p0-gbm然后修改 docker/hwaccel.transcoding.yml在rkmpp段下取消以下三行 OpenCL tonemapping 配置的注释去掉行首#rkmpp: # ... devices: # - /dev/mali0:/dev/mali0 volumes: # - /etc/OpenCL:/etc/OpenCL:ro # - /usr/lib/aarch64-linux-gnu/libmali.so.1:/usr/lib/aarch64-linux-gnu/libmali.so.1:ro仓库中这三行默认即为注释状态见 docker/hwaccel.transcoding.yml且注释说明only required to enable OpenCL-accelerated HDR - SDR tonemapping。rkmpp段还默认挂载了/dev/rga、/dev/dri、/dev/dma_heap、/dev/mpp_service四个设备并放宽了 apparmor 限制这些是 Rockchip 硬件编码链路的基础无需手动改动。基础部署Docker Compose extends步骤一获取 hwaccel.transcoding.yml 并放置如果尚无该文件下载仓库中的 docker/hwaccel.transcoding.yml确保它与docker-compose.yml位于同一目录。该文件定义了五个可挂载的后端服务段services: cpu: {} nvenc: # 通过 deploy.resources 申请 NVIDIA GPU quicksync: # 挂载 /dev/dri rkmpp: # 挂载 Rockchip 设备节点 可注释的 Mali/OpenCL 卷 vaapi: # 挂载 /dev/dri vaapi-wsl: # WSL2 专用额外挂载 /dev/dxg并设置 LIBVA_DRIVER_NAMEd3d12步骤二在 docker-compose.yml 中启用 extends在docker-compose.yml的immich-server服务下取消注释extends段并把cpu改成与你的硬件匹配的后端名称。docker/docker-compose.yml 中该段默认即为注释状态immich-server: # extends: # file: hwaccel.transcoding.yml # service: cpu改为例如service: quicksync即可。注意WSL2 下使用 VAAPI 时务必用vaapi-wsl而不是vaapi。两者差异见 docker/hwaccel.transcoding.ymlvaapi-wsl额外挂载/dev/dxg与/usr/lib/wsl并注入LIBVA_DRIVER_NAMEd3d12环境变量走 DirectX 12 的 VAAPI 兼容路径。步骤三重新部署 immich-server 容器用更新后的配置重新部署immich-server容器使设备挂载生效。步骤四在管理页面选择加速 API打开 Admin 页面 →Video transcoding settings把硬件加速设置改为对应选项nvenc/qsv/vaapi/rkmpp并保存。注意对于 Jasper Lake 与 Elkhart Lake 这类 CPU需要把Hardware Acceleration - Constant quality mode设为CQP。对应服务端枚举CQModeauto/cqp/icq定义在 server/src/enum.ts。步骤五可选开启硬件解码为获得最优性能建议开启硬件解码实现端到端加速。这一步对应 FFmpeg 配置中的accelDecode字段server/src/dtos/config.dto.ts 将其定义为configBool.describe(Accelerated decode)且 server/src/dtos/config.dto.ts 中的默认值为accel: DisabledaccelDecode: true——即默认关闭硬编码、默认开启硬解码与文档默认只有编码是软件的说明一致。开启后server/src/utils/media.ts 会为各 API 生成不同的硬解码参数例如 NVENC 路径使用-hwaccel cuda -hwaccel_output_format cuda见约 L734QSV 路径使用-hwaccel qsv -hwaccel_output_format qsv并配合scale_qsv缩放滤镜约 L781-L918。配置文件方式immich.json 的 accel 选项如果你使用 配置文件方式部署无需改 compose直接在immich.json中用accel选择硬件如 Intel 用qsv、NVIDIA 用nvenc需要硬解码时把accelDecode设为true{ ffmpeg: { accel: qsv, accelDecode: true } }转码相关配置项全景结合 server/src/dtos/config.dto.ts 中的AdminConfigFFmpegSchema管理页面Video transcoding settings里与硬件转码最相关的字段及其约束为字段类型/范围说明acceldisabled/nvenc/qsv/vaapi/rkmpp硬件加速 API默认disabledaccelDecodeboolean是否硬件解码默认truetwoPassboolean双遍编码仅 NVENC 实际生效cqModeauto/cqp/icq恒质量模式Jasper Lake / Elkhart Lake 需cqppresetstring转码 preset硬件转码建议选更慢的 presetcrf整数 0–51恒定质量因子targetVideoCodec视频编码必须在SUPPORTED_HWA_CODECS对应列表内preferredHwDevicestring偏好使用的硬件设备tonemaphable/mobius/reinhard/disabledHDR→SDR tone mapping 算法单文件部署不依赖 extends 的平台部分平台如 Unraid、Portainer截至文档撰写时不支持多个 Compose 文件。替代方案是把 docker/hwaccel.transcoding.yml 中对应后端的配置内联到docker-compose.yml的immich-server服务里去掉extends段。以quicksync段为例该段内容仅为devices: - /dev/dri:/dev/driimmich-server: container_name: immich_server image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release} # 注意没有 extends 段 devices: - /dev/dri:/dev/dri volumes: ...nvenc/rkmpp/vaapi的内联做法同理直接复制 docker/hwaccel.transcoding.yml 中对应服务段的全部键deploy/devices/volumes/security_opt/group_add/environment到immich-server服务即可。完成内联后回到基础部署的步骤三继续重新部署容器并修改管理页面设置。All-In-OneUnraid 专属步骤QSVUnraid Docker 停止Immich 容器 Edit下滑选择Add another Path, Port, Variable, Label or Device下拉菜单选Device任取一个名称值填/dev/dri继续基础部署的步骤四。NVENC在容器应用中添加环境变量KeyNVIDIA_VISIBLE_DEVICESValueall将容器从 Basic Mode 切到 Advanced Mode并在 Extra Parameters 字段添加--runtimenvidia重启容器应用继续基础部署的步骤四。服务端实现从配置到 FFmpeg 命令的调用链理解服务端如何处理硬件转码有助于排查改了设置没生效类问题。命令构建按 API 分发server/src/utils/media.ts 是转码命令的构建核心。其流程为见约 L70-L130若config.accel Disabled走纯软件编码路径校验targetVideoCodec是否在SUPPORTED_HWA_CODECS[config.accel]内否则报错按accel值 switch 分发到NvencHandler/QsvHandler/VaapiHandler/RkmppHandler并且每个 Handler 内部再根据accelDecode选择硬解码输入参数如 CUDA /scale_qsv/scale_vaapi/hwmapderive_devicerkmpp或退化为软件解码 硬件编码。从源码结构看各 Handler 的硬解码参数即 FFmpeg 的硬件管线例如 QSV 会构造-init_hw_device qsvhw,child_device${device}与hwmapderive_deviceqsv滤镜链约 L781、L907RKMPP 则使用-hwaccel rkmpp -hwaccel_output_format drm_prime -afbc rga加hwmapderive_devicerkmpp:modewrite:reverse1约 L1080-L1092。容错回退失败自动降级server/src/services/media.service.ts 展示了转码任务的日志与重试策略每次转码会打印所用模式日志Transcoding video ... with QSV-accelerated encoding and software decoding或...accelerated decoding、without hardware acceleration这本身就可以作为设备是否被真正使用的验证手段若硬件解码路径失败会以硬编码 软解码重试Retrying with QSV-accelerated encoding and software decoding若仍失败则彻底关闭硬件加速重试Retrying with hardware acceleration disabled保证转码任务最终完成而不阻塞队列。这也解释了为什么误配硬件 API 时 immich 不会丢任务——代价只是该次转码退回 CPU 且文件可能更大。调优与验证技巧文档 Tips 一节给出的实践建议结合源码可以进一步落地选更慢的 preset硬件转码的 preset 与软件转码的 preset 含义不同为保持质量与效率建议选比软件转码更慢如slow/slower的档位优先专用 API 而非 VAAPI虽然 VAAPI 可用于 NVIDIA 与 Intel 设备但 NVENCnvenc与 QSVqsv分别为自家设备深度优化应优先选用验证设备确实被使用转码期间用nvtopNVIDIA、intel_gpu_topIntel等工具查看 GPU 利用率同时检查日志无报错参考上文media.service.ts的转码日志也是设备生效的旁证对照 codec 支持表选型若目标是 VP9 编码只能选qsv或vaapiNVENC 选 VP9 会在命令构建阶段直接失败见 server/src/constants.ts。小结immich 的硬件转码通过compose 层设备挂载 配置层 API 选择两条正交链路实现前者决定容器能否看到 GPUdocker/hwaccel.transcoding.yml 的extends或内联设备段后者决定 FFmpeg 走哪条硬件编码/解码管线accelaccelDecode见 server/src/utils/media.ts。按本文的前置条件核对硬件、按对应平台的步骤挂载设备、在管理页面或immich.json中选定 API 并可选开启硬解码即可完成从软件转码到端到端硬件加速的切换且无需重跑任何历史转码任务。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考