Add vLLM-Omni library info to Hugging Face Hub requests (#5381)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Co-authored-by: Hongsheng Liu <liuhongsheng4@huawei.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

vllm_omni/model_executor/models/audex/checkpoint.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Audex checkpoint layout preparation.
 
 The nvidia/Nemotron-Labs-Audex-2B repo deduplicates weights: the
@@ -57,12 +57,12 @@ def _download_audiogen_index(model: str) -> str:
     metadata round trip per stage-engine boot; a cache miss falls back to
     the network.
     """
-    from huggingface_hub import hf_hub_download
+    from vllm_omni.transformers_utils.repo_utils import hf_api
 
     try:
-        return hf_hub_download(model, _AUDIOGEN_INDEX_FILE, local_files_only=True)
+        return hf_api().hf_hub_download(model, _AUDIOGEN_INDEX_FILE, local_files_only=True)
     except Exception:
-        return hf_hub_download(model, _AUDIOGEN_INDEX_FILE)
+        return hf_api().hf_hub_download(model, _AUDIOGEN_INDEX_FILE)
 
 
 def _dedup_shard_patterns(model: str) -> list[str]:
@@ -111,13 +111,13 @@ def ensure_audex_snapshot(model: str, profile: str = "tts") -> str:
     if profile in ("tts", "tta"):
         patterns += _dedup_shard_patterns(model)
 
-    from huggingface_hub import snapshot_download
+    from vllm_omni.transformers_utils.repo_utils import hf_api
 
     try:
-        return snapshot_download(model, allow_patterns=patterns)
+        return hf_api().snapshot_download(model, allow_patterns=patterns)
     except Exception as download_exc:
         try:
-            return snapshot_download(model, allow_patterns=patterns, local_files_only=True)
+            return hf_api().snapshot_download(model, allow_patterns=patterns, local_files_only=True)
         except Exception:
             raise RuntimeError(
                 f"Could not resolve the Audex repo {model!r} (profile {profile!r}): the download "
@@ -135,13 +135,13 @@ def ensure_xcodec1_snapshot(model: str | None) -> str:
     if os.path.isdir(model):
         return model
 
-    from huggingface_hub import snapshot_download
+    from vllm_omni.transformers_utils.repo_utils import hf_api
 
     try:
-        return snapshot_download(model)
+        return hf_api().snapshot_download(model)
     except Exception as download_exc:
         try:
-            return snapshot_download(model, local_files_only=True)
+            return hf_api().snapshot_download(model, local_files_only=True)
         except Exception:
             raise RuntimeError(
                 f"Could not resolve the XCodec1 checkpoint {model!r}: the download failed and "

vllm_omni/model_executor/models/bagel/bagel.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from collections.abc import Iterable, Mapping, Sequence
 from math import isqrt
 from typing import Any
@@ -122,9 +125,9 @@ class OmniBagelProcessingInfo(BaseProcessingInfo):
             if p.is_dir():
                 index_path = p / "model.safetensors.index.json"
             else:
-                from huggingface_hub import hf_hub_download
+                from vllm_omni.transformers_utils.repo_utils import hf_api
 
-                index_path = Path(hf_hub_download(model_name, "model.safetensors.index.json"))
+                index_path = Path(hf_api().hf_hub_download(model_name, "model.safetensors.index.json"))
 
             if not index_path.exists():
                 return

vllm_omni/model_executor/models/cosyvoice3/cosyvoice3.py

@@ -10,7 +10,6 @@ import numpy as np
 import onnxruntime
 import torch
 import torch.nn as nn
-from huggingface_hub import snapshot_download
 from scipy.signal import resample_poly
 from transformers import Qwen2Config
 from transformers.feature_extraction_utils import BatchFeature
@@ -52,6 +51,7 @@ from vllm_omni.model_executor.models.cosyvoice3.utils import (
 from vllm_omni.model_executor.models.output_templates import OmniOutput
 from vllm_omni.platforms import current_omni_platform
 from vllm_omni.transformers_utils.configs.cosyvoice3 import CosyVoice3Config
+from vllm_omni.transformers_utils.repo_utils import hf_api
 from vllm_omni.utils.speaker_cache import get_speaker_cache
 
 logger = init_logger(__name__)
@@ -137,7 +137,7 @@ class CosyVoice3MultiModalProcessor(BaseMultiModalProcessor[CosyVoice3MultiModal
         """Build the per-model runtime components once (cached process-wide)."""
         # If model_dir is an HF repo ID (not a local path), resolve to cache.
         if not os.path.isdir(model_dir):
-            model_dir = snapshot_download(model_dir)
+            model_dir = hf_api().snapshot_download(model_dir)
 
         tokenizer = get_qwen_tokenizer(
             token_path=os.path.join(model_dir, config.qwen_pretrain_path),
@@ -463,7 +463,7 @@ class CosyVoice3Model(
         self.model_stage = vllm_config.model_config.model_stage
         model_dir = vllm_config.model_config.model
         if not os.path.isdir(model_dir):
-            model_dir = snapshot_download(model_dir)
+            model_dir = hf_api().snapshot_download(model_dir)
         self.model_dir = model_dir
         self.model = None
         if self.model_stage == "cosyvoice3_talker":
@@ -918,7 +918,7 @@ class CosyVoice3Model(
         repo = getattr(self.config, "flow_estimator_onnx_repo", None)
         if repo:
             try:
-                fetched_dir = snapshot_download(repo, allow_patterns=[fp16_name])
+                fetched_dir = hf_api().snapshot_download(repo, allow_patterns=[fp16_name])
                 fetched = os.path.join(fetched_dir, fp16_name)
                 if os.path.exists(fetched):
                     return fetched

vllm_omni/model_executor/models/covo_audio/covo_audio_code2wav.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 # Copyright 2026 Tencent.
 import os
 from collections.abc import Iterable
@@ -25,9 +28,9 @@ class CovoAudioCode2WavForConditionalGeneration(nn.Module, SupportsPP):
         if os.path.isdir(model_name):
             model_path = model_name
         else:
-            from huggingface_hub import snapshot_download
+            from vllm_omni.transformers_utils.repo_utils import hf_api
 
-            model_path = snapshot_download(model_name)
+            model_path = hf_api().snapshot_download(model_name)
         token2wav_path = os.path.join(model_path, "token2wav")
 
         code2wav_config = CovoAudioCode2WavConfig()

vllm_omni/model_executor/models/dots_tts/dots_tts_talker.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """dots.tts talker — vLLM-native AR base LM + audio side path.
 
 Mirrors upstream rednote-hilab/dots.tts (pinned @ a393d2e):
@@ -516,9 +516,9 @@ class DotsTTSForConditionalGeneration(nn.Module):
         if os.path.exists(local):
             return local
         try:
-            from huggingface_hub import hf_hub_download
+            from vllm_omni.transformers_utils.repo_utils import hf_api
 
-            return hf_hub_download(
+            return hf_api().hf_hub_download(
                 repo_id=model_arg,
                 filename="latent_stats.pt",
                 local_files_only=True,

vllm_omni/model_executor/models/dynin_omni/dynin_omni_common.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from __future__ import annotations
 
 import hashlib
@@ -20,9 +23,9 @@ from vllm.logger import init_logger
 logger = init_logger(__name__)
 
 try:
-    from huggingface_hub import snapshot_download
+    from vllm_omni.transformers_utils.repo_utils import hf_api
 except Exception:  # pragma: no cover
-    snapshot_download = None
+    hf_api = None
 
 
 class DetokTarget(IntEnum):
@@ -397,13 +400,13 @@ def _find_dynin_config_under_root(root: Path) -> Path | None:
 
 @lru_cache(maxsize=16)
 def _resolve_dynin_config_from_hf_repo(repo_id: str) -> str | None:
-    if not _looks_like_hf_repo_id(repo_id) or snapshot_download is None:
+    if not _looks_like_hf_repo_id(repo_id) or hf_api is None:
         return None
 
     try:
         snapshot_dir = (
             Path(
-                snapshot_download(
+                hf_api().snapshot_download(
                     repo_id=repo_id,
                     repo_type="model",
                     allow_patterns=list(_DYNIN_CONFIG_CANDIDATE_RELPATHS),
@@ -719,7 +722,7 @@ def _resolve_remote_snapshot_dir(
     if source_path.is_dir():
         return str(source_path.resolve())
 
-    if snapshot_download is None:
+    if hf_api is None:
         raise RuntimeError("huggingface_hub is required to load remote code.")
 
     kwargs: dict[str, Any] = {
@@ -732,10 +735,10 @@ def _resolve_remote_snapshot_dir(
         kwargs["revision"] = revision
 
     try:
-        return str(snapshot_download(**kwargs))
+        return str(hf_api().snapshot_download(**kwargs))
     except TypeError:
         kwargs.pop("local_files_only", None)
-        return str(snapshot_download(**kwargs))
+        return str(hf_api().snapshot_download(**kwargs))
 
 
 def _ensure_remote_package(snapshot_dir: str) -> str:

vllm_omni/model_executor/models/dynin_omni/dynin_omni_token2audio.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from __future__ import annotations
 
 import os
@@ -80,7 +83,7 @@ def _ensure_remote_s2u_vendor_root(
             return str(existing_path)
 
     try:
-        from huggingface_hub import snapshot_download
+        from vllm_omni.transformers_utils.repo_utils import hf_api
     except Exception as e:
         logger.warning("huggingface_hub unavailable; cannot fetch s2u_vendor from %s: %s", repo_id, e)
         return None
@@ -91,7 +94,7 @@ def _ensure_remote_s2u_vendor_root(
 
     for revision in revisions:
         try:
-            snapshot_dir = snapshot_download(
+            snapshot_dir = hf_api().snapshot_download(
                 repo_id=repo_id,
                 revision=revision,
                 allow_patterns=["s2u_vendor/**"],
@@ -99,7 +102,7 @@ def _ensure_remote_s2u_vendor_root(
             )
         except TypeError:
             try:
-                snapshot_dir = snapshot_download(
+                snapshot_dir = hf_api().snapshot_download(
                     repo_id=repo_id,
                     revision=revision,
                     allow_patterns=["s2u_vendor/**"],

vllm_omni/model_executor/models/glm_tts/glm_tts.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """GLM-TTS AR Model (Stage 0): Text → Speech Tokens.
 
 Based on Llama architecture, generates speech token sequences from input text.
@@ -113,9 +113,9 @@ def resolve_glm_tts_tokenizer_path(model_name_or_path: Any) -> str:
                 return candidate
         return model_path
 
-    from huggingface_hub import snapshot_download
+    from vllm_omni.transformers_utils.repo_utils import hf_api
 
-    local_dir = snapshot_download(
+    local_dir = hf_api().snapshot_download(
         model_path,
         allow_patterns=[
             f"{_GLM_TTS_TOKENIZER_SUBDIR}/tokenizer*",
@@ -169,9 +169,9 @@ def resolve_glm_tts_model_dir(
         except Exception:
             pass
 
-    from huggingface_hub import snapshot_download
+    from vllm_omni.transformers_utils.repo_utils import hf_api
 
-    return snapshot_download(model_name_or_path)
+    return hf_api().snapshot_download(model_name_or_path)
 
 
 def _first_glm_tts_value(value: Any) -> Any:

vllm_omni/model_executor/models/higgs_audio_v2/higgs_audio_v2_code2wav.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Stage 1 (codec decoder) for higgs-audio v2.
 
 Two surfaces exposed:
@@ -231,9 +231,9 @@ class HiggsAudioV2Code2Wav(nn.Module):
                 if os.path.isfile(os.path.join(candidate, "config.json")):
                     return candidate
 
-        from huggingface_hub import snapshot_download
+        from vllm_omni.transformers_utils.repo_utils import hf_api
 
-        return snapshot_download(repo_id=repo_id)
+        return hf_api().snapshot_download(repo_id=repo_id)
 
     # ------------------------------------------------------ direct decode API
     @torch.inference_mode()

vllm_omni/model_executor/models/higgs_audio_v2/higgs_audio_v2_tokenizer.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """TTS prompt builder + scope validators for higgs-audio v2.
 
 vllm-omni's higgs path supports two request shapes:
@@ -248,9 +248,9 @@ def _load_audio_tokenizer():
 
     audio_tokenizer_dir = _resolve_audio_tokenizer_dir()
     if audio_tokenizer_dir is None:
-        from huggingface_hub import snapshot_download
+        from vllm_omni.transformers_utils.repo_utils import hf_api
 
-        repo_path = snapshot_download(
+        repo_path = hf_api().snapshot_download(
             _K2_OMNIVOICE_REPO,
             allow_patterns=[f"{_K2_OMNIVOICE_SUBDIR}/*"],
         )

vllm_omni/model_executor/models/indextts2/preprocess_utils.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """External model loading, audio I/O, and emotion conditioning for IndexTTS2."""
 
 from __future__ import annotations
@@ -171,9 +171,10 @@ def load_semantic_codec(
         codec.load_state_dict(state, strict=False)
     else:
         import safetensors.torch
-        from huggingface_hub import hf_hub_download
 
-        ckpt_path = hf_hub_download("amphion/MaskGCT", filename="semantic_codec/model.safetensors")
+        from vllm_omni.transformers_utils.repo_utils import hf_api
+
+        ckpt_path = hf_api().hf_hub_download("amphion/MaskGCT", filename="semantic_codec/model.safetensors")
         safetensors.torch.load_model(codec, ckpt_path)
     _freeze(codec.to(device=device, dtype=torch.float32))
     _semantic_codec_cache[cache_key] = codec
@@ -198,9 +199,11 @@ def load_campplus(model_path: str, device: torch.device):
         if ckpt_path is not None:
             break
     if ckpt_path is None:
-        from huggingface_hub import hf_hub_download
+        if os.path.isdir(model_path):
+            raise FileNotFoundError(f"IndexTTS CAMPPlus checkpoint is missing from local bundle {model_path!r}")
+        from vllm_omni.transformers_utils.repo_utils import hf_api
 
-        ckpt_path = hf_hub_download("funasr/campplus", filename="campplus_cn_common.bin")
+        ckpt_path = hf_api().hf_hub_download("funasr/campplus", filename="campplus_cn_common.bin")
     state = torch.load(ckpt_path, map_location="cpu", weights_only=True)
     campplus.load_state_dict(state, strict=False)
     _freeze(campplus.to(device=device, dtype=torch.float32))

vllm_omni/model_executor/models/indextts2/s2mel/modules/bigvgan.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 # Copyright (c) 2024 NVIDIA CORPORATION.
 #   Licensed under the MIT license.
 
@@ -9,13 +12,14 @@ import os
 
 import torch
 import torch.nn as nn
-from huggingface_hub import PyTorchModelHubMixin, hf_hub_download
+from huggingface_hub import PyTorchModelHubMixin
 from torch.nn import Conv1d, ConvTranspose1d
 from torch.nn.utils import remove_weight_norm, weight_norm
 
 from vllm_omni.model_executor.models.common.alias_free_activation import AliasFreeActivation1d
 from vllm_omni.model_executor.models.common.snake_activation import Snake, SnakeBeta
 from vllm_omni.model_executor.models.indextts2.s2mel.modules.commons import AttrDict
+from vllm_omni.transformers_utils.repo_utils import hf_api
 
 # ---------------------------------------------------------------------------
 # Helpers (inlined from env.py / utils.py)
@@ -328,7 +332,7 @@ class BigVGAN(
         def _resolve(filename):
             if os.path.isdir(model_id):
                 return os.path.join(model_id, filename)
-            return hf_hub_download(
+            return hf_api().hf_hub_download(
                 repo_id=model_id,
                 filename=filename,
                 **{

vllm_omni/model_executor/models/indextts2/tokenizer_v2_5.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """IndexTTS 2.5 multilingual tiktoken vocabulary.
 
 The vocabulary layout mirrors the official IndexTTS 2.5 tokenizer: 58,836
@@ -234,9 +234,9 @@ def resolve_indextts25_tokenizer_file(
         return str(model_path)
 
     try:
-        from huggingface_hub import hf_hub_download
+        from vllm_omni.transformers_utils.repo_utils import hf_api
 
-        return hf_hub_download(repo_id=model_dir, filename=tokenizer_file)
+        return hf_api().hf_hub_download(repo_id=model_dir, filename=tokenizer_file)
     except Exception as exc:
         raise FileNotFoundError(
             f"Could not resolve IndexTTS 2.5 tokenizer {tokenizer_file!r} from {model_dir!r}"

vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_code2wav.py

@@ -39,9 +39,9 @@ def _resolve_model_dir(model_ref: str, revision: str | None = None) -> str:
     """
     if Path(model_ref).is_dir():
         return model_ref
-    from huggingface_hub import snapshot_download
+    from vllm_omni.transformers_utils.repo_utils import hf_api
 
-    return snapshot_download(model_ref, revision=revision, allow_patterns=["assets/*"])
+    return hf_api().snapshot_download(model_ref, revision=revision, allow_patterns=["assets/*"])
 
 
 def _batch_error(reason: str, **details: Any) -> RuntimeError:

vllm_omni/model_executor/models/omnivoice/omnivoice.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """
 OmniVoice model for vLLM-Omni two-stage TTS pipeline.
 
@@ -487,9 +487,9 @@ class OmniVoiceModel(
         if os.path.isdir(model_dir):
             return model_dir
         # HF hub model ID — resolve to local cache
-        from huggingface_hub import snapshot_download
+        from vllm_omni.transformers_utils.repo_utils import hf_api
 
-        return snapshot_download(model_dir)
+        return hf_api().snapshot_download(model_dir)
 
     def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
         try:

vllm_omni/model_executor/models/personaplex/personaplex_mimi.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Streaming Mimi codec for PersonaPlex (moshi-free).
 
 Frame-clocked duplex needs a codec that encodes/decodes exactly one 80 ms frame
@@ -288,10 +288,11 @@ class PersonaPlexMimiCodec(nn.Module):
 
     def __init__(self, hf_repo: str = DEFAULT_HF_REPO, checkpoint: str | None = None, device: str = "cuda") -> None:
         super().__init__()
-        from huggingface_hub import hf_hub_download
         from safetensors.torch import load_file
         from transformers import MimiConfig, MimiModel
 
+        from vllm_omni.transformers_utils.repo_utils import hf_api
+
         self.device = torch.device(device)
 
         # The PersonaPlex repo ships the reference mimi checkpoint in the moshi
@@ -300,7 +301,7 @@ class PersonaPlexMimiCodec(nn.Module):
         # transformer stacks remain absent because the streaming implementations
         # below replace them with the checkpoint's fused QKV layout.
         if checkpoint is None:
-            checkpoint = hf_hub_download(
+            checkpoint = hf_api().hf_hub_download(
                 "nvidia/personaplex-7b-v1",
                 "tokenizer-e351c8d8-checkpoint125.safetensors",
             )

vllm_omni/model_executor/models/step_audio2/step_audio2_token2wav.py

@@ -461,9 +461,9 @@ class StepAudio2Token2WavForConditionalGeneration(nn.Module, SupportsPP):
         if model_path is None:
             # Resolve HF repo names to local cache path
             if not os.path.isdir(model_name_or_path):
-                from huggingface_hub import snapshot_download
+                from vllm_omni.transformers_utils.repo_utils import hf_api
 
-                model_name_or_path = snapshot_download(model_name_or_path)
+                model_name_or_path = hf_api().snapshot_download(model_name_or_path)
             model_path = f"{model_name_or_path}/token2wav"
 
         float16 = getattr(self.config, "token2wav_float16", False)

vllm_omni/model_executor/models/voxtral_tts/voxtral_tts.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from collections.abc import Iterable, Mapping
 from dataclasses import replace
 from functools import cached_property
@@ -6,7 +9,6 @@ from pathlib import Path
 import regex as re
 import torch
 import torch.nn as nn
-from huggingface_hub import hf_hub_download
 from vllm.config import VllmConfig
 from vllm.logger import init_logger
 from vllm.model_executor.models.interfaces import SupportsMultiModal
@@ -28,6 +30,7 @@ from vllm_omni.model_executor.models.voxtral_tts.voxtral_tts_audio_generation im
     VoxtralTTSMultiModalProcessor,
     VoxtralTTSProcessingInfo,
 )
+from vllm_omni.transformers_utils.repo_utils import hf_api
 
 logger = init_logger(__name__)
 
@@ -133,7 +136,7 @@ class VoxtralTTSForConditionalGeneration(
                 self.voice_to_embedding = {}
                 for sid in speaker_id:
                     if self.is_hf_model:
-                        path = hf_hub_download(repo_id=self.repo_id, filename=f"voice_embedding/{sid}.pt")
+                        path = hf_api().hf_hub_download(repo_id=self.repo_id, filename=f"voice_embedding/{sid}.pt")
                     else:
                         path = Path(self.repo_id) / "voice_embedding" / f"{sid}.pt"
                     if Path(path).exists():