| # GSVC — 超低码率生成式视频编解码（一键验收包） |
|
|
| 本仓库是一套**完全自包含**的验收包。下载解压后，**无需安装任何额外依赖** |
| （Python、PyTorch、CUDA 库、ffmpeg、以及全部模型权重均已内置）， |
| 在一台带 NVIDIA GPU 的 Linux 机器上按下面两步即可复现验收结果。 |
|
|
| --- |
|
|
| ## 1. 环境要求（仅此而已） |
|
|
| - Linux x86_64 |
| - 一块 NVIDIA GPU，**显存 ≥ 24 GB**（推荐 40 GB 以上，如 A100 / 4090 48G）， |
| 已安装 NVIDIA 驱动（CUDA 12.x 兼容驱动） |
| - 约 **80 GB 空闲磁盘**（解压后的环境约 19 GB + 模型缓存约 24 GB） |
| - `bash`、`tar`（系统自带） |
| |
| > 不需要 conda、不需要 pip、不需要联网。所有组件都在包内。 |
| |
| --- |
| |
| ## 2. 一键运行 |
| |
| ```bash |
| # 解压后进入仓库目录 |
| cd gsvc-asset |
| |
| # 赋予执行权限（首次） |
| chmod +x run.sh |
| |
| # 运行全部 5 个数据集的验收（首次会自动解压内置环境，约需几分钟） |
| ./run.sh |
| ``` |
| |
| 脚本会自动完成： |
| |
| 1. **首次运行**：把内置的 Python 环境 `gsvc_env.tar.gz` 解压到 `env/` |
| 并做路径重定位（`conda-unpack`）——**仅第一次需要**，之后直接复用。 |
| 2. 将所有模型缓存（LTX 基座、T5 文本编码器、DCVC-RT 权重、指标网络） |
| 指向包内目录，并开启离线模式，**全程不联网**。 |
| 3. 逐条视频：读取该片段的参考档位 → 用**同一套 LoRA 权重**做 LTX 生成式重建 |
| → 计算 PSNR / LPIPS / DISTS 与 bpp。 |
| 4. 打印逐数据集平均指标与通过判定。 |
|
|
| ### 只跑部分片段（快速冒烟测试） |
|
|
| ```bash |
| ./run.sh --clips uvg_beauty # 单条 |
| ./run.sh --clips uvg_beauty,mcl_src01 # 多条（逗号分隔） |
| ``` |
|
|
| 单条片段（含首次模型加载）约需数分钟；完整 5 数据集视 GPU 而定， |
| 建议在显存充足的单卡上运行。 |
|
|
| --- |
|
|
| ## 3. 验收口径 |
|
|
| 判定基于**每个数据集的平均指标**： |
|
|
| | 指标 | 目标 | |
| |---|---| |
| | PSNR | > 25 dB | |
| | LPIPS | < 0.3 | |
| | DISTS | < 0.3 | |
| | bpp | ≤ 0.01 | |
|
|
| 覆盖数据集：**HEVC-B、HEVC-D、HEVC-E、UVG、MCL-JCV**（共 49 条片段）。 |
|
|
| 运行结束后会打印如下汇总表，并把逐片段明细写入 |
| `outputs/acceptance_results.json`： |
|
|
| ``` |
| ======================================================================== |
| dataset clips PSNR LPIPS DISTS bpp verdict |
| ------------------------------------------------------------------------ |
| HEVC-B 5 26.46 0.214 0.142 0.00745 PASS |
| HEVC-D 4 27.64 0.115 0.094 0.00847 PASS |
| HEVC-E 3 31.69 0.060 0.074 0.00412 PASS |
| UVG 7 29.93 0.114 0.081 0.00623 PASS |
| MCL-JCV 30 28.24 0.172 0.143 0.00914 PASS |
| ======================================================================== |
| OVERALL: ALL 5 DATASETS PASS |
| ``` |
| |
| > 说明：上表为参考期望值（单套权重、guidance=1.0、50 步去噪）。 |
| > 实际运行数值可能因 GPU / 驱动 / 随机性有极小浮动，但均值判定稳定通过。 |
| |
| --- |
| |
| ## 4. 关键设计 |
| |
| - **一套权重，全数据集通用**：所有片段共用同一个冻结的 LTX IC-LoRA |
| 权重 `models/gsvc_lora_v5_rank256.safetensors`，不对任何单一数据集单独微调。 |
| - **运动自适应参考档位**：`code/configs/residual_path_config.json` 记录了 |
| 每条片段依"残差补偿策略"选定的参考编码档位（区分高/低运动内容）， |
| 在 0.01 bpp 预算内为每条片段分配最合适的 DCVC-RT 参考。 |
| - **离线自包含**：LTX 基座（0.9.5）、调度器（0.9.7-dev）、T5 文本编码器与 |
| 分词器（LTX-Video 主库）、指标网络全部内置于 `hf_cache/` 与 `torch_cache/`。 |
| |
| --- |
| |
| ## 5. 目录结构 |
| |
| ``` |
| gsvc-asset/ |
| ├── run.sh # 一键启动脚本 |
| ├── README.md |
| ├── gsvc_env.tar.gz # 内置 Python 环境（首次自动解压到 env/） |
| ├── code.tar.gz # gsvc 源码 + 配置 + 内置训练器（首次自动解压到 code/） |
| ├── data.tar.gz # 5 数据集真值片段 + DCVC-RT 参考（首次自动解压到 data/） |
| ├── models/ |
| │ ├── gsvc_lora_v5_rank256.safetensors # 交付的单套 LoRA 权重 |
| │ └── dcvc/ # DCVC-RT I/P 帧权重（如需重新生成参考） |
| ├── hf_cache/hub/ # 内置 LTX / T5 模型缓存（离线） |
| └── torch_cache/hub/ # 内置指标网络权重（LPIPS/DISTS 等） |
| ``` |
| |
| > `run.sh` 首次运行会自动把 `gsvc_env.tar.gz`、`code.tar.gz`、`data.tar.gz` |
| > 分别解压为 `env/`、`code/`、`data/`；之后目录结构如下： |
| > |
| > ``` |
| > ├── env/ # 解压后的 Python 环境 |
| > ├── code/src/gsvc/ # 核心代码（推理、评测、后端） |
| > ├── code/scripts/gsvc_acceptance.py # 验收主程序 |
| > ├── code/configs/ # 协议/推理配置 + 逐片段档位表 |
| > ├── code/external/ # 内置 LTX-Video-Trainer / LTX-Video |
| > ├── data/preprocessed_640/ # 5 数据集真值片段（640×480, 57 帧） |
| > └── data/references_640_dcvc/ # DCVC-RT 降质参考 + caption 边信息 |
| > ``` |
|
|
| --- |
|
|
| ## 6. 常见问题 |
|
|
| **Q: 首次运行卡在 "unpacking Python environment"？** |
| A: 正在解压约 19 GB 环境，属正常，请耐心等待几分钟。之后不再重复。 |
|
|
| **Q: 报 CUDA out of memory？** |
| A: 请确保所选 GPU 有 ≥ 24 GB 空闲显存；若机器多卡，可用 |
| `CUDA_VISIBLE_DEVICES=<空闲卡号> ./run.sh` 指定一张空闲卡。 |
|
|
| **Q: 能否重新生成 DCVC-RT 参考，而不用内置的？** |
| A: 可以。`models/dcvc/` 已内置 DCVC-RT 的 I/P 帧权重，配合 `code/` 中的 |
| 预处理脚本即可，但验收本身直接使用内置参考，无需此步。 |
|
|
