README_zh.md

<p align="center">
  <img src="assets/logo.png" alt="NAVA" width="160">
</p>

<h1 align="center">NAVA — 原生音视频对齐生成框架</h1>

<p align="center">
  <em>仅用 <b>6.3B</b> 参数即达到最先进的音视频同步效果。</em>
</p>

<p align="center">
  <a href="https://arxiv.org/abs/2605.30073"><img alt="arXiv" src="https://img.shields.io/badge/Paper-arXiv-b31b1b.svg"></a>
  <a href="https://github.com/ernie-research/NAVA"><img alt="Code" src="https://img.shields.io/badge/Code-GitHub-181717.svg"></a>
  <a href="https://ernie-research.github.io/NAVA/"><img alt="Project Page" src="https://img.shields.io/badge/Project_Page-online-2c8ebb.svg"></a>
  <img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-green.svg">
  <img alt="Params" src="https://img.shields.io/badge/params-6.3B-orange.svg">
  <img alt="Base model" src="https://img.shields.io/badge/base-Wan2.2--TI2V--5B-7c5cff.svg">
</p>

<p align="center">
  <b>ERNIE 团队</b> · 百度公司 · arXiv 2026
</p>

<p align="center">
  ⭐ <b>如果本模型对你有帮助，欢迎给我们的 <a href="https://github.com/ernie-research/NAVA">GitHub 仓库</a> 点个 Star！</b> ⭐
</p>

<p align="center">
  📖 <a href="https://huggingface.co/baidu/NAVA/blob/main/README.md"><b>English Version</b></a>
</p>

---

## TL;DR

NAVA 是一个 **6.3B 参数的联合音视频生成模型**，可以从一段提示词出发，端到端合成同步的视频**与**音频——包括带参考音色控制的多说话人语音，以及基于首帧图像的延续生成。

不同于事后对齐的双塔结构、或完全统一的三模态大栈，NAVA 采用 **Align-then-Fuse MMDiT**：先在专用对齐空间中建立音视频对应关系，再通过 cross-attention 融入上下文（文本、说话人嵌入）。在 Verse-Bench 上，NAVA 在 Sync-C / Sync-D / 视频质量 / 音频 WER 等指标上均刷新 SOTA，同时参数量比开源基线**少 2× 到 5×**。

> **亮点**
> - **720p 1 分钟快速生成** —— 8 卡 Ulysses 序列并行下，约 1 分钟生成 720p 同步音视频。
> - **双声道音频** —— 立体声音频（环境音 + 语音）与视频联合去噪，无需事后声码器对齐。
> - **精准多音色控制** —— 参考 WAV 绑定到 `<S>...<E>` 语音片段，实现按说话人控制音色身份。
> - **语言描述的镜头控制** —— 镜头构图、运动、节奏可直接由提示词驱动。
> - **多分辨率** —— 同一权重支持横屏 / 竖屏 / 方形比例。

---

## 模型详情

### 关键参数速览

| | |
|---|---|
| **架构** | Align-then-Fuse MMDiT（Wan2.2 主干） |
| **参数量** | **6.3B**（主干，联合 AV） |
| **模态** | 联合音频 + 视频，文本条件 |
| **分辨率** | 1280×704（推荐）· 同时支持 960×960 |
| **帧数 / 帧率** | 37 帧 @ 24 fps ≈ 6 秒 · 55–61 帧 ≈ 9–10 秒 |
| **音频** | 25 个 latent token / 秒，≤ 10 秒 |
| **采样** | Flow matching · UniPC scheduler · 默认 50 步 |
| **精度** | bf16 |
| **并行** | 单卡 **或** Ulysses 序列并行（最多 8 卡） |
| **基础模型** | [Wan-AI/Wan2.2-TI2V-5B](https://huggingface.co/Wan-AI/Wan2.2-TI2V-5B) |

### 架构

<p align="center">
  <img src="assets/arch.png" alt="NAVA Architecture" width="900">
</p>

NAVA 把*原生音视频对齐*实例化为 **Align-then-Fuse MMDiT** 堆栈：

- **层级对齐层 —— 10 个 double-stream 块。** 视频与音频保留各自独立的 QKV 投影与 FFN，但共享一个对 `[video_tokens; audio_tokens]` 拼接序列的联合 self-attention，并各自有专用的 cross-attention 接入文本。这样构建出一个对齐空间，让 AV 对应关系在不被语义上下文干扰的前提下被学到。
- **统一融合层 —— 20 个 single-stream 块。** 视频与音频共享 QKV/FFN；统一的联合注意力把所有 token 视作一条序列，仅有一条文本 cross-attention 通路。上下文条件下的去噪在这里发生。
- **主干超参。** `dim=3072`，`ffn_dim=14336`，24 个注意力头，30 层（10 double + 20 single），`text_len=512`，patch 大小 `(1, 2, 2)`。QK 上使用 RMSNorm；带 cross-attention 归一化；ε = 1e-6。
- **位置编码。** 视频用 3D RoPE（时间 + 高 + 宽），音频用 1D RoPE，二者在联合注意力路径中联合应用。
- **Timbre-in-Context 条件机制。** 参考 WAV 的说话人嵌入（ReDimNet，192 维）通过上下文通路注入，并绑定到 `<S>...<E>` 语音片段，使多说话人场景下的逐说话人音色控制成为可能。
- **3D 跨模态 CFG。** 视频、音频以及跨模态对齐方向各自拥有独立的无分类器引导尺度（`video_align_guidance_scale`、`audio_align_guidance_scale`），在推理阶段把 AV 同步性卡得很紧。

### 与现有开源 AV 模型的差异

| 设计维度 | 典型基线 | **NAVA** |
|---|---|---|
| 数据流布局 | 双塔（事后对齐）**或** 完全统一三模态 | **Align-then-Fuse** —— 先对齐空间，再融合上下文 |
| 语音控制 | 仅 caption，无逐说话人音色 | 通过参考 WAV 实现 **Timbre-in-Context** |
| 参数预算 | 10B – 32B | **6.3B** |

### 与主干一同发布的组件

| 组件 | 说明 | 大小 |
|---|---|---|
| **WanAVModel**（主干） | MMDiT，联合 AV 注意力 | 6.3B |
| **Wan2.2 Video VAE** | 因果 3D ConvNet · 16×16×4 时空压缩 · 48 latent 通道 | 2.7 GB |
| **LTX Audio VAE + Vocoder** | 128 latent 通道 · 25 token/秒 · 内置波形解码器 | 348 MB |
| **umt5-xxl 文本编码器** | T5 · 4096 维嵌入 | 11 GB |
| **ReDimNet** | 说话人嵌入 · 192 维 | ~50 MB |

---

## 评测

### 表 1 —— VerseBench（综合 AV 能力）

NAVA 在 AV 同步（Sync-C / Sync-D）、视频质量与音频 WER 上均取得**最佳**，同时参数量最小。

| 模型 | 参数量 | 分辨率 | Sync-C ↑ | Sync-D ↓ | IB ↑ | 视频质量 ↑ | WER ↓ | PQ ↑ | FD ↓ |
|---|---|---|---|---|---|---|---|---|---|
| Ovi 1.1 | 10B | 720p | <u>7.4839</u> | 7.9791 | 0.199 | <u>0.636</u> | 0.102 | 5.8432 | 0.9418 |
| MOVA | A18B (32B) | 720p | 7.2888 | 7.808 | 0.269 | 0.603 | 0.126 | **7.2331** | 0.9222 |
| Davinci | 15B | 540p | 7.1487 | 7.8158 | 0.269 | 0.600 | 0.151 | 5.9559 | 0.9307 |
| LTX 2.3 | 19B | 512p | 7.2476 | <u>7.6902</u> | **0.337** | 0.576 | 0.106 | <u>6.9459</u> | **0.8287** |
| **NAVA（本工作）** | **6.3B** | 720p | **7.7914** | **7.5655** | <u>0.313</u> | **0.659** | **0.099** | 6.8609 | <u>0.8328</u> |

<sub>↑ 越高越好 · ↓ 越低越好 · **加粗** = 最佳 · <u>下划线</u> = 次佳。</sub>

### 表 2 —— Seed-TTS-eval（语音质量）

在联合 AV 模型中，NAVA 的语音质量已接近专用纯音频系统。纯音频行仅作*参考*，不可直接比较。

| 类别 | 模型 | WER ↓ | 说话人相似度 ↑ |
|---|---|---|---|
| 纯音频（参考） | CosyVoice | 4.29 | 60.9 |
| 纯音频（参考） | Qwen2.5-Omni | 2.72 | 63.2 |
| 联合音视频 | DreamID-Omni | 33.44 | 34.1 |
| 联合音视频 | **NAVA（本工作）** | **5.81** | **62.4** |

---

## 使用方法

> **一行命令。** 完成第 §1 步环境准备后：
> ```bash
> bash scripts/inference.sh           # 通用 T2AV
> bash scripts/inference_timbre.sh    # I2AV + 音色控制
> ```
> 输出落到 `eval_results/` 下。

### 1 · 环境准备（一次性）

```bash
git clone https://github.com/ernie-research/NAVA && cd NAVA

# Python 依赖
pip install torch torchvision torchaudio
pip install diffusers transformers accelerate safetensors einops scipy PyYAML tqdm sentencepiece
pip install flash-attn --no-build-isolation

# 一次性下载所有权重 —— 主 checkpoint + Wan2.2 VAE + T5 + LTX 音频 VAE
huggingface-cli download <NAVA-repo-id> --local-dir .
```

<details>
<summary><b>预期目录结构</b></summary>

```
NAVA/
├── NAVA.ckpt                                                    # 主 checkpoint（24 GB）
├── Wan2.2-TI2V-5B/
│   ├── Wan2.2_VAE.pth                                           # 2.7 GB
│   ├── models_t5_umt5-xxl-enc-bf16.pth                          # 11 GB
│   └── google/umt5-xxl/{spiece.model, tokenizer.json}
├── params/
│   └── LTX2/
│       ├── ltx-2.3-22b-dev_audio_vae.safetensors                # 348 MB
│       └── LICENSE                                              # LTX-2 社区许可证
└── configs/                                                     # 推理 YAML
```

LTX 音频 VAE 的 Python 代码已 vendor 到 `nava_src/vendor/ltx_core/`（见其 `NOTICE.md`），无需再单独 clone LTX-Video 仓库。ReDimNet 在首次运行时通过 `torch.hub` 下载。
</details>

### 2 · 一键推理（推荐，8 卡 SP）

仓库提供了两个端到端脚本，会内联构造 JSONL 并启动 SP=8 推理：

```bash
# 通用 T2AV（纯文本）
bash scripts/inference.sh

# I2AV + 音色控制（首帧图 + 参考音频）
bash scripts/inference_timbre.sh
```

通过环境变量覆盖默认值：

```bash
CKPT=/path/to/NAVA.ckpt OUT_DIR=eval_results/run1 bash scripts/inference.sh
TIMBRE_SCALE=3.0 SPK_WAV=/path/to/spk.wav    bash scripts/inference_timbre.sh
```

### 3 · 自定义批次 —— 写自己的 JSONL

每行一条提示词：

```jsonl
{"prompt": "一位男子在海边奔跑，镜头跟随。背景是海浪声和风声。"}
{"prompt": "两人对话<S>Hello<E><S>Hi there<E>", "spk_wavs": ["spk1.wav", "spk2.wav"]}
{"prompt": "镜头跟随主体...", "image_path": "/abs/path/first_frame.png"}
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `prompt` | 是 | 文本 caption（也兼容旧字段名 `text`） |
| `image_path` | 否 | 首帧图绝对路径 —— 自动为该样本启用 I2V |
| `spk_wavs` | 否 | 说话人参考 WAV 的绝对路径列表（最多 2 条） |

然后启动：

```bash
SETUPTOOLS_USE_DISTUTILS=stdlib torchrun \
    --nnodes=1 --nproc_per_node=8 \
    --master_addr=127.0.0.1 --master_port=29507 \
    inference_nava.py \
    --config configs/baseline_t2av_demo_mmdit_no_split_ltx_control_unipc.yaml \
    --ckpt NAVA.ckpt \
    --out_dir ./outputs \
    --data_format json --data_file my_prompts.jsonl \
    --width 1280 --height 704 --frames 37 --fps 24 \
    --steps 50 --save_sample --gen_turn 1 --use_sp
```

输出落到 `outputs/{save_path}-{gen_turn}_av.mp4`。对带音色控制的样本，还需加上 `--timbre_cfg --timbre_align_guidance_scale 3.0`。

#### 模式速查

| 目标 | JSONL 字段 | 额外 flag |
|---|---|---|
| 文本 → AV | `prompt` | — |
| 图像 → AV | `prompt` + `image_path` | （自动检测） |
| 音色控制语音 | `prompt` + `spk_wavs` | `--timbre_cfg --timbre_align_guidance_scale 3.0` |
| 9 秒视频 | 任意 | `--frames 55` |
| 单卡（更慢） | 任意 | 去掉 `--use_sp` |

### 4 · 提示词改写（短输入 / 英文输入推荐）

NAVA 在中文密集 caption 上训练，短提示或英文提示在推理前先改写一遍会显著受益。我们提供三种通路，共用同一套 system prompt 与采样 profile（保证输出风格一致），且 `<S>...<E>` 语音片段会被原样保留。

| 通路 | 后端 | 速度 | 适用场景 |
|---|---|---|---|
| **vLLM 批量服务**（`pe_src/`） | Qwen3-4B-Thinking-2507 由 vLLM 提供，异步 HTTP | **< 2 秒** / 条 | 离线批量 |
| **本地 transformers，单条**（`gradio_demo/rewrite_single.py`） | 同模型，进程内 | 40–80 秒 / 条 | 单次 CLI |
| **Gradio "Rewrite" 按钮** | 同上，托管在 Gradio 中 | 40–80 秒 / 条 | 交互式 UI |

```bash
# 批量路径：先起 vLLM 服务，再改写一个 prompt 列表
bash pe_src/start_server.sh --gpu 0 --low-footprint
python pe_src/rewrite.py -i prompts.txt -o prompts_rewritten.txt
```

### 5 · Gradio 网页 UI

交互式 demo，支持点击改写（Qwen3-4B）、首帧图上传、参考 WAV 上传：

```bash
bash gradio_demo/start_gradio.sh \
    --config configs/baseline_t2av_demo_mmdit_no_split_ltx_control_unipc.yaml \
    --ckpt NAVA.ckpt \
    --rewrite_model pe_src/Qwen3-4B-Thinking-2507 \
    --port 8000 --nproc 8
```

<details>
<summary><b>Debug 模式（不加载模型，仅 UI）</b></summary>

```bash
python gradio_demo/gradio_server.py --debug --port 8000
```
</details>

---

## 偏见、安全与滥用

NAVA 可基于参考图（`image_path`）和参考音频（`spk_wavs`）合成视频与语音。**未经本人同意**用其再现真实人物的相貌或声音，是被许可证禁止的，并且在你所在司法辖区内可能也违法。我们建议：

1. 仅使用**已获得授权**的参考素材。
2. **将生成内容明确标注为合成**。
3. 在再分发前应用**溯源 / 水印**机制。

---

## 引用

```bibtex
@article{nava2026,
  title   = {NAVA: Native Audio-Visual Alignment for Joint Audio-Video Generation},
  author  = {ERNIE Team},
  journal = {arXiv preprint},
  year    = {2026},
}
```

## 致谢

NAVA 站在优秀的上游工作之上：**Wan2.2-TI2V-5B**（视频主干与 VAE）、**LTX 2.3**（音频 VAE + 内置声码器）、**umt5-xxl**（文本编码器）、**ReDimNet**（说话人嵌入）。同时感谢开源 AV 生成社区 —— Ovi、MOVA、Davinci、LTX —— 公开了强力基线，让公平 benchmark 成为可能。

## 许可证与联系方式

以 **Apache-2.0** 协议发布。研究 / 商业合作请联系**百度公司 ERNIE 团队**。