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
fix(rerank): support DashScope nested request/response envelope (#3463)
Yu Zhanga57adb951f31
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 3b4906ca7..292f9b2f6 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -848,7 +848,7 @@ Reranking model for search result refinement. Supports VikingDB (Volcengine), Co"provider": "openai","api_key": "your-api-key","api_base": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",- "model": "qwen3-vl-rerank",+ "model": "qwen3-rerank","timeout": 120,"max_input_tokens": 2048,"threshold": 0.1diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 6da6ac952..b0bf49156 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -817,7 +817,7 @@ AST 提取支持:Python、JavaScript/TypeScript、Rust、Go、Java、C/C++。"provider": "openai","api_key": "your-api-key","api_base": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",- "model": "qwen3-vl-rerank",+ "model": "qwen3-rerank","timeout": 120,"max_input_tokens": 2048,"threshold": 0.1diff --git a/openviking/models/rerank/openai_rerank.py b/openviking/models/rerank/openai_rerank.pyindex 2dcb9e222..838e7a16e 100644--- a/openviking/models/rerank/openai_rerank.py+++ b/openviking/models/rerank/openai_rerank.py@@ -17,6 +17,25 @@ from openviking_cli.utils import get_loggerlogger = get_logger(__name__)+# DashScope native API paths that use a nested request/response envelope.+# The OpenAI-compatible endpoint (/compatible-api/) uses the flat protocol.+_DASHSCOPE_NATIVE_PATH_MARKERS = ("/api/v1/services/rerank",)+++def _uses_nested_envelope(api_base: str) -> bool:+ """Return True if the endpoint uses DashScope's native nested envelope.++ DashScope exposes two API styles:+ - ``/compatible-api/v1/reranks`` — OpenAI-compatible, flat body and+ top-level ``results`` (used by qwen3-rerank).+ - ``/api/v1/services/rerank`` — native DashScope, nested+ ``input``/``output`` envelope (used by gte-rerank-v2, qwen3-vl-rerank).++ Detection is path-based, not hostname-based, so both styles work+ regardless of which DashScope host or gateway the user configures.+ """+ return any(marker in api_base for marker in _DASHSCOPE_NATIVE_PATH_MARKERS)+class OpenAIRerankClient(RerankBase):"""@@ -51,6 +70,47 @@ class OpenAIRerankClient(RerankBase):self.extra_headers = extra_headers or {}self.timeout = timeoutself.provider = "openai"+ self._uses_nested_envelope = _uses_nested_envelope(api_base)++ def _build_request_body(self, query: str, documents: List[str]) -> dict:+ """Build the request body for the rerank API.++ DashScope native API uses a nested envelope:+ {"model": ..., "input": {"query": ..., "documents": [...]}, "parameters": {...}}++ Standard OpenAI/Cohere and DashScope compatible-api use a flat body:+ {"model": ..., "query": ..., "documents": [...]}+ """+ if self._uses_nested_envelope:+ return {+ "model": self.model_name,+ "input": {+ "query": query,+ "documents": documents,+ },+ "parameters": {+ "return_documents": False,+ },+ }+ return {+ "model": self.model_name,+ "query": query,+ "documents": documents,+ }++ def _extract_results(self, response_json: dict) -> Optional[List[dict]]:+ """Extract the results list from an API response.++ DashScope native API nests results under ``output.results``;+ standard services and DashScope compatible-api return ``results``+ at the top level.+ """+ if self._uses_nested_envelope:+ output = response_json.get("output")+ if isinstance(output, dict):+ return output.get("results")+ return None+ return response_json.get("results")def rerank_batch(self, query: str, documents: List[str]) -> Optional[List[float]]:"""@@ -67,11 +127,7 @@ class OpenAIRerankClient(RerankBase):if not documents:return []- req_body = {- "model": self.model_name,- "query": query,- "documents": documents,- }+ req_body = self._build_request_body(query, documents)try:headers = {@@ -93,8 +149,7 @@ class OpenAIRerankClient(RerankBase):# Update token usage tracking (estimate, OpenAI rerank doesn't provide token info)self._extract_and_update_token_usage(result, query, documents)- # Standard OpenAI/Cohere rerank format: results[].{index, relevance_score}- results = result.get("results")+ results = self._extract_results(result)if not results:logger.warning(f"[OpenAIRerankClient] Unexpected response format: {result}")return None@@ -108,6 +163,8 @@ class OpenAIRerankClient(RerankBase):# Results may be sparse or out of order. Missing documents keep a# zero score while returned scores map back to their input indexes.+ # Both "relevance_score" (singular) and "relevance_scores" (plural)+ # are accepted — DashScope uses the singular form.scores = [0.0] * len(documents)for item in results:idx = item.get("index")@@ -116,7 +173,7 @@ class OpenAIRerankClient(RerankBase):"[OpenAIRerankClient] Out-of-bounds or missing index in result: %s", item)return None- scores[idx] = item.get("relevance_score", 0.0)+ scores[idx] = item.get("relevance_score", item.get("relevance_scores", 0.0))logger.debug(f"[OpenAIRerankClient] Reranked {len(documents)} documents")return scoresdiff --git a/tests/misc/test_rerank_openai.py b/tests/misc/test_rerank_openai.pyindex 311f8838b..002c3e7fa 100644--- a/tests/misc/test_rerank_openai.py+++ b/tests/misc/test_rerank_openai.py@@ -16,18 +16,20 @@ class TestOpenAIRerankClient:return OpenAIRerankClient(api_key="test-key",api_base="https://dashscope.aliyuncs.com/api/v1/services/rerank",- model_name="qwen3-rerank",+ model_name="gte-rerank-v2",)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},- ]+ "output": {+ "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()@@ -43,11 +45,13 @@ class TestOpenAIRerankClient: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},- ]+ "output": {+ "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()@@ -80,10 +84,12 @@ class TestOpenAIRerankClient: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},- ]+ "output": {+ "results": [+ {"index": 2, "relevance_score": 0.7},+ {"index": 0, "relevance_score": 0.9},+ ]+ }}mock_response.raise_for_status = MagicMock()@@ -102,9 +108,11 @@ class TestOpenAIRerankClient:client = self._make_client()mock_response = MagicMock()mock_response.json.return_value = {- "results": [- {"index": 5, "relevance_score": 0.9}, # only 1 doc- ]+ "output": {+ "results": [+ {"index": 5, "relevance_score": 0.9}, # only 1 doc+ ]+ }}mock_response.raise_for_status = MagicMock()@@ -120,9 +128,11 @@ class TestOpenAIRerankClient:client = self._make_client()mock_response = MagicMock()mock_response.json.return_value = {- "results": [- {"relevance_score": 0.9}, # missing 'index'- ]+ "output": {+ "results": [+ {"relevance_score": 0.9}, # missing 'index'+ ]+ }}mock_response.raise_for_status = MagicMock()@@ -147,7 +157,9 @@ class TestOpenAIRerankClient: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.json.return_value = {+ "output": {"results": [{"index": 0, "relevance_score": 0.8}]}+ }mock_response.raise_for_status = MagicMock()with patch(@@ -159,9 +171,10 @@ class TestOpenAIRerankClient: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"]+ assert body["model"] == "gte-rerank-v2"+ assert body["input"]["query"] == "my query"+ assert body["input"]["documents"] == ["doc1"]+ assert body["parameters"]["return_documents"] is Falsedef test_from_config(self):config = RerankConfig(diff --git a/tests/models/test_openai_rerank.py b/tests/models/test_openai_rerank.pynew file mode 100644index 000000000..13b9982c4--- /dev/null+++ b/tests/models/test_openai_rerank.py@@ -0,0 +1,327 @@+"""Tests for OpenAIRerankClient — DashScope native vs compatible-api protocol.++Regression for #3459: OpenAIRerankClient was incompatible with DashScope's+native API (gte-rerank-v2, qwen3-vl-rerank) which uses a nested+input/output envelope. The fix detects the protocol by URL path:++- ``/api/v1/services/rerank`` → native DashScope, nested envelope+- ``/compatible-api/v1/reranks`` → OpenAI-compatible, flat body+- Other endpoints → flat (default, backward compatible)+"""++from unittest.mock import MagicMock, patch++from openviking.models.rerank.openai_rerank import (+ OpenAIRerankClient,+ _uses_nested_envelope,+)++# ─── _uses_nested_envelope ───+++class TestUsesNestedEnvelope:+ def test_native_dashscope_path(self):+ assert _uses_nested_envelope("https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank") is True++ def test_compatible_api_path(self):+ assert _uses_nested_envelope("https://dashscope.aliyuncs.com/compatible-api/v1/reranks") is False++ def test_openai_path(self):+ assert _uses_nested_envelope("https://api.openai.com/v1/rerank") is False++ def test_empty_url(self):+ assert _uses_nested_envelope("") is False++ def test_custom_gateway_with_native_path(self):+ """Path detection works regardless of host/gateway."""+ assert _uses_nested_envelope("https://my-gateway.com/api/v1/services/rerank/text-rerank") is True+++# ─── Request body construction ───+++class TestBuildRequestBody:+ def test_native_nested_body(self):+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank",+ model_name="gte-rerank-v2",+ )+ body = client._build_request_body("hello", ["doc1", "doc2"])+ assert "input" in body+ assert body["input"]["query"] == "hello"+ assert body["input"]["documents"] == ["doc1", "doc2"]+ assert body["parameters"]["return_documents"] is False+ assert body["model"] == "gte-rerank-v2"+ # flat keys should NOT be present at top level+ assert "query" not in body+ assert "documents" not in body++ def test_compatible_api_flat_body(self):+ """DashScope compatible-api uses flat body, same as standard OpenAI."""+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://dashscope.aliyuncs.com/compatible-api/v1/reranks",+ model_name="qwen3-rerank",+ )+ body = client._build_request_body("hello", ["doc1", "doc2"])+ assert body["query"] == "hello"+ assert body["documents"] == ["doc1", "doc2"]+ assert body["model"] == "qwen3-rerank"+ # nested keys should NOT be present+ assert "input" not in body+ assert "parameters" not in body++ def test_standard_flat_body(self):+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://api.openai.com/v1/rerank",+ model_name="rerank-v2",+ )+ body = client._build_request_body("hello", ["doc1", "doc2"])+ assert body["query"] == "hello"+ assert body["documents"] == ["doc1", "doc2"]+ assert "input" not in body+++# ─── Response parsing ───+++class TestExtractResults:+ def test_native_nested_results(self):+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank",+ model_name="gte-rerank-v2",+ )+ response = {+ "output": {+ "results": [+ {"index": 0, "relevance_score": 0.95},+ {"index": 1, "relevance_score": 0.12},+ ]+ },+ "request_id": "abc123",+ }+ results = client._extract_results(response)+ assert results is not None+ assert len(results) == 2+ assert results[0]["relevance_score"] == 0.95++ def test_compatible_api_top_level_results(self):+ """DashScope compatible-api returns top-level results."""+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://dashscope.aliyuncs.com/compatible-api/v1/reranks",+ model_name="qwen3-rerank",+ )+ response = {+ "results": [+ {"index": 0, "relevance_score": 0.88},+ {"index": 1, "relevance_score": 0.42},+ ]+ }+ results = client._extract_results(response)+ assert results is not None+ assert len(results) == 2++ def test_native_missing_output(self):+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank",+ model_name="gte-rerank-v2",+ )+ assert client._extract_results({"request_id": "abc"}) is None++ def test_standard_missing_results(self):+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://api.openai.com/v1/rerank",+ model_name="rerank-v2",+ )+ assert client._extract_results({"id": "abc"}) is None+++# ─── End-to-end rerank_batch with mocked HTTP ───+++class TestRerankBatch:+ def test_native_full_flow(self):+ """DashScope native end-to-end: nested request, nested response."""+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank",+ model_name="gte-rerank-v2",+ )++ mock_response = MagicMock()+ mock_response.status_code = 200+ mock_response.raise_for_status.return_value = None+ mock_response.json.return_value = {+ "output": {+ "results": [+ {"index": 0, "relevance_score": 0.95},+ {"index": 1, "relevance_score": 0.12},+ ]+ },+ "request_id": "abc123",+ }++ with patch("openviking.models.rerank.openai_rerank.requests.post", return_value=mock_response) as mock_post:+ scores = client.rerank_batch("hello", ["doc1", "doc2"])++ assert scores == [0.95, 0.12]++ # Verify the request body was nested+ _, kwargs = mock_post.call_args+ sent_body = kwargs["json"]+ assert "input" in sent_body+ assert sent_body["input"]["query"] == "hello"+ assert sent_body["input"]["documents"] == ["doc1", "doc2"]++ def test_compatible_api_full_flow(self):+ """DashScope compatible-api end-to-end: flat request, flat response.++ This is the documented qwen3-rerank endpoint. It must use the+ same flat protocol as standard OpenAI services.+ """+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://dashscope.aliyuncs.com/compatible-api/v1/reranks",+ model_name="qwen3-rerank",+ )++ mock_response = MagicMock()+ mock_response.status_code = 200+ mock_response.raise_for_status.return_value = None+ mock_response.json.return_value = {+ "results": [+ {"index": 0, "relevance_score": 0.88},+ {"index": 1, "relevance_score": 0.42},+ ]+ }++ with patch("openviking.models.rerank.openai_rerank.requests.post", return_value=mock_response) as mock_post:+ scores = client.rerank_batch("hello", ["doc1", "doc2"])++ assert scores == [0.88, 0.42]++ # Verify the request body was flat+ _, kwargs = mock_post.call_args+ sent_body = kwargs["json"]+ assert sent_body["query"] == "hello"+ assert sent_body["documents"] == ["doc1", "doc2"]+ assert "input" not in sent_body++ def test_standard_full_flow(self):+ """Standard OpenAI-compatible end-to-end: flat request, flat response."""+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://api.openai.com/v1/rerank",+ model_name="rerank-v2",+ )++ mock_response = MagicMock()+ mock_response.status_code = 200+ mock_response.raise_for_status.return_value = None+ mock_response.json.return_value = {+ "results": [+ {"index": 0, "relevance_score": 0.88},+ {"index": 1, "relevance_score": 0.42},+ ]+ }++ with patch("openviking.models.rerank.openai_rerank.requests.post", return_value=mock_response) as mock_post:+ scores = client.rerank_batch("hello", ["doc1", "doc2"])++ assert scores == [0.88, 0.42]++ _, kwargs = mock_post.call_args+ sent_body = kwargs["json"]+ assert sent_body["query"] == "hello"+ assert sent_body["documents"] == ["doc1", "doc2"]++ def test_native_relevance_scores_plural_key(self):+ """Some DashScope models return 'relevance_scores' (plural)."""+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank",+ model_name="gte-rerank-v2",+ )++ mock_response = MagicMock()+ mock_response.status_code = 200+ mock_response.raise_for_status.return_value = None+ mock_response.json.return_value = {+ "output": {+ "results": [+ {"index": 0, "relevance_scores": 0.77},+ {"index": 1, "relevance_scores": 0.33},+ ]+ }+ }++ with patch("openviking.models.rerank.openai_rerank.requests.post", return_value=mock_response):+ scores = client.rerank_batch("hello", ["doc1", "doc2"])++ assert scores == [0.77, 0.33]++ def test_empty_documents(self):+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank",+ model_name="gte-rerank-v2",+ )+ assert client.rerank_batch("hello", []) == []++ def test_sparse_results_fill_zero(self):+ """Sparse results: missing indexes should get score 0.0."""+ client = OpenAIRerankClient(+ api_key="sk-test",+ api_base="https://api.openai.com/v1/rerank",+ model_name="rerank-v2",+ )++ mock_response = MagicMock()+ mock_response.status_code = 200+ mock_response.raise_for_status.return_value = None+ # Only index 1 returned, index 0 and 2 missing+ mock_response.json.return_value = {+ "results": [+ {"index": 1, "relevance_score": 0.55},+ ]+ }++ with patch("openviking.models.rerank.openai_rerank.requests.post", return_value=mock_response):+ scores = client.rerank_batch("hello", ["doc0", "doc1", "doc2"])++ assert scores == [0.0, 0.55, 0.0]++ def test_existing_dashscope_native_tests_still_pass(self):+ """The existing test suite uses /api/v1/services/rerank as api_base.++ Verify the client correctly detects this as native DashScope+ and uses the nested envelope.+ """+ client = OpenAIRerankClient(+ api_key="test-key",+ api_base="https://dashscope.aliyuncs.com/api/v1/services/rerank",+ model_name="qwen3-rerank",+ )+ assert client._uses_nested_envelope is True++ def test_compatible_api_uses_flat_protocol(self):+ """The documented compatible-api URL must use flat protocol.++ This is the regression for the reviewer's feedback: hostname-based+ detection incorrectly switched compatible-api to nested envelope.+ """+ client = OpenAIRerankClient(+ api_key="test-key",+ api_base="https://dashscope.aliyuncs.com/compatible-api/v1/reranks",+ model_name="qwen3-rerank",+ )+ assert client._uses_nested_envelope is False+ body = client._build_request_body("q", ["d"])+ assert "query" in body+ assert "input" not in body