deeptutor-knowledge 1.7.0__py3-none-any.whl

deeptutor/services/embedding/adapters/openai_sdk.py

@@ -0,0 +1,150 @@
+"""Legacy embedding adapter using AsyncOpenAI.
+
+Public Settings providers use exact endpoint URLs and raw HTTP adapters so the
+URL shown in Settings is the URL sent on the wire. This SDK adapter is retained
+for old configs/tests that intentionally depend on AsyncOpenAI semantics.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict
+
+from openai import APIConnectionError, APIError, APIStatusError, AsyncOpenAI
+
+from deeptutor.services.embedding.request_options import should_send_embedding_dimensions
+from deeptutor.services.llm.openai_http_client import openai_client_kwargs
+
+from .base import (
+    BaseEmbeddingAdapter,
+    EmbeddingProviderError,
+    EmbeddingRequest,
+    EmbeddingResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAISDKEmbeddingAdapter(BaseEmbeddingAdapter):
+    """Embedding adapter using the official ``AsyncOpenAI`` client."""
+
+    def _should_send_dimensions(self, model_name: str | None) -> bool:
+        """Mirror of the heuristic in :mod:`openai_compatible`.
+
+        Tri-state ``self.send_dimensions``: ``True`` always send, ``False``
+        never send, ``None`` auto by model family.
+        """
+        return should_send_embedding_dimensions(
+            binding=None,
+            model=model_name,
+            dimension=self.dimensions or 1,
+            send_dimensions=self.send_dimensions,
+        )
+
+    def _build_client(self) -> AsyncOpenAI:
+        # OpenRouter / custom gateways often don't validate the key, but the
+        # SDK refuses to construct without one. Use a placeholder when empty.
+        return AsyncOpenAI(
+            api_key=self.api_key or "sk-no-key-required",
+            base_url=self.base_url,
+            timeout=max(self.request_timeout, 60),
+            default_headers=(
+                {str(k): str(v) for k, v in self.extra_headers.items()}
+                if self.extra_headers
+                else None
+            ),
+            max_retries=2,
+            **openai_client_kwargs(timeout=max(self.request_timeout, 60)),
+        )
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        if request.contents:
+            raise ValueError(
+                "openai_sdk adapter does not support multimodal `contents`. "
+                "Pick a multimodal-capable provider (cohere, aliyun)."
+            )
+
+        model = request.model or self.model
+        kwargs: Dict[str, Any] = {
+            "model": model,
+            "input": request.texts,
+            # Unlike the gateway adapter (which omits `encoding_format` to avoid
+            # HTTP 400s), the official OpenAI/Azure API accepts it and callers
+            # expect float vectors, so pin "float" when none is set explicitly.
+            "encoding_format": request.encoding_format or "float",
+        }
+        dim_value = request.dimensions or self.dimensions
+        if dim_value and self._should_send_dimensions(model):
+            kwargs["dimensions"] = dim_value
+
+        client = self._build_client()
+        try:
+            response = await client.embeddings.create(**kwargs)
+        except APIStatusError as exc:
+            try:
+                body = exc.response.text
+            except Exception:
+                body = str(exc)
+            raise EmbeddingProviderError(
+                f"OpenAI SDK request failed: {exc}",
+                status=getattr(exc, "status_code", None),
+                body=body,
+                model=model,
+                url=self.base_url,
+                provider="openai_sdk",
+            ) from exc
+        except APIConnectionError as exc:
+            raise EmbeddingProviderError(
+                f"OpenAI SDK connection error: {exc}",
+                model=model,
+                url=self.base_url,
+                provider="openai_sdk",
+            ) from exc
+        except APIError as exc:
+            raise EmbeddingProviderError(
+                f"OpenAI SDK API error: {exc}",
+                model=model,
+                url=self.base_url,
+                provider="openai_sdk",
+            ) from exc
+        finally:
+            try:
+                await client.close()
+            except Exception:
+                pass
+
+        embeddings = [list(item.embedding) for item in response.data]
+        if not embeddings:
+            raise ValueError("openai_sdk returned an empty data list.")
+
+        actual_dims = len(embeddings[0])
+        usage_obj = getattr(response, "usage", None)
+        if usage_obj is None:
+            usage: Dict[str, Any] = {}
+        elif hasattr(usage_obj, "model_dump"):
+            usage = usage_obj.model_dump()
+        elif isinstance(usage_obj, dict):
+            usage = usage_obj
+        else:
+            usage = {}
+
+        logger.info(
+            f"Generated {len(embeddings)} embeddings via openai SDK "
+            f"(model={model}, dim={actual_dims}, base_url={self.base_url})"
+        )
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            model=getattr(response, "model", None) or model,
+            dimensions=actual_dims,
+            usage=usage,
+        )
+
+    def get_model_info(self) -> Dict[str, Any]:
+        return {
+            "model": self.model,
+            "dimensions": self.dimensions,
+            "supports_variable_dimensions": False,
+            "multimodal": False,
+            "provider": "openai_sdk",
+        }

deeptutor/services/embedding/client.py

@@ -0,0 +1,323 @@
+"""Unified embedding client backed by normalized provider runtime config."""
+
+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 (
+    redact_embedding_endpoint_for_display,
+)
+from deeptutor.services.config.provider_runtime import (
+    EMBEDDING_PROVIDERS,
+    embedding_endpoint_validation_error,
+)
+
+from .adapters import ADAPTER_BACKENDS, BaseEmbeddingAdapter, EmbeddingRequest
+from .config import EmbeddingConfig, get_embedding_config
+from .validation import validate_embedding_batch
+
+
+def _resolve_adapter_class(binding: str) -> type[BaseEmbeddingAdapter]:
+    provider = (binding or "").strip().lower()
+    spec = EMBEDDING_PROVIDERS.get(provider)
+    if spec is None:
+        supported = sorted(EMBEDDING_PROVIDERS.keys())
+        raise ValueError(
+            f"Unknown embedding binding: '{binding}'. Supported: {', '.join(supported)}"
+        )
+    cls = ADAPTER_BACKENDS.get(spec.adapter)
+    if cls is None:
+        raise ValueError(
+            f"No adapter registered for backend '{spec.adapter}' (binding='{binding}')"
+        )
+    return cls
+
+
+class EmbeddingClient:
+    """Unified embedding client for RAG and retrieval services."""
+
+    # 全局发帖节流：KB reindex 时 LlamaIndex 用线程池并发调 embedding，
+    # 每个线程经 _run_in_new_loop 跑独立 event loop——asyncio.Lock 绑定
+    # 创建时的 loop，跨 loop 既不互斥还会挂死。必须用线程级锁。
+    _spacing_lock: Any = None
+    _last_request_monotonic: float = 0.0
+    _thread_guard = threading.Lock()
+
+    @classmethod
+    def _global_spacing_lock(cls):
+        with cls._thread_guard:
+            if cls._spacing_lock is None:
+                cls._spacing_lock = threading.Lock()
+        return cls._spacing_lock
+
+    @staticmethod
+    @asynccontextmanager
+    async def _hold_spacing_lock():
+        """Acquire the cross-thread lock without blocking the current loop."""
+        import asyncio
+
+        lock = EmbeddingClient._global_spacing_lock()
+        while not lock.acquire(blocking=False):
+            await asyncio.sleep(0.05)
+        try:
+            yield
+        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__)
+        endpoint = self.config.effective_url or self.config.base_url
+        problem = embedding_endpoint_validation_error(self.config.binding, endpoint)
+        if problem:
+            displayed_endpoint = redact_embedding_endpoint_for_display(endpoint)
+            raise ValueError(
+                f"{problem} Current Settings endpoint is {displayed_endpoint!r}. "
+                "DeepTutor sends embedding requests to the Settings URL exactly; "
+                "update the visible Endpoint URL instead of relying on hidden path appending."
+            )
+        adapter_class = _resolve_adapter_class(self.config.binding)
+        self.adapter = adapter_class(
+            {
+                "api_key": self.config.api_key,
+                "base_url": self.config.effective_url or self.config.base_url,
+                "api_version": self.config.api_version,
+                "model": self.config.model,
+                "dimensions": self.config.dim,
+                "send_dimensions": self.config.send_dimensions,
+                "request_timeout": self.config.request_timeout,
+                "extra_headers": self.config.extra_headers or {},
+            }
+        )
+        self.logger.info(
+            f"Initialized embedding client with {self.config.binding} adapter "
+            f"(model: {self.config.model}, dimensions: {self.config.dim})"
+        )
+
+    async def embed(
+        self,
+        texts: List[str],
+        progress_callback=None,
+        *,
+        input_type: str | None = None,
+    ) -> List[List[float]]:
+        """Embed text batches, optionally identifying their retrieval role."""
+        if not texts:
+            return []
+
+        # Only adapters that opted in receive the role. Forwarding it to every
+        # backend would change the request Jina has always sent (no `task`) and
+        # silently invalidate the indexes built from it.
+        role = input_type if getattr(self.adapter, "SUPPORTS_INPUT_TYPE", False) else None
+
+        # 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
+        # chunks fails on the second batch even when "Test connection" passes.
+        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))
+        if batch_size < self.config.batch_size:
+            self.logger.info(
+                f"Clamped batch_size {self.config.batch_size} -> {batch_size} "
+                f"(provider '{self.config.binding}' max={provider_max})"
+            )
+        all_embeddings: List[List[float]] = []
+        expected_dim: int | None = None
+
+        total_batches = (len(texts) + batch_size - 1) // batch_size
+        for i, start in enumerate(range(0, len(texts), batch_size)):
+            batch = texts[start : start + batch_size]
+            request = EmbeddingRequest(
+                texts=batch,
+                model=self.config.model,
+                dimensions=self.config.dim or None,
+                input_type=role,
+            )
+            try:
+                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.
+                import traceback
+
+                first_chunk_chars = len(batch[0]) if batch else 0
+                longest_chunk_chars = max((len(t) for t in batch), default=0)
+                self.logger.error(
+                    f"Embedding batch failed "
+                    f"(binding={self.config.binding}, model={self.config.model}, "
+                    f"batch_index={i + 1}/{total_batches}, batch_items={len(batch)}, "
+                    f"first_chunk_chars={first_chunk_chars}, "
+                    f"longest_chunk_chars={longest_chunk_chars}): {exc}\n"
+                    f"{traceback.format_exc()}"
+                )
+                raise
+            validated = validate_embedding_batch(
+                response.embeddings,
+                expected_count=len(batch),
+                binding=self.config.binding,
+                model=self.config.model,
+                batch_index=i + 1,
+                total_batches=total_batches,
+                start_index=start,
+            )
+            batch_dim = len(validated[0]) if validated else 0
+            if expected_dim is None:
+                expected_dim = batch_dim
+            elif batch_dim != expected_dim:
+                raise ValueError(
+                    "Embedding provider returned inconsistent vector dimensions "
+                    f"across batches (binding={self.config.binding}, "
+                    f"model={self.config.model}): expected {expected_dim}, "
+                    f"got {batch_dim} in batch {i + 1}/{total_batches}. "
+                    "Use a single embedding model/dimension and re-index the knowledge base."
+                )
+
+            all_embeddings.extend(validated)
+
+            # Report progress after each batch
+            if progress_callback:
+                try:
+                    progress_callback(i + 1, total_batches)
+                except Exception as exc:
+                    # Progress feedback is best-effort: never fail the embedding
+                    # run, but never lose the failure silently either — index
+                    # progress would read as stalled with no trace why.
+                    self.logger.warning(
+                        f"Embedding progress callback failed "
+                        f"(batch {i + 1}/{total_batches}): {exc}",
+                        exc_info=True,
+                    )
+
+        self.logger.debug(
+            f"Generated {len(all_embeddings)} embeddings using "
+            f"{self.config.binding} (batch_size={batch_size})"
+        )
+        return all_embeddings
+
+    def supports_multimodal_contents(self) -> bool:
+        """Return whether the configured adapter/model accepts multimodal contents."""
+        try:
+            info = self.adapter.get_model_info()
+            if "multimodal" in info:
+                return bool(info.get("multimodal"))
+        except Exception:
+            pass
+
+        spec = EMBEDDING_PROVIDERS.get(self.config.binding)
+        return bool(spec and spec.multimodal)
+
+    async def embed_contents(
+        self,
+        contents: List[Dict[str, Any]],
+        *,
+        progress_callback=None,
+    ) -> List[List[float]]:
+        """Embed provider-agnostic multimodal content items.
+
+        ``contents`` uses the same simple contract as ``EmbeddingRequest``:
+        ``[{"text": "..."}, {"image": "data:...|url"}, {"video": "..."}]``.
+        """
+        if not contents:
+            return []
+        if not self.supports_multimodal_contents():
+            raise ValueError(
+                "Configured embedding provider/model does not support multimodal contents."
+            )
+
+        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))
+        all_embeddings: List[List[float]] = []
+        total_batches = (len(contents) + batch_size - 1) // batch_size
+
+        for i, start in enumerate(range(0, len(contents), batch_size)):
+            batch = contents[start : start + batch_size]
+            request = EmbeddingRequest(
+                texts=[],
+                model=self.config.model,
+                dimensions=self.config.dim or None,
+                contents=batch,
+                enable_fusion=False,
+            )
+            await self._wait_for_request_slot()
+            response = await self.adapter.embed(request)
+            validated = validate_embedding_batch(
+                response.embeddings,
+                expected_count=len(batch),
+                binding=self.config.binding,
+                model=self.config.model,
+                batch_index=i + 1,
+                total_batches=total_batches,
+                start_index=start,
+            )
+            all_embeddings.extend(validated)
+
+            if progress_callback:
+                try:
+                    progress_callback(i + 1, total_batches)
+                except Exception as exc:
+                    # Same contract as embed(): log and continue, so a broken
+                    # progress sink cannot stall multimodal indexing invisibly.
+                    self.logger.warning(
+                        f"Embedding progress callback failed "
+                        f"(batch {i + 1}/{total_batches}): {exc}",
+                        exc_info=True,
+                    )
+
+        return all_embeddings
+
+    def embed_sync(self, texts: List[str]) -> List[List[float]]:
+        import asyncio
+
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(self.embed(texts))
+
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            future = executor.submit(asyncio.run, self.embed(texts))
+            return future.result()
+
+
+_client: Optional[EmbeddingClient] = None
+
+
+def get_embedding_client(config: Optional[EmbeddingConfig] = None) -> EmbeddingClient:
+    global _client
+    resolved_config = config or get_embedding_config()
+    client = _client
+    if client is None or client.config != resolved_config:
+        client = EmbeddingClient(resolved_config)
+        _client = client
+    # Each caller retains its own client even if another worker changes the cache.
+    return client
+
+
+def reset_embedding_client() -> None:
+    global _client
+    _client = None

deeptutor/services/embedding/config.py

@@ -0,0 +1,114 @@
+"""Normalized embedding configuration resolved from the model catalog."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from copy import deepcopy
+from dataclasses import dataclass
+
+from deeptutor.services.config import resolve_embedding_runtime_config
+
+
+@dataclass
+class EmbeddingConfig:
+    """Embedding runtime configuration."""
+
+    model: str
+    api_key: str | list[str]
+    base_url: str | None = None
+    effective_url: str | None = None
+    binding: str = "openai"
+    provider_name: str = "openai"
+    provider_mode: str = "standard"
+    api_version: str | None = None
+    extra_headers: dict[str, str] | None = None
+    dim: int = 0
+    send_dimensions: bool | None = None
+    request_timeout: int = 60
+    batch_size: int = 10
+    batch_delay: float = 0.0
+
+
+_scoped_config: ContextVar[EmbeddingConfig | None] = ContextVar("embedding_config", default=None)
+
+
+def scoped_embedding_config() -> EmbeddingConfig | None:
+    return _scoped_config.get()
+
+
+@contextmanager
+def embedding_config_scope(config: EmbeddingConfig):
+    """Bind one operation, including its worker threads, to a resolved model."""
+    token = _scoped_config.set(config)
+    try:
+        yield
+    finally:
+        _scoped_config.reset(token)
+
+
+def get_embedding_config(
+    selection: dict | None = None, *, catalog: dict | None = None
+) -> EmbeddingConfig:
+    """Load embedding config from provider runtime resolver."""
+    if selection is None and catalog is None and _scoped_config.get() is not None:
+        return _scoped_config.get()
+    if selection is not None:
+        from deeptutor.services.config import get_model_catalog_service
+
+        catalog = deepcopy(catalog if catalog is not None else get_model_catalog_service().load())
+        service = catalog.get("services", {}).get("embedding", {})
+        profile = next(
+            (p for p in service.get("profiles", []) if p.get("id") == selection.get("profile_id")),
+            None,
+        )
+        model = next(
+            (
+                m
+                for m in (profile or {}).get("models", [])
+                if m.get("id") == selection.get("model_id")
+            ),
+            None,
+        )
+        if profile is None or model is None:
+            raise ValueError(
+                "The embedding model bound to this knowledge base was deleted. Select another embedding model to re-index it."
+            )
+        service["active_profile_id"] = profile["id"]
+        service["active_model_id"] = model["id"]
+    resolved = (
+        resolve_embedding_runtime_config(catalog=catalog)
+        if catalog is not None
+        else resolve_embedding_runtime_config()
+    )
+
+    if not resolved.model:
+        raise ValueError("Embedding model not set. Configure it in Settings > Embedding models.")
+
+    if not resolved.effective_url:
+        raise ValueError(
+            "No effective embedding endpoint resolved. Please configure base_url/host for the active profile."
+        )
+
+    if resolved.provider_mode != "local" and not resolved.api_key:
+        raise ValueError(
+            "Embedding API key not set. Configure the active profile in "
+            "Settings > Embedding models."
+        )
+
+    return EmbeddingConfig(
+        model=resolved.model,
+        api_key=resolved.api_key,
+        base_url=resolved.base_url,
+        effective_url=resolved.effective_url,
+        binding=resolved.binding,
+        provider_name=resolved.provider_name,
+        provider_mode=resolved.provider_mode,
+        api_version=resolved.api_version,
+        extra_headers=resolved.extra_headers,
+        dim=resolved.dimension,
+        send_dimensions=resolved.send_dimensions,
+        request_timeout=max(1, resolved.request_timeout),
+        batch_size=max(1, resolved.batch_size),
+        batch_delay=max(0.0, resolved.batch_delay),
+    )

deeptutor/services/embedding/request_options.py

@@ -0,0 +1,46 @@
+"""Shared request-option decisions for embedding transports."""
+
+from __future__ import annotations
+
+from deeptutor.services.config.embedding_endpoint import canonical_embedding_provider_name
+
+_JINA_VARIABLE_DIMENSIONS: dict[str, frozenset[int]] = {
+    "jina-embeddings-v3": frozenset({32, 64, 128, 256, 512, 768, 1024}),
+    "jina-embeddings-v4": frozenset({32, 64, 128, 256, 512, 768, 1024}),
+}
+
+
+def should_send_embedding_dimensions(
+    *,
+    binding: str | None,
+    model: str | None,
+    dimension: int | None,
+    send_dimensions: bool | None,
+) -> bool:
+    """Apply DeepTutor's tri-state ``dimensions`` request policy.
+
+    Explicit user choices always win. In automatic mode, Jina uses its known
+    Matryoshka dimensions while OpenAI-compatible transports use the model
+    families already supported by DeepTutor's regular embedding adapters.
+    """
+    if not dimension:
+        return False
+    if send_dimensions is True:
+        return True
+    if send_dimensions is False:
+        return False
+
+    provider = canonical_embedding_provider_name(binding)
+    model_name = str(model or "").strip()
+    if provider == "jina":
+        return dimension in _JINA_VARIABLE_DIMENSIONS.get(model_name, frozenset())
+
+    lowered = model_name.lower()
+    return (
+        lowered.startswith("text-embedding-3")
+        or "qwen3-embedding" in lowered
+        or "qwen3-vl-embedding" in lowered
+    )
+
+
+__all__ = ["should_send_embedding_dimensions"]