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 RAG: pause linked-folder indexing while a local chat generates (#17018)

Daniel Han31353df16cdd
diff --git a/studio/backend/core/rag/config.py b/studio/backend/core/rag/config.py
index 86d5e72bfdb..e103024a7b2 100644
--- a/studio/backend/core/rag/config.py
+++ b/studio/backend/core/rag/config.py
@@ -90,6 +90,8 @@ FOLDER_MAX_TEXT_BYTES = int(os.environ.get("RAG_FOLDER_MAX_TEXT_BYTES", str(20 *
FOLDER_JOB_HISTORY_LIMIT = int(os.environ.get("RAG_FOLDER_JOB_HISTORY_LIMIT", "200"))
# Linked-folder documents ingested concurrently, clamped to 1..4.
FOLDER_INGEST_WORKERS = int(os.environ.get("RAG_FOLDER_INGEST_WORKERS", "2"))
+# Linked-folder indexing waits while a local chat generates, else it starves decode (#16992).
+FOLDER_YIELD_TO_CHAT = os.environ.get("RAG_FOLDER_YIELD_TO_CHAT", "1") != "0"
# Small linked-folder files in flight, clamped to workers..64; past the workers they only wait to embed.
FOLDER_INGEST_IN_FLIGHT = int(os.environ.get("RAG_FOLDER_INGEST_IN_FLIGHT", "16"))
FOLDER_INGEST_BATCH_FILE_BYTES = int(
diff --git a/studio/backend/core/rag/folder_sync.py b/studio/backend/core/rag/folder_sync.py
index 43975a29d8c..1e3a50fd072 100644
--- a/studio/backend/core/rag/folder_sync.py
+++ b/studio/backend/core/rag/folder_sync.py
@@ -194,6 +194,27 @@ def is_cancel_requested(folder_id: str | None) -> bool:
return account_key(folder_id) in _folder_cancels
+def _local_chat_busy() -> bool:
+ from state import active_generations
+
+ # Cloud-provider chats use no local compute; embedding requests are indexing's own kind of work.
+ return any(
+ entry["kind"] != "embeddings"
+ for entry in active_generations.snapshot(include_external = False)
+ )
+
+
+def wait_while_chat_busy() -> None:
+ """Hold a linked-folder ingest thread while a local generation runs; stop and unlink end the wait."""
+ folder_id = getattr(_worker_state, "folder_id", None)
+ if folder_id is None or not config.FOLDER_YIELD_TO_CHAT:
+ return
+ stop_event = getattr(_worker_state, "stop_event", _stop)
+ while _local_chat_busy():
+ if account_is_retired() or is_cancel_requested(folder_id) or stop_event.wait(0.5):
+ return
+
+
def _folder_lock(folder_id: str) -> threading.RLock:
with _named_locks_lock:
return _folder_locks.setdefault(account_key(folder_id), threading.RLock())
@@ -1559,6 +1580,7 @@ def _ingest_folder_document(
ingestion_job = None
with rag_db.reuse_connections():
try:
+ wait_while_chat_busy()
_check_running()
document_id, ingestion_job = ingestion.start_ingestion(
folder["scope"],
diff --git a/studio/backend/core/rag/ingestion.py b/studio/backend/core/rag/ingestion.py
index e73b205542c..1faab62f227 100644
--- a/studio/backend/core/rag/ingestion.py
+++ b/studio/backend/core/rag/ingestion.py
@@ -117,11 +117,14 @@ def _set_job(
def _progress(conn, job_id: str, stage: str, progress: float) -> None:
- if account_is_retired():
- raise job_leases.JobLeaseLost("Account is retired")
# An unlink stops a linked-folder document mid-embed, not after it (folder_sync imports this module).
from . import folder_sync
+ # Before the checks below, so they see what happened during a chat. Never inside a write transaction.
+ if not conn.in_transaction:
+ folder_sync.wait_while_chat_busy()
+ if account_is_retired():
+ raise job_leases.JobLeaseLost("Account is retired")
if folder_sync.is_cancel_requested(getattr(folder_sync._worker_state, "folder_id", None)):
# Terminal, so the folder cleanup can prune the row with the document it discards.
_set_job(conn, job_id, status = "failed", stage = "error", error = "Linked folder was removed")
diff --git a/studio/backend/tests/test_rag_folder_yield_to_chat.py b/studio/backend/tests/test_rag_folder_yield_to_chat.py
new file mode 100644
index 00000000000..d8ae0e4361d
--- /dev/null
+++ b/studio/backend/tests/test_rag_folder_yield_to_chat.py
@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Linked-folder indexing waits while a local chat generates (#16992)."""
+
+from __future__ import annotations
+
+import threading
+from contextlib import closing
+from pathlib import Path
+
+import pytest
+
+from core.rag import config, embeddings, folder_sync, ingestion
+from state import active_generations
+from storage import rag_db
+
+pytestmark = pytest.mark.skipif(not rag_db.RAG_AVAILABLE, reason = "sqlite-vec is not installed")
+
+
+def _folder(rag_home: Path, files: int = 1) -> dict:
+ source = rag_home / "source"
+ source.mkdir()
+ for i in range(files):
+ (source / f"doc{i}.txt").write_text(f"document number {i} words", encoding = "utf-8")
+ return folder_sync.create_folder(
+ scope_type = "knowledge_base", scope_id = "scope-1", path = str(source), name = "Docs"
+ )
+
+
+def _indexed(folder: dict) -> int:
+ with closing(rag_db.get_connection()) as conn:
+ return conn.execute(
+ "SELECT COUNT(*) FROM documents WHERE linked_folder_id=?", (folder["id"],)
+ ).fetchone()[0]
+
+
+def _start_sync(folder: dict) -> tuple[threading.Thread, list]:
+ out: list = []
+ job_id = folder_sync.request_sync(folder["id"])
+
+ def run():
+ folder_sync.reconcile_folder(job_id)
+ out.append(folder_sync.get_job(job_id))
+
+ thread = threading.Thread(target = run, daemon = True)
+ thread.start()
+ return thread, out
+
+
+def test_indexing_waits_for_a_local_chat_then_resumes(rag_home, stub_embeddings):
+ folder = _folder(rag_home, files = 3)
+ with active_generations.ActiveGeneration(threading.Event(), kind = "chat"):
+ thread, out = _start_sync(folder)
+ # Without the yield the three documents index well inside this window.
+ thread.join(timeout = 4)
+ assert thread.is_alive()
+ assert _indexed(folder) == 0
+ thread.join(timeout = 30)
+
+ assert out and out[0]["status"] == "completed"
+ assert _indexed(folder) == 3
+
+
+def test_a_chat_started_mid_document_pauses_it(rag_home, stub_embeddings, monkeypatch):
+ folder = _folder(rag_home)
+ real_encode, real_set_job = embeddings.encode, ingestion._set_job
+ chat = active_generations.ActiveGeneration(threading.Event(), kind = "chat")
+ started = threading.Event()
+ stages_during_chat: list[str] = []
+
+ def encode_while_a_chat_starts(*args, **kwargs):
+ if not started.is_set():
+ started.set()
+ chat.__enter__()
+ threading.Timer(1.0, chat.__exit__, (None, None, None)).start()
+ return real_encode(*args, **kwargs)
+
+ def record_set_job(conn, job_id, **kwargs):
+ if started.is_set() and active_generations.count():
+ stages_during_chat.append(kwargs.get("stage"))
+ return real_set_job(conn, job_id, **kwargs)
+
+ monkeypatch.setattr(embeddings, "encode", encode_while_a_chat_starts)
+ monkeypatch.setattr(ingestion, "_set_job", record_set_job)
+ thread, out = _start_sync(folder)
+ thread.join(timeout = 30)
+
+ assert started.is_set()
+ assert out and out[0]["status"] == "completed"
+ assert stages_during_chat == []
+ assert _indexed(folder) == 1
+
+
[email protected]("kwargs", [{"external": True}, {"kind": "embeddings"}])
+def test_cloud_chats_and_embedding_requests_do_not_hold_indexing(rag_home, stub_embeddings, kwargs):
+ folder = _folder(rag_home)
+ with active_generations.ActiveGeneration(threading.Event(), **kwargs):
+ thread, out = _start_sync(folder)
+ thread.join(timeout = 30)
+ assert out and out[0]["status"] == "completed"
+ assert _indexed(folder) == 1
+
+
+def test_switch_off_restores_indexing_during_chat(rag_home, stub_embeddings, monkeypatch):
+ monkeypatch.setattr(config, "FOLDER_YIELD_TO_CHAT", False)
+ folder = _folder(rag_home)
+ with active_generations.ActiveGeneration(threading.Event(), kind = "chat"):
+ thread, out = _start_sync(folder)
+ thread.join(timeout = 30)
+ assert out and out[0]["status"] == "completed"
+
+
+def test_unlink_ends_the_wait(rag_home, stub_embeddings):
+ folder = _folder(rag_home)
+ with active_generations.ActiveGeneration(threading.Event(), kind = "chat"):
+ thread, _ = _start_sync(folder)
+ thread.join(timeout = 2)
+ assert thread.is_alive()
+ assert folder_sync.delete_folder(folder["id"]) is True
+ thread.join(timeout = 30)
+ assert not thread.is_alive()
+ assert folder_sync.get_folder(folder["id"]) is None
+
+
+def test_non_folder_work_never_waits():
+ with active_generations.ActiveGeneration(threading.Event(), kind = "chat"):
+ done = threading.Event()
+ threading.Thread(
+ target = lambda: (folder_sync.wait_while_chat_busy(), done.set()), daemon = True
+ ).start()
+ assert done.wait(timeout = 2)
+
+
+def test_retirement_during_the_wait_stops_the_document(monkeypatch):
+ import sqlite3
+
+ from core.rag import job_leases
+
+ retired = threading.Event()
+ monkeypatch.setattr(ingestion, "account_is_retired", retired.is_set)
+ errors: list = []
+
+ def document():
+ folder_sync._worker_state.folder_id = "folder-1"
+ try:
+ ingestion._progress(sqlite3.connect(":memory:"), "job-1", "embedding", 0.7)
+ except Exception as exc: # noqa: BLE001
+ errors.append(exc)
+
+ with active_generations.ActiveGeneration(threading.Event(), kind = "chat"):
+ thread = threading.Thread(target = document, daemon = True)
+ thread.start()
+ thread.join(timeout = 1.5)
+ assert thread.is_alive()
+ retired.set()
+ thread.join(timeout = 10)
+
+ assert len(errors) == 1 and isinstance(errors[0], job_leases.JobLeaseLost), errors