Skip to content

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

Python

Support Voyage AI embedding request parameters

ZOLO5fb2f4e92e83
diff --git a/docs/admin-guide/model-configuration.md b/docs/admin-guide/model-configuration.md
index 5a449953..1988e110 100644
--- a/docs/admin-guide/model-configuration.md
+++ b/docs/admin-guide/model-configuration.md
@@ -605,6 +605,27 @@ EMBEDDING_API_KEY=sk-or-...
EMBEDDING_MODEL=openai/text-embedding-3-large
```
+For Voyage AI's official endpoint, use:
+
+```env
+ENABLE_INQUIRE_MODE=true
+EMBEDDING_BASE_URL=https://api.voyageai.com/v1
+EMBEDDING_API_KEY=your-voyage-api-key
+EMBEDDING_MODEL=voyage-4-lite
+# EMBEDDING_DIMENSIONS=1024 # optional; must be supported by the model
+```
+
+Speakr recognizes the exact `api.voyageai.com` hostname and uses Voyage's
+encoding and `output_dimension` parameters. Recording chunks use
+`input_type=document`; searches use `input_type=query`. Other hosts retain
+OpenAI-compatible request semantics. A proxy under another hostname must
+provide an OpenAI-compatible interface. No Voyage SDK or local model is needed.
+Meeting text and search queries are sent to Voyage for embedding.
+
+After changing embedding providers, models, or dimensions, use **Admin →
+Vector Store → Re-embed all** to rebuild existing vectors. Do not retranscribe
+audio merely to rebuild the search index.
+
API mode does not require sentence-transformers to be installed, so the lightweight Docker image (`learnedmachine/speakr:lite`) can now run full semantic search by combining `EMBEDDING_BASE_URL` with any compatible provider. The lite image already ships `openai` and `scikit-learn`, so no further dependencies are needed.
### Compatibility Note
diff --git a/src/services/embeddings.py b/src/services/embeddings.py
index 9986ae92..7ada6a78 100644
--- a/src/services/embeddings.py
+++ b/src/services/embeddings.py
@@ -7,6 +7,7 @@ import re
import json
import time
import random
+from urllib.parse import urlsplit
import numpy as np
from flask import current_app
from sqlalchemy.orm import joinedload
@@ -54,6 +55,8 @@ except (TypeError, ValueError):
# When EMBEDDING_BASE_URL is set, embeddings are produced via an OpenAI-
# compatible /v1/embeddings call rather than locally.
USE_API_EMBEDDINGS = bool(EMBEDDING_BASE_URL)
+# Match the official host, never a substring in a path or lookalike domain.
+_USE_VOYAGE_API = urlsplit(EMBEDDING_BASE_URL).hostname == "api.voyageai.com"
# Identifier persisted to system_setting so the dimensionality compatibility
# check covers both "model changed" and "provider changed" scenarios.
@@ -157,7 +160,7 @@ def _is_dimensions_rejection(exc):
return 'dimension' in str(exc).lower()
-def _api_embed(texts, user_id=None):
+def _api_embed(texts, user_id=None, input_type="document"):
"""Call the OpenAI-compatible embeddings endpoint and return numpy vectors.
Retries on transient errors (rate limits, timeouts, 5xx, connection
@@ -188,7 +191,7 @@ def _api_embed(texts, user_id=None):
if len(texts) > batch_size:
out = []
for i in range(0, len(texts), batch_size):
- part = _api_embed(texts[i:i + batch_size], user_id=user_id)
+ part = _api_embed(texts[i:i + batch_size], user_id=user_id, input_type=input_type)
if len(part) != len(texts[i:i + batch_size]):
return []
out.extend(part)
@@ -203,12 +206,19 @@ def _api_embed(texts, user_id=None):
"Embedding API in failure cooldown; skipping call and using fallback")
return []
- # encoding_format='float' explicitly: OpenAI SDK v2 defaults to base64,
- # which some OpenAI-compatible providers cannot produce; float is the
- # format every compatible provider accepts.
- kwargs = {'input': texts, 'model': EMBEDDING_MODEL, 'encoding_format': 'float'}
- if EMBEDDING_DIMENSIONS is not None and not _dimensions_rejected:
- kwargs['dimensions'] = EMBEDDING_DIMENSIONS
+ if _USE_VOYAGE_API:
+ # Voyage accepts null/base64, not OpenAI's "float". Explicit null
+ # requests JSON floats and prevents the SDK's implicit base64 path.
+ extra_body = {'input_type': input_type}
+ if EMBEDDING_DIMENSIONS is not None:
+ extra_body['output_dimension'] = EMBEDDING_DIMENSIONS
+ kwargs = {'input': texts, 'model': EMBEDDING_MODEL,
+ 'encoding_format': None, 'extra_body': extra_body}
+ else:
+ # Explicit floats also work with providers that cannot emit base64.
+ kwargs = {'input': texts, 'model': EMBEDDING_MODEL, 'encoding_format': 'float'}
+ if EMBEDDING_DIMENSIONS is not None and not _dimensions_rejected:
+ kwargs['dimensions'] = EMBEDDING_DIMENSIONS
last_exc = None
for attempt in range(1, _API_EMBED_MAX_ATTEMPTS + 1):
@@ -777,7 +787,7 @@ def semantic_search_chunks(user_id, query, filters=None, top_k=5):
# the API call to the searching user so embedding cost tracking shows
# who issued the query.
if USE_API_EMBEDDINGS:
- api_vectors = _api_embed([query], user_id=user_id)
+ api_vectors = _api_embed([query], user_id=user_id, input_type="query")
if not api_vectors:
return basic_text_search_chunks(user_id, query, filters, top_k)
query_embedding = api_vectors[0]
diff --git a/tests/test_voyage_embeddings.py b/tests/test_voyage_embeddings.py
new file mode 100644
index 00000000..8850c04b
--- /dev/null
+++ b/tests/test_voyage_embeddings.py
@@ -0,0 +1,93 @@
+"""Voyage wire-format regressions; no credentials or network required."""
+import json
+import unittest
+from unittest.mock import patch
+
+import httpx
+from flask import Flask
+from openai import OpenAI
+
+from tests.test_embedding_api_mode import reload_with_env
+
+
+class VoyageEmbeddingsTests(unittest.TestCase):
+ def setUp(self):
+ self.ctx = Flask(__name__).app_context()
+ self.ctx.push()
+ self.requests = []
+
+ def tearDown(self):
+ reload_with_env()
+ self.ctx.pop()
+
+ def client(self, base, fail=False):
+ def handle(request):
+ body = json.loads(request.content)
+ self.requests.append(body)
+ if fail:
+ return httpx.Response(400, json={'detail': 'Invalid output_dimension'})
+ return httpx.Response(200, json={
+ 'object': 'list',
+ 'data': [{'object': 'embedding', 'index': i, 'embedding': [0.1, 0.2]}
+ for i in range(len(body['input']))],
+ 'model': body['model'], 'usage': {'total_tokens': 4},
+ })
+ return OpenAI(api_key='test-only', base_url=base, max_retries=0,
+ http_client=httpx.Client(transport=httpx.MockTransport(handle)))
+
+ def test_documents_use_voyage_wire_format(self):
+ base = 'https://api.voyageai.com/v1'
+ emb = reload_with_env(EMBEDDING_BASE_URL=base, EMBEDDING_MODEL='voyage-4-lite',
+ EMBEDDING_DIMENSIONS='256')
+ with self.client(base) as client, patch.object(emb, 'get_embedding_api_client', return_value=client):
+ vectors = emb.generate_embeddings(['hello', 'world'])
+ self.assertEqual(len(vectors), 2)
+ self.assertEqual(vectors[0].dtype.name, 'float32')
+ body = self.requests[0]
+ self.assertIsNone(body['encoding_format'])
+ self.assertEqual(body['input_type'], 'document')
+ self.assertEqual(body['output_dimension'], 256)
+ self.assertNotIn('dimensions', body)
+
+ def test_query_type_survives_batching(self):
+ base = 'https://api.voyageai.com/v1/'
+ emb = reload_with_env(EMBEDDING_BASE_URL=base, EMBEDDING_MODEL='voyage-4-lite')
+ with self.client(base) as client, patch.object(emb, 'get_embedding_api_client', return_value=client), patch.dict('os.environ', {'EMBEDDING_API_BATCH_SIZE': '1'}):
+ vectors = emb._api_embed(['one?', 'two?'], input_type='query')
+ self.assertEqual(len(vectors), 2)
+ self.assertEqual(len(self.requests), 2)
+ for body in self.requests:
+ self.assertEqual(body['input_type'], 'query')
+ self.assertNotIn('output_dimension', body)
+
+ def test_other_hosts_keep_openai_format(self):
+ for base in ('https://api.openai.com/v1', 'https://api.voyageai.com.example.org/v1',
+ 'https://proxy.example.org/api.voyageai.com/v1'):
+ with self.subTest(base=base):
+ emb = reload_with_env(EMBEDDING_BASE_URL=base, EMBEDDING_DIMENSIONS='256')
+ with self.client(base) as client, patch.object(emb, 'get_embedding_api_client', return_value=client):
+ self.assertEqual(len(emb.generate_embeddings(['text'])), 1)
+ body = self.requests[-1]
+ self.assertEqual(body['encoding_format'], 'float')
+ self.assertEqual(body['dimensions'], 256)
+ self.assertNotIn('input_type', body)
+ self.assertNotIn('output_dimension', body)
+
+ def test_semantic_search_marks_request_as_query(self):
+ base = 'https://api.voyageai.com/v1'
+ emb = reload_with_env(EMBEDDING_BASE_URL=base, EMBEDDING_MODEL='voyage-4-lite')
+ with self.client(base) as client, patch.object(emb, 'get_embedding_api_client', return_value=client), patch.object(emb, 'get_accessible_recording_ids', return_value=[]):
+ self.assertEqual(emb.semantic_search_chunks(None, 'When is launch?'), [])
+ self.assertEqual(len(self.requests), 1)
+ self.assertEqual(self.requests[0]['input_type'], 'query')
+
+ def test_voyage_bad_dimension_does_not_silently_change_vector_space(self):
+ base = 'https://api.voyageai.com/v1'
+ emb = reload_with_env(EMBEDDING_BASE_URL=base, EMBEDDING_DIMENSIONS='123')
+ with self.client(base, fail=True) as client, patch.object(emb, 'get_embedding_api_client', return_value=client):
+ self.assertEqual(emb.generate_embeddings(['text']), [])
+ self.assertEqual(len(self.requests), 1)
+
+
+if __name__ == '__main__':
+ unittest.main()