Skip to content

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

Python

docs: describe segment-aware chunking, CHUNKING_STRATEGY, and the re-embed requirement when changing embedding models

Murtaza Nasir9b5be87b8a0d
diff --git a/docs/user-guide/inquire-mode.md b/docs/user-guide/inquire-mode.md
index b287800c..ae25bd38 100644
--- a/docs/user-guide/inquire-mode.md
+++ b/docs/user-guide/inquire-mode.md
@@ -76,7 +76,9 @@ Inquire Mode's power comes from its semantic understanding capabilities. When em
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.
+The system processes recordings in chunks, allowing it to search through even very long recordings efficiently. Diarized transcripts are chunked segment-aware: each chunk holds whole speaker turns rendered as `Speaker: text` lines, packed to roughly 1,400 characters, with a one-turn overlap between consecutive chunks. Because boundaries are size-based rather than per-turn, a rapid back-and-forth exchange stays together in a single chunk with every speaker labeled inline. Each chunk also stores its dominant speaker and start and end timestamps, which is what allows search results and Inquire citations to point at the moment in the recording where something was said. Administrators can keep the older plain character-window behavior with `CHUNKING_STRATEGY=legacy`; either way, existing indexed chunks are untouched by an upgrade until a recording is reindexed. The chunk size is tunable via `CHUNK_TARGET_CHARS`.
+
+A note on changing embedding models: vectors from different models are not comparable, even when their dimensions happen to match. After switching `EMBEDDING_MODEL` or `EMBEDDING_BASE_URL` to a different model, re-embed the library (the admin dashboard's reprocessing tools, or reindex recordings individually) so search quality does not silently degrade.
Performance scales well with proper setup. The initial indexing of recordings happens automatically after transcription, and subsequent searches leverage this pre-computed index. Response times typically range from a few seconds for focused searches to slightly longer for complex queries across large libraries.