mirror of
https://github.com/jamiepine/voicebox.git
synced 2026-09-15 12:50:42 -07:00
Makinde
d00e28ffda
Implements offline mode patch for API stability issues: - Add hf_offline_patch.py to monkey-patch huggingface_hub - Force cache-only lookups before mlx_audio imports - Create symlink from original Qwen repo to MLX community version when only MLX version is cached This fixes: - Issue #150: Internet required even with cached models - Issue #151: API crashes when HF network fails The patch ensures that if models are locally cached, no network requests are made to HuggingFace during speech generation.
59 lines
1.8 KiB
Markdown
59 lines
1.8 KiB
Markdown
# 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*
|