mirror of
https://github.com/jamiepine/voicebox.git
synced 2026-09-15 12:50:42 -07:00
James Pine
fe19a9ca47
- Add backend/STYLE_GUIDE.md covering formatting, imports, types, docstrings, comments, error handling, async, logging, and naming conventions - Add pyproject.toml with ruff linter/formatter config (ERA, FIX, isort, pyupgrade) - Extract generation service (Phase 3): unified run_generation() replaces three duplicated closures, serial queue moved to services/task_queue.py - Delete Makefile in favor of justfile; update all references - Add Python lint/format/test commands to justfile (check-python, fix-python, test) - Install ruff, pytest, pytest-asyncio as dev tools in setup-python - Update REFACTOR_PLAN.md with Phase 3 and Phase 7 completion
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: `just build`
|
|
2. Disconnect from internet
|
|
3. Try generating speech
|
|
4. Should work without network requests
|
|
|
|
## Build Instructions
|
|
|
|
```bash
|
|
# Install dependencies
|
|
just setup
|
|
|
|
# Build the app
|
|
just build
|
|
|
|
# Or build just the server
|
|
just 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*
|