tangwang · tangwang · tangwang · tangwang · tangwang · tangwang
Showing 29 changed files Show diff stats
api/routes/indexer.py
config/config.yaml
config/loader.py
config/schema.py
docs/DEVELOPER_GUIDE.md
docs/QUICKSTART.md
docs/TODO-ES能力提升.md
docs/TODO.txt
docs/搜索API对接指南-01-搜索接口.md
docs/相关性检索优化说明.md
indexer/document_transformer.py
indexer/product_enrich.py
query/query_parser.py
requirements_hanlp.txt
scripts/eval_search_quality.py
search/es_query_builder.py
search/rerank_client.py
search/searcher.py
suggestion/builder.py
tests/test_embedding_pipeline.py
@@ -449,7 +449,7 @@ def _run_enrich_content(tenant_id: str, items: List[Dict[str, str]], languages: 
     同步执行内容理解：调用 product_enrich.analyze_products，按语言批量跑 LLM，
     再聚合成每 SPU 的 qanchors、semantic_attributes、tags。供 run_in_executor 调用。
     """
-    from indexer.product_enrich import analyze_products
+    from indexer.product_enrich import analyze_products, split_multi_value_field
  
     llm_langs = list(dict.fromkeys(languages)) or ["en"]
  
@@ -510,10 +510,7 @@ def _run_enrich_content(tenant_id: str, items: List[Dict[str, str]], languages: 
                 raw = row.get(name)
                 if not raw:
                     continue
-                for part in re.split(r"[,;|/\n\t]+", str(raw)):
-                    value = part.strip()
-                    if not value:
-                        continue
+                for value in split_multi_value_field(str(raw)):
                     rec["semantic_attributes"].append({"lang": lang, "name": name, "value": value})
                     if name == "tags":
                         rec["tags"].append(value)
 # Unified Configuration for Multi-Tenant Search Engine
 # 统一配置文件，所有租户共用一套配置
 # 注意：索引结构由 mappings/search_products.json 定义，此文件只配置搜索行为
+#
+# 约定：下列键为必填；进程环境变量可覆盖 infrastructure / runtime 中同名语义项
+#（如 ES_HOST、API_PORT 等），未设置环境变量时使用本文件中的值。
+
+# Process / bind addresses (环境变量 APP_ENV、RUNTIME_ENV、ES_INDEX_NAMESPACE 可覆盖前两者的语义)
+runtime:
+  environment: "prod"
+  index_namespace: ""
+  api_host: "0.0.0.0"
+  api_port: 6002
+  indexer_host: "0.0.0.0"
+  indexer_port: 6004
+  embedding_host: "0.0.0.0"
+  embedding_port: 6005
+  embedding_text_port: 6005
+  embedding_image_port: 6008
+  translator_host: "127.0.0.1"
+  translator_port: 6006
+  reranker_host: "127.0.0.1"
+  reranker_port: 6007
+
+# 基础设施连接（敏感项优先读环境变量：ES_*、REDIS_*、DB_*、DASHSCOPE_API_KEY、DEEPL_AUTH_KEY）
+infrastructure:
+  elasticsearch:
+    host: "http://localhost:9200"
+    username: null
+    password: null
+  redis:
+    host: "localhost"
+    port: 6479
+    snapshot_db: 0
+    password: null
+    socket_timeout: 1
+    socket_connect_timeout: 1
+    retry_on_timeout: false
+    cache_expire_days: 720
+    embedding_cache_prefix: "embedding"
+    anchor_cache_prefix: "product_anchors"
+    anchor_cache_expire_days: 30
+  database:
+    host: null
+    port: 3306
+    database: null
+    username: null
+    password: null
+  secrets:
+    dashscope_api_key: null
+    deepl_auth_key: null
  
 # Elasticsearch Index
 es_index_name: "search_products"
  
+# 检索域 / 索引列表（可为空列表；每项字段均需显式给出）
+indexes: []
+
 # Config assets
 assets:
   query_rewrite_dictionary_path: "config/dictionaries/query_rewrite.dict"
@@ -20,20 +71,19 @@ es_settings:
   refresh_interval: "30s"
  
 # 字段权重配置（用于搜索时的字段boost）
-# 统一按“字段基名”配置；查询时按 search_langs 动态拼接 .{lang}。
+# 统一按“字段基名”配置；查询时按实际检索语言动态拼接 .{lang}。
 # 若需要按某个语言单独调权，也可以加显式 key（例如 title.de: 3.2）。
 field_boosts:
   title: 3.0
+  qanchors: 2.5
+  tags: 2.0
+  category_name_text: 2.0
+  category_path: 2.0
   brief: 1.5
-  description: 1.0
-  qanchors: 1.5
-  vendor: 1.5
-  category_path: 1.5
-  category_name_text: 1.5
-  tags: 1.0
-  option1_values: 0.6
-  option2_values: 0.4
-  option3_values: 0.4
+  description: 1.5
+  option1_values: 1.5
+  option2_values: 1.5
+  option3_values: 1.5
  
 # Query Configuration（查询配置）
 query_config:
@@ -47,10 +97,23 @@ query_config:
   enable_text_embedding: true
   enable_query_rewrite: true
  
+  # 查询翻译模型（须与 services.translation.capabilities 中某项一致）
+  # 源语种在租户 index_languages 内：主召回可打在源语种字段，用下面三项。
+  # zh_to_en_model: "opus-mt-zh-en"
+  # en_to_zh_model: "opus-mt-en-zh"
+  # default_translation_model: "nllb-200-distilled-600m"
+  zh_to_en_model: "deepl"
+  en_to_zh_model: "deepl"
+  default_translation_model: "deepl"
+  # 源语种不在 index_languages：翻译对可检索文本更关键，可单独指定（缺省则与上一组相同）
+  zh_to_en_model__source_not_in_index: "deepl"
+  en_to_zh_model__source_not_in_index: "deepl"
+  default_translation_model__source_not_in_index: "deepl"
+
   # 查询解析阶段：翻译与 query 向量并发执行，共用同一等待预算（毫秒）。
   # 检测语言已在租户 index_languages 内：较短；不在索引语言内：较长（翻译对召回更关键）。
-  translation_embedding_wait_budget_ms_source_in_index: 80
-  translation_embedding_wait_budget_ms_source_not_in_index: 200
+  translation_embedding_wait_budget_ms_source_in_index: 500 # 80
+  translation_embedding_wait_budget_ms_source_not_in_index: 500 #200
  
   # 动态多语言检索字段配置
   # multilingual_fields 会被拼成 title.{lang}/brief.{lang}/... 形式；
@@ -58,11 +121,11 @@ query_config:
   search_fields:
     multilingual_fields:
       - "title"
-      - "brief"
-      - "description"
-      - "vendor"
+      - "qanchors"
       - "category_path"
       - "category_name_text"
+      - "brief"
+      - "description"
     shared_fields:
       - "tags"
       - "option1_values"
@@ -71,18 +134,14 @@ query_config:
     core_multilingual_fields:
       - "title"
       - "brief"
-      - "vendor"
       - "category_name_text"
  
-  # 统一文本召回策略（主查询 + 翻译查询 + 原始查询兜底）
+  # 统一文本召回策略（主查询 + 翻译查询）
   text_query_strategy:
     base_minimum_should_match: "75%"
     translation_minimum_should_match: "75%"
-    translation_boost: 0.4
-    translation_boost_when_source_missing: 1.0
-    source_boost_when_missing: 0.6
-    original_query_fallback_boost_when_translation_missing: 0.2
-    tie_breaker_base_query: 0.9
+    translation_boost: 0.75
+    tie_breaker_base_query: 0.5
  
   # Embedding字段名称
   text_embedding_field: "title_embedding"
@@ -120,7 +179,7 @@ query_config:
     - skus
  
   # KNN boost配置（向量召回的boost值）
-  knn_boost: 0.25  # Lower boost for embedding recall
+  knn_boost: 2.0  # Lower boost for embedding recall
  
 # Function Score配置（ES层打分规则）
 function_score:
@@ -148,6 +207,17 @@ services:
     cache:
       ttl_seconds: 62208000
       sliding_expiration: true
+      # When false, cache keys are exact-match per request model only (ignores model_quality_tiers for lookups).
+      enable_model_quality_tier_cache: true
+      # Higher tier = better quality. Multiple models may share one tier (同级).
+      # A request may reuse Redis keys from models with tier > A or tier == A (not from lower tiers).
+      model_quality_tiers:
+        deepl: 30
+        qwen-mt: 30
+        llm: 30
+        nllb-200-distilled-600m: 20
+        opus-mt-zh-en: 10
+        opus-mt-en-zh: 10
     capabilities:
       qwen-mt:
         enabled: true
@@ -290,7 +360,7 @@ services:
         engine: "vllm"
         max_model_len: 160
         tensor_parallel_size: 1
-        gpu_memory_utilization: 0.36
+        gpu_memory_utilization: 0.20
         dtype: "float16"
         enable_prefix_caching: true
         enforce_eager: false
@@ -284,19 +284,30 @@ class AppConfigLoader:
             base_minimum_should_match=str(text_strategy.get("base_minimum_should_match", "70%")),
             translation_minimum_should_match=str(text_strategy.get("translation_minimum_should_match", "70%")),
             translation_boost=float(text_strategy.get("translation_boost", 0.4)),
-            translation_boost_when_source_missing=float(
-                text_strategy.get("translation_boost_when_source_missing", 1.0)
-            ),
-            source_boost_when_missing=float(text_strategy.get("source_boost_when_missing", 0.6)),
-            original_query_fallback_boost_when_translation_missing=float(
-                text_strategy.get("original_query_fallback_boost_when_translation_missing", 0.2)
-            ),
             tie_breaker_base_query=float(text_strategy.get("tie_breaker_base_query", 0.9)),
             zh_to_en_model=str(query_cfg.get("zh_to_en_model") or "opus-mt-zh-en"),
             en_to_zh_model=str(query_cfg.get("en_to_zh_model") or "opus-mt-en-zh"),
             default_translation_model=str(
                 query_cfg.get("default_translation_model") or "nllb-200-distilled-600m"
             ),
+            zh_to_en_model_source_not_in_index=(
+                str(v)
+                if (v := query_cfg.get("zh_to_en_model__source_not_in_index"))
+                not in (None, "")
+                else None
+            ),
+            en_to_zh_model_source_not_in_index=(
+                str(v)
+                if (v := query_cfg.get("en_to_zh_model__source_not_in_index"))
+                not in (None, "")
+                else None
+            ),
+            default_translation_model_source_not_in_index=(
+                str(v)
+                if (v := query_cfg.get("default_translation_model__source_not_in_index"))
+                not in (None, "")
+                else None
+            ),
             translation_embedding_wait_budget_ms_source_in_index=int(
                 query_cfg.get("translation_embedding_wait_budget_ms_source_in_index", 80)
             ),
@@ -54,13 +54,14 @@ class QueryConfig:
     base_minimum_should_match: str = "70%"
     translation_minimum_should_match: str = "70%"
     translation_boost: float = 0.4
-    translation_boost_when_source_missing: float = 1.0
-    source_boost_when_missing: float = 0.6
-    original_query_fallback_boost_when_translation_missing: float = 0.2
     tie_breaker_base_query: float = 0.9
     zh_to_en_model: str = "opus-mt-zh-en"
     en_to_zh_model: str = "opus-mt-en-zh"
     default_translation_model: str = "nllb-200-distilled-600m"
+    # 检测语种不在租户 index_languages（无可直接命中的多语字段）时使用；None 表示与上一组同模型。
+    zh_to_en_model_source_not_in_index: Optional[str] = None
+    en_to_zh_model_source_not_in_index: Optional[str] = None
+    default_translation_model_source_not_in_index: Optional[str] = None
     # 查询阶段：翻译与向量生成并发提交后，共用同一等待预算（毫秒）。
     # 检测语言已在租户 index_languages 内：偏快返回，预算较短。
     # 检测语言不在 index_languages 内：翻译对召回更关键，预算较长。
@@ -147,7 +147,7 @@ docs/                # 文档（含本指南）
  
 ### 4.4 query
  
-- **职责**：查询解析与预处理：规范化、语言检测、改写（词典）、翻译、文本向量化；输出可供 Searcher 使用的结构化查询信息（含 search_langs 语言计划）。
+- **职责**：查询解析与预处理：规范化、语言检测、改写（词典）、翻译、文本向量化；输出解析事实（如 `rewritten_query`、`detected_language`、`translations`、`query_vector`），不再承担 ES 语言计划拼装。
 - **原则**：翻译/向量通过 `providers` 获取，不直接依赖具体服务 URL 或实现；支持按配置关闭翻译/向量（如短查询、typing 场景）。
  
 ### 4.5 search
@@ -558,6 +558,21 @@ lsof -i :6004
  
 更完整的运行排障（多环境切换、Suggestion 构建、FAQ）见 `docs/Usage-Guide.md`。
  
+### 5.4 HanLP 与 `transformers` 版本（`BertTokenizer.encode_plus`）
+
+若日志出现 **`AttributeError: BertTokenizer has no attribute encode_plus`**，通常是 **同一 venv 里装了 `transformers` 5.x**，与 **HanLP 2.1.x** 不兼容（HanLP 仍调用已移除的 `encode_plus`）。
+
+**处理：** 将 `transformers` 固定到 **4.x**（例如 4.44+），然后重装/校验 HanLP：
+
+```bash
+source activate.sh
+pip install -r requirements_hanlp.txt
+python -c "from transformers import BertTokenizer; import transformers as t; print(t.__version__, hasattr(BertTokenizer, 'encode_plus'))"
+# 期望：4.x 且 True
+```
+
+**说明：** 重排/TEI 等若使用 **独立 venv**（如 `.venv-reranker`），可与主 venv 的 `transformers` 版本分离；主 venv 只要装了 HanLP 做查询分词，就不要把 `transformers` 升到 5。
+
 ---
  
 ## 6. 相关文档
@@ -0,0 +1,69 @@
+ES 付费版本 or 定制开发（建议先看下付费版本价格）
+ES定制开发： 
+RRF / retrievers
+
+Elastic 的订阅矩阵里明确列了这些相关能力：Retrievers: linear, rule, RRF, text similarity re-ranker，以及 Reciprocal Rank Fusion (RRF) for hybrid search。
+
+这类能力最有价值的点是：
+它们把混合检索从“自己拼 DSL 和手搓打分”变成了官方支持的多阶段检索框架。重排：text similarity re-ranker / Elastic Rerank. text_similarity_reranker 用 NLP 模型对 top-k 结果按语义相似度重新排序；它可以用内置的 Elastic Rerank，也可以接 Cohere、Vertex AI，或者你自己上传的 text similarity 模型。
+
+{
+  "retriever": {
+    "rrf": {
+      "retrievers": [
+        { "standard": { "query": { ... } } },
+        { "knn": { ... } }
+      ]
+    }
+  }
+}
+
+
+加reranker：
+text_similarity_reranker 用 NLP 模型对 top-k 结果按语义相似度重新排序；它可以用内置的 Elastic Rerank，也可以接 Cohere、Vertex AI，或者你自己上传的 text similarity 模型。
+
+{
+  "retriever": {
+    "text_similarity_reranker": {
+      "retriever": {
+        "rrf": { ... }
+      },
+      ...
+    }
+  }
+}
+
+{
+  "retriever": {
+    "text_similarity_reranker": {
+      "retriever": {
+        "rrf": {
+          "retrievers": [
+            {
+              "standard": {
+                "query": {
+                  "...": "..."
+                }
+              }
+            },
+            {
+              "knn": {
+                "...": "..."
+              }
+            }
+          ],
+          "rank_window_size": 100,
+          "rank_constant": 20
+        }
+      },
+      "field": "your_rerank_text_field",
+      "inference_text": "白色 oversized T-shirt",
+      "inference_id": ".rerank-v1-elasticsearch",
+      "rank_window_size": 50
+    }
+  },
+  "size": 20
+}
+
+
+
  
  
-@reranker/backends/qwen3_vllm.py 单次 generate 前有进程内锁，同一进程里不会并行多路 vLLM 推理，这个锁有必要吗？是否会影响性能？是否能够打开，使得性能更好？比如这个场景，我一次请求 400 条，分成每64个一个batch，基于我现在的gpu配置，可以再提高并发度吗？
-测试了，让每个批次都并发地进行，耗时没有变化
+
+本地部署一个7b Q4量化的大模型
+es需要licence的两个功能，如果费用低，开通下licence，或者改es源码定制开发下，支持 rank.rrf，reranker
+
+
+
+把knn跟文本相关性的融合方式修改为  "rank": {"rrf": {} }需要licence，可以帮我修改源码支持吗？
+
+  knn_boost: 2.0  
+
+  
+{
+  "query": { ...全文检索... },
+  "knn": { ...向量检索... },
+  "rank": {
+    "rrf": {}
+  }
+}
+
+
+"image_embedding": {
+  "type": "nested",
+  "properties": {
+    "vector": {
+      "type": "dense_vector",
+      "dims": 1024,
+      "index": true,
+      "similarity": "dot_product",
+      "element_type": "bfloat16"
+    },
+    "url": {
+      "type": "text"
+    }
+  }
+},
+去掉 image_embedding_512
+image_embedding改为，一个spu有多个sku向量，每个向量内部properties：
+除了vector url还应该包括，该图片是对应哪些sku
+"image_embedding": {
+  "type": "nested",
+  "properties": {
+    "vector": {
+      "type": "dense_vector",
+      "dims": 1024,
+      "index": true,
+      "similarity": "dot_product",
+      "element_type": "bfloat16"
+    },
+    "url": {
+      "type": "text"
+    }
+  }
+},
+
+
+
+
+tags字段使用的优化：
+现在是keyword，在搜索中，不太好使用（目前主要用于suggest）。
+可以考虑也拆分多语言，配合analyzer使用（和qanchors一样）
+
+
+
+外部需求：
+1. 对推理能力要求很低、对耗时要求很高的大模型API（或者本地部署一个7b Q4量化的大模型），prompt大概30-50个token，首token响应要求500ms以内
+2. ES支持reranker pipline？
+
+
+
+
+
  
 增加款式意图识别模块
  
-意图类型： 颜色，尺寸（目前只需要支持这两种）
+意图类型： 颜色，尺码（目前只需要支持这两种）
  
 意图召回层：
 每种意图，有一个召回词集合
 对query（包括原始query、各种翻译query 都做匹配）
  
-意图识别层：
-如果召回 判断有款式需求，
+以颜色意图为例：
+有一个词表，每一行 都逗号分割，互为同义词，行内第一个为标准化词
+query匹配了其中任何一个词，都认为，具有颜色意图
+匹配规则： 用细粒度、粗粒度分词，看是否有在词表中的。原始query分词、和每种翻译的分词，都要用。
+
+意图判断： 暂时留空，直接返回true。目前没有模型，即只要召回了（词表匹配了），即认为有该维度款式需求。
+
+
+
+意图使用：
+
+我们第一阶段，使用 参与ES提权。
+
+一、参与ES提权
+
+
+二、参与reranker
  
  
-是否有：
-颜色需求
-尺码需求
 如果有： 先做sku筛选，然后把最优的拼接到名称中，参与reranker。
  
  
 现在在reranker、分页之后、做填充的时候，已经有做sku的筛选。
 需要优化：
 现在是，先做包含的判断，找到第一个 option_value被query包含的，则直接认为匹配。改为
-1. 第一轮：遍历完，如果有且仅有一个才这样。
-2. 第二轮：如果有多个，跳到3。如果没有，对每个词都走泛化词表进行匹配。
+1. 第一轮：遍历完，如果有且仅有一个被query包含，那么认为匹配。
+2. 第二轮：如果有多个符合（被query包含），跳到3。如果没有，对每个词都走泛化词表进行匹配。
 3. 第三轮：如果有多个，那么对这多个，走embedding相关性取最高的。如果一个也没有，则对所有的走embedding相关性取最高的
-这个sku筛选也需要提取为一个独立的模块
-
-
-
-2026-03-21 10:29:23,698 - elastic_transport.transport - INFO - POST http://localhost:9200/search_products_tenant_163/_search?include_named_queries_score=false [status:200 duration:0.009s]
-2026-03-21 10:29:23,700 - request_context - INFO - 分页详情回填 | ids=20 | filled=20 | took=7ms
-2026-03-21 10:29:23,700 - request_context - INFO - 重排分页切片 | from=20, size=20, 返回=20条
-2026-03-21 10:29:23,720 - embeddings.text_encoder - ERROR - TextEmbeddingEncoder service request failed: 502 Server Error: Bad Gateway for url: http://127.0.0.1:6005/embed/text?normalize=true&priority=1
-Traceback (most recent call last):
-  File "/data/saas-search/embeddings/text_encoder.py", line 63, in _call_service
-    response.raise_for_status()
-  File "/data/saas-search/.venv/lib/python3.12/site-packages/requests/models.py", line 1026, in raise_for_status
-    raise HTTPError(http_error_msg, response=self)
-requests.exceptions.HTTPError: 502 Server Error: Bad Gateway for url: http://127.0.0.1:6005/embed/text?normalize=true&priority=1
-2026-03-21 10:29:23,720 - search.searcher - WARNING - Failed to encode SKU option1 values for final-page sorting: 502 Server Error: Bad Gateway for url: http://127.0.0.1:6005/embed/text?normalize=true&priority=1
-Traceback (most recent call last):
-  File "/data/saas-search/search/searcher.py", line 448, in _apply_sku_sorting_for_page_hits
-    encoded_option_vectors = text_encoder.encode(option1_values_to_encode, priority=1)
-                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File "/data/saas-search/embeddings/text_encoder.py", line 112, in encode
-    response_data = self._call_service(
-                    ^^^^^^^^^^^^^^^^^^^
-  File "/data/saas-search/embeddings/text_encoder.py", line 63, in _call_service
-    response.raise_for_status()
-  File "/data/saas-search/.venv/lib/python3.12/site-packages/requests/models.py", line 1026, in raise_for_status
-    raise HTTPError(http_error_msg, response=self)
-requests.exceptions.HTTPError: 502 Server Error: Bad Gateway for url: http://127.0.0.1:6005/embed/text?normalize=true&priority=1
-2026-03-21 10:29:23,721 - request_context - WARNING - SKU option embedding failed: 502 Server Error: Bad Gateway for url: http://127.0.0.1:6005/embed/text?normalize=true&priority=1
+这个sku筛选也需要提取为一个独立的模块。
+
+
+另外：现在是reranker、分页之后做sku筛选，要改为：
+1. 有款式意图的时候，才做sku筛选
+2. sku筛选的时机，改为在reranker之前，对所有内容做sku筛选，然后
+3. 从仅 option1 扩展到多个维度，识别的意图，包含意图的维度名（color）和维度名的泛化词list（color、颜色、colour、olors、、、、），遍历option1_name,option2_name,option3_name，看哪个能匹配上意图的维度名list，哪个匹配上了，则在这个维度筛选。
+4. Rerank doc （有款式意图的时候）要带上属性后缀，拼接到title后面。在调用 run_rerank 前，对每条 hit 生成「用于重排的 doc 文本」（标题 + 可选后缀）
+5. TODO ： 还有一个问题。  目前，sku只返回一个维度（店铺主维度。默认应该是option1，不是所有维度的sku信息都返回的。所以，如果有款式意图，但是主维度是颜色，那么拿不到全的款式sku）
+
  
  
  
+当前项目功能已经较多，但是有清晰的框架，请务必基于现有框架进行改造，不要进行补丁式的修改，避免代码逻辑分叉。
+
+请一步一步来，先设计意图识别模块，仔细思考需求，意图识别模块需要提供哪些内容，用于返回数据接口的定义，深度思考，定义一个合理的接口后，再给出合理的模块设计。
+
+
+
+
+
+
+
+
+
+
+
+
+
+是否需要：
+当「源语言不在 index_languages」且「某些目标语言的翻译缺失」时，ES 里会额外加一层 用「原始 query 字符串」去撞缺失语种字段 
+
+
  
 先阅读文本embedding相关的代码：
 @embeddings/README.md @embeddings/server.py  @docs/搜索API对接指南-07-微服务接口（Embedding-Reranker-Translation）.md  @embeddings/text_encoder.py 
@@ -361,6 +444,31 @@ embeddings/image_encoder.py：requests.post(..., timeout=self.timeout_sec)
  
  
  
+
+
+
+
+
+
+
+多reranker：
+
+改 reranker 服务，一次请求返回多路分
+服务启动时 加载多个 backend（或按请求懒加载），/rerank 响应扩展为例如
+scores: [...]（兼容主后端）+ scores_by_backend: { "bge": [...], "qwen3_vllm": [...] }。
+搜索侧解析多路分，再融合或只透传 debug。
+优点：搜索侧仍只调一个 URL。缺点：单进程多大模型 显存压力很大；
+
+融合层要注意的一点
+fuse_scores_and_resort 目前只消费 一条 rerank_scores 序列，并写入 _rerank_score
+多 backend 之后需要rerank_scores 都参与融合
+
+
+
+
+
+
+
 product_enrich : Partial Mode   :   done
 https://help.aliyun.com/zh/model-studio/partial-mode?spm=a2c4g.11186623.help-menu-2400256.d_0_3_0_7.74a630119Ct6zR
 需在messages 数组中将最后一条消息的 role 设置为 assistant，并在其 content 中提供前缀，在此消息中设置参数 "partial": true。messages格式如下：
@@ -383,6 +491,8 @@ https://help.aliyun.com/zh/model-studio/partial-mode?spm=a2c4g.11186623.help-men
  
  
 融合打分（已完成，2026-03）
+
+以下已经完成：
 1. `fuse_scores_and_resort` 已改为乘法融合，并通过 `matched_queries` 提取：
    - `base_query`
    - `base_query_trans_*`
@@ -397,7 +507,11 @@ https://help.aliyun.com/zh/model-studio/partial-mode?spm=a2c4g.11186623.help-men
    - `docs/搜索API对接指南.md`
    - `docs/Usage-Guide.md`
  
-
+未完成的：
+（归一化、次序融合？还乘法公式？）
+RRF：先把多路召回稳妥融合
+linear + minmax：让你能精调 knn 和文本的权重
+reranker：对前面召回出来的 top-k 再做“最后一刀”
  
  
  
@@ -66,9 +66,11 @@ response = requests.post(url, headers=headers, json={&quot;query&quot;: &quot;芭比娃娃&quot;})
 | `min_score` | float | N | null | 最小相关性分数阈值 |
 | `sku_filter_dimension` | array[string] | N | null | 子SKU筛选维度列表（见[SKU筛选维度](#35-sku筛选维度)） |
 | `debug` | boolean | N | false | 是否返回调试信息 |
-| `enable_rerank` | boolean/null | N | null | 是否开启重排（调用外部重排服务对 ES 结果进行二次排序）。不传/传 null 使用服务端 `rerank.enabled`（默认开启）。开启后会先对 ES TopN（`rerank_window`）重排，再按分页截取；若 `from+size>1000`，则不重排，直接按分页从 ES 返回 |
-| `rerank_query_template` | string | N | null | 重排 query 模板（可选）。支持 `{query}` 占位符；不传则使用服务端配置 |
-| `rerank_doc_template` | string | N | null | 重排 doc 模板（可选）。支持 `{title} {brief} {vendor} {description} {category_path}`；不传则使用服务端配置 |
+| `enable_rerank` | boolean/null | N | null | 是否开启重排（调用外部重排服务对 ES 结果进行二次排序）。不传/传 null 使用服务端 `rerank.enabled`。当有效开启且 `from + size <= rerank_window` 时：ES 先取前 `rerank_window` 条，重排后再按 `from`/`size` 截取当前页；若 `from + size > rerank_window`，则**不进行**窗口内重排，直接按请求的 `from`/`size` 查询 ES（`rerank_window` 见 `config.yaml` 的 `rerank.rerank_window`，仓库示例默认 400） |
+| `rerank_query_template` | string | N | null | 重排 query 模板（可选）。支持 `{query}` 占位符；不传则使用服务端 `rerank.rerank_query_template` |
+| `rerank_doc_template` | string | N | null | 重排 doc 模板（可选）。支持 `{title} {brief} {vendor} {description} {category_path}` 等占位符（由 `search/rerank_client.py` 按语言字段拼装）；不传则使用服务端 `rerank.rerank_doc_template` |
+
+**与后端代码的对应关系**（便于联调）：HTTP `POST /search/` 请求体由 `api/models.py` 的 `SearchRequest` 校验；路由 `api/routes/search.py` 将字段原样传入 `Searcher.search(...)`（含上述三个重排相关字段）。CLI `python main.py search` 目前未暴露这些参数，走配置默认值。
 | `user_id` | string | N | null | 用户ID（用于个性化，预留） |
 | `session_id` | string | N | null | 会话ID（用于分析，预留） |
  
@@ -551,9 +553,6 @@ response = requests.post(url, headers=headers, json={&quot;query&quot;: &quot;芭比娃娃&quot;})
 | `rewritten_query` | string | 重写后的查询 |
 | `detected_language` | string | 检测到的语言 |
 | `translations` | object | 翻译结果 |
-| `query_text_by_lang` | object | 实际参与检索的多语言 query 文本 |
-| `search_langs` | array[string] | 实际参与检索的语言列表 |
-| `supplemental_search_langs` | array[string] | 因 mixed query 补入的附加语言列表 |
 | `has_vector` | boolean | 是否生成了向量 |
  
 `debug_info.per_result[]` 常见字段：
@@ -563,10 +562,9 @@ response = requests.post(url, headers=headers, json={&quot;query&quot;: &quot;芭比娃娃&quot;})
 | `spu_id` | string | 结果 SPU ID |
 | `es_score` | float | ES 原始 `_score` |
 | `rerank_score` | float | 重排分数 |
-| `text_score` | float | 文本相关性大分（由 `base_query` / `base_query_trans_*` / `fallback_original_query_*` 聚合而来） |
+| `text_score` | float | 文本相关性大分（由 `base_query` / `base_query_trans_*` 聚合而来） |
 | `text_source_score` | float | `base_query` 分数 |
 | `text_translation_score` | float | `base_query_trans_*` 里的最大分数 |
-| `text_fallback_score` | float | `fallback_original_query_*` 里的最大分数 |
 | `text_primary_score` | float | 文本大分中的主证据部分 |
 | `text_support_score` | float | 文本大分中的辅助证据部分 |
 | `knn_score` | float | `knn_query` 分数 |
@@ -2,11 +2,11 @@
  
 ## 1. 文档目标
  
-本文描述当前线上代码的文本检索策略，重点覆盖：
+本文描述当前代码中的文本检索策略，重点覆盖：
  
 - 多语言检索路由（`detector` / `translator` / `indexed` 的关系）
 - 统一文本召回表达式（无布尔 AST 分支）
-- 翻译缺失时的兜底策略
+- 解析层与检索表达式层的职责边界
 - 重排融合打分与调试字段
 - 典型场景下实际生成的 ES 查询结构
  
@@ -17,9 +17,11 @@
 查询链路（文本相关）：
  
 1. `QueryParser.parse()`  
-   输出 `detected_language`、`query_text_by_lang`、`search_langs`、`index_languages`、`source_in_index_languages`；另输出 `contains_chinese` / `contains_english`（仅服务混写辅助召回，见 §4 末）。
+   负责产出解析事实：`query_normalized`、`rewritten_query`、`detected_language`、`translations`、`query_vector`、`query_tokens`、`contains_chinese`、`contains_english`。
+2. `Searcher.search()`  
+   负责读取租户 `index_languages`，并将其一方面传给 `QueryParser` 作为 `target_languages`，另一方面传给 `ESQueryBuilder` 作为字段展开约束。
 2. `ESQueryBuilder._build_advanced_text_query()`  
-   按 `search_langs` 动态拼接 `title/brief/description/vendor/category_*` 的 `.{lang}` 字段，叠加 shared 字段（`tags`、`option*_values`）；若命中混写辅助条件，在同一子句内并入另一语种列（§4 末）。
+   基于 `rewritten_query + detected_language + translations + index_languages` 构建 `base_query` 与 `base_query_trans_*`；并按语言动态拼接 `title/brief/description/vendor/category_*` 的 `.{lang}` 字段，叠加 shared 字段（`tags`、`option*_values`）。
 3. `build_query()`  
    统一走文本策略，不再有布尔 AST 枝路。
  
@@ -37,18 +39,18 @@
    源语言字段做主召回；其他语言走翻译补召回（低权重）。
 2. 若 `detected_language not in index_languages`：  
    翻译到 `index_languages` 是主路径；源语言字段仅作弱召回。
-3. 若第 2 步翻译部分失败或全部失败：  
-   对缺失翻译的 `index_languages` 字段，追加“原文低权重兜底”子句，避免完全丢失这些语种索引面的召回机会。
+3. 若翻译部分失败或全部失败：  
+   当前实现不会再额外生成“原文打到其他语种字段”的兜底子句；系统保留 `base_query` 并继续执行，可观测性由 `translations` / warning / 命名子句分数提供。
  
 ### 3.2 翻译与向量：并发提交与共享超时
  
-`QueryParser.parse()` 内（Stage 4–6）对**离线调用**采用线程池提交 + **一次** `concurrent.futures.wait`：
+`QueryParser.parse()` 内对翻译与向量采用线程池提交 + **一次** `concurrent.futures.wait`：
  
-- **翻译**：对 `index_languages` 中除 `detected_language` 外的每个目标语种各提交一个 `translator.translate` 任务（多目标时并发执行）。
-- **查询向量**（若开启 `enable_text_embedding` 且域为 default）：再提交一个 `text_encoder.encode` 任务。
+- **翻译**：对调用方传入的 `target_languages` 中、除 `detected_language` 外的每个目标语种各提交一个 `translator.translate` 任务（多目标时并发执行）。
+- **查询向量**：若开启 `enable_text_embedding`，再提交一个 `text_encoder.encode` 任务。
 - 上述任务进入**同一** future 集合；例如租户索引为 `[zh, en]` 且检测语种**不在**索引内时，常为 **2 路翻译 + 1 路向量，共 3 个任务并发**，共用超时。
  
-**等待预算（毫秒）**由 `detected_language` 是否属于租户 `index_languages` 决定（`query_config`）：
+**等待预算（毫秒）**由 `detected_language` 是否属于调用方传入的 `target_languages` 决定（`query_config`）：
  
 - **在索引内**：`translation_embedding_wait_budget_ms_source_in_index`（默认较短，如 80ms）— 主召回已能打在源语种字段，翻译/向量稍慢可容忍。
 - **不在索引内**：`translation_embedding_wait_budget_ms_source_not_in_index`（默认较长，如 200ms）— 翻译对可检索文本更关键，给足时间。
@@ -62,7 +64,7 @@
 ```json
 {
   "multi_match": {
-    "_name": "base_query|base_query_trans_xx|fallback_original_query_xx",
+    "_name": "base_query|base_query_trans_xx",
     "query": "<text>",
     "fields": ["title.xx^3.0", "brief.xx^1.5", "...", "tags", "option1_values^0.5", "..."],
     "minimum_should_match": "75%",
@@ -75,7 +77,7 @@
 最终按 `bool.should` 组合，`minimum_should_match: 1`。
  
 > **附 — 混写辅助召回**  
-> 当中英（或多脚本）混写时，为略抬召回：`QueryParser` 用 `contains_chinese`（文中有汉字）、`contains_english`（分词中有长度 ≥3 的纯英文 token）打标；`ESQueryBuilder` 在某一语言的 `multi_match` 上，按规则把**另一语种**的同类字段并入同一 `fields`（受 `index_languages` 限制），并入列的 boost 为配置值再乘 **`mixed_script_merged_field_boost_scale`（默认 0.8，`ESQueryBuilder` 构造参数）**。`fallback_original_query_*` 同样适用。字段在内部以 `(path, boost)` 列表合并后再格式化为 ES 字符串。
+> 当中英（或多脚本）混写时，为略抬召回：`QueryParser` 用 `contains_chinese`（文中有汉字）、`contains_english`（分词中有长度 ≥3 的纯英文 token）打标；`ESQueryBuilder` 在某一语言的 `multi_match` 上，按规则把**另一语种**的同类字段并入同一 `fields`（受 `index_languages` 限制），并入列的 boost 为配置值再乘 **`mixed_script_merged_field_boost_scale`（默认 0.6，`ESQueryBuilder` 构造参数）**。字段在内部以 `(path, boost)` 列表合并后再格式化为 ES 字符串。
  
 ## 5. 关键配置项（文本策略）
  
@@ -88,20 +90,12 @@
  
 - `base_minimum_should_match`
 - `translation_minimum_should_match`
-- `translation_boost`
-- `translation_boost_when_source_missing`
-- `source_boost_when_missing`
-- `original_query_fallback_boost_when_translation_missing`（新增）
+- `translation_boost`（所有 `base_query_trans_*` 共用）
 - `tie_breaker_base_query`
  
-新增项说明：
-
-- `original_query_fallback_boost_when_translation_missing`：  
-  当源语种不在索引语言且翻译缺失时，原文打到缺失目标语字段的低权重系数，默认 `0.2`。
-
 说明：
  
-- `phrase_query` / `keywords_query` 已从当前实现中移除，文本相关性只由 `base_query`、`base_query_trans_*`、`fallback_original_query_*` 三类子句组成。
+- `phrase_query` / `keywords_query` 已从当前实现中移除，文本相关性只由 `base_query`、`base_query_trans_*` 两类子句组成。
  
 ## 6. 典型场景与实际 DSL
  
@@ -111,11 +105,12 @@
  
 - `detected_language=de`
 - `index_languages=[de,en]`
-- `query_text_by_lang={de:"herren schuhe", en:"men shoes"}`
+- `rewritten_query="herren schuhe"`
+- `translations={en:"men shoes"}`
  
 策略结果：
  
-- `base_query`：德语字段，正常权重
+- `base_query`：德语字段，**不写** `multi_match.boost`
 - `base_query_trans_en`：英语字段，`boost=translation_boost`（默认 0.4）
  
 ### 场景 B：源语种不在索引语言中，部分翻译缺失
@@ -126,38 +121,44 @@
  
 策略结果：
  
-- `base_query`（德语字段）：`boost=source_boost_when_missing`（默认 0.6）
-- `base_query_trans_en`（英文字段）：`boost=translation_boost_when_source_missing`（默认 1.0）
-- `fallback_original_query_zh`（中文字段）：原文低权重兜底（默认 0.2）
+- `base_query`（德语字段）：**不写** `multi_match.boost`（默认 1.0）
+- `base_query_trans_en`（英文字段）：`boost=translation_boost`（如 0.4）
+- 不会生成额外中文兜底子句
  
 ### 场景 C：源语种不在索引语言中，翻译全部失败
  
 - `detected_language=de`
 - `index_languages=[en,zh]`
-- `query_text_by_lang` 仅有 `de`
+- `translations={}`
  
 策略结果：
  
-- `base_query`（德语字段，低权重）
-- `fallback_original_query_en`（英文字段原文兜底）
-- `fallback_original_query_zh`（中文字段原文兜底）
+- `base_query`（德语字段，**无** `boost` 字段）
+- 不会生成 `base_query_trans_*`
  
-这能避免“只有源语种字段查询，且该语种字段在商家索引中稀疏/为空”导致的弱召回问题。
+这意味着当前实现优先保证职责清晰与可解释性，而不是继续在 Builder 内部隐式制造“跨语种原文兜底”。
  
-## 7. QueryParser 与 ESBuilder 的职责分工
+## 7. QueryParser 与 Searcher / ESBuilder 的职责分工
  
-- `QueryParser` 负责“语言计划”与“可用文本”：
-  - `search_langs`
-  - `query_text_by_lang`
-  - `source_in_index_languages`
-  - `index_languages`
+- `QueryParser` 负责“解析事实”：
+  - `query_normalized`
+  - `rewritten_query`
+  - `detected_language`
+  - `translations`
+  - `query_vector`
+  - `query_tokens`
   - `contains_chinese` / `contains_english`
+- `Searcher` 负责“租户语境”：
+  - `index_languages`
+  - 将其传给 parser 作为 `target_languages`
+  - 将其传给 builder 作为字段展开约束
 - `ESQueryBuilder` 负责“表达式展开”：
   - 动态字段组装
   - 子句权重分配
-  - 翻译缺失兜底子句拼接
+  - `base_query` / `base_query_trans_*` 子句拼接
+  - 跳过“与 base_query 文本和语言完全相同”的重复翻译子句
  
-这种分层让策略调优主要落在配置和 Builder，不破坏 Parser 的职责边界。
+这种分层让 parser 不再返回 ES 专用的“语言计划字段”，职责边界更清晰。
  
 ## 8. 融合打分（Rerank + Text + KNN）
  
@@ -165,24 +166,21 @@
  
 ### 8.1 文本相关性大分
  
-文本大分由三部分组成：
+文本大分由两部分组成：
  
 - `base_query`
 - `base_query_trans_*`
-- `fallback_original_query_*`
  
 聚合方式：
  
 1. `source_score = base_query`
 2. `translation_score = max(base_query_trans_*)`
-3. `fallback_score = max(fallback_original_query_*)`
-4. 加权：
+3. 加权：
    - `weighted_source = source_score`
    - `weighted_translation = 0.8 * translation_score`
-   - `weighted_fallback = 0.55 * fallback_score`
-5. 合成：
-   - `primary = max(weighted_source, weighted_translation, weighted_fallback)`
-   - `support = weighted_source + weighted_translation + weighted_fallback - primary`
+4. 合成：
+   - `primary = max(weighted_source, weighted_translation)`
+   - `support = weighted_source + weighted_translation - primary`
    - `text_score = primary + 0.25 * support`
  
 如果以上子分都缺失，则回退到 ES `_score` 作为 `text_score`，避免纯文本召回被误打成 0。
@@ -212,7 +210,6 @@ fused_score = (
 - `text_score`
 - `text_source_score`
 - `text_translation_score`
-- `text_fallback_score`
 - `text_primary_score`
 - `text_support_score`
 - `knn_score`
@@ -221,9 +218,9 @@ fused_score = (
  
 `debug_info.query_analysis` 还会暴露：
  
-- `query_text_by_lang`
-- `search_langs`
-- `supplemental_search_langs`
+- `translations`
+- `detected_language`
+- `rewritten_query`
  
 这些字段用于检索效果评估与 bad case 归因。
  
@@ -231,7 +228,7 @@ fused_score = (
  
 1. 当前文本主链路已移除布尔 AST 分支。  
 2. 文档中的旧描述（如 `operator: AND` 固定开启）不再适用，当前实现未强制设置该参数。  
-3. `HanLP` 为可选依赖；不可用时退化到轻量分词，不影响主链路可用性。  
+3. `HanLP` 为必需依赖；当前 parser 不再提供轻量 fallback。  
 4. 若后续扩展到更多语种，请确保：
    - mapping 中存在对应 `.<lang>` 字段
    - `index_languages` 配置在支持列表内
@@ -263,10 +260,9 @@ python ./scripts/eval_search_quality.py
 建议在 `tests/` 增加文本策略用例：
  
 1. 源语种在索引语言，翻译命中缓存  
-2. 源语种不在索引语言，翻译部分失败（验证 fallback 子句）  
-3. 源语种不在索引语言，翻译全部失败（验证多目标 fallback）  
-4. 自定义 `original_query_fallback_boost_when_translation_missing` 生效  
-5. 非 `zh/en` 语种字段动态拼接（如 `de/fr/es`）
+2. 源语种不在索引语言，翻译部分失败（验证仅保留 `base_query` + 成功翻译子句）  
+3. 源语种不在索引语言，翻译全部失败（验证无 `base_query_trans_*` 时仍可正常执行）  
+4. 非 `zh/en` 语种字段动态拼接（如 `de/fr/es`）
  
  
  
@@ -281,3 +277,24 @@ title.en: 2026 Korean-style High-waisted Slimming Corduroy Skirt with Slit, Mid-
 Rerank score: 0.9643
 title.en: Black Half-high Collar Base Shirt Women's Autumn and Winter fleece-lined Contrast Color Pure Desire Design Sense Horn Sleeve Ruffled Inner Top
 title.zh: 黑色高领半高领女士秋冬内搭加绒拼色纯欲设计荷叶边袖内衬上衣
+
+
+
+qwen3-0.6b的严重badcase：
+q=牛仔裤
+
+Rerank score: 0.0002
+title.en: Wrangler Womens Cowboy Cut Slim Fit Jean Bleach
+title.zh: Wrangler 女士牛仔裤 牛仔剪裁 紧身版型 漂白色
+
+Rerank score: 0.0168
+title.en: Fleece Lined Tights Sheer Women - Fake Translucent Warm Pantyhose Leggings Sheer Thick Tights for Winter
+title.zh: 加绒透肤女士连裤袜 - 仿透视保暖长筒袜 冬季厚款透肤连裤袜
+
+Rerank score: 0.1366
+title.en: Dockers Men's Classic Fit Workday Khaki Smart 360 FLEX Pants (Standard and Big & Tall)
+title.zh: Dockers 男士经典版型工作日卡其色智能360度弹力裤（标准码与加大码）
+
+Rerank score: 0.0981
+title.en: Lazy One Pajama Shorts for Men, Men's Pajama Bottoms, Sleepwear
+title.zh: 懒人男士睡裤，男式家居裤，睡眠服饰
@@ -13,7 +13,7 @@ import numpy as np
 import logging
 import re
 from typing import Dict, Any, Optional, List
-from indexer.product_enrich import analyze_products
+from indexer.product_enrich import analyze_products, split_multi_value_field
  
 logger = logging.getLogger(__name__)
  
@@ -121,7 +121,7 @@ class SPUDocumentTransformer:
         # Tags
         if pd.notna(spu_row.get('tags')):
             tags_str = str(spu_row['tags'])
-            doc['tags'] = [tag.strip() for tag in tags_str.split(',') if tag.strip()]
+            doc['tags'] = split_multi_value_field(tags_str)
  
         # Category相关字段
         self._fill_category_fields(doc, spu_row)
@@ -282,11 +282,7 @@ class SPUDocumentTransformer:
                 raw = row.get(name)
                 if not raw:
                     continue
-                parts = re.split(r"[,;|/\n\t]+", str(raw))
-                for part in parts:
-                    value = part.strip()
-                    if not value:
-                        continue
+                for value in split_multi_value_field(str(raw)):
                     semantic_list.append({"lang": lang, "name": name, "value": value})
  
             if qanchors_obj:
@@ -703,11 +699,7 @@ class SPUDocumentTransformer:
                 raw = row.get(name)
                 if not raw:
                     continue
-                parts = re.split(r"[,;|/\n\t]+", str(raw))
-                for part in parts:
-                    value = part.strip()
-                    if not value:
-                        continue
+                for value in split_multi_value_field(str(raw)):
                     semantic_list.append(
                         {
                             "lang": lang,
@@ -144,6 +144,20 @@ if _missing_prompt_langs:
     )
  
  
+# 多值字段分隔：英文逗号、中文逗号、顿号，及历史约定的 ; | / 与空白
+_MULTI_VALUE_FIELD_SPLIT_RE = re.compile(r"[，、,;|/\n\t]+")
+
+
+def split_multi_value_field(text: Optional[str]) -> List[str]:
+    """将 LLM/业务中的多值字符串拆成短语列表（strip 后去空）。"""
+    if text is None:
+        return []
+    s = str(text).strip()
+    if not s:
+        return []
+    return [p.strip() for p in _MULTI_VALUE_FIELD_SPLIT_RE.split(s) if p.strip()]
+
+
 def _normalize_space(text: str) -> str:
     return re.sub(r"\s+", " ", (text or "").strip())
  
 """
 Query parser - main module for query processing.
  
-Handles query rewriting, translation, and embedding generation.
+Responsibilities are intentionally narrow:
+- normalize and rewrite the incoming query
+- detect language and tokenize with HanLP
+- run translation and embedding requests concurrently
+- return parser facts, not Elasticsearch language-planning data
 """
  
-from typing import Dict, List, Optional, Any, Union, Tuple
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Tuple
 import numpy as np
 import logging
 import re
@@ -18,15 +23,12 @@ from .query_rewriter import QueryRewriter, QueryNormalizer
  
 logger = logging.getLogger(__name__)
  
-try:
-    import hanlp  # type: ignore
-except Exception:  # pragma: no cover
-    hanlp = None
+import hanlp  # type: ignore
  
  
 def simple_tokenize_query(text: str) -> List[str]:
     """
-    Lightweight tokenizer for suggestion length / analysis (aligned with QueryParser fallback).
+    Lightweight tokenizer for suggestion-side heuristics only.
  
     - Consecutive CJK characters form one token
     - Latin / digit runs (with internal hyphens) form tokens
@@ -37,63 +39,32 @@ def simple_tokenize_query(text: str) -&gt; List[str]:
     return pattern.findall(text)
  
  
+@dataclass(slots=True)
 class ParsedQuery:
-    """Container for parsed query results."""
-
-    def __init__(
-        self,
-        original_query: str,
-        query_normalized: str,
-        rewritten_query: Optional[str] = None,
-        detected_language: Optional[str] = None,
-        translations: Dict[str, str] = None,
-        query_vector: Optional[np.ndarray] = None,
-        domain: str = "default",
-        keywords: str = "",
-        token_count: int = 0,
-        query_tokens: Optional[List[str]] = None,
-        query_text_by_lang: Optional[Dict[str, str]] = None,
-        search_langs: Optional[List[str]] = None,
-        index_languages: Optional[List[str]] = None,
-        source_in_index_languages: bool = True,
-        contains_chinese: bool = False,
-        contains_english: bool = False,
-    ):
-        self.original_query = original_query
-        self.query_normalized = query_normalized
-        self.rewritten_query = rewritten_query or query_normalized
-        self.detected_language = detected_language
-        self.translations = translations or {}
-        self.query_vector = query_vector
-        self.domain = domain
-        # Query analysis fields
-        self.keywords = keywords
-        self.token_count = token_count
-        self.query_tokens = query_tokens or []
-        self.query_text_by_lang = query_text_by_lang or {}
-        self.search_langs = search_langs or []
-        self.index_languages = index_languages or []
-        self.source_in_index_languages = bool(source_in_index_languages)
-        self.contains_chinese = bool(contains_chinese)
-        self.contains_english = bool(contains_english)
+    """Container for query parser facts."""
+
+    original_query: str
+    query_normalized: str
+    rewritten_query: str
+    detected_language: Optional[str] = None
+    translations: Dict[str, str] = field(default_factory=dict)
+    query_vector: Optional[np.ndarray] = None
+    query_tokens: List[str] = field(default_factory=list)
+    contains_chinese: bool = False
+    contains_english: bool = False
  
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary representation."""
-        result = {
+        return {
             "original_query": self.original_query,
             "query_normalized": self.query_normalized,
             "rewritten_query": self.rewritten_query,
             "detected_language": self.detected_language,
             "translations": self.translations,
-            "domain": self.domain
+            "query_tokens": self.query_tokens,
+            "contains_chinese": self.contains_chinese,
+            "contains_english": self.contains_english,
         }
-        result["query_text_by_lang"] = self.query_text_by_lang
-        result["search_langs"] = self.search_langs
-        result["index_languages"] = self.index_languages
-        result["source_in_index_languages"] = self.source_in_index_languages
-        result["contains_chinese"] = self.contains_chinese
-        result["contains_english"] = self.contains_english
-        return result
  
  
 class QueryParser:
@@ -102,7 +73,7 @@ class QueryParser:
     1. Normalization
     2. Query rewriting (brand/category mappings, synonyms)
     3. Language detection
-    4. Translation to target languages
+    4. Translation to caller-provided target languages
     5. Text embedding generation (for semantic search)
     """
  
@@ -110,7 +81,8 @@ class QueryParser:
         self,
         config: SearchConfig,
         text_encoder: Optional[TextEmbeddingEncoder] = None,
-        translator: Optional[Any] = None
+        translator: Optional[Any] = None,
+        tokenizer: Optional[Callable[[str], Any]] = None,
     ):
         """
         Initialize query parser.
@@ -128,23 +100,7 @@ class QueryParser:
         self.normalizer = QueryNormalizer()
         self.language_detector = LanguageDetector()
         self.rewriter = QueryRewriter(config.query_config.rewrite_dictionary)
-        
-        # Optional HanLP components (heavy). If unavailable, fall back to a lightweight tokenizer.
-        self._tok = None
-        self._pos_tag = None
-        if hanlp is not None:
-            try:
-                logger.info("Initializing HanLP components...")
-                self._tok = hanlp.load(hanlp.pretrained.tok.CTB9_TOK_ELECTRA_BASE_CRF)
-                self._tok.config.output_spans = True
-                self._pos_tag = hanlp.load(hanlp.pretrained.pos.CTB9_POS_ELECTRA_SMALL)
-                logger.info("HanLP components initialized")
-            except Exception as e:
-                logger.warning(f"HanLP init failed, falling back to simple tokenizer: {e}")
-                self._tok = None
-                self._pos_tag = None
-        else:
-            logger.info("HanLP not installed; using simple tokenizer")
+        self._tokenizer = tokenizer or self._build_tokenizer()
  
         # Eager initialization (startup-time failure visibility, no lazy init in request path)
         if self.config.query_config.enable_text_embedding and self._text_encoder is None:
@@ -170,57 +126,81 @@ class QueryParser:
         """Return pre-initialized translator."""
         return self._translator
  
+    def _build_tokenizer(self) -> Callable[[str], Any]:
+        """Build the tokenizer used by query parsing. No fallback path by design."""
+        if hanlp is None:
+            raise RuntimeError("HanLP is required for QueryParser tokenization")
+        logger.info("Initializing HanLP tokenizer...")
+        tokenizer = hanlp.load(hanlp.pretrained.tok.CTB9_TOK_ELECTRA_BASE_CRF)
+        tokenizer.config.output_spans = True
+        logger.info("HanLP tokenizer initialized")
+        return tokenizer
+
     @staticmethod
-    def _pick_query_translation_model(source_lang: str, target_lang: str, config: SearchConfig) -> str:
+    def _pick_query_translation_model(
+        source_lang: str,
+        target_lang: str,
+        config: SearchConfig,
+        source_language_in_index: bool,
+    ) -> str:
         """Pick the translation capability for query-time translation (configurable)."""
         src = str(source_lang or "").strip().lower()
         tgt = str(target_lang or "").strip().lower()
+        qc = config.query_config
+
+        if source_language_in_index:
+            if src == "zh" and tgt == "en":
+                return qc.zh_to_en_model
+            if src == "en" and tgt == "zh":
+                return qc.en_to_zh_model
+            return qc.default_translation_model
  
-        # Use dedicated models for zh<->en if configured
         if src == "zh" and tgt == "en":
-            return config.query_config.zh_to_en_model
+            return qc.zh_to_en_model_source_not_in_index or qc.zh_to_en_model
         if src == "en" and tgt == "zh":
-            return config.query_config.en_to_zh_model
-
-        # For any other language pairs, fall back to the configurable default model.
-        # By default this is `nllb-200-distilled-600m` (multi-lingual local model).
-        return config.query_config.default_translation_model
-
-    def _simple_tokenize(self, text: str) -> List[str]:
-        return simple_tokenize_query(text)
-    
-    def _extract_keywords(self, query: str) -> str:
-        """Extract keywords (nouns with length > 1) from query."""
-        if self._tok is not None and self._pos_tag is not None:
-            tok_result = self._tok(query)
-            if not tok_result:
-                return ""
-            words = [x[0] for x in tok_result]
-            pos_tags = self._pos_tag(words)
-            keywords = []
-            for word, pos in zip(words, pos_tags):
-                if len(word) > 1 and isinstance(pos, str) and pos.startswith("N"):
-                    keywords.append(word)
-            return " ".join(keywords)
-
-        # Fallback: treat tokens with length > 1 as "keywords"
-        tokens = self._simple_tokenize(query)
-        keywords = [t for t in tokens if len(t) > 1]
-        return " ".join(keywords)
-    
-    def _get_token_count(self, query: str) -> int:
-        """Get token count (HanLP if available, otherwise simple)."""
-        if self._tok is not None:
-            tok_result = self._tok(query)
-            return len(tok_result) if tok_result else 0
-        return len(self._simple_tokenize(query))
+            return qc.en_to_zh_model_source_not_in_index or qc.en_to_zh_model
+        return qc.default_translation_model_source_not_in_index or qc.default_translation_model
+
+    @staticmethod
+    def _normalize_language_codes(languages: Optional[List[str]]) -> List[str]:
+        normalized: List[str] = []
+        seen = set()
+        for language in languages or []:
+            token = str(language or "").strip().lower()
+            if not token or token in seen:
+                continue
+            seen.add(token)
+            normalized.append(token)
+        return normalized
+
+    @staticmethod
+    def _extract_tokens(tokenizer_result: Any) -> List[str]:
+        """Normalize tokenizer output into a flat token string list."""
+        if not tokenizer_result:
+            return []
+        if isinstance(tokenizer_result, str):
+            token = tokenizer_result.strip()
+            return [token] if token else []
+
+        tokens: List[str] = []
+        for item in tokenizer_result:
+            token: Optional[str] = None
+            if isinstance(item, str):
+                token = item
+            elif isinstance(item, (list, tuple)) and item:
+                token = str(item[0])
+            elif item is not None:
+                token = str(item)
+
+            if token is None:
+                continue
+            token = token.strip()
+            if token:
+                tokens.append(token)
+        return tokens
  
     def _get_query_tokens(self, query: str) -> List[str]:
-        """Get token list (HanLP if available, otherwise simple)."""
-        if self._tok is not None:
-            tok_result = self._tok(query)
-            return [x[0] for x in tok_result] if tok_result else []
-        return self._simple_tokenize(query)
+        return self._extract_tokens(self._tokenizer(query))
  
     @staticmethod
     def _contains_cjk(text: str) -> bool:
@@ -237,64 +217,24 @@ class QueryParser:
             return False
         return bool(re.fullmatch(r"[A-Za-z]+(?:-[A-Za-z]+)*", token))
  
-    @staticmethod
-    def _extract_latin_tokens(text: str) -> List[str]:
-        """Extract latin word tokens from query text."""
-        return re.findall(r"[A-Za-z]+(?:-[A-Za-z]+)*", text or "")
-
-    def _infer_supplemental_search_langs(
-        self,
-        query_text: str,
-        detected_lang: str,
-        index_langs: List[str],
-    ) -> List[str]:
-        """
-        Infer extra languages to search when the query mixes scripts.
-
-        Rules:
-        - If any Chinese characters appear, include `zh` when available.
-        - If the query contains meaningful latin tokens, include `en` when available.
-          "Meaningful" means either:
-          1) at least 2 latin tokens with length >= 4, or
-          2) at least 1 latin token with length >= 4 and latin chars occupy >= 20% of non-space chars.
-        """
-        supplemental: List[str] = []
-        normalized_index_langs = {str(lang or "").strip().lower() for lang in index_langs}
-        normalized_detected = str(detected_lang or "").strip().lower()
-        query_text = str(query_text or "")
-
-        if "zh" in normalized_index_langs and self._contains_cjk(query_text) and normalized_detected != "zh":
-            supplemental.append("zh")
-
-        latin_tokens = self._extract_latin_tokens(query_text)
-        significant_latin_tokens = [tok for tok in latin_tokens if len(tok) >= 4]
-        latin_chars = sum(len(tok) for tok in latin_tokens)
-        non_space_chars = len(re.sub(r"\s+", "", query_text))
-        latin_ratio = (latin_chars / non_space_chars) if non_space_chars > 0 else 0.0
-        has_meaningful_english = (
-            len(significant_latin_tokens) >= 2 or
-            (len(significant_latin_tokens) >= 1 and latin_ratio >= 0.2)
-        )
-
-        if "en" in normalized_index_langs and has_meaningful_english and normalized_detected != "en":
-            supplemental.append("en")
-
-        return supplemental
-
     def parse(
         self,
         query: str,
         tenant_id: Optional[str] = None,
         generate_vector: bool = True,
-        context: Optional[Any] = None
+        context: Optional[Any] = None,
+        target_languages: Optional[List[str]] = None,
     ) -> ParsedQuery:
         """
         Parse query through all processing stages.
  
         Args:
             query: Raw query string
+            tenant_id: Deprecated and ignored by QueryParser. Kept temporarily
+                to avoid a wider refactor in this first step.
             generate_vector: Whether to generate query embedding
             context: Optional request context for tracking and logging
+            target_languages: Translation target languages decided by the caller
  
         Returns:
             ParsedQuery object with all processing results
@@ -325,15 +265,9 @@ class QueryParser:
         if context:
             context.store_intermediate_result('query_normalized', normalized)
  
-        # Extract domain if present (e.g., "brand:Nike" -> domain="brand", query="Nike")
-        domain, query_text = self.normalizer.extract_domain_query(normalized)
-        log_debug(f"Domain extraction | Domain: '{domain}', Query: '{query_text}'")
-        if context:
-            context.store_intermediate_result('extracted_domain', domain)
-            context.store_intermediate_result('domain_query', query_text)
-
         # Stage 2: Query rewriting
-        rewritten = None
+        query_text = normalized
+        rewritten = normalized
         if self.config.query_config.rewrite_dictionary:  # Enable rewrite if dictionary exists
             rewritten = self.rewriter.rewrite(query_text)
             if rewritten != query_text:
@@ -351,43 +285,57 @@ class QueryParser:
         log_info(f"Language detection | Detected language: {detected_lang}")
         if context:
             context.store_intermediate_result('detected_language', detected_lang)
+        # Stage 4: Query analysis (tokenization + script flags)
+        query_tokens = self._get_query_tokens(query_text)
+        contains_chinese = self._contains_cjk(query_text)
+        contains_english = any(self._is_pure_english_word_token(t) for t in query_tokens)
+
+        log_debug(
+            f"Query analysis | Query tokens: {query_tokens} | "
+            f"contains_chinese={contains_chinese} | contains_english={contains_english}"
+        )
+        if context:
+            context.store_intermediate_result('query_tokens', query_tokens)
+            context.store_intermediate_result('contains_chinese', contains_chinese)
+            context.store_intermediate_result('contains_english', contains_english)
  
-        # Stage 4: Translation — always submit to thread pool; results are collected together with
-        # embedding in one wait() that uses a configurable budget (short vs long by source-in-index).
+        # Stage 5: Translation + embedding. Parser only coordinates async enrichment work; the
+        # caller decides translation targets and later search-field planning.
         translations: Dict[str, str] = {}
-        translation_futures: Dict[str, Any] = {}
-        translation_executor: Optional[ThreadPoolExecutor] = None
-        index_langs: List[str] = []
+        future_to_task: Dict[Any, Tuple[str, Optional[str]]] = {}
+        async_executor: Optional[ThreadPoolExecutor] = None
         detected_norm = str(detected_lang or "").strip().lower()
+        normalized_targets = self._normalize_language_codes(target_languages)
+        translation_targets = [lang for lang in normalized_targets if lang != detected_norm]
+        source_language_in_index = bool(normalized_targets) and detected_norm in normalized_targets
+
+        # Stage 6: Text embedding - async execution
+        query_vector = None
+        should_generate_embedding = (
+            generate_vector and
+            self.config.query_config.enable_text_embedding
+        )
+
+        task_count = len(translation_targets) + (1 if should_generate_embedding else 0)
+        if task_count > 0:
+            async_executor = ThreadPoolExecutor(
+                max_workers=max(1, min(task_count, 4)),
+                thread_name_prefix="query-enrichment",
+            )
  
         try:
-            # 根据租户配置的 index_languages 决定翻译目标语言
-            from config.tenant_config_loader import get_tenant_config_loader
-            tenant_loader = get_tenant_config_loader()
-            tenant_cfg = tenant_loader.get_tenant_config(tenant_id or "default")
-            raw_index_langs = tenant_cfg.get("index_languages") or []
-            index_langs = []
-            seen_langs = set()
-            for lang in raw_index_langs:
-                norm_lang = str(lang or "").strip().lower()
-                if not norm_lang or norm_lang in seen_langs:
-                    continue
-                seen_langs.add(norm_lang)
-                index_langs.append(norm_lang)
-
-            target_langs_for_translation = [lang for lang in index_langs if lang != detected_norm]
-
-            if target_langs_for_translation:
-                translation_executor = ThreadPoolExecutor(
-                    max_workers=max(1, min(len(target_langs_for_translation), 4)),
-                    thread_name_prefix="query-translation",
-                )
-                for lang in target_langs_for_translation:
-                    model_name = self._pick_query_translation_model(detected_lang, lang, self.config)
+            if async_executor is not None:
+                for lang in translation_targets:
+                    model_name = self._pick_query_translation_model(
+                        detected_lang,
+                        lang,
+                        self.config,
+                        source_language_in_index,
+                    )
                     log_debug(
                         f"Submitting query translation | source={detected_lang} target={lang} model={model_name}"
                     )
-                    translation_futures[lang] = translation_executor.submit(
+                    future = async_executor.submit(
                         self.translator.translate,
                         query_text,
                         lang,
@@ -395,107 +343,61 @@ class QueryParser:
                         "ecommerce_search_query",
                         model_name,
                     )
-
-                if context:
-                    context.store_intermediate_result('translations', translations)
-                    for lang, translation in translations.items():
-                        if translation:
-                            context.store_intermediate_result(f'translation_{lang}', translation)
-
+                    future_to_task[future] = ("translation", lang)
+
+                if should_generate_embedding:
+                    if self.text_encoder is None:
+                        raise RuntimeError("Text embedding is enabled but text encoder is not initialized")
+                    log_debug("Submitting query vector generation")
+
+                    def _encode_query_vector() -> Optional[np.ndarray]:
+                        arr = self.text_encoder.encode([query_text], priority=1)
+                        if arr is None or len(arr) == 0:
+                            return None
+                        vec = arr[0]
+                        if vec is None:
+                            return None
+                        return np.asarray(vec, dtype=np.float32)
+
+                    future = async_executor.submit(_encode_query_vector)
+                    future_to_task[future] = ("embedding", None)
         except Exception as e:
-            error_msg = f"Translation failed | Error: {str(e)}"
+            error_msg = f"Async query enrichment submission failed | Error: {str(e)}"
             log_info(error_msg)
             if context:
                 context.add_warning(error_msg)
+            if async_executor is not None:
+                async_executor.shutdown(wait=False)
+                async_executor = None
+            future_to_task.clear()
  
-        # Stage 5: Query analysis (keywords, token count, query_tokens)
-        keywords = self._extract_keywords(query_text)
-        query_tokens = self._get_query_tokens(query_text)
-        token_count = len(query_tokens)
-        contains_chinese = self._contains_cjk(query_text)
-        contains_english = any(self._is_pure_english_word_token(t) for t in query_tokens)
-        
-        log_debug(f"Query analysis | Keywords: {keywords} | Token count: {token_count} | "
-                 f"Query tokens: {query_tokens} | contains_chinese={contains_chinese} | "
-                 f"contains_english={contains_english}")
-        if context:
-            context.store_intermediate_result('keywords', keywords)
-            context.store_intermediate_result('token_count', token_count)
-            context.store_intermediate_result('query_tokens', query_tokens)
-            context.store_intermediate_result('contains_chinese', contains_chinese)
-            context.store_intermediate_result('contains_english', contains_english)
-        
-        # Stage 6: Text embedding (only for non-short queries) - async execution
-        query_vector = None
-        embedding_future = None
-        should_generate_embedding = (
-            generate_vector and
-            self.config.query_config.enable_text_embedding and
-            domain == "default"
-        )
-        
-        encoding_executor = None
-        if should_generate_embedding:
-            try:
-                if self.text_encoder is None:
-                    raise RuntimeError("Text embedding is enabled but text encoder is not initialized")
-                log_debug("Starting query vector generation (async)")
-                # Submit encoding task to thread pool for async execution
-                encoding_executor = ThreadPoolExecutor(max_workers=1)
-                def _encode_query_vector() -> Optional[np.ndarray]:
-                    arr = self.text_encoder.encode([query_text], priority=1)
-                    if arr is None or len(arr) == 0:
-                        return None
-                    vec = arr[0]
-                    return vec if isinstance(vec, np.ndarray) else None
-                embedding_future = encoding_executor.submit(
-                    _encode_query_vector
-                )
-            except Exception as e:
-                error_msg = f"Query vector generation task submission failed | Error: {str(e)}"
-                log_info(error_msg)
-                if context:
-                    context.add_warning(error_msg)
-                encoding_executor = None
-                embedding_future = None
-        
-        # Wait for translation + embedding concurrently; shared budget (ms) depends on whether
-        # the detected language is in tenant index_languages.
+        # Wait for translation + embedding concurrently; shared budget depends on whether
+        # the detected language belongs to caller-provided target_languages.
         qc = self.config.query_config
-        source_in_index_for_budget = detected_norm in index_langs
+        source_in_target_languages = bool(normalized_targets) and detected_norm in normalized_targets
         budget_ms = (
             qc.translation_embedding_wait_budget_ms_source_in_index
-            if source_in_index_for_budget
+            if source_in_target_languages
             else qc.translation_embedding_wait_budget_ms_source_not_in_index
         )
         budget_sec = max(0.0, float(budget_ms) / 1000.0)
  
-        if translation_futures:
+        if translation_targets:
             log_info(
                 f"Translation+embedding shared wait budget | budget_ms={budget_ms} | "
-                f"source_in_index_languages={source_in_index_for_budget} | "
-                f"translation_targets={list(translation_futures.keys())}"
+                f"source_in_target_languages={source_in_target_languages} | "
+                f"translation_targets={translation_targets}"
             )
  
-        if translation_futures or embedding_future:
+        if future_to_task:
             log_debug(
                 f"Waiting for async tasks (translation+embedding) | budget_ms={budget_ms} | "
-                f"source_in_index_languages={source_in_index_for_budget}"
+                f"source_in_target_languages={source_in_target_languages}"
             )
  
-            all_futures: List[Any] = []
-            future_to_lang: Dict[Any, tuple] = {}
-            for lang, future in translation_futures.items():
-                all_futures.append(future)
-                future_to_lang[future] = ("translation", lang)
-
-            if embedding_future:
-                all_futures.append(embedding_future)
-                future_to_lang[embedding_future] = ("embedding", None)
-
-            done, not_done = wait(all_futures, timeout=budget_sec)
+            done, not_done = wait(list(future_to_task.keys()), timeout=budget_sec)
             for future in done:
-                task_type, lang = future_to_lang[future]
+                task_type, lang = future_to_task[future]
                 try:
                     result = future.result()
                     if task_type == "translation":
@@ -528,7 +430,7 @@ class QueryParser:
  
             if not_done:
                 for future in not_done:
-                    task_type, lang = future_to_lang[future]
+                    task_type, lang = future_to_task[future]
                     if task_type == "translation":
                         timeout_msg = (
                             f"Translation timeout (>{budget_ms}ms) | Language: {lang} | "
@@ -542,68 +444,21 @@ class QueryParser:
                     if context:
                         context.add_warning(timeout_msg)
  
-            if encoding_executor:
-                encoding_executor.shutdown(wait=False)
-            if translation_executor:
-                translation_executor.shutdown(wait=False)
+            if async_executor:
+                async_executor.shutdown(wait=False)
  
             if translations and context:
                 context.store_intermediate_result("translations", translations)
-        
-        # Build language-scoped query plan: source language + available translations
-        query_text_by_lang: Dict[str, str] = {}
-        if query_text:
-            query_text_by_lang[detected_lang] = query_text
-        for lang, translated_text in (translations or {}).items():
-            if translated_text and str(translated_text).strip():
-                query_text_by_lang[str(lang).strip().lower()] = str(translated_text)
-
-        supplemental_search_langs = self._infer_supplemental_search_langs(
-            query_text=query_text,
-            detected_lang=detected_lang,
-            index_langs=index_langs,
-        )
-        for lang in supplemental_search_langs:
-            if lang not in query_text_by_lang and query_text:
-                # Use the original mixed-script query as a robust fallback probe for that language field set.
-                query_text_by_lang[lang] = query_text
-
-        source_in_index_languages = detected_norm in index_langs
-        ordered_search_langs: List[str] = []
-        seen_order = set()
-        if detected_lang in query_text_by_lang:
-            ordered_search_langs.append(detected_lang)
-            seen_order.add(detected_lang)
-        for lang in index_langs:
-            if lang in query_text_by_lang and lang not in seen_order:
-                ordered_search_langs.append(lang)
-                seen_order.add(lang)
-        for lang in query_text_by_lang.keys():
-            if lang not in seen_order:
-                ordered_search_langs.append(lang)
-                seen_order.add(lang)
-        
-        if context:
-            context.store_intermediate_result("search_langs", ordered_search_langs)
-            context.store_intermediate_result("query_text_by_lang", query_text_by_lang)
-            context.store_intermediate_result("supplemental_search_langs", supplemental_search_langs)
  
         # Build result
         result = ParsedQuery(
             original_query=query,
             query_normalized=normalized,
-            rewritten_query=rewritten,
+            rewritten_query=query_text,
             detected_language=detected_lang,
             translations=translations,
             query_vector=query_vector,
-            domain=domain,
-            keywords=keywords,
-            token_count=token_count,
             query_tokens=query_tokens,
-            query_text_by_lang=query_text_by_lang,
-            search_langs=ordered_search_langs,
-            index_languages=index_langs,
-            source_in_index_languages=source_in_index_languages,
             contains_chinese=contains_chinese,
             contains_english=contains_english,
         )
@@ -611,14 +466,13 @@ class QueryParser:
         if context and hasattr(context, 'logger'):
             context.logger.info(
                 f"Query parsing completed | Original query: '{query}' | Final query: '{rewritten or query_text}' | "
-                f"Language: {detected_lang} | Domain: {domain} | "
                 f"Translation count: {len(translations)} | Vector: {'yes' if query_vector is not None else 'no'}",
                 extra={'reqid': context.reqid, 'uid': context.uid}
             )
         else:
             logger.info(
                 f"Query parsing completed | Original query: '{query}' | Final query: '{rewritten or query_text}' | "
-                f"Language: {detected_lang} | Domain: {domain}"
+                f"Language: {detected_lang}"
             )
  
         return result
@@ -0,0 +1,13 @@
+# Optional: HanLP query tokenization for the main backend venv (QueryParser).
+#
+# Install:
+#   source activate.sh
+#   pip install -r requirements_hanlp.txt
+#
+# Why pin transformers<5:
+#   transformers 5.x no longer exposes `encode_plus` on `BertTokenizer`, but HanLP 2.1.x
+#   still calls it → AttributeError during `hanlp.load(...)`.
+#   Use transformers 4.44+ (4.x) which remains API-compatible with HanLP.
+
+hanlp>=2.1.0
+transformers>=4.44,<5
@@ -83,7 +83,6 @@ class RankedItem:
     text_score: float | None
     text_source_score: float | None
     text_translation_score: float | None
-    text_fallback_score: float | None
     text_primary_score: float | None
     text_support_score: float | None
     knn_score: float | None
@@ -146,7 +145,6 @@ def _evaluate_query(searcher, tenant_id: str, query: str) -&gt; Dict[str, Any]:
                 text_score=_to_float(debug_item.get("text_score")),
                 text_source_score=_to_float(debug_item.get("text_source_score")),
                 text_translation_score=_to_float(debug_item.get("text_translation_score")),
-                text_fallback_score=_to_float(debug_item.get("text_fallback_score")),
                 text_primary_score=_to_float(debug_item.get("text_primary_score")),
                 text_support_score=_to_float(debug_item.get("text_support_score")),
                 knn_score=_to_float(debug_item.get("knn_score")),
@@ -185,12 +183,11 @@ def _render_markdown(report: Dict[str, Any]) -&gt; str:
                 f"- total={entry['total']} max_score={entry['max_score']:.6f} took_ms={entry['took_ms']}"
             )
             lines.append(
-                f"- detected_language={qa.get('detected_language')} search_langs={qa.get('search_langs')} supplemental_search_langs={qa.get('supplemental_search_langs')}"
+                f"- detected_language={qa.get('detected_language')} translations={qa.get('translations')}"
             )
-            lines.append(f"- query_text_by_lang={qa.get('query_text_by_lang')}")
             lines.append("")
-            lines.append("| rank | spu_id | title | fused | rerank | text | text_src | text_trans | text_fb | knn | es | matched_queries |")
-            lines.append("| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |")
+            lines.append("| rank | spu_id | title | fused | rerank | text | text_src | text_trans | knn | es | matched_queries |")
+            lines.append("| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |")
             for item in entry.get("top20", []):
                 title = str(item.get("title", "")).replace("|", "/")
                 matched = json.dumps(item.get("matched_queries"), ensure_ascii=False)
@@ -199,7 +196,7 @@ def _render_markdown(report: Dict[str, Any]) -&gt; str:
                     f"| {item.get('rank')} | {item.get('spu_id')} | {title} | "
                     f"{item.get('fused_score')} | {item.get('rerank_score')} | {item.get('text_score')} | "
                     f"{item.get('text_source_score')} | {item.get('text_translation_score')} | "
-                    f"{item.get('text_fallback_score')} | {item.get('knn_score')} | {item.get('es_score')} | {matched} |"
+                    f"{item.get('knn_score')} | {item.get('es_score')} | {matched} |"
                 )
             lines.append("")
     return "\n".join(lines)
@@ -36,11 +36,12 @@ class ESQueryBuilder:
         base_minimum_should_match: str = "70%",
         translation_minimum_should_match: str = "70%",
         translation_boost: float = 0.4,
-        translation_boost_when_source_missing: float = 1.0,
-        source_boost_when_missing: float = 0.6,
-        original_query_fallback_boost_when_translation_missing: float = 0.2,
         tie_breaker_base_query: float = 0.9,
         mixed_script_merged_field_boost_scale: float = 0.6,
+        phrase_match_base_fields: Optional[Tuple[str, ...]] = None,
+        phrase_match_slop: int = 2,
+        phrase_match_tie_breaker: float = 0.4,
+        phrase_match_boost: float = 3.0,
     ):
         """
         Initialize query builder.
@@ -74,13 +75,12 @@ class ESQueryBuilder:
         self.base_minimum_should_match = base_minimum_should_match
         self.translation_minimum_should_match = translation_minimum_should_match
         self.translation_boost = float(translation_boost)
-        self.translation_boost_when_source_missing = float(translation_boost_when_source_missing)
-        self.source_boost_when_missing = float(source_boost_when_missing)
-        self.original_query_fallback_boost_when_translation_missing = float(
-            original_query_fallback_boost_when_translation_missing
-        )
         self.tie_breaker_base_query = float(tie_breaker_base_query)
         self.mixed_script_merged_field_boost_scale = float(mixed_script_merged_field_boost_scale)
+        self.phrase_match_base_fields = tuple(phrase_match_base_fields or ("title", "qanchors"))
+        self.phrase_match_slop = int(phrase_match_slop)
+        self.phrase_match_tie_breaker = float(phrase_match_tie_breaker)
+        self.phrase_match_boost = float(phrase_match_boost)
  
     def _apply_source_filter(self, es_query: Dict[str, Any]) -> None:
         """
@@ -159,7 +159,8 @@ class ESQueryBuilder:
         knn_k: int = 50,
         knn_num_candidates: int = 200,
         min_score: Optional[float] = None,
-        parsed_query: Optional[Any] = None
+        parsed_query: Optional[Any] = None,
+        index_languages: Optional[List[str]] = None,
     ) -> Dict[str, Any]:
         """
         Build complete ES query with post_filter support for multi-select faceting.
@@ -167,7 +168,7 @@ class ESQueryBuilder:
         结构：filters and (text_recall or embedding_recall) + post_filter
         - conjunctive_filters: 应用在 query.bool.filter（影响结果和聚合）
         - disjunctive_filters: 应用在 post_filter（只影响结果，不影响聚合）
-        - text_recall: 文本相关性召回（按 search_langs 动态语言字段）
+        - text_recall: 文本相关性召回（按实际 clause 语言动态字段）
         - embedding_recall: 向量召回（KNN）
         - function_score: 包装召回部分，支持提权字段
  
@@ -202,7 +203,11 @@ class ESQueryBuilder:
         # Text recall (always include if query_text exists)
         if query_text:
             # Unified text query strategy
-            text_query = self._build_advanced_text_query(query_text, parsed_query)
+            text_query = self._build_advanced_text_query(
+                query_text,
+                parsed_query,
+                index_languages=index_languages,
+            )
             recall_clauses.append(text_query)
  
         # Embedding recall (KNN - separate from query, handled below)
@@ -456,6 +461,44 @@ class ESQueryBuilder:
         """Format (field_path, boost) pairs for Elasticsearch multi_match ``fields``."""
         return [self._format_field_with_boost(path, boost) for path, boost in specs]
  
+    def _build_phrase_match_fields(self, language: str) -> List[str]:
+        """Fields for phrase multi_match: base names × ``.{lang}`` with ``field_boosts``."""
+        lang = (language or "").strip().lower()
+        if not lang:
+            return []
+        out: List[str] = []
+        for base in self.phrase_match_base_fields:
+            path = f"{base}.{lang}"
+            boost = self._get_field_boost(base, lang)
+            out.append(self._format_field_with_boost(path, boost))
+        return out
+
+    def _append_phrase_should_clause(
+        self,
+        should_clauses: List[Dict[str, Any]],
+        lang: str,
+        lang_query: str,
+        clause_name: str
+    ) -> None:
+        text = (lang_query or "").strip()
+        if not text:
+            return
+        phrase_fields = self._build_phrase_match_fields(lang)
+        if not phrase_fields:
+            return
+        boost = self.phrase_match_boost
+        should_clauses.append({
+            "multi_match": {
+                "_name": f"{clause_name}_phrase",
+                "query": lang_query,
+                "type": "phrase",
+                "fields": phrase_fields,
+                "slop": self.phrase_match_slop,
+                "tie_breaker": self.phrase_match_tie_breaker,
+                "boost": boost,
+            }
+        })
+
     def _merge_supplemental_lang_field_specs(
         self,
         specs: List[MatchFieldSpec],
@@ -479,6 +522,7 @@ class ESQueryBuilder:
         contains_chinese: bool,
         contains_english: bool,
         index_languages: List[str],
+        is_source: bool = False
     ) -> List[MatchFieldSpec]:
         """
         When the query mixes scripts, widen each clause to indexed fields for the other script
@@ -492,10 +536,11 @@ class ESQueryBuilder:
  
         out = list(specs)
         lnorm = (lang or "").strip().lower()
-        if contains_english and lnorm != "en" and can_use("en"):
-            out = self._merge_supplemental_lang_field_specs(out, "en")
-        if contains_chinese and lnorm != "zh" and can_use("zh"):
-            out = self._merge_supplemental_lang_field_specs(out, "zh")
+        if is_source:
+            if contains_english and lnorm != "en" and can_use("en"):
+                out = self._merge_supplemental_lang_field_specs(out, "en")
+            if contains_chinese and lnorm != "zh" and can_use("zh"):
+                out = self._merge_supplemental_lang_field_specs(out, "zh")
         return out
  
     def _get_embedding_field(self, language: str) -> str:
@@ -503,13 +548,31 @@ class ESQueryBuilder:
         # Currently using unified embedding field
         return self.text_embedding_field or "title_embedding"
  
-    def _build_advanced_text_query(self, query_text: str, parsed_query: Optional[Any] = None) -> Dict[str, Any]:
+    @staticmethod
+    def _normalize_language_list(languages: Optional[List[str]]) -> List[str]:
+        normalized: List[str] = []
+        seen = set()
+        for language in languages or []:
+            token = str(language or "").strip().lower()
+            if not token or token in seen:
+                continue
+            seen.add(token)
+            normalized.append(token)
+        return normalized
+
+    def _build_advanced_text_query(
+        self,
+        query_text: str,
+        parsed_query: Optional[Any] = None,
+        *,
+        index_languages: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
         """
-        Build advanced text query using should clauses with primary and fallback lexical strategies.
+        Build advanced text query using base and translated lexical clauses.
  
         Unified implementation:
         - base_query: source-language clause
-        - translation queries: target-language clauses from search_langs/query_text_by_lang
+        - translation queries: target-language clauses from translations
         - KNN query: added separately in build_query
  
         Args:
@@ -520,66 +583,41 @@ class ESQueryBuilder:
             ES bool query with should clauses
         """
         should_clauses = []
-        
-        # Get query analysis from parsed_query
-        query_text_by_lang: Dict[str, str] = {}
-        search_langs: List[str] = []
         source_lang = self.default_language
-        source_in_index_languages = True
-        index_languages: List[str] = []
-
+        translations: Dict[str, str] = {}
         contains_chinese = False
         contains_english = False
+        normalized_index_languages = self._normalize_language_list(index_languages)
+
         if parsed_query:
-            query_text_by_lang = getattr(parsed_query, "query_text_by_lang", None) or {}
-            search_langs = getattr(parsed_query, "search_langs", None) or []
             detected_lang = getattr(parsed_query, "detected_language", None)
             source_lang = detected_lang if detected_lang and detected_lang != "unknown" else self.default_language
-            source_in_index_languages = bool(
-                getattr(parsed_query, "source_in_index_languages", True)
-            )
-            index_languages = getattr(parsed_query, "index_languages", None) or []
+            translations = getattr(parsed_query, "translations", None) or {}
             contains_chinese = bool(getattr(parsed_query, "contains_chinese", False))
             contains_english = bool(getattr(parsed_query, "contains_english", False))
  
-        if not query_text_by_lang:
-            query_text_by_lang = {source_lang: query_text}
-        if source_lang not in query_text_by_lang and query_text:
-            query_text_by_lang[source_lang] = query_text
-        if not search_langs:
-            search_langs = list(query_text_by_lang.keys())
-
-        # Base + translated clauses based on language plan.
-        for lang in search_langs:
-            lang_query = query_text_by_lang.get(lang)
-            if not lang_query:
-                continue
+        source_lang = str(source_lang or self.default_language).strip().lower() or self.default_language
+        base_query_text = (
+            getattr(parsed_query, "rewritten_query", None) if parsed_query else None
+        ) or query_text
+
+        def append_clause(lang: str, lang_query: str, clause_name: str, is_source: bool) -> None:
+            nonlocal should_clauses
             all_specs, _ = self._build_match_field_specs(lang)
             expanded_specs = self._expand_match_field_specs_for_mixed_script(
                 lang,
                 all_specs,
                 contains_chinese,
                 contains_english,
-                index_languages,
+                normalized_index_languages,
+                is_source,
             )
             match_fields = self._format_match_field_specs(expanded_specs)
             if not match_fields:
-                continue
-
-            is_source = (lang == source_lang)
-            clause_boost = 1.0
-            clause_name = "base_query" if is_source else f"base_query_trans_{lang}"
+                return
             minimum_should_match = (
                 self.base_minimum_should_match if is_source else self.translation_minimum_should_match
             )
-            if is_source and not source_in_index_languages:
-                clause_boost = self.source_boost_when_missing
-            elif not is_source:
-                clause_boost = (
-                    self.translation_boost
-                    if source_in_index_languages
-                    else self.translation_boost_when_source_missing
-                )
  
             clause = {
                 "multi_match": {
@@ -590,55 +628,34 @@ class ESQueryBuilder:
                     "tie_breaker": self.tie_breaker_base_query,
                 }
             }
-            if abs(clause_boost - 1.0) > 1e-9:
-                clause["multi_match"]["boost"] = clause_boost
+            # base_query: never set multi_match.boost (ES default 1.0).
+            # Translation clauses: single knob from config — translation_boost.
+            if not is_source:
+                tb = float(self.translation_boost)
+                clause["multi_match"]["boost"] = tb
             should_clauses.append({
                 "multi_match": clause["multi_match"]
             })
+            self._append_phrase_should_clause(
+                should_clauses, lang, lang_query, clause_name
+            )
  
-        # Fallback: source language is not indexed and translation for some index languages is missing.
-        # Use original query text on missing index-language fields with a low boost.
-        if not source_in_index_languages and query_text and index_languages:
-            normalized_index_langs: List[str] = []
-            seen_langs = set()
-            for lang in index_languages:
-                norm_lang = str(lang or "").strip().lower()
-                if not norm_lang or norm_lang in seen_langs:
-                    continue
-                seen_langs.add(norm_lang)
-                normalized_index_langs.append(norm_lang)
+        if base_query_text:
+            append_clause(source_lang, base_query_text, "base_query", True)
  
-            for lang in normalized_index_langs:
-                if lang == source_lang:
-                    continue
-                if lang in query_text_by_lang:
-                    continue
-                fb_specs, _ = self._build_match_field_specs(lang)
-                expanded_fb = self._expand_match_field_specs_for_mixed_script(
-                    lang,
-                    fb_specs,
-                    contains_chinese,
-                    contains_english,
-                    index_languages,
-                )
-                match_fields = self._format_match_field_specs(expanded_fb)
-                if not match_fields:
-                    continue
-                should_clauses.append({
-                    "multi_match": {
-                        "_name": f"fallback_original_query_{lang}",
-                        "query": query_text,
-                        "fields": match_fields,
-                        "minimum_should_match": self.translation_minimum_should_match,
-                        "tie_breaker": self.tie_breaker_base_query,
-                        "boost": self.original_query_fallback_boost_when_translation_missing,
-                    }
-                })
+        for lang, translated_text in translations.items():
+            normalized_lang = str(lang or "").strip().lower()
+            normalized_text = str(translated_text or "").strip()
+            if not normalized_lang or not normalized_text:
+                continue
+            if normalized_lang == source_lang and normalized_text == base_query_text:
+                continue
+            append_clause(normalized_lang, normalized_text, f"base_query_trans_{normalized_lang}", False)
  
         # Fallback to a simple query when language fields cannot be resolved.
         if not should_clauses:
             fallback_fields = self.match_fields or ["title.en^1.0"]
-            return {
+            fallback_lexical = {
                 "multi_match": {
                     "_name": "base_query_fallback",
                     "query": query_text,
@@ -647,6 +664,21 @@ class ESQueryBuilder:
                     "tie_breaker": self.tie_breaker_base_query,
                 }
             }
+            fb_should: List[Dict[str, Any]] = [fallback_lexical]
+            self._append_phrase_should_clause(
+                fb_should,
+                self.default_language,
+                query_text,
+                "base_query_fallback"
+            )
+            if len(fb_should) == 1:
+                return fallback_lexical
+            return {
+                "bool": {
+                    "should": fb_should,
+                    "minimum_should_match": 1,
+                }
+            }
  
         # Return bool query with should clauses
         if len(should_clauses) == 1:
@@ -116,7 +116,6 @@ def _extract_named_query_score(matched_queries: Any, name: str) -&gt; float:
 def _collect_text_score_components(matched_queries: Any, fallback_es_score: float) -> Dict[str, float]:
     source_score = _extract_named_query_score(matched_queries, "base_query")
     translation_score = 0.0
-    fallback_score = 0.0
  
     if isinstance(matched_queries, dict):
         for query_name, score in matched_queries.items():
@@ -125,21 +124,16 @@ def _collect_text_score_components(matched_queries: Any, fallback_es_score: floa
             numeric_score = _to_score(score)
             if query_name.startswith("base_query_trans_"):
                 translation_score = max(translation_score, numeric_score)
-            elif query_name.startswith("fallback_original_query_"):
-                fallback_score = max(fallback_score, numeric_score)
     elif isinstance(matched_queries, list):
         for query_name in matched_queries:
             if not isinstance(query_name, str):
                 continue
             if query_name.startswith("base_query_trans_"):
                 translation_score = 1.0
-            elif query_name.startswith("fallback_original_query_"):
-                fallback_score = 1.0
  
     weighted_source = source_score
     weighted_translation = 0.8 * translation_score
-    weighted_fallback = 0.55 * fallback_score
-    weighted_components = [weighted_source, weighted_translation, weighted_fallback]
+    weighted_components = [weighted_source, weighted_translation]
     primary_text_score = max(weighted_components)
     support_text_score = sum(weighted_components) - primary_text_score
     text_score = primary_text_score + 0.25 * support_text_score
@@ -153,10 +147,8 @@ def _collect_text_score_components(matched_queries: Any, fallback_es_score: floa
     return {
         "source_score": source_score,
         "translation_score": translation_score,
-        "fallback_score": fallback_score,
         "weighted_source_score": weighted_source,
         "weighted_translation_score": weighted_translation,
-        "weighted_fallback_score": weighted_fallback,
         "primary_text_score": primary_text_score,
         "support_text_score": support_text_score,
         "text_score": text_score,
@@ -219,7 +211,6 @@ def fuse_scores_and_resort(
         hit["_knn_score"] = knn_score
         hit["_text_source_score"] = text_components["source_score"]
         hit["_text_translation_score"] = text_components["translation_score"]
-        hit["_text_fallback_score"] = text_components["fallback_score"]
         hit["_text_primary_score"] = text_components["primary_text_score"]
         hit["_text_support_score"] = text_components["support_text_score"]
         hit["_fused_score"] = fused
@@ -231,7 +222,6 @@ def fuse_scores_and_resort(
             "text_score": text_score,
             "text_source_score": text_components["source_score"],
             "text_translation_score": text_components["translation_score"],
-            "text_fallback_score": text_components["fallback_score"],
             "text_primary_score": text_components["primary_text_score"],
             "text_support_score": text_components["support_text_score"],
             "knn_score": knn_score,
@@ -132,11 +132,6 @@ class Searcher:
             base_minimum_should_match=self.config.query_config.base_minimum_should_match,
             translation_minimum_should_match=self.config.query_config.translation_minimum_should_match,
             translation_boost=self.config.query_config.translation_boost,
-            translation_boost_when_source_missing=self.config.query_config.translation_boost_when_source_missing,
-            source_boost_when_missing=self.config.query_config.source_boost_when_missing,
-            original_query_fallback_boost_when_translation_missing=(
-                self.config.query_config.original_query_fallback_boost_when_translation_missing
-            ),
             tie_breaker_base_query=self.config.query_config.tie_breaker_base_query,
         )
  
@@ -267,13 +262,6 @@ class Searcher:
             if normalized:
                 candidates.append(normalized)
  
-        query_text_by_lang = getattr(parsed_query, "query_text_by_lang", {}) or {}
-        if isinstance(query_text_by_lang, dict):
-            for text in query_text_by_lang.values():
-                normalized = self._normalize_sku_match_text(text)
-                if normalized:
-                    candidates.append(normalized)
-
         translations = getattr(parsed_query, "translations", {}) or {}
         if isinstance(translations, dict):
             for text in translations.values():
@@ -516,10 +504,19 @@ class Searcher:
             range_filters: Range filters for numeric fields
             facets: Facet configurations for faceted search
             min_score: Minimum score threshold
-            context: Request context for tracking (created if not provided)
+            context: Request context for tracking (required)
             sort_by: Field name for sorting
             sort_order: Sort order: 'asc' or 'desc'
             debug: Enable debug information output
+            language: Response / field selection language hint (e.g. zh, en)
+            sku_filter_dimension: SKU grouping dimensions for per-SPU variant pick
+            enable_rerank: If None, use ``config.rerank.enabled``; if set, overrides
+                whether the rerank provider is invoked (subject to rerank window).
+            rerank_query_template: Override for rerank query text template; None uses
+                ``config.rerank.rerank_query_template`` (e.g. ``"{query}"``).
+            rerank_doc_template: Override for per-hit document text passed to rerank;
+                None uses ``config.rerank.rerank_doc_template``. Placeholders are
+                resolved in ``search/rerank_client.py``.
  
         Returns:
             SearchResult object with formatted results
@@ -592,7 +589,8 @@ class Searcher:
                 query,
                 tenant_id=tenant_id,
                 generate_vector=enable_embedding,
-                context=context
+                context=context,
+                target_languages=index_langs if enable_translation else [],
             )
             # Store query analysis results in context
             context.store_query_analysis(
@@ -602,7 +600,7 @@ class Searcher:
                 detected_language=parsed_query.detected_language,
                 translations=parsed_query.translations,
                 query_vector=parsed_query.query_vector.tolist() if parsed_query.query_vector is not None else None,
-                domain=parsed_query.domain,
+                domain="default",
                 is_simple_query=True
             )
  
@@ -610,7 +608,6 @@ class Searcher:
                 f"查询解析完成 | 原查询: '{parsed_query.original_query}' | "
                 f"重写后: '{parsed_query.rewritten_query}' | "
                 f"语言: {parsed_query.detected_language} | "
-                f"域: {parsed_query.domain} | "
                 f"向量: {'是' if parsed_query.query_vector is not None else '否'}",
                 extra={'reqid': context.reqid, 'uid': context.uid}
             )
@@ -643,7 +640,8 @@ class Searcher:
                 from_=es_fetch_from,
                 enable_knn=enable_embedding and parsed_query.query_vector is not None,
                 min_score=min_score,
-                parsed_query=parsed_query
+                parsed_query=parsed_query,
+                index_languages=index_langs,
             )
  
             # Add facets for faceted search
@@ -933,7 +931,6 @@ class Searcher:
                         debug_entry["text_score"] = rerank_debug.get("text_score")
                         debug_entry["text_source_score"] = rerank_debug.get("text_source_score")
                         debug_entry["text_translation_score"] = rerank_debug.get("text_translation_score")
-                        debug_entry["text_fallback_score"] = rerank_debug.get("text_fallback_score")
                         debug_entry["text_primary_score"] = rerank_debug.get("text_primary_score")
                         debug_entry["text_support_score"] = rerank_debug.get("text_support_score")
                         debug_entry["knn_score"] = rerank_debug.get("knn_score")
@@ -985,9 +982,6 @@ class Searcher:
                     "rewritten_query": context.query_analysis.rewritten_query,
                     "detected_language": context.query_analysis.detected_language,
                     "translations": context.query_analysis.translations,
-                    "query_text_by_lang": context.get_intermediate_result("query_text_by_lang", {}),
-                    "search_langs": context.get_intermediate_result("search_langs", []),
-                    "supplemental_search_langs": context.get_intermediate_result("supplemental_search_langs", []),
                     "has_vector": context.query_analysis.query_vector is not None,
                     "is_simple_query": context.query_analysis.is_simple_query,
                     "domain": context.query_analysis.domain
@@ -147,7 +147,7 @@ class SuggestionIndexBuilder:
         raw = str(value).strip()
         if not raw:
             return []
-        parts = re.split(r"[,;|/\n\t]+", raw)
+        parts = re.split(r"[，、,;|/\n\t]+", raw)
         out = [p.strip() for p in parts if p and p.strip()]
         if not out:
             return [raw]
@@ -162,7 +162,7 @@ class SuggestionIndexBuilder:
         s = str(raw).strip()
         if not s:
             return []
-        parts = re.split(r"[,;|/\n\t]+", s)
+        parts = re.split(r"[，、,;|/\n\t]+", s)
         out = [p.strip() for p in parts if p and p.strip()]
         return out if out else [s]
  
@@ -73,6 +73,10 @@ class _FakeQueryEncoder:
         return np.array([np.array([0.11, 0.22, 0.33], dtype=np.float32) for _ in sentences], dtype=object)
  
  
+def _tokenizer(text):
+    return str(text).split()
+
+
 class _FakeEmbeddingCache:
     def __init__(self):
         self.store: Dict[str, np.ndarray] = {}
@@ -210,6 +214,7 @@ def test_query_parser_generates_query_vector_with_encoder():
         config=_build_test_config(),
         text_encoder=encoder,
         translator=_FakeTranslator(),
+        tokenizer=_tokenizer,
     )
  
     parsed = parser.parse("red dress", tenant_id="162", generate_vector=True)
@@ -224,6 +229,7 @@ def test_query_parser_skips_query_vector_when_disabled():
         config=_build_test_config(),
         text_encoder=_FakeQueryEncoder(),
         translator=_FakeTranslator(),
+        tokenizer=_tokenizer,
     )
  
     parsed = parser.parse("red dress", tenant_id="162", generate_vector=False)
 from types import SimpleNamespace
+from typing import Any, Dict
  
 import numpy as np
  
@@ -13,6 +14,21 @@ def _builder() -&gt; ESQueryBuilder:
     )
  
  
+def _lexical_multi_match_fields(query_root: Dict[str, Any]) -> list:
+    """Fields from the non-phrase multi_match (bool.should or single clause)."""
+    if "multi_match" in query_root:
+        mm = query_root["multi_match"]
+        if mm.get("type") == "phrase":
+            raise AssertionError("root multi_match is phrase-only")
+        return mm["fields"]
+    for clause in query_root.get("bool", {}).get("should", []):
+        mm = clause.get("multi_match") or {}
+        if mm.get("type") == "phrase":
+            continue
+        return mm["fields"]
+    raise AssertionError("no lexical multi_match in query_root")
+
+
 def test_knn_prefilter_includes_range_filters():
     qb = _builder()
     q = qb.build_query(
@@ -65,21 +81,49 @@ def test_knn_prefilter_not_added_without_filters():
     assert q["knn"]["_name"] == "knn_query"
  
  
-def test_text_query_contains_only_base_translation_and_fallback_named_queries():
+def test_text_query_contains_only_base_and_translation_named_queries():
     qb = _builder()
     parsed_query = SimpleNamespace(
-        query_text_by_lang={"en": "dress", "zh": "连衣裙"},
-        search_langs=["en", "zh"],
+        rewritten_query="dress",
         detected_language="en",
-        source_in_index_languages=False,
-        index_languages=["en", "zh", "fr"],
+        translations={"en": "dress", "zh": "连衣裙"},
     )
  
-    q = qb.build_query(query_text="dress", parsed_query=parsed_query, enable_knn=False)
+    q = qb.build_query(
+        query_text="dress",
+        parsed_query=parsed_query,
+        enable_knn=False,
+        index_languages=["en", "zh", "fr"],
+    )
     should = q["query"]["bool"]["should"]
     names = [clause["multi_match"]["_name"] for clause in should]
  
-    assert names == ["base_query", "base_query_trans_zh", "fallback_original_query_fr"]
+    assert names == [
+        "base_query",
+        "base_query_phrase",
+        "base_query_trans_zh",
+        "base_query_trans_zh_phrase",
+    ]
+
+
+def test_text_query_skips_duplicate_translation_same_as_base():
+    qb = _builder()
+    parsed_query = SimpleNamespace(
+        rewritten_query="dress",
+        detected_language="en",
+        translations={"en": "dress"},
+    )
+
+    q = qb.build_query(
+        query_text="dress",
+        parsed_query=parsed_query,
+        enable_knn=False,
+        index_languages=["en", "zh"],
+    )
+
+    root = q["query"]
+    assert root["bool"]["should"][0]["multi_match"]["_name"] == "base_query"
+    assert root["bool"]["should"][1]["multi_match"]["_name"] == "base_query_phrase"
  
  
 def test_mixed_script_merges_en_fields_into_zh_clause():
@@ -91,22 +135,25 @@ def test_mixed_script_merges_en_fields_into_zh_clause():
         default_language="en",
     )
     parsed_query = SimpleNamespace(
-        query_text_by_lang={"zh": "法式 dress"},
-        search_langs=["zh"],
+        rewritten_query="法式 dress",
         detected_language="zh",
-        source_in_index_languages=True,
-        index_languages=["zh", "en"],
+        translations={},
         contains_chinese=True,
         contains_english=True,
     )
-    q = qb.build_query(query_text="法式 dress", parsed_query=parsed_query, enable_knn=False)
-    fields = q["query"]["multi_match"]["fields"]
+    q = qb.build_query(
+        query_text="法式 dress",
+        parsed_query=parsed_query,
+        enable_knn=False,
+        index_languages=["zh", "en"],
+    )
+    fields = _lexical_multi_match_fields(q["query"])
     bases = {f.split("^", 1)[0] for f in fields}
     assert "title.zh" in bases and "title.en" in bases
     assert "brief.zh" in bases and "brief.en" in bases
-    # Merged supplemental language fields use boost * 0.8 (implicit 1.0 -> ^0.8)
-    assert "title.en^0.8" in fields
-    assert "brief.en^0.8" in fields
+    # Merged supplemental language fields use boost * 0.6 by default.
+    assert "title.en^0.6" in fields
+    assert "brief.en^0.6" in fields
  
  
 def test_mixed_script_merges_zh_fields_into_en_clause():
@@ -118,19 +165,22 @@ def test_mixed_script_merges_zh_fields_into_en_clause():
         default_language="en",
     )
     parsed_query = SimpleNamespace(
-        query_text_by_lang={"en": "red 连衣裙"},
-        search_langs=["en"],
+        rewritten_query="red 连衣裙",
         detected_language="en",
-        source_in_index_languages=True,
-        index_languages=["zh", "en"],
+        translations={},
         contains_chinese=True,
         contains_english=True,
     )
-    q = qb.build_query(query_text="red 连衣裙", parsed_query=parsed_query, enable_knn=False)
-    fields = q["query"]["multi_match"]["fields"]
+    q = qb.build_query(
+        query_text="red 连衣裙",
+        parsed_query=parsed_query,
+        enable_knn=False,
+        index_languages=["zh", "en"],
+    )
+    fields = _lexical_multi_match_fields(q["query"])
     bases = {f.split("^", 1)[0] for f in fields}
     assert "title.en" in bases and "title.zh" in bases
-    assert "title.zh^0.8" in fields
+    assert "title.zh^0.6" in fields
  
  
 def test_mixed_script_merged_fields_scale_configured_boosts():
@@ -143,18 +193,21 @@ def test_mixed_script_merged_fields_scale_configured_boosts():
         default_language="en",
     )
     parsed_query = SimpleNamespace(
-        query_text_by_lang={"zh": "法式 dress"},
-        search_langs=["zh"],
+        rewritten_query="法式 dress",
         detected_language="zh",
-        source_in_index_languages=True,
-        index_languages=["zh", "en"],
+        translations={},
         contains_chinese=True,
         contains_english=True,
     )
-    q = qb.build_query(query_text="法式 dress", parsed_query=parsed_query, enable_knn=False)
-    fields = q["query"]["multi_match"]["fields"]
+    q = qb.build_query(
+        query_text="法式 dress",
+        parsed_query=parsed_query,
+        enable_knn=False,
+        index_languages=["zh", "en"],
+    )
+    fields = _lexical_multi_match_fields(q["query"])
     assert "title.zh^5.0" in fields
-    assert "title.en^8.0" in fields  # 10.0 * 0.8
+    assert "title.en^6.0" in fields  # 10.0 * 0.6
  
  
 def test_mixed_script_does_not_merge_en_when_not_in_index_languages():
@@ -166,16 +219,19 @@ def test_mixed_script_does_not_merge_en_when_not_in_index_languages():
         default_language="zh",
     )
     parsed_query = SimpleNamespace(
-        query_text_by_lang={"zh": "法式 dress"},
-        search_langs=["zh"],
+        rewritten_query="法式 dress",
         detected_language="zh",
-        source_in_index_languages=True,
-        index_languages=["zh"],
+        translations={},
         contains_chinese=True,
         contains_english=True,
     )
-    q = qb.build_query(query_text="法式 dress", parsed_query=parsed_query, enable_knn=False)
-    fields = q["query"]["multi_match"]["fields"]
+    q = qb.build_query(
+        query_text="法式 dress",
+        parsed_query=parsed_query,
+        enable_knn=False,
+        index_languages=["zh"],
+    )
+    fields = _lexical_multi_match_fields(q["query"])
     bases = {f.split("^", 1)[0] for f in fields}
     assert "title.zh" in bases
     assert "title.en" not in bases
@@ -0,0 +1,453 @@
+"""
+ES text recall: base_query (rewritten @ detected_language) + base_query_trans_*.
+
+Covers combinations of query language vs tenant index_languages, translations,
+and mixed Chinese/English queries. Asserts multi_match _name, query text, and
+target language fields (title.{lang}).
+"""
+
+from types import SimpleNamespace
+from typing import Any, Dict, List
+
+import numpy as np
+
+from search.es_query_builder import ESQueryBuilder
+
+
+def _builder_multilingual_title_only(
+    *,
+    default_language: str = "en",
+    mixed_script_scale: float = 0.6,
+) -> ESQueryBuilder:
+    """Minimal builder: only title.{lang} for easy field assertions."""
+    return ESQueryBuilder(
+        match_fields=["title.en^1.0"],
+        multilingual_fields=["title"],
+        shared_fields=[],
+        text_embedding_field="title_embedding",
+        default_language=default_language,
+        mixed_script_merged_field_boost_scale=mixed_script_scale,
+        function_score_config=None,
+    )
+
+
+def _unwrap_inner_query(es_body: Dict[str, Any]) -> Dict[str, Any]:
+    """Navigate bool.must / function_score wrappers to the text recall root."""
+    q = es_body.get("query") or {}
+    if "bool" in q and "must" in q["bool"] and q["bool"]["must"]:
+        q = q["bool"]["must"][0]
+    if "function_score" in q:
+        q = q["function_score"]["query"]
+    return q
+
+
+def _extract_multi_match_clauses(es_body: Dict[str, Any]) -> List[Dict[str, Any]]:
+    inner = _unwrap_inner_query(es_body)
+    if "multi_match" in inner:
+        return [inner["multi_match"]]
+    should = (inner.get("bool") or {}).get("should") or []
+    return [c["multi_match"] for c in should if "multi_match" in c]
+
+
+def _clauses_index(es_body: Dict[str, Any]) -> Dict[str, Dict[str, Any]]:
+    """Map _name -> multi_match dict."""
+    out: Dict[str, Dict[str, Any]] = {}
+    for mm in _extract_multi_match_clauses(es_body):
+        name = mm.get("_name")
+        if name:
+            out[str(name)] = mm
+    return out
+
+
+def _with_phrase(lexical_names: set[str]) -> set[str]:
+    """Each lexical recall clause has a companion ``*_phrase`` multi_match."""
+    return lexical_names | {f"{n}_phrase" for n in lexical_names}
+
+
+def _title_fields(mm: Dict[str, Any]) -> List[str]:
+    fields = mm.get("fields") or []
+    return [f for f in fields if str(f).startswith("title.")]
+
+
+def _has_title_lang(mm: Dict[str, Any], lang: str) -> bool:
+    """True if any field is title.{lang} with optional ^boost suffix."""
+    prefix = f"title.{lang}"
+    for f in mm.get("fields") or []:
+        s = str(f)
+        if s == prefix or s.startswith(prefix + "^"):
+            return True
+    return False
+
+
+def _build(
+    qb: ESQueryBuilder,
+    *,
+    query_text: str,
+    rewritten: str,
+    detected_language: str,
+    translations: Dict[str, str],
+    index_languages: List[str],
+    contains_chinese: bool = False,
+    contains_english: bool = False,
+) -> Dict[str, Any]:
+    parsed = SimpleNamespace(
+        rewritten_query=rewritten,
+        detected_language=detected_language,
+        translations=dict(translations),
+        contains_chinese=contains_chinese,
+        contains_english=contains_english,
+    )
+    return qb.build_query(
+        query_text=query_text,
+        parsed_query=parsed,
+        enable_knn=False,
+        index_languages=index_languages,
+    )
+
+
+# --- 检测语言在 index_languages 内：主召回 + 翻译补召回 ---
+
+
+def test_zh_query_index_zh_en_includes_base_zh_and_trans_en():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="连衣裙",
+        rewritten="连衣裙",
+        detected_language="zh",
+        translations={"en": "dress"},
+        index_languages=["zh", "en"],
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query", "base_query_trans_en"})
+    assert idx["base_query"]["query"] == "连衣裙"
+    assert "title.zh" in _title_fields(idx["base_query"])
+    assert idx["base_query_trans_en"]["query"] == "dress"
+    assert "title.en" in _title_fields(idx["base_query_trans_en"])
+
+
+def test_en_query_index_zh_en_includes_base_en_and_trans_zh():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="dress",
+        rewritten="dress",
+        detected_language="en",
+        translations={"zh": "连衣裙"},
+        index_languages=["en", "zh"],
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query", "base_query_trans_zh"})
+    assert idx["base_query"]["query"] == "dress"
+    assert "title.en" in _title_fields(idx["base_query"])
+    assert idx["base_query_trans_zh"]["query"] == "连衣裙"
+    assert "title.zh" in _title_fields(idx["base_query_trans_zh"])
+
+
+def test_de_query_index_de_en_fr_includes_base_and_two_translations():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="kleid",
+        rewritten="kleid",
+        detected_language="de",
+        translations={"en": "dress", "fr": "robe"},
+        index_languages=["de", "en", "fr"],
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase(
+        {"base_query", "base_query_trans_en", "base_query_trans_fr"}
+    )
+    assert idx["base_query"]["query"] == "kleid"
+    assert "title.de" in _title_fields(idx["base_query"])
+    assert idx["base_query_trans_en"]["query"] == "dress"
+    assert idx["base_query_trans_fr"]["query"] == "robe"
+
+
+# --- 检测语言不在 index_languages：仍有 base（弱）+ 翻译（强） ---
+
+
+def test_de_query_index_only_en_zh_base_on_de_translations_on_target_fields():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="schuh",
+        rewritten="schuh",
+        detected_language="de",
+        translations={"en": "shoe", "zh": "鞋"},
+        index_languages=["en", "zh"],
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase(
+        {"base_query", "base_query_trans_en", "base_query_trans_zh"}
+    )
+    assert idx["base_query"]["query"] == "schuh"
+    assert "title.de" in _title_fields(idx["base_query"])
+    assert "boost" not in idx["base_query"]
+    assert idx["base_query_trans_en"]["query"] == "shoe"
+    assert idx["base_query_trans_en"]["boost"] == qb.translation_boost
+    assert idx["base_query_trans_zh"]["query"] == "鞋"
+    assert idx["base_query_trans_zh"]["boost"] == qb.translation_boost
+
+
+# --- 中英混写：原文在 base_query；翻译子句独立；混写时 base 子句扩列 ---
+
+
+def test_mixed_zh_primary_with_en_translation_merges_en_into_zh_base_clause():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="红色 dress",
+        rewritten="红色 dress",
+        detected_language="zh",
+        translations={"en": "red dress"},
+        index_languages=["zh", "en"],
+        contains_chinese=True,
+        contains_english=True,
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query", "base_query_trans_en"})
+    assert idx["base_query"]["query"] == "红色 dress"
+    assert _has_title_lang(idx["base_query"], "zh") and _has_title_lang(idx["base_query"], "en")
+    assert idx["base_query_trans_en"]["query"] == "red dress"
+    assert _has_title_lang(idx["base_query_trans_en"], "en")
+
+
+def test_mixed_en_primary_with_zh_translation_merges_zh_into_en_base_clause():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="nike 运动鞋",
+        rewritten="nike 运动鞋",
+        detected_language="en",
+        translations={"zh": "耐克运动鞋"},
+        index_languages=["zh", "en"],
+        contains_chinese=True,
+        contains_english=True,
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query", "base_query_trans_zh"})
+    assert idx["base_query"]["query"] == "nike 运动鞋"
+    assert _has_title_lang(idx["base_query"], "en") and _has_title_lang(idx["base_query"], "zh")
+    assert idx["base_query_trans_zh"]["query"] == "耐克运动鞋"
+
+
+def test_mixed_zh_query_index_zh_only_no_en_merge_in_base():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="法式 dress",
+        rewritten="法式 dress",
+        detected_language="zh",
+        translations={},
+        index_languages=["zh"],
+        contains_chinese=True,
+        contains_english=True,
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query"})
+    bases = {f.split("^", 1)[0] for f in _title_fields(idx["base_query"])}
+    assert bases == {"title.zh"}
+
+
+# --- 去重：与 base 同语言同文本的翻译项跳过 ---
+
+
+def test_skips_translation_when_same_lang_and_same_text_as_base():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="NIKE",
+        rewritten="NIKE",
+        detected_language="en",
+        translations={"en": "NIKE", "zh": "耐克"},
+        index_languages=["en", "zh"],
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query", "base_query_trans_zh"})
+
+
+def test_keeps_translation_when_same_text_but_different_lang_than_base():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="NIKE",
+        rewritten="NIKE",
+        detected_language="en",
+        translations={"zh": "NIKE"},
+        index_languages=["en", "zh"],
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query", "base_query_trans_zh"})
+    assert idx["base_query_trans_zh"]["query"] == "NIKE"
+
+
+# --- 翻译 key 规范化、空翻译跳过 ---
+
+
+def test_translation_language_key_is_normalized_case_insensitive():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="dress",
+        rewritten="dress",
+        detected_language="en",
+        translations={"ZH": "连衣裙"},
+        index_languages=["en", "zh"],
+    )
+    idx = _clauses_index(q)
+    assert "base_query_trans_zh" in idx
+    assert idx["base_query_trans_zh"]["query"] == "连衣裙"
+
+
+def test_empty_translation_value_is_skipped():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="dress",
+        rewritten="dress",
+        detected_language="en",
+        translations={"zh": "  ", "fr": "robe"},
+        index_languages=["en", "zh", "fr"],
+    )
+    idx = _clauses_index(q)
+    assert "base_query_trans_zh" not in idx
+    assert "base_query_trans_fr" in idx
+
+
+# --- index_languages 为空：视为「未约束」source_in_index 为 True ---
+
+
+def test_empty_index_languages_treats_source_as_in_index_boosts():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="x",
+        rewritten="x",
+        detected_language="de",
+        translations={"en": "y"},
+        index_languages=[],
+    )
+    idx = _clauses_index(q)
+    assert "boost" not in idx["base_query"]
+    assert idx["base_query_trans_en"]["boost"] == qb.translation_boost
+    assert idx["base_query_phrase"]["boost"] == qb.phrase_match_boost
+    assert idx["base_query_trans_en_phrase"]["boost"] == qb.phrase_match_boost
+
+
+# --- 无翻译：仅 base_query ---
+
+
+def test_no_translations_only_base_query():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="hello",
+        rewritten="hello",
+        detected_language="en",
+        translations={},
+        index_languages=["en", "zh"],
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query"})
+
+
+# --- 与 KNN 同存时仍能解析文本子句（顶层 knn 不影响 query 内结构） ---
+
+
+def test_text_clauses_present_alongside_knn():
+    qb = _builder_multilingual_title_only(default_language="en")
+    parsed = SimpleNamespace(
+        rewritten_query="dress",
+        detected_language="en",
+        translations={"zh": "连衣裙"},
+        contains_chinese=False,
+        contains_english=True,
+    )
+    q = qb.build_query(
+        query_text="dress",
+        query_vector=np.array([0.1, 0.2, 0.3], dtype=np.float32),
+        parsed_query=parsed,
+        enable_knn=True,
+        index_languages=["en", "zh"],
+    )
+    assert "knn" in q
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query", "base_query_trans_zh"})
+
+
+def test_detected_language_unknown_falls_back_to_default_language():
+    """与 LanguageDetector 失败时 QueryConfig.default_language 行为对齐。"""
+    qb = _builder_multilingual_title_only(default_language="en")
+    parsed = SimpleNamespace(
+        rewritten_query="shirt",
+        detected_language="unknown",
+        translations={"zh": "衬衫"},
+        contains_chinese=False,
+        contains_english=True,
+    )
+    q = qb.build_query(
+        query_text="shirt",
+        parsed_query=parsed,
+        enable_knn=False,
+        index_languages=["en", "zh"],
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query", "base_query_trans_zh"})
+    assert idx["base_query"]["query"] == "shirt"
+    assert _has_title_lang(idx["base_query"], "en")
+
+
+def test_ru_query_index_ru_en_includes_base_ru_and_trans_en():
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="платье",
+        rewritten="платье",
+        detected_language="ru",
+        translations={"en": "dress"},
+        index_languages=["ru", "en"],
+    )
+    idx = _clauses_index(q)
+    assert set(idx) == _with_phrase({"base_query", "base_query_trans_en"})
+    assert idx["base_query"]["query"] == "платье"
+    assert _has_title_lang(idx["base_query"], "ru")
+    assert idx["base_query_trans_en"]["query"] == "dress"
+
+
+def test_translation_for_lang_not_listed_in_index_languages_still_generates_clause():
+    """
+    当前实现：凡是 translations 里非空的条目都会生成子句；
+    index_languages 只约束混写扩列，不用于过滤翻译子句。
+    """
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text="dress",
+        rewritten="dress",
+        detected_language="en",
+        translations={"zh": "连衣裙", "de": "Kleid"},
+        index_languages=["en", "zh"],
+    )
+    idx = _clauses_index(q)
+    assert "base_query_trans_de" in idx
+    assert idx["base_query_trans_de"]["query"] == "Kleid"
+    assert _has_title_lang(idx["base_query_trans_de"], "de")
+
+
+def test_mixed_detected_zh_rewrite_differs_from_query_text_uses_rewritten_in_base():
+    """base_query 始终用 rewritten_query，而非仅 query_text。"""
+    qb = _builder_multilingual_title_only(default_language="en")
+    q = _build(
+        qb,
+        query_text=" 红色 ",
+        rewritten="红色连衣裙",
+        detected_language="zh",
+        translations={"en": "red dress"},
+        index_languages=["zh", "en"],
+        contains_chinese=True,
+        contains_english=False,
+    )
+    idx = _clauses_index(q)
+    assert idx["base_query"]["query"] == "红色连衣裙"
+    assert idx["base_query_trans_en"]["query"] == "red dress"
-from types import SimpleNamespace
-
 from config import FunctionScoreConfig, IndexConfig, QueryConfig, RerankConfig, SPUConfig, SearchConfig
 from query.query_parser import QueryParser
  
@@ -9,6 +7,10 @@ class _DummyTranslator:
         return f"{text}-{target_lang}"
  
  
+def _tokenizer(text):
+    return str(text).split()
+
+
 def test_pure_english_word_token_length_and_script():
     assert QueryParser._is_pure_english_word_token("ab") is False
     assert QueryParser._is_pure_english_word_token("abc") is True
@@ -35,59 +37,57 @@ def _build_config() -&gt; SearchConfig:
  
  
 def test_parse_adds_en_fields_for_mixed_chinese_query_with_meaningful_english(monkeypatch):
-    parser = QueryParser(_build_config(), translator=_DummyTranslator())
+    parser = QueryParser(_build_config(), translator=_DummyTranslator(), tokenizer=_tokenizer)
     monkeypatch.setattr(parser.language_detector, "detect", lambda text: "zh")
-    monkeypatch.setattr(
-        "query.query_parser.get_tenant_config_loader",
-        lambda: SimpleNamespace(get_tenant_config=lambda tenant_id: {"index_languages": ["zh", "en"]}),
-        raising=False,
-    )
  
-    result = parser.parse("法式 dress 连衣裙", tenant_id="162", generate_vector=False)
+    result = parser.parse(
+        "法式 dress 连衣裙",
+        tenant_id="162",
+        generate_vector=False,
+        target_languages=["zh", "en"],
+    )
  
     assert result.detected_language == "zh"
     assert result.contains_chinese is True
     assert result.contains_english is True
-    assert "en" in result.search_langs
-    # 翻译在预算内完成时会写入目标语言字段（优于仅用原文做 supplemental 探测）
-    assert result.query_text_by_lang["en"] == "法式 dress 连衣裙-en"
-    assert result.query_text_by_lang["zh"] == "法式 dress 连衣裙"
+    assert result.translations == {"en": "法式 dress 连衣裙-en"}
+    assert result.query_tokens == ["法式", "dress", "连衣裙"]
+    assert not hasattr(result, "query_text_by_lang")
+    assert not hasattr(result, "search_langs")
  
  
 def test_parse_adds_zh_fields_for_english_query_when_cjk_present(monkeypatch):
-    parser = QueryParser(_build_config(), translator=_DummyTranslator())
+    parser = QueryParser(_build_config(), translator=_DummyTranslator(), tokenizer=_tokenizer)
     monkeypatch.setattr(parser.language_detector, "detect", lambda text: "en")
-    monkeypatch.setattr(
-        "query.query_parser.get_tenant_config_loader",
-        lambda: SimpleNamespace(get_tenant_config=lambda tenant_id: {"index_languages": ["en", "zh"]}),
-        raising=False,
-    )
  
-    result = parser.parse("red 连衣裙", tenant_id="0", generate_vector=False)
+    result = parser.parse(
+        "red 连衣裙",
+        tenant_id="0",
+        generate_vector=False,
+        target_languages=["en", "zh"],
+    )
  
     assert result.detected_language == "en"
     assert result.contains_chinese is True
     assert result.contains_english is True
-    assert "zh" in result.search_langs
-    assert result.query_text_by_lang["zh"] == "red 连衣裙-zh"
-    assert result.query_text_by_lang["en"] == "red 连衣裙"
+    assert result.translations == {"zh": "red 连衣裙-zh"}
+    assert result.query_tokens == ["red", "连衣裙"]
  
  
 def test_parse_waits_for_translation_when_source_in_index_languages(monkeypatch):
     """en 在 index_languages 内时仍应等待并采纳 en->zh 翻译结果（与向量共用预算）。"""
-    parser = QueryParser(_build_config(), translator=_DummyTranslator())
+    parser = QueryParser(_build_config(), translator=_DummyTranslator(), tokenizer=_tokenizer)
     monkeypatch.setattr(parser.language_detector, "detect", lambda text: "en")
-    monkeypatch.setattr(
-        "query.query_parser.get_tenant_config_loader",
-        lambda: SimpleNamespace(get_tenant_config=lambda tenant_id: {"index_languages": ["en", "zh"]}),
-        raising=False,
-    )
  
-    result = parser.parse("off shoulder top", tenant_id="0", generate_vector=False)
+    result = parser.parse(
+        "off shoulder top",
+        tenant_id="0",
+        generate_vector=False,
+        target_languages=["en", "zh"],
+    )
  
     assert result.detected_language == "en"
     assert result.contains_chinese is False
     assert result.contains_english is True
     assert result.translations.get("zh") == "off shoulder top-zh"
-    assert result.query_text_by_lang.get("zh") == "off shoulder top-zh"
-    assert result.source_in_index_languages is True
+    assert not hasattr(result, "source_in_index_languages")
@@ -11,7 +11,6 @@ def test_fuse_scores_and_resort_aggregates_text_components_and_keeps_rerank_prim
             "matched_queries": {
                 "base_query": 2.4,
                 "base_query_trans_zh": 1.8,
-                "fallback_original_query_zh": 1.2,
                 "knn_query": 0.8,
             },
         },
@@ -27,7 +26,7 @@ def test_fuse_scores_and_resort_aggregates_text_components_and_keeps_rerank_prim
  
     debug = fuse_scores_and_resort(hits, [0.9, 0.7])
  
-    expected_text_1 = 2.4 + 0.25 * ((0.8 * 1.8) + (0.55 * 1.2))
+    expected_text_1 = 2.4 + 0.25 * (0.8 * 1.8)
     expected_fused_1 = (0.9 + 0.00001) * ((expected_text_1 + 0.1) ** 0.35) * ((0.8 + 0.6) ** 0.2)
     expected_fused_2 = (0.7 + 0.00001) * ((9.0 + 0.1) ** 0.35) * ((0.2 + 0.6) ** 0.2)
  
@@ -38,7 +37,6 @@ def test_fuse_scores_and_resort_aggregates_text_components_and_keeps_rerank_prim
     assert isclose(by_id["2"]["_fused_score"], expected_fused_2, rel_tol=1e-9)
     assert debug[0]["text_source_score"] == 2.4
     assert debug[0]["text_translation_score"] == 1.8
-    assert debug[0]["text_fallback_score"] == 1.2
     assert debug[0]["knn_score"] == 0.8
     assert [hit["_id"] for hit in hits] == ["2", "1"]
  
@@ -43,7 +43,14 @@ class _FakeParsedQuery:
  
  
 class _FakeQueryParser:
-    def parse(self, query: str, tenant_id: str, generate_vector: bool, context: Any):
+    def parse(
+        self,
+        query: str,
+        tenant_id: str,
+        generate_vector: bool,
+        context: Any,
+        target_languages: Any = None,
+    ):
         return _FakeParsedQuery(
             original_query=query,
             query_normalized=query,
@@ -191,6 +198,66 @@ def test_config_loader_rerank_enabled_defaults_true(tmp_path: Path):
         "field_boosts": {"title.en": 3.0},
         "indexes": [{"name": "default", "label": "default", "fields": ["title.en"]}],
         "query_config": {"supported_languages": ["en"], "default_language": "en"},
+        "services": {
+            "translation": {
+                "service_url": "http://localhost:6005",
+                "timeout_sec": 3.0,
+                "default_model": "dummy-model",
+                "default_scene": "general",
+                "cache": {
+                    "ttl_seconds": 60,
+                    "sliding_expiration": True,
+                },
+                "capabilities": {
+                    "dummy-model": {
+                        "enabled": True,
+                        "backend": "llm",
+                        "use_cache": True,
+                        "model": "dummy-model",
+                        "base_url": "http://localhost:6005/v1",
+                        "timeout_sec": 3.0,
+                    }
+                },
+            },
+            "embedding": {
+                "provider": "http",
+                "providers": {
+                    "http": {
+                        "text_base_url": "http://localhost:6005",
+                        "image_base_url": "http://localhost:6008",
+                    }
+                },
+                "backend": "tei",
+                "backends": {
+                    "tei": {
+                        "base_url": "http://localhost:8080",
+                        "timeout_sec": 3.0,
+                        "model_id": "dummy-embedding-model",
+                    }
+                },
+            },
+            "rerank": {
+                "provider": "http",
+                "providers": {
+                    "http": {
+                        "base_url": "http://localhost:6007",
+                        "service_url": "http://localhost:6007/rerank",
+                    }
+                },
+                "backend": "bge",
+                "backends": {
+                    "bge": {
+                        "model_name": "dummy-rerank-model",
+                        "device": "cpu",
+                        "use_fp16": False,
+                        "batch_size": 8,
+                        "max_length": 128,
+                        "cache_dir": "./model_cache",
+                        "enable_warmup": False,
+                    }
+                },
+            },
+        },
         "spu_config": {"enabled": False},
         "function_score": {"score_mode": "sum", "boost_mode": "multiply", "functions": []},
         "rerank": {"rerank_window": 384},
@@ -354,7 +421,14 @@ def test_searcher_promotes_sku_when_option1_matches_translated_query(monkeypatch
     class _TranslatedQueryParser:
         text_encoder = None
  
-        def parse(self, query: str, tenant_id: str, generate_vector: bool, context: Any):
+        def parse(
+            self,
+            query: str,
+            tenant_id: str,
+            generate_vector: bool,
+            context: Any,
+            target_languages: Any = None,
+        ):
             return _FakeParsedQuery(
                 original_query=query,
                 query_normalized=query,
@@ -407,15 +481,22 @@ def test_searcher_promotes_sku_by_embedding_when_query_has_no_direct_option_matc
     encoder = _FakeTextEncoder(
         {
             "linen summer dress": [0.8, 0.2],
-            "color:Red": [1.0, 0.0],
-            "color:Blue": [0.0, 1.0],
+            "color:red": [1.0, 0.0],
+            "color:blue": [0.0, 1.0],
         }
     )
  
     class _EmbeddingQueryParser:
         text_encoder = encoder
  
-        def parse(self, query: str, tenant_id: str, generate_vector: bool, context: Any):
+        def parse(
+            self,
+            query: str,
+            tenant_id: str,
+            generate_vector: bool,
+            context: Any,
+            target_languages: Any = None,
+        ):
             return _FakeParsedQuery(
                 original_query=query,
                 query_normalized=query,
 import logging
  
+import pytest
+
 from translation.cache import TranslationCache
 from translation.logging_utils import (
     TranslationRequestFilter,
@@ -7,6 +9,7 @@ from translation.logging_utils import (
     reset_translation_request_id,
 )
 from translation.service import TranslationService
+from translation.settings import build_translation_config, translation_cache_probe_models
  
  
 class _FakeCache:
@@ -16,7 +19,8 @@ class _FakeCache:
         self.get_calls = []
         self.set_calls = []
  
-    def get(self, *, model, target_lang, source_text):
+    def get(self, *, model, target_lang, source_text, log_lookup=True):
+        del log_lookup
         self.get_calls.append((model, target_lang, source_text))
         return self.storage.get((model, target_lang, source_text))
  
@@ -191,3 +195,262 @@ def test_translation_route_log_focuses_on_routing_decision(monkeypatch, caplog):
     assert route_messages == [
         "Translation route | backend=llm request_type=single use_cache=True cache_available=False"
     ]
+
+
+def test_translation_cache_probe_models_order():
+    cfg = {"cache": {"model_quality_tiers": {"low": 10, "high": 50, "mid": 30}}}
+    assert translation_cache_probe_models(cfg, "low") == ["high", "mid", "low"]
+    assert translation_cache_probe_models(cfg, "mid") == ["high", "mid"]
+    assert translation_cache_probe_models(cfg, "high") == ["high"]
+    assert translation_cache_probe_models(cfg, "unknown") == ["unknown"]
+
+
+def test_translation_cache_probe_models_respects_enable_switch():
+    cfg = {
+        "cache": {
+            "enable_model_quality_tier_cache": False,
+            "model_quality_tiers": {"peer-a": 50, "peer-b": 50, "top": 100},
+        }
+    }
+    assert translation_cache_probe_models(cfg, "peer-a") == ["peer-a"]
+
+
+def test_translation_cache_probe_models_same_tier_included():
+    """Same numeric tier: all peers are probed (higher tier first, then name order)."""
+    cfg = {"cache": {"model_quality_tiers": {"peer-a": 50, "peer-b": 50, "top": 100}}}
+    assert translation_cache_probe_models(cfg, "peer-a") == ["top", "peer-a", "peer-b"]
+    assert translation_cache_probe_models(cfg, "peer-b") == ["top", "peer-b", "peer-a"]
+
+
+def test_model_quality_tiers_unknown_capability_raises():
+    with pytest.raises(ValueError, match="unknown capability"):
+        build_translation_config(
+            {
+                "service_url": "http://127.0.0.1:6006",
+                "timeout_sec": 10.0,
+                "default_model": "llm",
+                "default_scene": "general",
+                "cache": {
+                    "ttl_seconds": 60,
+                    "sliding_expiration": True,
+                    "model_quality_tiers": {"ghost": 1},
+                },
+                "capabilities": {
+                    "llm": {
+                        "enabled": True,
+                        "backend": "llm",
+                        "model": "dummy-llm",
+                        "base_url": "https://example.com",
+                        "timeout_sec": 10.0,
+                        "use_cache": True,
+                    }
+                },
+            }
+        )
+
+
+def test_tiered_cache_reuses_higher_tier_entry(monkeypatch):
+    monkeypatch.setattr(TranslationCache, "_init_redis_client", staticmethod(lambda: None))
+    translate_calls = []
+
+    def _fake_create_backend(self, *, name, backend_type, cfg):
+        del self, backend_type, cfg
+
+        class _Backend:
+            model = name
+
+            @property
+            def supports_batch(self):
+                return True
+
+            def translate(self, text, target_lang, source_lang=None, scene=None):
+                del target_lang, source_lang, scene
+                translate_calls.append((name, text))
+                if isinstance(text, list):
+                    return [f"{name}:{item}" for item in text]
+                return f"{name}:{text}"
+
+        return _Backend()
+
+    monkeypatch.setattr(TranslationService, "_create_backend", _fake_create_backend)
+    config = {
+        "service_url": "http://127.0.0.1:6006",
+        "timeout_sec": 10.0,
+        "default_model": "opus-mt-zh-en",
+        "default_scene": "general",
+        "capabilities": {
+            "deepl": {
+                "enabled": True,
+                "backend": "deepl",
+                "api_url": "https://api.deepl.com/v2/translate",
+                "timeout_sec": 10.0,
+                "use_cache": True,
+            },
+            "opus-mt-zh-en": {
+                "enabled": True,
+                "backend": "local_marian",
+                "model_id": "dummy",
+                "model_dir": "dummy",
+                "device": "cpu",
+                "torch_dtype": "float32",
+                "batch_size": 8,
+                "max_input_length": 16,
+                "max_new_tokens": 16,
+                "num_beams": 1,
+                "use_cache": True,
+            },
+        },
+        "cache": {
+            "ttl_seconds": 60,
+            "sliding_expiration": True,
+            "model_quality_tiers": {"deepl": 100, "opus-mt-zh-en": 40},
+        },
+    }
+
+    service = TranslationService(config)
+    fake_cache = _FakeCache()
+    fake_cache.storage[("deepl", "en", "商品标题")] = "from-deepl"
+    service._translation_cache = fake_cache
+
+    out = service.translate("商品标题", target_lang="en", source_lang="zh", model="opus-mt-zh-en")
+    assert out == "from-deepl"
+    assert translate_calls == []
+    assert fake_cache.get_calls == [("deepl", "en", "商品标题")]
+
+
+def test_tiered_cache_reuses_same_tier_peer(monkeypatch):
+    """Model A may use cache written under model B when both share the same tier."""
+    monkeypatch.setattr(TranslationCache, "_init_redis_client", staticmethod(lambda: None))
+    translate_calls = []
+
+    def _fake_create_backend(self, *, name, backend_type, cfg):
+        del self, backend_type, cfg
+
+        class _Backend:
+            model = name
+
+            @property
+            def supports_batch(self):
+                return True
+
+            def translate(self, text, target_lang, source_lang=None, scene=None):
+                del target_lang, source_lang, scene
+                translate_calls.append((name, text))
+                if isinstance(text, list):
+                    return [f"{name}:{item}" for item in text]
+                return f"{name}:{text}"
+
+        return _Backend()
+
+    monkeypatch.setattr(TranslationService, "_create_backend", _fake_create_backend)
+    marian_cap = {
+        "enabled": True,
+        "backend": "local_marian",
+        "model_id": "dummy",
+        "model_dir": "dummy",
+        "device": "cpu",
+        "torch_dtype": "float32",
+        "batch_size": 8,
+        "max_input_length": 16,
+        "max_new_tokens": 16,
+        "num_beams": 1,
+        "use_cache": True,
+    }
+    config = {
+        "service_url": "http://127.0.0.1:6006",
+        "timeout_sec": 10.0,
+        "default_model": "opus-mt-en-zh",
+        "default_scene": "general",
+        "capabilities": {
+            "opus-mt-zh-en": dict(marian_cap),
+            "opus-mt-en-zh": dict(marian_cap),
+        },
+        "cache": {
+            "ttl_seconds": 60,
+            "sliding_expiration": True,
+            "model_quality_tiers": {"opus-mt-zh-en": 50, "opus-mt-en-zh": 50},
+        },
+    }
+
+    service = TranslationService(config)
+    fake_cache = _FakeCache()
+    fake_cache.storage[("opus-mt-zh-en", "en", "hello")] = "from-zh-en"
+    service._translation_cache = fake_cache
+
+    out = service.translate("hello", target_lang="en", source_lang="zh", model="opus-mt-en-zh")
+    assert out == "from-zh-en"
+    assert translate_calls == []
+    assert fake_cache.get_calls == [
+        ("opus-mt-en-zh", "en", "hello"),
+        ("opus-mt-zh-en", "en", "hello"),
+    ]
+
+
+def test_tiered_cache_switch_off_uses_exact_model_only(monkeypatch):
+    monkeypatch.setattr(TranslationCache, "_init_redis_client", staticmethod(lambda: None))
+    translate_calls = []
+
+    def _fake_create_backend(self, *, name, backend_type, cfg):
+        del self, backend_type, cfg
+
+        class _Backend:
+            model = name
+
+            @property
+            def supports_batch(self):
+                return True
+
+            def translate(self, text, target_lang, source_lang=None, scene=None):
+                del target_lang, source_lang, scene
+                translate_calls.append((name, text))
+                if isinstance(text, list):
+                    return [f"{name}:{item}" for item in text]
+                return f"{name}:{text}"
+
+        return _Backend()
+
+    monkeypatch.setattr(TranslationService, "_create_backend", _fake_create_backend)
+    config = {
+        "service_url": "http://127.0.0.1:6006",
+        "timeout_sec": 10.0,
+        "default_model": "opus-mt-zh-en",
+        "default_scene": "general",
+        "capabilities": {
+            "deepl": {
+                "enabled": True,
+                "backend": "deepl",
+                "api_url": "https://api.deepl.com/v2/translate",
+                "timeout_sec": 10.0,
+                "use_cache": True,
+            },
+            "opus-mt-zh-en": {
+                "enabled": True,
+                "backend": "local_marian",
+                "model_id": "dummy",
+                "model_dir": "dummy",
+                "device": "cpu",
+                "torch_dtype": "float32",
+                "batch_size": 8,
+                "max_input_length": 16,
+                "max_new_tokens": 16,
+                "num_beams": 1,
+                "use_cache": True,
+            },
+        },
+        "cache": {
+            "ttl_seconds": 60,
+            "sliding_expiration": True,
+            "enable_model_quality_tier_cache": False,
+            "model_quality_tiers": {"deepl": 100, "opus-mt-zh-en": 40},
+        },
+    }
+
+    service = TranslationService(config)
+    fake_cache = _FakeCache()
+    fake_cache.storage[("deepl", "en", "商品标题")] = "from-deepl"
+    service._translation_cache = fake_cache
+
+    out = service.translate("商品标题", target_lang="en", source_lang="zh", model="opus-mt-zh-en")
+    assert out == "opus-mt-zh-en:商品标题"
+    assert translate_calls == [("opus-mt-zh-en", "商品标题")]
+    assert fake_cache.get_calls == [("opus-mt-zh-en", "en", "商品标题")]
@@ -36,7 +36,13 @@ class TranslationCache:
         digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
         return f"trans:{normalized_model}:{normalized_target_lang}:{text_prefix}{digest}"
  
-    def get(self, *, model: str, target_lang: str, source_text: str) -> Optional[str]:
+    def get(
+        self,
+        *,
+        model: str,
+        target_lang: str,
+        source_text: str
+    ) -> Optional[str]:
         if self.redis_client is None:
             return None
         key = self.build_key(model=model, target_lang=target_lang, source_text=source_text)
@@ -3,7 +3,7 @@
 from __future__ import annotations
  
 import logging
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Tuple
  
 from config.loader import get_app_config
 from config.schema import AppConfig
@@ -15,6 +15,7 @@ from translation.settings import (
     get_translation_capability,
     normalize_translation_model,
     normalize_translation_scene,
+    translation_cache_probe_models,
 )
  
 logger = logging.getLogger(__name__)
@@ -247,7 +248,11 @@ class TranslationService:
     ) -> Optional[str]:
         if not text.strip():
             return text
-        cached = self._translation_cache.get(model=model, target_lang=target_lang, source_text=text)
+        cached, _served = self._tiered_cache_get(
+            request_model=model,
+            target_lang=target_lang,
+            source_text=text,
+        )
         if cached is not None:
             logger.info(
                 "Translation cache served | request_type=single text_len=%s",
@@ -279,6 +284,30 @@ class TranslationService:
             )
         return translated
  
+    def _tiered_cache_get(
+        self,
+        *,
+        request_model: str,
+        target_lang: str,
+        source_text: str,
+    ) -> Tuple[Optional[str], Optional[str]]:
+        """Redis lookup: cache from higher-tier or **same-tier** models may satisfy A.
+
+        Lower-tier entries are never read. Returns ``(translated, served_model)``.
+        """
+        probe_models = translation_cache_probe_models(self.config, request_model)
+
+        for probe_model in probe_models:
+            hit = self._translation_cache.get(
+                model=probe_model,
+                target_lang=target_lang,
+                source_text=source_text,
+            )
+            if hit is not None:
+                return hit, probe_model
+
+        return None, None
+
     def _translate_batch_with_cache(
         self,
         *,
@@ -300,8 +329,8 @@ class TranslationService:
             if not normalized_text.strip():
                 results[idx] = normalized_text
                 continue
-            cached = self._translation_cache.get(
-                model=model,
+            cached, _served = self._tiered_cache_get(
+                request_model=model,
                 target_lang=target_lang,
                 source_text=normalized_text,
             )
@@ -2,7 +2,7 @@
  
 from __future__ import annotations
  
-from typing import Any, Dict, List, Mapping, Optional
+from typing import Any, Dict, List, Mapping, Optional, Tuple
  
 from translation.scenes import normalize_scene_name
  
@@ -38,6 +38,7 @@ def build_translation_config(raw_cfg: Mapping[str, Any]) -&gt; TranslationConfig:
     if not get_enabled_translation_models(config):
         raise ValueError("At least one translation capability must be enabled")
  
+    _validate_model_quality_tiers(config)
     return config
  
  
@@ -86,18 +87,107 @@ def get_translation_cache(config: Mapping[str, Any]) -&gt; Dict[str, Any]:
     return dict(cache)
  
  
+def translation_cache_probe_models(config: Mapping[str, Any], request_model: str) -> List[str]:
+    """Redis cache key models to try.
+
+    Sort order: (1) **tier** descending (higher quality first); (2) within the same tier,
+    the **request model** before other peers; (3) remaining ties by model name.
+
+    For a request to model A with tier T, probes every configured model whose tier is
+    **greater than or equal to** T. Lower tiers are never used.
+
+    When ``enable_model_quality_tier_cache`` is false, only the request model is probed.
+
+    When ``model_quality_tiers`` is empty or ``request_model`` is not listed, only the
+    request model is probed (legacy exact-match behavior).
+    """
+    rm = str(request_model or "").strip().lower()
+    cache = config.get("cache")
+    if not isinstance(cache, Mapping):
+        return [rm]
+    if not bool(cache.get("enable_model_quality_tier_cache", True)):
+        return [rm]
+    tiers = cache.get("model_quality_tiers")
+    if not isinstance(tiers, Mapping) or not tiers:
+        return [rm]
+    if rm not in tiers:
+        return [rm]
+    threshold = int(tiers[rm])
+    scored: List[Tuple[int, str]] = []
+    for name, tier_val in tiers.items():
+        n = str(name).strip().lower()
+        t = int(tier_val)
+        if t >= threshold:
+            scored.append((t, n))
+    scored.sort(
+        key=lambda item: (
+            -item[0],
+            0 if item[1] == rm else 1,
+            item[1],
+        )
+    )
+    out: List[str] = []
+    seen: set[str] = set()
+    for _t, n in scored:
+        if n not in seen:
+            seen.add(n)
+            out.append(n)
+    return out
+
+
 def _build_cache_config(raw_cache: Any) -> Dict[str, Any]:
     if not isinstance(raw_cache, Mapping):
         raise ValueError("services.translation.cache must be a mapping")
+    if "enable_model_quality_tier_cache" in raw_cache:
+        enable_tier_cache = _require_bool(
+            raw_cache["enable_model_quality_tier_cache"],
+            "services.translation.cache.enable_model_quality_tier_cache",
+        )
+    else:
+        enable_tier_cache = True
     return {
         "ttl_seconds": _require_positive_int(raw_cache.get("ttl_seconds"), "services.translation.cache.ttl_seconds"),
         "sliding_expiration": _require_bool(
             raw_cache.get("sliding_expiration"),
             "services.translation.cache.sliding_expiration",
         ),
+        "enable_model_quality_tier_cache": enable_tier_cache,
+        "model_quality_tiers": _build_model_quality_tiers(raw_cache.get("model_quality_tiers")),
     }
  
  
+def _build_model_quality_tiers(raw: Any) -> Dict[str, int]:
+    if raw is None:
+        return {}
+    if not isinstance(raw, Mapping):
+        raise ValueError("services.translation.cache.model_quality_tiers must be a mapping")
+    resolved: Dict[str, int] = {}
+    for name, tier_val in raw.items():
+        cap = _require_string(name, "services.translation.cache.model_quality_tiers key").lower()
+        field = f"services.translation.cache.model_quality_tiers.{cap}"
+        resolved[cap] = _require_non_negative_int(tier_val, field)
+    return resolved
+
+
+def _validate_model_quality_tiers(config: TranslationConfig) -> None:
+    tiers = config["cache"].get("model_quality_tiers")
+    if not isinstance(tiers, Mapping) or not tiers:
+        return
+    caps = config["capabilities"]
+    for name in tiers:
+        if name not in caps:
+            raise ValueError(
+                f"services.translation.cache.model_quality_tiers references unknown capability '{name}'"
+            )
+
+
+def _require_non_negative_int(value: Any, field_name: str) -> int:
+    parsed = _require_int(value, field_name)
+    if parsed < 0:
+        raise ValueError(f"{field_name} must be >= 0")
+    return parsed
+
+
 def _build_capabilities(raw_capabilities: Any) -> Dict[str, Dict[str, Any]]:
     if not isinstance(raw_capabilities, Mapping):
         raise ValueError("services.translation.capabilities must be a mapping")