DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix: embedding local keyless, qwen3-Instruct thinking, embedding concurrency (#1797)
Wu Shuwen259bb43e3d81
diff --git a/deeptutor/services/config/provider_runtime.py b/deeptutor/services/config/provider_runtime.pyindex 511c2100e..7b5cd4bc7 100644--- a/deeptutor/services/config/provider_runtime.py+++ b/deeptutor/services/config/provider_runtime.py@@ -1083,10 +1083,10 @@ def _is_legacy_lemonade_endpoint(api_base: str) -> bool:"""try:endpoint = urlparse(api_base if "://" in api_base else f"http://{api_base}")+ if endpoint.port != 13305:+ return Falseexcept ValueError:return False- if endpoint.port != 13305:- return Falseif not _is_nonpublic_embedding_host(endpoint.hostname or ""):return Falsepath = endpoint.path.rstrip("/")@@ -1105,6 +1105,20 @@ def _resolve_embedding_provider(# Compatible embeddings. Recognize that endpoint before a Qwen3 model# name is mistaken for a remote embedding vendor (#1568, #1782).return "lemonade"++ if _is_local_base_url(api_base) and hint in {None, "custom", "openai"}:+ # Ollama also serves OpenAI-compatible embeddings on /v1/embeddings.+ # Select the wire protocol by path, not by a port substring.+ endpoint = urlparse(api_base if "://" in api_base else f"http://{api_base}")+ path = endpoint.path.rstrip("/")+ try:+ native_root = not path and endpoint.port == 11434+ except ValueError:+ native_root = False+ if path in {"/api/embed", "/api/embeddings"} or native_root:+ return "ollama"+ return "vllm"+if hint and hint in EMBEDDING_PROVIDERS:return hint@@ -1117,11 +1131,6 @@ def _resolve_embedding_provider(if any(keyword in model_lower for keyword in spec.keywords):return provider_name- if _is_local_base_url(api_base):- if api_base and "11434" in api_base:- return "ollama"- return "vllm"-for provider_name, spec in EMBEDDING_PROVIDERS.items():configured = provider_pool.get(provider_name)if not configured:diff --git a/deeptutor/services/embedding/client.py b/deeptutor/services/embedding/client.pyindex de23e0665..e4725be3d 100644--- a/deeptutor/services/embedding/client.py+++ b/deeptutor/services/embedding/client.py@@ -4,6 +4,7 @@ from __future__ import annotationsfrom contextlib import asynccontextmanagerimport logging+import threadingfrom typing import Any, Dict, List, Optionalfrom deeptutor.services.config.embedding_endpoint import (@@ -43,19 +44,13 @@ class EmbeddingClient:# 创建时的 loop,跨 loop 既不互斥还会挂死。必须用线程级锁。_spacing_lock: Any = None_last_request_monotonic: float = 0.0- _thread_guard: Any = None+ _thread_guard = threading.Lock()@classmethoddef _global_spacing_lock(cls):- import threading-- if cls._spacing_lock is None:- cls._thread_guard = threading.Lock()- with cls._thread_guard:- if cls._spacing_lock is None:- from threading import Lock as _TLock-- cls._spacing_lock = _TLock()+ with cls._thread_guard:+ if cls._spacing_lock is None:+ cls._spacing_lock = threading.Lock()return cls._spacing_lock@staticmethod@@ -72,6 +67,24 @@ class EmbeddingClient:finally:lock.release()+ async def _wait_for_request_slot(self) -> None:+ """Space request starts across threads/loops without serializing HTTP.++ Text and multimodal calls share the same clock. No delay means no+ throttling; adapters still enforce their own concurrency/retry policy.+ """+ import asyncio+ from time import monotonic++ delay = self.config.batch_delay+ if delay <= 0:+ return+ async with EmbeddingClient._hold_spacing_lock():+ remaining = delay - (monotonic() - EmbeddingClient._last_request_monotonic)+ if remaining > 0:+ await asyncio.sleep(remaining)+ EmbeddingClient._last_request_monotonic = monotonic()+def __init__(self, config: Optional[EmbeddingConfig] = None):self.config = config or get_embedding_config()self.logger = logging.getLogger(__name__)@@ -118,8 +131,6 @@ class EmbeddingClient:# silently invalidate the indexes built from it.role = input_type if getattr(self.adapter, "SUPPORTS_INPUT_TYPE", False) else None- import asyncio-# Clamp configured batch size against the provider's per-request item# cap. SiliconFlow Qwen3 family caps at 32; DashScope at 20; others# have generous defaults. Without this clamp, indexing a doc with many@@ -133,7 +144,6 @@ class EmbeddingClient:f"(provider '{self.config.binding}' max={provider_max})")all_embeddings: List[List[float]] = []- batch_delay = self.config.batch_delayexpected_dim: int | None = Nonetotal_batches = (len(texts) + batch_size - 1) // batch_size@@ -146,26 +156,8 @@ class EmbeddingClient:input_type=role,)try:- # The spacing lock exists only to keep a configured gap between- # requests across threads and event loops (LlamaIndex's pool- # gives each thread its own loop, so an asyncio.Lock is not- # enough). With the default batch_delay of 0 there is no gap- # to protect, and holding the lock around the HTTP call would- # flatten every concurrent embed — including LightRAG's — into- # one in-flight request (#1779).- from time import monotonic as _mono-- if batch_delay > 0:- async with EmbeddingClient._hold_spacing_lock():- elapsed = _mono() - EmbeddingClient._last_request_monotonic- if elapsed < batch_delay:- await asyncio.sleep(batch_delay - elapsed)- # The timestamp has to be written inside the lock, or- # overlapping callers overwrite it and the gap collapses.- EmbeddingClient._last_request_monotonic = _mono()- response = await self.adapter.embed(request)- else:- response = await self.adapter.embed(request)+ await self._wait_for_request_slot()+ response = await self.adapter.embed(request)except Exception as exc:# Capture batch context so the task log stream / KB diagnostics# show actionable info instead of a bare exception string.@@ -219,10 +211,6 @@ class EmbeddingClient:exc_info=True,)- # Delay between batches to avoid rate limiting- if i < total_batches - 1 and batch_delay > 0:- await asyncio.sleep(batch_delay)-self.logger.debug(f"Generated {len(all_embeddings)} embeddings using "f"{self.config.binding} (batch_size={batch_size})"@@ -259,8 +247,6 @@ class EmbeddingClient:"Configured embedding provider/model does not support multimodal contents.")- import asyncio-spec = EMBEDDING_PROVIDERS.get(self.config.binding)provider_max = spec.max_batch_items if spec else 256batch_size = max(1, min(self.config.batch_size, provider_max))@@ -276,6 +262,7 @@ class EmbeddingClient:contents=batch,enable_fusion=False,)+ await self._wait_for_request_slot()response = await self.adapter.embed(request)validated = validate_embedding_batch(response.embeddings,@@ -300,9 +287,6 @@ class EmbeddingClient:exc_info=True,)- if i < total_batches - 1 and self.config.batch_delay > 0:- await asyncio.sleep(self.config.batch_delay)-return all_embeddingsdef embed_sync(self, texts: List[str]) -> List[List[float]]:diff --git a/deeptutor/services/llm/reasoning_params.py b/deeptutor/services/llm/reasoning_params.pyindex 4d3ccbf4d..9d0106524 100644--- a/deeptutor/services/llm/reasoning_params.py+++ b/deeptutor/services/llm/reasoning_params.py@@ -171,6 +171,13 @@ def build_openai_compatible_reasoning_kwargs(if not patterns:patterns = custom_patterns+ # Qwen Instruct variants do not implement thinking controls, even when a+ # caller explicitly requests an effort. Do not replace the unsupported+ # native parameter with the equally unsupported top-level effort field.+ model_tokens = model_name.lower().replace("_", "-").split("-")+ if thinking_style == "enable_thinking" and "instruct" in model_tokens:+ return {}+resolved_effort = reasoning_effortif resolved_effort is None:if patterns and _matches(model_name, patterns):diff --git a/tests/core/test_agentic_client_provider_kwargs.py b/tests/core/test_agentic_client_provider_kwargs.pyindex 0cf8690e1..8fba38ac5 100644--- a/tests/core/test_agentic_client_provider_kwargs.py+++ b/tests/core/test_agentic_client_provider_kwargs.py@@ -75,7 +75,7 @@ def test_agentic_kwargs_enable_qwen_thinking_for_custom_binding() -> None:assert kwargs["extra_body"] == {"enable_thinking": True}-def test_agentic_kwargs_disable_qwen_thinking_for_custom_minimal_reasoning() -> None:+def test_agentic_kwargs_omit_thinking_for_qwen_instruct() -> None:kwargs = build_completion_kwargs(temperature=0.7,model="Qwen/Qwen3-235B-A22B-Instruct",@@ -85,7 +85,7 @@ def test_agentic_kwargs_disable_qwen_thinking_for_custom_minimal_reasoning() ->)assert "reasoning_effort" not in kwargs- assert kwargs["extra_body"] == {"enable_thinking": False}+ assert "extra_body" not in kwargsdef test_agentic_kwargs_preserve_legacy_shape_without_binding() -> None:diff --git a/tests/services/config/test_embedding_runtime.py b/tests/services/config/test_embedding_runtime.pyindex 002d2dced..6d89e822d 100644--- a/tests/services/config/test_embedding_runtime.py+++ b/tests/services/config/test_embedding_runtime.py@@ -636,3 +636,51 @@ def test_embedding_provider_profile_key() -> None:resolved = resolve_embedding_runtime_config(catalog=catalog)assert resolved.provider_name == "cohere"assert resolved.api_key == "cohere-test-key"++[email protected]("binding", ["openai", "custom"])+def test_generic_local_embedding_endpoint_accepts_empty_key(binding):+ catalog = _build_catalog(+ embedding_profile={+ "id": "embedding-p",+ "binding": binding,+ "base_url": "http://localhost:1234/v1/embeddings",+ "api_key": "",+ "models": [{"id": "embedding-m", "model": "local-embedding"}],+ }+ )+ config = get_embedding_config(catalog=catalog)+ assert config.provider_mode == "local"+ assert config.api_key == ""+ assert config.effective_url == "http://localhost:1234/v1/embeddings"+++def test_invalid_lemonade_port_does_not_raise_during_detection():+ from deeptutor.services.config.provider_runtime import _is_legacy_lemonade_endpoint++ assert not _is_legacy_lemonade_endpoint("http://localhost:not-a-port/v1")+++ "endpoint, expected",+ [+ ("http://localhost:11434/v1/embeddings", "vllm"),+ ("http://localhost:1234/v1/embeddings?model=11434", "vllm"),+ ("http://localhost:11434/api/embed", "ollama"),+ ("http://localhost:9000/api/embed", "ollama"),+ ],+)+def test_local_embedding_protocol_follows_endpoint_path(endpoint, expected):+ catalog = _build_catalog(+ embedding_profile={+ "id": "embedding-p",+ "binding": "openai",+ "base_url": endpoint,+ "api_key": "",+ "models": [{"id": "embedding-m", "model": "nomic-embed-text"}],+ }+ )+ config = get_embedding_config(catalog=catalog)+ assert config.binding == expected+ assert config.effective_url == endpoint+ assert config.api_key == ""diff --git a/tests/services/embedding/test_client_runtime.py b/tests/services/embedding/test_client_runtime.pyindex 37da74266..ea2861cc4 100644--- a/tests/services/embedding/test_client_runtime.py+++ b/tests/services/embedding/test_client_runtime.py@@ -140,40 +140,65 @@ async def test_embedding_client_overlaps_calls_when_batch_delay_is_zero(@pytest.mark.asyncio-async def test_embedding_client_serializes_when_batch_delay_is_set(monkeypatch) -> None:- class _ConcurrentAdapter(_FakeAdapter):- in_flight = 0- max_in_flight = 0[email protected]("multimodal", [False, True])+async def test_embedding_requests_are_spaced_but_http_can_overlap(monkeypatch, multimodal):+ from time import monotonic++ entered = asyncio.Event()+ release = asyncio.Event()+ starts = []++ class Adapter(_FakeAdapter):+ def get_model_info(self):+ return {"multimodal": True}async def embed(self, request):- type(self).in_flight += 1- type(self).max_in_flight = max(type(self).max_in_flight, type(self).in_flight)- try:- await asyncio.sleep(0.02)- return await super().embed(request)- finally:- type(self).in_flight -= 1+ starts.append(monotonic())+ if len(starts) == 2:+ entered.set()+ await release.wait()+ items = request.contents or request.texts+ return type("Resp", (), {"embeddings": [[0.1, 0.2] for _ in items]})()- _FakeAdapter.instances = []monkeypatch.setattr(- "deeptutor.services.embedding.client._resolve_adapter_class",- lambda _b: _ConcurrentAdapter,+ "deeptutor.services.embedding.client._resolve_adapter_class", lambda _: Adapter)monkeypatch.setattr(EmbeddingClient, "_spacing_lock", None)monkeypatch.setattr(EmbeddingClient, "_last_request_monotonic", 0.0)- _ConcurrentAdapter.in_flight = 0- _ConcurrentAdapter.max_in_flight = 0config = _build_config("openai")- config.batch_delay = 0.05- client = EmbeddingClient(config)-- first, second = await asyncio.wait_for(- asyncio.gather(client.embed(["first"]), client.embed(["second"])),- timeout=1.0,+ config.batch_delay = 0.02+ first_client = EmbeddingClient(config)+ second_client = EmbeddingClient(config)+ first = asyncio.create_task(first_client.embed(["text"]))+ second = asyncio.create_task(+ second_client.embed_contents([{"image": "data:image/png;base64,test"}])+ if multimodal+ else second_client.embed(["other"]))+ try:+ # Both requests must start before either HTTP response is released.+ await asyncio.wait_for(entered.wait(), timeout=1)+ assert starts[1] - starts[0] >= config.batch_delay+ finally:+ release.set()+ await asyncio.gather(first, second)- assert len(first) == len(second) == 1- assert _ConcurrentAdapter.max_in_flight == 1++async def test_cancelled_spacing_wait_releases_cross_thread_lock(monkeypatch):+ from time import monotonic++ monkeypatch.setattr(EmbeddingClient, "_spacing_lock", threading.Lock())+ monkeypatch.setattr(EmbeddingClient, "_last_request_monotonic", monotonic())+ client = EmbeddingClient(_build_config("openai"))+ client.config.batch_delay = 60+ waiting = asyncio.create_task(client._wait_for_request_slot())+ await asyncio.sleep(0)+ assert EmbeddingClient._spacing_lock.locked()+ waiting.cancel()+ with pytest.raises(asyncio.CancelledError):+ await waiting+ assert not EmbeddingClient._spacing_lock.locked()@pytest.mark.asyncio@@ -469,3 +494,37 @@ async def test_embed_contents_progress_callback_failure_logged_and_not_fatal(warnings = [r for r in caplog.records if r.levelno >= logging.WARNING]assert any("progress callback" in r.getMessage() for r in warnings)assert any("progress sink offline" in r.getMessage() for r in warnings)+++def test_embedding_spacing_shared_across_thread_event_loops(monkeypatch):+ from concurrent.futures import ThreadPoolExecutor+ from time import monotonic++ starts = []+ requests_started = threading.Event()+ starts_guard = threading.Lock()++ class Adapter(_FakeAdapter):+ async def embed(self, request):+ with starts_guard:+ starts.append(monotonic())+ if len(starts) == 2:+ requests_started.set()+ deadline = monotonic() + 2+ while not requests_started.is_set():+ assert monotonic() < deadline, "HTTP calls serialized across thread loops"+ await asyncio.sleep(0.005)+ return await super().embed(request)++ monkeypatch.setattr(+ "deeptutor.services.embedding.client._resolve_adapter_class", lambda _: Adapter+ )+ monkeypatch.setattr(EmbeddingClient, "_spacing_lock", None)+ monkeypatch.setattr(EmbeddingClient, "_last_request_monotonic", 0.0)+ config = _build_config("openai")+ config.batch_delay = 0.02+ clients = [EmbeddingClient(config), EmbeddingClient(config)]+ with ThreadPoolExecutor(max_workers=2) as executor:+ futures = [executor.submit(asyncio.run, client.embed(["text"])) for client in clients]+ assert all(len(future.result(timeout=3)) == 1 for future in futures)+ assert starts[1] - starts[0] >= config.batch_delaydiff --git a/tests/services/llm/test_reasoning_params.py b/tests/services/llm/test_reasoning_params.pyindex 8c70884fb..d9e37e354 100644--- a/tests/services/llm/test_reasoning_params.py+++ b/tests/services/llm/test_reasoning_params.py@@ -122,3 +122,23 @@ def test_an_explicitly_requested_off_is_narrowed_like_an_inferred_one() -> None:assert effort("gemini-2.5-flash") == "none"assert thinking_off_effort_for("openai", "gpt-4o") == "none"assert thinking_off_effort_for(None, None) == "none"++[email protected]("binding", ["custom", "openai", "dashscope"])[email protected]("effort", [None, "high", "none", "minimal"])[email protected]("model", ["Qwen/Qwen3-VL-30B-A3B-Instruct", "qwen3_235b_instruct_2507"])+def test_qwen_instruct_omits_unsupported_reasoning_controls(binding, effort, model) -> None:+ assert (+ build_openai_compatible_reasoning_kwargs(+ spec=None, binding=binding, model=model, reasoning_effort=effort+ )+ == {}+ )++[email protected]("binding", ["custom", "dashscope"])[email protected]("effort,enabled", [(None, True), ("high", True), ("none", False)])+def test_qwen_thinking_models_keep_native_controls(binding, effort, enabled) -> None:+ assert build_openai_compatible_reasoning_kwargs(+ spec=None, binding=binding, model="qwen3-235b-a22b", reasoning_effort=effort+ ) == {"extra_body": {"enable_thinking": enabled}}