Skip to content

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

Python

Document EMBEDDING_BASE_URL API mode in inquire-mode, vector-store, troubleshooting, and changelog entries

Murtaza Nasirc6202c96d2d2
diff --git a/README.md b/README.md
index 839f3a50..db938c13 100644
--- a/README.md
+++ b/README.md
@@ -184,7 +184,7 @@ Complete documentation is available at **[murtaza-nasir.github.io/speakr](https:
**Per-Recording Model Selection, API v1 Parity, and Backlog Cleanup**
- **Per-Upload / Per-Tag / Per-Folder Transcription Model** - Set `TRANSCRIPTION_MODELS_AVAILABLE` and the upload form, in-app reprocess modal, and tag/folder edit forms all gain a model dropdown so different recordings can use different transcription models
-- **Configurable Embedding Model** - New `EMBEDDING_MODEL` env var lets you swap `all-MiniLM-L6-v2` for any sentence-transformers model; Speakr warns at startup if the model changes after embeddings are already stored
+- **Configurable Embedding Model** - New `EMBEDDING_MODEL` env var swaps the default `all-MiniLM-L6-v2` for any sentence-transformers model. `EMBEDDING_BASE_URL`, `EMBEDDING_API_KEY`, and `EMBEDDING_DIMENSIONS` route embeddings through an OpenAI-compatible API instead (vLLM, OpenRouter, OpenAI, Together, etc.). Speakr warns at startup if the model or provider changes after embeddings are already stored.
- **Mistral Voxtral Chunking** - `MISTRAL_ENABLE_CHUNKING=true` opts the Mistral connector into app-side chunking for very long meeting recordings that would otherwise time out near Voxtral's 3-hour limit
- **API v1 Parity** - `/api/v1/recordings` and `/api/v1/recordings/{id}` now expose `audio_duration`, transcription/summarization durations, folder, events, and `deletion_exempt` for companion-app integrations
diff --git a/docs/admin-guide/vector-store.md b/docs/admin-guide/vector-store.md
index 0fe8dc35..76409f24 100644
--- a/docs/admin-guide/vector-store.md
+++ b/docs/admin-guide/vector-store.md
@@ -15,11 +15,11 @@ This approach goes beyond simple keyword matching. The system understands that "
## The Embedding Model
-Your Speakr instance uses the all-MiniLM-L6-v2 model, shown prominently in the interface. This model generates 384-dimensional vectors - imagine each chunk of text mapped to a point in 384-dimensional space where similar meanings cluster together.
+By default, Speakr uses the all-MiniLM-L6-v2 model. It generates 384-dimensional vectors and runs efficiently on CPU-only systems, which makes advanced search accessible without GPU infrastructure. The default is suitable for English-dominant deployments and small-to-medium recording libraries.
-This specific model was chosen carefully. Larger models exist with better accuracy, but they require GPUs and significant computational resources. The MiniLM model runs efficiently on CPU-only systems, making advanced search accessible without expensive infrastructure. It processes text quickly, understands context well, and produces compact embeddings that don't overwhelm your storage.
+For larger libraries, multilingual content, or higher-quality semantic matching, the `EMBEDDING_MODEL` environment variable accepts any sentence-transformers identifier (`all-mpnet-base-v2`, `paraphrase-multilingual-MiniLM-L12-v2`, and similar). For deployments that prefer not to load embedding models locally, setting `EMBEDDING_BASE_URL` switches Speakr to an OpenAI-compatible HTTP endpoint, allowing the use of providers such as OpenAI, OpenRouter, or a self-hosted vLLM server. See [Model Configuration → Configurable Embedding Model](model-configuration.md#configurable-embedding-model) for the full set of supported environment variables and migration guidance.
-The model works best with English text, as that's what dominated its training data. Other languages may work with varying success, but English content will always produce the most reliable results. This limitation is a trade-off for the model's efficiency and accessibility.
+Changing the model or provider on an existing instance produces vectors that do not match what is stored. Speakr records the active configuration in `system_setting` on first run and logs a warning at startup if it changes. After such a change, reprocess recordings to rebuild the index.
## Processing Status Overview
diff --git a/docs/index.md b/docs/index.md
index 6de4a184..33a16815 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,7 +10,7 @@ Speakr is a powerful self-hosted transcription platform that helps you capture,
**Per-upload model selection, embedding model env var, Mistral chunking, API v1 parity, and bug fixes**
- **Per-Upload / Per-Tag / Per-Folder Transcription Model** - Configurable model dropdown via `TRANSCRIPTION_MODELS_AVAILABLE`
- - **Configurable Embedding Model** - `EMBEDDING_MODEL` env var for swapping `all-MiniLM-L6-v2`
+ - **Configurable Embedding Model** - `EMBEDDING_MODEL` for local sentence-transformers, or `EMBEDDING_BASE_URL` to offload to an OpenAI-compatible provider
- **Mistral Voxtral Chunking** - `MISTRAL_ENABLE_CHUNKING=true` for long meeting recordings
- **API v1 Parity** - `audio_duration`, durations, folder, events, and deletion_exempt now exposed
- **Bug Fixes** - Reprocess now respects tag/folder hotwords; legacy "français" language values normalized; Cyrillic title generation no longer leaks unicode escapes
@@ -148,7 +148,7 @@ Learn more about [audio synchronization features](user-guide/transcripts.md#audi
!!! info "Version 0.8.16-alpha - Per-Recording Model Selection & Backlog Cleanup"
- **Per-Upload / Per-Tag / Per-Folder Transcription Model** - Set `TRANSCRIPTION_MODELS_AVAILABLE` to expose a model dropdown
- - **Configurable Embedding Model** - `EMBEDDING_MODEL` env var for swapping the default sentence-transformers model
+ - **Configurable Embedding Model** - `EMBEDDING_MODEL` for local models, or `EMBEDDING_BASE_URL` to offload embeddings to an OpenAI-compatible provider (vLLM, OpenRouter, OpenAI, etc.)
- **Mistral Voxtral Chunking** - `MISTRAL_ENABLE_CHUNKING=true` opts into app-side chunking for long recordings
- **API v1 Parity** - `audio_duration`, transcription/summarization durations, folder, events, and `deletion_exempt` exposed
- **Bug Fixes** - Reprocess now applies tag/folder hotwords; "français" → "fr" migration; Cyrillic title fix
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index f41bf3ed..5b391e13 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -229,7 +229,7 @@ A separate [upload disclaimer](admin-guide/system-settings.md#upload-disclaimer)
Speakr can run completely offline as all dependencies are built into the Docker image. For offline deployments, use local models via Ollama for [text generation](features.md#automatic-summarization) and ensure your ASR endpoint is hosted locally. The system will work without internet access once properly configured.
-**Inquire Mode (Semantic Search)**: If you use Inquire Mode, the embedding model (all-MiniLM-L6-v2) is automatically cached in the persistent `instance/huggingface/` directory on first use. Run Speakr once with internet access to download the model, then it will load from cache on subsequent restarts - no network required.
+**Inquire Mode (Semantic Search)**: If you use Inquire Mode with the default local embedding model (all-MiniLM-L6-v2, or any value configured via `EMBEDDING_MODEL`), the model is automatically cached in the persistent `instance/huggingface/` directory on first use. Run Speakr once with internet access to download the model, then it will load from cache on subsequent restarts and no further network access is required. Configurations that use `EMBEDDING_BASE_URL` to offload embeddings to an API provider naturally require network access to that provider on every request.
### Non-Docker Installation
diff --git a/docs/user-guide/inquire-mode.md b/docs/user-guide/inquire-mode.md
index 936eeb83..453c4eb3 100644
--- a/docs/user-guide/inquire-mode.md
+++ b/docs/user-guide/inquire-mode.md
@@ -75,7 +75,7 @@ Pay attention to how the system interprets your questions. If results aren't qui
Inquire Mode's power comes from its semantic understanding capabilities. When embeddings are enabled (with sentence-transformers installed), the system creates mathematical representations of meaning that allow it to understand concepts beyond simple keyword matching. This means it can find relevant information even when different words are used to express the same ideas.
-Speakr uses the all-MiniLM-L6-v2 embedding model, a deliberately lightweight choice that balances performance with resource efficiency. This model generates 384-dimensional vectors and runs comfortably on CPU-only systems, which is crucial since most Speakr deployments are on standard servers or personal machines without dedicated GPUs. While newer, larger embedding models exist, they would require significantly more computational resources and could make the system sluggish or unusable on typical hardware. The MiniLM model provides excellent semantic understanding for conversational content while remaining fast and responsive even when processing hundreds of recordings.
+Speakr defaults to the all-MiniLM-L6-v2 embedding model, a deliberately lightweight choice that balances performance with resource efficiency. This model generates 384-dimensional vectors and runs comfortably on CPU-only systems, which is crucial since most Speakr deployments are on standard servers or personal machines without dedicated GPUs. The default provides solid semantic understanding for conversational content while remaining responsive even when processing hundreds of recordings. Administrators who want a different trade-off can override the model via the `EMBEDDING_MODEL` environment variable, or offload embedding generation entirely to an OpenAI-compatible API provider (vLLM, OpenRouter, OpenAI, and similar) by setting `EMBEDDING_BASE_URL`. See [Model Configuration](../admin-guide/model-configuration.md#configurable-embedding-model) for details.
The system processes recordings in chunks, allowing it to search through even very long recordings efficiently. Each chunk is analyzed independently but results are synthesized to maintain context and continuity. This approach ensures both speed and accuracy, even with large recording libraries.
@@ -93,7 +93,7 @@ Remember that Inquire Mode complements, not replaces, the standard recording int
While powerful, Inquire Mode has boundaries. It searches only transcribed text, not audio directly, so any errors in transcription will affect search results. The system cannot infer information that isn't explicitly stated in recordings - it finds and synthesizes what was said, not what was meant but left unsaid.
-Language support is optimized for English, as the embedding model (all-MiniLM-L6-v2) was primarily trained on English text. Other languages may work with varying degrees of success. Very long recordings might be summarized rather than fully indexed if they exceed processing limits. The system requires recordings to be fully processed before they're searchable, so very recent recordings might not appear immediately in results.
+Language support depends on the configured embedding model. The default all-MiniLM-L6-v2 was trained primarily on English, so non-English content works with varying results; switching to a multilingual model (e.g., `paraphrase-multilingual-MiniLM-L12-v2`) or a large API model such as `openai/text-embedding-3-large` significantly improves cross-lingual quality. Very long recordings might be summarized rather than fully indexed if they exceed processing limits. The system requires recordings to be fully processed before they are searchable, so very recent recordings may not appear immediately in results.
---