From 1d88f95972b815be0028c4b93c9853172e211cca Mon Sep 17 00:00:00 2001 From: liming Date: Wed, 30 Sep 2026 14:53:19 +0800 Subject: [PATCH 1/5] fix(dashscope): forward rerank instruction as instruct --- .../llms/dashscope/rerank/transformation.py | 18 +++++--- .../test_dashscope_rerank_transformation.py | 42 +++++++++++++++++-- 2 files changed, 51 insertions(+), 9 deletions(-) diff --git a/litellm/llms/dashscope/rerank/transformation.py b/litellm/llms/dashscope/rerank/transformation.py index 14ad756ec9c..bc75ca9bd2c 100644 --- a/litellm/llms/dashscope/rerank/transformation.py +++ b/litellm/llms/dashscope/rerank/transformation.py @@ -54,7 +54,7 @@ class DashScopeRerankConfig(BaseRerankConfig): Reference: https://help.aliyun.com/zh/model-studio/text-rerank-api Targets DashScope's qwen3-rerank model. Request fields: model, query, - documents, top_n, return_documents. Response: results[].index, + documents, top_n, return_documents, instruct. Response: results[].index, results[].relevance_score, optionally results[].document.text (when return_documents=true), plus a top-level usage.total_tokens counter. """ @@ -109,7 +109,7 @@ class DashScopeRerankConfig(BaseRerankConfig): } def get_supported_cohere_rerank_params(self, model: str) -> list: - return ["query", "documents", "top_n", "return_documents"] + return ["query", "documents", "top_n", "return_documents", "instruction"] def map_cohere_rerank_params( self, @@ -126,8 +126,6 @@ class DashScopeRerankConfig(BaseRerankConfig): max_tokens_per_doc: int | None = None, instruction: str | None = None, ) -> dict: - # qwen3-rerank accepts query/documents/top_n/return_documents. The - # rest (rank_fields, max_*_per_doc) are silently dropped. params: Final[OptionalRerankParams] = OptionalRerankParams( query=query, documents=documents, @@ -136,7 +134,11 @@ class DashScopeRerankConfig(BaseRerankConfig): params["top_n"] = top_n if return_documents is not None: params["return_documents"] = return_documents - return dict(params) + mapped_params: Final[OptionalRerankParams] = { + **params, + **({"instruction": instruction} if instruction is not None else {}), + } + return dict(mapped_params) def transform_rerank_request( self, @@ -159,7 +161,11 @@ class DashScopeRerankConfig(BaseRerankConfig): request["top_n"] = optional_rerank_params["top_n"] if optional_rerank_params.get("return_documents") is not None: request["return_documents"] = optional_rerank_params["return_documents"] - return request + if optional_rerank_params.get("instruction") is None: + return request + return dict( # mutable-ok: rerank transport requires a JSON-serializable dict + request, instruct=optional_rerank_params["instruction"] + ) def transform_rerank_response( self, diff --git a/tests/unit/llms/dashscope/test_dashscope_rerank_transformation.py b/tests/unit/llms/dashscope/test_dashscope_rerank_transformation.py index 4466e5b8767..e0e420a79c2 100644 --- a/tests/unit/llms/dashscope/test_dashscope_rerank_transformation.py +++ b/tests/unit/llms/dashscope/test_dashscope_rerank_transformation.py @@ -3,18 +3,21 @@ Unit tests for DashScope rerank transformation. """ import json +from typing import Final from unittest.mock import MagicMock import httpx import pytest - +from litellm import LlmProviders from litellm.llms.dashscope.common_utils import DashScopeError from litellm.llms.dashscope.rerank.transformation import ( DEFAULT_RERANK_URL, DashScopeRerankConfig, ) +from litellm.rerank_api.rerank_utils import get_optional_rerank_params from litellm.types.rerank import RerankResponse +from litellm.utils import ProviderConfigManager class TestDashScopeRerankURL: @@ -111,11 +114,44 @@ class TestDashScopeRerankRequest: "documents", "top_n", "return_documents", + "instruction", ] + @pytest.mark.parametrize( + "provider", + [LlmProviders.DASHSCOPE, LlmProviders.QWENCLOUD, LlmProviders.QWEN_AI_PLATFORM], + ) + @pytest.mark.parametrize("instruction", [None, "", "Retrieve semantically similar text."]) + def test_instruction_reaches_provider_request( + self, provider: LlmProviders, instruction: str | None + ) -> None: + config: Final = ProviderConfigManager.get_provider_rerank_config( + model="qwen3-rerank", provider=provider, api_base=None, present_version_params=[] + ) + assert config is not None + params: Final = get_optional_rerank_params( + rerank_provider_config=config, + model="qwen3-rerank", + drop_params=False, + query="How do I reset my password?", + documents=["How can I change my password?", "Open settings and choose Reset password."], + top_n=1, + return_documents=False, + instruction=instruction, + ) + body: Final = config.transform_rerank_request( + model="qwen3-rerank", optional_rerank_params=params, headers={} + ) + assert body == { + "model": "qwen3-rerank", + "query": "How do I reset my password?", + "documents": ["How can I change my password?", "Open settings and choose Reset password."], + "top_n": 1, + "return_documents": False, + **({"instruct": instruction} if instruction is not None else {}), + } + def test_map_params_drops_unsupported(self): - # qwen3-rerank accepts query/documents/top_n/return_documents. - # rank_fields and max_*_per_doc are silently dropped. params = self.config.map_cohere_rerank_params( non_default_params={}, model="qwen3-rerank", From 80928f56cbfb14acc6bfc031d080a78e59e7094e Mon Sep 17 00:00:00 2001 From: liming Date: Fri, 9 Oct 2026 10:08:02 +0800 Subject: [PATCH 2/5] test(dashscope): restore rerank parameter comments --- .../unit/llms/dashscope/test_dashscope_rerank_transformation.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/unit/llms/dashscope/test_dashscope_rerank_transformation.py b/tests/unit/llms/dashscope/test_dashscope_rerank_transformation.py index e0e420a79c2..4dd889492d5 100644 --- a/tests/unit/llms/dashscope/test_dashscope_rerank_transformation.py +++ b/tests/unit/llms/dashscope/test_dashscope_rerank_transformation.py @@ -152,6 +152,8 @@ class TestDashScopeRerankRequest: } def test_map_params_drops_unsupported(self): + # qwen3-rerank accepts query/documents/top_n/return_documents. + # rank_fields and max_*_per_doc are silently dropped. params = self.config.map_cohere_rerank_params( non_default_params={}, model="qwen3-rerank", From 5f6a8a23012f75f0b040fc13076a8060ba6cdadf Mon Sep 17 00:00:00 2001 From: limdeng <42972202+limdeng@users.noreply.github.com> Date: Fri, 9 Oct 2026 10:17:18 +0800 Subject: [PATCH 3/5] fix(dashscope): remove unused mutable suppression --- litellm/llms/dashscope/rerank/transformation.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/litellm/llms/dashscope/rerank/transformation.py b/litellm/llms/dashscope/rerank/transformation.py index 8a1a62c2c9b..8ae1dbafec2 100644 --- a/litellm/llms/dashscope/rerank/transformation.py +++ b/litellm/llms/dashscope/rerank/transformation.py @@ -169,7 +169,7 @@ class DashScopeRerankConfig(BaseRerankConfig): request["return_documents"] = optional_rerank_params["return_documents"] if optional_rerank_params.get("instruction") is None: return request - return dict( # mutable-ok: rerank transport requires a JSON-serializable dict + return dict( request, instruct=optional_rerank_params["instruction"] ) From 0ca47e5fea18bab684d252d342369390a7afbbe5 Mon Sep 17 00:00:00 2001 From: limdeng <42972202+limdeng@users.noreply.github.com> Date: Fri, 9 Oct 2026 10:21:56 +0800 Subject: [PATCH 4/5] style(dashscope): format rerank request after suppression cleanup --- litellm/llms/dashscope/rerank/transformation.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/litellm/llms/dashscope/rerank/transformation.py b/litellm/llms/dashscope/rerank/transformation.py index 8ae1dbafec2..b4ad69619ae 100644 --- a/litellm/llms/dashscope/rerank/transformation.py +++ b/litellm/llms/dashscope/rerank/transformation.py @@ -169,9 +169,7 @@ class DashScopeRerankConfig(BaseRerankConfig): request["return_documents"] = optional_rerank_params["return_documents"] if optional_rerank_params.get("instruction") is None: return request - return dict( - request, instruct=optional_rerank_params["instruction"] - ) + return dict(request, instruct=optional_rerank_params["instruction"]) def transform_rerank_response( self, From c66a6c0c0ab707c98834656c5406a802e10618ea Mon Sep 17 00:00:00 2001 From: limdeng <42972202+limdeng@users.noreply.github.com> Date: Fri, 9 Oct 2026 10:36:12 +0800 Subject: [PATCH 5/5] fix(dashscope): type rerank instruction mapping --- litellm/llms/dashscope/rerank/transformation.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/litellm/llms/dashscope/rerank/transformation.py b/litellm/llms/dashscope/rerank/transformation.py index b4ad69619ae..0074debcb4e 100644 --- a/litellm/llms/dashscope/rerank/transformation.py +++ b/litellm/llms/dashscope/rerank/transformation.py @@ -140,16 +140,14 @@ class DashScopeRerankConfig(BaseRerankConfig): params["top_n"] = top_n if return_documents is not None: params["return_documents"] = return_documents - mapped_params: Final[OptionalRerankParams] = { - **params, - **({"instruction": instruction} if instruction is not None else {}), - } - return dict(mapped_params) + if instruction is not None: + params["instruction"] = instruction + return dict(params) def transform_rerank_request( self, model: str, - optional_rerank_params: dict, + optional_rerank_params: dict[str, object], headers: dict, litellm_params: dict | None = None, ) -> dict: @@ -167,9 +165,10 @@ class DashScopeRerankConfig(BaseRerankConfig): request["top_n"] = optional_rerank_params["top_n"] if optional_rerank_params.get("return_documents") is not None: request["return_documents"] = optional_rerank_params["return_documents"] - if optional_rerank_params.get("instruction") is None: + instruction: Final = optional_rerank_params.get("instruction") + if instruction is None: return request - return dict(request, instruct=optional_rerank_params["instruction"]) + return dict(request, instruct=_STR.validate_python(instruction)) def transform_rerank_response( self,