Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(rerank): add OpenAI-compatible rerank provider (#785)
ChenXiaofei44d9542fc3dd
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex a46309979..1328df969 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -431,11 +431,27 @@ Reranking model for search result refinement.}```+**OpenAI-compatible provider (e.g. DashScope qwen3-rerank):**++```json+{+ "rerank": {+ "provider": "openai",+ "api_key": "your-api-key",+ "api_base": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",+ "model": "qwen3-rerank",+ "threshold": 0.1+ }+}+```+| Parameter | Type | Description ||-----------|------|-------------|-| `provider` | str | `"volcengine"` |+| `provider` | str | `"volcengine"` or `"openai"` || `api_key` | str | API key || `model` | str | Model name |+| `api_base` | str | Endpoint URL (openai provider only) |+| `threshold` | float | Score threshold; results below this are filtered out. Default: `0.1` |If rerank is not configured, search uses vector similarity only.@@ -750,9 +766,11 @@ For details on the lock mechanism, see [Path Locks and Crash Recovery](../concep"stream": false},"rerank": {- "provider": "volcengine",+ "provider": "volcengine|openai","api_key": "string",- "model": "string"+ "model": "string",+ "api_base": "string",+ "threshold": 0.1},"storage": {"workspace": "string",diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 96558bd09..588eb9509 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -405,11 +405,27 @@ AST 提取支持:Python、JavaScript/TypeScript、Rust、Go、Java、C/C++。}```+**OpenAI 兼容提供方(如 DashScope qwen3-rerank):**++```json+{+ "rerank": {+ "provider": "openai",+ "api_key": "your-api-key",+ "api_base": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",+ "model": "qwen3-rerank",+ "threshold": 0.1+ }+}+```+| 参数 | 类型 | 说明 ||------|------|------|-| `provider` | str | `"volcengine"` |+| `provider` | str | `"volcengine"` 或 `"openai"` || `api_key` | str | API Key || `model` | str | 模型名称 |+| `api_base` | str | 接口地址(openai 提供方专用) |+| `threshold` | float | 分数阈值,低于此值的结果会被过滤。默认:`0.1` |如果未配置 Rerank,搜索仅使用向量相似度。@@ -726,9 +742,11 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远"stream": false},"rerank": {- "provider": "volcengine",+ "provider": "volcengine|openai","api_key": "string",- "model": "string"+ "model": "string",+ "api_base": "string",+ "threshold": 0.1},"storage": {"workspace": "string",diff --git a/examples/ov.conf.example b/examples/ov.conf.exampleindex 249c0a136..e2573abcd 100644--- a/examples/ov.conf.example+++ b/examples/ov.conf.example@@ -64,13 +64,22 @@"thinking": false},"rerank": {- "ak": null,- "sk": null,+ "provider": "vikingdb",+ "ak": "{your-ak}",+ "sk": "{your-sk}","host": "api-vikingdb.vikingdb.cn-beijing.volces.com","model_name": "doubao-seed-rerank","model_version": "251028","threshold": 0.1},+ "rerank_openai_example": {+ "_comment": "For OpenAI-compatible rerank providers (e.g. DashScope qwen3-rerank):",+ "provider": "openai",+ "api_key": "{your-api-key}",+ "api_base": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",+ "model": "qwen3-rerank",+ "threshold": 0.1+ },"auto_generate_l0": true,"auto_generate_l1": true,"default_search_mode": "thinking",diff --git a/openviking_cli/utils/config/rerank_config.py b/openviking_cli/utils/config/rerank_config.pyindex 076ef9f60..91c0b0236 100644--- a/openviking_cli/utils/config/rerank_config.py+++ b/openviking_cli/utils/config/rerank_config.py@@ -2,12 +2,15 @@# SPDX-License-Identifier: Apache-2.0from typing import Optional-from pydantic import BaseModel, Field+from pydantic import BaseModel, Field, model_validatorclass RerankConfig(BaseModel):- """Configuration for VikingDB Rerank API."""+ """Configuration for rerank API (VikingDB or OpenAI-compatible providers)."""+ provider: str = Field(default="vikingdb", description="Rerank provider: 'vikingdb' or 'openai'")++ # VikingDB fieldsak: Optional[str] = Field(default=None, description="VikingDB Access Key")sk: Optional[str] = Field(default=None, description="VikingDB Secret Key")host: str = Field(@@ -15,12 +18,36 @@ class RerankConfig(BaseModel):)model_name: str = Field(default="doubao-seed-rerank", description="Rerank model name")model_version: str = Field(default="251028", description="Rerank model version")++ # OpenAI-compatible fields+ api_key: Optional[str] = Field(+ default=None, description="Bearer token for OpenAI-compatible providers"+ )+ api_base: Optional[str] = Field(default=None, description="Custom endpoint URL")+ model: Optional[str] = Field(+ default=None, description="Model name for OpenAI-compatible providers"+ )+threshold: float = Field(default=0.1, description="Relevance threshold (score > threshold is relevant)")model_config = {"extra": "forbid"}+ @model_validator(mode="after")+ def validate_provider_fields(self) -> "RerankConfig":+ allowed = ["vikingdb", "openai"]+ if self.provider not in allowed:+ raise ValueError(f"Rerank provider must be one of {allowed}, got '{self.provider}'")+ if self.provider == "openai":+ if not self.api_key or not self.api_base:+ raise ValueError(+ "OpenAI-compatible rerank provider requires 'api_key' and 'api_base'"+ )+ return self+def is_available(self) -> bool:"""Check if rerank is configured."""+ if self.provider == "openai":+ return self.api_key is not None and self.api_base is not Nonereturn self.ak is not None and self.sk is not Nonediff --git a/openviking_cli/utils/rerank.py b/openviking_cli/utils/rerank.pyindex 10192c973..8ca906023 100644--- a/openviking_cli/utils/rerank.py+++ b/openviking_cli/utils/rerank.py@@ -156,6 +156,11 @@ class RerankClient:if not config or not config.is_available():return None+ if config.provider == "openai":+ from openviking_cli.utils.rerank_openai import OpenAIRerankClient++ return OpenAIRerankClient.from_config(config)+return cls(ak=config.ak,sk=config.sk,diff --git a/openviking_cli/utils/rerank_openai.py b/openviking_cli/utils/rerank_openai.pynew file mode 100644index 000000000..28557b533--- /dev/null+++ b/openviking_cli/utils/rerank_openai.py@@ -0,0 +1,122 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0+"""+OpenAI-compatible Rerank API Client.++Supports third-party rerank services like Alibaba Cloud DashScope (qwen3-rerank)+via api_key + api_base configuration.+"""++from typing import List, Optional++import requests++from openviking_cli.utils.logger import get_logger++logger = get_logger(__name__)+++class OpenAIRerankClient:+ """+ OpenAI-compatible rerank API client using Bearer token auth.++ Compatible with services like Alibaba Cloud DashScope.+ """++ def __init__(self, api_key: str, api_base: str, model_name: str):+ """+ Initialize OpenAI-compatible rerank client.++ Args:+ api_key: Bearer token for authentication+ api_base: Full endpoint URL for the rerank API+ model_name: Model name to use for reranking+ """+ self.api_key = api_key+ self.api_base = api_base+ self.model_name = model_name++ def rerank_batch(self, query: str, documents: List[str]) -> Optional[List[float]]:+ """+ Batch rerank documents against a query.++ Args:+ query: Query text+ documents: List of document texts to rank++ Returns:+ List of rerank scores for each document (same order as input),+ or None when rerank fails and the caller should fall back+ """+ if not documents:+ return []++ req_body = {+ "model": self.model_name,+ "query": query,+ "documents": documents,+ }++ try:+ response = requests.post(+ url=self.api_base,+ headers={+ "Authorization": f"Bearer {self.api_key}",+ "Content-Type": "application/json",+ },+ json=req_body,+ timeout=30,+ )+ response.raise_for_status()+ result = response.json()++ # Standard OpenAI/Cohere rerank format: results[].{index, relevance_score}+ results = result.get("results")+ if not results:+ logger.warning(f"[OpenAIRerankClient] Unexpected response format: {result}")+ return None++ if len(results) != len(documents):+ logger.warning(+ "[OpenAIRerankClient] Unexpected rerank result length: expected=%s actual=%s",+ len(documents),+ len(results),+ )+ return None++ # Results may not be in original order — sort by index+ scores = [0.0] * len(documents)+ for item in results:+ idx = item.get("index")+ if idx is None or not (0 <= idx < len(documents)):+ logger.warning(+ "[OpenAIRerankClient] Out-of-bounds or missing index in result: %s", item+ )+ return None+ scores[idx] = item.get("relevance_score", 0.0)++ logger.debug(f"[OpenAIRerankClient] Reranked {len(documents)} documents")+ return scores++ except Exception as e:+ logger.error(f"[OpenAIRerankClient] Rerank failed: {e}")+ return None++ @classmethod+ def from_config(cls, config) -> Optional["OpenAIRerankClient"]:+ """+ Create OpenAIRerankClient from RerankConfig.++ Args:+ config: RerankConfig instance with provider='openai'++ Returns:+ OpenAIRerankClient instance or None if config is not available+ """+ if not config or not config.is_available():+ return None+ return cls(+ api_key=config.api_key,+ api_base=config.api_base,+ model_name=config.model or "qwen3-rerank",+ )diff --git a/tests/misc/test_rerank_openai.py b/tests/misc/test_rerank_openai.pynew file mode 100644index 000000000..dd033b966--- /dev/null+++ b/tests/misc/test_rerank_openai.py@@ -0,0 +1,249 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0+"""Tests for OpenAI-compatible rerank client and factory dispatch."""++from unittest.mock import MagicMock, patch++import pytest+from pydantic import ValidationError++from openviking_cli.utils.config.rerank_config import RerankConfig+from openviking_cli.utils.rerank import RerankClient+from openviking_cli.utils.rerank_openai import OpenAIRerankClient+++class TestOpenAIRerankClient:+ def _make_client(self):+ return OpenAIRerankClient(+ api_key="test-key",+ api_base="https://dashscope.aliyuncs.com/api/v1/services/rerank",+ model_name="qwen3-rerank",+ )++ def test_rerank_batch_success(self):+ client = self._make_client()+ mock_response = MagicMock()+ mock_response.json.return_value = {+ "results": [+ {"index": 0, "relevance_score": 0.9},+ {"index": 1, "relevance_score": 0.3},+ {"index": 2, "relevance_score": 0.7},+ ]+ }+ mock_response.raise_for_status = MagicMock()++ with patch("openviking_cli.utils.rerank_openai.requests.post", return_value=mock_response):+ scores = client.rerank_batch("test query", ["doc1", "doc2", "doc3"])++ assert scores == [0.9, 0.3, 0.7]++ def test_rerank_batch_out_of_order_results(self):+ """Results returned out-of-order should be re-ordered by index."""+ client = self._make_client()+ mock_response = MagicMock()+ mock_response.json.return_value = {+ "results": [+ {"index": 2, "relevance_score": 0.7},+ {"index": 0, "relevance_score": 0.9},+ {"index": 1, "relevance_score": 0.3},+ ]+ }+ mock_response.raise_for_status = MagicMock()++ with patch("openviking_cli.utils.rerank_openai.requests.post", return_value=mock_response):+ scores = client.rerank_batch("test query", ["doc1", "doc2", "doc3"])++ assert scores == [0.9, 0.3, 0.7]++ def test_rerank_batch_empty_documents(self):+ client = self._make_client()+ scores = client.rerank_batch("query", [])+ assert scores == []++ def test_rerank_batch_unexpected_format_returns_none(self):+ client = self._make_client()+ mock_response = MagicMock()+ mock_response.json.return_value = {"unexpected": "format"}+ mock_response.raise_for_status = MagicMock()++ with patch("openviking_cli.utils.rerank_openai.requests.post", return_value=mock_response):+ result = client.rerank_batch("query", ["doc1"])++ assert result is None++ def test_rerank_batch_length_mismatch_returns_none(self):+ client = self._make_client()+ mock_response = MagicMock()+ mock_response.json.return_value = {+ "results": [+ {"index": 0, "relevance_score": 0.9},+ ]+ }+ mock_response.raise_for_status = MagicMock()++ with patch("openviking_cli.utils.rerank_openai.requests.post", return_value=mock_response):+ result = client.rerank_batch("query", ["doc1", "doc2"])++ assert result is None++ def test_rerank_batch_out_of_bounds_index_returns_none(self):+ """An index that is >= len(documents) should return None."""+ client = self._make_client()+ mock_response = MagicMock()+ mock_response.json.return_value = {+ "results": [+ {"index": 5, "relevance_score": 0.9}, # only 1 doc+ ]+ }+ mock_response.raise_for_status = MagicMock()++ with patch("openviking_cli.utils.rerank_openai.requests.post", return_value=mock_response):+ result = client.rerank_batch("query", ["doc1"])++ assert result is None++ def test_rerank_batch_missing_index_field_returns_none(self):+ """A result item with no 'index' key should return None."""+ client = self._make_client()+ mock_response = MagicMock()+ mock_response.json.return_value = {+ "results": [+ {"relevance_score": 0.9}, # missing 'index'+ ]+ }+ mock_response.raise_for_status = MagicMock()++ with patch("openviking_cli.utils.rerank_openai.requests.post", return_value=mock_response):+ result = client.rerank_batch("query", ["doc1"])++ assert result is None++ def test_rerank_batch_http_error_returns_none(self):+ client = self._make_client()++ with patch(+ "openviking_cli.utils.rerank_openai.requests.post",+ side_effect=Exception("connection error"),+ ):+ result = client.rerank_batch("query", ["doc1"])++ assert result is None++ def test_rerank_batch_sends_correct_request(self):+ client = self._make_client()+ mock_response = MagicMock()+ mock_response.json.return_value = {"results": [{"index": 0, "relevance_score": 0.8}]}+ mock_response.raise_for_status = MagicMock()++ with patch(+ "openviking_cli.utils.rerank_openai.requests.post", return_value=mock_response+ ) as mock_post:+ client.rerank_batch("my query", ["doc1"])++ call_kwargs = mock_post.call_args+ assert call_kwargs.kwargs["url"] == "https://dashscope.aliyuncs.com/api/v1/services/rerank"+ assert call_kwargs.kwargs["headers"]["Authorization"] == "Bearer test-key"+ body = call_kwargs.kwargs["json"]+ assert body["model"] == "qwen3-rerank"+ assert body["query"] == "my query"+ assert body["documents"] == ["doc1"]++ def test_from_config(self):+ config = RerankConfig(+ provider="openai",+ api_key="my-key",+ api_base="https://example.com/rerank",+ model="qwen3-rerank",+ )+ client = OpenAIRerankClient.from_config(config)+ assert isinstance(client, OpenAIRerankClient)+ assert client.api_key == "my-key"+ assert client.api_base == "https://example.com/rerank"+ assert client.model_name == "qwen3-rerank"++ def test_from_config_default_model(self):+ config = RerankConfig(+ provider="openai",+ api_key="my-key",+ api_base="https://example.com/rerank",+ )+ client = OpenAIRerankClient.from_config(config)+ assert client.model_name == "qwen3-rerank"++ def test_from_config_unavailable_returns_none(self):+ result = OpenAIRerankClient.from_config(None)+ assert result is None+++class TestRerankClientFactoryDispatch:+ def test_factory_dispatches_to_openai_client(self):+ config = RerankConfig(+ provider="openai",+ api_key="test-key",+ api_base="https://example.com/rerank",+ model="qwen3-rerank",+ )+ client = RerankClient.from_config(config)+ assert isinstance(client, OpenAIRerankClient)++ def test_factory_dispatches_to_vikingdb_client(self):+ config = RerankConfig(+ provider="vikingdb",+ ak="test-ak",+ sk="test-sk",+ )+ client = RerankClient.from_config(config)+ assert isinstance(client, RerankClient)+ assert not isinstance(client, OpenAIRerankClient)++ def test_factory_defaults_to_vikingdb(self):+ """Config without provider field defaults to vikingdb."""+ config = RerankConfig(ak="test-ak", sk="test-sk")+ client = RerankClient.from_config(config)+ assert isinstance(client, RerankClient)+ assert not isinstance(client, OpenAIRerankClient)++ def test_factory_returns_none_for_none_config(self):+ assert RerankClient.from_config(None) is None++ def test_factory_returns_none_for_unavailable_vikingdb_config(self):+ config = RerankConfig() # no ak/sk+ assert RerankClient.from_config(config) is None++ def test_factory_returns_none_for_unavailable_openai_config(self):+ # This should raise validation error since openai requires api_key + api_base+ with pytest.raises(ValidationError):+ RerankConfig(provider="openai")+++class TestRerankConfig:+ def test_vikingdb_is_available(self):+ config = RerankConfig(ak="ak", sk="sk")+ assert config.is_available() is True++ def test_vikingdb_not_available_without_credentials(self):+ config = RerankConfig()+ assert config.is_available() is False++ def test_openai_is_available(self):+ config = RerankConfig(+ provider="openai",+ api_key="key",+ api_base="https://example.com/rerank",+ )+ assert config.is_available() is True++ def test_openai_requires_api_key_and_api_base(self):+ with pytest.raises(ValidationError):+ RerankConfig(provider="openai", api_key="key")++ with pytest.raises(ValidationError):+ RerankConfig(provider="openai", api_base="https://example.com/rerank")++ def test_default_provider_is_vikingdb(self):+ config = RerankConfig()+ assert config.provider == "vikingdb"++ def test_unknown_provider_raises_value_error(self):+ with pytest.raises(ValueError, match="provider"):+ RerankConfig(provider="cohere", ak="ak", sk="sk")