feat(rerank): add Bailian DashScope provider support (#295)

This commit is contained in:
Yangtze-Seventh
2026-06-17 20:19:42 +08:00
committed by GitHub
parent 5a821acf20
commit dc02b2fbab
17 changed files with 765 additions and 26 deletions
+24
View File
@@ -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=<DASHSCOPE_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=<DASHSCOPE_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=<DASHSCOPE_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
+33 -7
View File
@@ -173,9 +173,10 @@ Agent 记忆(<code>cases</code> / <code>skills</code>)与用户记忆(<cod
### 0. 前置条件
- Python 3.12+
- 默认 provider 需要 API keys:OpenRouter 用于 chat / multimodal,
DeepInfra 用于 embedding / rerank。也可以通过 `.env` 里的
`*__BASE_URL` 字段切换到其他 OpenAI-compatible providers。
- 默认 provider 需要 API keys:[OpenRouter](https://openrouter.ai/) 用于
chat / multimodal,[DeepInfra](https://deepinfra.com/) 用于 embedding /
rerank。也可以通过 `.env` 里的 `*__BASE_URL` 字段切换到其他
OpenAI-compatible providers。
### 1. 安装
@@ -186,9 +187,18 @@ uv pip install everos
### 2. 配置
生成一个 starter `.env` 文件,然后根据生成的注释填入四个 API key slots。
默认配置只需要两把不同的 key:OpenRouter 用于 `LLM` / `MULTIMODAL`,
DeepInfra 用于 `EMBEDDING` / `RERANK`。
生成一个 starter `.env` 文件,然后根据生成的注释填入对应的 API key 字段。
默认配置需要分别提供 [OpenRouter](https://openrouter.ai/) 和
[DeepInfra](https://deepinfra.com/) 的 API key:OpenRouter 用于
`LLM` / `MULTIMODAL`,DeepInfra 用于 `EMBEDDING` / `RERANK`。
EverOS 也支持通过
[阿里云百炼控制台](https://bailian.console.aliyun.com/) 创建一个
DashScope API Key,统一配置 `LLM` / `EMBEDDING` / `RERANK`
三个核心能力。把同一个值填到
`EVEROS_LLM__API_KEY`、`EVEROS_EMBEDDING__API_KEY`、`EVEROS_RERANK__API_KEY`,
并把对应 model/base_url 切到生成模板里的 Bailian / DashScope 示例。
当前 EverOS 的百炼 rerank 路线推荐并支持 `gte-rerank-v2`。
```bash
everos init
@@ -199,6 +209,22 @@ cp .env.example .env
`everos init` 默认写入 `./.env`。也可以使用 `everos init --xdg`
写入 `${XDG_CONFIG_HOME:-~/.config}/everos/.env`。
百炼三件套示例:
```env
EVEROS_LLM__MODEL=qwen-plus
EVEROS_LLM__API_KEY=<DASHSCOPE_API_KEY>
EVEROS_LLM__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EVEROS_EMBEDDING__MODEL=text-embedding-v4
EVEROS_EMBEDDING__API_KEY=<DASHSCOPE_API_KEY>
EVEROS_EMBEDDING__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EVEROS_RERANK__MODEL=gte-rerank-v2
EVEROS_RERANK__API_KEY=<DASHSCOPE_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
+3 -2
View File
@@ -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,
+3 -2
View File
@@ -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,
)
+4
View File
@@ -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",
@@ -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 <api_key>
Content-Type: application/json
Request body (note the nested ``input`` / ``parameters``)::
{
"model": "<model>",
"input": {"query": "<query>", "documents": ["<doc 1>", ...]},
"parameters": {"return_documents": false, "top_n": <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
+70 -6
View File
@@ -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}")
+8 -1
View File
@@ -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"
+11 -3
View File
@@ -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
+14 -5
View File
@@ -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",
+24
View File
@@ -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=<DASHSCOPE_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=<DASHSCOPE_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=<DASHSCOPE_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
@@ -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"):
@@ -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"):
@@ -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"])
@@ -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)
+46
View File
@@ -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:
@@ -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`` ────────────────────────