Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

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.py
index 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 False
except ValueError:
return False
- if endpoint.port != 13305:
- return False
if not _is_nonpublic_embedding_host(endpoint.hostname or ""):
return False
path = 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.py
index de23e0665..e4725be3d 100644
--- a/deeptutor/services/embedding/client.py
+++ b/deeptutor/services/embedding/client.py
@@ -4,6 +4,7 @@ from __future__ import annotations
from contextlib import asynccontextmanager
import logging
+import threading
from typing import Any, Dict, List, Optional
from 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()
@classmethod
def _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_delay
expected_dim: int | None = None
total_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 256
batch_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_embeddings
def embed_sync(self, texts: List[str]) -> List[List[float]]:
diff --git a/deeptutor/services/llm/reasoning_params.py b/deeptutor/services/llm/reasoning_params.py
index 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_effort
if 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.py
index 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 kwargs
def 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.py
index 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.py
index 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 = 0
config = _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_delay
diff --git a/tests/services/llm/test_reasoning_params.py b/tests/services/llm/test_reasoning_params.py
index 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}}