Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

Add embedding model and hardware guidance to library pages (#7895)

LearningCircuit42255b46071b
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 20c5277265..5561a3fc82 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -78,6 +78,7 @@ They are not available in the Web UI because they are needed to start the applic
| `app.warnings.dismiss_context_truncation_history` | `LDR_APP_WARNINGS_DISMISS_CONTEXT_TRUNCATION_HISTORY` | `false` | Dismiss warnings about historical context truncation | APP |
| `app.warnings.dismiss_egress_policy` | `LDR_APP_WARNINGS_DISMISS_EGRESS_POLICY` | `false` | Permanently hide the 'public search egress enabled' banner (the fresh-install informational one). The critical cloud-LLM and cloud-embeddings banners have their OWN dismiss flags so this can't silently hide them. | APP |
| `app.warnings.dismiss_elasticsearch_public_url` | `LDR_APP_WARNINGS_DISMISS_ELASTICSEARCH_PUBLIC_URL` | `false` | Permanently hide the 'Elasticsearch points at a non-private host' banner that appears when the Elasticsearch engine is active but its hosts (or cloud_id) do not look like private/local addresses (document queries would leave the machine; a private-only egress scope excludes the engine). Dismiss when a hosted endpoint such as Elastic Cloud is intentional. | APP |
+| `app.warnings.dismiss_embedding_performance` | `LDR_APP_WARNINGS_DISMISS_EMBEDDING_PERFORMANCE` | `false` | Hide embedding performance tips on collection and embedding settings pages. Turn off to show the tips again. | APP |
| `app.warnings.dismiss_high_context` | `LDR_APP_WARNINGS_DISMISS_HIGH_CONTEXT` | `false` | Permanently hide the warning shown when your local LLM context window is set above 8,192 tokens, which may cause memory issues on some hardware. | APP |
| `app.warnings.dismiss_legacy_config` | `LDR_APP_WARNINGS_DISMISS_LEGACY_CONFIG` | `false` | Dismiss warnings about the deprecated server_config.json file | APP |
| `app.warnings.dismiss_model_mismatch` | `LDR_APP_WARNINGS_DISMISS_MODEL_MISMATCH` | `false` | Permanently hide the warning shown when using a large model (70B+ parameters) with a local provider and high context window, which may exceed available GPU memory. | APP |
diff --git a/docs/embedding-performance.md b/docs/embedding-performance.md
new file mode 100644
index 0000000000..4ad58c76cf
--- /dev/null
+++ b/docs/embedding-performance.md
@@ -0,0 +1,54 @@
+# Choosing embeddings for your hardware
+
+If you have never changed your embedding settings and indexing makes your
+computer slow or keeps CPU usage high, try a smaller embedding model. With a
+supported GPU and enough free VRAM, Ollama can also be a useful option.
+
+Use the × button on a performance tip to hide these tips for your account across
+collection and embedding settings pages. To show them again, turn off
+**Dismiss Embedding Performance Tips** in Settings. This preference only hides
+the tips; it does not change your embedding configuration.
+
+## Use a smaller model on CPU
+
+Open **Library → Embedding Settings** (`/library/embedding-settings`). Select
+**Sentence Transformers** and try **all-MiniLM-L6-v2**, a lightweight model
+available in the model dropdown. Use **Test Embedding Model** before indexing;
+settings save automatically.
+
+Smaller models can trade retrieval quality and context length for lower resource
+use. This model accepts up to 256 tokens per chunk, so review your chunk size:
+longer chunks may be truncated. Try a small collection and check search results
+before rebuilding a large one.
+
+## Consider Ollama with GPU acceleration
+
+Ollama supports local embedding models and can use supported GPUs. Check
+[Ollama hardware support](https://docs.ollama.com/gpu) for your GPU and drivers.
+Leave enough free VRAM for the embedding model, its working memory, and any LLM
+running at the same time. Switching providers alone does not guarantee lower CPU
+usage or faster indexing.
+
+1. Start Ollama and download an embedding model, for example with
+ `ollama pull nomic-embed-text`.
+2. In **Embedding Settings**, select **Ollama**, configure its server URL, and
+ select the downloaded embedding model. The URL must be reachable from LDR;
+ in Docker, `localhost` refers to the LDR container itself.
+3. Use **Test Embedding Model**, then try indexing a small collection.
+4. Check GPU usage while indexing to confirm that acceleration is active.
+
+Use an embedding model rather than a chat model. See
+[Ollama embeddings](https://docs.ollama.com/capabilities/embeddings) for background.
+
+## Apply changes to existing collections
+
+Saved defaults apply to new collections. Existing collections retain their
+embedding settings until you choose **Re-Index All Documents** on the collection
+page to rebuild with the current settings. A full rebuild processes every
+document and can take time; keep it running until it completes. Cancelling before
+publication preserves the previous index and its settings, if any.
+
+If indexing is already making your computer unresponsive, use **Cancel Indexing**
+on the collection page before changing settings and starting a rebuild.
+
+See [Library and RAG](library-and-rag.md#rag-indexing) for more about indexing.
diff --git a/docs/library-and-rag.md b/docs/library-and-rag.md
index 650351f685..41d12f9aac 100644
--- a/docs/library-and-rag.md
+++ b/docs/library-and-rag.md
@@ -238,6 +238,9 @@ Document → Split into Chunks → Generate Embeddings → Store in Vector Index
2. **Embedding** - Each chunk converted to a vector using AI model
3. **Indexing** - Vectors stored in FAISS for fast similarity search
+For high CPU usage, smaller models, and Ollama GPU options, see
+[Choosing embeddings for your hardware](embedding-performance.md).
+
### Indexing a Collection
1. Go to **Library** → **Collections**
diff --git a/src/local_deep_research/defaults/default_settings.json b/src/local_deep_research/defaults/default_settings.json
index 5124798691..813df710bf 100644
--- a/src/local_deep_research/defaults/default_settings.json
+++ b/src/local_deep_research/defaults/default_settings.json
@@ -4398,6 +4398,20 @@
"value": true,
"visible": true
},
+ "app.warnings.dismiss_embedding_performance": {
+ "category": "warnings",
+ "description": "Hide embedding performance tips on collection and embedding settings pages. Turn off to show the tips again.",
+ "editable": true,
+ "max_value": null,
+ "min_value": null,
+ "name": "Dismiss Embedding Performance Tips",
+ "options": null,
+ "step": null,
+ "type": "APP",
+ "ui_element": "checkbox",
+ "value": false,
+ "visible": true
+ },
"app.warnings.dismiss_high_context": {
"category": "warnings",
"description": "Permanently hide the warning shown when your local LLM context window is set above 8,192 tokens, which may cause memory issues on some hardware.",
diff --git a/src/local_deep_research/web/routers/rag.py b/src/local_deep_research/web/routers/rag.py
index a30fed22d0..c50479bd50 100644
--- a/src/local_deep_research/web/routers/rag.py
+++ b/src/local_deep_research/web/routers/rag.py
@@ -492,10 +492,19 @@ def embedding_settings_page(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""Render the Embedding Settings page."""
+ from ...embeddings.sentence_transformer_models import (
+ SENTENCE_TRANSFORMER_MODELS,
+ )
+
return templates.TemplateResponse(
request=request,
name="pages/embedding_settings.html",
- context={"request": request, "active_page": "embedding-settings"},
+ context={
+ "request": request,
+ "active_page": "embedding-settings",
+ "sentence_transformer_models": SENTENCE_TRANSFORMER_MODELS,
+ "default_sentence_transformer_model": DEFAULT_LOCAL_SEARCH_MODEL,
+ },
)
diff --git a/src/local_deep_research/web/static/js/embedding_performance_hint.js b/src/local_deep_research/web/static/js/embedding_performance_hint.js
new file mode 100644
index 0000000000..c6feb61583
--- /dev/null
+++ b/src/local_deep_research/web/static/js/embedding_performance_hint.js
@@ -0,0 +1,118 @@
+/** Account-scoped dismissal for the shared embedding performance tip. */
+(function() {
+ 'use strict';
+
+ const hints = Array.from(document.querySelectorAll('[data-embedding-performance-hint]'));
+ if (hints.length === 0) return;
+
+ const settingUrl = '/settings/api/app.warnings.dismiss_embedding_performance';
+ const buttons = hints.map(hint => hint.querySelector('[data-dismiss-embedding-hint]')).filter(Boolean);
+ const errorTargets = hints.map(hint => hint.querySelector('[data-embedding-hint-error]')).filter(Boolean);
+
+ // Controls that point at a hint's text (data-embedding-hint-describedby)
+ // reference it through aria-describedby only while the tip is shown, so a
+ // hidden or dismissed tip is not still announced. Controls may also carry a
+ // tip-augmented title (data-embedding-hint-title) that replaces their base
+ // title only while the tip is shown.
+ const hintTextIds = new Set(
+ hints.flatMap(hint => Array.from(hint.querySelectorAll('[id]'), el => el.id))
+ );
+ const describers = Array.from(document.querySelectorAll('[data-embedding-hint-describedby]'))
+ .filter(el => hintTextIds.has(el.dataset.embeddingHintDescribedby));
+ const titled = Array.from(document.querySelectorAll('[data-embedding-hint-title]'));
+ const baseTitles = new Map(titled.map(el => [el, el.getAttribute('title')]));
+
+ function syncReferences(visible) {
+ describers.forEach(el => {
+ const hintId = el.dataset.embeddingHintDescribedby;
+ const tokens = (el.getAttribute('aria-describedby') || '')
+ .split(/\s+/).filter(token => token && token !== hintId);
+ if (visible) tokens.push(hintId);
+ if (tokens.length) el.setAttribute('aria-describedby', tokens.join(' '));
+ else el.removeAttribute('aria-describedby');
+ });
+ titled.forEach(el => {
+ const title = visible ? el.dataset.embeddingHintTitle : baseTitles.get(el);
+ if (title) el.setAttribute('title', title);
+ else el.removeAttribute('title');
+ });
+ }
+
+ function setVisible(visible) {
+ hints.forEach(hint => { hint.hidden = !visible; });
+ syncReferences(visible);
+ }
+
+ function removeDismissControls() {
+ // Removed rather than hidden: .ldr-btn's display rule would
+ // override the hidden attribute.
+ buttons.forEach(button => button.remove());
+ }
+
+ function showError(message) {
+ errorTargets.forEach(target => { target.textContent = message; });
+ }
+
+ async function serverError(response) {
+ try {
+ const data = await response.json();
+ const message = data && (data.error || data.detail);
+ return typeof message === 'string' ? message : '';
+ } catch {
+ return '';
+ }
+ }
+
+ async function dismiss() {
+ buttons.forEach(button => { button.disabled = true; });
+ showError('');
+ try {
+ const response = await safeFetchWithAuth(settingUrl, {
+ method: 'PUT',
+ headers: {
+ 'Content-Type': 'application/json',
+ 'X-CSRFToken': window.api ? window.api.getCsrfToken() : ''
+ },
+ body: JSON.stringify({ value: true })
+ });
+ if (!response.ok) {
+ const message = await serverError(response);
+ showError(message
+ ? `Could not save dismissal: ${message}`
+ : 'Could not save dismissal. Please try again.');
+ return;
+ }
+ setVisible(false);
+ } catch {
+ showError('Could not save dismissal. Please try again.');
+ } finally {
+ buttons.forEach(button => { button.disabled = false; });
+ }
+ }
+
+ buttons.forEach(button => button.addEventListener('click', dismiss));
+
+ // The tip is rendered hidden so a dismissed tip never flashes in and
+ // shifts the layout; it is revealed once the preference says it is
+ // wanted. Loading failures fail open: guidance and dismissal are shown.
+ async function loadPreference() {
+ let data = null;
+ try {
+ const response = await safeFetchWithAuth(settingUrl);
+ if (response.ok) data = await response.json();
+ } catch {
+ data = null;
+ }
+ if (data && data.value === true) {
+ setVisible(false);
+ return;
+ }
+ // A locked setting (e.g. an LDR_* env override) rejects every save,
+ // so do not offer a dismissal control that can never succeed.
+ if (data && data.editable === false) removeDismissControls();
+ setVisible(true);
+ }
+
+ setVisible(false);
+ loadPreference();
+})();
diff --git a/src/local_deep_research/web/templates/components/embedding_performance_hint.html b/src/local_deep_research/web/templates/components/embedding_performance_hint.html
new file mode 100644
index 0000000000..46878e54b5
--- /dev/null
+++ b/src/local_deep_research/web/templates/components/embedding_performance_hint.html
@@ -0,0 +1,14 @@
+<div data-embedding-performance-hint hidden>
+<button type="button" class="ldr-btn ldr-btn-sm" data-dismiss-embedding-hint aria-label="Dismiss embedding performance tip" title="Don't show this tip again">&times;</button>
+<p class="ldr-form-text ldr-text-muted"{% if embedding_hint_id %} id="{{ embedding_hint_id }}"{% endif %}>
+ <i aria-hidden="true" class="fas fa-info-circle"></i>
+ If you haven't changed your embedding settings, the default model may be demanding on your CPU.
+ Indexing can take a while; keeping the default is fine if the resource use works for you.
+ If indexing slows down your computer, consider a smaller model in
+ <a href="/library/embedding-settings">Embedding Settings</a>.
+ Ollama may help with a supported GPU and enough free VRAM.
+ Existing collections need a full re-index to use changed settings.
+ <a href="https://github.com/LearningCircuit/local-deep-research/blob/main/docs/embedding-performance.md" target="_blank" rel="noopener noreferrer">Embedding performance guide &#8599;</a>
+</p>
+<span class="ldr-form-text" data-embedding-hint-error role="status"></span>
+</div>
diff --git a/src/local_deep_research/web/templates/pages/collection_details.html b/src/local_deep_research/web/templates/pages/collection_details.html
index 2c008f263c..3b7af183fd 100644
--- a/src/local_deep_research/web/templates/pages/collection_details.html
+++ b/src/local_deep_research/web/templates/pages/collection_details.html
@@ -33,16 +33,19 @@
<a href="/library/collections/{{ collection_id }}/upload" class="ldr-btn-collections ldr-btn-collections-primary ldr-btn-lg ldr-btn-featured" title="Add PDF, TXT, MD, or HTML files to this collection">
<i aria-hidden="true" class="fas fa-upload"></i> Upload Files
</a>
- <button id="index-collection-btn" class="ldr-btn-collections ldr-btn-collections-success ldr-btn-lg" title="Create searchable embeddings for unindexed documents">
+ <button id="index-collection-btn" class="ldr-btn-collections ldr-btn-collections-success ldr-btn-lg" data-embedding-hint-describedby="index-embedding-performance-hint" title="Create searchable embeddings for unindexed documents" data-embedding-hint-title="Create searchable embeddings for unindexed documents. High CPU usage? Consider a smaller embedding model or Ollama with a supported GPU and enough free VRAM.">
<i aria-hidden="true" class="fas fa-sync"></i> Index All Documents
</button>
- <button id="reindex-collection-btn" class="ldr-btn-collections ldr-btn-collections-warning ldr-btn-lg" title="Re-process all documents. Use after changing embedding settings.">
+ <button id="reindex-collection-btn" data-embedding-hint-describedby="index-embedding-performance-hint" class="ldr-btn-collections ldr-btn-collections-warning ldr-btn-lg" title="Re-process all documents. Use after changing embedding settings.">
<i aria-hidden="true" class="fas fa-redo"></i> Re-Index All Documents
</button>
<button id="delete-collection-btn" class="ldr-btn-collections ldr-btn-collections-danger ldr-btn-lg" title="Delete this collection and its embeddings. Documents also in other collections are kept; documents only in this collection are deleted with it.">
<i aria-hidden="true" class="fas fa-trash"></i> Delete Collection
</button>
</div>
+ {% with embedding_hint_id="index-embedding-performance-hint" %}
+ {% include "components/embedding_performance_hint.html" %}
+ {% endwith %}
</div>
<!-- Privacy & Egress -->
@@ -163,6 +166,8 @@
<p id="progress-text" class="ldr-progress-text">Starting...</p>
</div>
+ {% include "components/embedding_performance_hint.html" %}
+
<div id="progress-log" class="ldr-progress-log"></div>
</div>
@@ -228,3 +233,7 @@
<script defer src="/static/js/components/library_search.js"></script>
<script defer src="/static/js/collection_details.js"></script>
{% endblock %}
+
+{% block page_scripts %}
+<script defer src="/static/js/embedding_performance_hint.js"></script>
+{% endblock %}
diff --git a/src/local_deep_research/web/templates/pages/collections.html b/src/local_deep_research/web/templates/pages/collections.html
index 6f779c08cf..7df0f9838c 100644
--- a/src/local_deep_research/web/templates/pages/collections.html
+++ b/src/local_deep_research/web/templates/pages/collections.html
@@ -14,6 +14,8 @@
<p class="ldr-subtitle">Manage your document collections for {{ tooltip("RAG-enabled searches", "Upload your documents, index them, then select a collection as 'search engine' when researching. AI will search YOUR files instead of the web.") }}</p>
</div>
+ {% include "components/embedding_performance_hint.html" %}
+
<!-- How Collections Work Help Panel -->
{% call help_panel('collections-how', 'Understanding Document Collections', icon='folder-open', collapsed=true, dismissible=true) %}
<div class="ldr-help-steps">
@@ -70,3 +72,7 @@
<script defer src="/static/js/collections_manager.js"></script>
{% endblock %}
+
+{% block page_scripts %}
+<script defer src="/static/js/embedding_performance_hint.js"></script>
+{% endblock %}
diff --git a/src/local_deep_research/web/templates/pages/embedding_settings.html b/src/local_deep_research/web/templates/pages/embedding_settings.html
index 96876a04d7..89e7a17648 100644
--- a/src/local_deep_research/web/templates/pages/embedding_settings.html
+++ b/src/local_deep_research/web/templates/pages/embedding_settings.html
@@ -35,12 +35,32 @@
</p>
<p style="margin: 0;">
<i aria-hidden="true" class="fas fa-lock"></i> Once a collection is indexed, its embedding settings are locked.
- To change settings for an existing collection, you must re-index the entire collection, which will delete the current index.
+ To change settings for an existing collection, use Re-Index All Documents to build a replacement index. The current index stays available until the replacement is ready.
</p>
</div>
</div>
</div>
+ <div class="ldr-rag-config-panel">
+ <h2>Supported Sentence Transformers models</h2>
+ <p class="ldr-text-muted">
+ These are the models available directly through the Sentence Transformers provider.
+ Indexing a large collection can take a while; keeping the default is fine if the resource use works for you.
+ Choose a smaller model if CPU load or memory use interferes with other work.
+ Each link opens the model's Hugging Face page with more details.
+ </p>
+ <ul>
+ {% for model_name, model in sentence_transformer_models.items() %}
+ <li><a href="https://huggingface.co/{{ model.repository }}" target="_blank" rel="noopener noreferrer">{{ model_name }}</a>{% if model_name == default_sentence_transformer_model %} (default){% endif %}: {{ model.description }} Input limit: {{ model.max_seq_length }} tokens.</li>
+ {% endfor %}
+ </ul>
+ <p class="ldr-form-text ldr-text-muted">
+ Models have different input limits; long chunks may be truncated. Review chunk size when switching models.
+ For more locally managed model choices, use Ollama.
+ <a href="https://github.com/LearningCircuit/local-deep-research/blob/main/docs/embedding-performance.md" target="_blank" rel="noopener noreferrer">Embedding performance guide &#8599;</a>
+ </p>
+ </div>
+
<!-- Test Panel -->
<div class="ldr-rag-operations-panel">
<h2><i aria-hidden="true" class="fas fa-vial"></i> Test Configuration</h2>
@@ -214,6 +234,8 @@
</div>
</div>
+ {% include "components/embedding_performance_hint.html" %}
+
<!-- Provider Information Panel -->
<div class="ldr-rag-stats-panel">
<h2><i aria-hidden="true" class="fas fa-info-circle"></i> Provider Information</h2>
@@ -227,3 +249,7 @@
<script defer src="/static/js/embedding_settings.js"></script>
{% endblock %}
+
+{% block page_scripts %}
+<script defer src="/static/js/embedding_performance_hint.js"></script>
+{% endblock %}
diff --git a/tests/js/embedding-performance-hint.test.js b/tests/js/embedding-performance-hint.test.js
new file mode 100644
index 0000000000..cfb31f05cc
--- /dev/null
+++ b/tests/js/embedding-performance-hint.test.js
@@ -0,0 +1,167 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import DOMPurify from 'dompurify';
+
+const template = readFileSync(resolve(__dirname, '../../src/local_deep_research/web/templates/components/embedding_performance_hint.html'), 'utf8');
+const component = template
+ .replace(/\{%[\s\S]*?%\}/g, '')
+ .replace(/\{\{[\s\S]*?\}\}/g, '');
+// Same component rendered with an embedding_hint_id, as collection_details.html does.
+const componentWithId = template
+ .replace(/\{% if embedding_hint_id %\}([\s\S]*?)\{% endif %\}/g, '$1')
+ .replace(/\{\{\s*embedding_hint_id\s*\}\}/g, 'index-hint')
+ .replace(/\{%[\s\S]*?%\}/g, '');
+const baseTitle = 'Create searchable embeddings';
+const tipTitle = 'Create searchable embeddings. High CPU usage?';
+const describedControls = `
+ <button id="index-btn" data-embedding-hint-describedby="index-hint" title="${baseTitle}" data-embedding-hint-title="${tipTitle}">Index</button>
+ <button id="reindex-btn" aria-describedby="other-help" data-embedding-hint-describedby="index-hint" title="Re-index">Re-Index</button>
+ <span id="other-help">Other help</span>`;
+const settingUrl = '/settings/api/app.warnings.dismiss_embedding_performance';
+const response = (value, ok = true, extra = {}) => ({ ok, json: async () => ({ value, editable: true, ...extra }) });
+const errorResponse = body => ({ ok: false, json: async () => body });
+const hints = () => Array.from(document.querySelectorAll('[data-embedding-performance-hint]'));
+const buttons = () => Array.from(document.querySelectorAll('[data-dismiss-embedding-hint]'));
+const allVisible = () => hints().every(hint => !hint.hidden);
+const allHidden = () => hints().every(hint => hint.hidden);
+
+beforeEach(() => {
+ vi.resetModules();
+ document.body.innerHTML = DOMPurify.sanitize(component + component);
+ window.api = { getCsrfToken: () => 'test-csrf' };
+ globalThis.safeFetchWithAuth = vi.fn().mockResolvedValue(response(false));
+});
+
+afterEach(() => {
+ document.body.innerHTML = '';
+ delete window.api;
+});
+
+async function start() {
+ await import('../../src/local_deep_research/web/static/js/embedding_performance_hint.js');
+ await vi.waitFor(() => expect(safeFetchWithAuth).toHaveBeenCalledWith(settingUrl));
+}
+
+it('renders hidden and stays hidden until the preference has loaded', async () => {
+ expect(allHidden()).toBe(true);
+ let finishLoad;
+ safeFetchWithAuth.mockImplementation(() => new Promise(complete => { finishLoad = complete; }));
+ await start();
+ expect(allHidden()).toBe(true);
+ finishLoad(response(false));
+ await vi.waitFor(() => expect(allVisible()).toBe(true));
+});
+
+it('keeps every copy hidden when the account has dismissed the tip', async () => {
+ safeFetchWithAuth.mockResolvedValue(response(true));
+ await start();
+ await new Promise(r => setTimeout(r, 0));
+ expect(allHidden()).toBe(true);
+});
+
+it.each([false, 'false'])('reveals tips for preference %s', async value => {
+ safeFetchWithAuth.mockResolvedValue(response(value));
+ await start();
+ await vi.waitFor(() => expect(allVisible()).toBe(true));
+ expect(buttons()).toHaveLength(2);
+});
+
+it('removes the dismiss control when the setting is not editable', async () => {
+ safeFetchWithAuth.mockResolvedValue(response(false, true, { editable: false }));
+ await start();
+ await vi.waitFor(() => expect(allVisible()).toBe(true));
+ expect(buttons()).toHaveLength(0);
+});
+
+it('saves with CSRF and hides all copies only after the save succeeds', async () => {
+ let finishSave;
+ safeFetchWithAuth.mockImplementation((_url, options) => {
+ if (options) return new Promise(complete => { finishSave = complete; });
+ return Promise.resolve(response(false));
+ });
+ await start();
+ await vi.waitFor(() => expect(allVisible()).toBe(true));
+ buttons()[0].click();
+ expect(buttons().every(button => button.disabled)).toBe(true);
+ expect(allVisible()).toBe(true);
+ expect(safeFetchWithAuth).toHaveBeenLastCalledWith(settingUrl, {
+ method: 'PUT',
+ headers: { 'Content-Type': 'application/json', 'X-CSRFToken': 'test-csrf' },
+ body: JSON.stringify({ value: true })
+ });
+ finishSave(response(true));
+ await vi.waitFor(() => expect(allHidden()).toBe(true));
+});
+
+it('reports a rejected save and allows retry without hiding the tips', async () => {
+ await start();
+ await vi.waitFor(() => expect(allVisible()).toBe(true));
+ safeFetchWithAuth.mockResolvedValueOnce(errorResponse(null));
+ buttons()[0].click();
+ await vi.waitFor(() => expect(buttons().every(button => !button.disabled)).toBe(true));
+ expect(allVisible()).toBe(true);
+ expect(document.querySelector('[data-embedding-hint-error]').textContent).toContain('Please try again');
+ safeFetchWithAuth.mockResolvedValueOnce(response(true));
+ buttons()[0].click();
+ await vi.waitFor(() => expect(allHidden()).toBe(true));
+});
+
+it('surfaces the server error message when a save is refused', async () => {
+ await start();
+ await vi.waitFor(() => expect(allVisible()).toBe(true));
+ safeFetchWithAuth.mockResolvedValueOnce(errorResponse({ error: 'Settings are locked' }));
+ buttons()[0].click();
+ await vi.waitFor(() => expect(buttons().every(button => !button.disabled)).toBe(true));
+ expect(allVisible()).toBe(true);
+ expect(document.querySelector('[data-embedding-hint-error]').textContent)
+ .toBe('Could not save dismissal: Settings are locked');
+});
+
+it('fails open when the preference request is not ok', async () => {
+ safeFetchWithAuth.mockResolvedValue(errorResponse({ error: 'Failed to retrieve settings' }));
+ await start();
+ await vi.waitFor(() => expect(allVisible()).toBe(true));
+ expect(buttons()).toHaveLength(2);
+});
+
+it('fails open when preference loading rejects', async () => {
+ safeFetchWithAuth.mockRejectedValue(new Error('Offline'));
+ await start();
+ await vi.waitFor(() => expect(allVisible()).toBe(true));
+});
+
+describe('controls described by the tip', () => {
+ beforeEach(() => {
+ document.body.innerHTML = DOMPurify.sanitize(describedControls + componentWithId);
+ });
+
+ const indexBtn = () => document.getElementById('index-btn');
+ const reindexBtn = () => document.getElementById('reindex-btn');
+
+ it('reference the tip only while it is shown and drop it on dismissal', async () => {
+ expect(document.getElementById('index-hint')).not.toBeNull();
+ await start();
+ await vi.waitFor(() => expect(allVisible()).toBe(true));
+ expect(indexBtn().getAttribute('aria-describedby')).toBe('index-hint');
+ expect(indexBtn().getAttribute('title')).toBe(tipTitle);
+ expect(reindexBtn().getAttribute('aria-describedby')).toBe('other-help index-hint');
+
+ safeFetchWithAuth.mockResolvedValueOnce(response(true));
+ buttons()[0].click();
+ await vi.waitFor(() => expect(allHidden()).toBe(true));
+ expect(indexBtn().hasAttribute('aria-describedby')).toBe(false);
+ expect(indexBtn().getAttribute('title')).toBe(baseTitle);
+ expect(reindexBtn().getAttribute('aria-describedby')).toBe('other-help');
+ expect(reindexBtn().getAttribute('title')).toBe('Re-index');
+ });
+
+ it('never reference an already-dismissed tip', async () => {
+ safeFetchWithAuth.mockResolvedValue(response(true));
+ await start();
+ await new Promise(r => setTimeout(r, 0));
+ expect(allHidden()).toBe(true);
+ expect(indexBtn().hasAttribute('aria-describedby')).toBe(false);
+ expect(indexBtn().getAttribute('title')).toBe(baseTitle);
+ expect(reindexBtn().getAttribute('aria-describedby')).toBe('other-help');
+ });
+});
diff --git a/tests/settings/golden_master_settings.json b/tests/settings/golden_master_settings.json
index c9e5982574..f8bdbb01e4 100644
--- a/tests/settings/golden_master_settings.json
+++ b/tests/settings/golden_master_settings.json
@@ -482,6 +482,20 @@
"value": false,
"visible": true
},
+ "app.warnings.dismiss_embedding_performance": {
+ "category": "warnings",
+ "description": "Hide embedding performance tips on collection and embedding settings pages. Turn off to show the tips again.",
+ "editable": true,
+ "max_value": null,
+ "min_value": null,
+ "name": "Dismiss Embedding Performance Tips",
+ "options": null,
+ "step": null,
+ "type": "APP",
+ "ui_element": "checkbox",
+ "value": false,
+ "visible": true
+ },
"app.warnings.dismiss_high_context": {
"category": "warnings",
"description": "Permanently hide the warning shown when your local LLM context window is set above 8,192 tokens, which may cause memory issues on some hardware.",
diff --git a/tests/settings/test_shipped_defaults_contracts.py b/tests/settings/test_shipped_defaults_contracts.py
index 59b8162a92..984d637f9b 100644
--- a/tests/settings/test_shipped_defaults_contracts.py
+++ b/tests/settings/test_shipped_defaults_contracts.py
@@ -418,6 +418,8 @@ DOCUMENTED_PERMISSIVE_DEFAULTS: Dict[str, Tuple[Any, str]] = {
# unclassified match fails rather than being quietly skipped.
NOT_A_SECURITY_CONTROL = frozenset(
{
+ # Informational performance tip only; dismissal changes no policy.
+ "app.warnings.dismiss_embedding_performance",
"app.host", # notification URL building only -- see its own test
"app.port",
"web.port",
diff --git a/tests/test_constants.py b/tests/test_constants.py
index 3aeeb7b351..c9410c9d60 100644
--- a/tests/test_constants.py
+++ b/tests/test_constants.py
@@ -165,10 +165,13 @@ def test_injected_frontend_local_search_constants_match_defaults():
def test_embedding_settings_template_renders_without_syntax_error():
- """pages/embedding_settings.html must compile and render properly."""
+ """The page route renders defaults and the shared model catalog."""
from starlette.requests import Request
+ from local_deep_research.embeddings.sentence_transformer_models import (
+ SENTENCE_TRANSFORMER_MODELS,
+ )
from local_deep_research.web.fastapi_app import _setup_template_globals
- from local_deep_research.web.template_config import templates
+ from local_deep_research.web.routers.rag import embedding_settings_page
_setup_template_globals()
req = Request(
@@ -180,14 +183,26 @@ def test_embedding_settings_template_renders_without_syntax_error():
"session": {},
}
)
- ctx = {"request": req, "active_page": "embedding-settings"}
- resp = templates.TemplateResponse(
- request=req,
- name="pages/embedding_settings.html",
- context=ctx,
- )
+ resp = embedding_settings_page(req, username="testuser")
html = resp.body.decode()
+ assert resp.status_code == 200
+ assert html.index("/static/js/security/safe-fetch.js") < html.index(
+ "/static/js/embedding_performance_hint.js"
+ )
+ assert (
+ resp.context["sentence_transformer_models"]
+ is SENTENCE_TRANSFORMER_MODELS
+ )
+ assert html.count('href="https://huggingface.co/') == len(
+ SENTENCE_TRANSFORMER_MODELS
+ )
+ for model_name, model in SENTENCE_TRANSFORMER_MODELS.items():
+ assert f'href="https://huggingface.co/{model.repository}"' in html
+ assert f">{model_name}</a>" in html
+ assert model.description in html
+ assert f"Input limit: {model.max_seq_length} tokens." in html
+ assert f">{DEFAULT_LOCAL_SEARCH_MODEL}</a> (default)" in html
assert "Default Embedding Settings" in html
assert 'id="text-separators"' in html
assert (
diff --git a/tests/web/test_template_script_placement.py b/tests/web/test_template_script_placement.py
index 0d0fdbea9c..bba363bf9b 100644
--- a/tests/web/test_template_script_placement.py
+++ b/tests/web/test_template_script_placement.py
@@ -30,6 +30,7 @@ _PAGES = (
# Components whose synchronous init depends on base.html's deferred shared
# scripts (safeFetchWithAuth from safe-fetch.js).
_SAFE_FETCH_COMPONENTS = (
+ "embedding_performance_hint.js",
"components/annotation_surface.js",
"components/document_notes.js",
"components/research_notes.js",
@@ -83,9 +84,12 @@ def test_safe_fetch_components_load_from_page_scripts_block():
def test_known_consumers_still_covered():
- # The three templates that load these components today. If one stops
+ # The templates that load these components today. If one stops
# loading them, this list (not the invariant) needs updating.
expected = {
+ "collections.html": {"embedding_performance_hint.js"},
+ "collection_details.html": {"embedding_performance_hint.js"},
+ "embedding_settings.html": {"embedding_performance_hint.js"},
"document_details.html": {"components/document_notes.js"},
"document_text.html": {
"components/annotation_surface.js",