Upload README_zh.md with huggingface_hub

README_zh.md

@@ -0,0 +1,300 @@
+<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="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 团队**。