Add unified model downloader and usage guides

README.md

@@ -118,7 +118,9 @@ All values are reported in the
 │   ├── model-*.safetensors       # Sharded model weights
 │   ├── config.json, *.py         # Model config and custom Transformers code
 │   └── assets/                   # Reference voice, Token2wav, demo audio
-├── assets/                   # Brand resources (logo)
+├── assets/                      # Brand resources (logo)
+├── config.yaml                  # Model names and download directory mapping
+├── download_models.py           # Unified Omni / Audio / all downloader
 ├── README.md
 ├── README_zh.md
 └── LICENSE
@@ -129,19 +131,71 @@ new output directory when repeating an experiment.
 
 ## 6. 🛠️ Installation
 
-Requires Python 3.10, CUDA, and FFmpeg. Download the repository (the two
-checkpoints live in its sub-directories) and install the Python dependencies:
+Running the inference examples requires Python 3.10, CUDA, and FFmpeg. First,
+install the download dependencies and fetch the unified downloader from this
+Hugging Face repository:
 
 ```bash
-huggingface-cli download inclusionAI/Realtime-Venus --local-dir .
-# or: modelscope download --model inclusionAI/Realtime-Venus --local_dir .
+python -m pip install 'huggingface_hub>=0.34' 'PyYAML>=6.0'
+hf download inclusionAI/Realtime-Venus download_models.py --local-dir .
+```
+
+Then choose the models to download:
+
+| `--model` | Download |
+| --- | --- |
+| `omni` | Realtime-Venus-Omni for audio-visual interaction |
+| `audio` | Realtime-Venus-Audio for audio understanding and conversation |
+| `all` | Both models |
+
+For example, download both models into the current directory:
+
+```bash
+python download_models.py --model all --local-dir .
+```
 
+Use `--model omni` or `--model audio` to download only the model you need.
+The downloader reads this repository's root `config.yaml` and downloads each
+selected model's complete directory, including weights, custom code, and
+assets. It saves a download manifest and uses the Hugging Face Hub's standard
+progress display and cache. Each download uses one repository revision.
+
+Install the inference dependencies after downloading. For Omni or `all`:
+
+```bash
 python -m pip install -r Realtime-Venus-Omni/requirements.txt
 ```
 
-All example paths below are relative to the downloaded repository's root
-directory. The examples load the local `Realtime-Venus-Omni/` and
-`Realtime-Venus-Audio/` checkpoints through Hugging Face Transformers.
+Audio uses the same published dependency list; it does not have a separate
+`requirements.txt`. If you downloaded only Audio, fetch that small file first
+without downloading the Omni weights:
+
+```bash
+hf download inclusionAI/Realtime-Venus Realtime-Venus-Omni/requirements.txt --local-dir .
+python -m pip install -r Realtime-Venus-Omni/requirements.txt
+```
+
+To download from Python instead, run this once from the directory containing
+`download_models.py`. It uses the same downloader as the command above:
+
+```python
+from download_models import download_models
+
+paths = download_models(model="omni", local_dir=".")  # "omni", "audio", or "all"
+model_dir = paths["omni"]  # pathlib.Path; use paths["audio"] for Audio
+```
+
+The inference examples below load the downloaded local model directories. Run
+them from the same directory; all asset and output paths are relative to it.
+
+As an independent alternative, the ModelScope CLI (installed separately) can
+download the entire mirror repository:
+
+```bash
+modelscope download --model inclusionAI/Realtime-Venus --local_dir .
+```
+
+This mirror command is separate from the Hugging Face downloader above.
 
 ## 7. 🎙️ Realtime-Venus-Omni Usages
 

README_zh.md

@@ -79,7 +79,9 @@
 │   ├── model-*.safetensors       # 分片模型权重
 │   ├── config.json, *.py         # 模型配置与自定义 Transformers 代码
 │   └── assets/                   # 参考音色、Token2wav、演示音频
-├── assets/                   # 品牌资源（标志）
+├── assets/                      # 品牌资源（标志）
+├── config.yaml                  # 模型名称与下载目录映射
+├── download_models.py           # Omni / Audio / all 统一下载入口
 ├── README.md
 ├── README_zh.md
 └── LICENSE
@@ -89,16 +91,60 @@
 
 ## 6. 🛠️ 安装
 
-运行示例需要 Python 3.10、CUDA 和 FFmpeg。先下载模型仓库，再安装 Python 依赖；两个模型的权重分别位于各自的子目录中：
+运行推理示例需要 Python 3.10、CUDA 和 FFmpeg。首先安装下载依赖，并从本 Hugging Face 仓库获取统一下载脚本：
 
 ```bash
-huggingface-cli download inclusionAI/Realtime-Venus --local-dir .
-# 或：modelscope download --model inclusionAI/Realtime-Venus --local_dir .
+python -m pip install 'huggingface_hub>=0.34' 'PyYAML>=6.0'
+hf download inclusionAI/Realtime-Venus download_models.py --local-dir .
+```
+
+然后选择需要下载的模型：
+
+| `--model` | 下载内容 |
+| --- | --- |
+| `omni` | 用于音视频交互的 Realtime-Venus-Omni |
+| `audio` | 用于音频理解与语音对话的 Realtime-Venus-Audio |
+| `all` | 两款模型 |
+
+例如，将两款模型下载到当前目录：
+
+```bash
+python download_models.py --model all --local-dir .
+```
 
+如只需一款模型，将参数改为 `--model omni` 或 `--model audio`。下载器读取本仓库根目录的 `config.yaml`，下载所选模型的完整子目录，包括权重、自定义代码和资源文件；同时保存下载清单，并使用 Hugging Face Hub 的标准进度显示与缓存。单次下载中的所有文件均来自同一个仓库版本。
+
+下载后安装推理依赖。选择 Omni 或 `all` 时运行：
+
+```bash
 python -m pip install -r Realtime-Venus-Omni/requirements.txt
 ```
 
-下文所有示例路径均相对于下载后的仓库根目录。示例通过 Hugging Face Transformers 加载本地的 `Realtime-Venus-Omni/` 与 `Realtime-Venus-Audio/` 模型。
+Audio 使用相同的已发布依赖清单，没有独立的 `requirements.txt`。如果只下载了 Audio，先单独获取这份小文件，无需下载 Omni 权重：
+
+```bash
+hf download inclusionAI/Realtime-Venus Realtime-Venus-Omni/requirements.txt --local-dir .
+python -m pip install -r Realtime-Venus-Omni/requirements.txt
+```
+
+也可以在包含 `download_models.py` 的目录中，通过 Python 完成一次下载准备。它与上述命令使用同一个下载入口：
+
+```python
+from download_models import download_models
+
+paths = download_models(model="omni", local_dir=".")  # 可选 "omni"、"audio" 或 "all"
+model_dir = paths["omni"]  # pathlib.Path；Audio 使用 paths["audio"]
+```
+
+下文推理示例直接加载下载后的本地模型目录。请在同一目录中运行，资源文件和输出路径均相对于当前目录。
+
+也可以独立使用 ModelScope CLI（需另行安装）下载整个镜像仓库：
+
+```bash
+modelscope download --model inclusionAI/Realtime-Venus --local_dir .
+```
+
+该镜像命令与上述 Hugging Face 下载器相互独立。
 
 ## 7. 🎙️ Realtime-Venus-Omni 使用方法
 

download_models.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""Download Realtime-Venus checkpoints using the model repository's manifest."""
+
+from __future__ import annotations
+
+import argparse
+import math
+import re
+from pathlib import Path, PurePosixPath
+
+import yaml
+from huggingface_hub import HfApi, hf_hub_download, snapshot_download
+
+
+REPO_ID = "inclusionAI/Realtime-Venus"
+MANIFEST = "config.yaml"
+MODEL_CHOICES = ("omni", "audio", "all")
+
+
+def _model_paths(manifest: object) -> dict[str, str]:
+    if not isinstance(manifest, dict) or manifest.get("name") != "Realtime-Venus":
+        raise ValueError("config.yaml must describe the Realtime-Venus repository.")
+    models = manifest.get("models")
+    if not isinstance(models, dict):
+        raise ValueError("config.yaml must contain a models mapping.")
+
+    paths = {}
+    for name in ("omni", "audio"):
+        entry = models.get(name)
+        value = entry.get("path") if isinstance(entry, dict) else None
+        if not isinstance(value, str) or not re.fullmatch(
+            r"[A-Za-z0-9_-][A-Za-z0-9._/-]*", value
+        ):
+            raise ValueError(f"Invalid directory for {name} in config.yaml.")
+        if any(part in ("", ".", "..") for part in value.split("/")):
+            raise ValueError(f"Invalid directory for {name} in config.yaml.")
+        paths[name] = value
+
+    omni, audio = (PurePosixPath(paths[name]) for name in ("omni", "audio"))
+    if omni == audio or omni in audio.parents or audio in omni.parents:
+        raise ValueError("The Omni and Audio directories must not overlap.")
+    return paths
+
+
+def _check_destination(root: Path, filename: str) -> Path:
+    """Keep downloaded files and Hub metadata inside the selected directory."""
+    relative = PurePosixPath(filename)
+    if relative.is_absolute() or any(p in ("", ".", "..") for p in filename.split("/")):
+        raise ValueError(f"Invalid repository file path: {filename!r}")
+    if "\\" in filename:
+        raise ValueError(f"Invalid repository file path: {filename!r}")
+    destination = root.joinpath(*relative.parts)
+    if not destination.resolve().is_relative_to(root):
+        raise ValueError(f"Download path leaves the destination directory: {filename}")
+    return destination
+
+
+def _verify_downloads(
+    root: Path,
+    filenames: list[str],
+    revision: str,
+    sizes: dict[str, int | None] | None = None,
+) -> None:
+    """Reject the Hub's offline fallback to files from an older revision.
+
+    In local-dir mode, huggingface_hub records the commit hash on the first
+    line of each .metadata file. Checking it avoids reporting an incomplete
+    or stale download as successful after a network failure.
+    """
+    for filename in filenames:
+        destination = _check_destination(root, filename)
+        metadata = _check_destination(
+            root, f".cache/huggingface/download/{filename}.metadata"
+        )
+        try:
+            with metadata.open(encoding="utf-8") as handle:
+                downloaded_revision = handle.readline().strip()
+                etag = handle.readline().strip()
+                timestamp = float(handle.readline().strip())
+            stat = destination.stat()
+            expected_size = (sizes or {}).get(filename)
+            valid = (
+                destination.is_file()
+                and downloaded_revision == revision
+                and bool(etag)
+                and math.isfinite(timestamp)
+                and stat.st_mtime <= timestamp + 1
+                and (expected_size is None or stat.st_size == expected_size)
+            )
+        except (OSError, ValueError):
+            valid = False
+        if not valid:
+            raise RuntimeError(
+                f"Could not confirm {filename} at revision {revision}. "
+                "Check the connection and rerun the same download command; "
+                "completed files will be reused."
+            )
+
+
+def download_models(
+    model: str = "all",
+    local_dir: str | Path = ".",
+    revision: str = "main",
+    max_workers: int = 8,
+    token: str | bool | None = None,
+) -> dict[str, Path]:
+    """Download omni, audio, or both, returning their local checkpoint paths.
+
+    The root config.yaml is downloaded and read before selecting model files.
+    All requests use one resolved commit. Existing up-to-date files are reused
+    by huggingface_hub; other local files and model directories are not removed.
+    """
+    if model not in MODEL_CHOICES:
+        raise ValueError(f"model must be one of {', '.join(MODEL_CHOICES)}")
+    if max_workers < 1:
+        raise ValueError("max_workers must be at least 1")
+
+    root = Path(local_dir).expanduser().resolve()
+    _check_destination(root, MANIFEST)
+    _check_destination(root, ".cache/huggingface")
+    _check_destination(root, f".cache/huggingface/download/{MANIFEST}.metadata")
+    _check_destination(root, f".cache/huggingface/download/{MANIFEST}.lock")
+    info = HfApi().model_info(
+        REPO_ID, revision=revision, token=token, files_metadata=True
+    )
+    commit = info.sha
+    if not commit:
+        raise RuntimeError(f"Could not resolve revision {revision!r}.")
+    sizes = {entry.rfilename: entry.size for entry in info.siblings or []}
+    print(f"Repository: {REPO_ID} @ {commit}", flush=True)
+    manifest_file = hf_hub_download(
+        repo_id=REPO_ID,
+        filename=MANIFEST,
+        revision=commit,
+        local_dir=root,
+        token=token,
+    )
+    _verify_downloads(root, [MANIFEST], commit, sizes)
+    with Path(manifest_file).open(encoding="utf-8") as handle:
+        paths = _model_paths(yaml.safe_load(handle))
+    selected = paths if model == "all" else {model: paths[model]}
+
+    available = set(sizes)
+    filenames = sorted(
+        filename
+        for filename in available
+        if any(filename.startswith(f"{path}/") for path in selected.values())
+    )
+    for name, path in selected.items():
+        if f"{path}/config.json" not in available:
+            raise ValueError(f"The manifest's {name} directory has no config.json: {path}")
+        print(f"{name}: {root / path}", flush=True)
+    for filename in filenames:
+        _check_destination(root, filename)
+        _check_destination(root, f".cache/huggingface/download/{filename}.metadata")
+        _check_destination(root, f".cache/huggingface/download/{filename}.lock")
+
+    # The manifest is already present. Fetch only the selected model directories
+    # so choosing Audio does not also download the Omni checkpoint.
+    snapshot_download(
+        repo_id=REPO_ID,
+        revision=commit,
+        local_dir=root,
+        allow_patterns=[f"{path}/*" for path in selected.values()],
+        max_workers=max_workers,
+        token=token,
+    )
+    _verify_downloads(root, filenames, commit, sizes)
+    return {name: root / path for name, path in selected.items()}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--model", choices=MODEL_CHOICES, default="all")
+    parser.add_argument("--local-dir", default=".", help="Destination root (default: current directory)")
+    parser.add_argument("--revision", default="main", help="Hub branch, tag, or commit (default: main)")
+    parser.add_argument("--max-workers", type=int, default=8, help="Concurrent file downloads (default: 8)")
+    args = parser.parse_args()
+    try:
+        paths = download_models(
+            model=args.model,
+            local_dir=args.local_dir,
+            revision=args.revision,
+            max_workers=args.max_workers,
+        )
+    except (OSError, ValueError, RuntimeError, yaml.YAMLError) as error:
+        parser.exit(1, f"Download failed: {error}\n")
+    for name, path in paths.items():
+        print(f"Ready: {name} -> {path}")
+
+
+if __name__ == "__main__":
+    main()