From dc02b2fbab2e0edfa05e512b6882a82924f3707c Mon Sep 17 00:00:00 2001 From: Yangtze-Seventh <1368653777@qq.com> Date: Wed, 17 Jun 2026 20:19:42 +0800 Subject: [PATCH] feat(rerank): add Bailian DashScope provider support (#295) --- .env.example | 24 ++ README.zh-CN.md | 40 +++- src/everos/component/embedding/factory.py | 5 +- src/everos/component/llm/factory.py | 5 +- src/everos/component/rerank/__init__.py | 4 + .../component/rerank/dashscope_provider.py | 190 ++++++++++++++++ src/everos/component/rerank/factory.py | 76 ++++++- src/everos/config/default.toml | 9 +- src/everos/config/settings.py | 14 +- src/everos/service/search.py | 19 +- src/everos/templates/env.template | 24 ++ .../test_embedding/test_factory.py | 6 + .../test_component/test_llm/test_factory.py | 6 + .../test_rerank/test_dashscope_provider.py | 209 ++++++++++++++++++ .../test_rerank/test_factory.py | 89 ++++++++ tests/unit/test_config/test_settings.py | 46 ++++ .../test_cli/test_init_command.py | 25 +++ 17 files changed, 765 insertions(+), 26 deletions(-) create mode 100644 src/everos/component/rerank/dashscope_provider.py create mode 100644 tests/unit/test_component/test_rerank/test_dashscope_provider.py diff --git a/.env.example b/.env.example index 6ca33de..fe392d2 100644 --- a/.env.example +++ b/.env.example @@ -34,6 +34,13 @@ EVEROS_LLM__MODEL=openai/gpt-4.1-mini EVEROS_LLM__API_KEY= EVEROS_LLM__BASE_URL=https://openrouter.ai/api/v1 +# Aliyun Bailian (DashScope) alternative — one key also covers embedding + +# rerank below, so the same value goes in all three API_KEY slots. +# Uncomment these three lines and comment out the OpenRouter lines above: +# EVEROS_LLM__MODEL=qwen-plus +# EVEROS_LLM__API_KEY= +# EVEROS_LLM__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 + # ─── Multimodal LLM (independent from [llm]; vision/audio capable) ──── # Separate model for parsing multimodal content items (image / pdf / @@ -63,6 +70,12 @@ EVEROS_MULTIMODAL__BASE_URL=https://openrouter.ai/api/v1 EVEROS_EMBEDDING__MODEL=Qwen/Qwen3-Embedding-4B EVEROS_EMBEDDING__API_KEY= EVEROS_EMBEDDING__BASE_URL=https://api.deepinfra.com/v1/openai + +# Aliyun Bailian (DashScope) alternative. Uncomment these three lines and +# comment out the DeepInfra embedding lines above: +# EVEROS_EMBEDDING__MODEL=text-embedding-v4 +# EVEROS_EMBEDDING__API_KEY= +# EVEROS_EMBEDDING__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 # Runtime knobs — uncomment to override defaults (30s / 3 / 10 / 5): # EVEROS_EMBEDDING__TIMEOUT_SECONDS=30 # EVEROS_EMBEDDING__MAX_RETRIES=3 @@ -72,10 +85,21 @@ EVEROS_EMBEDDING__BASE_URL=https://api.deepinfra.com/v1/openai # ─── Rerank (OpenAI-protocol /rerank) ──────────────── # base_url should point at the rerank endpoint (e.g. .../v1/rerank). +# EVEROS_RERANK__PROVIDER selects the request-shape: "deepinfra" (default), +# "vllm", or "dashscope". Left unset, it is inferred from the base_url host +# (dashscope.aliyuncs.com -> dashscope, *.deepinfra.com -> deepinfra). EVEROS_RERANK__MODEL=Qwen/Qwen3-Reranker-4B EVEROS_RERANK__API_KEY= EVEROS_RERANK__BASE_URL=https://api.deepinfra.com/v1/inference + +# Aliyun Bailian (DashScope) alternative. EverOS currently supports +# DashScope rerank via gte-rerank-v2; provider is auto-inferred from host, +# so EVEROS_RERANK__PROVIDER is optional. Uncomment these three lines and +# comment out the DeepInfra rerank lines above: +# EVEROS_RERANK__MODEL=gte-rerank-v2 +# EVEROS_RERANK__API_KEY= +# EVEROS_RERANK__BASE_URL=https://dashscope.aliyuncs.com # Runtime knobs — uncomment to override defaults (30s / 3 / 10 / 5): # EVEROS_RERANK__TIMEOUT_SECONDS=30 # EVEROS_RERANK__MAX_RETRIES=3 diff --git a/README.zh-CN.md b/README.zh-CN.md index 749033a..e8920df 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -173,9 +173,10 @@ Agent 记忆(cases / skills)与用户记忆( +EVEROS_LLM__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 + +EVEROS_EMBEDDING__MODEL=text-embedding-v4 +EVEROS_EMBEDDING__API_KEY= +EVEROS_EMBEDDING__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 + +EVEROS_RERANK__MODEL=gte-rerank-v2 +EVEROS_RERANK__API_KEY= +EVEROS_RERANK__BASE_URL=https://dashscope.aliyuncs.com +``` + ### 3. 启动 EverOS ```bash @@ -309,7 +335,7 @@ git clone https://github.com/EverMind-AI/EverOS.git cd EverOS uv sync # creates ./.venv and installs deps source .venv/bin/activate # or prefix commands with `uv run` -everos init # fill the four API key slots in .env (two distinct keys) +everos init # fill the API key fields in .env everos --help make test diff --git a/src/everos/component/embedding/factory.py b/src/everos/component/embedding/factory.py index 97967c4..304ab56 100644 --- a/src/everos/component/embedding/factory.py +++ b/src/everos/component/embedding/factory.py @@ -36,7 +36,8 @@ def build_embedding_provider( "Embedding model is not configured " "(set EVEROS_EMBEDDING__MODEL or [embedding] model in user toml)" ) - if settings.api_key is None: + api_key = settings.api_key.get_secret_value() if settings.api_key else "" + if not api_key: raise ValueError( "Embedding api_key is not configured (set EVEROS_EMBEDDING__API_KEY)" ) @@ -46,7 +47,7 @@ def build_embedding_provider( ) return OpenAIEmbeddingProvider( model=settings.model, - api_key=settings.api_key.get_secret_value(), + api_key=api_key, base_url=settings.base_url, dim=dim, timeout=settings.timeout_seconds, diff --git a/src/everos/component/llm/factory.py b/src/everos/component/llm/factory.py index d0db74f..a7d143c 100644 --- a/src/everos/component/llm/factory.py +++ b/src/everos/component/llm/factory.py @@ -28,7 +28,8 @@ def build_llm_provider(settings: LLMSettings) -> LLMClient: Raises: ValueError: If ``api_key`` or ``base_url`` is unset. """ - if settings.api_key is None: + api_key = settings.api_key.get_secret_value() if settings.api_key else "" + if not api_key: raise ValueError( "LLM api_key is not configured " "(set EVEROS_LLM__API_KEY or [llm] api_key in user toml)" @@ -40,6 +41,6 @@ def build_llm_provider(settings: LLMSettings) -> LLMClient: ) return OpenAIProvider( model=settings.model, - api_key=settings.api_key.get_secret_value(), + api_key=api_key, base_url=settings.base_url, ) diff --git a/src/everos/component/rerank/__init__.py b/src/everos/component/rerank/__init__.py index a2f502f..ebea251 100644 --- a/src/everos/component/rerank/__init__.py +++ b/src/everos/component/rerank/__init__.py @@ -7,6 +7,8 @@ Public surface: - :class:`DeepInfraRerankProvider` — DeepInfra inference-API rerank. - :class:`VllmRerankProvider` — OpenAI-compat ``/v1/rerank`` (vLLM, self-hosted, other compatible servers). +- :class:`DashScopeRerankProvider` — Aliyun Bailian / DashScope + ``gte-rerank-v2`` native ``text-rerank`` endpoint. - :func:`build_rerank_provider` — settings-driven factory that picks the concrete provider via ``settings.rerank.provider``. @@ -17,6 +19,7 @@ External usage:: scored = await provider.rerank("how to file a claim", documents) """ +from .dashscope_provider import DashScopeRerankProvider as DashScopeRerankProvider from .deepinfra_provider import DeepInfraRerankProvider as DeepInfraRerankProvider from .factory import build_rerank_provider as build_rerank_provider from .protocol import RerankError as RerankError @@ -25,6 +28,7 @@ from .protocol import RerankResult as RerankResult from .vllm_provider import VllmRerankProvider as VllmRerankProvider __all__ = [ + "DashScopeRerankProvider", "DeepInfraRerankProvider", "RerankError", "RerankProvider", diff --git a/src/everos/component/rerank/dashscope_provider.py b/src/everos/component/rerank/dashscope_provider.py new file mode 100644 index 0000000..13110cf --- /dev/null +++ b/src/everos/component/rerank/dashscope_provider.py @@ -0,0 +1,190 @@ +"""DashScope (Aliyun Bailian) ``gte-rerank-v2`` provider. + +DashScope's ``gte-rerank-v2`` uses a native ``text-rerank`` endpoint; the +``compatible-mode`` base_url used for LLM / embedding does not apply here:: + + POST {base_url}/api/v1/services/rerank/text-rerank/text-rerank + Authorization: Bearer + Content-Type: application/json + +Request body (note the nested ``input`` / ``parameters``):: + + { + "model": "", + "input": {"query": "", "documents": ["", ...]}, + "parameters": {"return_documents": false, "top_n": } + } + +Response body (results nested under ``output``):: + + { + "output": { + "results": [ + {"index": 0, "relevance_score": 0.87}, + {"index": 1, "relevance_score": 0.43}, + ... + ] + }, + "usage": {...}, + "request_id": "..." + } + +We request ``top_n = len(documents)`` so DashScope scores every input and +the :class:`RerankProvider` contract (one result per document) holds; the +returned list is sorted score-descending defensively regardless of server +ordering. ``api_key`` is required — DashScope has no anonymous tier. + +Only ``gte-rerank-v2`` is supported by this provider for now. +``qwen3-rerank`` uses a different endpoint / request shape and should be +added as a separate branch if EverOS decides to support it later. +""" + +from __future__ import annotations + +import asyncio +from collections.abc import Sequence +from typing import Any + +import httpx + +from .protocol import RerankError, RerankResult + + +class DashScopeRerankProvider: + """Rerank provider for Aliyun Bailian / DashScope ``gte-rerank-v2``. + + Args: + model: Reranker model id. Currently only ``"gte-rerank-v2"`` is + supported. + api_key: DashScope bearer credential (``sk-...``). Required. + base_url: DashScope API root *without* the service path + (e.g. ``"https://dashscope.aliyuncs.com"``). The + ``/api/v1/services/rerank/text-rerank/text-rerank`` suffix is + appended at request time. + timeout: Per-request timeout, seconds. + max_retries: Soft retry count on transport errors / 5xx. + batch_size: Cap on documents per request. + max_concurrent: Cap on in-flight requests across all batches. + """ + + _SERVICE_PATH = "/api/v1/services/rerank/text-rerank/text-rerank" + _SUPPORTED_MODELS = frozenset({"gte-rerank-v2"}) + + def __init__( + self, + *, + model: str, + api_key: str, + base_url: str, + timeout: float = 30.0, + max_retries: int = 3, + batch_size: int = 10, + max_concurrent: int = 5, + ) -> None: + if model not in self._SUPPORTED_MODELS: + raise ValueError( + f"DashScope rerank currently supports gte-rerank-v2 only; got {model!r}" + ) + self._model = model + self._api_key = api_key + self._url = f"{base_url.rstrip('/')}{self._SERVICE_PATH}" + self._timeout = timeout + self._max_retries = max_retries + self._batch_size = batch_size + self._semaphore = asyncio.Semaphore(max_concurrent) + + async def rerank( + self, + query: str, + documents: Sequence[str], + *, + instruction: str | None = None, + ) -> list[RerankResult]: + """Score every document against ``query``; return sorted desc. + + ``instruction`` is accepted for protocol parity but not transmitted: + DashScope applies the reranker template server-side, so there is no + client-side prompt to fill. + """ + if not documents: + return [] + + chunks: list[tuple[int, list[str]]] = [ + (offset, list(documents[offset : offset + self._batch_size])) + for offset in range(0, len(documents), self._batch_size) + ] + chunk_results = await asyncio.gather( + *(self._score_chunk(query, docs) for _, docs in chunks) + ) + scored: list[RerankResult] = [] + for (offset, _), partial in zip(chunks, chunk_results, strict=True): + scored.extend( + RerankResult(index=offset + r.index, score=r.score) for r in partial + ) + scored.sort(key=lambda r: r.score, reverse=True) + return scored + + async def _score_chunk( + self, query: str, documents: list[str] + ) -> list[RerankResult]: + payload: dict[str, Any] = { + "model": self._model, + "input": {"query": query, "documents": documents}, + "parameters": {"return_documents": False, "top_n": len(documents)}, + } + headers = { + "Authorization": f"Bearer {self._api_key}", + "Content-Type": "application/json", + } + + async with self._semaphore: + for attempt in range(self._max_retries + 1): + try: + async with httpx.AsyncClient(timeout=self._timeout) as client: + response = await client.post( + self._url, json=payload, headers=headers + ) + except httpx.HTTPError as exc: + if attempt == self._max_retries: + raise RerankError( + f"DashScope rerank transport failure: {exc}" + ) from exc + continue + + if response.status_code == 200: + return _parse_dashscope_results(response.json()) + + if response.status_code >= 500 or response.status_code == 429: + if attempt == self._max_retries: + raise RerankError( + f"DashScope rerank HTTP {response.status_code}: " + f"{response.text[:200]}" + ) + continue + raise RerankError( + f"DashScope rerank HTTP {response.status_code}: " + f"{response.text[:200]}" + ) + + raise RerankError( + f"DashScope rerank exhausted retries ({self._max_retries})" + ) + + +def _parse_dashscope_results(body: dict[str, Any]) -> list[RerankResult]: + output = body.get("output") + items = output.get("results") if isinstance(output, dict) else None + if not isinstance(items, list): + raise RerankError(f"DashScope rerank response missing results: {body!r}") + parsed: list[RerankResult] = [] + for item in items: + try: + parsed.append( + RerankResult( + index=int(item["index"]), + score=float(item["relevance_score"]), + ) + ) + except (KeyError, TypeError, ValueError) as exc: + raise RerankError(f"malformed rerank result entry: {item!r}") from exc + return parsed diff --git a/src/everos/component/rerank/factory.py b/src/everos/component/rerank/factory.py index bdc8be5..760d341 100644 --- a/src/everos/component/rerank/factory.py +++ b/src/everos/component/rerank/factory.py @@ -5,6 +5,8 @@ implementation to build: - ``"deepinfra"`` → :class:`DeepInfraRerankProvider` - ``"vllm"`` → :class:`VllmRerankProvider` + - ``"dashscope"`` → :class:`DashScopeRerankProvider` + (Aliyun Bailian ``gte-rerank-v2``) Adding a new provider = one match arm here + one new file under :mod:`everos.component.rerank`. @@ -12,12 +14,42 @@ Adding a new provider = one match arm here + one new file under from __future__ import annotations -from everos.config import RerankSettings +from urllib.parse import urlparse +from everos.config import RerankSettings +from everos.core.observability.logging import get_logger + +from .dashscope_provider import DashScopeRerankProvider from .deepinfra_provider import DeepInfraRerankProvider from .protocol import RerankProvider from .vllm_provider import VllmRerankProvider +logger = get_logger(__name__) + +# host substring → provider. Ordered most-specific first; matched against +# the ``base_url`` host so a Bailian / DeepInfra URL routes to the right +# request-shape without the operator also having to set ``provider``. +_PROVIDER_HOST_HINTS: tuple[tuple[str, str], ...] = ( + ("dashscope.aliyuncs.com", "dashscope"), + ("deepinfra.com", "deepinfra"), +) + +# Fallback when the host matches no hint and ``provider`` is unset. Keeps +# the historical default so existing configs without ``provider`` are +# unaffected. +_DEFAULT_PROVIDER = "deepinfra" + + +def _infer_provider(base_url: str) -> str | None: + """Infer the rerank provider from the ``base_url`` host, or ``None``.""" + host = (urlparse(base_url).hostname or "").lower() + if not host: + return None + for needle, provider in _PROVIDER_HOST_HINTS: + if host == needle or host.endswith(f".{needle}"): + return provider + return None + def build_rerank_provider(settings: RerankSettings) -> RerankProvider: """Build a rerank provider from settings. @@ -32,8 +64,14 @@ def build_rerank_provider(settings: RerankSettings) -> RerankProvider: Raises: ValueError: If ``model`` or ``base_url`` is unset, or if ``provider`` does not match a known implementation. - ``api_key`` is required for ``deepinfra``; optional (empty - string) for ``vllm`` self-hosted endpoints. + ``api_key`` is required for ``deepinfra`` and ``dashscope``; + optional (empty string) for ``vllm`` self-hosted endpoints. + ``dashscope`` currently supports ``gte-rerank-v2`` only. + + Notes: + When ``settings.provider`` is ``None`` the provider is inferred + from the ``base_url`` host (see :data:`_PROVIDER_HOST_HINTS`), + falling back to ``"deepinfra"`` for unrecognized hosts. """ if not settings.model: raise ValueError( @@ -46,7 +84,18 @@ def build_rerank_provider(settings: RerankSettings) -> RerankProvider: ) api_key = settings.api_key.get_secret_value() if settings.api_key else "" - if settings.provider == "deepinfra": + provider = settings.provider + if provider is None: + inferred = _infer_provider(settings.base_url) + provider = inferred or _DEFAULT_PROVIDER + logger.info( + "rerank_provider_inferred", + provider=provider, + inferred=inferred is not None, + base_url=settings.base_url, + ) + + if provider == "deepinfra": if not api_key: raise ValueError( "DeepInfra rerank api_key is not configured " @@ -61,7 +110,7 @@ def build_rerank_provider(settings: RerankSettings) -> RerankProvider: batch_size=settings.batch_size, max_concurrent=settings.max_concurrent, ) - if settings.provider == "vllm": + if provider == "vllm": return VllmRerankProvider( model=settings.model, api_key=api_key, @@ -71,4 +120,19 @@ def build_rerank_provider(settings: RerankSettings) -> RerankProvider: batch_size=settings.batch_size, max_concurrent=settings.max_concurrent, ) - raise ValueError(f"unknown rerank provider: {settings.provider!r}") + if provider == "dashscope": + if not api_key: + raise ValueError( + "DashScope rerank api_key is not configured " + "(set EVEROS_RERANK__API_KEY)" + ) + return DashScopeRerankProvider( + model=settings.model, + api_key=api_key, + base_url=settings.base_url, + timeout=settings.timeout_seconds, + max_retries=settings.max_retries, + batch_size=settings.batch_size, + max_concurrent=settings.max_concurrent, + ) + raise ValueError(f"unknown rerank provider: {provider!r}") diff --git a/src/everos/config/default.toml b/src/everos/config/default.toml index 1bea9a5..08d3ab3 100644 --- a/src/everos/config/default.toml +++ b/src/everos/config/default.toml @@ -96,7 +96,14 @@ max_concurrent = 5 # `provider` picks the request-shape: # - "deepinfra" -> POST {base_url}/{model} (DeepInfra inference API) # - "vllm" -> POST {base_url}/rerank (OpenAI-compat rerank endpoint) -provider = "deepinfra" +# - "dashscope" -> POST {base_url}/api/v1/services/rerank/text-rerank/text-rerank +# (Aliyun Bailian native text-rerank; currently +# "gte-rerank-v2", base_url "https://dashscope.aliyuncs.com") +# Left unset, the factory infers the provider from the base_url host +# (dashscope.aliyuncs.com -> dashscope, *.deepinfra.com -> deepinfra) and +# falls back to "deepinfra" for unknown hosts. Set it explicitly to +# override — required for self-hosted "vllm" on an arbitrary host. +# provider = "deepinfra" # model = "Qwen/Qwen3-Reranker-4B" # api_key = "" # base_url = "https://api.deepinfra.com/v1/inference" diff --git a/src/everos/config/settings.py b/src/everos/config/settings.py index 98337f4..fd57a7c 100644 --- a/src/everos/config/settings.py +++ b/src/everos/config/settings.py @@ -191,8 +191,16 @@ class RerankSettings(BaseModel): Unlike LLM / embedding (single OpenAI-compatible shape), rerank API schemas differ between providers — DeepInfra uses ``POST {base_url}/ {model}`` with a custom body, vLLM uses ``POST {base_url}/rerank`` - with ``{model, query, documents}``. ``provider`` picks which client - implementation the factory builds. + with ``{model, query, documents}``, DashScope (Aliyun Bailian) + ``gte-rerank-v2`` uses ``POST {base_url}/api/v1/services/rerank/ + text-rerank/text-rerank`` with a nested ``{model, input, parameters}`` + body. ``provider`` picks which client implementation the factory builds. + + ``provider`` defaults to ``None`` — the factory then infers it from + the ``base_url`` host (e.g. ``dashscope.aliyuncs.com`` → DashScope, + ``*.deepinfra.com`` → DeepInfra), falling back to ``"deepinfra"`` when + the host is unrecognized. Set ``provider`` explicitly to override the + inference (required for self-hosted ``vllm`` on an arbitrary host). Env binding: EVEROS_RERANK__PROVIDER @@ -205,7 +213,7 @@ class RerankSettings(BaseModel): EVEROS_RERANK__MAX_CONCURRENT """ - provider: Literal["deepinfra", "vllm"] = "deepinfra" + provider: Literal["deepinfra", "vllm", "dashscope"] | None = None model: str | None = None api_key: SecretStr | None = None base_url: str | None = None diff --git a/src/everos/service/search.py b/src/everos/service/search.py index 234e6b0..1b31293 100644 --- a/src/everos/service/search.py +++ b/src/everos/service/search.py @@ -59,10 +59,14 @@ def _get_embedding() -> EmbeddingProvider | None: from everos.config import load_settings cfg = load_settings().embedding - if not cfg.model or cfg.api_key is None: + api_key = cfg.api_key.get_secret_value() if cfg.api_key else "" + if not cfg.model or not api_key or not cfg.base_url: logger.warning( "embedding_not_configured", - hint="set [embedding] model / api_key to enable vector / hybrid search", + hint=( + "set [embedding] model / api_key / base_url to enable " + "vector / hybrid search" + ), ) _embedding = None else: @@ -82,10 +86,14 @@ def _get_reranker() -> RerankProvider | None: from everos.config import load_settings cfg = load_settings().rerank - if not cfg.model or not cfg.base_url: + api_key = cfg.api_key.get_secret_value() if cfg.api_key else "" + if not cfg.model or not cfg.base_url or (cfg.provider != "vllm" and not api_key): logger.warning( "rerank_not_configured", - hint="set [rerank] model / base_url to enable agentic search", + hint=( + "set [rerank] model / api_key / base_url to enable " + "agentic search; api_key is optional only for provider='vllm'" + ), ) _reranker = None else: @@ -105,7 +113,8 @@ def _get_llm_client() -> LLMClient | None: from everos.config import load_settings cfg = load_settings().llm - if cfg.api_key is None or not cfg.base_url: + api_key = cfg.api_key.get_secret_value() if cfg.api_key else "" + if not api_key or not cfg.base_url: logger.warning( "llm_not_configured", hint="set [llm] api_key / base_url to enable hybrid / agentic search", diff --git a/src/everos/templates/env.template b/src/everos/templates/env.template index 6ca33de..fe392d2 100755 --- a/src/everos/templates/env.template +++ b/src/everos/templates/env.template @@ -34,6 +34,13 @@ EVEROS_LLM__MODEL=openai/gpt-4.1-mini EVEROS_LLM__API_KEY= EVEROS_LLM__BASE_URL=https://openrouter.ai/api/v1 +# Aliyun Bailian (DashScope) alternative — one key also covers embedding + +# rerank below, so the same value goes in all three API_KEY slots. +# Uncomment these three lines and comment out the OpenRouter lines above: +# EVEROS_LLM__MODEL=qwen-plus +# EVEROS_LLM__API_KEY= +# EVEROS_LLM__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 + # ─── Multimodal LLM (independent from [llm]; vision/audio capable) ──── # Separate model for parsing multimodal content items (image / pdf / @@ -63,6 +70,12 @@ EVEROS_MULTIMODAL__BASE_URL=https://openrouter.ai/api/v1 EVEROS_EMBEDDING__MODEL=Qwen/Qwen3-Embedding-4B EVEROS_EMBEDDING__API_KEY= EVEROS_EMBEDDING__BASE_URL=https://api.deepinfra.com/v1/openai + +# Aliyun Bailian (DashScope) alternative. Uncomment these three lines and +# comment out the DeepInfra embedding lines above: +# EVEROS_EMBEDDING__MODEL=text-embedding-v4 +# EVEROS_EMBEDDING__API_KEY= +# EVEROS_EMBEDDING__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 # Runtime knobs — uncomment to override defaults (30s / 3 / 10 / 5): # EVEROS_EMBEDDING__TIMEOUT_SECONDS=30 # EVEROS_EMBEDDING__MAX_RETRIES=3 @@ -72,10 +85,21 @@ EVEROS_EMBEDDING__BASE_URL=https://api.deepinfra.com/v1/openai # ─── Rerank (OpenAI-protocol /rerank) ──────────────── # base_url should point at the rerank endpoint (e.g. .../v1/rerank). +# EVEROS_RERANK__PROVIDER selects the request-shape: "deepinfra" (default), +# "vllm", or "dashscope". Left unset, it is inferred from the base_url host +# (dashscope.aliyuncs.com -> dashscope, *.deepinfra.com -> deepinfra). EVEROS_RERANK__MODEL=Qwen/Qwen3-Reranker-4B EVEROS_RERANK__API_KEY= EVEROS_RERANK__BASE_URL=https://api.deepinfra.com/v1/inference + +# Aliyun Bailian (DashScope) alternative. EverOS currently supports +# DashScope rerank via gte-rerank-v2; provider is auto-inferred from host, +# so EVEROS_RERANK__PROVIDER is optional. Uncomment these three lines and +# comment out the DeepInfra rerank lines above: +# EVEROS_RERANK__MODEL=gte-rerank-v2 +# EVEROS_RERANK__API_KEY= +# EVEROS_RERANK__BASE_URL=https://dashscope.aliyuncs.com # Runtime knobs — uncomment to override defaults (30s / 3 / 10 / 5): # EVEROS_RERANK__TIMEOUT_SECONDS=30 # EVEROS_RERANK__MAX_RETRIES=3 diff --git a/tests/unit/test_component/test_embedding/test_factory.py b/tests/unit/test_component/test_embedding/test_factory.py index d75a178..3e6625e 100644 --- a/tests/unit/test_component/test_embedding/test_factory.py +++ b/tests/unit/test_component/test_embedding/test_factory.py @@ -24,6 +24,12 @@ def test_raises_when_api_key_missing() -> None: build_embedding_provider(s) +def test_raises_when_api_key_empty() -> None: + s = EmbeddingSettings(model="m", api_key=SecretStr(""), base_url="https://x") + with pytest.raises(ValueError, match="EVEROS_EMBEDDING__API_KEY"): + build_embedding_provider(s) + + def test_raises_when_base_url_missing() -> None: s = EmbeddingSettings(model="m", api_key=SecretStr("k"), base_url=None) with pytest.raises(ValueError, match="EVEROS_EMBEDDING__BASE_URL"): diff --git a/tests/unit/test_component/test_llm/test_factory.py b/tests/unit/test_component/test_llm/test_factory.py index 4329fce..53d161b 100644 --- a/tests/unit/test_component/test_llm/test_factory.py +++ b/tests/unit/test_component/test_llm/test_factory.py @@ -16,6 +16,12 @@ def test_raises_when_api_key_missing() -> None: build_llm_provider(s) +def test_raises_when_api_key_empty() -> None: + s = LLMSettings(model="m", api_key=SecretStr(""), base_url="https://x") + with pytest.raises(ValueError, match="EVEROS_LLM__API_KEY"): + build_llm_provider(s) + + def test_raises_when_base_url_missing() -> None: s = LLMSettings(model="m", api_key=SecretStr("k"), base_url=None) with pytest.raises(ValueError, match="EVEROS_LLM__BASE_URL"): diff --git a/tests/unit/test_component/test_rerank/test_dashscope_provider.py b/tests/unit/test_component/test_rerank/test_dashscope_provider.py new file mode 100644 index 0000000..3fce9af --- /dev/null +++ b/tests/unit/test_component/test_rerank/test_dashscope_provider.py @@ -0,0 +1,209 @@ +"""DashScope rerank provider — URL/body shape, results parsing, retries.""" + +from __future__ import annotations + +import json +from collections.abc import Callable + +import httpx +import pytest + +from everos.component.rerank import DashScopeRerankProvider, RerankError + + +def _patch_httpx( + monkeypatch: pytest.MonkeyPatch, + handler: Callable[[httpx.Request], httpx.Response], +) -> None: + transport = httpx.MockTransport(handler) + import everos.component.rerank.dashscope_provider as mod + + real_cls = httpx.AsyncClient + + def factory(*args: object, **kwargs: object) -> httpx.AsyncClient: + kwargs["transport"] = transport + return real_cls(*args, **kwargs) # type: ignore[arg-type] + + monkeypatch.setattr(mod.httpx, "AsyncClient", factory) + + +def _ok_response(items: list[dict[str, float | int]]) -> httpx.Response: + return httpx.Response(200, json={"output": {"results": items}}) + + +def test_only_gte_rerank_v2_is_supported() -> None: + with pytest.raises(ValueError, match="gte-rerank-v2 only"): + DashScopeRerankProvider( + model="qwen3-rerank", + api_key="k", + base_url="https://dashscope.aliyuncs.com", + ) + + +async def test_empty_documents_short_circuits(monkeypatch: pytest.MonkeyPatch) -> None: + calls = 0 + + def handler(_req: httpx.Request) -> httpx.Response: + nonlocal calls + calls += 1 + return _ok_response([]) + + _patch_httpx(monkeypatch, handler) + p = DashScopeRerankProvider( + model="gte-rerank-v2", api_key="k", base_url="https://dashscope.aliyuncs.com" + ) + assert await p.rerank("q", []) == [] + assert calls == 0 + + +async def test_url_body_and_sort_desc(monkeypatch: pytest.MonkeyPatch) -> None: + seen_urls: list[str] = [] + seen_bodies: list[dict[str, object]] = [] + + def handler(req: httpx.Request) -> httpx.Response: + seen_urls.append(str(req.url)) + seen_bodies.append(json.loads(req.content)) + return _ok_response( + [ + {"index": 0, "relevance_score": 0.1}, + {"index": 1, "relevance_score": 0.9}, + {"index": 2, "relevance_score": 0.5}, + ] + ) + + _patch_httpx(monkeypatch, handler) + p = DashScopeRerankProvider( + model="gte-rerank-v2", + api_key="k", + base_url="https://dashscope.aliyuncs.com/", + ) + results = await p.rerank("q", ["a", "b", "c"]) + # Trailing slash stripped, native service path appended. + assert seen_urls == [ + "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank" + ] + # Nested input/parameters body shape. + body = seen_bodies[0] + assert body["model"] == "gte-rerank-v2" + assert body["input"] == {"query": "q", "documents": ["a", "b", "c"]} + assert body["parameters"]["top_n"] == 3 + assert [r.index for r in results] == [1, 2, 0] + + +async def test_auth_header_always_present(monkeypatch: pytest.MonkeyPatch) -> None: + seen_headers: list[dict[str, str]] = [] + + def handler(req: httpx.Request) -> httpx.Response: + seen_headers.append(dict(req.headers)) + return _ok_response([{"index": 0, "relevance_score": 0.5}]) + + _patch_httpx(monkeypatch, handler) + p = DashScopeRerankProvider( + model="gte-rerank-v2", + api_key="sk-abc", + base_url="https://dashscope.aliyuncs.com", + ) + await p.rerank("q", ["a"]) + assert seen_headers[0].get("authorization") == "Bearer sk-abc" + + +async def test_batching_offsets_indices(monkeypatch: pytest.MonkeyPatch) -> None: + """With batch_size=2 and 3 docs, the second batch's result index 0 becomes 2.""" + + def handler(req: httpx.Request) -> httpx.Response: + body = json.loads(req.content) + docs = body["input"]["documents"] + return _ok_response( + [{"index": i, "relevance_score": float(i)} for i in range(len(docs))] + ) + + _patch_httpx(monkeypatch, handler) + p = DashScopeRerankProvider( + model="gte-rerank-v2", + api_key="k", + base_url="https://dashscope.aliyuncs.com", + batch_size=2, + ) + results = await p.rerank("q", ["a", "b", "c"]) + assert sorted(r.index for r in results) == [0, 1, 2] + + +async def test_4xx_raises_immediately(monkeypatch: pytest.MonkeyPatch) -> None: + state = {"calls": 0} + + def handler(_req: httpx.Request) -> httpx.Response: + state["calls"] += 1 + return httpx.Response(401, text="unauthorized") + + _patch_httpx(monkeypatch, handler) + p = DashScopeRerankProvider( + model="gte-rerank-v2", + api_key="bad", + base_url="https://dashscope.aliyuncs.com", + max_retries=3, + ) + with pytest.raises(RerankError, match="HTTP 401"): + await p.rerank("q", ["a"]) + assert state["calls"] == 1 + + +async def test_5xx_retries(monkeypatch: pytest.MonkeyPatch) -> None: + state = {"calls": 0} + + def handler(_req: httpx.Request) -> httpx.Response: + state["calls"] += 1 + if state["calls"] < 2: + return httpx.Response(503, text="unavailable") + return _ok_response([{"index": 0, "relevance_score": 0.42}]) + + _patch_httpx(monkeypatch, handler) + p = DashScopeRerankProvider( + model="gte-rerank-v2", + api_key="k", + base_url="https://dashscope.aliyuncs.com", + max_retries=3, + ) + results = await p.rerank("q", ["a"]) + assert state["calls"] == 2 + assert results[0].score == pytest.approx(0.42) + + +async def test_transport_error_exhausts(monkeypatch: pytest.MonkeyPatch) -> None: + def handler(_req: httpx.Request) -> httpx.Response: + raise httpx.ReadTimeout("timeout") + + _patch_httpx(monkeypatch, handler) + p = DashScopeRerankProvider( + model="gte-rerank-v2", + api_key="k", + base_url="https://dashscope.aliyuncs.com", + max_retries=1, + ) + with pytest.raises(RerankError, match="transport failure"): + await p.rerank("q", ["a"]) + + +async def test_malformed_results_missing_output( + monkeypatch: pytest.MonkeyPatch, +) -> None: + def handler(_req: httpx.Request) -> httpx.Response: + return httpx.Response(200, json={"usage": {}}) + + _patch_httpx(monkeypatch, handler) + p = DashScopeRerankProvider( + model="gte-rerank-v2", api_key="k", base_url="https://dashscope.aliyuncs.com" + ) + with pytest.raises(RerankError, match="missing results"): + await p.rerank("q", ["a"]) + + +async def test_malformed_result_entry(monkeypatch: pytest.MonkeyPatch) -> None: + def handler(_req: httpx.Request) -> httpx.Response: + return httpx.Response(200, json={"output": {"results": [{"index": 0}]}}) + + _patch_httpx(monkeypatch, handler) + p = DashScopeRerankProvider( + model="gte-rerank-v2", api_key="k", base_url="https://dashscope.aliyuncs.com" + ) + with pytest.raises(RerankError, match="malformed rerank result"): + await p.rerank("q", ["a"]) diff --git a/tests/unit/test_component/test_rerank/test_factory.py b/tests/unit/test_component/test_rerank/test_factory.py index 1f5ab11..c4af2a9 100644 --- a/tests/unit/test_component/test_rerank/test_factory.py +++ b/tests/unit/test_component/test_rerank/test_factory.py @@ -6,6 +6,7 @@ import pytest from pydantic import SecretStr from everos.component.rerank import ( + DashScopeRerankProvider, DeepInfraRerankProvider, VllmRerankProvider, build_rerank_provider, @@ -33,6 +34,17 @@ def test_deepinfra_requires_api_key() -> None: build_rerank_provider(s) +def test_deepinfra_rejects_empty_api_key() -> None: + s = RerankSettings( + provider="deepinfra", + model="m", + api_key=SecretStr(""), + base_url="https://api.deepinfra.com/v1/inference", + ) + with pytest.raises(ValueError, match="EVEROS_RERANK__API_KEY"): + build_rerank_provider(s) + + def test_deepinfra_builds_provider() -> None: s = RerankSettings( provider="deepinfra", @@ -65,3 +77,80 @@ def test_vllm_with_api_key() -> None: ) p = build_rerank_provider(s) assert isinstance(p, VllmRerankProvider) + + +def test_dashscope_requires_api_key() -> None: + s = RerankSettings( + provider="dashscope", + model="gte-rerank-v2", + api_key=None, + base_url="https://dashscope.aliyuncs.com", + ) + with pytest.raises(ValueError, match="EVEROS_RERANK__API_KEY"): + build_rerank_provider(s) + + +def test_dashscope_builds_provider() -> None: + s = RerankSettings( + provider="dashscope", + model="gte-rerank-v2", + api_key=SecretStr("k"), + base_url="https://dashscope.aliyuncs.com", + ) + p = build_rerank_provider(s) + assert isinstance(p, DashScopeRerankProvider) + + +def test_dashscope_supports_gte_rerank_v2_only() -> None: + s = RerankSettings( + provider="dashscope", + model="qwen3-rerank", + api_key=SecretStr("k"), + base_url="https://dashscope.aliyuncs.com", + ) + with pytest.raises(ValueError, match="gte-rerank-v2 only"): + build_rerank_provider(s) + + +def test_infers_dashscope_from_base_url() -> None: + """provider unset + DashScope host -> DashScopeRerankProvider.""" + s = RerankSettings( + provider=None, + model="gte-rerank-v2", + api_key=SecretStr("k"), + base_url="https://dashscope.aliyuncs.com", + ) + assert isinstance(build_rerank_provider(s), DashScopeRerankProvider) + + +def test_infers_deepinfra_from_base_url() -> None: + """provider unset + DeepInfra host -> DeepInfraRerankProvider.""" + s = RerankSettings( + provider=None, + model="m", + api_key=SecretStr("k"), + base_url="https://api.deepinfra.com/v1/inference", + ) + assert isinstance(build_rerank_provider(s), DeepInfraRerankProvider) + + +def test_unknown_host_falls_back_to_deepinfra() -> None: + """provider unset + unrecognized host -> historical deepinfra default.""" + s = RerankSettings( + provider=None, + model="m", + api_key=SecretStr("k"), + base_url="https://rerank.internal.example/v1", + ) + assert isinstance(build_rerank_provider(s), DeepInfraRerankProvider) + + +def test_explicit_provider_overrides_inference() -> None: + """Explicit provider wins even when the host hints another.""" + s = RerankSettings( + provider="vllm", + model="m", + api_key=SecretStr("k"), + base_url="https://dashscope.aliyuncs.com", + ) + assert isinstance(build_rerank_provider(s), VllmRerankProvider) diff --git a/tests/unit/test_config/test_settings.py b/tests/unit/test_config/test_settings.py index a8fc5ca..de6d849 100644 --- a/tests/unit/test_config/test_settings.py +++ b/tests/unit/test_config/test_settings.py @@ -134,6 +134,52 @@ def test_rerank_env_overrides(monkeypatch: pytest.MonkeyPatch) -> None: assert s.rerank.max_concurrent == 8 +def test_dashscope_one_key_can_configure_llm_embedding_and_rerank( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """One DashScope key value can be reused across all three clients.""" + key = "sk-dashscope" + compatible_base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1" + + monkeypatch.setenv("EVEROS_LLM__MODEL", "qwen-plus") + monkeypatch.setenv("EVEROS_LLM__API_KEY", key) + monkeypatch.setenv("EVEROS_LLM__BASE_URL", compatible_base_url) + monkeypatch.setenv("EVEROS_EMBEDDING__MODEL", "text-embedding-v4") + monkeypatch.setenv("EVEROS_EMBEDDING__API_KEY", key) + monkeypatch.setenv("EVEROS_EMBEDDING__BASE_URL", compatible_base_url) + monkeypatch.setenv("EVEROS_RERANK__PROVIDER", "dashscope") + monkeypatch.setenv("EVEROS_RERANK__MODEL", "gte-rerank-v2") + monkeypatch.setenv("EVEROS_RERANK__API_KEY", key) + monkeypatch.setenv("EVEROS_RERANK__BASE_URL", "https://dashscope.aliyuncs.com") + + s = Settings() + + assert s.llm.api_key is not None + assert s.embedding.api_key is not None + assert s.rerank.api_key is not None + assert s.llm.api_key.get_secret_value() == key + assert s.embedding.api_key.get_secret_value() == key + assert s.rerank.api_key.get_secret_value() == key + assert s.llm.base_url == compatible_base_url + assert s.embedding.base_url == compatible_base_url + assert s.rerank.provider == "dashscope" + + from everos.component.embedding import ( + OpenAIEmbeddingProvider, + build_embedding_provider, + ) + from everos.component.llm import build_llm_provider + from everos.component.llm.openai_provider import OpenAIProvider + from everos.component.rerank import ( + DashScopeRerankProvider, + build_rerank_provider, + ) + + assert isinstance(build_llm_provider(s.llm), OpenAIProvider) + assert isinstance(build_embedding_provider(s.embedding), OpenAIEmbeddingProvider) + assert isinstance(build_rerank_provider(s.rerank), DashScopeRerankProvider) + + def test_user_toml_override_via_env_path( monkeypatch: pytest.MonkeyPatch, tmp_path: Path ) -> None: diff --git a/tests/unit/test_entrypoints/test_cli/test_init_command.py b/tests/unit/test_entrypoints/test_cli/test_init_command.py index 8ef0622..79f0e45 100644 --- a/tests/unit/test_entrypoints/test_cli/test_init_command.py +++ b/tests/unit/test_entrypoints/test_cli/test_init_command.py @@ -135,6 +135,31 @@ def test_template_resource_is_packaged_under_everos_templates() -> None: assert res.is_file() body = res.read_text(encoding="utf-8") assert "EVEROS_LLM__API_KEY" in body + assert "DASHSCOPE_API_KEY" in body + assert "text-embedding-v4" in body + assert "gte-rerank-v2" in body + + +def test_template_has_single_active_value_per_env_key() -> None: + """Alternative provider examples must stay commented to avoid overrides.""" + from collections import Counter + from importlib import resources + + body = ( + resources.files("everos.templates") + .joinpath("env.template") + .read_text(encoding="utf-8") + ) + active_assignments = [ + line.strip() + for line in body.splitlines() + if line.strip() and not line.lstrip().startswith("#") and "=" in line + ] + assert all("<" not in line for line in active_assignments) + + keys = [line.split("=", 1)[0] for line in active_assignments] + duplicates = [key for key, count in Counter(keys).items() if count > 1] + assert duplicates == [] # ── 4-layer .env resolution for ``server start`` ────────────────────────