Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

docs: set HF_HOME=/.cache in whisperx-asr compose snippets so the pyannote diarization model persists in the cache volume (whisperx-asr-service#24)

Murtaza Nasirc6cee21166d4
diff --git a/docs/admin-guide/whisperx-setup.md b/docs/admin-guide/whisperx-setup.md
index 54996321..5ff85e36 100644
--- a/docs/admin-guide/whisperx-setup.md
+++ b/docs/admin-guide/whisperx-setup.md
@@ -358,6 +358,8 @@ curl http://ASR_BASE_URL/health
- Accept model agreements again
- Check logs for specific errors
+If diarization breaks specifically after enabling `HF_HUB_OFFLINE=1`, the container is missing `HF_HOME=/.cache` and the diarization model was never stored in the cache volume. See [Diarization Fails After Enabling Offline Mode](../troubleshooting.md#diarization-fails-after-enabling-offline-mode-whisperx-asr-service).
+
## Upgrading
### Update WhisperX Service
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 0c7c535b..41ca4e0f 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -609,6 +609,8 @@ docker compose up -d
curl http://localhost:9000/health
```
+Prebuilt images are also published per release, so you can pull instead of building: `learnedmachine/whisperx-asr-service:latest` covers Pascal through Hopper GPUs as well as CPU, and `learnedmachine/whisperx-asr-service:blackwell` covers RTX 50xx cards (the plain `:blackwell` tag is available as of v0.4.0). To use one, replace the `build:` section in the compose snippet below with the corresponding `image:` line.
+
See the [WhisperX ASR Service README](https://github.com/murtaza-nasir/whisperx-asr-service#readme) for detailed configuration options, troubleshooting, and performance tuning.
!!! warning "PyTorch 2.6 Compatibility"
@@ -657,7 +659,18 @@ services:
- COMPUTE_TYPE=float16
- BATCH_SIZE=16
- HF_TOKEN=your_huggingface_token_here
+ # Store all Hugging Face downloads (including the pyannote diarization
+ # model) in the cache volume below. Without this, the diarization model
+ # is cached inside the container filesystem and is lost whenever the
+ # container is recreated.
+ - HF_HOME=/.cache
- TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=true # Required for PyTorch 2.6+
+ # Uncomment after one successful online run with diarization to run
+ # fully offline (models must already be in the cache volume):
+ # - HF_HUB_OFFLINE=1
+ # Unload idle models from VRAM after this many seconds
+ # (0 = keep resident, the default):
+ # - MODEL_KEEP_ALIVE_SECONDS=3600
deploy:
resources:
reservations:
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 9991755e..a9089307 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -175,6 +175,7 @@ whisper-asr:
image: learnedmachine/whisperx-asr-service:latest
environment:
- TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=true
+ - HF_HOME=/.cache # keep model downloads in the cache volume
# ... your other environment variables
```
@@ -189,6 +190,21 @@ docker compose up -d whisper-asr
For more details, see the [WhisperX issue discussion](https://github.com/m-bain/whisperX/issues/1304).
+### Diarization Fails After Enabling Offline Mode (WhisperX ASR Service)
+
+If speaker diarization worked while online but fails with an error like this after setting `HF_HUB_OFFLINE=1`:
+
+```
+Speaker diarization failed: An error happened while trying to locate the file
+on the Hub and we cannot find the requested files in the local cache.
+```
+
+the pyannote diarization model was never stored in the cache volume. Unless `HF_HOME` is set, Hugging Face downloads go to `/root/.cache/huggingface` inside the container filesystem, so the model silently disappears whenever the container is recreated. Recreating the container is exactly what enabling offline mode requires, which is when the missing model surfaces.
+
+**Solution**: Add `HF_HOME=/.cache` to the ASR container's environment so it points at the mounted cache volume, remove `HF_HUB_OFFLINE=1` for now, and recreate the container. Run one transcription with diarization while online so the model downloads into the volume, then re-enable `HF_HUB_OFFLINE=1`. You can confirm the model is in the volume by checking for `/.cache/hub/models--pyannote--speaker-diarization-community-1` inside the container.
+
+Images newer than v0.4.0 of the WhisperX ASR service set `HF_HOME=/.cache` by default, so this only affects v0.4.0 and earlier deployments configured without it.
+
### WhisperX Shows UNKNOWN_SPEAKER
If WhisperX only shows "UNKNOWN_SPEAKER" instead of numbered speakers (SPEAKER_00, SPEAKER_01, etc.), check these common issues: