Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: re-embed documents after switching the embedding model (#13702)

Long Yixingb9c93fee361b
diff --git a/studio/backend/core/rag/config.py b/studio/backend/core/rag/config.py
index 59ab8f80dab..b978da955c1 100644
--- a/studio/backend/core/rag/config.py
+++ b/studio/backend/core/rag/config.py
@@ -181,14 +181,17 @@ def embedding_identity_matches(stored: str | None, current: str) -> bool:
return stored == (embedding_identity_model(current) or current)
-def effective_embedding_model() -> str:
+def effective_embedding_model(fresh: bool = False) -> str:
"""The embedding model actually in use: the persisted Settings override when
one is stored, else ``EMBEDDING_MODEL`` (env/default). Read at call time so a
- Settings change applies without a restart."""
+ Settings change applies without a restart; ``fresh`` also skips the short cache and
+ raises rather than fall back."""
try:
from utils.embedding_model_settings import get_rag_embedding_model
- return get_rag_embedding_model()
+ return get_rag_embedding_model(fresh = fresh)
except Exception: # noqa: BLE001 - settings store unavailable (tests, early boot)
+ if fresh:
+ raise
return EMBEDDING_MODEL
diff --git a/studio/backend/core/rag/reembed.py b/studio/backend/core/rag/reembed.py
new file mode 100644
index 00000000000..f62ce305e6d
--- /dev/null
+++ b/studio/backend/core/rag/reembed.py
@@ -0,0 +1,270 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Re-embed documents indexed under a different embedder than the current one.
+
+Dense search skips such documents, so after an embedding model switch they are reachable by
+keyword search only. This re-encodes each one's stored chunk text and swaps its vectors in place,
+keeping document and chunk ids (citations keep resolving) and needing no source file, OCR or
+captioning. One job per account; it follows the current model, so a switch mid-job is absorbed.
+"""
+
+from __future__ import annotations
+
+from core.training.account_jobs import account_is_retired, account_key
+from utils.account_context import account_thread
+import logging
+import threading
+import uuid
+
+from core.rag import account_db as rag_db
+
+from . import config, embeddings, ingestion, store
+
+logger = logging.getLogger(__name__)
+
+# An embedder that cannot load fails every document; stop instead of failing them one by one.
+_MAX_CONSECUTIVE_FAILURES = 3
+_RETIRE_JOIN_SECONDS = 10.0
+
+_jobs: dict = {}
+_lock = threading.Lock()
+
+
+class _Stopped(Exception):
+ pass
+
+
+class _Job:
+ def __init__(self) -> None:
+ self.id = str(uuid.uuid4())
+ self.status = "running"
+ self.done = 0
+ self.failed = 0
+ self.remaining = 0
+ self.clipped_chunks = 0
+ self.current = 0.0
+ self.error: str | None = None
+ self.stop = threading.Event()
+ self.thread: threading.Thread | None = None
+
+ def snapshot(self) -> dict:
+ finished = self.done + self.failed
+ total = finished + self.remaining
+ return {
+ "id": self.id,
+ "status": self.status,
+ "done": self.done,
+ "failed": self.failed,
+ "remaining": self.remaining,
+ "clipped_chunks": self.clipped_chunks,
+ "progress": 1.0 if not total else min(1.0, (finished + self.current) / total),
+ "error": self.error,
+ }
+
+
+def _stale_documents(conn, identity: str) -> list[dict]:
+ """Completed, searchable documents whose vectors another embedder wrote; files before
+ archived conversation turns, newest first."""
+ # Chunks, not num_chunks, which archived conversation turns leave at 0.
+ rows = conn.execute(
+ "SELECT id, scope, embedding_model FROM documents d WHERE status='completed' "
+ "AND EXISTS (SELECT 1 FROM chunks c WHERE c.document_id=d.id) AND NOT EXISTS "
+ "(SELECT 1 FROM linked_folder_retired_scopes r WHERE r.scope=d.scope) "
+ "AND (d.linked_folder_id IS NULL OR EXISTS "
+ "(SELECT 1 FROM linked_folder_files ff WHERE ff.document_id=d.id)) "
+ "ORDER BY d.scope LIKE 'convarchive#_%' ESCAPE '#', d.created_at DESC, d.rowid DESC"
+ ).fetchall()
+ return [
+ dict(r)
+ for r in rows
+ if not config.embedding_identity_matches(r["embedding_model"], identity)
+ ]
+
+
+def stale_counts() -> dict:
+ """How many uploaded documents and archived conversation turns need re-embedding."""
+ identity = embeddings.embedding_identity(config.effective_embedding_model())
+ conn = rag_db.get_connection()
+ try:
+ rows = _stale_documents(conn, identity)
+ finally:
+ conn.close()
+ archived = sum(r["scope"].startswith(store.CONVERSATION_ARCHIVE_PREFIX) for r in rows)
+ return {"documents": len(rows) - archived, "archived": archived}
+
+
+def _clip(text: str, count, limit: int | None) -> tuple[str, bool]:
+ """The longest prefix of ``text`` the embedder accepts. Chunks were sized with the previous
+ model's tokenizer, and llama-server refuses an input past its batch instead of truncating."""
+ if not limit or count(text) <= limit:
+ return text, False
+ lo, hi = 0, len(text)
+ while lo < hi:
+ mid = (lo + hi + 1) // 2
+ if count(text[:mid]) <= limit:
+ lo = mid
+ else:
+ hi = mid - 1
+ return text[:lo], True
+
+
+def _reembed_document(job: _Job, doc: dict, model: str) -> bool:
+ conn = rag_db.get_connection()
+ try:
+ rows = conn.execute(
+ "SELECT id, text FROM chunks WHERE document_id=? ORDER BY chunk_index", (doc["id"],)
+ ).fetchall()
+ finally:
+ conn.close()
+ # Per document: an ST failure can hand the model to llama-server, whose tokenizer and limit differ.
+ count, limit = embeddings.token_counter(model), embeddings.max_tokens(model)
+ texts = []
+ clipped = 0
+ for row in rows:
+ text, was_clipped = _clip(row["text"], count, limit)
+ texts.append(text)
+ clipped += was_clipped
+
+ def on_progress(done: int, total: int) -> None:
+ if job.stop.is_set() or account_is_retired():
+ raise _Stopped
+ job.current = done / total
+
+ vectors, identity = ingestion._embed_all(texts, model, on_progress)
+ conn = rag_db.get_connection()
+ try:
+ swapped = store.replace_document_vectors(
+ conn,
+ doc["id"],
+ doc["embedding_model"],
+ [r["id"] for r in rows],
+ vectors,
+ identity,
+ model,
+ )
+ finally:
+ conn.close()
+ if swapped:
+ job.done += 1
+ job.remaining -= 1
+ job.clipped_chunks += clipped
+ if clipped:
+ logger.info(
+ "re-embedded document %s with %d of %d chunks clipped to %s tokens",
+ doc["id"],
+ clipped,
+ len(rows),
+ limit,
+ )
+ return swapped
+
+
+def _run(job: _Job) -> None:
+ # Per model: a failed document is not retried; a refused one only once the row it read changes.
+ failed: set[tuple[str, str]] = set()
+ refused: set[tuple[str, str | None, str]] = set()
+ failures = 0
+ try:
+ while True:
+ if job.stop.is_set() or account_is_retired():
+ raise _Stopped
+ model = config.effective_embedding_model()
+ identity = embeddings.embedding_identity(model)
+ conn = rag_db.get_connection()
+ try:
+ pending = [
+ d
+ for d in _stale_documents(conn, identity)
+ if (d["id"], identity) not in failed
+ and (d["id"], d["embedding_model"], identity) not in refused
+ ]
+ finally:
+ conn.close()
+ job.remaining = len(pending)
+ if not pending:
+ job.status = "completed"
+ return
+ doc = pending[0]
+ job.current = 0.0
+ try:
+ if not _reembed_document(job, doc, model):
+ refused.add((doc["id"], doc["embedding_model"], identity))
+ failures = 0
+ except _Stopped:
+ raise
+ except embeddings.EmbeddingModelDownloadRequiredError as exc:
+ # The model, not the document: every other document would fail the same way.
+ job.error = str(exc)
+ job.status = "failed"
+ return
+ except Exception as exc: # noqa: BLE001 - one bad document must not end the job
+ logger.warning("re-embedding document %s failed", doc["id"], exc_info = True)
+ failed.add((doc["id"], identity))
+ job.failed += 1
+ job.remaining -= 1
+ job.error = str(exc)
+ failures += 1
+ if failures >= _MAX_CONSECUTIVE_FAILURES:
+ job.status = "failed"
+ return
+ except _Stopped:
+ job.status = "cancelled"
+ except Exception as exc: # noqa: BLE001 - surface any failure to the client
+ logger.exception("re-embed job %s failed", job.id)
+ job.error = str(exc)
+ job.status = "failed"
+ finally:
+ job.current = 0.0
+
+
+def start() -> dict:
+ """Start re-embedding this account's stale documents, or return the job already running."""
+ if account_is_retired():
+ raise RuntimeError("Account is retired")
+ key = account_key("reembed")
+ with _lock:
+ job = _jobs.get(key)
+ if job is not None and job.status == "running":
+ return job.snapshot()
+ job = _Job()
+ job.remaining = sum(stale_counts().values())
+ job.thread = account_thread(target = _run, args = (job,), daemon = True)
+ _jobs[key] = job
+ # Before the worker runs: a job that ends at once must still read as started to the client.
+ started = job.snapshot()
+ # Under the lock, so retirement never finds a registered job it cannot join yet.
+ job.thread.start()
+ return started
+
+
+def status() -> dict | None:
+ with _lock:
+ job = _jobs.get(account_key("reembed"))
+ return job.snapshot() if job is not None else None
+
+
+def cancel() -> dict | None:
+ with _lock:
+ job = _jobs.get(account_key("reembed"))
+ if job is None:
+ return None
+ job.stop.set()
+ return job.snapshot()
+
+
+def retire_account_reembed() -> None:
+ """Stop this account's job before its storage moves."""
+ key = account_key("reembed")
+ with _lock:
+ job = _jobs.get(key)
+ if job is None or job.thread is None:
+ return
+ job.stop.set()
+ if job.thread is not threading.current_thread():
+ job.thread.join(timeout = _RETIRE_JOIN_SECONDS)
+ if job.thread.is_alive():
+ # Left registered, so a retried retirement waits for it again.
+ raise RuntimeError("Retired account re-embed job has not stopped")
+ with _lock:
+ _jobs.pop(key, None)
diff --git a/studio/backend/core/rag/store.py b/studio/backend/core/rag/store.py
index 8e7ecd48c5c..58a8b89389a 100644
--- a/studio/backend/core/rag/store.py
+++ b/studio/backend/core/rag/store.py
@@ -482,7 +482,7 @@ def add_chunks(
``vectors`` parallels ``chunks``; optional ``regions`` (also parallel) holds
per-chunk PDF highlight rects, stored as JSON."""
if len(vectors):
- rag_db.ensure_vec(conn, len(vectors[0]))
+ rag_db.ensure_vec(conn, len(vectors[0]), document_id)
vec_rowids: list[int] = []
for i, (chunk, vector) in enumerate(zip(chunks, vectors)):
chunk_id = f"{document_id}:{chunk.chunk_index}"
@@ -520,10 +520,79 @@ def add_chunks(
(scope, chunk_id, _f32(vector)),
).lastrowid
)
+ # Another writer's width change may have marked this document while it was encoding.
+ rag_db.restore_dropped_identity(conn, document_id)
conn.commit()
_remember_vec_rowids(conn, document_id, vec_rowids)
+def replace_document_vectors(
+ conn: sqlite3.Connection,
+ document_id: str,
+ stale_model: str | None,
+ chunk_ids: list[str],
+ vectors,
+ identity: str,
+ model_name: str,
+) -> bool:
+ """Swap a document's vectors in place and stamp ``identity``, keeping its id and chunk ids.
+
+ Writes only while the row is still the one that was encoded: present, still under
+ ``stale_model``, with the same chunks, and ``model_name`` still the configured model. A delete,
+ a re-upload, another re-embed or a model switch in between wins, and False is returned."""
+ conn.execute("BEGIN IMMEDIATE")
+ try:
+ row = conn.execute(
+ "SELECT scope, embedding_model FROM documents WHERE id=?", (document_id,)
+ ).fetchone()
+ current = [
+ r["id"]
+ for r in conn.execute(
+ "SELECT id FROM chunks WHERE document_id=? ORDER BY chunk_index", (document_id,)
+ )
+ ]
+ if (
+ row is None
+ or row["embedding_model"] != stale_model
+ or current != list(chunk_ids)
+ or len(vectors) != len(current)
+ or not current
+ # Uncached, under the write lock: old-width vectors would drop every row the new model wrote.
+ or config.effective_embedding_model(fresh = True) != model_name
+ ):
+ conn.rollback()
+ return False
+ scope = row["scope"]
+ rag_db.ensure_vec(conn, len(vectors[0]), document_id)
+ # One partition scan for the document's rows ('; sorts right after ':'), then delete by rowid.
+ stale_rowids = [
+ r["rowid"]
+ for r in conn.execute(
+ "SELECT rowid FROM chunks_vec WHERE scope=? AND chunk_id > ? AND chunk_id < ?",
+ (scope, f"{document_id}:", f"{document_id};"),
+ )
+ ]
+ for start in range(0, len(stale_rowids), _ID_BATCH):
+ batch = stale_rowids[start : start + _ID_BATCH]
+ conn.execute(
+ f"DELETE FROM chunks_vec WHERE rowid IN ({','.join('?' * len(batch))})", batch
+ )
+ rowids = [
+ conn.execute(
+ "INSERT INTO chunks_vec(scope, chunk_id, embedding) VALUES(?,?,?)",
+ (scope, chunk_id, _f32(vector)),
+ ).lastrowid
+ for chunk_id, vector in zip(current, vectors)
+ ]
+ conn.execute("UPDATE documents SET embedding_model=? WHERE id=?", (identity, document_id))
+ conn.commit()
+ except Exception:
+ conn.rollback()
+ raise
+ _remember_vec_rowids(conn, document_id, rowids)
+ return True
+
+
def delete_document(
conn: sqlite3.Connection,
document_id: str,
@@ -843,6 +912,19 @@ def search_dense(
written before identities carried a backend match on the model name alone, and
NULL-model legacy documents are assumed current, matching the ingestion dedupe
rule."""
+ # One snapshot for the KNN and the identity filter, as in search_lexical: a re-embed swap committed
+ # between them would pass an old-space distance under the new identity.
+ own_read_txn = not conn.in_transaction
+ if own_read_txn:
+ conn.execute("BEGIN")
+ try:
+ return _search_dense(conn, scope, vector, k, embedding_model)
+ finally:
+ if own_read_txn:
+ conn.commit()
+
+
+def _search_dense(conn: sqlite3.Connection, scope, vector, k: int, embedding_model: str | None):
if not rag_db.vec_table_exists(conn):
return []
dim = rag_db.vec_table_dim(conn)
@@ -945,7 +1027,9 @@ def count_untagged_documents(conn: sqlite3.Connection) -> int:
behind the user's back, so this exists to say how many are in that state."""
tags = " ".join(f"AND embedding_model NOT LIKE '{t}:%'" for t in config.EMBEDDING_IDENTITY_TAGS)
row = conn.execute(
- f"SELECT COUNT(*) AS n FROM documents WHERE embedding_model IS NOT NULL {tags}"
+ f"SELECT COUNT(*) AS n FROM documents WHERE embedding_model IS NOT NULL {tags} "
+ "AND embedding_model NOT LIKE ?",
+ (rag_db.VECTORS_DROPPED + "%",),
).fetchone()
return int(row["n"]) if row else 0
diff --git a/studio/backend/core/training/account_jobs.py b/studio/backend/core/training/account_jobs.py
index f548f126d27..bc891e0b809 100644
--- a/studio/backend/core/training/account_jobs.py
+++ b/studio/backend/core/training/account_jobs.py
@@ -414,7 +414,7 @@ def retire_account_jobs(account: AccountContext) -> None:
from hub.services.models.downloads import (
retire_account_downloads as retire_account_model_downloads,
)
- from core.rag import folder_sync, ingestion
+ from core.rag import folder_sync, ingestion, reembed
from core.research_runs import retire_account_research
from routes.inference import retire_stt_downloads
@@ -423,6 +423,7 @@ def retire_account_jobs(account: AccountContext) -> None:
retire_account_model_downloads,
retire_stt_downloads,
ingestion.retire_account_ingestions,
+ reembed.retire_account_reembed,
folder_sync.retire_account_sync,
lambda: retire_account_research(account),
):
diff --git a/studio/backend/routes/rag.py b/studio/backend/routes/rag.py
index 4b02b100fbf..0bc87ca9f11 100644
--- a/studio/backend/routes/rag.py
+++ b/studio/backend/routes/rag.py
@@ -33,7 +33,7 @@ from fastapi.responses import FileResponse, StreamingResponse
from pydantic import BaseModel, Field
from auth.authentication import get_current_subject, request_admitted_without_credential
-from core.rag import config, folder_sync, ingestion, retrieval, store
+from core.rag import config, folder_sync, ingestion, reembed, retrieval, store
from storage import rag_db
from utils.account_context import (
OWNER,
@@ -848,6 +848,52 @@ def delete_document(document_id: str, subject: str = Depends(get_current_subject
conn.close()
+def _reembed_view(job: dict | None) -> dict | None:
+ if job is None:
+ return None
+ return {
+ "id": job["id"],
+ "status": job["status"],
+ "done": job["done"],
+ "failed": job["failed"],
+ "remaining": job["remaining"],
+ "clippedChunks": job["clipped_chunks"],
+ "progress": job["progress"],
+ "error": job["error"],
+ }
+
+
[email protected]("/reembed")
+def reembed_status(subject: str = Depends(get_current_subject)) -> dict:
+ """Documents indexed under another embedder than the current one, and the re-embed job."""
+ _require_rag()
+ # Job first: one ending between the reads still says running, so the client polls for the counts.
+ job = _reembed_view(reembed.status())
+ with _rag_unavailable_as_503():
+ stale = reembed.stale_counts()
+ return {
+ "staleDocuments": stale["documents"],
+ "staleArchived": stale["archived"],
+ "job": job,
+ }
+
+
[email protected]("/reembed")
+def start_reembed(subject: str = Depends(get_current_subject)) -> dict:
+ _require_rag()
+ with _rag_unavailable_as_503():
+ return {"job": _reembed_view(reembed.start())}
+
+
[email protected]("/reembed/cancel")
+def cancel_reembed(subject: str = Depends(get_current_subject)) -> dict:
+ _require_rag()
+ job = reembed.cancel()
+ if job is None:
+ raise HTTPException(status_code = 404, detail = "No re-embed job")
+ return {"job": _reembed_view(job)}
+
+
@router.get("/jobs/{job_id}")
def job_status(job_id: str, subject: str = Depends(get_current_subject)) -> dict:
_require_rag()
diff --git a/studio/backend/storage/rag_db.py b/studio/backend/storage/rag_db.py
index 2367fae688d..e85a6284c26 100644
--- a/studio/backend/storage/rag_db.py
+++ b/studio/backend/storage/rag_db.py
@@ -372,20 +372,34 @@ def vec_table_dim(conn: sqlite3.Connection) -> int | None:
return int(m.group(1)) if m else None
-def ensure_vec(conn: sqlite3.Connection, dim: int) -> None:
+# Prefixed to the identity of a document whose vectors were dropped, so it matches no embedder.
+VECTORS_DROPPED = "vectors-dropped:"
+
+
+def ensure_vec(
+ conn: sqlite3.Connection,
+ dim: int,
+ writing: str | None = None,
+) -> None:
"""Create the dense ``chunks_vec`` table once the embedding dim is known (vec0 bakes it into the column
type). A width change (embedding model switched in Settings) drops the table: the old vectors live in a
- foreign space and would only block inserts, while lexical search keeps serving old chunks until they are
- re-uploaded."""
+ foreign space and would only block inserts. Lexical search keeps serving the old chunks, and every
+ document but ``writing``, completed or not (ingestion commits its vectors before completing), gets
+ ``VECTORS_DROPPED`` prefixed to its identity until it writes vectors again or is re-embedded."""
existing = vec_table_dim(conn)
if existing is not None and existing != int(dim):
logger.warning(
"chunks_vec dim changed %d -> %d (embedding model switched); dropping "
- "stale dense index. Re-upload documents to restore dense search.",
+ "stale dense index. Re-embed documents to restore dense search.",
existing,
int(dim),
)
conn.execute("DROP TABLE chunks_vec")
+ conn.execute(
+ "UPDATE documents SET embedding_model=? || COALESCE(embedding_model, '') "
+ "WHERE id IS NOT ? AND COALESCE(embedding_model, '') NOT LIKE ?",
+ (VECTORS_DROPPED, writing, VECTORS_DROPPED + "%"),
+ )
conn.execute(
f"CREATE VIRTUAL TABLE IF NOT EXISTS chunks_vec USING vec0("
f"scope TEXT partition key, "
@@ -394,6 +408,15 @@ def ensure_vec(conn: sqlite3.Connection, dim: int) -> None:
)
+def restore_dropped_identity(conn: sqlite3.Connection, document_id: str) -> None:
+ """Undo ``ensure_vec``'s prefix once ``document_id`` has written vectors into the current table."""
+ conn.execute(
+ "UPDATE documents SET embedding_model=NULLIF(substr(embedding_model, ?), '') "
+ "WHERE id=? AND embedding_model LIKE ?",
+ (len(VECTORS_DROPPED) + 1, document_id, VECTORS_DROPPED + "%"),
+ )
+
+
def vec_table_exists(conn: sqlite3.Connection) -> bool:
"""True if the dense ``chunks_vec`` table exists."""
row = conn.execute(
diff --git a/studio/backend/tests/test_embedding_model_settings.py b/studio/backend/tests/test_embedding_model_settings.py
index ecb25cfac10..007d897e5a4 100644
--- a/studio/backend/tests/test_embedding_model_settings.py
+++ b/studio/backend/tests/test_embedding_model_settings.py
@@ -404,6 +404,17 @@ def test_pinning_a_model_memoizes_what_was_resolved_for_it(settings_store, monke
assert ems.get_stored_backend("org/embedder-a") == "llama-server"
+def test_a_fresh_read_sees_a_save_from_another_process(settings_store, monkeypatch):
+ ems.set_rag_embedding_model("org/first")
+ assert ems.get_rag_embedding_model() == "org/first"
+ settings_store[ems.EMBEDDING_MODEL_SETTING_KEY] = "org/second" # no invalidation here
+ assert ems.get_rag_embedding_model() == "org/first"
+ assert rag_config.effective_embedding_model(fresh = True) == "org/second"
+ monkeypatch.setattr("storage.studio_db.get_app_settings", lambda keys: 1 / 0)
+ with pytest.raises(ZeroDivisionError): # an unconfirmed model never passes a fresh check
+ rag_config.effective_embedding_model(fresh = True)
+
+
def test_the_per_identity_cache_is_bounded(settings_store, monkeypatch):
ems._cached.clear()
ems._generation.clear()
diff --git a/studio/backend/tests/test_rag_reembed.py b/studio/backend/tests/test_rag_reembed.py
new file mode 100644
index 00000000000..985aacdd67b
--- /dev/null
+++ b/studio/backend/tests/test_rag_reembed.py
@@ -0,0 +1,221 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import contextlib
+import hashlib
+import threading
+
+import pytest
+
+from core.rag import chunking, config, embeddings, ingestion, reembed, retrieval, store
+from storage import rag_db
+
+OLD, NEW, NEWER = "org/old-embedder", "org/new-embedder", "org/newer-embedder"
+WIDTHS = {OLD: 8, NEW: 12, NEWER: 12} # same width: NEWER's rewrite must remove NEW's rows
+
+
+def models(rag_home, stub_embeddings, monkeypatch):
+ state = {"model": OLD, "encoded": [], "fail": lambda texts: False}
+
+ def encode(texts, model_name, **_):
+ if model_name != OLD and (failure := state["fail"](texts)):
+ raise failure if isinstance(failure, Exception) else RuntimeError("embedder down")
+ state["encoded"].append((model_name, list(texts)))
+ digests = (hashlib.sha256(f"{model_name}{t}".encode()).digest() for t in texts)
+ return [[b / 255.0 + 1e-3 for b in d[: WIDTHS[model_name]]] for d in digests]
+
+ monkeypatch.setattr(embeddings, "encode", encode)
+ monkeypatch.setattr(embeddings, "max_tokens", lambda model_name = None: None)
+ monkeypatch.setattr(reembed, "_jobs", {})
+ monkeypatch.setattr(reembed, "_RETIRE_JOIN_SECONDS", 0.2)
+ current = lambda fresh = False: state["model"] if fresh else state.get("cached", state["model"])
+ monkeypatch.setattr(config, "effective_embedding_model", current)
+ return state
+
+
+def _connect():
+ return contextlib.closing(rag_db.get_connection())
+
+
+def _ingest(tmp_path, scope, name, text):
+ (tmp_path / name).write_text(text, encoding = "utf-8")
+ return ingestion.start_ingestion(
+ scope, None, None, name, str(tmp_path / name), model_name = OLD, background = False
+ )[0]
+
+
+def _row(document_id):
+ sql = "SELECT id, text FROM chunks WHERE document_id=? ORDER BY chunk_index"
+ with _connect() as c:
+ chunks = [tuple(r) for r in c.execute(sql, (document_id,))]
+ return store.get_document(c, document_id)["embedding_model"], chunks
+
+
+def _run_job():
+ reembed.start()
+ reembed._jobs["reembed"].thread.join(timeout = 10)
+ return reembed.status()
+
+
+def test_stale_documents_regain_dense_search_under_the_same_ids(models, tmp_path, monkeypatch):
+ monkeypatch.setattr(config, "CHUNK_TOKENS", 3)
+ scope = store.project_scope("P1")
+ first = _ingest(tmp_path, scope, "a.txt", "alpha bravo charlie")
+ second = _ingest(tmp_path, scope, "b.txt", "kilo lima mike\n\ndelta echo foxtrot")
+ turn = _ingest(tmp_path, store.conversation_archive_scope("T1"), "turn.txt", "golf hotel")
+ chunks = [_row(d)[1] for d in (first, second)]
+ with _connect() as c: # as archive_turns writes it
+ store.set_document_status(c, turn, "completed", num_chunks = 0)
+ models["model"] = NEW
+ assert reembed.stale_counts() == {"documents": 2, "archived": 1}
+ assert ((job := _run_job())["status"], job["done"], job["failed"]) == ("completed", 3, 0)
+ assert reembed.stale_counts() == {"documents": 0, "archived": 0}
+ assert [_row(first), _row(second)] == [(embeddings.embedding_identity(NEW), c) for c in chunks]
+ with _connect() as c:
+ hits = retrieval.retrieve_dense(c, scope, "delta echo foxtrot", k = 5, model_name = NEW)
+ assert hits[0].chunk_id == chunks[1][1][0]
+
+
+def test_failures_keep_the_old_index_and_only_a_streak_ends_the_job(models, tmp_path, monkeypatch):
+ monkeypatch.setattr(reembed, "_MAX_CONSECUTIVE_FAILURES", 2)
+ scope = store.kb_scope("K1")
+ broken = _ingest(tmp_path, scope, "broken.txt", "poison alpha")
+ healthy = _ingest(tmp_path, scope, "ok.txt", "bravo charlie")
+ _ingest(tmp_path, scope, "broken2.txt", "poison bravo")
+ original = (rag_db.VECTORS_DROPPED + embeddings.embedding_identity(OLD), _row(broken)[1])
+ models.update(model = NEW, fail = lambda texts: any("poison" in t for t in texts))
+ assert ((job := _run_job())["status"], job["done"], job["failed"]) == ("completed", 1, 2)
+ assert (_row(broken), _row(healthy)[0]) == (original, embeddings.embedding_identity(NEW))
+ models["fail"] = lambda texts: True
+ job = _run_job()
+ assert (job["status"], job["remaining"], job["error"]) == ("failed", 0, "embedder down")
+ models["fail"] = lambda texts: embeddings.EmbeddingModelDownloadRequiredError("gone")
+ assert ((job := _run_job())["status"], job["failed"], job["error"]) == ("failed", 0, "gone")
+
+
+def test_a_model_switch_mid_job_redoes_what_the_previous_model_wrote(models, tmp_path):
+ scope = store.kb_scope("K3")
+ ids = [_ingest(tmp_path, scope, f"{n}.txt", f"text {n}") for n in "ab"]
+ switch_while_a_encodes = lambda texts: texts == ["text a"] and models.update(model = NEWER)
+ models.update(model = NEW, fail = switch_while_a_encodes)
+ assert _run_job()["status"] == "completed"
+ assert {_row(d)[0] for d in ids} == {embeddings.embedding_identity(NEWER)}
+ with _connect() as c:
+ assert c.execute("SELECT COUNT(*) FROM chunks_vec").fetchone()[0] == 2
+ hit = retrieval.retrieve_dense(c, scope, "text b", k = 1, model_name = NEWER)[0]
+ assert (hit.chunk_id, round(hit.score, 4)) == (f"{ids[1]}:0", 1.0)
+
+
+def test_vectors_superseded_mid_encode_are_not_written_over_the_new_index(models, tmp_path):
+ scope = store.kb_scope("K8")
+ [_ingest(tmp_path, scope, f"{n}.txt", f"text {n}") for n in "ab"]
+ switch_in_another_process = lambda texts: "cached" not in models and (
+ _ingest(tmp_path, scope, "c.txt", "text c") and models.update(model = OLD, cached = NEW)
+ )
+ models.update(model = NEW, fail = switch_in_another_process)
+ assert ((job := _run_job())["status"], job["done"]) == ("completed", 0)
+ with _connect() as c:
+ assert c.execute("SELECT COUNT(*) FROM chunks_vec").fetchone()[0] == 3
+
+
+def test_documents_a_width_change_stripped_stay_stale_after_switching_back(models, tmp_path):
+ ids = [_ingest(tmp_path, store.kb_scope("K9"), f"{n}.txt", f"text {n}") for n in "ab"]
+ models.update(model = NEW, fail = lambda t: t == ["text a"] and reembed.cancel() and False)
+ assert _run_job()["status"] == "cancelled" # b re-embedded, which dropped a's vectors
+ models["model"] = OLD
+ assert (reembed.stale_counts()["documents"], _run_job()["done"]) == (2, 2)
+ old, chunk = embeddings.embedding_identity(OLD), chunking.Chunk("text b", 2, None, 0, 0, 0, 6)
+ with _connect() as c:
+ store.set_document_status(c, ids[1], "pending") # still being ingested
+ rag_db.ensure_vec(c, 4, ids[0]) or rag_db.ensure_vec(c, 6, ids[0]) # ids[0] is writing
+ assert store.get_document(c, ids[1])["embedding_model"] == rag_db.VECTORS_DROPPED + old
+ assert store.count_untagged_documents(c) == 0
+ store.add_chunks(c, store.kb_scope("K9"), ids[1], [chunk], [[0.5] * 6]) # its writer lands
+ assert [_row(d)[0] for d in ids] == [old, old]
+
+
+def test_cancel_and_retirement_stop_before_the_document_in_flight_is_written(models, tmp_path):
+ reembed.retire_account_reembed() # no job yet
+ document_id = _ingest(tmp_path, store.kb_scope("K6"), "a.txt", "alpha bravo")
+ original = _row(document_id)
+ models.update(model = NEW, fail = lambda texts: reembed.cancel() and False)
+ assert (_run_job()["status"], _row(document_id)) == ("cancelled", original)
+ entered, release = threading.Event(), threading.Event()
+ models["fail"] = lambda texts: entered.set() or not release.wait(5)
+ assert reembed.start()["remaining"] == 1 and entered.wait(5)
+ with pytest.raises(RuntimeError, match = "not stopped"):
+ reembed.retire_account_reembed()
+ job = reembed._jobs["reembed"] # still registered, so the retry below waits for it
+ release.set()
+ reembed.retire_account_reembed()
+ assert (job.thread.is_alive(), job.status, reembed.status()) == (False, "cancelled", None)
+ assert _row(document_id) == original
+
+
+def test_chunks_past_the_limit_embed_a_prefix(models, tmp_path, monkeypatch):
+ for i, text in enumerate(("six seven eight", "ten eleven twelve", "one two three four five")):
+ _ingest(tmp_path, store.kb_scope("K4"), f"{i}.txt", text)
+ limits = iter([3, 3, 2]) # read per document, newest first
+ monkeypatch.setattr(embeddings, "max_tokens", lambda model_name = None: next(limits))
+ models["model"] = NEW
+ assert _run_job()["clipped_chunks"] == 2
+ sent = [t for m, t in models["encoded"] if m == NEW]
+ assert sent == [["one two three "], ["ten eleven twelve"], ["six seven "]]
+
+
+def test_a_document_changed_while_it_encodes_is_not_overwritten_but_redone(models, tmp_path):
+ [_ingest(tmp_path, store.kb_scope("K5"), f"{n}.txt", f"text {n}") for n in "ab"]
+ widen = lambda: rag_db.ensure_vec(c := rag_db.get_connection(), 12) or c.commit() or c.close()
+ models.update(model = NEW, widen = widen, fail = lambda t: models.pop("widen", bool)())
+ assert ((job := _run_job())["status"], job["done"]) == ("completed", 2)
+ sent = [t for m, [t] in models["encoded"] if m == NEW]
+ assert sent == ["text b", "text b", "text a"] # widened while b encoded: b re-read
+
+
+def test_retirement_racing_a_start_waits_for_its_worker(models, tmp_path, monkeypatch):
+ _ingest(tmp_path, store.kb_scope("K7"), "a.txt", "alpha bravo")
+ models["model"] = NEW
+ errors, racers = [], []
+
+ def retire():
+ try:
+ reembed.retire_account_reembed()
+ except Exception as exc:
+ errors.append(exc)
+
+ class Racing(threading.Thread):
+ def start(self):
+ racers.append(racer := threading.Thread(target = retire))
+ racer.start()
+ racer.join(0.3) # retirement lands between publishing the job and starting its worker
+ super().start()
+
+ monkeypatch.setattr(reembed, "account_thread", lambda **kw: Racing(**kw))
+ reembed.start()
+ racers[0].join(5)
+ assert errors == [] and reembed.status() is None
+
+
+def test_a_swap_committed_mid_search_cannot_pass_an_old_space_score(models, tmp_path, monkeypatch):
+ scope = store.kb_scope("K9")
+ doc = _ingest(tmp_path, scope, "a.txt", "text a")
+ models["model"] = NEW
+ assert _run_job()["status"] == "completed"
+ models["model"] = NEWER # same width: NEW's vectors stay in the table until swapped
+ original = store._drop_incompatible
+
+ def swap_between_reads(conn, *args):
+ # The swap's commit, from another connection, after the KNN read scored NEW's vector.
+ with _connect() as other:
+ other.execute(
+ "UPDATE documents SET embedding_model=? WHERE id=?",
+ (embeddings.embedding_identity(NEWER), doc),
+ )
+ other.commit()
+ return original(conn, *args)
+
+ monkeypatch.setattr(store, "_drop_incompatible", swap_between_reads)
+ with _connect() as c:
+ hits = retrieval.retrieve_dense(c, scope, "text a", k = 5, model_name = NEWER)
+ assert hits == []
diff --git a/studio/backend/utils/embedding_model_settings.py b/studio/backend/utils/embedding_model_settings.py
index f1a1bd9e83d..da43cb36da2 100644
--- a/studio/backend/utils/embedding_model_settings.py
+++ b/studio/backend/utils/embedding_model_settings.py
@@ -197,7 +197,7 @@ def get_stored_embedding_model() -> str | None:
return _get_stored_state()[0]
-def _get_stored_state() -> _StoredState:
+def _get_stored_state(fresh: bool = False) -> _StoredState:
"""Read the override and its resolved artifact association as one snapshot.
The resolution is one JSON value so its model/repo/backend can never be
@@ -208,7 +208,7 @@ def _get_stored_state() -> _StoredState:
now = time.monotonic()
with _lock:
cached = _cached.get(key)
- if cached is not None and now - cached[0] < _CACHE_TTL_S:
+ if cached is not None and now - cached[0] < _CACHE_TTL_S and not fresh:
return cached[1]
gen = _generation.get(key, 0)
try:
@@ -222,6 +222,8 @@ def _get_stored_state() -> _StoredState:
]
)
except Exception:
+ if fresh:
+ raise # a fresh read confirms the model, which a fallback cannot
# Transient store failure: keep the last known value instead of silently reverting the embed/search hot path to the default model, which would mix vector spaces mid-ingestion.
with _lock:
cached = _cached.get(key)
@@ -253,9 +255,10 @@ def _get_stored_state() -> _StoredState:
return value
-def get_rag_embedding_model() -> str:
- """Effective embedding model: persisted override, else env/default."""
- stored = _get_stored_state()
+def get_rag_embedding_model(fresh: bool = False) -> str:
+ """Effective embedding model: persisted override, else env/default. ``fresh`` skips the cache
+ and raises when the store cannot be read, for a check that must see another process's save."""
+ stored = _get_stored_state(fresh)
model = stored[0] or default_embedding_model()
# Reading this is how a job pins its model, so record the resolution here: the memo protects a pinned job only if it was populated before another model's save takes the stored record.
if stored[1] == model:
diff --git a/studio/frontend/scripts/check-bundle-budget.ts b/studio/frontend/scripts/check-bundle-budget.ts
index c24bea033bd..52727182529 100644
--- a/studio/frontend/scripts/check-bundle-budget.ts
+++ b/studio/frontend/scripts/check-bundle-budget.ts
@@ -106,8 +106,12 @@ export const BUDGET = {
// `$1$?`-style shell text literal add 6,984 B raw / 2,836 B transfer to the eager chat chunk
// (6,753,387 -> 6,760,371 B raw, 2,029,398 -> 2,032,234 B transfer against eba7641835, one machine
// and build, chunk count unchanged at 95), raised by that.
- transferBytes: 2_032_302,
- rawBytes: 6_760_750,
+ // Re-embedding documents after an embedding model switch (the save toast's action and the Settings row)
+ // adds 3,018 B raw / 905 B transfer (6,760,371 -> 6,763,389 B raw, 2,032,234 -> 2,033,139 B transfer
+ // against 525f3ceae, one machine and build, Node 24, chunk count unchanged at 95). Lazy-loading its store
+ // from both save sites cost 0.3 KB transfer more in chunk overhead, so the budget is raised by that growth.
+ transferBytes: 2_033_207,
+ rawBytes: 6_763_768,
};
// The chunk count is reported but not budgeted. Splitting a page out of the entry raises it while lowering the
diff --git a/studio/frontend/src/features/rag/api/rag-api.ts b/studio/frontend/src/features/rag/api/rag-api.ts
index 9af9e4282bc..aaf0dc65755 100644
--- a/studio/frontend/src/features/rag/api/rag-api.ts
+++ b/studio/frontend/src/features/rag/api/rag-api.ts
@@ -16,6 +16,8 @@ import type {
LinkedFolder,
LinkedFolderScope,
RagDocument,
+ ReembedJob,
+ ReembedStatus,
UploadedDocument,
} from "../types/rag";
import { noteRagAvailability, noteRagResponse } from "./rag-availability";
@@ -754,6 +756,18 @@ export async function deleteDocument(
return result;
}
+export function getReembedStatus(): Promise<ReembedStatus> {
+ return ragRequest("/reembed");
+}
+
+export function startReembed(): Promise<{ job: ReembedJob }> {
+ return ragRequest("/reembed", { method: "POST" });
+}
+
+export function cancelReembed(): Promise<{ job: ReembedJob }> {
+ return ragRequest("/reembed/cancel", { method: "POST" });
+}
+
export function getJob(jobId: string, signal?: AbortSignal): Promise<IndexJob> {
return ragRequest(`/jobs/${encodeURIComponent(jobId)}`, { signal });
}
diff --git a/studio/frontend/src/features/rag/components/embedding-model-menu-picker.tsx b/studio/frontend/src/features/rag/components/embedding-model-menu-picker.tsx
index dc6888e11bc..2e836c26ad7 100644
--- a/studio/frontend/src/features/rag/components/embedding-model-menu-picker.tsx
+++ b/studio/frontend/src/features/rag/components/embedding-model-menu-picker.tsx
@@ -29,6 +29,7 @@ import { MenuTickIcon } from "@/lib/tick-icon";
import { toast } from "@/lib/toast";
import { cn } from "@/lib/utils";
import { embeddingMenuModels } from "../lib/embedding-menu-models";
+import { toastEmbeddingModelSaved } from "./reembed-store";
const HEADING_LINK_CLASS =
"my-0! shrink-0 cursor-pointer rounded-sm font-normal text-muted-foreground underline decoration-muted-foreground/50 underline-offset-[3px] outline-hidden transition-colors hover:text-foreground hover:decoration-foreground/60 data-[highlighted]:text-foreground data-[highlighted]:decoration-foreground/60";
@@ -149,9 +150,7 @@ export function EmbeddingModelMenuList({ onBack }: { onBack: () => void }) {
},
});
} else if (result.status === "saved") {
- toast.success(t("settings.general.rag.switched", { model: name }), {
- description: t("settings.general.rag.reindexWarning"),
- });
+ void toastEmbeddingModelSaved(t("settings.general.rag.switched", { model: name }));
}
if (mountedRef.current) onBack();
} finally {
diff --git a/studio/frontend/src/features/rag/components/reembed-store.ts b/studio/frontend/src/features/rag/components/reembed-store.ts
new file mode 100644
index 00000000000..a7df6d4a3ea
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/reembed-store.ts
@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { AUTH_SESSION_CLEARED_EVENT } from "@/features/auth";
+import { translate } from "@/i18n";
+import { toast } from "@/lib/toast";
+import { create } from "zustand";
+import { cancelReembed, getReembedStatus, startReembed } from "../api/rag-api";
+import type { ReembedJob, ReembedStatus } from "../types/rag";
+
+const POLL_MS = 1500;
+
+interface ReembedStore {
+ status: ReembedStatus | null;
+ load: () => Promise<ReembedStatus | null>;
+ start: () => Promise<void>;
+ /** Resolves false when the request failed, so Stop can be offered again. */
+ cancel: () => Promise<boolean>;
+}
+
+let pollTimer: ReturnType<typeof setTimeout> | null = null;
+/** A job seen running here, so its end is announced once. */
+let watchedJobId: string | null = null;
+let clock = 0;
+/** Replies sent before this may describe an older server state: it is when the last applied reply
+ * arrived, or when a failed start or cancel left the server's state unknown. */
+let freshAfter = 0;
+/** The shown state is known to be outdated (a dropped reply, a failed start or cancel, or the counts
+ * a finished job changed) until a reply applies; failed reads keep retrying meanwhile. */
+let reconciling = false;
+/** Replies to requests sent before this sign-out describe the account that signed out. */
+let signedOutAt = 0;
+
+/** Applies the reply unless it was sent before `freshAfter`, which would roll the job back or
+ * announce its end twice. Such a reply returns false, and the caller reads the current state. */
+async function request<T>(
+ send: () => Promise<T>,
+ apply: (value: T) => void,
+): Promise<boolean> {
+ const sentAt = ++clock;
+ try {
+ const value = await send();
+ const arrivedAt = ++clock;
+ // Sent before signing out: settled without effect, as is its failure below.
+ if (sentAt <= signedOutAt) return true;
+ if (sentAt <= freshAfter) {
+ reconciling = true;
+ return false;
+ }
+ freshAfter = arrivedAt;
+ reconciling = false;
+ apply(value);
+ return true;
+ } catch (error) {
+ if (sentAt <= signedOutAt) return true;
+ // A failed request must not end the polling that reports the job's progress and end.
+ if (watchedJobId !== null || reconciling) schedulePoll();
+ throw error;
+ }
+}
+
+function setJob(job: ReembedJob): void {
+ useReembedStore.setState((state) => ({
+ status: { staleDocuments: 0, staleArchived: 0, ...state.status, job },
+ }));
+ follow(job);
+ if (job.status !== "running") {
+ // Only a status read carries the stale counts a finished job changed.
+ reconciling = true;
+ void useReembedStore.getState().load();
+ }
+}
+
+/** Shared by every surface, so a job started from a toast shows its progress in Settings. */
+export const useReembedStore = create<ReembedStore>(() => ({
+ status: null,
+ load: async (): Promise<ReembedStatus | null> => {
+ try {
+ const applied = await request(getReembedStatus, (status) => {
+ useReembedStore.setState({ status });
+ follow(status.job);
+ });
+ return applied
+ ? useReembedStore.getState().status
+ : await useReembedStore.getState().load();
+ } catch {
+ return null;
+ }
+ },
+ start: async () => {
+ try {
+ if (!(await request(startReembed, ({ job }) => setJob(job)))) {
+ await useReembedStore.getState().load();
+ }
+ } catch (error) {
+ markOutdated();
+ toast.error(translate("settings.general.rag.reembed.startFailed"), {
+ description: error instanceof Error ? error.message : undefined,
+ });
+ }
+ },
+ cancel: async () => {
+ try {
+ if (!(await request(cancelReembed, ({ job }) => setJob(job)))) {
+ await useReembedStore.getState().load();
+ }
+ return true;
+ } catch {
+ markOutdated();
+ return false;
+ }
+ },
+}));
+
+/** A failed start or cancel may still have reached the server, so read status until a read applies. */
+function markOutdated(): void {
+ freshAfter = ++clock;
+ reconciling = true;
+ schedulePoll();
+}
+
+/** Signing out keeps this module loaded for the next account, so the job it followed is dropped. */
+function resetOnSignOut(): void {
+ if (pollTimer !== null) clearTimeout(pollTimer);
+ pollTimer = null;
+ watchedJobId = null;
+ reconciling = false;
+ signedOutAt = ++clock;
+ useReembedStore.setState({ status: null });
+}
+
+if (typeof window !== "undefined") {
+ window.addEventListener(AUTH_SESSION_CLEARED_EVENT, resetOnSignOut);
+}
+
+function schedulePoll(): void {
+ if (pollTimer !== null) clearTimeout(pollTimer);
+ pollTimer = setTimeout(() => void useReembedStore.getState().load(), POLL_MS);
+}
+
+function follow(job: ReembedJob | null): void {
+ if (pollTimer !== null) clearTimeout(pollTimer);
+ pollTimer = null;
+ if (job?.status === "running") {
+ watchedJobId = job.id;
+ schedulePoll();
+ return;
+ }
+ if (!job || job.id !== watchedJobId) return;
+ watchedJobId = null;
+ if (job.status === "failed") {
+ toast.error(translate("settings.general.rag.reembed.stopped"), {
+ description: job.error ?? undefined,
+ });
+ } else if (job.status === "completed" && job.failed > 0) {
+ toast.warning(
+ translate("settings.general.rag.reembed.finishedWithFailures", {
+ count: job.failed,
+ }),
+ { description: job.error ?? undefined },
+ );
+ } else if (job.status === "completed") {
+ toast.success(translate("settings.general.rag.reembed.finished"));
+ }
+}
+
+/** What is stale, in words; null when nothing is. */
+export function staleDescription(status: ReembedStatus): string | null {
+ if (status.staleDocuments === 1) {
+ return translate("settings.general.rag.reembed.staleOne");
+ }
+ if (status.staleDocuments > 1) {
+ return translate("settings.general.rag.reembed.staleMany", {
+ count: status.staleDocuments,
+ });
+ }
+ return status.staleArchived > 0
+ ? translate("settings.general.rag.reembed.staleArchived")
+ : null;
+}
+
+/** Offers Re-embed when the save left documents stale; reads the counts either way, for the Settings row. */
+export async function toastEmbeddingModelSaved(
+ title: string,
+ ready = true,
+): Promise<void> {
+ const status = await useReembedStore.getState().load();
+ if (status === null) {
+ toast.success(title, {
+ description: translate("settings.general.rag.reindexWarning"),
+ });
+ return;
+ }
+ const description = staleDescription(status);
+ if (!ready || description === null || status.job?.status === "running") {
+ // A running job follows the current model, so it already covers the switch.
+ toast.success(title, description ? { description } : undefined);
+ return;
+ }
+ toast.success(title, {
+ description,
+ duration: 10_000,
+ action: {
+ label: translate("settings.general.rag.reembed.action"),
+ onClick: () => void useReembedStore.getState().start(),
+ },
+ });
+}
diff --git a/studio/frontend/src/features/rag/index.ts b/studio/frontend/src/features/rag/index.ts
index 3abb6c7ea49..a22b2349766 100644
--- a/studio/frontend/src/features/rag/index.ts
+++ b/studio/frontend/src/features/rag/index.ts
@@ -13,6 +13,11 @@ export {
listKnowledgeBases,
} from "./api/rag-api";
export { saveMarkdownAsProjectSource } from "./api/save-markdown-source";
+export {
+ staleDescription,
+ toastEmbeddingModelSaved,
+ useReembedStore,
+} from "./components/reembed-store";
export { useRagAvailabilityStore } from "./api/rag-availability";
export { isLinkedFolderManaged } from "./types/rag";
export type { KnowledgeBase, RagDocument, UploadedDocument } from "./types/rag";
diff --git a/studio/frontend/src/features/rag/types/rag.ts b/studio/frontend/src/features/rag/types/rag.ts
index 78dd3e6e3df..8808089b69a 100644
--- a/studio/frontend/src/features/rag/types/rag.ts
+++ b/studio/frontend/src/features/rag/types/rag.ts
@@ -157,6 +157,23 @@ export interface FolderSyncJob {
error?: string | null;
}
+export interface ReembedJob {
+ id: string;
+ status: Exclude<JobStatus, "pending">;
+ done: number;
+ failed: number;
+ remaining: number;
+ clippedChunks: number;
+ progress: number;
+ error: string | null;
+}
+
+export interface ReembedStatus {
+ staleDocuments: number;
+ staleArchived: number;
+ job: ReembedJob | null;
+}
+
/** Missing counts (older backends) count as a change. */
export function jobChangedSources(job: FolderSyncJob): boolean {
if (
diff --git a/studio/frontend/src/features/settings/components/documents-rag-section.tsx b/studio/frontend/src/features/settings/components/documents-rag-section.tsx
index d1c628f3461..66f5ca7302d 100644
--- a/studio/frontend/src/features/settings/components/documents-rag-section.tsx
+++ b/studio/frontend/src/features/settings/components/documents-rag-section.tsx
@@ -11,6 +11,7 @@ import {
} from "@/components/ui/select";
import { useChatRuntimeStore } from "@/features/chat";
import { formatBytes, listCachedGguf, listCachedModels } from "@/features/hub";
+import { toastEmbeddingModelSaved } from "@/features/rag";
import { Spinner } from "@/components/ui/spinner";
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
import { cn } from "@/lib/utils";
@@ -40,6 +41,7 @@ import { useEmbeddingModelStore } from "../stores/embedding-model-store";
import { useEmbeddingPinsStore } from "../stores/embedding-pins-store";
import { useSettingsDialogStore } from "../stores/settings-dialog-store";
import { EmbeddingModelPicker } from "./embedding-model-picker";
+import { ReembedDocumentsRow } from "./reembed-documents-row";
import { SettingsRow } from "./settings-row";
import { SettingsSection } from "./settings-section";
@@ -173,9 +175,11 @@ export function DocumentsRagSection(): ReactElement {
);
if (!stood) return false;
setForceCandidate(null);
- toast.success(t("settings.general.rag.saved"), {
- description: t("settings.general.rag.reindexWarning"),
- });
+ // Unresolved or still to download: Re-embed would fail until the files are on disk.
+ void toastEmbeddingModelSaved(
+ t("settings.general.rag.saved"),
+ Boolean(plan && (plan.cached || !plan.downloadRepo)),
+ );
return true;
} catch (error) {
// A hard security block cannot be forced; keep "Save anyway" hidden.
@@ -497,6 +501,7 @@ export function DocumentsRagSection(): ReactElement {
</div>
</div>
</SettingsRow>
+ <ReembedDocumentsRow />
<SettingsRow
label={t("settings.general.rag.device")}
description={
diff --git a/studio/frontend/src/features/settings/components/reembed-documents-row.tsx b/studio/frontend/src/features/settings/components/reembed-documents-row.tsx
new file mode 100644
index 00000000000..93c27fbeb27
--- /dev/null
+++ b/studio/frontend/src/features/settings/components/reembed-documents-row.tsx
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Button } from "@/components/ui/button";
+import { Progress } from "@/components/ui/progress";
+import { staleDescription, useReembedStore } from "@/features/rag";
+import { useT } from "@/i18n";
+import { type ReactElement, useEffect, useState } from "react";
+import { SettingsRow } from "./settings-row";
+
+/** Offers to re-embed documents indexed under a previous embedding model; hidden when none are. */
+export function ReembedDocumentsRow(): ReactElement | null {
+ const t = useT();
+ const status = useReembedStore((s) => s.status);
+ const [stoppingJobId, setStoppingJobId] = useState<string | null>(null);
+
+ useEffect(() => {
+ void useReembedStore.getState().load();
+ }, []);
+
+ const job = status?.job ?? null;
+ const running = job?.status === "running";
+
+ const stale = status ? staleDescription(status) : null;
+ if (!running && !stale) return null;
+
+ return (
+ <SettingsRow
+ label={t("settings.general.rag.reembed.label")}
+ description={
+ running && job ? (
+ <span className="flex flex-col gap-1.5">
+ <span>
+ {t("settings.general.rag.reembed.running", {
+ done: job.done + job.failed,
+ total: job.done + job.failed + job.remaining,
+ })}
+ </span>
+ <Progress
+ value={Math.round(job.progress * 100)}
+ className="h-1.5 w-[calc(160px*var(--ui-space-scale,1))]"
+ />
+ </span>
+ ) : (
+ stale
+ )
+ }
+ >
+ {running ? (
+ <Button
+ variant="outline"
+ size="sm"
+ disabled={stoppingJobId === job?.id}
+ onClick={() => {
+ setStoppingJobId(job?.id ?? null);
+ void useReembedStore
+ .getState()
+ .cancel()
+ .then((sent) => sent || setStoppingJobId(null));
+ }}
+ >
+ {t("settings.general.rag.reembed.stop")}
+ </Button>
+ ) : (
+ <Button
+ variant="outline"
+ size="sm"
+ onClick={() => void useReembedStore.getState().start()}
+ >
+ {t("settings.general.rag.reembed.action")}
+ </Button>
+ )}
+ </SettingsRow>
+ );
+}
diff --git a/studio/frontend/src/features/settings/tabs/data-tab.tsx b/studio/frontend/src/features/settings/tabs/data-tab.tsx
index 80a7da89866..dad2d453abb 100644
--- a/studio/frontend/src/features/settings/tabs/data-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/data-tab.tsx
@@ -106,6 +106,7 @@ import {
ArchivedMediaView,
} from "../components/archived-media-dialog";
import { DocumentsRagSection } from "../components/documents-rag-section";
+import { ReembedDocumentsRow } from "../components/reembed-documents-row";
import { SettingsRow } from "../components/settings-row";
import { SettingsSection } from "../components/settings-section";
import { UploadedFilesView } from "../components/uploaded-files-dialog";
@@ -1198,6 +1199,8 @@ export function DataTab({ searchEntry }: { searchEntry?: string }) {
<LinkedFoldersManager />
</div>
) : null}
+ {/* The owner sees it beside the embedding model below. */}
+ {!isOwner ? <ReembedDocumentsRow /> : null}
</SettingsSection>
{/* Embedding model settings are installation-wide (owner-only routes). */}
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index b0d560427ff..c3142c4a316 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -1846,7 +1846,21 @@ export const ar = {
"نموذج Hugging Face أو مسار محلي يُستخدم لفهرسة مستنداتك والبحث فيها. القيمة الافتراضية هي {defaultModel}.",
searchPlaceholder: "ابحث عن أي نموذج على HF",
reindexWarning:
- "يؤثر فقط في المستندات التي تُفهرس حديثًا. أعِد رفع المستندات الحالية بعد تغيير النموذج.",
+ "يؤثر فقط في المستندات التي تُفهرس حديثًا. أعِد تضمين المستندات الحالية بعد تغيير النموذج.",
+ reembed: {
+ label: "إعادة تضمين المستندات",
+ staleOne: "فُهرس مستند واحد بنموذج تضمين مختلف، لذا يتخطاه البحث الدلالي.",
+ staleMany:
+ "عدد المستندات المفهرسة بنموذج تضمين مختلف: {count}، لذا يتخطاها البحث الدلالي.",
+ staleArchived: "فُهرس سجل الدردشة السابق بنموذج تضمين مختلف، لذا يتخطاه البحث الدلالي.",
+ running: "جارٍ إعادة التضمين: {done} من {total}",
+ action: "إعادة التضمين",
+ stop: "إيقاف",
+ startFailed: "تعذّر بدء إعادة التضمين",
+ stopped: "توقفت إعادة التضمين",
+ finished: "أُعيد تضمين المستندات",
+ finishedWithFailures: "تعذّرت إعادة تضمين {count}",
+ },
emptyError: "أدخل معرّف نموذج Hugging Face أو مسارًا محليًا.",
loadError: "فشل تحميل إعداد نموذج التضمين.",
saveError: "فشل حفظ نموذج التضمين.",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index a5ffeb66319..39152371fda 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -1870,7 +1870,23 @@ export const de = {
"Hugging-Face-Modell oder lokaler Pfad zum Indexieren und Durchsuchen Ihrer Dokumente. Standard ist {defaultModel}.",
searchPlaceholder: "Beliebiges Modell auf HF suchen",
reindexWarning:
- "Betrifft nur neu indexierte Dokumente. Laden Sie bestehende nach einer Modelländerung erneut hoch.",
+ "Betrifft nur neu indexierte Dokumente. Betten Sie bestehende nach einer Modelländerung neu ein.",
+ reembed: {
+ label: "Dokumente neu einbetten",
+ staleOne:
+ "1 Dokument wurde mit einem anderen Embedding-Modell indexiert, daher überspringt die semantische Suche es.",
+ staleMany:
+ "{count} Dokumente wurden mit einem anderen Embedding-Modell indexiert, daher überspringt die semantische Suche sie.",
+ staleArchived:
+ "Früherer Chatverlauf wurde mit einem anderen Embedding-Modell indexiert, daher überspringt die semantische Suche ihn.",
+ running: "Neu einbetten: {done} von {total}",
+ action: "Neu einbetten",
+ stop: "Stoppen",
+ startFailed: "Neu-Einbettung konnte nicht gestartet werden",
+ stopped: "Neu-Einbettung angehalten",
+ finished: "Dokumente neu eingebettet",
+ finishedWithFailures: "{count} konnten nicht neu eingebettet werden",
+ },
emptyError:
"Geben Sie eine Hugging-Face-Modell-ID oder einen lokalen Pfad ein.",
loadError:
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index eaa00751a6c..faa9faefd2e 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -1917,7 +1917,23 @@ export const en = {
"Hugging Face model or local path used to index and search your documents. Default is {defaultModel}.",
searchPlaceholder: "Search any model on HF",
reindexWarning:
- "Only affects newly indexed documents. Re-upload existing ones after changing the model.",
+ "Only affects newly indexed documents. Re-embed existing ones after changing the model.",
+ reembed: {
+ label: "Re-embed documents",
+ staleOne:
+ "1 document was indexed with a different embedding model, so semantic search skips it.",
+ staleMany:
+ "{count} documents were indexed with a different embedding model, so semantic search skips them.",
+ staleArchived:
+ "Earlier chat history was indexed with a different embedding model, so semantic search skips it.",
+ running: "Re-embedding: {done} of {total}",
+ action: "Re-embed",
+ stop: "Stop",
+ startFailed: "Couldn't start re-embedding",
+ stopped: "Re-embedding stopped",
+ finished: "Documents re-embedded",
+ finishedWithFailures: "{count} could not be re-embedded",
+ },
emptyError: "Enter a Hugging Face model id or local path.",
loadError: "Failed to load the embedding model setting.",
saveError: "Failed to save the embedding model.",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index 224cc08762f..5f57601d508 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -1865,7 +1865,23 @@ export const es = {
"Modelo de Hugging Face o ruta local usada para indexar y buscar tus documentos. El valor predeterminado es {defaultModel}.",
searchPlaceholder: "Buscar cualquier modelo en HF",
reindexWarning:
- "Solo afecta a los documentos recién indexados. Vuelve a subir los existentes tras cambiar el modelo.",
+ "Solo afecta a los documentos recién indexados. Vuelve a incrustar los existentes tras cambiar el modelo.",
+ reembed: {
+ label: "Volver a incrustar documentos",
+ staleOne:
+ "1 documento se indexó con otro modelo de embeddings, así que la búsqueda semántica lo omite.",
+ staleMany:
+ "{count} documentos se indexaron con otro modelo de embeddings, así que la búsqueda semántica los omite.",
+ staleArchived:
+ "El historial de chat anterior se indexó con otro modelo de embeddings, así que la búsqueda semántica lo omite.",
+ running: "Volviendo a incrustar: {done} de {total}",
+ action: "Volver a incrustar",
+ stop: "Detener",
+ startFailed: "No se pudo iniciar la nueva incrustación",
+ stopped: "Nueva incrustación detenida",
+ finished: "Documentos incrustados de nuevo",
+ finishedWithFailures: "No se pudieron volver a incrustar {count}",
+ },
emptyError:
"Introduce un id de modelo de Hugging Face o una ruta local.",
loadError:
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index a50af87479c..a4126cb72f6 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -1869,7 +1869,23 @@ export const fr = {
"Modèle Hugging Face ou chemin local utilisé pour indexer et rechercher vos documents. La valeur par défaut est {defaultModel}.",
searchPlaceholder: "Rechercher n'importe quel modèle sur HF",
reindexWarning:
- "N'affecte que les documents nouvellement indexés. Téléversez à nouveau les documents existants après avoir changé de modèle.",
+ "N'affecte que les documents nouvellement indexés. Ré-encodez les documents existants après avoir changé de modèle.",
+ reembed: {
+ label: "Ré-encoder les documents",
+ staleOne:
+ "1 document a été indexé avec un autre modèle d'embedding, la recherche sémantique l'ignore donc.",
+ staleMany:
+ "{count} documents ont été indexés avec un autre modèle d'embedding, la recherche sémantique les ignore donc.",
+ staleArchived:
+ "L'historique de chat antérieur a été indexé avec un autre modèle d'embedding, la recherche sémantique l'ignore donc.",
+ running: "Ré-encodage : {done} sur {total}",
+ action: "Ré-encoder",
+ stop: "Arrêter",
+ startFailed: "Impossible de lancer le ré-encodage",
+ stopped: "Ré-encodage interrompu",
+ finished: "Documents ré-encodés",
+ finishedWithFailures: "{count} n'ont pas pu être ré-encodés",
+ },
emptyError:
"Saisissez un identifiant de modèle Hugging Face ou un chemin local.",
loadError: "Échec du chargement du paramètre du modèle d'embedding.",
diff --git a/studio/frontend/src/i18n/locales/he.ts b/studio/frontend/src/i18n/locales/he.ts
index ef39a5c135a..2ff6ef1f53b 100644
--- a/studio/frontend/src/i18n/locales/he.ts
+++ b/studio/frontend/src/i18n/locales/he.ts
@@ -1958,7 +1958,21 @@ export const he = {
"מודל Hugging Face או נתיב מקומי המשמש לאינדוקס וחיפוש במסמכים שלך. ברירת המחדל היא {defaultModel}.",
searchPlaceholder: "חפש כל מודל ב-HF",
reindexWarning:
- "משפיע רק על מסמכים שיאונדקסו מעתה ואילך. העלה מחדש מסמכים קיימים לאחר שינוי המודל.",
+ "משפיע רק על מסמכים שיאונדקסו מעתה ואילך. לאחר שינוי המודל, הטמע מחדש מסמכים קיימים.",
+ reembed: {
+ label: "הטמעה מחדש של מסמכים",
+ staleOne: "מסמך אחד אונדקס במודל הטמעה אחר, ולכן החיפוש הסמנטי מדלג עליו.",
+ staleMany: "{count} מסמכים אונדקסו במודל הטמעה אחר, ולכן החיפוש הסמנטי מדלג עליהם.",
+ staleArchived:
+ "היסטוריית צ'אט קודמת אונדקסה במודל הטמעה אחר, ולכן החיפוש הסמנטי מדלג עליה.",
+ running: "מטמיע מחדש: {done} מתוך {total}",
+ action: "הטמעה מחדש",
+ stop: "עצור",
+ startFailed: "לא ניתן להתחיל הטמעה מחדש",
+ stopped: "ההטמעה מחדש נעצרה",
+ finished: "המסמכים הוטמעו מחדש",
+ finishedWithFailures: "לא ניתן היה להטמיע מחדש {count}",
+ },
emptyError: "הזן מזהה מודל ב-Hugging Face או נתיב מקומי.",
loadError: "טעינת הגדרת מודל השיבוץ נכשלה.",
saveError: "שמירת מודל השיבוץ נכשלה.",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index e5d93d6a595..094b2c8a218 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -1850,7 +1850,23 @@ export const hi = {
"आपके दस्तावेज़ों को इंडेक्स और खोजने के लिए उपयोग किया जाने वाला Hugging Face मॉडल या स्थानीय पथ। डिफ़ॉल्ट {defaultModel} है।",
searchPlaceholder: "HF पर कोई भी मॉडल खोजें",
reindexWarning:
- "केवल नए इंडेक्स किए गए दस्तावेज़ों को प्रभावित करता है। मॉडल बदलने के बाद मौजूदा दस्तावेज़ फिर से अपलोड करें।",
+ "केवल नए इंडेक्स किए गए दस्तावेज़ों को प्रभावित करता है। मॉडल बदलने के बाद मौजूदा दस्तावेज़ों को फिर से एम्बेड करें।",
+ reembed: {
+ label: "दस्तावेज़ फिर से एम्बेड करें",
+ staleOne:
+ "1 दस्तावेज़ किसी दूसरे एम्बेडिंग मॉडल से इंडेक्स किया गया था, इसलिए सिमैंटिक खोज उसे छोड़ देती है।",
+ staleMany:
+ "{count} दस्तावेज़ किसी दूसरे एम्बेडिंग मॉडल से इंडेक्स किए गए थे, इसलिए सिमैंटिक खोज उन्हें छोड़ देती है।",
+ staleArchived:
+ "पिछला चैट इतिहास किसी दूसरे एम्बेडिंग मॉडल से इंडेक्स किया गया था, इसलिए सिमैंटिक खोज उसे छोड़ देती है।",
+ running: "फिर से एम्बेड हो रहा है: {total} में से {done}",
+ action: "फिर से एम्बेड करें",
+ stop: "रोकें",
+ startFailed: "फिर से एम्बेड करना शुरू नहीं हो सका",
+ stopped: "फिर से एम्बेड करना रोका गया",
+ finished: "दस्तावेज़ फिर से एम्बेड हो गए",
+ finishedWithFailures: "{count} फिर से एम्बेड नहीं हो सके",
+ },
emptyError: "एक Hugging Face मॉडल id या स्थानीय पथ दर्ज करें।",
loadError: "एम्बेडिंग मॉडल सेटिंग लोड करने में विफल।",
saveError: "एम्बेडिंग मॉडल सहेजने में विफल।",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index 6f228e08d01..197fe591fcd 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -1794,7 +1794,23 @@ export const it = {
"Modello Hugging Face o percorso locale usato per indicizzare e cercare nei tuoi documenti. Il valore predefinito è {defaultModel}.",
searchPlaceholder: "Cerca qualsiasi modello su HF",
reindexWarning:
- "Vale solo per i documenti indicizzati da ora in poi. Ricarica quelli esistenti dopo aver cambiato modello.",
+ "Vale solo per i documenti indicizzati da ora in poi. Ricalcola gli embedding di quelli esistenti dopo aver cambiato modello.",
+ reembed: {
+ label: "Ricalcola gli embedding dei documenti",
+ staleOne:
+ "1 documento è stato indicizzato con un altro modello di embedding, quindi la ricerca semantica lo ignora.",
+ staleMany:
+ "{count} documenti sono stati indicizzati con un altro modello di embedding, quindi la ricerca semantica li ignora.",
+ staleArchived:
+ "La cronologia chat precedente è stata indicizzata con un altro modello di embedding, quindi la ricerca semantica la ignora.",
+ running: "Ricalcolo embedding: {done} di {total}",
+ action: "Ricalcola",
+ stop: "Interrompi",
+ startFailed: "Impossibile avviare il ricalcolo degli embedding",
+ stopped: "Ricalcolo degli embedding interrotto",
+ finished: "Embedding dei documenti ricalcolati",
+ finishedWithFailures: "Non è stato possibile ricalcolare {count}",
+ },
emptyError:
"Inserisci l'ID di un modello Hugging Face o un percorso locale.",
loadError:
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index d843e1a1f27..5808971534f 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -1832,7 +1832,20 @@ export const ja = {
embeddingModelShort: "ドキュメントをベクトルに変換し、チャットで検索できるようにします。",
embeddingModelDescription: "ドキュメントのインデックス作成と検索に使用する Hugging Face モデルまたはローカルパス。デフォルトは {defaultModel} です。",
searchPlaceholder: "HF 上の任意のモデルを検索",
- reindexWarning: "新しくインデックスされるドキュメントにのみ影響します。モデルを変更した後は、既存のドキュメントを再アップロードしてください。",
+ reindexWarning: "新しくインデックスされるドキュメントにのみ影響します。モデルを変更した後は、既存のドキュメントを再埋め込みしてください。",
+ reembed: {
+ label: "ドキュメントを再埋め込み",
+ staleOne: "1 件のドキュメントが別の埋め込みモデルでインデックスされているため、セマンティック検索の対象外です。",
+ staleMany: "{count} 件のドキュメントが別の埋め込みモデルでインデックスされているため、セマンティック検索の対象外です。",
+ staleArchived: "以前のチャット履歴が別の埋め込みモデルでインデックスされているため、セマンティック検索の対象外です。",
+ running: "再埋め込み中: {done} / {total}",
+ action: "再埋め込み",
+ stop: "停止",
+ startFailed: "再埋め込みを開始できませんでした",
+ stopped: "再埋め込みを停止しました",
+ finished: "ドキュメントを再埋め込みしました",
+ finishedWithFailures: "{count} 件を再埋め込みできませんでした",
+ },
emptyError: "Hugging Face モデル ID またはローカルパスを入力してください。",
loadError: "埋め込みモデル設定の読み込みに失敗しました。",
saveError: "埋め込みモデルの保存に失敗しました。",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index bb409076aab..0a8a6f6a513 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -1842,8 +1842,20 @@ export const ko = {
embeddingModelDescription:
"문서 인덱싱 및 검색에 사용할 Hugging Face 모델이나 로컬 경로를 지정합니다. 기본값은 {defaultModel}입니다.",
searchPlaceholder: "HF의 모든 모델 검색",
- reindexWarning:
- "새로 인덱싱되는 문서에만 적용됩니다. 모델을 변경한 후 기존 문서를 다시 업로드하세요.",
+ reindexWarning: "새로 인덱싱되는 문서에만 적용됩니다. 모델을 변경한 후 기존 문서를 다시 임베딩하세요.",
+ reembed: {
+ label: "문서 다시 임베딩",
+ staleOne: "문서 1개가 다른 임베딩 모델로 인덱싱되어 시맨틱 검색에서 제외됩니다.",
+ staleMany: "문서 {count}개가 다른 임베딩 모델로 인덱싱되어 시맨틱 검색에서 제외됩니다.",
+ staleArchived: "이전 채팅 기록이 다른 임베딩 모델로 인덱싱되어 시맨틱 검색에서 제외됩니다.",
+ running: "다시 임베딩 중: {done}/{total}",
+ action: "다시 임베딩",
+ stop: "중지",
+ startFailed: "다시 임베딩을 시작할 수 없습니다",
+ stopped: "다시 임베딩이 중지되었습니다",
+ finished: "문서를 다시 임베딩했습니다",
+ finishedWithFailures: "{count}개를 다시 임베딩하지 못했습니다",
+ },
emptyError: "Hugging Face 모델 ID 또는 로컬 경로를 입력하세요.",
loadError: "임베딩 모델 설정을 불러오지 못했습니다.",
saveError: "임베딩 모델을 저장하지 못했습니다.",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index 9821cd442f4..7467744b747 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -1859,7 +1859,23 @@ export const ptBR = {
"Modelo do Hugging Face ou caminho local usado para indexar e buscar seus documentos. O padrão é {defaultModel}.",
searchPlaceholder: "Buscar qualquer modelo no HF",
reindexWarning:
- "Afeta apenas documentos recém-indexados. Reenvie os documentos existentes após alterar o modelo.",
+ "Afeta apenas documentos recém-indexados. Reincorpore os documentos existentes após alterar o modelo.",
+ reembed: {
+ label: "Reincorporar documentos",
+ staleOne:
+ "1 documento foi indexado com outro modelo de embedding, então a busca semântica o ignora.",
+ staleMany:
+ "{count} documentos foram indexados com outro modelo de embedding, então a busca semântica os ignora.",
+ staleArchived:
+ "O histórico de chat anterior foi indexado com outro modelo de embedding, então a busca semântica o ignora.",
+ running: "Reincorporando: {done} de {total}",
+ action: "Reincorporar",
+ stop: "Parar",
+ startFailed: "Não foi possível iniciar a reincorporação",
+ stopped: "Reincorporação interrompida",
+ finished: "Documentos reincorporados",
+ finishedWithFailures: "{count} não puderam ser reincorporados",
+ },
emptyError: "Insira um id de modelo do Hugging Face ou um caminho local.",
loadError: "Falha ao carregar a configuração do modelo de embedding.",
saveError: "Falha ao salvar o modelo de embedding.",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index 2073b40f9a7..07e586f8e66 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -1852,7 +1852,23 @@ export const ru = {
"Модель Hugging Face или локальный путь для индексации и поиска по вашим документам. По умолчанию {defaultModel}.",
searchPlaceholder: "Поиск любой модели на HF",
reindexWarning:
- "Влияет только на вновь индексируемые документы. После смены модели загрузите существующие документы заново.",
+ "Влияет только на вновь индексируемые документы. После смены модели пересчитайте эмбеддинги существующих документов.",
+ reembed: {
+ label: "Пересчитать эмбеддинги документов",
+ staleOne:
+ "1 документ проиндексирован другой моделью эмбеддингов, поэтому семантический поиск его пропускает.",
+ staleMany:
+ "Документов, проиндексированных другой моделью эмбеддингов: {count}. Семантический поиск их пропускает.",
+ staleArchived:
+ "Ранняя история чатов проиндексирована другой моделью эмбеддингов, поэтому семантический поиск её пропускает.",
+ running: "Пересчёт эмбеддингов: {done} из {total}",
+ action: "Пересчитать",
+ stop: "Остановить",
+ startFailed: "Не удалось запустить пересчёт эмбеддингов",
+ stopped: "Пересчёт эмбеддингов остановлен",
+ finished: "Эмбеддинги документов пересчитаны",
+ finishedWithFailures: "Не удалось пересчитать: {count}",
+ },
emptyError: "Введите ID модели Hugging Face или локальный путь.",
loadError: "Не удалось загрузить настройку модели эмбеддингов.",
saveError: "Не удалось сохранить модель эмбеддингов.",
diff --git a/studio/frontend/src/i18n/locales/sv.ts b/studio/frontend/src/i18n/locales/sv.ts
index 6779fb343a8..0c7c8355088 100644
--- a/studio/frontend/src/i18n/locales/sv.ts
+++ b/studio/frontend/src/i18n/locales/sv.ts
@@ -2028,7 +2028,23 @@ export const sv = {
"Hugging Face-modell eller lokal sökväg som används för att indexera och söka i dina dokument. Standard är {defaultModel}.",
searchPlaceholder: "Sök efter valfri modell på HF",
reindexWarning:
- "Påverkar endast nyindexerade dokument. Ladda upp befintliga dokument igen efter att du har bytt modell.",
+ "Påverkar endast nyindexerade dokument. Bädda in befintliga dokument på nytt efter att du har bytt modell.",
+ reembed: {
+ label: "Bädda in dokument på nytt",
+ staleOne:
+ "1 dokument indexerades med en annan inbäddningsmodell, så semantisk sökning hoppar över det.",
+ staleMany:
+ "{count} dokument indexerades med en annan inbäddningsmodell, så semantisk sökning hoppar över dem.",
+ staleArchived:
+ "Tidigare chatthistorik indexerades med en annan inbäddningsmodell, så semantisk sökning hoppar över den.",
+ running: "Bäddar in på nytt: {done} av {total}",
+ action: "Bädda in på nytt",
+ stop: "Stoppa",
+ startFailed: "Det gick inte att starta ominbäddningen",
+ stopped: "Ominbäddningen stoppades",
+ finished: "Dokumenten har bäddats in på nytt",
+ finishedWithFailures: "{count} kunde inte bäddas in på nytt",
+ },
emptyError: "Ange ett Hugging Face-modell-ID eller en lokal sökväg.",
loadError:
"Det gick inte att läsa in inställningen för inbäddningsmodellen.",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index c3648f1ac38..94bdba5a293 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -1824,8 +1824,20 @@ export const zhCN = {
embeddingModelDescription:
"用于为文档建立索引和搜索的 Hugging Face 模型或本地路径。默认值为 {defaultModel}。",
searchPlaceholder: "搜索 HF 上的任意模型",
- reindexWarning:
- "仅影响新建立索引的文档。更改模型后请重新上传已有文档。",
+ reindexWarning: "仅影响新建立索引的文档。更改模型后请重新嵌入已有文档。",
+ reembed: {
+ label: "重新嵌入文档",
+ staleOne: "有 1 个文档使用其他嵌入模型建立索引,语义搜索会跳过它。",
+ staleMany: "有 {count} 个文档使用其他嵌入模型建立索引,语义搜索会跳过它们。",
+ staleArchived: "较早的聊天记录使用其他嵌入模型建立索引,语义搜索会跳过它。",
+ running: "正在重新嵌入:{done} / {total}",
+ action: "重新嵌入",
+ stop: "停止",
+ startFailed: "无法开始重新嵌入",
+ stopped: "重新嵌入已停止",
+ finished: "文档已重新嵌入",
+ finishedWithFailures: "{count} 个无法重新嵌入",
+ },
emptyError: "请输入 Hugging Face 模型 ID 或本地路径。",
loadError: "加载 embedding 模型设置失败。",
saveError: "保存 embedding 模型失败。",
diff --git a/studio/frontend/tests/helpers/store-stubs/auth.ts b/studio/frontend/tests/helpers/store-stubs/auth.ts
index d52a64136a1..bfd548601de 100644
--- a/studio/frontend/tests/helpers/store-stubs/auth.ts
+++ b/studio/frontend/tests/helpers/store-stubs/auth.ts
@@ -1,6 +1,7 @@
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+export { AUTH_SESSION_CLEARED_EVENT } from "../../../src/features/auth/session-events.ts";
export type AuthFetchHandler = (
input: string,
init?: RequestInit,
diff --git a/studio/frontend/tests/rag-reembed-toast.test.ts b/studio/frontend/tests/rag-reembed-toast.test.ts
new file mode 100644
index 00000000000..c3e54fcaa1a
--- /dev/null
+++ b/studio/frontend/tests/rag-reembed-toast.test.ts
@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import { register } from "node:module";
+import test, { afterEach } from "node:test";
+
+import { AUTH_SESSION_CLEARED_EVENT } from "../src/features/auth/session-events.ts";
+import { installLocalStorageFake } from "./helpers/kit.ts";
+
+register("./helpers/igpu-carveout-resolver.mjs", import.meta.url);
+const { fireWindowEvent } = installLocalStorageFake();
+
+const { calls } = await import("./helpers/toast-stub.mjs");
+const { setAuthFetchHandler } = await import("./helpers/store-stubs/auth.ts");
+const { toastEmbeddingModelSaved, useReembedStore } = await import(
+ "../src/features/rag/components/reembed-store.ts"
+);
+
+const job = (status: string, failed = 0, id = "j1") => ({
+ id,
+ status,
+ done: 2,
+ failed,
+ remaining: 0,
+ clippedChunks: 0,
+ progress: 1,
+ error: failed ? "embedder down" : null,
+});
+
+const idle = { staleDocuments: 0, staleArchived: 0 };
+const stale = { staleDocuments: 2, staleArchived: 0 };
+const kinds = () => calls.map((call) => call.kind);
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+const offline = () => Promise.reject(new Error("offline"));
+const reply = (body: object) => new Response(JSON.stringify(body));
+const signOut = () => fireWindowEvent(AUTH_SESSION_CLEARED_EVENT, {});
+afterEach(signOut);
+
+function serve(status: object, posted: string[] = []) {
+ calls.length = 0;
+ setAuthFetchHandler((url, init) => {
+ if (init?.method !== "POST") return reply(status);
+ posted.push(url);
+ return reply({ job: job("running") });
+ });
+ return posted;
+}
+
+test("signing out forgets the job and stops polling for it", async (t) => {
+ t.mock.timers.enable({ apis: ["setTimeout"] });
+ serve({ ...stale, job: job("running", 0, "j11") });
+ await useReembedStore.getState().load();
+ setAuthFetchHandler(offline);
+ await useReembedStore.getState().cancel(); // leaves the state to reconcile
+ serve({ ...stale, job: job("running", 0, "j11") });
+ void useReembedStore.getState().load(); // answered after signing out
+ setAuthFetchHandler(offline);
+ void useReembedStore.getState().start(); // fails after signing out
+ signOut();
+ await useReembedStore.getState().load(); // a read that fails once signed out
+ serve({ ...idle, job: job("completed", 0, "j11") });
+ t.mock.timers.tick(1500);
+ await flush();
+ assert.deepEqual([useReembedStore.getState().status, kinds()], [null, []]);
+});
+
+test("a save that leaves documents stale offers Re-embed, which starts the job", async () => {
+ const posted = serve({ staleDocuments: 3, staleArchived: 0, job: null });
+ await toastEmbeddingModelSaved("Saved");
+ const [saved] = calls;
+ assert.equal(
+ saved.options?.description,
+ "3 documents were indexed with a different embedding model, so semantic search skips them.",
+ );
+ assert.equal(saved.options?.duration, 10_000);
+ saved.options?.action?.onClick();
+ assert.deepEqual(posted, ["/api/rag/reembed"]);
+});
+
+test("no action when nothing is stale, a job already follows the model, or it is not on disk", async () => {
+ for (const [status, ready] of [
+ [{ ...idle, job: null }, true],
+ [{ ...stale, job: job("running") }, true],
+ [{ ...stale, job: null }, false],
+ ] as const) {
+ serve(status);
+ await toastEmbeddingModelSaved("Saved", ready);
+ assert.equal(calls[0].options?.action, undefined);
+ assert.deepEqual(useReembedStore.getState().status, status); // read either way, for the row
+ }
+});
+
+test("a job's end is announced once, and only by a client that saw it running", async () => {
+ serve({ ...idle, job: job("completed", 0, "j0") });
+ await useReembedStore.getState().load();
+ assert.equal(calls.length, 0);
+ for (const [end, kind] of [
+ [job("completed"), "success"],
+ [job("completed", 1), "warning"],
+ [job("failed", 3), "error"],
+ ] as const) {
+ serve({ ...idle, job: job("running") });
+ await useReembedStore.getState().load();
+ serve({ ...idle, job: end });
+ await useReembedStore.getState().load();
+ await useReembedStore.getState().load();
+ assert.deepEqual(kinds(), [kind]);
+ }
+});
+
+test("polling outlives failed requests, and a failed cancel reports false", async (t) => {
+ t.mock.timers.enable({ apis: ["setTimeout"] });
+ serve({ ...idle, job: job("running", 0, "j2") });
+ await useReembedStore.getState().load();
+ setAuthFetchHandler(offline);
+ assert.equal(await useReembedStore.getState().cancel(), false);
+ t.mock.timers.tick(1500);
+ await flush();
+ serve({ ...idle, job: job("completed", 0, "j2") });
+ t.mock.timers.tick(1500);
+ await flush();
+ assert.deepEqual(kinds(), ["success"]);
+});
+
+test("a status reply older than a start reply is replaced by a fresh read", async () => {
+ let server: object = { ...idle, job: null };
+ const held: { get?: (response: Response) => void } = {};
+ calls.length = 0;
+ setAuthFetchHandler((_url, init) => {
+ if (init?.method === "POST") {
+ server = { ...stale, job: job("running", 0, "j3") };
+ return reply({ job: job("running", 0, "j3") });
+ }
+ if (held.get) return reply(server);
+ return new Promise((resolve) => {
+ held.get = resolve;
+ });
+ });
+ const late = toastEmbeddingModelSaved("Saved");
+ await useReembedStore.getState().start();
+ held.get?.(reply({ ...stale, job: null }));
+ await late;
+ assert.equal(useReembedStore.getState().status?.job?.id, "j3");
+ const saved = calls.at(-1)?.options;
+ assert.equal(saved?.description?.startsWith("2 documents"), true);
+ assert.equal(saved?.action, undefined);
+});
+
+test("a late start reply neither hides its job nor announces its end twice", async (t) => {
+ t.mock.timers.enable({ apis: ["setTimeout"] });
+ let server: object | null = { ...idle, job: null };
+ const held: { post?: (response: Response) => void } = {};
+ calls.length = 0;
+ setAuthFetchHandler((_url, init) => {
+ if (init?.method === "POST") {
+ return new Promise((resolve) => {
+ held.post = resolve;
+ });
+ }
+ if (server === null) throw new Error("offline");
+ return reply(server);
+ });
+ const startReply = (id: string) => reply({ job: job("running", 0, id) });
+ let started = useReembedStore.getState().start();
+ await useReembedStore.getState().load();
+ server = null; // the read that replaces the dropped start reply fails once
+ held.post?.(startReply("j5"));
+ await started;
+ await flush();
+ server = { ...idle, job: job("running", 0, "j5") };
+ t.mock.timers.tick(1500);
+ await flush();
+ assert.equal(useReembedStore.getState().status?.job?.id, "j5");
+ server = { ...idle, job: job("completed", 0, "j5") };
+ started = useReembedStore.getState().start();
+ await useReembedStore.getState().load();
+ held.post?.(startReply("j5"));
+ await started;
+ await flush();
+ t.mock.timers.tick(1500);
+ await flush();
+ assert.deepEqual(kinds(), ["success"]);
+});
+
+test("a finished job in a start or cancel reply refreshes the stale counts", async (t) => {
+ t.mock.timers.enable({ apis: ["setTimeout"] });
+ serve({ ...stale, job: job("running", 0, "j8") });
+ await useReembedStore.getState().load();
+ let online = false;
+ setAuthFetchHandler((_url, init) => {
+ if (init?.method === "POST") {
+ return reply({ job: job("completed", 0, "j8") });
+ }
+ if (!online) throw new Error("offline");
+ return reply({ ...idle, job: job("completed", 0, "j8") });
+ });
+ await useReembedStore.getState().cancel();
+ await flush();
+ online = true;
+ t.mock.timers.tick(1500);
+ await flush();
+ assert.equal(useReembedStore.getState().status?.staleDocuments, 0);
+});
+
+test("a start whose reply was lost is found by the next status read", async (t) => {
+ t.mock.timers.enable({ apis: ["setTimeout"] });
+ serve({ ...idle, job: null });
+ await useReembedStore.getState().load();
+ setAuthFetchHandler((_url, init) => {
+ if (init?.method === "POST") throw new Error("offline");
+ return reply({ ...idle, job: job("running", 0, "j9") });
+ });
+ await useReembedStore.getState().start();
+ t.mock.timers.tick(1500);
+ await flush();
+ assert.equal(useReembedStore.getState().status?.job?.id, "j9");
+});
+
+test("a status reply sent before a failed start cannot end the recovery", async (t) => {
+ t.mock.timers.enable({ apis: ["setTimeout"] });
+ const held: { get?: (response: Response) => void } = {};
+ setAuthFetchHandler((_url, init) => {
+ if (init?.method === "POST") throw new Error("offline");
+ if (held.get) {
+ return reply({ ...idle, job: job("running", 0, "j10") });
+ }
+ return new Promise((resolve) => {
+ held.get = resolve;
+ });
+ });
+ const early = useReembedStore.getState().load();
+ await useReembedStore.getState().start();
+ held.get?.(reply({ ...idle, job: null }));
+ await early;
+ assert.equal(useReembedStore.getState().status?.job?.id, "j10");
+});