【DCVC-RT】手把手带你在Linux环境下复现CVPR论文，保姆级教学！！！

DCVC-RT复现完全实战指南

📚文档说明：本文档基于真实环境（Windows 11 Laptop + RTX 4060）实战总结，适用于希望在 WSL2 环境下复现 DCVC-RT 的研究人员。
🎯目标：解决环境配置、大文件传输损坏、版本不兼容、配置报错等问题，实现 1080p 视频实时神经压缩推理。
⚙️核心环境：WSL2 Ubuntu 22.04 (Microsoft Store) | Python 3.12 | CUDA 12.1 | PyTorch 2.6
📅最后更新：2025年12月

📋 目录

• 1. 系统与硬件准备
• 2. Python 基础环境搭建
• 3. 项目部署与核心编译
• 4. 模型权重下载与校验（关键）
• 5. 数据准备与自动化配置
• 6. 启动推理：参数详解与实战
• 7. 结果验证与可视化
• 8. 踩坑记录与解决方案 (FAQ)

1. 系统与硬件准备

1.1 硬件环境确认

• 设备：联想拯救者笔记本 (Lenovo Legion)
• GPU：NVIDIA GeForce RTX 4060 Laptop GPU (8GB 显存)
• CPU：Intel Core i7/i9 (高性能模式)

1.2 操作系统 (WSL2)

1. 安装 Ubuntu：

• 直接在Microsoft Store搜索 “Ubuntu 22.04.3 LTS” 并安装。
• 启动 Ubuntu，设置用户名和密码。

2. 网络环境：

• 确保拥有合适的环境，以便顺利访问 GitHub 和 OneDrive 下载模型。
• WSL2 技巧：如果在 WSL2 中无法连网，可尝试重置网络或配置代理。

1.3 验证显卡穿透

在 Ubuntu 终端输入：

nvidia-smi

• 必须看到：显卡型号 (RTX 4060) 和驱动版本 (Driver Version: 5xx.xx)。
• 注意：WSL2 直接复用 Windows 驱动，切勿在 Linux 内重复安装驱动。

2. Python 基础环境搭建

2.1 安装 Miniconda

推荐使用 Miniconda 进行轻量化管理：

mkdir-p ~/miniconda3wgethttps://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.shbash~/miniconda3/miniconda.sh -b -u -p ~/miniconda3rm-rf ~/miniconda3/miniconda.sh ~/miniconda3/bin/conda initbashsource~/.bashrc

2.2 创建虚拟环境

根据官方要求，使用 Python 3.12：

conda create -n dcvc_rtpython=3.12-y conda activate dcvc_rt

2.3 安装 PyTorch

为了匹配 RTX 4060 的 CUDA 架构，安装支持 CUDA 12.x 的版本：

pipinstalltorch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

• 验证安装：

python -c"import torch; print(torch.cuda.is_available())"# 输出 True 表示成功

3. 项目部署与核心编译

3.1 获取代码

方法一：利用网络工具直接从 GitHub 克隆，确保获取最新代码

gitclone https://github.com/microsoft/DCVC.gitcdDCVC

方法二：可以直接访问此官方链接自行下载：https://github.com/microsoft/DCVC

下载完，你应该得到了一个 DCVC-main.zip。

1. 回到 Windows 桌面，打开“此电脑”或者随便一个文件夹。
2. 在文件夹顶部的地址栏里，把里面的内容清空，输入下面这行代码并回车：

\\wsl$

3. 你会看到一个叫Ubuntu-20.04的文件夹，双击进去。
4. 依次打开：home->XXX（你在Linux的账户名）。

• 这就是你在 Linux 终端里看到的~目录。

把你在 Windows 浏览器里下载好的DCVC-main.zip，直接复制、粘贴到这个文件夹里。

之后回到终端继续操作
文件粘贴进去后，回到你的黑框终端(dcvc) XXX@XXX:~$。

依次执行下面的命令：

1. 下载解压工具：

sudoaptinstallunzip-y

2. 解压代码、改名并进入文件夹：

unzipDCVC-main.zipmvDCVC-main DCVCcdDCVC

3.2 安装依赖库

pipinstall-r requirements.txt

3.3 编译 C++ 扩展 (至关重要)

这是导致很多人运行失败的核心原因。DCVC-RT 的算术编码和推理优化依赖 C++ 编译的.so文件，必须手动编译：

# 安装编译工具链sudoapt-getupdatesudoapt-getinstallcmake g++ ninja-build# 1. 编译码流读写模块 (Bitstream IO)cdsrc/cpp/ pipinstall.# 2. 编译推理优化模块 (Inference Extensions)cd../layers/extensions/inference/ pipinstall.# 返回项目根目录cd../../../

• 如果不做这一步，后续会报错缺少模块或运行极慢。

4. 模型权重下载与校验（关键）

4.1 下载方式

• 来源：官方 OneDrive 链接。
• 方法：建议在Windows 端直接下载，速度快且稳定。

4.2 文件完整性校验 (必做)

下载后请务必查看文件属性，确保大小一致：

• cvpr2025_image.pth.tar:~174 MB
• cvpr2025_video.pth.tar:~79.1 MB(82,900,000 字节左右)
• 避坑：如果 Video 模型只有 58MB 或更小，说明下载中断，必须重新下载。

4.3 传输至 Linux

将文件从 Windows 下载目录移动到 WSL 环境。直接拖拽或复制均可，但传输后需二次验证。

# 在项目根目录创建文件夹mkdir-p checkpoints# 假设文件在 Windows 下载目录 (使用 cp 命令复制)cp/mnt/c/Users/Administrator/Downloads/cvpr2025_image.pth.tar ./checkpoints/cp/mnt/c/Users/Administrator/Downloads/cvpr2025_video.pth.tar ./checkpoints/# 再次检查 Linux 内的文件大小ls-lh checkpoints/

• 确认：Video 模型必须显示为80M或79M。

5. 数据准备与自动化配置

DCVC-RT 的 JSON 配置文件对字段要求极其严格，手动修改容易出错（例如src_type字段）。

5.1 准备测试视频

将 YUV 格式视频放入DCVC/test_data/目录。

• 示例文件：ReadySteadyGo_1920x1080_120fps_420_8bit_YUV.yuv

5.2 生成“完美”配置文件

在DCVC目录下新建脚本setup_custom_video.py，使用以下代码自动生成配置：

importosimportjson# === 参数配置区 ===filename="ReadySteadyGo_1920x1080_120fps_420_8bit_YUV.yuv"width=1920height=1080framerate=120# ==================file_path=os.path.join("test_data",filename)# 自动计算帧数file_size=os.path.getsize(file_path)total_frames=file_size//(width*height*3//2)config={"test_classes":{"Custom":{"test":1,"src_type":"yuv420",# 【核心修正】必须是 yuv420，不能是 raw"dataloader":"Video","base_path":os.path.abspath("test_data"),"sequences":{os.path.splitext(filename)[0]:{"width":width,"height":height,"frames":total_frames,"frame_rate":framerate,"bit_depth":8,"format":"yuv420","intra_period":32}}}}}withopen('custom_config.json','w')asf:json.dump(config,f,indent=4)print("✅ 配置文件生成成功！")

运行：python setup_custom_video.py

6. 启动推理：参数详解与实战

6.1 显卡编号修正

• 现象：nvidia-smi显示显卡为 GPU 0，但 Windows 任务管理器显示为 GPU 1。
• 结论：代码中必须指定--cuda 0。如果用cuda 1，程序会回退到 CPU，导致无 GPU 占用且速度极慢。

6.2 最终运行命令

复制以下命令执行（已包含所有 Bug 修复）：

python test_video.py\--model_path_i ./checkpoints/cvpr2025_image.pth.tar\--model_path_p ./checkpoints/cvpr2025_video.pth.tar\--rate_num4\--test_config ./custom_config.json\--force_root_path ./\--cuda0\--worker1\--write_stream1\--output_path output_result.json\--verbose1

6.3 参数说明

• --cuda 0: 指定使用 0 号显卡（笔记本独显）。
• --write_stream 1:必须开启，否则会触发代码中的断言错误。
• --worker 1: 限制线程数为 1，避免 WSL2 下的多进程死锁问题。
• --force_root_path ./: 强制指定根目录，避免路径解析错误。

7. 结果验证与可视化

7.1 验证运行状态

• 终端：看到Frame 1,Frame 2… 滚动输出。
• 显存：使用nvidia-smi查看，Python 进程应占用 1-2GB 显存 。

7.2 输出文件

• JSON 报告：output_result.json，包含 BPP (压缩率) 和 PSNR (画质) 数据。
• 码流文件：out_bin/目录下会生成.bin压缩文件。

7.3 生成 RD 曲线图

使用 Python 脚本读取 JSON 并绘图：

importjson,matplotlib.pyplotasplt# 读取 json 并绘制 BPP-PSNR 曲线 (代码略，参考前文)# ...plt.savefig('result_chart.png')

8. 踩坑记录与解决方案 (FAQ)

🎉祝你天天开心，我将更新更多有意思的内容，欢迎关注！

最后更新：2025年12月
作者：Echo