The open-source AI voice studio. Clone, dictate, create.
Fix: Prevent crashes when HuggingFace is unreachable
Makinded00e28ffda7d
diff --git a/PATCH_NOTES.md b/PATCH_NOTES.mdnew file mode 100644index 00000000..e5c08175--- /dev/null+++ b/PATCH_NOTES.md@@ -0,0 +1,58 @@+# Voicebox Offline Mode Fix++## Problem+Voicebox crashes when generating speech if HuggingFace is unreachable, even when models are fully cached locally.++**Root Cause:**+- Voicebox downloads `mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16` (MLX optimized version)+- But `mlx_audio.tts.load()` tries to fetch `config.json` from original repo `Qwen/Qwen3-TTS-12Hz-1.7B-Base`+- This network request fails → server crashes with `RemoteDisconnected`++**Related Issues:**+- Issue #150: "Internet connection required, even though models are downloaded?"+- Issue #151: "API Stability Issues: Model Loading Hangs and Server Crashes"++## Solution+Two-part fix:++### 1. Monkey-patch huggingface_hub (`backend/utils/hf_offline_patch.py`)+- Intercepts cache lookup functions+- Forces offline mode early (before mlx_audio imports)+- Adds debug logging for cache hits/misses++### 2. Symlink original repo to MLX version (`ensure_original_qwen_config_cached()`)+- When original `Qwen/Qwen3-TTS-12Hz-1.7B-Base` cache doesn't exist+- But MLX `mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16` does exist+- Creates a symlink so cache lookups succeed++## Files Changed+- `backend/backends/mlx_backend.py` - Added patch imports at top+- `backend/utils/hf_offline_patch.py` - New patch module++## Testing+To test this fix:+1. Build Voicebox from source: `make build`+2. Disconnect from internet+3. Try generating speech+4. Should work without network requests++## Build Instructions++```bash+# Install dependencies+pip install -r requirements.txt++# Build the app+make build++# Or build just the server+make build-server+```++## Notes+- The patch is applied automatically when `mlx_backend.py` is imported+- Set `VOICEBOX_OFFLINE_PATCH=0` to disable the patch+- The symlink approach works because the config.json is compatible between versions++---+*Patch contributed by community*diff --git a/backend/backends/mlx_backend.py b/backend/backends/mlx_backend.pyindex c4ecc090..52820938 100644--- a/backend/backends/mlx_backend.py+++ b/backend/backends/mlx_backend.py@@ -5,8 +5,15 @@ MLX backend implementation for TTS and STT using mlx-audio.from typing import Optional, List, Tupleimport asyncioimport numpy as np+import osfrom pathlib import Path+# PATCH: Import and apply offline patch BEFORE any huggingface_hub usage+# This prevents mlx_audio from making network requests when models are cached+from ..utils.hf_offline_patch import patch_huggingface_hub_offline, ensure_original_qwen_config_cached+patch_huggingface_hub_offline()+ensure_original_qwen_config_cached()+from . import TTSBackend, STTBackendfrom ..utils.cache import get_cache_key, get_cached_voice_prompt, cache_voice_promptfrom ..utils.audio import normalize_audio, load_audio@@ -159,15 +166,35 @@ class MLXTTSBackend:tracker_context = tracker.patch_download()tracker_context.__enter__()+ # PATCH: Force offline mode when model is already cached+ # This prevents crashes when HuggingFace is unreachable+ original_hf_hub_offline = os.environ.get("HF_HUB_OFFLINE")+ if is_cached:+ os.environ["HF_HUB_OFFLINE"] = "1"+ print(f"[PATCH] Model {model_size} is cached, forcing HF_HUB_OFFLINE=1 to avoid network requests")+# Import mlx_audio AFTER patching tqdmfrom mlx_audio.tts import load# Load MLX model (downloads automatically)try:self.model = load(model_path)+ except Exception as load_error:+ # If offline mode failed, try with network enabled as fallback+ if is_cached and "offline" in str(load_error).lower():+ print(f"[PATCH] Offline load failed, trying with network: {load_error}")+ os.environ.pop("HF_HUB_OFFLINE", None)+ self.model = load(model_path)+ else:+ raisefinally:# Exit the patch contexttracker_context.__exit__(None, None, None)+ # Restore original HF_HUB_OFFLINE setting+ if original_hf_hub_offline is not None:+ os.environ["HF_HUB_OFFLINE"] = original_hf_hub_offline+ else:+ os.environ.pop("HF_HUB_OFFLINE", None)# Only mark download as complete if we were tracking itif not is_cached:diff --git a/backend/utils/hf_offline_patch.py b/backend/utils/hf_offline_patch.pynew file mode 100644index 00000000..288ed040--- /dev/null+++ b/backend/utils/hf_offline_patch.py@@ -0,0 +1,100 @@+"""+Monkey patch for huggingface_hub to force offline mode with cached models.+This prevents mlx_audio from making network requests when models are already downloaded.+"""++import os+from pathlib import Path+from typing import Optional, Union+++def patch_huggingface_hub_offline():+ """+ Monkey-patch huggingface_hub to force offline mode.+ This must be called BEFORE importing mlx_audio.+ """+ try:+ import huggingface_hub+ from huggingface_hub import constants as hf_constants+ from huggingface_hub.file_download import _try_to_load_from_cache++ # Store original function+ original_try_load = _try_to_load_from_cache++ def _patched_try_to_load_from_cache(+ repo_id: str,+ filename: str,+ cache_dir: Union[str, Path, None] = None,+ revision: Optional[str] = None,+ repo_type: Optional[str] = None,+ ):+ """+ Patched version that forces offline mode.+ Returns None if not cached (instead of making network request).+ """+ # Always use the original function, but we're already in HF_HUB_OFFLINE mode+ result = original_try_load(+ repo_id=repo_id,+ filename=filename,+ cache_dir=cache_dir,+ revision=revision,+ repo_type=repo_type,+ )++ if result is None:+ # File not in cache - log this for debugging+ cache_path = Path(hf_constants.HF_HUB_CACHE) / f"models--{repo_id.replace('/', '--')}"+ print(f"[HF_PATCH] File not cached: {repo_id}/{filename}")+ print(f"[HF_PATCH] Expected at: {cache_path}")+ else:+ print(f"[HF_PATCH] Cache hit: {repo_id}/{filename}")++ return result++ # Replace the function+ import huggingface_hub.file_download as fd+ fd._try_to_load_from_cache = _patched_try_to_load_from_cache++ print("[HF_PATCH] huggingface_hub patched for offline mode")++ except ImportError:+ print("[HF_PATCH] huggingface_hub not found, skipping patch")+ except Exception as e:+ print(f"[HF_PATCH] Error patching huggingface_hub: {e}")+++def ensure_original_qwen_config_cached():+ """+ The MLX community model is based on the original Qwen model.+ mlx_audio may try to fetch config from the original repo.+ We need to ensure that config is available in the cache.+ """+ from huggingface_hub import constants as hf_constants++ # Original Qwen model that mlx_audio might reference+ original_repo = "Qwen/Qwen3-TTS-12Hz-1.7B-Base"+ mlx_repo = "mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16"++ cache_dir = Path(hf_constants.HF_HUB_CACHE)++ original_path = cache_dir / f"models--{original_repo.replace('/', '--')}"+ mlx_path = cache_dir / f"models--{mlx_repo.replace('/', '--')}"++ # If original repo cache doesn't exist but MLX does, create a symlink or copy config+ if not original_path.exists() and mlx_path.exists():+ print(f"[HF_PATCH] Original repo not cached, but MLX version is")+ print(f"[HF_PATCH] Creating symlink from {original_repo} -> {mlx_repo}")++ try:+ # Create a symlink so the cache lookup succeeds+ original_path.parent.mkdir(parents=True, exist_ok=True)+ original_path.symlink_to(mlx_path, target_is_directory=True)+ print(f"[HF_PATCH] Symlink created successfully")+ except Exception as e:+ print(f"[HF_PATCH] Could not create symlink: {e}")+++# Auto-apply patch when module is imported+if os.environ.get("VOICEBOX_OFFLINE_PATCH", "1") != "0":+ patch_huggingface_hub_offline()+ ensure_original_qwen_config_cached()