README.md

# 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/` 中的
预处理脚本即可，但验收本身直接使用内置参考，无需此步。