Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

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.md
index 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.1
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 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.1
diff --git a/openviking/models/rerank/openai_rerank.py b/openviking/models/rerank/openai_rerank.py
index 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_logger
logger = 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 = timeout
self.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 scores
diff --git a/tests/misc/test_rerank_openai.py b/tests/misc/test_rerank_openai.py
index 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 False
def test_from_config(self):
config = RerankConfig(
diff --git a/tests/models/test_openai_rerank.py b/tests/models/test_openai_rerank.py
new file mode 100644
index 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