deeptutor-knowledge 1.7.0__py3-none-any.whl

deeptutor/services/embedding/adapters/cohere.py

@@ -0,0 +1,176 @@
+"""Cohere Embedding Adapter for v1 and v2 API."""
+
+import logging
+from typing import Any, Dict
+
+import httpx
+
+from deeptutor.services.llm.openai_http_client import disable_ssl_verify_enabled
+
+from .base import BaseEmbeddingAdapter, EmbeddingRequest, EmbeddingResponse
+
+logger = logging.getLogger(__name__)
+
+
+class CohereEmbeddingAdapter(BaseEmbeddingAdapter):
+    """Adapter for Cohere Embed API (v1 and v2)."""
+
+    # Cohere requires input_type and already defaults to "search_document",
+    # so document vectors are unchanged and only queries gain the right role.
+    SUPPORTS_INPUT_TYPE = True
+
+    MODELS_INFO = {
+        "embed-v4.0": {
+            "dimensions": [256, 512, 1024, 1536],
+            "default": 1024,
+            "api_version": "v2",
+            "multimodal": True,
+        },
+        "embed-english-v3.0": {
+            "dimensions": [1024],
+            "default": 1024,
+            "api_version": "v1",
+            "multimodal": False,
+        },
+        "embed-multilingual-v3.0": {
+            "dimensions": [1024],
+            "default": 1024,
+            "api_version": "v1",
+            "multimodal": False,
+        },
+        "embed-multilingual-light-v3.0": {
+            "dimensions": [384],
+            "default": 384,
+            "api_version": "v1",
+            "multimodal": False,
+        },
+        "embed-english-light-v3.0": {
+            "dimensions": [384],
+            "default": 384,
+            "api_version": "v1",
+            "multimodal": False,
+        },
+    }
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        headers.update({str(k): str(v) for k, v in self.extra_headers.items()})
+
+        model_name = request.model or self.model
+        model_info = self.MODELS_INFO.get(model_name, {})
+        # `api_version` is now purely a request-shape selector (v1 vs v2 payload).
+        # The URL itself is whatever the user configured. Resolution order:
+        #   explicit self.api_version (catalog/env override) → MODELS_INFO entry → "v2"
+        api_version = self.api_version or model_info.get("api_version") or "v2"
+        dimension = request.dimensions or self.dimensions
+
+        input_type = request.input_type or "search_document"
+
+        if api_version == "v1":
+            if request.contents:
+                raise ValueError(
+                    "Cohere v1 API does not support multimodal `contents`. "
+                    "Use embed-v4.0 (v2 API) for multimodal."
+                )
+            payload = {
+                "texts": request.texts,
+                "model": model_name,
+                "input_type": input_type,
+            }
+
+            if not request.truncate:
+                payload["truncate"] = "NONE"
+        else:
+            if request.contents and not bool(model_info.get("multimodal", False)):
+                raise ValueError(
+                    f"Cohere model '{model_name}' does not support multimodal `contents`."
+                )
+            payload = {
+                "model": model_name,
+                "embedding_types": ["float"],
+                "input_type": input_type,
+            }
+
+            if request.contents:
+                # Cohere v2 multimodal: `inputs: [{content: [{type, text|image_url}]}]`
+                # We translate the simple [{text|image|video}] contract into v2's
+                # nested form. v2 cannot mix text+image in one input, so each
+                # content dict becomes its own input item.
+                inputs = []
+                for item in request.contents:
+                    if not isinstance(item, dict):
+                        continue
+                    kind, value = next(iter(item.items()))
+                    if kind == "text":
+                        inputs.append({"content": [{"type": "text", "text": value}]})
+                    elif kind == "image":
+                        inputs.append(
+                            {"content": [{"type": "image_url", "image_url": {"url": value}}]}
+                        )
+                    else:
+                        raise ValueError(f"Cohere v2 does not support content type '{kind}'")
+                payload["inputs"] = inputs
+            else:
+                payload["texts"] = request.texts
+
+            supported_dims = model_info.get("dimensions", [])
+            if isinstance(supported_dims, list) and len(supported_dims) > 1:
+                payload["output_dimension"] = dimension or model_info.get("default")
+
+            if not request.truncate:
+                payload["truncate"] = "NONE"
+
+        url = self.base_url
+
+        logger.debug(f"Sending embedding request to {url} with {len(request.texts)} texts")
+
+        async with httpx.AsyncClient(
+            timeout=self.request_timeout, verify=not disable_ssl_verify_enabled()
+        ) as client:
+            response = await client.post(url, json=payload, headers=headers)
+
+            if response.status_code >= 400:
+                logger.error(f"HTTP {response.status_code} response body: {response.text}")
+
+            response.raise_for_status()
+            data = response.json()
+
+        if api_version == "v1":
+            embeddings = data["embeddings"]
+        else:
+            embeddings = data["embeddings"]["float"]
+
+        actual_dims = len(embeddings[0]) if embeddings else 0
+        expected_dims = request.dimensions or self.dimensions
+
+        if expected_dims and actual_dims != expected_dims:
+            logger.warning(f"Dimension mismatch: expected {expected_dims}, got {actual_dims}")
+
+        logger.info(
+            f"Successfully generated {len(embeddings)} embeddings "
+            f"(model: {data.get('model', self.model)}, dimensions: {actual_dims})"
+        )
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            model=data.get("model", self.model),
+            dimensions=actual_dims,
+            usage=data.get("meta", {}).get("billed_units", {}),
+        )
+
+    def get_model_info(self) -> Dict[str, Any]:
+        model_info = self.MODELS_INFO.get(self.model, {})
+        dimensions_list = model_info.get("dimensions", [])
+        api_version = self.api_version or model_info.get("api_version") or "v2"
+        return {
+            "model": self.model,
+            "dimensions": model_info.get("default", self.dimensions),
+            "supports_variable_dimensions": len(dimensions_list) > 1
+            if isinstance(dimensions_list, list)
+            else False,
+            "multimodal": bool(model_info.get("multimodal", False)) and api_version != "v1",
+            "provider": "cohere",
+        }

deeptutor/services/embedding/adapters/dashscope_native.py

@@ -0,0 +1,242 @@
+"""Aliyun DashScope embedding adapter (text + multimodal).
+
+Uses the ``dashscope`` Python SDK rather than the OpenAI contract because
+DashScope's native API shape does not match it. DashScope splits embeddings
+across two surfaces served from different endpoints, and the SDK derives the
+endpoint from the model id:
+
+* multimodal models (``qwen3-vl-embedding``, ``multimodal-embedding-v1``) use
+  ``dashscope.MultiModalEmbedding.call`` (``input=[{text|image|video}]`` +
+  ``parameters={dimension, enable_fusion}``);
+* text models (``text-embedding-v1..v4``) use ``dashscope.TextEmbedding.call``
+  (``input=[str, ...]``).
+
+Routing a text model through the multimodal call sends it to the multimodal
+endpoint and fails with HTTP 400 "url error" (issue #660), so ``embed`` picks
+the surface from the model id. Both calls are synchronous, so we run them in a
+thread pool to keep the embedding stack non-blocking.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from http import HTTPStatus
+import logging
+from typing import Any, Dict, List
+
+from deeptutor.services.config.embedding_endpoint import (
+    is_dashscope_multimodal_embedding_model,
+)
+
+from .base import BaseEmbeddingAdapter, EmbeddingRequest, EmbeddingResponse
+
+logger = logging.getLogger(__name__)
+
+
+class DashScopeMultiModalEmbeddingAdapter(BaseEmbeddingAdapter):
+    """Adapter for Aliyun DashScope (Bailian) text + multimodal embedding."""
+
+    MODELS_INFO = {
+        "qwen3-vl-embedding": {
+            "default": 2560,
+            "dimensions": [256, 512, 768, 1024, 1536, 2048, 2560],
+            "multimodal": True,
+        },
+        "multimodal-embedding-v1": {
+            "default": 1536,
+            "dimensions": [],
+            "multimodal": True,
+        },
+        "text-embedding-v3": {
+            "default": 1024,
+            "dimensions": [],
+            "multimodal": False,
+        },
+        "text-embedding-v4": {
+            "default": 1024,
+            "dimensions": [],
+            "multimodal": False,
+        },
+    }
+
+    def _build_contents(self, request: EmbeddingRequest) -> List[Dict[str, Any]]:
+        if request.contents:
+            return [item for item in request.contents if isinstance(item, dict)]
+        return [{"text": text} for text in request.texts]
+
+    def _build_parameters(self, request: EmbeddingRequest) -> Dict[str, Any]:
+        params: Dict[str, Any] = {}
+        dim_value = request.dimensions or self.dimensions
+        if dim_value:
+            params["dimension"] = dim_value
+        if request.enable_fusion is not None:
+            params["enable_fusion"] = bool(request.enable_fusion)
+        return params
+
+    def _build_text_inputs(self, request: EmbeddingRequest) -> List[str]:
+        """Flatten the request to the plain string list TextEmbedding expects."""
+        if request.texts:
+            return list(request.texts)
+        return [
+            item["text"]
+            for item in (request.contents or [])
+            if isinstance(item, dict) and item.get("text")
+        ]
+
+    def _build_text_parameters(self, request: EmbeddingRequest) -> Dict[str, Any]:
+        # TextEmbedding takes `dimension` (v3/v4 support it) but has no
+        # `enable_fusion` — that is a multimodal-only knob.
+        params: Dict[str, Any] = {}
+        dim_value = request.dimensions or self.dimensions
+        if dim_value:
+            params["dimension"] = dim_value
+        return params
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        model_name = request.model or self.model
+        if is_dashscope_multimodal_embedding_model(model_name):
+            return await self._embed_multimodal(request, model_name)
+        return await self._embed_text(request, model_name)
+
+    async def _embed_multimodal(
+        self, request: EmbeddingRequest, model_name: str
+    ) -> EmbeddingResponse:
+        try:
+            from dashscope import MultiModalEmbedding
+        except ImportError as exc:
+            raise ImportError(
+                "dashscope SDK not installed. Run `pip install dashscope` "
+                "(or add to your project deps) to enable Aliyun DashScope."
+            ) from exc
+
+        contents = self._build_contents(request)
+        parameters = self._build_parameters(request)
+
+        logger.debug(
+            "Calling dashscope.MultiModalEmbedding.call "
+            f"(model={model_name}, items={len(contents)}, params={parameters})"
+        )
+
+        # SDK call is sync — run in worker thread to avoid blocking the loop.
+        # IMPORTANT: the dashscope SDK takes a flat list for `input`
+        # (e.g. ``input=[{"text": "..."}]``) and internally wraps it as
+        # ``{"contents": [...]}`` before POSTing to the REST endpoint. Do NOT
+        # pass ``{"contents": contents}`` here — that produces a double-wrap
+        # and the API responds with HTTP 400 ("Input should be a valid list").
+        resp = await asyncio.to_thread(
+            MultiModalEmbedding.call,
+            api_key=self.api_key,
+            model=model_name,
+            input=contents,
+            **parameters,
+        )
+
+        self._raise_on_error(resp, model_name)
+        return self._parse_response(resp, model_name, request)
+
+    async def _embed_text(self, request: EmbeddingRequest, model_name: str) -> EmbeddingResponse:
+        try:
+            from dashscope import TextEmbedding
+        except ImportError as exc:
+            raise ImportError(
+                "dashscope SDK not installed. Run `pip install dashscope` "
+                "(or add to your project deps) to enable Aliyun DashScope."
+            ) from exc
+
+        inputs = self._build_text_inputs(request)
+        parameters = self._build_text_parameters(request)
+
+        logger.debug(
+            "Calling dashscope.TextEmbedding.call "
+            f"(model={model_name}, items={len(inputs)}, params={parameters})"
+        )
+
+        # TextEmbedding.call POSTs to the DashScope text-embedding endpoint and
+        # accepts a flat list of strings for `input`. Response/usage/error shape
+        # matches MultiModalEmbedding, so we reuse the shared parsers below.
+        resp = await asyncio.to_thread(
+            TextEmbedding.call,
+            api_key=self.api_key,
+            model=model_name,
+            input=inputs,
+            **parameters,
+        )
+
+        self._raise_on_error(resp, model_name)
+        return self._parse_response(resp, model_name, request)
+
+    def _raise_on_error(self, resp: Any, model_name: str) -> None:
+        status_code = getattr(resp, "status_code", None)
+        if status_code is None or status_code == HTTPStatus.OK:
+            return
+        code = getattr(resp, "code", "") or ""
+        message = getattr(resp, "message", "") or ""
+        request_id = getattr(resp, "request_id", "") or ""
+        raise RuntimeError(
+            f"DashScope MultiModalEmbedding call failed: "
+            f"status={status_code}, code={code}, message={message}, "
+            f"model={model_name}, request_id={request_id}"
+        )
+
+    def _parse_response(
+        self, resp: Any, model_name: str, request: EmbeddingRequest
+    ) -> EmbeddingResponse:
+        output = getattr(resp, "output", None)
+        if output is None:
+            raise ValueError(
+                f"DashScope response missing `output` (request_id={getattr(resp, 'request_id', '')})"
+            )
+
+        # `output` is dict-like in the SDK.
+        if isinstance(output, dict):
+            raw = output.get("embeddings") or []
+        else:
+            raw = getattr(output, "embeddings", None) or []
+
+        embeddings: List[List[float]] = []
+        for item in raw:
+            if isinstance(item, dict):
+                vec = item.get("embedding")
+            else:
+                vec = getattr(item, "embedding", None)
+            if vec is None:
+                continue
+            embeddings.append(list(vec))
+
+        if not embeddings:
+            raise ValueError(
+                "DashScope response parsed successfully but no embedding vectors were returned."
+            )
+
+        usage = getattr(resp, "usage", {}) or {}
+        if not isinstance(usage, dict):
+            usage = {
+                k: getattr(usage, k, None)
+                for k in ("input_tokens", "output_tokens", "total_tokens")
+                if hasattr(usage, k)
+            }
+
+        actual_dims = len(embeddings[0]) if embeddings else 0
+        logger.info(
+            f"Successfully generated {len(embeddings)} DashScope embeddings "
+            f"(model: {model_name}, dimensions: {actual_dims}, "
+            f"fusion={request.enable_fusion})"
+        )
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            model=model_name,
+            dimensions=actual_dims,
+            usage=usage,
+        )
+
+    def get_model_info(self) -> Dict[str, Any]:
+        info = self.MODELS_INFO.get(self.model or "", {})
+        return {
+            "model": self.model,
+            "dimensions": info.get("default", self.dimensions),
+            "supported_dimensions": info.get("dimensions", []),
+            "supports_variable_dimensions": bool(info.get("dimensions")),
+            "multimodal": bool(info.get("multimodal", False)),
+            "provider": "aliyun",
+        }