tangwang · tangwang · tangwang · tangwang · tangwang · tangwang
Showing 45 changed files Show diff stats
config/config.yaml
config/dictionaries/product_title_exclusion.tsv
config/dictionaries/style_intent_color.csv
config/dictionaries/style_intent_size.csv
config/loader.py
config/schema.py
config/services_config.py
perf_reports/reranker_vllm_instruction/2026-03-25/RESULTS.md
query/style_intent.py
requirements_reranker_base.txt
requirements_reranker_bge.txt
requirements_reranker_dashscope.txt
requirements_reranker_qwen3_gguf.txt
requirements_reranker_qwen3_gguf_06b.txt
requirements_reranker_qwen3_transformers.txt
requirements_reranker_qwen3_transformers_packed.txt
requirements_reranker_qwen3_vllm.txt
requirements_reranker_qwen3_vllm_score.txt
requirements_reranker_service.txt
reranker/DEPLOYMENT_AND_TUNING.md
@@ -114,10 +114,11 @@ query_config:
   # 查询解析阶段：翻译与 query 向量并发执行，共用同一等待预算（毫秒）。
   # 检测语言已在租户 index_languages 内：较短；不在索引语言内：较长（翻译对召回更关键）。
   translation_embedding_wait_budget_ms_source_in_index: 500 # 80
-  translation_embedding_wait_budget_ms_source_not_in_index: 500 #200
+  translation_embedding_wait_budget_ms_source_not_in_index: 700 #200
  
   style_intent:
     enabled: true
+    selected_sku_boost: 1.2
     color_dictionary_path: "config/dictionaries/style_intent_color.csv"
     size_dictionary_path: "config/dictionaries/style_intent_size.csv"
     dimension_aliases:
@@ -230,7 +231,7 @@ rerank:
     text_bias: 0.1
     text_exponent: 0.35
     knn_bias: 0.6
-    knn_exponent: 0.2
+    knn_exponent: 0.0
  
 # 可扩展服务/provider 注册表（单一配置源）
 services:
@@ -380,7 +381,7 @@ services:
       max_docs: 1000
       normalize: true
     # 服务内后端（reranker 进程启动时读取）
-    backend: "bge"  # bge | qwen3_vllm | qwen3_transformers | dashscope_rerank
+    backend: "qwen3_vllm"  # bge | qwen3_vllm | qwen3_vllm_score | qwen3_transformers | qwen3_transformers_packed | qwen3_gguf | qwen3_gguf_06b | dashscope_rerank
     backends:
       bge:
         model_name: "BAAI/bge-reranker-v2-m3"
@@ -401,6 +402,9 @@ services:
         enforce_eager: false
         infer_batch_size: 100
         sort_by_doc_length: true
+        # 与 reranker/backends/qwen3_vllm.py 一致：standard=_format_instruction__standard（固定 yes/no system）；compact=_format_instruction（instruction 作 system 且 user 内重复 Instruct）
+        # instruction_format: compact
+        instruction_format: compact
         # instruction: "Given a query, score the product for relevance"
         # "rank products by given query" 比 “Given a query, score the product for relevance” 更好点
         # instruction: "rank products by given query, category match first" 
@@ -410,6 +414,32 @@ services:
         # instruction: "Relevance ranking: category & style match first"
         # instruction: "Score product relevance by query with category & style match prioritized"
         instruction: "Rank products by query with category & style match prioritized"
+      # vLLM LLM.score()（跨编码打分）。独立高性能环境 .venv-reranker-score（vllm 0.18 固定版）：./scripts/setup_reranker_venv.sh qwen3_vllm_score
+      # 与 qwen3_vllm 可共用同一 model_name / HF 缓存；venv 分离以便升级 vLLM 而不影响 generate 后端。
+      qwen3_vllm_score:
+        model_name: "Qwen/Qwen3-Reranker-0.6B"
+        # 官方 Hub 原版需 true；若改用已转换的 seq-cls 权重（如 tomaarsen/...-seq-cls）则设为 false
+        use_original_qwen3_hf_overrides: true
+        # vLLM 0.18：算力 < 8（如 T4）默认自动用 TRITON_ATTN；Ampere+ 可省略或设 auto。也可设环境变量 RERANK_VLLM_ATTENTION_BACKEND
+        # vllm_attention_backend: "auto"
+        # 可选：与 vLLM 对齐；一般保持 auto
+        # vllm_runner: "auto"
+        # vllm_convert: "auto"
+        # 可选：在 use_original_qwen3_hf_overrides 为 true 时与内置 overrides 合并
+        # hf_overrides: {}
+        engine: "vllm"
+        max_model_len: 160
+        tensor_parallel_size: 1
+        gpu_memory_utilization: 0.20
+        dtype: "float16"
+        enable_prefix_caching: true
+        enforce_eager: false
+        infer_batch_size: 100
+        sort_by_doc_length: true
+        # 与 qwen3_vllm 同名项语义一致；默认 standard 与 vLLM 官方 Qwen3 reranker 前缀一致
+        # instruction_format: compact
+        instruction_format: standard
+        instruction: "Rank products by query with category & style match prioritized"
       qwen3_transformers:
         model_name: "Qwen/Qwen3-Reranker-0.6B"
         instruction: "rank products by given query"
@@ -419,6 +449,68 @@ services:
         use_fp16: true
         # sdpa：默认无需 flash-attn；若已安装 flash_attn 可改为 flash_attention_2
         attn_implementation: "sdpa"
+      # Packed Transformers backend: shared query prefix + custom position_ids/attention_mask.
+      # For 1 query + many short docs (for example 400 product titles), this usually reduces
+      # repeated prefix work and padding waste compared with pairwise batching.
+      qwen3_transformers_packed:
+        model_name: "Qwen/Qwen3-Reranker-0.6B"
+        instruction: "Rank products by query with category & style match prioritized"
+        max_model_len: 4096
+        max_doc_len: 160
+        max_docs_per_pack: 0
+        use_fp16: true
+        sort_by_doc_length: true
+        # Packed mode relies on a custom 4D attention mask. "eager" is the safest default.
+        # If your torch/transformers stack validates it, you can benchmark "sdpa".
+        attn_implementation: "eager"
+      qwen3_gguf:
+        repo_id: "DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF"
+        filename: "*Q8_0.gguf"
+        cache_dir: "./model_cache"
+        local_dir: "./models/reranker/qwen3-reranker-4b-gguf"
+        instruction: "Rank products by query with category & style match prioritized"
+        # T4 16GB / 性能优先配置：全量层 offload，实测比保守配置明显更快
+        n_ctx: 512
+        n_batch: 512
+        n_ubatch: 512
+        n_gpu_layers: 999
+        main_gpu: 0
+        n_threads: 2
+        n_threads_batch: 4
+        flash_attn: true
+        offload_kqv: true
+        use_mmap: true
+        use_mlock: false
+        infer_batch_size: 8
+        sort_by_doc_length: true
+        length_sort_mode: "char"
+        enable_warmup: true
+        verbose: false
+      qwen3_gguf_06b:
+        repo_id: "ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF"
+        filename: "qwen3-reranker-0.6b-q8_0.gguf"
+        cache_dir: "./model_cache"
+        local_dir: "./models/reranker/qwen3-reranker-0.6b-q8_0-gguf"
+        instruction: "Rank products by query with category & style match prioritized"
+        # 0.6B GGUF / online rerank baseline:
+        # 实测 400 titles 单请求约 265s，因此它更适合作为低显存功能后备，不适合在线低延迟主路由。
+        n_ctx: 256
+        n_batch: 256
+        n_ubatch: 256
+        n_gpu_layers: 999
+        main_gpu: 0
+        n_threads: 2
+        n_threads_batch: 4
+        flash_attn: true
+        offload_kqv: true
+        use_mmap: true
+        use_mlock: false
+        infer_batch_size: 32
+        sort_by_doc_length: true
+        length_sort_mode: "char"
+        reuse_query_state: false
+        enable_warmup: true
+        verbose: false
       dashscope_rerank:
         model_name: "qwen3-rerank"
         # 按地域选择 endpoint:
 # zh triggers	en triggers	zh title exclusions	en title exclusions
-修身	fitted	宽松	loose,relaxed,oversized,baggy,slouchy
+修身,紧身	fitted,tight	宽松	loose,relaxed,oversized,baggy,slouchy
+宽松	loose,relaxed,oversized,baggy,slouchy	修身,紧身	fitted,tight
-black,black,blk,黑,黑色
-white,white,wht,白,白色
-red,red,reddish,红,红色
-blue,blue,blu,蓝,蓝色
-green,green,grn,绿,绿色
-yellow,yellow,ylw,黄,黄色
-pink,pink,粉,粉色
-purple,purple,violet,紫,紫色
-gray,gray,grey,灰,灰色
-brown,brown,棕,棕色,咖啡色
-beige,beige,khaki,米色,卡其色
-navy,navy,navy blue,藏青,藏蓝,深蓝
-silver,silver,银,银色
-gold,gold,金,金色
-orange,orange,橙,橙色
+"black,blk","黑,黑色","black"
+"white,wht","白,白色","white"
+"red,reddish","红,红色","red"
+"blue,blu","蓝,蓝色","blue"
+"green,grn","绿,绿色","green"
+"yellow,ylw","黄,黄色","yellow"
+"pink","粉,粉色","pink"
+"purple,violet","紫,紫色","purple"
+"gray,grey","灰,灰色","gray,grey"
+"brown","棕,棕色,咖啡色","brown"
+"beige,khaki","米色,卡其色","beige,khaki"
+"navy,navy blue","藏青,藏蓝,深蓝","navy"
+"silver","银,银色","silver"
+"gold","金,金色","gold"
+"orange","橙,橙色","orange"
-xs,xs,extra small,x-small,加小码
-s,s,small,小码,小号
-m,m,medium,中码,中号
-l,l,large,大码,大号
-xl,xl,x-large,extra large,加大码
-xxl,xxl,2xl,xx-large,双加大码
-xxxl,xxxl,3xl,xxx-large,三加大码
-one size,one size,onesize,free size,均码
+"xs,extra small,x-small","加小码","xs,extra small,x-small"
+"s,small","小码,小号","s,small"
+"m,medium","中码,中号","m,medium"
+"l,large","大码,大号","l,large"
+"xl,x-large,extra large","加大码","xl,x-large,extra large"
+"xxl,2xl,xx-large","双加大码","xxl,2xl,xx-large"
+"xxxl,3xl,xxx-large","三加大码","xxxl,3xl,xxx-large"
@@ -10,6 +10,7 @@ from __future__ import annotations
 import hashlib
 import json
 import os
+import csv
 from copy import deepcopy
 from dataclasses import asdict
 from functools import lru_cache
@@ -96,20 +97,33 @@ def _read_rewrite_dictionary(path: Path) -&gt; Dict[str, str]:
     return rewrite_dict
  
  
-def _read_synonym_csv_dictionary(path: Path) -> List[List[str]]:
-    rows: List[List[str]] = []
+def _read_synonym_csv_dictionary(path: Path) -> List[Dict[str, List[str]]]:
+    rows: List[Dict[str, List[str]]] = []
     if not path.exists():
         return rows
  
+    def _split_terms(cell: str) -> List[str]:
+        return [item.strip() for item in str(cell or "").split(",") if item.strip()]
+
     with open(path, "r", encoding="utf-8") as handle:
-        for raw_line in handle:
-            line = raw_line.strip()
-            if not line or line.startswith("#"):
+        reader = csv.reader(handle)
+        for parts in reader:
+            if not parts:
+                continue
+            if parts[0].strip().startswith("#"):
                 continue
-            parts = [segment.strip() for segment in line.split(",")]
-            normalized = [segment for segment in parts if segment]
-            if normalized:
-                rows.append(normalized)
+
+            normalized = [segment.strip() for segment in parts]
+            if len(normalized) < 3:
+                continue
+
+            row = {
+                "en_terms": _split_terms(normalized[0]),
+                "zh_terms": _split_terms(normalized[1]),
+                "attribute_terms": _split_terms(normalized[2]),
+            }
+            if any(row.values()):
+                rows.append(row)
     return rows
  
  
@@ -425,6 +439,9 @@ class AppConfigLoader:
                 query_cfg.get("translation_embedding_wait_budget_ms_source_not_in_index", 200)
             ),
             style_intent_enabled=bool(style_intent_cfg.get("enabled", True)),
+            style_intent_selected_sku_boost=float(
+                style_intent_cfg.get("selected_sku_boost", 1.2)
+            ),
             style_intent_terms=style_intent_terms,
             style_intent_dimension_aliases=style_dimension_aliases,
             product_title_exclusion_enabled=bool(product_title_exclusion_cfg.get("enabled", True)),
@@ -65,7 +65,8 @@ class QueryConfig:
     translation_embedding_wait_budget_ms_source_in_index: int = 80
     translation_embedding_wait_budget_ms_source_not_in_index: int = 200
     style_intent_enabled: bool = True
-    style_intent_terms: Dict[str, List[List[str]]] = field(default_factory=dict)
+    style_intent_selected_sku_boost: float = 1.2
+    style_intent_terms: Dict[str, List[Dict[str, List[str]]]] = field(default_factory=dict)
     style_intent_dimension_aliases: Dict[str, List[str]] = field(default_factory=dict)
     product_title_exclusion_enabled: bool = True
     product_title_exclusion_rules: List[Dict[str, List[str]]] = field(default_factory=list)
@@ -7,6 +7,7 @@ contains no independent parsing or precedence logic.
  
 from __future__ import annotations
  
+import os
 from typing import Any, Dict, Tuple
  
 from config.loader import get_app_config
@@ -61,6 +62,12 @@ def get_embedding_image_backend_config() -&gt; Tuple[str, Dict[str, Any]]:
  
 def get_rerank_backend_config() -> Tuple[str, Dict[str, Any]]:
     cfg = get_app_config().services.rerank
+    backend = str(os.getenv("RERANK_BACKEND") or cfg.backend).strip()
+    if backend != cfg.backend:
+        backend_cfg = cfg.backends.get(backend)
+        if backend_cfg is None:
+            raise ValueError(f"Unknown rerank backend override from RERANK_BACKEND: {backend!r}")
+        return backend, dict(backend_cfg)
     return cfg.backend, cfg.get_backend_config()
  
  
@@ -0,0 +1,61 @@
+# Reranker benchmark: `qwen3_vllm` vs `qwen3_vllm_score` × `instruction_format`
+
+**Date:** 2026-03-25  
+**Host:** single GPU (Tesla T4, ~16 GiB), CUDA 12.8 (see `nvidia-smi` during run).
+
+## Configuration (from `config/config.yaml`)
+
+Shared across both backends for this run:
+
+| Key | Value |
+|-----|-------|
+| `model_name` | `Qwen/Qwen3-Reranker-0.6B` |
+| `max_model_len` | 160 |
+| `infer_batch_size` | 100 |
+| `sort_by_doc_length` | true |
+| `enable_prefix_caching` | true |
+| `enforce_eager` | false |
+| `dtype` | float16 |
+| `tensor_parallel_size` | 1 |
+| `gpu_memory_utilization` | 0.20 |
+| `instruction` | `Rank products by query with category & style match prioritized` |
+
+`qwen3_vllm` uses vLLM **generate + logprobs** (`.venv-reranker`).  
+`qwen3_vllm_score` uses vLLM **`LLM.score()`** (`.venv-reranker-score`, pinned vLLM stack per `reranker/README.md`).
+
+## Methodology
+
+- Script: `python scripts/benchmark_reranker_random_titles.py 100,200,400,600,800,1000 --repeat 5` with **`--seed 99`** (see note below), **`--quiet-runs`**, **`--timeout 360`**.
+- Titles: default file `/home/ubuntu/rerank_test/titles.1.8w` (one title per line).
+- Query: default `健身女生T恤短袖`.
+- Each scenario: **3 warm-up** requests at `n=400` (not timed), then **5 timed** runs per `n`.
+- Metric: **client wall time** for `POST /rerank` (localhost), milliseconds.
+- After each `services.rerank.backend` / `instruction_format` change: `./restart.sh reranker`, then **`GET /health`** until `backend` and `instruction_format` matched the intended scenario (extended `reranker/server.py` to expose `instruction_format` when the backend defines `_instruction_format`).
+
+**Note on RNG seed:** With `--seed 42`, some runs occasionally lost one sample at `n=600` (non-200 or transport error). All figures below use **`--seed 99`** so every cell has **5/5** successful runs and comparable sampled titles.
+
+## Raw artifacts
+
+JSON aggregates (means, stdev, raw `values_ms`): same directory, `qwen3_vllm_{compact,standard}.json`, `qwen3_vllm_score_{compact,standard}.json`.
+
+## Results — mean latency (ms)
+
+| backend | instruction_format | n=100 | n=200 | n=400 | n=600 | n=800 | n=1000 |
+|---------|-------------------|------:|------:|------:|------:|------:|-------:|
+| `qwen3_vllm` | `compact` | 213.5 | 418.0 | 861.4 | 1263.4 | 1744.3 | 2162.2 |
+| `qwen3_vllm` | `standard` | 254.9 | 475.4 | 909.7 | 1353.2 | 1912.5 | 2406.7 |
+| `qwen3_vllm_score` | `compact` | 239.2 | 480.2 | 966.2 | 1433.5 | 1937.2 | 2428.4 |
+| `qwen3_vllm_score` | `standard` | 299.6 | 591.8 | 1178.9 | 1773.7 | 2341.6 | 2931.7 |
+
+## Short interpretation
+
+1. **`compact` vs `standard`:** For both backends, **`compact` is faster** on this setup (shorter / different chat template vs fixed yes/no system prompt + user block — see `reranker/backends/qwen3_vllm.py` / `qwen3_vllm_score.py`).
+2. **`qwen3_vllm` vs `qwen3_vllm_score`:** At **`n=1000`**, **`qwen3_vllm` + `compact`** is the fastest row (~2162 ms mean); **`qwen3_vllm_score` + `standard`** is the slowest (~2932 ms). Ordering can change on other GPUs / vLLM versions / batching.
+3. **Repo default** after tests: `services.rerank.backend: qwen3_vllm_score`, `instruction_format: compact` on **both** `qwen3_vllm` and `qwen3_vllm_score` blocks (patch script keeps them aligned).
+
+## Tooling added / changed
+
+- `reranker/server.py`: `/health` includes `instruction_format` when the active backend sets `_instruction_format`.
+- `scripts/benchmark_reranker_random_titles.py`: `--tag`, `--json-summary-out`, `--quiet-runs`.
+- `scripts/patch_rerank_vllm_benchmark_config.py`: surgical YAML patch (preserves newlines).
+- `scripts/run_reranker_vllm_instruction_benchmark.sh`: full matrix driver (continues if a benchmark exits non-zero; uses `--timeout 360`).
@@ -11,38 +11,79 @@ from .tokenization import TokenizedText, normalize_query_text, tokenize_text
  
  
 @dataclass(frozen=True)
+class StyleIntentTermDefinition:
+    canonical_value: str
+    en_terms: Tuple[str, ...]
+    zh_terms: Tuple[str, ...]
+    attribute_terms: Tuple[str, ...]
+
+
+@dataclass(frozen=True)
 class StyleIntentDefinition:
     intent_type: str
-    term_groups: Tuple[Tuple[str, ...], ...]
+    terms: Tuple[StyleIntentTermDefinition, ...]
     dimension_aliases: Tuple[str, ...]
-    synonym_to_canonical: Dict[str, str]
+    en_synonym_to_term: Dict[str, StyleIntentTermDefinition]
+    zh_synonym_to_term: Dict[str, StyleIntentTermDefinition]
     max_term_ngram: int = 3
  
     @classmethod
     def from_rows(
         cls,
         intent_type: str,
-        rows: Sequence[Sequence[str]],
+        rows: Sequence[Dict[str, List[str]]],
         dimension_aliases: Sequence[str],
     ) -> "StyleIntentDefinition":
-        term_groups: List[Tuple[str, ...]] = []
-        synonym_to_canonical: Dict[str, str] = {}
+        terms: List[StyleIntentTermDefinition] = []
+        en_synonym_to_term: Dict[str, StyleIntentTermDefinition] = {}
+        zh_synonym_to_term: Dict[str, StyleIntentTermDefinition] = {}
         max_ngram = 1
  
         for row in rows:
-            normalized_terms: List[str] = []
-            for raw_term in row:
-                term = normalize_query_text(raw_term)
-                if not term or term in normalized_terms:
-                    continue
-                normalized_terms.append(term)
-            if not normalized_terms:
+            normalized_en = tuple(
+                dict.fromkeys(
+                    term
+                    for term in (normalize_query_text(raw) for raw in row.get("en_terms", []))
+                    if term
+                )
+            )
+            normalized_zh = tuple(
+                dict.fromkeys(
+                    term
+                    for term in (normalize_query_text(raw) for raw in row.get("zh_terms", []))
+                    if term
+                )
+            )
+            normalized_attribute = tuple(
+                dict.fromkeys(
+                    term
+                    for term in (normalize_query_text(raw) for raw in row.get("attribute_terms", []))
+                    if term
+                )
+            )
+            if not normalized_en and not normalized_zh and not normalized_attribute:
                 continue
  
-            canonical = normalized_terms[0]
-            term_groups.append(tuple(normalized_terms))
-            for term in normalized_terms:
-                synonym_to_canonical[term] = canonical
+            canonical = (
+                normalized_attribute[0]
+                if normalized_attribute
+                else normalized_en[0]
+                if normalized_en
+                else normalized_zh[0]
+            )
+            term_definition = StyleIntentTermDefinition(
+                canonical_value=canonical,
+                en_terms=normalized_en,
+                zh_terms=normalized_zh,
+                attribute_terms=normalized_attribute,
+            )
+            terms.append(term_definition)
+
+            for term in normalized_en:
+                en_synonym_to_term[term] = term_definition
+                max_ngram = max(max_ngram, len(term.split()))
+            for term in normalized_zh:
+                zh_synonym_to_term[term] = term_definition
                 max_ngram = max(max_ngram, len(term.split()))
  
         aliases = tuple(
@@ -58,28 +99,31 @@ class StyleIntentDefinition:
  
         return cls(
             intent_type=intent_type,
-            term_groups=tuple(term_groups),
+            terms=tuple(terms),
             dimension_aliases=aliases,
-            synonym_to_canonical=synonym_to_canonical,
+            en_synonym_to_term=en_synonym_to_term,
+            zh_synonym_to_term=zh_synonym_to_term,
             max_term_ngram=max_ngram,
         )
  
-    def match_candidates(self, candidates: Iterable[str]) -> Set[str]:
-        matched: Set[str] = set()
+    def match_candidates(self, candidates: Iterable[str], *, language: str) -> Set[StyleIntentTermDefinition]:
+        mapping = self.zh_synonym_to_term if language == "zh" else self.en_synonym_to_term
+        matched: Set[StyleIntentTermDefinition] = set()
         for candidate in candidates:
-            canonical = self.synonym_to_canonical.get(normalize_query_text(candidate))
-            if canonical:
-                matched.add(canonical)
+            term_definition = mapping.get(normalize_query_text(candidate))
+            if term_definition:
+                matched.add(term_definition)
         return matched
  
     def match_text(
         self,
         text: str,
         *,
+        language: str,
         tokenizer: Optional[Callable[[str], Any]] = None,
-    ) -> Set[str]:
+    ) -> Set[StyleIntentTermDefinition]:
         bundle = tokenize_text(text, tokenizer=tokenizer, max_ngram=self.max_term_ngram)
-        return self.match_candidates(bundle.candidates)
+        return self.match_candidates(bundle.candidates, language=language)
  
  
 @dataclass(frozen=True)
@@ -88,6 +132,7 @@ class DetectedStyleIntent:
     canonical_value: str
     matched_term: str
     matched_query_text: str
+    attribute_terms: Tuple[str, ...]
     dimension_aliases: Tuple[str, ...]
  
     def to_dict(self) -> Dict[str, Any]:
@@ -96,6 +141,7 @@ class DetectedStyleIntent:
             "canonical_value": self.canonical_value,
             "matched_term": self.matched_term,
             "matched_query_text": self.matched_query_text,
+            "attribute_terms": list(self.attribute_terms),
             "dimension_aliases": list(self.dimension_aliases),
         }
  
@@ -159,7 +205,7 @@ class StyleIntentRegistry:
                 rows=rows or [],
                 dimension_aliases=dimension_aliases.get(intent_type, []),
             )
-            if definition.synonym_to_canonical:
+            if definition.terms:
                 definitions[definition.intent_type] = definition
  
         return cls(
@@ -191,15 +237,10 @@ class StyleIntentDetector:
         seen = set()
         variants: List[TokenizedText] = []
         texts = [
-            getattr(parsed_query, "original_query", None),
-            getattr(parsed_query, "query_normalized", None),
-            getattr(parsed_query, "rewritten_query", None),
+            self._get_language_query_text(parsed_query, "zh"),
+            self._get_language_query_text(parsed_query, "en"),
         ]
  
-        translations = getattr(parsed_query, "translations", {}) or {}
-        if isinstance(translations, dict):
-            texts.extend(translations.values())
-
         for raw_text in texts:
             text = str(raw_text or "").strip()
             if not text:
@@ -221,35 +262,66 @@ class StyleIntentDetector:
  
         return tuple(variants)
  
+    @staticmethod
+    def _get_language_query_text(parsed_query: Any, language: str) -> str:
+        translations = getattr(parsed_query, "translations", {}) or {}
+        if isinstance(translations, dict):
+            translated = translations.get(language)
+            if translated:
+                return str(translated)
+        return str(getattr(parsed_query, "original_query", "") or "")
+
+    def _tokenize_language_query(self, parsed_query: Any, language: str) -> Optional[TokenizedText]:
+        text = self._get_language_query_text(parsed_query, language).strip()
+        if not text:
+            return None
+        return tokenize_text(
+            text,
+            tokenizer=self.tokenizer,
+            max_ngram=max(
+                (definition.max_term_ngram for definition in self.registry.definitions.values()),
+                default=3,
+            ),
+        )
+
     def detect(self, parsed_query: Any) -> StyleIntentProfile:
         if not self.registry.enabled or not self.registry.definitions:
             return StyleIntentProfile()
  
         query_variants = self._build_query_variants(parsed_query)
+        zh_variant = self._tokenize_language_query(parsed_query, "zh")
+        en_variant = self._tokenize_language_query(parsed_query, "en")
         detected: List[DetectedStyleIntent] = []
         seen_pairs = set()
  
-        for variant in query_variants:
-            for intent_type, definition in self.registry.definitions.items():
-                matched_canonicals = definition.match_candidates(variant.candidates)
-                if not matched_canonicals:
+        for intent_type, definition in self.registry.definitions.items():
+            for language, variant, mapping in (
+                ("zh", zh_variant, definition.zh_synonym_to_term),
+                ("en", en_variant, definition.en_synonym_to_term),
+            ):
+                if variant is None or not mapping:
+                    continue
+
+                matched_terms = definition.match_candidates(variant.candidates, language=language)
+                if not matched_terms:
                     continue
  
                 for candidate in variant.candidates:
                     normalized_candidate = normalize_query_text(candidate)
-                    canonical = definition.synonym_to_canonical.get(normalized_candidate)
-                    if not canonical or canonical not in matched_canonicals:
+                    term_definition = mapping.get(normalized_candidate)
+                    if term_definition is None or term_definition not in matched_terms:
                         continue
-                    pair = (intent_type, canonical)
+                    pair = (intent_type, term_definition.canonical_value)
                     if pair in seen_pairs:
                         continue
                     seen_pairs.add(pair)
                     detected.append(
                         DetectedStyleIntent(
                             intent_type=intent_type,
-                            canonical_value=canonical,
+                            canonical_value=term_definition.canonical_value,
                             matched_term=normalized_candidate,
                             matched_query_text=variant.text,
+                            attribute_terms=term_definition.attribute_terms,
                             dimension_aliases=definition.dimension_aliases,
                         )
                     )
@@ -0,0 +1,7 @@
+# Shared base dependencies for reranker service venvs.
+
+fastapi>=0.100.0
+uvicorn[standard]>=0.23.0
+pydantic>=2.0.0
+numpy>=1.24.0
+pyyaml>=6.0
@@ -0,0 +1,7 @@
+# Isolated dependencies for bge reranker backend.
+
+-r requirements_reranker_base.txt
+torch>=2.0.0
+transformers>=4.30.0
+sentence-transformers>=2.2.0
+modelscope>=1.9.0
@@ -0,0 +1,3 @@
+# Isolated dependencies for dashscope_rerank backend.
+
+-r requirements_reranker_base.txt
@@ -0,0 +1,5 @@
+# Isolated dependencies for qwen3_gguf reranker backend (.venv-reranker-gguf).
+
+-r requirements_reranker_base.txt
+huggingface-hub>=0.32.0
+llama-cpp-python>=0.3.16
@@ -0,0 +1,3 @@
+# Isolated dependencies for qwen3_gguf_06b reranker backend (.venv-reranker-gguf-06b).
+
+-r requirements_reranker_qwen3_gguf.txt
@@ -0,0 +1,5 @@
+# Isolated dependencies for qwen3_transformers reranker backend.
+
+-r requirements_reranker_base.txt
+torch>=2.0.0
+transformers>=4.51.0
@@ -0,0 +1,9 @@
+# Isolated dependencies for qwen3_transformers_packed reranker backend.
+#
+# Keep this stack aligned with the validated CUDA runtime on our hosts.
+# On this machine, torch 2.11.0 + cu130 fails CUDA init, while torch 2.10.0 + cu128 works.
+# We also cap transformers <5 to stay on the same family as the working vLLM score env.
+
+-r requirements_reranker_qwen3_transformers.txt
+torch==2.10.0
+transformers>=4.51.0,<5
@@ -0,0 +1,5 @@
+# Isolated dependencies for qwen3_vllm reranker backend (.venv-reranker).
+
+-r requirements_reranker_base.txt
+transformers>=4.30.0
+vllm>=0.8.5
@@ -0,0 +1,14 @@
+# Dedicated high-performance venv for qwen3_vllm_score: .venv-reranker-score
+#
+# Create / refresh:
+#   ./scripts/setup_reranker_venv.sh qwen3_vllm_score
+#
+# vLLM 0.17+ replaces LLM(task="score") with runner/convert auto + LLM.score().
+# Pin vLLM for reproducible perf baselines; bump after validating CUDA/driver on your hosts.
+# If pip cannot find a wheel for your CUDA version, edit the vllm line or install from:
+#   https://docs.vllm.ai/en/latest/getting_started/installation.html
+
+-r requirements_reranker_base.txt
+vllm==0.18.0
+# Match vLLM 0.18 stack; cap <5 to avoid pip prefetching incompatible transformers 5.x.
+transformers>=4.51.0,<5
-# Isolated dependencies for reranker service (.venv-reranker)
+# Legacy alias: qwen3_vllm reranker service env (.venv-reranker).
 #
-# Default backend is qwen3_vllm (Qwen3-Reranker-0.6B).
+# Prefer backend-specific requirements files:
+# - requirements_reranker_qwen3_vllm.txt
+# - requirements_reranker_qwen3_vllm_score.txt
+# - requirements_reranker_qwen3_gguf.txt
+# - requirements_reranker_qwen3_transformers.txt
+# - requirements_reranker_bge.txt
+# - requirements_reranker_dashscope.txt
  
-fastapi>=0.100.0
-uvicorn[standard]>=0.23.0
-pydantic>=2.0.0
-numpy>=1.24.0
-pyyaml>=6.0
-transformers>=4.30.0
-vllm>=0.8.5
+-r requirements_reranker_qwen3_vllm.txt
-# Reranker 部署与性能调优手册（Qwen3-vLLM）
+# Reranker 部署与性能调优手册（Qwen3-vLLM / Qwen3-GGUF）
  
 本文档沉淀当前项目在电商搜索重排场景下的可复用实践，覆盖：
  
 - 环境准备与安装部署
-- `qwen3_vllm` 配置项与优化思路
+- `qwen3_vllm` / `qwen3_gguf` / `qwen3_gguf_06b` 配置项与优化思路
 - 1000-doc 场景压测流程
 - 关键结论与推荐默认参数
 - 常见故障排查
  
 适用范围：
  
-- 重排后端：`services.rerank.backend: qwen3_vllm`
-- 模型：`Qwen/Qwen3-Reranker-0.6B`
+- 重排后端：`services.rerank.backend: qwen3_vllm` / `qwen3_gguf` / `qwen3_gguf_06b`
+- 模型：`Qwen/Qwen3-Reranker-0.6B` / `DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF` / `ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF`
 - 场景：query 较短（通常 < 100 tokens），doc 为商品标题或标题+简短描述，单请求 docs 约 1000 条
  
 ## 1. 环境基线
  
-当前验证环境（2026-03-11）：
+当前验证环境（2026-03-25）：
  
 - GPU：`Tesla T4 16GB`
 - Driver / CUDA：`570.158.01 / 12.8`
 - Python：`3.12.3`
-- 关键依赖：`vllm==0.17.0`、`torch==2.10.0+cu128`、`transformers==4.57.6`、`fastapi==0.135.1`、`uvicorn==0.41.0`
+- 关键依赖：`vllm==0.17.0`、`torch==2.10.0+cu128`、`transformers==4.57.6`、`llama-cpp-python>=0.3.16`、`fastapi==0.135.1`、`uvicorn==0.41.0`
  
 ## 2. 环境准备与安装
  
 ### 2.1 准备 reranker 独立虚拟环境
  
 ```bash
-./scripts/setup_reranker_venv.sh
+./scripts/setup_reranker_venv.sh qwen3_vllm
+```
+
+若使用 GGUF 并需要 CUDA：
+
+```bash
+./scripts/setup_reranker_venv.sh qwen3_gguf
+PATH=/usr/local/cuda/bin:$PATH \
+CUDACXX=/usr/local/cuda/bin/nvcc \
+CMAKE_ARGS="-DGGML_CUDA=on" \
+FORCE_CMAKE=1 \
+./.venv-reranker-gguf/bin/pip install --no-cache-dir --force-reinstall --no-build-isolation llama-cpp-python==0.3.18
 ```
  
 ### 2.2 基础检查
@@ -37,6 +48,7 @@
 nvidia-smi
 ./.venv-reranker/bin/python -c "import torch; print(torch.cuda.is_available())"
 ./.venv-reranker/bin/python -c "import vllm, transformers; print(vllm.__version__, transformers.__version__)"
+./.venv-reranker-gguf/bin/python -c "import llama_cpp; print(llama_cpp.__version__)"
 ```
  
 ## 3. 部署与运行
@@ -64,6 +76,29 @@ services:
         length_sort_mode: "char"  # char | token
 ```
  
+GGUF / T4 剩余显存约 `4.8~6GB` 时，推荐基线：
+
+```yaml
+services:
+  rerank:
+    backend: "qwen3_gguf"
+    backends:
+      qwen3_gguf:
+        repo_id: "DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF"
+        filename: "*Q8_0.gguf"
+        local_dir: "./models/reranker/qwen3-reranker-4b-gguf"
+        cache_dir: "./model_cache"
+        n_ctx: 384
+        n_batch: 384
+        n_ubatch: 128
+        n_gpu_layers: 24
+        flash_attn: true
+        offload_kqv: true
+        infer_batch_size: 8
+        sort_by_doc_length: true
+        length_sort_mode: "char"
+```
+
 ### 3.2 启停命令
  
 推荐统一使用：
@@ -105,6 +140,13 @@ curl -sS http://127.0.0.1:6007/health
 - `service_ctl.sh` 对 reranker 使用独立启动路径
 - 增加“稳定健康检查”（连续健康探测）避免“刚 healthy 即退出”的假阳性
  
+### 4.4 GGUF / T4 小显存优化原则
+
+- `Q8_0` 权重约 `4.28GB`，但还要给 KV cache、CUDA 工作区和运行时碎片预留空间，不能按“模型大小 < 剩余显存”直接判断可行。
+- 当前业务是短 query + 商品标题，优先压缩 `n_ctx`；`384` 通常比默认长上下文更划算。
+- T4 小显存下先扫 `n_gpu_layers`，再尝试提高 `n_ctx`；`infer_batch_size` 在当前 GGUF 接入里主要是服务侧 work chunk，不是 llama.cpp 的真实算子 batch。
+- `flash_attn: true`、`offload_kqv: true` 默认保持开启；若 OOM，优先降低 `n_gpu_layers`。
+
 ## 5. 性能调优流程（标准流程）
  
 ### 5.1 使用一键压测脚本
@@ -125,6 +167,13 @@ curl -sS http://127.0.0.1:6007/health
 - `infer_batch_size`: `24 32 48 64`
 - 并发组：`c=1`（看单请求延迟）、`c=4`（看并发吞吐与尾延迟）
  
+GGUF 建议扫描：
+
+- `n_gpu_layers`: `20 24 28`
+- `n_ctx`: `320 384 448`
+- `infer_batch_size`: `4 8 12`（次要，仅影响服务侧 work chunk）
+- 扫描顺序：先固定 `n_ctx=384`，找能稳定启动的最大 `n_gpu_layers`；再在显存允许时尝试 `n_ctx=448`；最后才微调 `infer_batch_size`
+
 可通过环境变量覆盖：
  
 - `BATCH_SIZES`
@@ -140,23 +189,28 @@ curl -sS http://127.0.0.1:6007/health
 - `RERANK_VLLM_INFER_BATCH_SIZE`
 - `RERANK_VLLM_SORT_BY_DOC_LENGTH`
  
-## 6. 本轮关键结论（2026-03-11）
-
-基于报告：
-
-- `perf_reports/20260311/reranker_1000docs/report.md`
+## 6. 本轮关键结论
  
-结论：
+vLLM（2026-03-11，见 `perf_reports/20260311/reranker_1000docs/report.md`）：
  
 - 对在线重排更重要的单请求延迟（`c=1`）指标，`infer_batch_size=64` 最优
 - `infer_batch_size=96` 在更高并发下吞吐略高，但会牺牲单请求延迟稳定性
 - 当前默认选择 `infer_batch_size=64` 作为平衡点
  
+GGUF（2026-03-25，本次接入）：
+
+- `DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF` 的 `Q8_0` 体积约 `4.28GB`，结合当前机器实测剩余显存约 `4823 MiB`，默认不采用激进的全量 GPU offload。
+- 当前推荐默认值：`n_ctx=384`、`n_batch=384`、`n_ubatch=128`、`n_gpu_layers=24`、`infer_batch_size=8`。
+- 若现场剩余显存更接近 `6GB` 且碎片较少，可优先尝试 `n_gpu_layers=28`；若启动失败，回退到 `24` 或 `20`。
+- 由于当前工作区尚未缓存该 GGUF 权重，本次尚未完成真实吞吐压测；上线前需在部署机复跑一轮参数扫描并归档报告。
+
 ## 7. 生产建议
  
 - 默认保持：`infer_batch_size: 64`、`sort_by_doc_length: true`
 - 满足以下条件时可考虑提高到 `96`：业务以吞吐优先、可接受更高单请求延迟、已通过同机同数据压测验证收益
 - 每次改动后都必须复跑 `benchmark_reranker_1000docs.sh` 并归档结果
+- GGUF 默认保持：`n_ctx: 384`、`n_gpu_layers: 24`、`infer_batch_size: 8`、`flash_attn: true`、`offload_kqv: true`
+- GGUF 若 OOM：先降 `n_gpu_layers`，再降 `n_ctx`，最后再降 `infer_batch_size`
  
 ## 8. 故障排查
  
@@ -194,6 +248,13 @@ lsof -i :6007 -P -n
 - 降低 `infer_batch_size`
 - 检查是否有其他进程占用同卡
  
+GGUF 优先调整：
+
+- 降低 `n_gpu_layers`
+- 降低 `n_ctx`
+- 降低 `infer_batch_size`
+- 检查是否有其他进程占用同卡
+
 ## 9. 变更与验证清单
  
 每次 reranker 调优改动后，至少完成：
@@ -0,0 +1,154 @@
+# Qwen3-Reranker-0.6B GGUF 安装与调优
+
+本文档覆盖 `qwen3_gguf_06b` 后端，对应模型：
+
+- Hugging Face: `ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF`
+- 文件: `qwen3-reranker-0.6b-q8_0.gguf`
+- 本地目录: `./models/reranker/qwen3-reranker-0.6b-q8_0-gguf`
+
+## 结论先看
+
+这个后端已经接入完成，也能正常使用 GPU offload，但不适合当前项目的在线主链路场景。
+
+目标场景是：
+
+- 1 个 query
+- 400 个商品标题
+- 追求最短响应时间
+
+实测最优配置下：
+
+- GPU 显存占用约 `894 MiB`
+- 400 titles 单请求延迟约 `265318 ms`
+
+因此它更适合作为：
+
+- 低显存 fallback
+- 功能验证
+- 本地离线实验
+
+不建议作为在线低延迟 reranker 主 backend。
+
+## 独立环境
+
+`qwen3_gguf_06b` 使用独立 venv：
+
+- backend: `qwen3_gguf_06b`
+- venv: `.venv-reranker-gguf-06b`
+- requirements: `requirements_reranker_qwen3_gguf_06b.txt`
+
+安装：
+
+```bash
+./scripts/setup_reranker_venv.sh qwen3_gguf_06b
+```
+
+如果需要确认是 CUDA 版 `llama-cpp-python`：
+
+```bash
+./.venv-reranker-gguf-06b/bin/python - <<'PY'
+import llama_cpp
+print(llama_cpp.llama_supports_gpu_offload())
+PY
+```
+
+预期输出：
+
+```python
+True
+```
+
+## 模型下载
+
+推荐预先下载到本地，避免首次服务启动时在线拉取：
+
+```bash
+mkdir -p models/reranker/qwen3-reranker-0.6b-q8_0-gguf
+curl -L --fail -C - \
+  -o models/reranker/qwen3-reranker-0.6b-q8_0-gguf/qwen3-reranker-0.6b-q8_0.gguf \
+  'https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/resolve/main/qwen3-reranker-0.6b-q8_0.gguf?download=true'
+```
+
+当前实测文件大小：
+
+- `639153184` bytes
+
+## 推荐配置
+
+`config/config.yaml` 中建议保留：
+
+```yaml
+qwen3_gguf_06b:
+  repo_id: "ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF"
+  filename: "qwen3-reranker-0.6b-q8_0.gguf"
+  local_dir: "./models/reranker/qwen3-reranker-0.6b-q8_0-gguf"
+  cache_dir: "./model_cache"
+  instruction: "Rank products by query with category & style match prioritized"
+  n_ctx: 256
+  n_batch: 256
+  n_ubatch: 256
+  n_gpu_layers: 999
+  main_gpu: 0
+  n_threads: 2
+  n_threads_batch: 4
+  flash_attn: true
+  offload_kqv: true
+  use_mmap: true
+  use_mlock: false
+  infer_batch_size: 32
+  sort_by_doc_length: true
+  length_sort_mode: "char"
+  reuse_query_state: false
+  enable_warmup: true
+  verbose: false
+```
+
+## 调优结果
+
+在当前机器上做了同机实测。标题文件来自 `/home/ubuntu/rerank_test/titles.1.8w`，查询为 `白色oversized T-shirt`。
+
+80 titles：
+
+- `n_ctx=256, reuse_query_state=true` -> `60108 ms`
+- `n_ctx=256, reuse_query_state=false` -> `53383~56893 ms`
+- `n_ctx=320, reuse_query_state=true` -> `60961 ms`
+- `n_ctx=384, reuse_query_state=true` -> `56578 ms`
+- `n_ctx=384, reuse_query_state=false` -> `57272 ms`
+- `n_ctx=512, reuse_query_state=false` -> `60542 ms`
+- `n_ctx=256, reuse_query_state=false, n_threads=4, n_threads_batch=8` -> `61228 ms`
+
+400 titles：
+
+- `n_ctx=256, n_batch=256, n_ubatch=256, n_gpu_layers=999, reuse_query_state=false`
+  -> `265318 ms`
+
+## 经验沉淀
+
+这次接入最重要的结论不是“哪个小参数更快”，而是：
+
+1. 这个 0.6B GGUF 权重虽然小，但当前后端实现仍是逐 doc 顺序打分。
+2. 对在线 400-title 请求来说，串行打分本身就是主瓶颈。
+3. `reuse_query_state` 在这个模型上没有带来收益，反而更慢。
+4. `n_ctx` 拉大到 `384/512` 也没有带来实质收益，反而更慢或持平。
+5. 这个 backend 的优势是低显存，不是低延迟。
+
+如果目标是在线最短响应时间，优先级建议是：
+
+1. `qwen3_vllm`
+2. 其他真正支持高吞吐批处理的后端
+3. `qwen3_gguf_06b` 仅作为低显存 fallback
+
+## 验证命令
+
+本地直连 backend 调优：
+
+```bash
+PYTHONPATH=/data/saas-search ./.venv-reranker-gguf/bin/python \
+  scripts/benchmark_reranker_gguf_local.py --backend-name qwen3_gguf_06b --docs 400
+```
+
+按服务方式启动：
+
+```bash
+RERANK_BACKEND=qwen3_gguf_06b ./scripts/start_reranker.sh
+```
@@ -0,0 +1,280 @@
+# Qwen3 GGUF 安装与调优手册
+
+本文档只覆盖 `qwen3_gguf` 后端，目标机器为当前项目实测环境：
+
+- GPU: `Tesla T4 16GB`
+- CUDA: `12.8`
+- 模型: `DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF`
+- 量化: `Q8_0`
+
+---
+
+## 1. 结论先看
+
+当前这套代码里，GGUF 后端的主要瓶颈不是“显存没吃满”，而是 **llama.cpp 按 doc 顺序逐条打分**。因此最有效的优化策略是：
+
+- 让模型层尽可能全部 offload 到 GPU
+- 打开 `flash_attn` / `offload_kqv`
+- 把 `n_ctx / n_batch / n_ubatch` 调到一个对短标题重排更合适的高效点
+
+本轮在当前机器上的推荐配置是：
+
+```yaml
+qwen3_gguf:
+  n_ctx: 512
+  n_batch: 512
+  n_ubatch: 512
+  n_gpu_layers: 999
+  n_threads: 2
+  n_threads_batch: 4
+  flash_attn: true
+  offload_kqv: true
+  infer_batch_size: 8
+  sort_by_doc_length: true
+  length_sort_mode: "char"
+```
+
+说明：
+
+- `n_gpu_layers: 999` 在 llama.cpp 中等价于“尽可能全部层都 offload”
+- 这台 T4 上，**即使全量 offload，当前模型也只占到约 `4.5 GiB` GPU 显存**
+- 所以“允许 8G 显存”并不会自动带来更高速度；这个模型/后端在当前工作负载下已经接近“该用到的权重都上 GPU 了”
+
+---
+
+## 2. 独立环境
+
+`qwen3_gguf` 必须使用自己的独立 venv：
+
+- `qwen3_vllm` -> `.venv-reranker`
+- `qwen3_gguf` -> `.venv-reranker-gguf`
+
+安装命令：
+
+```bash
+./scripts/setup_reranker_venv.sh qwen3_gguf
+```
+
+脚本现在会自动做两件事：
+
+1. 安装 GGUF 后端所需 Python 依赖
+2. 在检测到 `/usr/local/cuda/bin/nvcc` 时，把 `llama-cpp-python` **重编译成 CUDA 版**
+
+---
+
+## 3. GPU 版验证
+
+必须验证不是 CPU-only 版：
+
+```bash
+./.venv-reranker-gguf/bin/python - <<'PY'
+import llama_cpp
+print("supports_gpu_offload =", llama_cpp.llama_supports_gpu_offload())
+PY
+```
+
+正确结果应为：
+
+```text
+supports_gpu_offload = True
+```
+
+还可以看动态库：
+
+```bash
+ldd .venv-reranker-gguf/lib/python3.12/site-packages/llama_cpp/lib/libllama.so | rg 'cuda|cublas|ggml-cuda'
+```
+
+应能看到：
+
+- `libggml-cuda.so`
+- `libcudart.so`
+- `libcublas.so`
+
+---
+
+## 4. 模型下载
+
+当前使用本地文件优先策略，模型放在：
+
+```text
+models/reranker/qwen3-reranker-4b-gguf/Qwen.Qwen3-Reranker-4B.Q8_0.gguf
+```
+
+若本地文件存在，后端会直接加载本地 GGUF，不再依赖启动时在线下载。
+
+为了避免当前机器上 Hugging Face Xet 下载的 `416 Range Not Satisfiable` 问题，`start_reranker.sh` 已对 `qwen3_gguf` 默认设置：
+
+```bash
+HF_HUB_DISABLE_XET=1
+```
+
+---
+
+## 5. 本地调优脚本
+
+新增本地基准脚本：
+
+```bash
+PYTHONPATH=/data/saas-search ./.venv-reranker-gguf/bin/python \
+  scripts/benchmark_reranker_gguf_local.py --docs 64 --repeat 1
+```
+
+它会直接实例化 GGUF backend，输出：
+
+- 模型加载耗时
+- 当前进程 GPU 显存占用
+- 单次 rerank 延迟
+
+---
+
+## 6. 本轮实测结果
+
+测试条件：
+
+- Query: `白色oversized T-shirt`
+- Docs: `64` 条商品标题
+- 本地脚本：`scripts/benchmark_reranker_gguf_local.py`
+- 每组 1 次，重点比较相对趋势
+
+结果：
+
+### 6.1 保守配置
+
+```text
+n_ctx=384
+n_batch=384
+n_ubatch=128
+n_gpu_layers=24
+```
+
+- GPU 显存：`2984 MiB`
+- 64 docs 延迟：`74347.91 ms`
+
+### 6.2 全量 offload
+
+```text
+n_ctx=384
+n_batch=384
+n_ubatch=128
+n_gpu_layers=999
+```
+
+- GPU 显存：`4338 MiB`
+- 64 docs 延迟：`51401.77 ms`
+
+### 6.3 最优配置
+
+```text
+n_ctx=512
+n_batch=512
+n_ubatch=512
+n_gpu_layers=999
+```
+
+- GPU 显存：`4564 MiB`
+- 64 docs 延迟：`49116.10 ms`
+
+### 6.4 其它尝试
+
+`n_threads=4 / n_threads_batch=8`：
+
+- GPU 显存：`4564 MiB`
+- 64 docs 延迟：`49895.88 ms`
+- 比推荐值略慢
+
+`infer_batch_size=64`：
+
+- GPU 显存：`4564 MiB`
+- 64 docs 延迟：`50723.36 ms`
+- 也略慢
+
+### 6.5 API 级验证
+
+在把推荐配置写入 `config/config.yaml` 并重启服务后，使用：
+
+```bash
+RERANK_BASE=http://127.0.0.1:6007 \
+  ./.venv/bin/python scripts/benchmark_reranker_random_titles.py 64 --repeat 1 --query '白色oversized T-shirt'
+```
+
+得到：
+
+- `64 docs`：`50177.22 ms`
+
+再用：
+
+```bash
+RERANK_BASE=http://127.0.0.1:6007 \
+  ./.venv/bin/python scripts/benchmark_reranker_random_titles.py 153 --repeat 1 --query '白色oversized T-shirt'
+```
+
+得到：
+
+- `153 docs`：`115328.60 ms`
+
+对比旧日志中的保守配置：
+
+- 旧配置 `153 docs`：`153435.37 ms`
+- 新配置 `153 docs`：`115328.60 ms`
+
+改善幅度约：
+
+- `24.8%`
+
+---
+
+## 7. 为什么没有吃到 8G
+
+结论很重要：
+
+- 当前最优配置已经是“尽可能全量层 offload”
+- 该 `Q8_0` 模型在这套 llama.cpp / T4 / 短文本重排场景下，**实测只需要约 `4.5 GiB` GPU 显存**
+- 继续为了“吃满 8G”去增大 `n_ctx`，不会明显提升吞吐，反而可能带来额外开销
+
+所以本轮不是“显存太保守”，而是：
+
+- 可 offload 的权重已经基本 offload 完了
+- 真正拖慢响应的是 **逐 doc 顺序推理** 这一后端实现路径
+
+---
+
+## 8. 生产建议
+
+### 8.1 当前建议
+
+保留以下参数：
+
+```yaml
+n_ctx: 512
+n_batch: 512
+n_ubatch: 512
+n_gpu_layers: 999
+n_threads: 2
+n_threads_batch: 4
+flash_attn: true
+offload_kqv: true
+```
+
+### 8.2 如果还嫌慢
+
+优先级建议：
+
+1. 缩小 `rerank_window`
+2. 减少传入 doc 数
+3. 若业务允许，切换到更适合高吞吐的后端
+
+原因：
+
+- 当前 GGUF 后端是本地单进程、逐 doc 打分
+- 对长列表重排，它天然不如 vLLM / 云端 rerank API 擅长吞吐
+
+---
+
+## 9. 本轮落地文件
+
+- `config/config.yaml`
+- `scripts/setup_reranker_venv.sh`
+- `scripts/start_reranker.sh`
+- `scripts/benchmark_reranker_gguf_local.py`
+- `reranker/GGUF_INSTALL_AND_TUNING.md`
 # Reranker 模块
  
-**请求示例**见 `docs/QUICKSTART.md` §3.5。扩展规范见 `docs/DEVELOPER_GUIDE.md` §7。部署与调优实战见 `reranker/DEPLOYMENT_AND_TUNING.md`。
+**请求示例**见 `docs/QUICKSTART.md` §3.5。扩展规范见 `docs/DEVELOPER_GUIDE.md` §7。部署与调优实战见 `reranker/DEPLOYMENT_AND_TUNING.md`。`ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF` 的专项接入与调优结论见 `reranker/GGUF_0_6B_INSTALL_AND_TUNING.md`。
  
 ---
  
-Reranker 服务提供统一的 `/rerank` API，支持可插拔后端（BGE、Qwen3-vLLM、Qwen3-Transformers、DashScope 云重排）。调用方通过 HTTP 访问，不关心具体后端。
+Reranker 服务提供统一的 `/rerank` API，支持可插拔后端（BGE、Qwen3-vLLM、Qwen3-Transformers、Qwen3-GGUF、DashScope 云重排）。调用方通过 HTTP 访问，不关心具体后端。
  
 **特性**
-- 多后端：`qwen3_vllm`（默认，Qwen3-Reranker-0.6B + vLLM）、`qwen3_transformers`（纯 Transformers，无需 vLLM）、`bge`（兼容保留）
+- 多后端：`qwen3_vllm`、`qwen3_vllm_score`（同模型，vLLM ``LLM.score()`` + 独立 `.venv-reranker-score`）、`qwen3_transformers`、`qwen3_transformers_packed`（共享前缀 + packed attention mask）、`qwen3_gguf`（Qwen3-Reranker-4B GGUF + llama.cpp）、`qwen3_gguf_06b`（Qwen3-Reranker-0.6B Q8_0 GGUF + llama.cpp）、`bge`（兼容保留）
 - 云后端：`dashscope_rerank`（调用 DashScope `/compatible-api/v1/reranks`，支持按地域切换 endpoint）
 - 统一配置：`config/config.yaml` → `services.rerank.backend` / `services.rerank.backends.<name>`
 - 文档去重、分数与输入顺序一致、FP16/GPU 支持（视后端）
@@ -17,28 +17,51 @@ Reranker 服务提供统一的 `/rerank` API，支持可插拔后端（BGE、Qwe
 - `reranker/backends/`：后端实现与工厂
   - `backends/__init__.py`：`get_rerank_backend(name, config)`
   - `backends/bge.py`：BGE 后端
-  - `backends/qwen3_vllm.py`：Qwen3-Reranker-0.6B + vLLM 后端
+  - `backends/qwen3_vllm.py`：Qwen3-Reranker-0.6B + vLLM（generate + logprobs）
+  - `backends/qwen3_vllm_score.py`：同上模型 + vLLM ``LLM.score()``（`requirements_reranker_qwen3_vllm_score.txt` / `.venv-reranker-score`）
   - `backends/qwen3_transformers.py`：Qwen3-Reranker-0.6B 纯 Transformers 后端（官方 Usage 方式）
+  - `backends/qwen3_transformers_packed.py`：Qwen3-Reranker-0.6B + Transformers packed 推理（共享 query prefix，适合 `1 query + 400 docs`）
+  - `backends/qwen3_gguf.py`：Qwen3-Reranker GGUF + llama.cpp 后端（支持 `qwen3_gguf` / `qwen3_gguf_06b`）
   - `backends/dashscope_rerank.py`：DashScope 云重排后端（HTTP 调用）
 - `reranker/bge_reranker.py`：BGE 核心推理（被 bge 后端封装）
 - `reranker/config.py`：服务端口、MAX_DOCS、NORMALIZE 等（后端参数在 config.yaml）
  
 ## 依赖
 - 通用：`torch`、`transformers`、`fastapi`、`uvicorn`（隔离环境见 `requirements_reranker_service.txt`；全量 ML 环境另见 `requirements_ml.txt`）
-- **Qwen3-vLLM 后端**：`vllm>=0.8.5`、`transformers>=4.51.0`（仅当使用 `backend: qwen3_vllm` 时需 vLLM）
+- **Qwen3-vLLM 后端**：`vllm>=0.8.5`、`transformers>=4.51.0`（`qwen3_vllm` → `.venv-reranker`）
+- **Qwen3-vLLM-score 后端**：固定 `vllm==0.18.0`（`qwen3_vllm_score` → `.venv-reranker-score`，见 `requirements_reranker_qwen3_vllm_score.txt`）
 - **Qwen3-Transformers 后端**：`transformers>=4.51.0`、`torch`（无需 vLLM，适合 CPU 或小显存）
+- **Qwen3-Transformers-Packed 后端**：复用 Transformers 依赖（`qwen3_transformers_packed` → `.venv-reranker-transformers-packed`）
+- **Qwen3-GGUF 后端**：`llama-cpp-python>=0.3.16`
+- 现在按 backend 使用独立 venv：
+  - `qwen3_vllm` -> `.venv-reranker`
+  - `qwen3_vllm_score` -> `.venv-reranker-score`
+  - `qwen3_gguf` -> `.venv-reranker-gguf`
+  - `qwen3_gguf_06b` -> `.venv-reranker-gguf-06b`
+  - `qwen3_transformers` -> `.venv-reranker-transformers`
+  - `qwen3_transformers_packed` -> `.venv-reranker-transformers-packed`
+  - `bge` -> `.venv-reranker-bge`
+  - `dashscope_rerank` -> `.venv-reranker-dashscope`
   ```bash
-  ./scripts/setup_reranker_venv.sh
+  ./scripts/setup_reranker_venv.sh qwen3_gguf_06b
+  ```
+  CUDA 构建建议：
+  ```bash
+  PATH=/usr/local/cuda/bin:$PATH \
+  CUDACXX=/usr/local/cuda/bin/nvcc \
+  CMAKE_ARGS="-DGGML_CUDA=on" \
+  FORCE_CMAKE=1 \
+  ./.venv-reranker-gguf/bin/pip install --no-cache-dir --force-reinstall --no-build-isolation llama-cpp-python==0.3.18
   ```
  
 ## 配置
-- **后端选择**：`config/config.yaml` 中 `services.rerank.backend`（`qwen3_vllm` | `qwen3_transformers` | `bge` | `dashscope_rerank`），或环境变量 `RERANK_BACKEND`。
+- **后端选择**：`config/config.yaml` 中 `services.rerank.backend`（`qwen3_vllm` | `qwen3_vllm_score` | `qwen3_transformers` | `qwen3_transformers_packed` | `qwen3_gguf` | `qwen3_gguf_06b` | `bge` | `dashscope_rerank`），或环境变量 `RERANK_BACKEND`。
 - **后端参数**：`services.rerank.backends.bge` / `services.rerank.backends.qwen3_vllm`，例如：
  
 ```yaml
 services:
   rerank:
-    backend: "qwen3_vllm"   # 或 bge
+    backend: "qwen3_gguf"   # 或 qwen3_vllm / bge
     backends:
       bge:
         model_name: "BAAI/bge-reranker-v2-m3"
@@ -65,6 +88,44 @@ services:
         tensor_parallel_size: 1
         gpu_memory_utilization: 0.8
         instruction: "Given a shopping query, rank product titles by relevance"
+      qwen3_transformers_packed:
+        model_name: "Qwen/Qwen3-Reranker-0.6B"
+        instruction: "Rank products by query with category & style match prioritized"
+        max_model_len: 4096
+        max_doc_len: 160
+        max_docs_per_pack: 0
+        use_fp16: true
+        sort_by_doc_length: true
+        attn_implementation: "eager"
+      qwen3_gguf:
+        repo_id: "DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF"
+        filename: "*Q8_0.gguf"
+        local_dir: "./models/reranker/qwen3-reranker-4b-gguf"
+        cache_dir: "./model_cache"
+        instruction: "Rank products by query with category & style match prioritized"
+        n_ctx: 384
+        n_batch: 384
+        n_ubatch: 128
+        n_gpu_layers: 24
+        flash_attn: true
+        offload_kqv: true
+        infer_batch_size: 8
+        sort_by_doc_length: true
+        length_sort_mode: "char"
+      qwen3_gguf_06b:
+        repo_id: "ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF"
+        filename: "qwen3-reranker-0.6b-q8_0.gguf"
+        local_dir: "./models/reranker/qwen3-reranker-0.6b-q8_0-gguf"
+        cache_dir: "./model_cache"
+        instruction: "Rank products by query with category & style match prioritized"
+        n_ctx: 256
+        n_batch: 256
+        n_ubatch: 256
+        n_gpu_layers: 999
+        infer_batch_size: 32
+        sort_by_doc_length: true
+        length_sort_mode: "char"
+        reuse_query_state: false
       dashscope_rerank:
         model_name: "qwen3-rerank"
         endpoint: "https://dashscope.aliyuncs.com/compatible-api/v1/reranks"
@@ -94,7 +155,7 @@ DashScope 认证：
 ```bash
 ./scripts/start_reranker.sh
 ```
-该脚本会使用隔离环境 `.venv-reranker`；首次请先执行 `./scripts/setup_reranker_venv.sh`。
+该脚本会按当前 `services.rerank.backend` 自动选择对应的独立 venv；首次请先执行 `./scripts/setup_reranker_venv.sh <backend>`。
  
 ## 性能压测（1000 docs）
 ```bash
@@ -122,7 +183,7 @@ Content-Type: application/json
 ```
  
 `top_n` 为可选字段：
-- 对本地后端（`qwen3_vllm` / `qwen3_transformers` / `bge`）通常会忽略，仍返回全量分数。
+- 对本地后端（`qwen3_vllm` / `qwen3_transformers` / `qwen3_transformers_packed` / `qwen3_gguf` / `qwen3_gguf_06b` / `bge`）通常会忽略，仍返回全量分数。
 - 对 `dashscope_rerank` 可用于控制云端返回的候选量，建议设置为 `page+size`（例如分页 `from=20,size=10` 时传 `30`）。
  
 Response:
@@ -160,3 +221,6 @@ uvicorn reranker.server:app --host 0.0.0.0 --port 6007 --log-level info
 - 运行时可用环境变量临时覆盖批量参数：`RERANK_VLLM_INFER_BATCH_SIZE`、`RERANK_VLLM_SORT_BY_DOC_LENGTH`。
 - **Qwen3-vLLM**：参考 [Qwen3-Reranker-0.6B](https://huggingface.co/Qwen/Qwen3-Reranker-0.6B)，需 GPU 与较多显存；与 BGE 相比适合长文本、高吞吐场景（vLLM 前缀缓存）。
 - **Qwen3-Transformers**：官方 Transformers Usage 方式，无需 vLLM；适合 CPU 或小显存。默认 `attn_implementation: "sdpa"`；若已安装 `flash_attn` 可设 `flash_attention_2`（未安装时服务会自动回退到 sdpa）。
+- **Qwen3-Transformers-Packed**：仍使用 Hugging Face Transformers 与 PyTorch CUDA 内核，只定制 packed 输入、`position_ids` 和 4D `attention_mask`。它更适合在线检索里的“一个 query 对几百个短 doc”场景；默认 `attn_implementation: "eager"` 以保证自定义 mask 兼容性，若你的 `torch/transformers` 版本已验证支持，可再压测 `"sdpa"`。
+- **Qwen3-GGUF**：参考 [DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF](https://huggingface.co/DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF)。单卡 T4 且仅剩约 `4.8~6GB` 显存时，推荐 `Q8_0 + n_ctx=384 + n_gpu_layers=24 + flash_attn=true + offload_kqv=true` 起步；若启动 OOM，优先把 `n_gpu_layers` 下调到 `20`，再把 `n_ctx` 下调到 `320`。`infer_batch_size` 在 GGUF 后端是服务侧 work chunk，大多不如 `n_gpu_layers` / `n_ctx` 关键。
+- **Qwen3-GGUF-0.6B**：参考 [ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF](https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF)。它的优点是权重小、显存占用低，单进程实测约 `0.9~1.1 GiB`；但在当前 llama.cpp 串行打分接法下，`1 query + 400 titles` 的实测延迟仍约 `265s`。因此它更适合低显存功能后备，不适合作为在线低延迟主 reranker。
@@ -43,14 +43,32 @@ def get_rerank_backend(name: str, config: Dict[str, Any]) -&gt; RerankBackendProtoc
     if name == "qwen3_vllm":
         from reranker.backends.qwen3_vllm import Qwen3VLLMRerankerBackend
         return Qwen3VLLMRerankerBackend(config)
+    if name == "qwen3_vllm_score":
+        from reranker.backends.qwen3_vllm_score import Qwen3VLLMScoreRerankerBackend
+        return Qwen3VLLMScoreRerankerBackend(config)
     if name == "qwen3_transformers":
         from reranker.backends.qwen3_transformers import Qwen3TransformersRerankerBackend
         return Qwen3TransformersRerankerBackend(config)
+    if name == "qwen3_transformers_packed":
+        from reranker.backends.qwen3_transformers_packed import (
+            Qwen3TransformersPackedRerankerBackend,
+        )
+        return Qwen3TransformersPackedRerankerBackend(config)
+    if name == "qwen3_gguf":
+        from reranker.backends.qwen3_gguf import Qwen3GGUFRerankerBackend
+        gguf_config = dict(config or {})
+        gguf_config.setdefault("_backend_name", "qwen3_gguf")
+        return Qwen3GGUFRerankerBackend(gguf_config)
+    if name == "qwen3_gguf_06b":
+        from reranker.backends.qwen3_gguf import Qwen3GGUFRerankerBackend
+        gguf_config = dict(config or {})
+        gguf_config.setdefault("_backend_name", "qwen3_gguf_06b")
+        return Qwen3GGUFRerankerBackend(gguf_config)
     if name == "dashscope_rerank":
         from reranker.backends.dashscope_rerank import DashScopeRerankBackend
         return DashScopeRerankBackend(config)
     raise ValueError(
-        f"Unknown rerank backend: {name!r}. Supported: bge, qwen3_vllm, qwen3_transformers, dashscope_rerank"
+        f"Unknown rerank backend: {name!r}. Supported: bge, qwen3_vllm, qwen3_vllm_score, qwen3_transformers, qwen3_transformers_packed, qwen3_gguf, qwen3_gguf_06b, dashscope_rerank"
     )
  
  
@@ -0,0 +1,408 @@
+"""
+Qwen3-Reranker GGUF backend using llama-cpp-python.
+
+Reference:
+- https://huggingface.co/DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF
+- https://huggingface.co/Qwen/Qwen3-Reranker-4B
+- https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF
+- https://huggingface.co/Qwen/Qwen3-Reranker-0.6B
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+
+logger = logging.getLogger("reranker.backends.qwen3_gguf")
+
+
+_BACKEND_DEFAULTS: Dict[str, Dict[str, str]] = {
+    "qwen3_gguf": {
+        "repo_id": "DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF",
+        "filename": "*Q8_0.gguf",
+        "local_dir": "./models/reranker/qwen3-reranker-4b-gguf",
+    },
+    "qwen3_gguf_06b": {
+        "repo_id": "ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF",
+        "filename": "qwen3-reranker-0.6b-q8_0.gguf",
+        "local_dir": "./models/reranker/qwen3-reranker-0.6b-q8_0-gguf",
+    },
+}
+
+
+def deduplicate_with_positions(texts: List[str]) -> Tuple[List[str], List[int]]:
+    """Deduplicate texts globally while preserving first-seen order."""
+    unique_texts: List[str] = []
+    position_to_unique: List[int] = []
+    seen: Dict[str, int] = {}
+
+    for text in texts:
+        idx = seen.get(text)
+        if idx is None:
+            idx = len(unique_texts)
+            seen[text] = idx
+            unique_texts.append(text)
+        position_to_unique.append(idx)
+
+    return unique_texts, position_to_unique
+
+
+def _format_instruction(instruction: str, query: str, doc: str) -> str:
+    return "<Instruct>: {instruction}\n<Query>: {query}\n<Document>: {doc}".format(
+        instruction=instruction,
+        query=query,
+        doc=doc,
+    )
+
+
+class Qwen3GGUFRerankerBackend:
+    """
+    Qwen3-Reranker GGUF backend using llama.cpp through llama-cpp-python.
+
+    Tuned for short-query / short-doc reranking on a single GPU.
+    Config from services.rerank.backends.<backend_name>.
+    """
+
+    def __init__(self, config: Dict[str, Any]) -> None:
+        self._config = config or {}
+        self._backend_name = str(self._config.get("_backend_name") or "qwen3_gguf").strip()
+        defaults = _BACKEND_DEFAULTS.get(self._backend_name, _BACKEND_DEFAULTS["qwen3_gguf"])
+        self._repo_id = str(self._config.get("repo_id") or defaults["repo_id"]).strip()
+        self._filename = str(self._config.get("filename") or defaults["filename"]).strip()
+        self._model_path = str(self._config.get("model_path") or "").strip()
+        self._cache_dir = str(self._config.get("cache_dir") or "").strip() or None
+        self._local_dir = str(self._config.get("local_dir") or defaults["local_dir"]).strip() or None
+        self._instruction = str(
+            self._config.get("instruction")
+            or "Rank products by query with category & style match prioritized"
+        )
+        self._infer_batch_size = int(
+            os.getenv("RERANK_GGUF_INFER_BATCH_SIZE") or self._config.get("infer_batch_size", 8)
+        )
+        sort_by_doc_length = os.getenv("RERANK_GGUF_SORT_BY_DOC_LENGTH")
+        if sort_by_doc_length is None:
+            sort_by_doc_length = self._config.get("sort_by_doc_length", True)
+        self._sort_by_doc_length = str(sort_by_doc_length).strip().lower() in {
+            "1",
+            "true",
+            "yes",
+            "y",
+            "on",
+        }
+        self._length_sort_mode = str(self._config.get("length_sort_mode") or "char").strip().lower()
+        self._reuse_query_state = bool(self._config.get("reuse_query_state", False))
+
+        n_ctx = int(self._config.get("n_ctx", self._config.get("max_model_len", 384)))
+        n_batch = int(self._config.get("n_batch", min(n_ctx, 384)))
+        n_ubatch = int(self._config.get("n_ubatch", min(n_batch, 128)))
+        n_gpu_layers = int(self._config.get("n_gpu_layers", 24))
+        main_gpu = int(self._config.get("main_gpu", 0))
+        n_threads = int(self._config.get("n_threads", 2))
+        n_threads_batch = int(self._config.get("n_threads_batch", 4))
+        flash_attn = bool(self._config.get("flash_attn", True))
+        offload_kqv = bool(self._config.get("offload_kqv", True))
+        use_mmap = bool(self._config.get("use_mmap", True))
+        use_mlock = bool(self._config.get("use_mlock", False))
+        verbose = bool(self._config.get("verbose", False))
+        enable_warmup = bool(self._config.get("enable_warmup", True))
+
+        if self._infer_batch_size <= 0:
+            raise ValueError(f"infer_batch_size must be > 0, got {self._infer_batch_size}")
+        if n_ctx <= 0:
+            raise ValueError(f"n_ctx must be > 0, got {n_ctx}")
+        if n_batch <= 0 or n_ubatch <= 0:
+            raise ValueError(f"n_batch/n_ubatch must be > 0, got {n_batch}/{n_ubatch}")
+
+        try:
+            from llama_cpp import Llama
+        except Exception as exc:  # pragma: no cover - depends on optional dependency
+            raise RuntimeError(
+                f"{self._backend_name} backend requires llama-cpp-python. "
+                f"Install the {self._backend_name} backend venv first via "
+                f"scripts/setup_reranker_venv.sh {self._backend_name}."
+            ) from exc
+
+        self._llama_class = Llama
+        self._n_ctx = n_ctx
+        self._n_batch = n_batch
+        self._n_ubatch = n_ubatch
+        self._n_gpu_layers = n_gpu_layers
+        self._enable_warmup = enable_warmup
+        self._infer_lock = threading.Lock()
+
+        logger.info(
+            "[Qwen3_GGUF] Loading backend=%s repo=%s filename=%s model_path=%s n_ctx=%s n_batch=%s n_ubatch=%s n_gpu_layers=%s flash_attn=%s offload_kqv=%s reuse_query_state=%s",
+            self._backend_name,
+            self._repo_id,
+            self._filename,
+            self._model_path or None,
+            n_ctx,
+            n_batch,
+            n_ubatch,
+            n_gpu_layers,
+            flash_attn,
+            offload_kqv,
+            self._reuse_query_state,
+        )
+
+        llm_kwargs = {
+            "n_ctx": n_ctx,
+            "n_batch": n_batch,
+            "n_ubatch": n_ubatch,
+            "n_gpu_layers": n_gpu_layers,
+            "main_gpu": main_gpu,
+            "n_threads": n_threads,
+            "n_threads_batch": n_threads_batch,
+            "logits_all": True,
+            "offload_kqv": offload_kqv,
+            "flash_attn": flash_attn,
+            "use_mmap": use_mmap,
+            "use_mlock": use_mlock,
+            "verbose": verbose,
+        }
+        llm_kwargs = {key: value for key, value in llm_kwargs.items() if value is not None}
+        self._llm = self._load_model(llm_kwargs)
+        self._model_name = self._model_path or f"{self._repo_id}:{self._filename}"
+
+        self._prefix = (
+            "<|im_start|>system\n"
+            "Judge whether the Document meets the requirements based on the Query and the Instruct provided. "
+            'Note that the answer can only be "yes" or "no".'
+            "<|im_end|>\n<|im_start|>user\n"
+        )
+        self._suffix = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"
+        self._prefix_tokens = self._tokenize(self._prefix, special=True)
+        self._suffix_tokens = self._tokenize(self._suffix, special=True)
+        self._request_prefix_template = "<Instruct>: {instruction}\n<Query>: {query}\n<Document>: "
+        self._effective_max_len = self._n_ctx - len(self._prefix_tokens) - len(self._suffix_tokens)
+        if self._effective_max_len <= 16:
+            raise RuntimeError(
+                f"n_ctx={self._n_ctx} is too small after prompt overhead; effective={self._effective_max_len}"
+            )
+
+        self._true_token = self._single_token_id("yes")
+        self._false_token = self._single_token_id("no")
+
+        if self._enable_warmup:
+            self._warmup()
+
+        logger.info(
+            "[Qwen3_GGUF] Model ready | backend=%s model=%s effective_max_len=%s infer_batch_size=%s sort_by_doc_length=%s",
+            self._backend_name,
+            self._model_name,
+            self._effective_max_len,
+            self._infer_batch_size,
+            self._sort_by_doc_length,
+        )
+
+    def _load_model(self, llm_kwargs: Dict[str, Any]):
+        if self._model_path:
+            return self._llama_class(model_path=self._model_path, **llm_kwargs)
+        if self._local_dir:
+            matches = sorted(
+                path for path in Path(self._local_dir).glob(self._filename) if path.is_file()
+            )
+            if matches:
+                local_model_path = str(matches[0].resolve())
+                logger.info("[Qwen3_GGUF] Using local GGUF file: %s", local_model_path)
+                return self._llama_class(model_path=local_model_path, **llm_kwargs)
+        return self._llama_class.from_pretrained(
+            repo_id=self._repo_id,
+            filename=self._filename,
+            local_dir=self._local_dir,
+            cache_dir=self._cache_dir,
+            **llm_kwargs,
+        )
+
+    def _tokenize(self, text: str, *, special: bool) -> List[int]:
+        return list(
+            self._llm.tokenize(
+                text.encode("utf-8"),
+                add_bos=False,
+                special=special,
+            )
+        )
+
+    def _single_token_id(self, text: str) -> int:
+        token_ids = self._tokenize(text, special=False)
+        if len(token_ids) != 1:
+            raise RuntimeError(f"Expected {text!r} to be one token, got {token_ids}")
+        return int(token_ids[0])
+
+    def _warmup(self) -> None:
+        try:
+            prompt = self._build_prompt_tokens("warmup query", "warmup document")
+            with self._infer_lock:
+                self._eval_logits(prompt)
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.warning("[Qwen3_GGUF] Warmup failed: %s", exc)
+
+    def _build_request_prefix_tokens(self, query: str) -> List[int]:
+        request_prefix = self._request_prefix_template.format(
+            instruction=self._instruction,
+            query=query,
+        )
+        return self._tokenize(request_prefix, special=False)
+
+    def _build_prompt_tokens(self, query: str, doc: str) -> List[int]:
+        pair = _format_instruction(self._instruction, query, doc)
+        pair_tokens = self._tokenize(pair, special=False)
+        pair_tokens = pair_tokens[: self._effective_max_len]
+        return self._prefix_tokens + pair_tokens + self._suffix_tokens
+
+    def _eval_logits(self, prompt_tokens: List[int]) -> List[float]:
+        self._llm.reset()
+        self._llm.eval(prompt_tokens)
+        logits = self._llm.eval_logits
+        if not logits:
+            raise RuntimeError("llama.cpp returned empty logits")
+        return list(logits[-1])
+
+    def _score_prompt(self, prompt_tokens: List[int]) -> float:
+        logits = self._eval_logits(prompt_tokens)
+        true_logit = float(logits[self._true_token])
+        false_logit = float(logits[self._false_token])
+        max_logit = max(true_logit, false_logit)
+        true_exp = math.exp(true_logit - max_logit)
+        false_exp = math.exp(false_logit - max_logit)
+        return float(true_exp / (true_exp + false_exp))
+
+    def _supports_query_state_reuse(self) -> bool:
+        return (
+            self._reuse_query_state
+            and hasattr(self._llm, "save_state")
+            and hasattr(self._llm, "load_state")
+        )
+
+    def _build_query_state_locked(self, query: str):
+        request_prefix_tokens = self._build_request_prefix_tokens(query)
+        max_doc_tokens = self._effective_max_len - len(request_prefix_tokens)
+        if max_doc_tokens <= 0:
+            return None, 0
+        self._llm.reset()
+        self._llm.eval(self._prefix_tokens + request_prefix_tokens)
+        return self._llm.save_state(), max_doc_tokens
+
+    def _score_doc_with_state_locked(self, state, doc_tokens: List[int], max_doc_tokens: int) -> float:
+        self._llm.load_state(state)
+        self._llm.eval(doc_tokens[:max_doc_tokens] + self._suffix_tokens)
+        logits = self._llm.eval_logits
+        if not logits:
+            raise RuntimeError("llama.cpp returned empty logits")
+        final_logits = list(logits[-1])
+        true_logit = float(final_logits[self._true_token])
+        false_logit = float(final_logits[self._false_token])
+        max_logit = max(true_logit, false_logit)
+        true_exp = math.exp(true_logit - max_logit)
+        false_exp = math.exp(false_logit - max_logit)
+        return float(true_exp / (true_exp + false_exp))
+
+    def _estimate_doc_lengths(self, docs: List[str]) -> List[int]:
+        if self._length_sort_mode == "token":
+            return [len(self._tokenize(text, special=False)) for text in docs]
+        return [len(text) for text in docs]
+
+    def score_with_meta(
+        self,
+        query: str,
+        docs: List[str],
+        normalize: bool = True,
+    ) -> Tuple[List[float], Dict[str, Any]]:
+        start_ts = time.time()
+        total_docs = len(docs) if docs else 0
+        output_scores: List[float] = [0.0] * total_docs
+
+        query = "" if query is None else str(query).strip()
+        indexed: List[Tuple[int, str]] = []
+        for i, doc in enumerate(docs or []):
+            if doc is None:
+                continue
+            text = str(doc).strip()
+            if not text:
+                continue
+            indexed.append((i, text))
+
+        if not query or not indexed:
+            elapsed_ms = (time.time() - start_ts) * 1000.0
+            return output_scores, {
+                "input_docs": total_docs,
+                "usable_docs": len(indexed),
+                "unique_docs": 0,
+                "dedup_ratio": 0.0,
+                "elapsed_ms": round(elapsed_ms, 3),
+                "model": self._model_name,
+                "backend": self._backend_name,
+                "normalize": normalize,
+                "infer_batch_size": self._infer_batch_size,
+                "inference_batches": 0,
+                "sort_by_doc_length": self._sort_by_doc_length,
+                "n_ctx": self._n_ctx,
+                "n_batch": self._n_batch,
+                "n_ubatch": self._n_ubatch,
+                "n_gpu_layers": self._n_gpu_layers,
+            }
+
+        indexed_texts = [text for _, text in indexed]
+        unique_texts, position_to_unique = deduplicate_with_positions(indexed_texts)
+
+        lengths = self._estimate_doc_lengths(unique_texts)
+        order = list(range(len(unique_texts)))
+        if self._sort_by_doc_length and len(unique_texts) > 1:
+            order = sorted(order, key=lambda i: lengths[i])
+
+        unique_scores: List[float] = [0.0] * len(unique_texts)
+        unique_doc_tokens = [self._tokenize(text, special=False) for text in unique_texts]
+        inference_batches = 0
+        with self._infer_lock:
+            query_state = None
+            max_doc_tokens = self._effective_max_len
+            if self._supports_query_state_reuse():
+                query_state, max_doc_tokens = self._build_query_state_locked(query)
+            for start in range(0, len(order), self._infer_batch_size):
+                batch_indices = order[start : start + self._infer_batch_size]
+                inference_batches += 1
+                for idx in batch_indices:
+                    if query_state is not None:
+                        unique_scores[idx] = self._score_doc_with_state_locked(
+                            query_state,
+                            unique_doc_tokens[idx],
+                            max_doc_tokens,
+                        )
+                    else:
+                        prompt = self._build_prompt_tokens(query, unique_texts[idx])
+                        unique_scores[idx] = self._score_prompt(prompt)
+
+        for (orig_idx, _), unique_idx in zip(indexed, position_to_unique):
+            output_scores[orig_idx] = float(unique_scores[unique_idx])
+
+        elapsed_ms = (time.time() - start_ts) * 1000.0
+        dedup_ratio = 0.0
+        if indexed:
+            dedup_ratio = 1.0 - (len(unique_texts) / float(len(indexed)))
+
+        meta = {
+            "input_docs": total_docs,
+            "usable_docs": len(indexed),
+            "unique_docs": len(unique_texts),
+            "dedup_ratio": round(dedup_ratio, 4),
+            "elapsed_ms": round(elapsed_ms, 3),
+            "model": self._model_name,
+            "backend": self._backend_name,
+            "normalize": normalize,
+            "infer_batch_size": self._infer_batch_size,
+            "inference_batches": inference_batches,
+            "sort_by_doc_length": self._sort_by_doc_length,
+            "length_sort_mode": self._length_sort_mode,
+            "n_ctx": self._n_ctx,
+            "n_batch": self._n_batch,
+            "n_ubatch": self._n_ubatch,
+            "n_gpu_layers": self._n_gpu_layers,
+            "reuse_query_state": query_state is not None,
+        }
+        return output_scores, meta
@@ -0,0 +1,398 @@
+"""
+Qwen3-Reranker backend using packed inference with Transformers.
+
+This backend implements the sequence stitching optimization described in
+Qwen3-Reranker packed inference examples:
+1. Share the query/instruction prefix across many documents.
+2. Reset document ``position_ids`` relative to the shared prefix.
+3. Use a custom causal attention mask so each document can attend to the
+   prefix and itself, but never to other documents.
+
+Compared with the standard per-pair batching path, this reduces repeated
+prefix computation and removes inter-sample padding waste. For online search
+requests like ``1 query + 400 docs``, the backend further packs documents into
+multiple chunks under a configurable total token budget.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any, Dict, List, Sequence, Tuple
+
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+logger = logging.getLogger("reranker.backends.qwen3_transformers_packed")
+
+_DEFAULT_PREFIX = (
+    "<|im_start|>system\n"
+    "Judge whether the Document meets the requirements based on the Query and the Instruct "
+    'provided. Note that the answer can only be "yes" or "no".'
+    "<|im_end|>\n<|im_start|>user\n"
+)
+_DEFAULT_SUFFIX = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"
+_DEFAULT_PAIR_PREFIX_TEMPLATE = "{prefix}<Instruct>: {instruction}\n<Query>: {query}\n<Document>: "
+
+
+def _deduplicate_with_positions(texts: Sequence[str]) -> Tuple[List[str], List[int]]:
+    unique_texts: List[str] = []
+    position_to_unique: List[int] = []
+    seen: Dict[str, int] = {}
+
+    for text in texts:
+        idx = seen.get(text)
+        if idx is None:
+            idx = len(unique_texts)
+            seen[text] = idx
+            unique_texts.append(text)
+        position_to_unique.append(idx)
+
+    return unique_texts, position_to_unique
+
+
+class Qwen3TransformersPackedRerankerBackend:
+    """
+    Qwen3-Reranker packed inference backend using Transformers.
+
+    Config from ``services.rerank.backends.qwen3_transformers_packed``.
+    """
+
+    def __init__(self, config: Dict[str, Any]) -> None:
+        self._config = config or {}
+        model_name = str(self._config.get("model_name") or "Qwen/Qwen3-Reranker-0.6B")
+        self._instruction = str(
+            self._config.get("instruction")
+            or "Rank products by query with category & style match prioritized"
+        )
+        self._prefix = str(self._config.get("prompt_prefix") or _DEFAULT_PREFIX)
+        self._suffix = str(self._config.get("prompt_suffix") or _DEFAULT_SUFFIX)
+        self._pair_prefix_template = str(
+            self._config.get("pair_prefix_template") or _DEFAULT_PAIR_PREFIX_TEMPLATE
+        )
+
+        max_model_len = int(self._config.get("max_model_len", 4096))
+        max_doc_len = int(self._config.get("max_doc_len", 160))
+        max_docs_per_pack = int(self._config.get("max_docs_per_pack", 0))
+        use_fp16 = bool(self._config.get("use_fp16", True))
+        device = self._config.get("device")
+        attn_impl = str(self._config.get("attn_implementation") or "eager").strip()
+        sort_by_doc_length = self._config.get("sort_by_doc_length", True)
+
+        self._model_name = model_name
+        self._max_model_len = max_model_len
+        self._max_doc_len = max_doc_len
+        self._max_docs_per_pack = max_docs_per_pack
+        self._sort_by_doc_length = str(sort_by_doc_length).strip().lower() in {
+            "1",
+            "true",
+            "yes",
+            "y",
+            "on",
+        }
+        self._attn_impl = attn_impl
+
+        logger.info(
+            "[Qwen3_Transformers_Packed] Loading model %s (max_model_len=%s, max_doc_len=%s, "
+            "max_docs_per_pack=%s, fp16=%s, attn_impl=%s)",
+            model_name,
+            max_model_len,
+            max_doc_len,
+            max_docs_per_pack,
+            use_fp16,
+            attn_impl,
+        )
+
+        self._tokenizer = AutoTokenizer.from_pretrained(model_name, padding_side="left")
+        self._tokenizer.pad_token = self._tokenizer.eos_token
+
+        self._prefix_tokens = self._tokenizer.encode(self._prefix, add_special_tokens=False)
+        self._suffix_tokens = self._tokenizer.encode(self._suffix, add_special_tokens=False)
+        self._suffix_len = len(self._suffix_tokens)
+
+        if not torch.cuda.is_available():
+            raise RuntimeError(
+                "qwen3_transformers_packed backend requires CUDA GPU, "
+                "but torch.cuda.is_available() is False"
+            )
+
+        kwargs: Dict[str, Any] = {}
+        if use_fp16:
+            kwargs["torch_dtype"] = torch.float16
+        if attn_impl:
+            kwargs["attn_implementation"] = attn_impl
+
+        self._model = AutoModelForCausalLM.from_pretrained(model_name, **kwargs).eval()
+        target_device = str(device).strip() if device is not None else "cuda"
+        if not target_device.startswith("cuda"):
+            raise ValueError(
+                "qwen3_transformers_packed backend is GPU-only. "
+                f"Unsupported device setting: {target_device!r}"
+            )
+        self._model = self._model.to(target_device)
+        self._device = next(self._model.parameters()).device
+        if self._device.type != "cuda":
+            raise RuntimeError(
+                "qwen3_transformers_packed backend failed to place model on CUDA. "
+                f"Current device: {self._device}"
+            )
+
+        self._token_true_id = self._tokenizer.convert_tokens_to_ids("yes")
+        self._token_false_id = self._tokenizer.convert_tokens_to_ids("no")
+        if self._token_true_id is None or self._token_false_id is None:
+            raise RuntimeError("Failed to resolve Qwen3 reranker classifier token ids for yes/no")
+
+        prefix_budget = len(self._prefix_tokens) + self._suffix_len + 1
+        if self._max_model_len <= prefix_budget:
+            raise ValueError(
+                "max_model_len is too small for packed reranking. "
+                f"Need > {prefix_budget}, got {self._max_model_len}."
+            )
+        if self._max_doc_len <= 0:
+            raise ValueError(f"max_doc_len must be > 0, got {self._max_doc_len}")
+        if self._max_docs_per_pack < 0:
+            raise ValueError(
+                f"max_docs_per_pack must be >= 0, got {self._max_docs_per_pack}"
+            )
+
+        self._infer_lock = threading.Lock()
+
+        logger.info(
+            "[Qwen3_Transformers_Packed] Model ready | model=%s device=%s",
+            model_name,
+            self._device,
+        )
+
+    def _build_pair_prefix_tokens(self, query: str) -> List[int]:
+        pair_prefix = self._pair_prefix_template.format(
+            prefix=self._prefix,
+            instruction=self._instruction,
+            query=query,
+        )
+        return self._tokenizer.encode(pair_prefix, add_special_tokens=False)
+
+    def _tokenize_documents(self, docs: Sequence[str], query_prefix_len: int) -> List[List[int]]:
+        max_doc_tokens = min(
+            self._max_doc_len,
+            max(1, self._max_model_len - query_prefix_len - self._suffix_len),
+        )
+        tokenized = self._tokenizer(
+            list(docs),
+            padding=False,
+            truncation=True,
+            max_length=max_doc_tokens,
+            add_special_tokens=False,
+            return_attention_mask=False,
+        )
+        return [list(ids) for ids in tokenized["input_ids"]]
+
+    def _build_pack_plan(
+        self,
+        query_prefix_len: int,
+        doc_tokens: Sequence[Sequence[int]],
+    ) -> List[List[int]]:
+        order = list(range(len(doc_tokens)))
+        if self._sort_by_doc_length and len(order) > 1:
+            order.sort(key=lambda idx: len(doc_tokens[idx]))
+
+        packs: List[List[int]] = []
+        current_pack: List[int] = []
+        current_len = query_prefix_len
+        for idx in order:
+            packed_doc_len = len(doc_tokens[idx]) + self._suffix_len
+            if packed_doc_len <= 0:
+                continue
+
+            over_docs_cap = self._max_docs_per_pack > 0 and len(current_pack) >= self._max_docs_per_pack
+            over_token_cap = current_pack and (current_len + packed_doc_len > self._max_model_len)
+            if over_docs_cap or over_token_cap:
+                packs.append(current_pack)
+                current_pack = []
+                current_len = query_prefix_len
+
+            if query_prefix_len + packed_doc_len > self._max_model_len:
+                raise ValueError(
+                    "Packed doc still exceeds max_model_len after truncation. "
+                    f"query_prefix_len={query_prefix_len}, doc_len={packed_doc_len}, "
+                    f"max_model_len={self._max_model_len}"
+                )
+
+            current_pack.append(idx)
+            current_len += packed_doc_len
+
+        if current_pack:
+            packs.append(current_pack)
+        return packs
+
+    def _build_pack_inputs(
+        self,
+        query_prefix_tokens: Sequence[int],
+        doc_tokens: Sequence[Sequence[int]],
+        doc_indices: Sequence[int],
+    ) -> Tuple[Dict[str, torch.Tensor], torch.Tensor]:
+        prefix_len = len(query_prefix_tokens)
+        input_ids_list = list(query_prefix_tokens)
+        position_ids_list = list(range(prefix_len))
+        spans: List[Tuple[int, int]] = []
+        current_len = prefix_len
+
+        for idx in doc_indices:
+            doc_with_suffix = list(doc_tokens[idx]) + self._suffix_tokens
+            start = current_len
+            end = start + len(doc_with_suffix)
+            spans.append((start, end))
+            input_ids_list.extend(doc_with_suffix)
+            position_ids_list.extend(range(prefix_len, prefix_len + len(doc_with_suffix)))
+            current_len = end
+
+        total_len = len(input_ids_list)
+        device = self._device
+        neg_inf = torch.finfo(torch.float32).min
+
+        allowed = torch.zeros((total_len, total_len), dtype=torch.bool, device=device)
+        prefix_causal = torch.tril(
+            torch.ones((prefix_len, prefix_len), dtype=torch.bool, device=device)
+        )
+        allowed[:prefix_len, :prefix_len] = prefix_causal
+        for start, end in spans:
+            allowed[start:end, :prefix_len] = True
+            doc_len = end - start
+            allowed[start:end, start:end] = torch.tril(
+                torch.ones((doc_len, doc_len), dtype=torch.bool, device=device)
+            )
+
+        attention_mask = torch.full(
+            (total_len, total_len),
+            neg_inf,
+            dtype=torch.float32,
+            device=device,
+        )
+        attention_mask.masked_fill_(allowed, 0.0)
+
+        inputs = {
+            "input_ids": torch.tensor([input_ids_list], dtype=torch.long, device=device),
+            "position_ids": torch.tensor([position_ids_list], dtype=torch.long, device=device),
+            "attention_mask": attention_mask.view(1, 1, total_len, total_len),
+        }
+        logits_ids = torch.tensor(
+            [end - 1 for _, end in spans],
+            dtype=torch.long,
+            device=device,
+        )
+        return inputs, logits_ids
+
+    @torch.no_grad()
+    def _score_pack(
+        self,
+        query_prefix_tokens: Sequence[int],
+        doc_tokens: Sequence[Sequence[int]],
+        doc_indices: Sequence[int],
+    ) -> Tuple[List[float], int]:
+        inputs, logits_ids = self._build_pack_inputs(
+            query_prefix_tokens=query_prefix_tokens,
+            doc_tokens=doc_tokens,
+            doc_indices=doc_indices,
+        )
+        outputs = self._model(**inputs)
+        scores = outputs.logits[0, logits_ids, :]
+        true_vector = scores[:, self._token_true_id]
+        false_vector = scores[:, self._token_false_id]
+        pair_scores = torch.stack([false_vector, true_vector], dim=1)
+        pair_scores = torch.nn.functional.log_softmax(pair_scores, dim=1)
+        return pair_scores[:, 1].exp().tolist(), int(inputs["input_ids"].shape[1])
+
+    def score_with_meta(
+        self,
+        query: str,
+        docs: List[str],
+        normalize: bool = True,
+    ) -> Tuple[List[float], Dict[str, Any]]:
+        start_ts = time.time()
+        total_docs = len(docs) if docs else 0
+        output_scores: List[float] = [0.0] * total_docs
+
+        query = "" if query is None else str(query).strip()
+        indexed: List[Tuple[int, str]] = []
+        for i, doc in enumerate(docs or []):
+            if doc is None:
+                continue
+            text = str(doc).strip()
+            if not text:
+                continue
+            indexed.append((i, text))
+
+        if not query or not indexed:
+            elapsed_ms = (time.time() - start_ts) * 1000.0
+            return output_scores, {
+                "input_docs": total_docs,
+                "usable_docs": len(indexed),
+                "unique_docs": 0,
+                "dedup_ratio": 0.0,
+                "elapsed_ms": round(elapsed_ms, 3),
+                "model": self._model_name,
+                "backend": "qwen3_transformers_packed",
+                "normalize": normalize,
+                "packed_batches": 0,
+                "max_model_len": self._max_model_len,
+                "max_doc_len": self._max_doc_len,
+                "sort_by_doc_length": self._sort_by_doc_length,
+            }
+
+        indexed_texts = [text for _, text in indexed]
+        unique_texts, position_to_unique = _deduplicate_with_positions(indexed_texts)
+
+        query_prefix_tokens = self._build_pair_prefix_tokens(query)
+        doc_tokens = self._tokenize_documents(unique_texts, query_prefix_len=len(query_prefix_tokens))
+        pack_plan = self._build_pack_plan(
+            query_prefix_len=len(query_prefix_tokens),
+            doc_tokens=doc_tokens,
+        )
+
+        unique_scores: List[float] = [0.0] * len(unique_texts)
+        pack_lengths: List[int] = []
+        with self._infer_lock:
+            for pack_doc_indices in pack_plan:
+                batch_scores, pack_seq_len = self._score_pack(
+                    query_prefix_tokens=query_prefix_tokens,
+                    doc_tokens=doc_tokens,
+                    doc_indices=pack_doc_indices,
+                )
+                if len(batch_scores) != len(pack_doc_indices):
+                    raise RuntimeError(
+                        "Packed reranker score size mismatch: "
+                        f"expected {len(pack_doc_indices)}, got {len(batch_scores)}"
+                    )
+                for idx, score in zip(pack_doc_indices, batch_scores):
+                    unique_scores[idx] = float(score)
+                pack_lengths.append(pack_seq_len)
+
+        for (orig_idx, _), unique_idx in zip(indexed, position_to_unique):
+            output_scores[orig_idx] = float(unique_scores[unique_idx])
+
+        elapsed_ms = (time.time() - start_ts) * 1000.0
+        dedup_ratio = 0.0
+        if indexed:
+            dedup_ratio = 1.0 - (len(unique_texts) / float(len(indexed)))
+
+        meta = {
+            "input_docs": total_docs,
+            "usable_docs": len(indexed),
+            "unique_docs": len(unique_texts),
+            "dedup_ratio": round(dedup_ratio, 4),
+            "elapsed_ms": round(elapsed_ms, 3),
+            "model": self._model_name,
+            "backend": "qwen3_transformers_packed",
+            "normalize": normalize,
+            "packed_batches": len(pack_plan),
+            "packed_max_seq_len": max(pack_lengths) if pack_lengths else 0,
+            "packed_avg_seq_len": round(sum(pack_lengths) / len(pack_lengths), 3)
+            if pack_lengths
+            else 0.0,
+            "max_model_len": self._max_model_len,
+            "max_doc_len": self._max_doc_len,
+            "max_docs_per_pack": self._max_docs_per_pack,
+            "sort_by_doc_length": self._sort_by_doc_length,
+            "attn_implementation": self._attn_impl,
+        }
+        return output_scores, meta
@@ -45,7 +45,7 @@ def deduplicate_with_positions(texts: List[str]) -&gt; Tuple[List[str], List[int]]:
     return unique_texts, position_to_unique
  
  
-def _format_instruction(instruction: str, query: str, doc: str) -> List[Dict[str, str]]:
+def _format_instruction__standard(instruction: str, query: str, doc: str) -> List[Dict[str, str]]:
     """Build chat messages for one (query, doc) pair."""
     return [
         {
@@ -58,6 +58,18 @@ def _format_instruction(instruction: str, query: str, doc: str) -&gt; List[Dict[str
         },
     ]
  
+def _format_instruction(instruction: str, query: str, doc: str) -> List[Dict[str, str]]:
+    """Build chat messages for one (query, doc) pair."""
+    return [
+        {
+            "role": "system",
+            "content": instruction,
+        },
+        {
+            "role": "user",
+            "content": f"<Instruct>: {instruction}\n\n<Query>: {query}\n\n<Document>: {doc}",
+        },
+    ]
  
 class Qwen3VLLMRerankerBackend:
     """
@@ -78,6 +90,17 @@ class Qwen3VLLMRerankerBackend:
             self._config.get("instruction")
             or "Given a query, score the product for relevance"
         )
+        _fmt = str(self._config.get("instruction_format") or "compact").strip().lower()
+        if _fmt not in {"standard", "compact"}:
+            raise ValueError(
+                f"instruction_format must be 'standard' or 'compact', got {_fmt!r}"
+            )
+        self._instruction_format = _fmt
+        self._format_messages = (
+            _format_instruction__standard
+            if self._instruction_format == "standard"
+            else _format_instruction
+        )
         infer_batch_size = os.getenv("RERANK_VLLM_INFER_BATCH_SIZE") or self._config.get("infer_batch_size", 64)
         sort_by_doc_length = os.getenv("RERANK_VLLM_SORT_BY_DOC_LENGTH")
         if sort_by_doc_length is None:
@@ -95,13 +118,15 @@ class Qwen3VLLMRerankerBackend:
             )
  
         logger.info(
-            "[Qwen3_VLLM] Loading model %s (max_model_len=%s, tp=%s, gpu_mem=%.2f, dtype=%s, prefix_caching=%s)",
+            "[Qwen3_VLLM] Loading model %s (max_model_len=%s, tp=%s, gpu_mem=%.2f, dtype=%s, prefix_caching=%s, "
+            "instruction_format=%s)",
             model_name,
             max_model_len,
             tensor_parallel_size,
             gpu_memory_utilization,
             dtype,
             enable_prefix_caching,
+            self._instruction_format,
         )
  
         self._llm = LLM(
@@ -145,7 +170,7 @@ class Qwen3VLLMRerankerBackend:
     ) -> List[TokensPrompt]:
         """Build tokenized prompts for vLLM from (query, doc) pairs. Batch apply_chat_template."""
         messages_batch = [
-            _format_instruction(self._instruction, q, d) for q, d in pairs
+            self._format_messages(self._instruction, q, d) for q, d in pairs
         ]
         tokenized = self._tokenizer.apply_chat_template(
             messages_batch,
@@ -242,6 +267,7 @@ class Qwen3VLLMRerankerBackend:
                 "infer_batch_size": self._infer_batch_size,
                 "inference_batches": 0,
                 "sort_by_doc_length": self._sort_by_doc_length,
+                "instruction_format": self._instruction_format,
             }
  
         # Deduplicate globally by text, keep mapping to original indices.
@@ -289,6 +315,7 @@ class Qwen3VLLMRerankerBackend:
             "normalize": normalize,
             "infer_batch_size": self._infer_batch_size,
             "inference_batches": inference_batches,
-            "sort_by_doc_length": self._sort_by_doc_length
+            "sort_by_doc_length": self._sort_by_doc_length,
+            "instruction_format": self._instruction_format,
         }
         return output_scores, meta
@@ -0,0 +1,323 @@
+"""
+Qwen3-Reranker via vLLM ``LLM.score()`` (pooling / cross-encoder score API).
+
+Matches vLLM ``examples/offline_inference/qwen3_reranker.py``: paired
+``llm.score(query_texts, doc_texts)`` with the recommended prefix/suffix templates.
+Requires vLLM >= 0.17 (uses ``runner``/``convert`` auto, not legacy ``task="score"``).
+
+Dedicated venv: ``.venv-reranker-score`` + ``requirements_reranker_qwen3_vllm_score.txt``
+(see ``./scripts/setup_reranker_venv.sh qwen3_vllm_score``). Default ``model_name`` can match
+``qwen3_vllm``; only the Python env differs for pinned high-performance vLLM.
+
+Reference: https://docs.vllm.ai/ — Qwen3 reranker example
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from typing import Any, Dict, List, Tuple
+
+logger = logging.getLogger("reranker.backends.qwen3_vllm_score")
+
+import torch
+from vllm import LLM
+
+from reranker.backends.qwen3_vllm import deduplicate_with_positions
+
+# Official vLLM Qwen3 reranker prompt layout (im_start blocks + assistant suffix).
+_DEFAULT_PREFIX = (
+    "<|im_start|>system\n"
+    "Judge whether the Document meets the requirements based on the Query and the Instruct "
+    'provided. Note that the answer can only be "yes" or "no".'
+    "<|im_end|>\n<|im_start|>user\n"
+)
+_DEFAULT_SUFFIX = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"
+_DEFAULT_QUERY_TEMPLATE = "{prefix}<Instruct>: {instruction}\n<Query>: {query}\n"
+_DEFAULT_DOCUMENT_TEMPLATE = "<Document>: {doc}{suffix}"
+# compact：与 qwen3_vllm._format_instruction 一致（instruction 作 system，user 内重复 Instruct）
+_IM_USER_START = "<|im_end|>\n<|im_start|>user\n"
+
+
+def _resolve_vllm_attention_config(config: Dict[str, Any]) -> Dict[str, Any] | None:
+    """
+    vLLM 0.18 defaults to Flash-Attention paths that require compute capability >= 8 (Ampere+).
+    Turing / Volta (e.g. T4 sm_75) must use a non-FA backend such as TRITON_ATTN.
+    """
+    env = (os.getenv("RERANK_VLLM_ATTENTION_BACKEND") or "").strip()
+    raw = config.get("vllm_attention_backend")
+    if env:
+        choice = env
+    elif raw is not None and str(raw).strip() and str(raw).strip().lower() != "auto":
+        choice = str(raw).strip()
+    else:
+        choice = ""
+    if choice:
+        backend = choice.strip().upper()
+        if backend == "AUTO":
+            choice = ""
+        else:
+            logger.info("[Qwen3_VLLM_SCORE] attention_config.backend=%s (from config/env)", backend)
+            return {"backend": backend}
+
+    major, minor = torch.cuda.get_device_capability()
+    if major < 8:
+        logger.info(
+            "[Qwen3_VLLM_SCORE] GPU compute capability %d.%d < 8.0; using attention backend "
+            "TRITON_ATTN (Flash-Attention 2 requires sm >= 80). "
+            "Override with services.rerank.backends.qwen3_vllm_score.vllm_attention_backend "
+            "or RERANK_VLLM_ATTENTION_BACKEND.",
+            major,
+            minor,
+        )
+        return {"backend": "TRITON_ATTN"}
+    return None
+
+
+class Qwen3VLLMScoreRerankerBackend:
+    """
+    Qwen3 reranker using vLLM ``LLM.score()`` (pooling runner) for cross-encoder scores.
+
+    Config from ``services.rerank.backends.qwen3_vllm_score``.
+    """
+
+    def __init__(self, config: Dict[str, Any]) -> None:
+        self._config = config or {}
+        model_name = str(self._config.get("model_name") or "Qwen/Qwen3-Reranker-0.6B")
+        max_model_len = int(self._config.get("max_model_len", 2048))
+        tensor_parallel_size = int(self._config.get("tensor_parallel_size", 1))
+        gpu_memory_utilization = float(self._config.get("gpu_memory_utilization", 0.4))
+        enable_prefix_caching = bool(self._config.get("enable_prefix_caching", False))
+        enforce_eager = bool(self._config.get("enforce_eager", True))
+        dtype = str(self._config.get("dtype", "float16")).strip().lower()
+        use_hf_overrides = self._config.get("use_original_qwen3_hf_overrides")
+        if use_hf_overrides is None:
+            use_hf_overrides = True
+        use_hf_overrides = bool(use_hf_overrides)
+
+        self._instruction = str(
+            self._config.get("instruction")
+            or "Given a query, score the product for relevance"
+        )
+        _fmt = str(self._config.get("instruction_format") or "standard").strip().lower()
+        if _fmt not in {"standard", "compact"}:
+            raise ValueError(
+                f"instruction_format must be 'standard' or 'compact', got {_fmt!r}"
+            )
+        self._instruction_format = _fmt
+        self._prefix = str(self._config.get("prompt_prefix") or _DEFAULT_PREFIX)
+        self._suffix = str(self._config.get("prompt_suffix") or _DEFAULT_SUFFIX)
+        self._query_template = str(self._config.get("query_template") or _DEFAULT_QUERY_TEMPLATE)
+        self._document_template = str(
+            self._config.get("document_template") or _DEFAULT_DOCUMENT_TEMPLATE
+        )
+
+        infer_batch_size = os.getenv("RERANK_VLLM_INFER_BATCH_SIZE") or self._config.get(
+            "infer_batch_size", 64
+        )
+        sort_by_doc_length = os.getenv("RERANK_VLLM_SORT_BY_DOC_LENGTH")
+        if sort_by_doc_length is None:
+            sort_by_doc_length = self._config.get("sort_by_doc_length", True)
+
+        self._infer_batch_size = int(infer_batch_size)
+        self._sort_by_doc_length = str(sort_by_doc_length).strip().lower() in {
+            "1",
+            "true",
+            "yes",
+            "y",
+            "on",
+        }
+
+        if not torch.cuda.is_available():
+            raise RuntimeError(
+                "qwen3_vllm_score backend requires CUDA GPU, but torch.cuda.is_available() is False"
+            )
+        if dtype not in {"float16", "half", "auto"}:
+            raise ValueError(
+                f"Unsupported dtype for qwen3_vllm_score: {dtype!r}. Use float16/half/auto."
+            )
+        if self._infer_batch_size <= 0:
+            raise ValueError(f"infer_batch_size must be > 0, got {self._infer_batch_size}")
+
+        runner = str(self._config.get("vllm_runner") or "auto").strip().lower()
+        convert = str(self._config.get("vllm_convert") or "auto").strip().lower()
+        if runner not in {"auto", "generate", "pooling", "draft"}:
+            raise ValueError(f"Invalid vllm_runner: {runner!r}")
+        if convert not in {"auto", "none", "embed", "classify"}:
+            raise ValueError(f"Invalid vllm_convert: {convert!r}")
+
+        logger.info(
+            "[Qwen3_VLLM_SCORE] Loading model %s (LLM.score API, runner=%s, convert=%s, "
+            "hf_overrides=%s, max_model_len=%s, tp=%s, gpu_mem=%.2f, dtype=%s, prefix_caching=%s, "
+            "instruction_format=%s)",
+            model_name,
+            runner,
+            convert,
+            use_hf_overrides,
+            max_model_len,
+            tensor_parallel_size,
+            gpu_memory_utilization,
+            dtype,
+            enable_prefix_caching,
+            self._instruction_format,
+        )
+
+        # vLLM 0.17+ uses runner/convert instead of LLM(..., task="score"). With the official
+        # Qwen3 reranker hf_overrides, architecture becomes *ForSequenceClassification -> pooling+classify.
+        llm_kwargs: Dict[str, Any] = {
+            "model": model_name,
+            "runner": runner,
+            "convert": convert,
+            "tensor_parallel_size": tensor_parallel_size,
+            "max_model_len": max_model_len,
+            "gpu_memory_utilization": gpu_memory_utilization,
+            "enable_prefix_caching": enable_prefix_caching,
+            "enforce_eager": enforce_eager,
+            "dtype": dtype,
+        }
+        hf_overrides: Dict[str, Any] = dict(self._config.get("hf_overrides") or {})
+        if use_hf_overrides:
+            hf_overrides = {
+                **hf_overrides,
+                "architectures": ["Qwen3ForSequenceClassification"],
+                "classifier_from_token": ["no", "yes"],
+                "is_original_qwen3_reranker": True,
+            }
+        if hf_overrides:
+            llm_kwargs["hf_overrides"] = hf_overrides
+
+        attn_cfg = _resolve_vllm_attention_config(self._config)
+        if attn_cfg is not None:
+            llm_kwargs["attention_config"] = attn_cfg
+
+        self._llm = LLM(**llm_kwargs)
+        # vLLM score path: single-process safety (mirrors generate backend until verified).
+        self._infer_lock = threading.Lock()
+
+        self._model_name = model_name
+        logger.info("[Qwen3_VLLM_SCORE] Model ready | model=%s", model_name)
+
+    def _format_pair(self, query: str, doc: str) -> Tuple[str, str]:
+        if self._instruction_format == "compact":
+            # Align with reranker.backends.qwen3_vllm._format_instruction query/doc split for LLM.score().
+            compact_prefix = f"<|im_start|>system\n{self._instruction}{_IM_USER_START}"
+            q_text = (
+                f"{compact_prefix}<Instruct>: {self._instruction}\n\n<Query>: {query}\n"
+            )
+            d_text = f"\n<Document>: {doc}{self._suffix}"
+            return q_text, d_text
+        q_text = self._query_template.format(
+            prefix=self._prefix,
+            instruction=self._instruction,
+            query=query,
+        )
+        d_text = self._document_template.format(doc=doc, suffix=self._suffix)
+        return q_text, d_text
+
+    def _score_batch(self, pairs: List[Tuple[str, str]]) -> List[float]:
+        if not pairs:
+            return []
+        queries: List[str] = []
+        documents: List[str] = []
+        for q, d in pairs:
+            qt, dt = self._format_pair(q, d)
+            queries.append(qt)
+            documents.append(dt)
+        with self._infer_lock:
+            outputs = self._llm.score(queries, documents, use_tqdm=False)
+        scores: List[float] = []
+        for out in outputs:
+            so = out.outputs
+            scores.append(float(so.score))
+        return scores
+
+    @staticmethod
+    def _estimate_doc_lengths(docs: List[str]) -> List[int]:
+        if not docs:
+            return []
+        return [len(text) for text in docs]
+
+    def score_with_meta(
+        self,
+        query: str,
+        docs: List[str],
+        normalize: bool = True,
+    ) -> Tuple[List[float], Dict[str, Any]]:
+        start_ts = time.time()
+        total_docs = len(docs) if docs else 0
+        output_scores: List[float] = [0.0] * total_docs
+
+        query = "" if query is None else str(query).strip()
+        indexed: List[Tuple[int, str]] = []
+        for i, doc in enumerate(docs or []):
+            if doc is None:
+                continue
+            text = str(doc).strip()
+            if not text:
+                continue
+            indexed.append((i, text))
+
+        if not query or not indexed:
+            elapsed_ms = (time.time() - start_ts) * 1000.0
+            return output_scores, {
+                "input_docs": total_docs,
+                "usable_docs": len(indexed),
+                "unique_docs": 0,
+                "dedup_ratio": 0.0,
+                "elapsed_ms": round(elapsed_ms, 3),
+                "model": self._model_name,
+                "backend": "qwen3_vllm_score",
+                "normalize": normalize,
+                "infer_batch_size": self._infer_batch_size,
+                "inference_batches": 0,
+                "sort_by_doc_length": self._sort_by_doc_length,
+                "instruction_format": self._instruction_format,
+            }
+
+        indexed_texts = [text for _, text in indexed]
+        unique_texts, position_to_unique = deduplicate_with_positions(indexed_texts)
+
+        lengths = self._estimate_doc_lengths(unique_texts)
+        order = list(range(len(unique_texts)))
+        if self._sort_by_doc_length and len(unique_texts) > 1:
+            order = sorted(order, key=lambda i: lengths[i])
+
+        unique_scores: List[float] = [0.0] * len(unique_texts)
+        inference_batches = 0
+        for start in range(0, len(order), self._infer_batch_size):
+            batch_indices = order[start : start + self._infer_batch_size]
+            inference_batches += 1
+            pairs = [(query, unique_texts[i]) for i in batch_indices]
+            batch_scores = self._score_batch(pairs)
+            if len(batch_scores) != len(batch_indices):
+                raise RuntimeError(
+                    f"Reranker score size mismatch: expected {len(batch_indices)}, got {len(batch_scores)}"
+                )
+            for idx, score in zip(batch_indices, batch_scores):
+                unique_scores[idx] = float(score)
+
+        for (orig_idx, _), unique_idx in zip(indexed, position_to_unique):
+            output_scores[orig_idx] = float(unique_scores[unique_idx])
+
+        elapsed_ms = (time.time() - start_ts) * 1000.0
+        dedup_ratio = 0.0
+        if indexed:
+            dedup_ratio = 1.0 - (len(unique_texts) / float(len(indexed)))
+
+        meta = {
+            "input_docs": total_docs,
+            "usable_docs": len(indexed),
+            "unique_docs": len(unique_texts),
+            "dedup_ratio": round(dedup_ratio, 4),
+            "elapsed_ms": round(elapsed_ms, 3),
+            "model": self._model_name,
+            "backend": "qwen3_vllm_score",
+            "normalize": normalize,
+            "infer_batch_size": self._infer_batch_size,
+            "inference_batches": inference_batches,
+            "sort_by_doc_length": self._sort_by_doc_length,
+            "instruction_format": self._instruction_format,
+        }
+        return output_scores, meta
@@ -7,7 +7,7 @@ Request: { &quot;query&quot;: &quot;...&quot;, &quot;docs&quot;: [&quot;doc1&quot;, &quot;doc2&quot;, ...], &quot;normalize&quot;: optional 
 Response: { "scores": [float], "meta": {...} }
  
 Backend selected via config: services.rerank.backend
-(bge | qwen3_vllm | qwen3_transformers | dashscope_rerank), env RERANK_BACKEND.
+(bge | qwen3_vllm | qwen3_vllm_score | qwen3_transformers | qwen3_transformers_packed | qwen3_gguf | qwen3_gguf_06b | dashscope_rerank), env RERANK_BACKEND.
 """
  
 import logging
@@ -99,12 +99,17 @@ def health() -&gt; Dict[str, Any]:
         model_info = getattr(_reranker, "_model_name", None) or getattr(
             _reranker, "_config", {}
         ).get("model_name", _backend_name)
-    return {
+    payload: Dict[str, Any] = {
         "status": "ok" if _reranker is not None else "unavailable",
         "model_loaded": _reranker is not None,
         "model": model_info,
         "backend": _backend_name,
     }
+    if _reranker is not None:
+        _fmt = getattr(_reranker, "_instruction_format", None)
+        if _fmt is not None:
+            payload["instruction_format"] = _fmt
+    return payload
  
  
 @app.post("/rerank", response_model=RerankResponse)
@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""
+Local tuning probe for GGUF reranker backends.
+
+Runs the backend directly in a fresh process per config to measure:
+- load time
+- GPU memory used by this process
+- single-request rerank latency
+
+Example:
+  ./.venv-reranker-gguf/bin/python scripts/benchmark_reranker_gguf_local.py
+  ./.venv-reranker-gguf-06b/bin/python scripts/benchmark_reranker_gguf_local.py --backend-name qwen3_gguf_06b --docs 400
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import statistics
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_TITLES = Path("/home/ubuntu/rerank_test/titles.1.8w")
+
+
+def load_titles(path: Path) -> list[str]:
+    items: list[str] = []
+    with path.open(encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            text = line.strip()
+            if text:
+                items.append(text)
+    return items
+
+
+def gpu_mem_for_pid(pid: int) -> int:
+    try:
+        out = subprocess.check_output(
+            [
+                "nvidia-smi",
+                "--query-compute-apps=pid,used_gpu_memory",
+                "--format=csv,noheader,nounits",
+            ],
+            text=True,
+        )
+    except Exception:
+        return -1
+    for raw in out.splitlines():
+        parts = [p.strip() for p in raw.split(",")]
+        if len(parts) != 2:
+            continue
+        try:
+            row_pid = int(parts[0])
+            row_mem = int(parts[1])
+        except ValueError:
+            continue
+        if row_pid == pid:
+            return row_mem
+    return -1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--backend-name", type=str, default="qwen3_gguf")
+    parser.add_argument("--titles-file", type=Path, default=DEFAULT_TITLES)
+    parser.add_argument("--query", type=str, default="白色oversized T-shirt")
+    parser.add_argument("--docs", type=int, default=160)
+    parser.add_argument("--repeat", type=int, default=1)
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument(
+        "--configs-json",
+        type=str,
+        default="",
+        help="JSON array of config objects; when omitted, uses built-in scan set.",
+    )
+    args = parser.parse_args()
+
+    if not args.titles_file.is_file():
+        print(f"missing titles file: {args.titles_file}", file=sys.stderr)
+        return 2
+
+    titles = load_titles(args.titles_file)
+    if len(titles) < args.docs:
+        print(f"not enough titles: need {args.docs}, got {len(titles)}", file=sys.stderr)
+        return 2
+
+    random.seed(args.seed)
+    docs = random.sample(titles, args.docs)
+
+    if args.configs_json:
+        configs = json.loads(args.configs_json)
+    elif args.backend_name == "qwen3_gguf_06b":
+        configs = [
+            {"name": "gguf_06b_full_256", "n_ctx": 256, "n_batch": 256, "n_ubatch": 256, "n_gpu_layers": 999},
+            {"name": "gguf_06b_full_320", "n_ctx": 320, "n_batch": 320, "n_ubatch": 320, "n_gpu_layers": 999},
+            {"name": "gguf_06b_full_384", "n_ctx": 384, "n_batch": 384, "n_ubatch": 384, "n_gpu_layers": 999},
+            {"name": "gguf_06b_full_512", "n_ctx": 512, "n_batch": 512, "n_ubatch": 512, "n_gpu_layers": 999},
+        ]
+    else:
+        configs = [
+            {"name": "gguf_t4_24g", "n_ctx": 384, "n_batch": 384, "n_ubatch": 128, "n_gpu_layers": 24},
+            {"name": "gguf_t4_40g", "n_ctx": 384, "n_batch": 384, "n_ubatch": 128, "n_gpu_layers": 40},
+            {"name": "gguf_t4_full", "n_ctx": 384, "n_batch": 384, "n_ubatch": 128, "n_gpu_layers": 999},
+            {"name": "gguf_t4_full_512", "n_ctx": 512, "n_batch": 512, "n_ubatch": 256, "n_gpu_layers": 999},
+            {"name": "gguf_t4_full_512_u512", "n_ctx": 512, "n_batch": 512, "n_ubatch": 512, "n_gpu_layers": 999},
+            {"name": "gguf_t4_full_768", "n_ctx": 768, "n_batch": 768, "n_ubatch": 256, "n_gpu_layers": 999},
+        ]
+
+    from reranker.backends.qwen3_gguf import Qwen3GGUFRerankerBackend
+
+    default_cfg_by_backend: dict[str, dict[str, Any]] = {
+        "qwen3_gguf": {
+            "_backend_name": "qwen3_gguf",
+            "repo_id": "DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF",
+            "filename": "*Q8_0.gguf",
+            "local_dir": "./models/reranker/qwen3-reranker-4b-gguf",
+            "infer_batch_size": 8,
+        },
+        "qwen3_gguf_06b": {
+            "_backend_name": "qwen3_gguf_06b",
+            "repo_id": "ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF",
+            "filename": "qwen3-reranker-0.6b-q8_0.gguf",
+            "local_dir": "./models/reranker/qwen3-reranker-0.6b-q8_0-gguf",
+            "infer_batch_size": 32,
+        },
+    }
+    if args.backend_name not in default_cfg_by_backend:
+        print(f"unsupported backend: {args.backend_name}", file=sys.stderr)
+        return 2
+
+    base_cfg: dict[str, Any] = {
+        **default_cfg_by_backend[args.backend_name],
+        "instruction": "Rank products by query with category & style match prioritized",
+        "cache_dir": "./model_cache",
+        "main_gpu": 0,
+        "n_threads": 2,
+        "n_threads_batch": 4,
+        "flash_attn": True,
+        "offload_kqv": True,
+        "use_mmap": True,
+        "use_mlock": False,
+        "sort_by_doc_length": True,
+        "length_sort_mode": "char",
+        "enable_warmup": True,
+        "verbose": False,
+        "reuse_query_state": True,
+    }
+
+    all_results: list[dict[str, Any]] = []
+    for cfg in configs:
+        merged = dict(base_cfg)
+        merged.update(cfg)
+        name = str(merged.pop("name"))
+
+        t0 = time.perf_counter()
+        backend = Qwen3GGUFRerankerBackend(merged)
+        load_ms = (time.perf_counter() - t0) * 1000.0
+        gpu_mem_mib = gpu_mem_for_pid(os.getpid())
+
+        runs: list[float] = []
+        last_meta: dict[str, Any] = {}
+        for _ in range(args.repeat):
+            t1 = time.perf_counter()
+            _scores, meta = backend.score_with_meta(args.query, docs, normalize=True)
+            runs.append((time.perf_counter() - t1) * 1000.0)
+            last_meta = dict(meta)
+
+        result = {
+            "name": name,
+            "config": merged,
+            "load_ms": round(load_ms, 2),
+            "gpu_mem_mib": gpu_mem_mib,
+            "latency_ms_min": round(min(runs), 2),
+            "latency_ms_avg": round(statistics.mean(runs), 2),
+            "latency_ms_max": round(max(runs), 2),
+            "meta": last_meta,
+        }
+        all_results.append(result)
+        print(json.dumps(result, ensure_ascii=False))
+        del backend
+
+    print("SUMMARY")
+    for item in sorted(all_results, key=lambda x: x["latency_ms_avg"]):
+        print(
+            f'{item["name"]}: avg={item["latency_ms_avg"]}ms '
+            f'gpu={item["gpu_mem_mib"]}MiB load={item["load_ms"]}ms'
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -6,6 +6,7 @@ Randomly samples N titles from a text file (one title per line), POSTs to the
 rerank HTTP API, prints wall-clock latency.
  
 Supports multiple N values (comma-separated) and multiple repeats per N.
+Each invocation runs 3 warmup requests with n=400 first; those are not timed for summaries.
  
 Example:
   source activate.sh
@@ -149,6 +150,23 @@ def main() -&gt; int:
         action="store_true",
         help="Print first ~500 chars of response body on success (last run only).",
     )
+    parser.add_argument(
+        "--tag",
+        type=str,
+        default=os.environ.get("BENCH_TAG", ""),
+        help="Optional label stored in --json-summary-out (default: env BENCH_TAG or empty).",
+    )
+    parser.add_argument(
+        "--json-summary-out",
+        type=Path,
+        default=None,
+        help="Write one JSON object with per-n latencies and aggregates for downstream tables.",
+    )
+    parser.add_argument(
+        "--quiet-runs",
+        action="store_true",
+        help="Suppress per-run lines; still prints warmup lines and text summaries.",
+    )
     args = parser.parse_args()
  
     try:
@@ -167,7 +185,9 @@ def main() -&gt; int:
         return 2
  
     titles = _load_titles(args.titles_file)
-    max_n = max(doc_counts)
+    warmup_n = 400
+    warmup_runs = 3
+    max_n = max(max(doc_counts), warmup_n)
     if len(titles) < max_n:
         print(
             f"error: file has only {len(titles)} non-empty lines, need at least {max_n}",
@@ -181,6 +201,33 @@ def main() -&gt; int:
     summary: dict[int, List[float]] = {n: [] for n in doc_counts}
  
     with httpx.Client(timeout=args.timeout) as client:
+        for w in range(warmup_runs):
+            if args.seed is not None:
+                random.seed(args.seed + 8_000_000 + w)
+            docs_w = random.sample(titles, warmup_n)
+            try:
+                ok_w, status_w, _elapsed_w, scores_len_w, _text_w = _do_rerank(
+                    client,
+                    args.url,
+                    args.query,
+                    docs_w,
+                    top_n=top_n,
+                    normalize=normalize,
+                )
+            except httpx.HTTPError as exc:
+                print(
+                    f"warmup n={warmup_n} {w + 1}/{warmup_runs} error: request failed: {exc}",
+                    file=sys.stderr,
+                )
+                any_fail = True
+                continue
+            if not ok_w:
+                any_fail = True
+            print(
+                f"warmup n={warmup_n} {w + 1}/{warmup_runs} status={status_w} "
+                f"scores={scores_len_w if scores_len_w is not None else 'n/a'} (not timed)"
+            )
+
         for n in doc_counts:
             for run_idx in range(repeat):
                 if args.seed is not None:
@@ -208,10 +255,11 @@ def main() -&gt; int:
                 else:
                     any_fail = True
  
-                print(
-                    f"n={n} run={run_idx + 1}/{repeat} status={status} "
-                    f"latency_ms={elapsed_ms:.2f} scores={scores_len if scores_len is not None else 'n/a'}"
-                )
+                if not args.quiet_runs:
+                    print(
+                        f"n={n} run={run_idx + 1}/{repeat} status={status} "
+                        f"latency_ms={elapsed_ms:.2f} scores={scores_len if scores_len is not None else 'n/a'}"
+                    )
                 if args.print_body_preview and text and run_idx == repeat - 1 and n == doc_counts[-1]:
                     preview = text[:500] + ("…" if len(text) > 500 else "")
                     print(preview)
@@ -230,6 +278,33 @@ def main() -&gt; int:
             f"summary n={n} runs={len(lat)} min_ms={lo:.2f} max_ms={hi:.2f} avg_ms={avg:.2f}{extra}"
         )
  
+    if args.json_summary_out is not None:
+        per_n: dict = {}
+        for n in doc_counts:
+            lat = summary[n]
+            row: dict = {"values_ms": lat, "runs": len(lat)}
+            if lat:
+                row["mean_ms"] = statistics.mean(lat)
+                row["min_ms"] = min(lat)
+                row["max_ms"] = max(lat)
+                if len(lat) >= 2:
+                    row["stdev_ms"] = statistics.stdev(lat)
+            per_n[str(n)] = row
+        out_obj = {
+            "tag": args.tag or None,
+            "doc_counts": doc_counts,
+            "repeat": repeat,
+            "url": args.url,
+            "per_n": per_n,
+            "failed": bool(any_fail),
+        }
+        args.json_summary_out.parent.mkdir(parents=True, exist_ok=True)
+        args.json_summary_out.write_text(
+            json.dumps(out_obj, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        print(f"wrote json summary -> {args.json_summary_out}")
+
     return 1 if any_fail else 0
  
  
@@ -0,0 +1,68 @@
+#!/bin/bash
+#
+# Shared helpers for mapping reranker backends to isolated virtualenvs.
+#
+
+set -euo pipefail
+
+detect_rerank_backend() {
+  local project_root="$1"
+  local backend="${RERANK_BACKEND:-}"
+
+  if [[ -n "${backend}" ]]; then
+    printf '%s\n' "${backend}"
+    return 0
+  fi
+
+  backend="$(
+    awk '
+      /^  rerank:$/ { in_rerank=1; next }
+      in_rerank && /^  [^ ]/ { in_rerank=0 }
+      in_rerank && /^    backend:/ {
+        gsub(/"/, "", $2)
+        print $2
+        exit
+      }
+    ' "${project_root}/config/config.yaml"
+  )"
+
+  if [[ -z "${backend}" ]]; then
+    backend="qwen3_vllm"
+  fi
+
+  printf '%s\n' "${backend}"
+}
+
+reranker_backend_venv_dir() {
+  local project_root="$1"
+  local backend="$2"
+
+  case "${backend}" in
+    qwen3_vllm) printf '%s/.venv-reranker\n' "${project_root}" ;;
+    qwen3_vllm_score) printf '%s/.venv-reranker-score\n' "${project_root}" ;;
+    qwen3_gguf) printf '%s/.venv-reranker-gguf\n' "${project_root}" ;;
+    qwen3_gguf_06b) printf '%s/.venv-reranker-gguf-06b\n' "${project_root}" ;;
+    qwen3_transformers) printf '%s/.venv-reranker-transformers\n' "${project_root}" ;;
+    qwen3_transformers_packed) printf '%s/.venv-reranker-transformers-packed\n' "${project_root}" ;;
+    bge) printf '%s/.venv-reranker-bge\n' "${project_root}" ;;
+    dashscope_rerank) printf '%s/.venv-reranker-dashscope\n' "${project_root}" ;;
+    *) printf '%s/.venv-reranker-%s\n' "${project_root}" "${backend}" ;;
+  esac
+}
+
+reranker_backend_requirements_file() {
+  local project_root="$1"
+  local backend="$2"
+
+  case "${backend}" in
+    qwen3_vllm) printf '%s/requirements_reranker_qwen3_vllm.txt\n' "${project_root}" ;;
+    qwen3_vllm_score) printf '%s/requirements_reranker_qwen3_vllm_score.txt\n' "${project_root}" ;;
+    qwen3_gguf) printf '%s/requirements_reranker_qwen3_gguf.txt\n' "${project_root}" ;;
+    qwen3_gguf_06b) printf '%s/requirements_reranker_qwen3_gguf_06b.txt\n' "${project_root}" ;;
+    qwen3_transformers) printf '%s/requirements_reranker_qwen3_transformers.txt\n' "${project_root}" ;;
+    qwen3_transformers_packed) printf '%s/requirements_reranker_qwen3_transformers_packed.txt\n' "${project_root}" ;;
+    bge) printf '%s/requirements_reranker_bge.txt\n' "${project_root}" ;;
+    dashscope_rerank) printf '%s/requirements_reranker_dashscope.txt\n' "${project_root}" ;;
+    *) return 1 ;;
+  esac
+}
@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+Surgically patch config/config.yaml:
+  services.rerank.backend
+  services.rerank.backends.qwen3_vllm.instruction_format
+  services.rerank.backends.qwen3_vllm_score.instruction_format
+
+Preserves comments and unrelated lines. Used for benchmark matrix runs.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+def _with_stripped_body(line: str) -> tuple[str, str]:
+    """Return (body without end newline, newline suffix including '' if none)."""
+    if line.endswith("\r\n"):
+        return line[:-2], "\r\n"
+    if line.endswith("\n"):
+        return line[:-1], "\n"
+    return line, ""
+
+
+def _patch_backend_in_rerank_block(lines: list[str], backend: str) -> None:
+    in_rerank = False
+    for i, line in enumerate(lines):
+        if line.startswith("  rerank:"):
+            in_rerank = True
+            continue
+        if in_rerank:
+            if line.startswith("  ") and not line.startswith("    ") and line.strip():
+                in_rerank = False
+                continue
+            body, nl = _with_stripped_body(line)
+            m = re.match(r'^(\s*backend:\s*")[^"]+(".*)$', body)
+            if m:
+                lines[i] = f'{m.group(1)}{backend}{m.group(2)}{nl}'
+                return
+    raise RuntimeError("services.rerank.backend line not found")
+
+
+def _patch_instruction_format_under_backend(
+    lines: list[str], section: str, fmt: str
+) -> None:
+    """section is 'qwen3_vllm' or 'qwen3_vllm_score' (first line is '      qwen3_vllm:')."""
+    header = f"      {section}:"
+    start = None
+    for i, line in enumerate(lines):
+        if line.rstrip() == header:
+            start = i
+            break
+    if start is None:
+        raise RuntimeError(f"section {section!r} not found")
+
+    for j in range(start + 1, len(lines)):
+        line = lines[j]
+        body, nl = _with_stripped_body(line)
+        if re.match(r"^      [a-zA-Z0-9_]+:\s*$", body):
+            break
+        m = re.match(r"^(\s*instruction_format:\s*)\S+", body)
+        if m:
+            lines[j] = f"{m.group(1)}{fmt}{nl}"
+            return
+    raise RuntimeError(f"instruction_format not found under {section!r}")
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument(
+        "--config",
+        type=Path,
+        default=Path(__file__).resolve().parent.parent / "config" / "config.yaml",
+    )
+    p.add_argument("--backend", choices=("qwen3_vllm", "qwen3_vllm_score"), required=True)
+    p.add_argument(
+        "--instruction-format",
+        dest="instruction_format",
+        choices=("compact", "standard"),
+        required=True,
+    )
+    args = p.parse_args()
+    text = args.config.read_text(encoding="utf-8")
+    lines = text.splitlines(keepends=True)
+    if not lines:
+        print("empty config", file=sys.stderr)
+        return 2
+    _patch_backend_in_rerank_block(lines, args.backend)
+    _patch_instruction_format_under_backend(lines, "qwen3_vllm", args.instruction_format)
+    _patch_instruction_format_under_backend(lines, "qwen3_vllm_score", args.instruction_format)
+    args.config.write_text("".join(lines), encoding="utf-8")
+    print(f"patched {args.config}: backend={args.backend} instruction_format={args.instruction_format} (both vLLM blocks)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Patch config, restart reranker, wait for /health, run benchmark_reranker_random_titles.py.
+# Requires: curl, .venv with PyYAML not needed (patch is standalone Python).
+
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+PYTHON="${ROOT}/.venv/bin/python"
+DAY="$(date +%F)"
+OUT_DIR="${ROOT}/perf_reports/reranker_vllm_instruction/${DAY}"
+mkdir -p "$OUT_DIR"
+
+health_ok() {
+  local want_backend="$1"
+  local want_fmt="$2"
+  local body
+  if ! body="$(curl -sS --connect-timeout 2 --max-time 5 "http://127.0.0.1:6007/health" 2>/dev/null)"; then
+    return 1
+  fi
+  echo "$body" | "$PYTHON" -c "
+import json, sys
+want_b, want_f = sys.argv[1], sys.argv[2]
+d = json.load(sys.stdin)
+if d.get('status') != 'ok' or not d.get('model_loaded'):
+    sys.exit(1)
+if d.get('backend') != want_b:
+    sys.exit(1)
+if d.get('instruction_format') != want_f:
+    sys.exit(1)
+sys.exit(0)
+" "$want_backend" "$want_fmt"
+}
+
+wait_health() {
+  local want_backend="$1"
+  local want_fmt="$2"
+  local i
+  for i in $(seq 1 180); do
+    if health_ok "$want_backend" "$want_fmt"; then
+      curl -sS "http://127.0.0.1:6007/health" | "$PYTHON" -m json.tool
+      return 0
+    fi
+    echo "[wait] ${i}/180 backend=${want_backend} instruction_format=${want_fmt} ..."
+    sleep 3
+  done
+  echo "[error] health did not match in time" >&2
+  return 1
+}
+
+run_one() {
+  local backend="$1"
+  local fmt="$2"
+  local tag="${backend}|${fmt}"
+  local jf="${OUT_DIR}/${backend}_${fmt}.json"
+
+  echo "========== ${tag} =========="
+  "$PYTHON" "${ROOT}/scripts/patch_rerank_vllm_benchmark_config.py" \
+    --backend "$backend" --instruction-format "$fmt"
+
+  "${ROOT}/restart.sh" reranker
+  wait_health "$backend" "$fmt"
+
+  if ! "$PYTHON" "${ROOT}/scripts/benchmark_reranker_random_titles.py" \
+    100,200,400,600,800,1000 \
+    --repeat 5 \
+    --seed 42 \
+    --quiet-runs \
+    --timeout 360 \
+    --tag "$tag" \
+    --json-summary-out "$jf"
+  then
+    echo "[warn] benchmark exited non-zero for ${tag} (see ${jf} failed flag / partial runs)" >&2
+  fi
+
+  echo "artifact: $jf"
+}
+
+run_one qwen3_vllm compact
+run_one qwen3_vllm standard
+run_one qwen3_vllm_score compact
+run_one qwen3_vllm_score standard
+
+# Restore repo-default-style rerank settings (score + compact).
+"$PYTHON" "${ROOT}/scripts/patch_rerank_vllm_benchmark_config.py" \
+  --backend qwen3_vllm_score --instruction-format compact
+"${ROOT}/restart.sh" reranker
+wait_health qwen3_vllm_score compact
+echo "Restored config: qwen3_vllm_score + compact. Done. Artifacts under ${OUT_DIR}"
 #!/bin/bash
 #
-# Create isolated venv for reranker service (.venv-reranker).
+# Create isolated venv for one reranker backend.
 #
 set -euo pipefail
  
 PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "${PROJECT_ROOT}"
  
-VENV_DIR="${PROJECT_ROOT}/.venv-reranker"
 PYTHON_BIN="${PYTHON_BIN:-python3}"
 TMP_DIR="${RERANKER_PIP_TMPDIR:-${PROJECT_ROOT}/.tmp/reranker-pip}"
  
+# shellcheck source=scripts/lib/load_env.sh
+source "${PROJECT_ROOT}/scripts/lib/load_env.sh"
+load_env_file "${PROJECT_ROOT}/.env"
+# shellcheck source=scripts/lib/reranker_backend_env.sh
+source "${PROJECT_ROOT}/scripts/lib/reranker_backend_env.sh"
+
+BACKEND="${1:-$(detect_rerank_backend "${PROJECT_ROOT}")}"
+VENV_DIR="${RERANKER_VENV:-$(reranker_backend_venv_dir "${PROJECT_ROOT}" "${BACKEND}")}"
+REQ_FILE="$(reranker_backend_requirements_file "${PROJECT_ROOT}" "${BACKEND}")"
+
+if [[ ! -f "${REQ_FILE}" ]]; then
+  echo "ERROR: requirements file not found for reranker backend ${BACKEND}: ${REQ_FILE}" >&2
+  exit 1
+fi
+
 if ! command -v "${PYTHON_BIN}" >/dev/null 2>&1; then
   echo "ERROR: python not found: ${PYTHON_BIN}" >&2
   exit 1
@@ -34,9 +48,35 @@ PIP_ARGS=(--no-cache-dir)
  
 echo "Using TMPDIR=${TMPDIR}"
 "${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" --upgrade pip wheel
-"${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" -r requirements_reranker_service.txt
+"${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" -r "${REQ_FILE}"
+
+if [[ "${BACKEND}" == qwen3_gguf* ]]; then
+  if [[ -x "/usr/local/cuda/bin/nvcc" ]]; then
+    "${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" \
+      cmake \
+      ninja \
+      scikit-build-core \
+      flit_core \
+      setuptools-scm
+    echo "Rebuilding llama-cpp-python with CUDA support for ${BACKEND}"
+    PATH="/usr/local/cuda/bin:/usr/bin:/bin" \
+    CC="/usr/bin/x86_64-linux-gnu-gcc" \
+    CXX="/usr/bin/x86_64-linux-gnu-g++" \
+    CUDACXX="/usr/local/cuda/bin/nvcc" \
+    CMAKE_ARGS="-DGGML_CUDA=on" \
+    FORCE_CMAKE=1 \
+    "${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" \
+      --force-reinstall \
+      --no-build-isolation \
+      "llama-cpp-python==0.3.18"
+  else
+    echo "WARNING: /usr/local/cuda/bin/nvcc not found; ${BACKEND} will be installed without CUDA support." >&2
+  fi
+fi
  
 echo
 echo "Done."
+echo "Backend: ${BACKEND}"
 echo "Reranker venv: ${VENV_DIR}"
+echo "Requirements: ${REQ_FILE}"
 echo "Start service: ./scripts/start_reranker.sh"
 #!/bin/bash
 #
-# Start reranker service from isolated venv (.venv-reranker).
+# Start reranker service from its backend-specific isolated venv.
 #
 set -euo pipefail
  
 PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "${PROJECT_ROOT}"
  
-RERANKER_VENV="${RERANKER_VENV:-${PROJECT_ROOT}/.venv-reranker}"
-PYTHON_BIN="${RERANKER_VENV}/bin/python"
-
-if [[ ! -x "${PYTHON_BIN}" ]]; then
-  echo "ERROR: reranker venv not found: ${RERANKER_VENV}" >&2
-  echo "Please run: ./scripts/setup_reranker_venv.sh" >&2
-  exit 1
-fi
-
 # Load .env without activating main venv.
 # shellcheck source=scripts/lib/load_env.sh
 source "${PROJECT_ROOT}/scripts/lib/load_env.sh"
 load_env_file "${PROJECT_ROOT}/.env"
+# shellcheck source=scripts/lib/reranker_backend_env.sh
+source "${PROJECT_ROOT}/scripts/lib/reranker_backend_env.sh"
  
 RERANKER_HOST="${RERANKER_HOST:-0.0.0.0}"
 RERANKER_PORT="${RERANKER_PORT:-6007}"
-RERANK_BACKEND=$("${PYTHON_BIN}" -c "from config.services_config import get_rerank_backend_config; print(get_rerank_backend_config()[0])")
+RERANK_BACKEND="${RERANK_BACKEND:-$(detect_rerank_backend "${PROJECT_ROOT}")}"
+RERANKER_VENV="${RERANKER_VENV:-$(reranker_backend_venv_dir "${PROJECT_ROOT}" "${RERANK_BACKEND}")}"
+PYTHON_BIN="${RERANKER_VENV}/bin/python"
+
+if [[ ! -x "${PYTHON_BIN}" ]]; then
+  echo "ERROR: reranker venv not found for backend ${RERANK_BACKEND}: ${RERANKER_VENV}" >&2
+  echo "Please run: ./scripts/setup_reranker_venv.sh ${RERANK_BACKEND}" >&2
+  exit 1
+fi
  
 # Keep vLLM/triton/torch caches out of system disk.
 RERANKER_RUNTIME_DIR="${RERANKER_RUNTIME_DIR:-${PROJECT_ROOT}/.runtime/reranker}"
@@ -42,23 +43,56 @@ export TMPDIR=&quot;${RERANKER_RUNTIME_DIR}/tmp&quot;
 export VLLM_NO_USAGE_STATS="${VLLM_NO_USAGE_STATS:-1}"
 export PATH="${RERANKER_VENV}/bin:${PATH}"
  
-if [[ "${RERANK_BACKEND}" == "qwen3_vllm" ]]; then
+if [[ "${RERANK_BACKEND}" == qwen3_gguf* ]]; then
+  export HF_HUB_DISABLE_XET="${HF_HUB_DISABLE_XET:-1}"
+fi
+
+if [[ "${RERANK_BACKEND}" == "qwen3_vllm" || "${RERANK_BACKEND}" == "qwen3_vllm_score" || "${RERANK_BACKEND}" == "qwen3_transformers_packed" ]]; then
   if ! command -v nvidia-smi >/dev/null 2>&1 || ! nvidia-smi >/dev/null 2>&1; then
-    echo "ERROR: qwen3_vllm backend requires NVIDIA GPU, but nvidia-smi is unavailable." >&2
+    echo "ERROR: ${RERANK_BACKEND} backend requires NVIDIA GPU, but nvidia-smi is unavailable." >&2
     exit 1
   fi
   if ! "${PYTHON_BIN}" - <<'PY'
 try:
-    import vllm  # noqa: F401
     import torch
+    try:
+        import vllm  # noqa: F401
+    except Exception:
+        pass
     if not torch.cuda.is_available():
         raise SystemExit(1)
 except Exception:
     raise SystemExit(1)
 PY
   then
-    echo "ERROR: qwen3_vllm backend requires vllm + CUDA runtime in ${RERANKER_VENV}." >&2
-    echo "Please run: ./scripts/setup_reranker_venv.sh and verify CUDA is available." >&2
+    if [[ "${RERANK_BACKEND}" == "qwen3_transformers_packed" ]]; then
+      echo "ERROR: ${RERANK_BACKEND} backend requires torch + CUDA runtime in ${RERANKER_VENV}." >&2
+    else
+      echo "ERROR: ${RERANK_BACKEND} backend requires vllm + CUDA runtime in ${RERANKER_VENV}." >&2
+    fi
+    echo "Please run: ./scripts/setup_reranker_venv.sh ${RERANK_BACKEND} and verify CUDA is available." >&2
+    exit 1
+  fi
+fi
+
+if [[ "${RERANK_BACKEND}" == qwen3_gguf* ]]; then
+  gguf_check_status=0
+  "${PYTHON_BIN}" - <<'PY' || gguf_check_status=$?
+try:
+    import llama_cpp
+    if hasattr(llama_cpp, "llama_supports_gpu_offload") and not llama_cpp.llama_supports_gpu_offload():
+        raise SystemExit(2)
+except Exception:
+    raise SystemExit(1)
+PY
+  if [[ "${gguf_check_status}" != "0" ]]; then
+    if [[ "${gguf_check_status}" == "2" ]]; then
+      echo "ERROR: ${RERANK_BACKEND} backend detected a CPU-only llama-cpp-python build in ${RERANKER_VENV}." >&2
+      echo "Please rerun: ./scripts/setup_reranker_venv.sh ${RERANK_BACKEND}" >&2
+    else
+      echo "ERROR: ${RERANK_BACKEND} backend requires llama-cpp-python in ${RERANKER_VENV}." >&2
+      echo "Please run: ./scripts/setup_reranker_venv.sh ${RERANK_BACKEND}" >&2
+    fi
     exit 1
   fi
 fi
@@ -200,19 +200,24 @@ def _multiply_fusion_factors(
     knn_score: float,
     fusion: RerankFusionConfig,
 ) -> Tuple[float, float, float, float]:
-    """(rerank_factor, text_factor, knn_factor, fused)."""
+    """(rerank_factor, text_factor, knn_factor, fused_without_style_boost)."""
     r = (max(rerank_score, 0.0) + fusion.rerank_bias) ** fusion.rerank_exponent
     t = (max(text_score, 0.0) + fusion.text_bias) ** fusion.text_exponent
     k = (max(knn_score, 0.0) + fusion.knn_bias) ** fusion.knn_exponent
     return r, t, k, r * t * k
  
  
+def _has_selected_sku(hit: Dict[str, Any]) -> bool:
+    return bool(str(hit.get("_style_rerank_suffix") or "").strip())
+
+
 def fuse_scores_and_resort(
     es_hits: List[Dict[str, Any]],
     rerank_scores: List[float],
     weight_es: float = DEFAULT_WEIGHT_ES,
     weight_ai: float = DEFAULT_WEIGHT_AI,
     fusion: Optional[RerankFusionConfig] = None,
+    style_intent_selected_sku_boost: float = 1.2,
     debug: bool = False,
     rerank_debug_rows: Optional[List[Dict[str, Any]]] = None,
 ) -> List[Dict[str, Any]]:
@@ -220,7 +225,10 @@ def fuse_scores_and_resort(
     将 ES 分数与重排分数按乘法公式融合（不修改原始 _score），并按融合分数降序重排。
  
     融合形式（由 ``fusion`` 配置 bias / exponent）::
-        fused = (max(rerank,0)+b_r)^e_r * (max(text,0)+b_t)^e_t * (max(knn,0)+b_k)^e_k
+        fused = (max(rerank,0)+b_r)^e_r * (max(text,0)+b_t)^e_t * (max(knn,0)+b_k)^e_k * sku_boost
+
+    其中 sku_boost 仅在当前 hit 已选中 SKU 时生效，默认值为 1.2，可通过
+    ``query.style_intent.selected_sku_boost`` 配置。
  
     对每条 hit 会写入：
     - _original_score: 原始 ES 分数
@@ -252,12 +260,16 @@ def fuse_scores_and_resort(
         rerank_factor, text_factor, knn_factor, fused = _multiply_fusion_factors(
             rerank_score, text_score, knn_score, f
         )
+        sku_selected = _has_selected_sku(hit)
+        style_boost = style_intent_selected_sku_boost if sku_selected else 1.0
+        fused *= style_boost
  
         hit["_original_score"] = hit.get("_score")
         hit["_rerank_score"] = rerank_score
         hit["_text_score"] = text_score
         hit["_knn_score"] = knn_score
         hit["_fused_score"] = fused
+        hit["_style_intent_selected_sku_boost"] = style_boost
         if debug:
             hit["_text_source_score"] = text_components["source_score"]
             hit["_text_translation_score"] = text_components["translation_score"]
@@ -285,6 +297,8 @@ def fuse_scores_and_resort(
                 "rerank_factor": rerank_factor,
                 "text_factor": text_factor,
                 "knn_factor": knn_factor,
+                "style_intent_selected_sku": sku_selected,
+                "style_intent_selected_sku_boost": style_boost,
                 "matched_queries": matched_queries,
                 "fused_score": fused,
             }
@@ -311,6 +325,7 @@ def run_rerank(
     top_n: Optional[int] = None,
     debug: bool = False,
     fusion: Optional[RerankFusionConfig] = None,
+    style_intent_selected_sku_boost: float = 1.2,
 ) -> Tuple[Dict[str, Any], Optional[Dict[str, Any]], List[Dict[str, Any]]]:
     """
     完整重排流程：从 es_response 取 hits -> 构造 docs -> 调服务 -> 融合分数并重排 -> 更新 max_score。
@@ -345,6 +360,7 @@ def run_rerank(
         weight_es=weight_es,
         weight_ai=weight_ai,
         fusion=fusion,
+        style_intent_selected_sku_boost=style_intent_selected_sku_boost,
         debug=debug,
         rerank_debug_rows=rerank_debug_rows,
     )
@@ -594,6 +594,7 @@ class Searcher:
                     top_n=(from_ + size),
                     debug=debug,
                     fusion=rc.fusion,
+                    style_intent_selected_sku_boost=self.config.query_config.style_intent_selected_sku_boost,
                 )
  
                 if rerank_meta is not None:
@@ -1055,4 +1056,3 @@ class Searcher:
         except Exception as e:
             logger.error(f"Failed to get document {doc_id} from tenant {tenant_id}: {e}", exc_info=True)
             return None
-
@@ -5,12 +5,10 @@ SKU selection for style-intent-aware search results.
 from __future__ import annotations
  
 from dataclasses import dataclass, field
-from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
-
-import numpy as np
+from typing import Any, Callable, Dict, List, Optional, Tuple
  
 from query.style_intent import StyleIntentProfile, StyleIntentRegistry
-from query.tokenization import normalize_query_text
+from query.tokenization import normalize_query_text, simple_tokenize_query
  
  
 @dataclass(frozen=True)
@@ -34,24 +32,11 @@ class SkuSelectionDecision:
  
  
 @dataclass
-class _SkuCandidate:
-    index: int
-    sku_id: str
-    sku: Dict[str, Any]
-    selection_text: str
-    normalized_selection_text: str
-    intent_values: Dict[str, str]
-    normalized_intent_values: Dict[str, str]
-
-
-@dataclass
 class _SelectionContext:
-    query_texts: Tuple[str, ...]
-    matched_terms_by_intent: Dict[str, Tuple[str, ...]]
-    query_vector: Optional[np.ndarray]
+    attribute_terms_by_intent: Dict[str, Tuple[str, ...]]
+    normalized_text_cache: Dict[str, str] = field(default_factory=dict)
+    tokenized_text_cache: Dict[str, Tuple[str, ...]] = field(default_factory=dict)
     text_match_cache: Dict[Tuple[str, str], bool] = field(default_factory=dict)
-    selection_vector_cache: Dict[str, Optional[np.ndarray]] = field(default_factory=dict)
-    similarity_cache: Dict[str, Optional[float]] = field(default_factory=dict)
  
  
 class StyleSkuSelector:
@@ -76,7 +61,7 @@ class StyleSkuSelector:
         if not isinstance(style_profile, StyleIntentProfile) or not style_profile.is_active:
             return decisions
  
-        selection_context = self._build_selection_context(parsed_query, style_profile)
+        selection_context = self._build_selection_context(style_profile)
  
         for hit in es_hits:
             source = hit.get("_source")
@@ -126,81 +111,37 @@ class StyleSkuSelector:
             else:
                 hit.pop("_style_rerank_suffix", None)
  
-    def _build_query_texts(
-        self,
-        parsed_query: Any,
-        style_profile: StyleIntentProfile,
-    ) -> List[str]:
-        texts = [variant.normalized_text for variant in style_profile.query_variants if variant.normalized_text]
-        if texts:
-            return list(dict.fromkeys(texts))
-
-        fallbacks: List[str] = []
-        for value in (
-            getattr(parsed_query, "original_query", None),
-            getattr(parsed_query, "query_normalized", None),
-            getattr(parsed_query, "rewritten_query", None),
-        ):
-            normalized = normalize_query_text(value)
-            if normalized:
-                fallbacks.append(normalized)
-        translations = getattr(parsed_query, "translations", {}) or {}
-        if isinstance(translations, dict):
-            for value in translations.values():
-                normalized = normalize_query_text(value)
-                if normalized:
-                    fallbacks.append(normalized)
-        return list(dict.fromkeys(fallbacks))
-
-    def _get_query_vector(self, parsed_query: Any) -> Optional[np.ndarray]:
-        query_vector = getattr(parsed_query, "query_vector", None)
-        if query_vector is not None:
-            return np.asarray(query_vector, dtype=np.float32)
-
-        text_encoder = self._get_text_encoder()
-        if text_encoder is None:
-            return None
-
-        query_text = (
-            getattr(parsed_query, "rewritten_query", None)
-            or getattr(parsed_query, "query_normalized", None)
-            or getattr(parsed_query, "original_query", None)
-        )
-        if not query_text:
-            return None
-
-        vectors = text_encoder.encode([query_text], priority=1)
-        if vectors is None or len(vectors) == 0 or vectors[0] is None:
-            return None
-        return np.asarray(vectors[0], dtype=np.float32)
-
     def _build_selection_context(
         self,
-        parsed_query: Any,
         style_profile: StyleIntentProfile,
     ) -> _SelectionContext:
-        matched_terms_by_intent: Dict[str, List[str]] = {}
+        attribute_terms_by_intent: Dict[str, List[str]] = {}
         for intent in style_profile.intents:
-            normalized_term = normalize_query_text(intent.matched_term)
-            if not normalized_term:
-                continue
-            matched_terms = matched_terms_by_intent.setdefault(intent.intent_type, [])
-            if normalized_term not in matched_terms:
-                matched_terms.append(normalized_term)
+            terms = attribute_terms_by_intent.setdefault(intent.intent_type, [])
+            for raw_term in intent.attribute_terms:
+                normalized_term = normalize_query_text(raw_term)
+                if not normalized_term or normalized_term in terms:
+                    continue
+                terms.append(normalized_term)
  
         return _SelectionContext(
-            query_texts=tuple(self._build_query_texts(parsed_query, style_profile)),
-            matched_terms_by_intent={
+            attribute_terms_by_intent={
                 intent_type: tuple(terms)
-                for intent_type, terms in matched_terms_by_intent.items()
+                for intent_type, terms in attribute_terms_by_intent.items()
             },
-            query_vector=self._get_query_vector(parsed_query),
         )
  
-    def _get_text_encoder(self) -> Any:
-        if self._text_encoder_getter is None:
-            return None
-        return self._text_encoder_getter()
+    @staticmethod
+    def _normalize_cached(selection_context: _SelectionContext, value: Any) -> str:
+        raw = str(value or "").strip()
+        if not raw:
+            return ""
+        cached = selection_context.normalized_text_cache.get(raw)
+        if cached is not None:
+            return cached
+        normalized = normalize_query_text(raw)
+        selection_context.normalized_text_cache[raw] = normalized
+        return normalized
  
     def _resolve_dimensions(
         self,
@@ -225,51 +166,6 @@ class StyleSkuSelector:
             resolved[intent.intent_type] = matched_field
         return resolved
  
-    def _build_candidates(
-        self,
-        skus: List[Dict[str, Any]],
-        resolved_dimensions: Dict[str, Optional[str]],
-    ) -> List[_SkuCandidate]:
-        if not resolved_dimensions or any(not field_name for field_name in resolved_dimensions.values()):
-            return []
-
-        candidates: List[_SkuCandidate] = []
-        for index, sku in enumerate(skus):
-            intent_values: Dict[str, str] = {}
-            normalized_intent_values: Dict[str, str] = {}
-            for intent_type, field_name in resolved_dimensions.items():
-                if not field_name:
-                    continue
-                raw = str(sku.get(field_name) or "").strip()
-                intent_values[intent_type] = raw
-                normalized_intent_values[intent_type] = normalize_query_text(raw)
-
-            selection_parts: List[str] = []
-            norm_parts: List[str] = []
-            seen: set[str] = set()
-            for intent_type, raw in intent_values.items():
-                nv = normalized_intent_values[intent_type]
-                if not nv or nv in seen:
-                    continue
-                seen.add(nv)
-                selection_parts.append(raw)
-                norm_parts.append(nv)
-
-            selection_text = " ".join(selection_parts).strip()
-            normalized_selection_text = " ".join(norm_parts).strip()
-            candidates.append(
-                _SkuCandidate(
-                    index=index,
-                    sku_id=str(sku.get("sku_id") or ""),
-                    sku=sku,
-                    selection_text=selection_text,
-                    normalized_selection_text=normalized_selection_text,
-                    intent_values=intent_values,
-                    normalized_intent_values=normalized_intent_values,
-                )
-            )
-        return candidates
-
     @staticmethod
     def _empty_decision(
         resolved_dimensions: Dict[str, Optional[str]],
@@ -286,13 +182,10 @@ class StyleSkuSelector:
     def _is_text_match(
         self,
         intent_type: str,
-        value: str,
         selection_context: _SelectionContext,
         *,
-        normalized_value: Optional[str] = None,
+        normalized_value: str,
     ) -> bool:
-        if normalized_value is None:
-            normalized_value = normalize_query_text(value)
         if not normalized_value:
             return False
  
@@ -301,84 +194,94 @@ class StyleSkuSelector:
         if cached is not None:
             return cached
  
-        matched_terms = selection_context.matched_terms_by_intent.get(intent_type, ())
-        has_term_match = any(term in normalized_value for term in matched_terms if term)
-        query_contains_value = any(
-            normalized_value in query_text
-            for query_text in selection_context.query_texts
+        attribute_terms = selection_context.attribute_terms_by_intent.get(intent_type, ())
+        value_tokens = self._tokenize_cached(selection_context, normalized_value)
+        matched = any(
+            self._matches_term_tokens(
+                term=term,
+                value_tokens=value_tokens,
+                selection_context=selection_context,
+                normalized_value=normalized_value,
+            )
+            for term in attribute_terms
+            if term
         )
-        matched = bool(has_term_match or query_contains_value)
         selection_context.text_match_cache[cache_key] = matched
         return matched
  
-    def _find_first_text_match(
+    @staticmethod
+    def _tokenize_cached(selection_context: _SelectionContext, value: str) -> Tuple[str, ...]:
+        normalized_value = normalize_query_text(value)
+        if not normalized_value:
+            return ()
+        cached = selection_context.tokenized_text_cache.get(normalized_value)
+        if cached is not None:
+            return cached
+        tokens = tuple(normalize_query_text(token) for token in simple_tokenize_query(normalized_value) if token)
+        selection_context.tokenized_text_cache[normalized_value] = tokens
+        return tokens
+
+    def _matches_term_tokens(
         self,
-        candidates: Sequence[_SkuCandidate],
+        *,
+        term: str,
+        value_tokens: Tuple[str, ...],
         selection_context: _SelectionContext,
-    ) -> Optional[_SkuCandidate]:
-        for candidate in candidates:
-            if candidate.intent_values and all(
-                self._is_text_match(
-                    intent_type,
-                    value,
-                    selection_context,
-                    normalized_value=candidate.normalized_intent_values[intent_type],
-                )
-                for intent_type, value in candidate.intent_values.items()
-            ):
-                return candidate
-        return None
+        normalized_value: str,
+    ) -> bool:
+        normalized_term = normalize_query_text(term)
+        if not normalized_term:
+            return False
+        if normalized_term == normalized_value:
+            return True
  
-    def _select_by_embedding(
+        term_tokens = self._tokenize_cached(selection_context, normalized_term)
+        if not term_tokens or not value_tokens:
+            return normalized_term in normalized_value
+
+        term_length = len(term_tokens)
+        value_length = len(value_tokens)
+        if term_length > value_length:
+            return False
+
+        for start in range(value_length - term_length + 1):
+            if value_tokens[start:start + term_length] == term_tokens:
+                return True
+        return False
+
+    def _find_first_text_match(
         self,
-        candidates: Sequence[_SkuCandidate],
+        skus: List[Dict[str, Any]],
+        resolved_dimensions: Dict[str, Optional[str]],
         selection_context: _SelectionContext,
-    ) -> Tuple[Optional[_SkuCandidate], Optional[float]]:
-        if not candidates:
-            return None, None
-        text_encoder = self._get_text_encoder()
-        if selection_context.query_vector is None or text_encoder is None:
-            return None, None
-
-        unique_texts = list(
-            dict.fromkeys(
-                candidate.normalized_selection_text
-                for candidate in candidates
-                if candidate.normalized_selection_text
-                and candidate.normalized_selection_text not in selection_context.selection_vector_cache
-            )
-        )
-        if unique_texts:
-            vectors = text_encoder.encode(unique_texts, priority=1)
-            for key, vector in zip(unique_texts, vectors):
-                selection_context.selection_vector_cache[key] = (
-                    np.asarray(vector, dtype=np.float32) if vector is not None else None
-                )
-
-        best_candidate: Optional[_SkuCandidate] = None
-        best_score: Optional[float] = None
-        query_vector_array = np.asarray(selection_context.query_vector, dtype=np.float32)
-        for candidate in candidates:
-            normalized_text = candidate.normalized_selection_text
-            if not normalized_text:
-                continue
+    ) -> Optional[Tuple[str, str]]:
+        for sku in skus:
+            selection_parts: List[str] = []
+            seen_parts: set[str] = set()
+            matched = True
  
-            score = selection_context.similarity_cache.get(normalized_text)
-            if score is None:
-                candidate_vector = selection_context.selection_vector_cache.get(normalized_text)
-                if candidate_vector is None:
-                    selection_context.similarity_cache[normalized_text] = None
-                    continue
-                score = float(np.inner(query_vector_array, candidate_vector))
-                selection_context.similarity_cache[normalized_text] = score
+            for intent_type, field_name in resolved_dimensions.items():
+                if not field_name:
+                    matched = False
+                    break
  
-            if score is None:
-                continue
-            if best_score is None or score > best_score:
-                best_candidate = candidate
-                best_score = score
+                raw_value = str(sku.get(field_name) or "").strip()
+                normalized_value = self._normalize_cached(selection_context, raw_value)
+                if not self._is_text_match(
+                    intent_type,
+                    selection_context,
+                    normalized_value=normalized_value,
+                ):
+                    matched = False
+                    break
  
-        return best_candidate, best_score
+                if raw_value and normalized_value not in seen_parts:
+                    seen_parts.add(normalized_value)
+                    selection_parts.append(raw_value)
+
+            if matched:
+                return str(sku.get("sku_id") or ""), " ".join(selection_parts).strip()
+        return None
  
     def _select_for_source(
         self,
@@ -395,36 +298,29 @@ class StyleSkuSelector:
         if not resolved_dimensions or any(not field_name for field_name in resolved_dimensions.values()):
             return self._empty_decision(resolved_dimensions, matched_stage="unresolved")
  
-        candidates = self._build_candidates(skus, resolved_dimensions)
-        if not candidates:
-            return self._empty_decision(resolved_dimensions, matched_stage="no_candidates")
-
-        text_match = self._find_first_text_match(candidates, selection_context)
-        if text_match is not None:
-            return self._build_decision(text_match, resolved_dimensions, matched_stage="text")
-
-        chosen, similarity_score = self._select_by_embedding(candidates, selection_context)
-        if chosen is None:
+        text_match = self._find_first_text_match(skus, resolved_dimensions, selection_context)
+        if text_match is None:
             return self._empty_decision(resolved_dimensions, matched_stage="no_match")
         return self._build_decision(
-            chosen,
-            resolved_dimensions,
-            matched_stage="embedding",
-            similarity_score=similarity_score,
+            selected_sku_id=text_match[0],
+            selected_text=text_match[1],
+            resolved_dimensions=resolved_dimensions,
+            matched_stage="text",
         )
  
     @staticmethod
     def _build_decision(
-        candidate: _SkuCandidate,
+        selected_sku_id: str,
+        selected_text: str,
         resolved_dimensions: Dict[str, Optional[str]],
         *,
         matched_stage: str,
         similarity_score: Optional[float] = None,
     ) -> SkuSelectionDecision:
         return SkuSelectionDecision(
-            selected_sku_id=candidate.sku_id or None,
-            rerank_suffix=str(candidate.selection_text or "").strip(),
-            selected_text=str(candidate.selection_text or "").strip(),
+            selected_sku_id=selected_sku_id or None,
+            rerank_suffix=str(selected_text or "").strip(),
+            selected_text=str(selected_text or "").strip(),
             matched_stage=matched_stage,
             similarity_score=similarity_score,
             resolved_dimensions=dict(resolved_dimensions),
@@ -0,0 +1,452 @@
+"""
+SKU selection for style-intent-aware search results.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from query.style_intent import StyleIntentProfile, StyleIntentRegistry
+from query.tokenization import normalize_query_text
+
+
+@dataclass(frozen=True)
+class SkuSelectionDecision:
+    selected_sku_id: Optional[str]
+    rerank_suffix: str
+    selected_text: str
+    matched_stage: str
+    similarity_score: Optional[float] = None
+    resolved_dimensions: Dict[str, Optional[str]] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "selected_sku_id": self.selected_sku_id,
+            "rerank_suffix": self.rerank_suffix,
+            "selected_text": self.selected_text,
+            "matched_stage": self.matched_stage,
+            "similarity_score": self.similarity_score,
+            "resolved_dimensions": dict(self.resolved_dimensions),
+        }
+
+
+@dataclass
+class _SkuCandidate:
+    index: int
+    sku_id: str
+    sku: Dict[str, Any]
+    selection_text: str
+    normalized_selection_text: str
+    intent_values: Dict[str, str]
+    normalized_intent_values: Dict[str, str]
+
+
+@dataclass
+class _SelectionContext:
+    query_texts: Tuple[str, ...]
+    matched_terms_by_intent: Dict[str, Tuple[str, ...]]
+    query_vector: Optional[np.ndarray]
+    text_match_cache: Dict[Tuple[str, str], bool] = field(default_factory=dict)
+    selection_vector_cache: Dict[str, Optional[np.ndarray]] = field(default_factory=dict)
+    similarity_cache: Dict[str, Optional[float]] = field(default_factory=dict)
+
+
+class StyleSkuSelector:
+    """Selects the best SKU for an SPU based on detected style intent."""
+
+    def __init__(
+        self,
+        registry: StyleIntentRegistry,
+        *,
+        text_encoder_getter: Optional[Callable[[], Any]] = None,
+    ) -> None:
+        self.registry = registry
+        self._text_encoder_getter = text_encoder_getter
+
+    def prepare_hits(
+        self,
+        es_hits: List[Dict[str, Any]],
+        parsed_query: Any,
+    ) -> Dict[str, SkuSelectionDecision]:
+        decisions: Dict[str, SkuSelectionDecision] = {}
+        style_profile = getattr(parsed_query, "style_intent_profile", None)
+        if not isinstance(style_profile, StyleIntentProfile) or not style_profile.is_active:
+            return decisions
+
+        selection_context = self._build_selection_context(parsed_query, style_profile)
+
+        for hit in es_hits:
+            source = hit.get("_source")
+            if not isinstance(source, dict):
+                continue
+
+            decision = self._select_for_source(
+                source,
+                style_profile=style_profile,
+                selection_context=selection_context,
+            )
+            if decision is None:
+                continue
+
+            if decision.rerank_suffix:
+                hit["_style_rerank_suffix"] = decision.rerank_suffix
+            else:
+                hit.pop("_style_rerank_suffix", None)
+
+            doc_id = hit.get("_id")
+            if doc_id is not None:
+                decisions[str(doc_id)] = decision
+
+        return decisions
+
+    def apply_precomputed_decisions(
+        self,
+        es_hits: List[Dict[str, Any]],
+        decisions: Dict[str, SkuSelectionDecision],
+    ) -> None:
+        if not es_hits or not decisions:
+            return
+
+        for hit in es_hits:
+            doc_id = hit.get("_id")
+            if doc_id is None:
+                continue
+            decision = decisions.get(str(doc_id))
+            if decision is None:
+                continue
+            source = hit.get("_source")
+            if not isinstance(source, dict):
+                continue
+            self._apply_decision_to_source(source, decision)
+            if decision.rerank_suffix:
+                hit["_style_rerank_suffix"] = decision.rerank_suffix
+            else:
+                hit.pop("_style_rerank_suffix", None)
+
+    def _build_query_texts(
+        self,
+        parsed_query: Any,
+        style_profile: StyleIntentProfile,
+    ) -> List[str]:
+        texts = [variant.normalized_text for variant in style_profile.query_variants if variant.normalized_text]
+        if texts:
+            return list(dict.fromkeys(texts))
+
+        fallbacks: List[str] = []
+        for value in (
+            getattr(parsed_query, "original_query", None),
+            getattr(parsed_query, "query_normalized", None),
+            getattr(parsed_query, "rewritten_query", None),
+        ):
+            normalized = normalize_query_text(value)
+            if normalized:
+                fallbacks.append(normalized)
+        translations = getattr(parsed_query, "translations", {}) or {}
+        if isinstance(translations, dict):
+            for value in translations.values():
+                normalized = normalize_query_text(value)
+                if normalized:
+                    fallbacks.append(normalized)
+        return list(dict.fromkeys(fallbacks))
+
+    def _get_query_vector(self, parsed_query: Any) -> Optional[np.ndarray]:
+        query_vector = getattr(parsed_query, "query_vector", None)
+        if query_vector is not None:
+            return np.asarray(query_vector, dtype=np.float32)
+
+        text_encoder = self._get_text_encoder()
+        if text_encoder is None:
+            return None
+
+        query_text = (
+            getattr(parsed_query, "rewritten_query", None)
+            or getattr(parsed_query, "query_normalized", None)
+            or getattr(parsed_query, "original_query", None)
+        )
+        if not query_text:
+            return None
+
+        vectors = text_encoder.encode([query_text], priority=1)
+        if vectors is None or len(vectors) == 0 or vectors[0] is None:
+            return None
+        return np.asarray(vectors[0], dtype=np.float32)
+
+    def _build_selection_context(
+        self,
+        parsed_query: Any,
+        style_profile: StyleIntentProfile,
+    ) -> _SelectionContext:
+        matched_terms_by_intent: Dict[str, List[str]] = {}
+        for intent in style_profile.intents:
+            normalized_term = normalize_query_text(intent.matched_term)
+            if not normalized_term:
+                continue
+            matched_terms = matched_terms_by_intent.setdefault(intent.intent_type, [])
+            if normalized_term not in matched_terms:
+                matched_terms.append(normalized_term)
+
+        return _SelectionContext(
+            query_texts=tuple(self._build_query_texts(parsed_query, style_profile)),
+            matched_terms_by_intent={
+                intent_type: tuple(terms)
+                for intent_type, terms in matched_terms_by_intent.items()
+            },
+            query_vector=self._get_query_vector(parsed_query),
+        )
+
+    def _get_text_encoder(self) -> Any:
+        if self._text_encoder_getter is None:
+            return None
+        return self._text_encoder_getter()
+
+    def _resolve_dimensions(
+        self,
+        source: Dict[str, Any],
+        style_profile: StyleIntentProfile,
+    ) -> Dict[str, Optional[str]]:
+        option_names = {
+            "option1_value": normalize_query_text(source.get("option1_name")),
+            "option2_value": normalize_query_text(source.get("option2_name")),
+            "option3_value": normalize_query_text(source.get("option3_name")),
+        }
+        resolved: Dict[str, Optional[str]] = {}
+        for intent in style_profile.intents:
+            if intent.intent_type in resolved:
+                continue
+            aliases = set(intent.dimension_aliases or self.registry.get_dimension_aliases(intent.intent_type))
+            matched_field = None
+            for field_name, option_name in option_names.items():
+                if option_name and option_name in aliases:
+                    matched_field = field_name
+                    break
+            resolved[intent.intent_type] = matched_field
+        return resolved
+
+    def _build_candidates(
+        self,
+        skus: List[Dict[str, Any]],
+        resolved_dimensions: Dict[str, Optional[str]],
+    ) -> List[_SkuCandidate]:
+        if not resolved_dimensions or any(not field_name for field_name in resolved_dimensions.values()):
+            return []
+
+        candidates: List[_SkuCandidate] = []
+        for index, sku in enumerate(skus):
+            intent_values: Dict[str, str] = {}
+            normalized_intent_values: Dict[str, str] = {}
+            for intent_type, field_name in resolved_dimensions.items():
+                if not field_name:
+                    continue
+                raw = str(sku.get(field_name) or "").strip()
+                intent_values[intent_type] = raw
+                normalized_intent_values[intent_type] = normalize_query_text(raw)
+
+            selection_parts: List[str] = []
+            norm_parts: List[str] = []
+            seen: set[str] = set()
+            for intent_type, raw in intent_values.items():
+                nv = normalized_intent_values[intent_type]
+                if not nv or nv in seen:
+                    continue
+                seen.add(nv)
+                selection_parts.append(raw)
+                norm_parts.append(nv)
+
+            selection_text = " ".join(selection_parts).strip()
+            normalized_selection_text = " ".join(norm_parts).strip()
+            candidates.append(
+                _SkuCandidate(
+                    index=index,
+                    sku_id=str(sku.get("sku_id") or ""),
+                    sku=sku,
+                    selection_text=selection_text,
+                    normalized_selection_text=normalized_selection_text,
+                    intent_values=intent_values,
+                    normalized_intent_values=normalized_intent_values,
+                )
+            )
+        return candidates
+
+    @staticmethod
+    def _empty_decision(
+        resolved_dimensions: Dict[str, Optional[str]],
+        matched_stage: str,
+    ) -> SkuSelectionDecision:
+        return SkuSelectionDecision(
+            selected_sku_id=None,
+            rerank_suffix="",
+            selected_text="",
+            matched_stage=matched_stage,
+            resolved_dimensions=dict(resolved_dimensions),
+        )
+
+    def _is_text_match(
+        self,
+        intent_type: str,
+        value: str,
+        selection_context: _SelectionContext,
+        *,
+        normalized_value: Optional[str] = None,
+    ) -> bool:
+        if normalized_value is None:
+            normalized_value = normalize_query_text(value)
+        if not normalized_value:
+            return False
+
+        cache_key = (intent_type, normalized_value)
+        cached = selection_context.text_match_cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        matched_terms = selection_context.matched_terms_by_intent.get(intent_type, ())
+        has_term_match = any(term in normalized_value for term in matched_terms if term)
+        query_contains_value = any(
+            normalized_value in query_text
+            for query_text in selection_context.query_texts
+        )
+        matched = bool(has_term_match or query_contains_value)
+        selection_context.text_match_cache[cache_key] = matched
+        return matched
+
+    def _find_first_text_match(
+        self,
+        candidates: Sequence[_SkuCandidate],
+        selection_context: _SelectionContext,
+    ) -> Optional[_SkuCandidate]:
+        for candidate in candidates:
+            if candidate.intent_values and all(
+                self._is_text_match(
+                    intent_type,
+                    value,
+                    selection_context,
+                    normalized_value=candidate.normalized_intent_values[intent_type],
+                )
+                for intent_type, value in candidate.intent_values.items()
+            ):
+                return candidate
+        return None
+
+    def _select_by_embedding(
+        self,
+        candidates: Sequence[_SkuCandidate],
+        selection_context: _SelectionContext,
+    ) -> Tuple[Optional[_SkuCandidate], Optional[float]]:
+        if not candidates:
+            return None, None
+        text_encoder = self._get_text_encoder()
+        if selection_context.query_vector is None or text_encoder is None:
+            return None, None
+
+        unique_texts = list(
+            dict.fromkeys(
+                candidate.normalized_selection_text
+                for candidate in candidates
+                if candidate.normalized_selection_text
+                and candidate.normalized_selection_text not in selection_context.selection_vector_cache
+            )
+        )
+        if unique_texts:
+            vectors = text_encoder.encode(unique_texts, priority=1)
+            for key, vector in zip(unique_texts, vectors):
+                selection_context.selection_vector_cache[key] = (
+                    np.asarray(vector, dtype=np.float32) if vector is not None else None
+                )
+
+        best_candidate: Optional[_SkuCandidate] = None
+        best_score: Optional[float] = None
+        query_vector_array = np.asarray(selection_context.query_vector, dtype=np.float32)
+        for candidate in candidates:
+            normalized_text = candidate.normalized_selection_text
+            if not normalized_text:
+                continue
+
+            score = selection_context.similarity_cache.get(normalized_text)
+            if score is None:
+                candidate_vector = selection_context.selection_vector_cache.get(normalized_text)
+                if candidate_vector is None:
+                    selection_context.similarity_cache[normalized_text] = None
+                    continue
+                score = float(np.inner(query_vector_array, candidate_vector))
+                selection_context.similarity_cache[normalized_text] = score
+
+            if score is None:
+                continue
+            if best_score is None or score > best_score:
+                best_candidate = candidate
+                best_score = score
+
+        return best_candidate, best_score
+
+    def _select_for_source(
+        self,
+        source: Dict[str, Any],
+        *,
+        style_profile: StyleIntentProfile,
+        selection_context: _SelectionContext,
+    ) -> Optional[SkuSelectionDecision]:
+        skus = source.get("skus")
+        if not isinstance(skus, list) or not skus:
+            return None
+
+        resolved_dimensions = self._resolve_dimensions(source, style_profile)
+        if not resolved_dimensions or any(not field_name for field_name in resolved_dimensions.values()):
+            return self._empty_decision(resolved_dimensions, matched_stage="unresolved")
+
+        candidates = self._build_candidates(skus, resolved_dimensions)
+        if not candidates:
+            return self._empty_decision(resolved_dimensions, matched_stage="no_candidates")
+
+        text_match = self._find_first_text_match(candidates, selection_context)
+        if text_match is not None:
+            return self._build_decision(text_match, resolved_dimensions, matched_stage="text")
+
+        chosen, similarity_score = self._select_by_embedding(candidates, selection_context)
+        if chosen is None:
+            return self._empty_decision(resolved_dimensions, matched_stage="no_match")
+        return self._build_decision(
+            chosen,
+            resolved_dimensions,
+            matched_stage="embedding",
+            similarity_score=similarity_score,
+        )
+
+    @staticmethod
+    def _build_decision(
+        candidate: _SkuCandidate,
+        resolved_dimensions: Dict[str, Optional[str]],
+        *,
+        matched_stage: str,
+        similarity_score: Optional[float] = None,
+    ) -> SkuSelectionDecision:
+        return SkuSelectionDecision(
+            selected_sku_id=candidate.sku_id or None,
+            rerank_suffix=str(candidate.selection_text or "").strip(),
+            selected_text=str(candidate.selection_text or "").strip(),
+            matched_stage=matched_stage,
+            similarity_score=similarity_score,
+            resolved_dimensions=dict(resolved_dimensions),
+        )
+
+    @staticmethod
+    def _apply_decision_to_source(source: Dict[str, Any], decision: SkuSelectionDecision) -> None:
+        skus = source.get("skus")
+        if not isinstance(skus, list) or not skus or not decision.selected_sku_id:
+            return
+
+        selected_index = None
+        for index, sku in enumerate(skus):
+            if str(sku.get("sku_id") or "") == decision.selected_sku_id:
+                selected_index = index
+                break
+        if selected_index is None:
+            return
+
+        selected_sku = skus.pop(selected_index)
+        skus.insert(0, selected_sku)
+
+        image_src = selected_sku.get("image_src") or selected_sku.get("imageSrc")
+        if image_src:
+            source["image_url"] = image_src
@@ -118,3 +118,34 @@ def test_fuse_scores_and_resort_uses_configurable_fusion_params():
     by_id = {h["_id"]: h for h in hits}
     assert isclose(by_id["a"]["_fused_score"], 1.0, rel_tol=1e-9)
     assert isclose(by_id["b"]["_fused_score"], 0.0, rel_tol=1e-9)
+
+
+def test_fuse_scores_and_resort_boosts_hits_with_selected_sku():
+    hits = [
+        {
+            "_id": "style-selected",
+            "_score": 1.0,
+            "_style_rerank_suffix": "Blue XL",
+            "matched_queries": {"base_query": 1.0, "knn_query": 0.0},
+        },
+        {
+            "_id": "plain",
+            "_score": 1.0,
+            "matched_queries": {"base_query": 1.0, "knn_query": 0.0},
+        },
+    ]
+
+    debug = fuse_scores_and_resort(
+        hits,
+        [1.0, 1.0],
+        style_intent_selected_sku_boost=1.2,
+        debug=True,
+    )
+
+    by_id = {h["_id"]: h for h in hits}
+    assert isclose(by_id["style-selected"]["_fused_score"], by_id["plain"]["_fused_score"] * 1.2, rel_tol=1e-9)
+    assert by_id["style-selected"]["_style_intent_selected_sku_boost"] == 1.2
+    assert by_id["plain"]["_style_intent_selected_sku_boost"] == 1.0
+    assert [h["_id"] for h in hits] == ["style-selected", "plain"]
+    assert debug[0]["style_intent_selected_sku"] is True
+    assert debug[0]["style_intent_selected_sku_boost"] == 1.2
@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import sys
+import types
+
+from reranker.backends import get_rerank_backend
+from reranker.backends.qwen3_gguf import Qwen3GGUFRerankerBackend
+
+
+class _FakeLlama:
+    def __init__(self, model_path: str | None = None, **kwargs):
+        self.model_path = model_path
+        self.kwargs = kwargs
+        self.eval_logits = []
+        self._tokens = []
+        self.eval_call_count = 0
+
+    @classmethod
+    def from_pretrained(cls, repo_id: str, filename: str, local_dir=None, cache_dir=None, **kwargs):
+        inst = cls(model_path=f"{repo_id}/{filename}", **kwargs)
+        inst.repo_id = repo_id
+        inst.filename = filename
+        inst.local_dir = local_dir
+        inst.cache_dir = cache_dir
+        return inst
+
+    def tokenize(self, text: bytes, add_bos: bool = False, special: bool = False):
+        raw = text.decode("utf-8")
+        if raw == "yes":
+            return [1]
+        if raw == "no":
+            return [2]
+        return [10 + (ord(ch) % 17) for ch in raw]
+
+    def reset(self):
+        self._tokens = []
+        return None
+
+    def eval(self, prompt_tokens):
+        self.eval_call_count += 1
+        self._tokens.extend(prompt_tokens)
+        pos = float(sum(self._tokens) % 11) + 3.0
+        neg = 1.0
+        logits = [0.0] * 64
+        logits[1] = pos
+        logits[2] = neg
+        self.eval_logits = [logits]
+
+    def save_state(self):
+        return list(self._tokens)
+
+    def load_state(self, state):
+        self._tokens = list(state)
+
+
+def _install_fake_llama_cpp(monkeypatch):
+    fake_module = types.SimpleNamespace(Llama=_FakeLlama)
+    monkeypatch.setitem(sys.modules, "llama_cpp", fake_module)
+
+
+def test_qwen3_gguf_backend_factory_loads(monkeypatch):
+    _install_fake_llama_cpp(monkeypatch)
+    backend = get_rerank_backend(
+        "qwen3_gguf",
+        {
+            "repo_id": "DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF",
+            "filename": "*Q8_0.gguf",
+            "enable_warmup": False,
+        },
+    )
+    assert isinstance(backend, Qwen3GGUFRerankerBackend)
+    assert backend._backend_name == "qwen3_gguf"
+
+
+def test_qwen3_gguf_06b_backend_factory_loads(monkeypatch):
+    _install_fake_llama_cpp(monkeypatch)
+    backend = get_rerank_backend(
+        "qwen3_gguf_06b",
+        {
+            "enable_warmup": False,
+        },
+    )
+    assert isinstance(backend, Qwen3GGUFRerankerBackend)
+    assert backend._backend_name == "qwen3_gguf_06b"
+    assert backend._repo_id == "ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF"
+    assert backend._filename == "qwen3-reranker-0.6b-q8_0.gguf"
+
+
+def test_qwen3_gguf_backend_score_with_meta_dedup_and_restore(monkeypatch):
+    _install_fake_llama_cpp(monkeypatch)
+    backend = Qwen3GGUFRerankerBackend(
+        {
+            "repo_id": "DevQuasar/Qwen.Qwen3-Reranker-4B-GGUF",
+            "filename": "*Q8_0.gguf",
+            "enable_warmup": False,
+            "infer_batch_size": 2,
+            "sort_by_doc_length": True,
+            "reuse_query_state": True,
+        }
+    )
+
+    scores, meta = backend.score_with_meta(
+        query="wireless mouse",
+        docs=["doc-a", "doc-b", "doc-a", "", "   ", None],
+        normalize=True,
+    )
+
+    assert len(scores) == 6
+    assert scores[0] == scores[2]
+    assert scores[0] > 0.5
+    assert scores[1] > 0.5
+    assert scores[3:] == [0.0, 0.0, 0.0]
+    assert meta["input_docs"] == 6
+    assert meta["usable_docs"] == 3
+    assert meta["unique_docs"] == 2
+    assert meta["backend"] == "qwen3_gguf"
+    assert meta["inference_batches"] == 1
+    assert meta["reuse_query_state"] is True
+    assert backend._llm.eval_call_count == 3
@@ -63,6 +63,7 @@ def _build_style_intent_profile(intent_type: str, canonical_value: str, *dimensi
                 canonical_value=canonical_value,
                 matched_term=canonical_value,
                 matched_query_text=canonical_value,
+                attribute_terms=(canonical_value,),
                 dimension_aliases=tuple(aliases),
             ),
         )
@@ -0,0 +1,197 @@
+from types import SimpleNamespace
+
+from config import QueryConfig
+from query.style_intent import DetectedStyleIntent, StyleIntentProfile, StyleIntentRegistry
+from search.sku_intent_selector import StyleSkuSelector
+
+
+def test_style_sku_selector_matches_first_sku_by_attribute_terms():
+    registry = StyleIntentRegistry.from_query_config(
+        QueryConfig(
+            style_intent_terms={
+                "color": [{"en_terms": ["navy"], "zh_terms": ["藏青"], "attribute_terms": ["navy"]}],
+                "size": [{"en_terms": ["xl"], "zh_terms": ["加大码"], "attribute_terms": ["x-large"]}],
+            },
+            style_intent_dimension_aliases={
+                "color": ["color", "颜色"],
+                "size": ["size", "尺码"],
+            },
+        )
+    )
+    selector = StyleSkuSelector(registry)
+    parsed_query = SimpleNamespace(
+        style_intent_profile=StyleIntentProfile(
+            intents=(
+                DetectedStyleIntent(
+                    intent_type="color",
+                    canonical_value="navy",
+                    matched_term="藏青",
+                    matched_query_text="藏青",
+                    attribute_terms=("navy",),
+                    dimension_aliases=("color", "颜色"),
+                ),
+                DetectedStyleIntent(
+                    intent_type="size",
+                    canonical_value="x-large",
+                    matched_term="xl",
+                    matched_query_text="xl",
+                    attribute_terms=("x-large",),
+                    dimension_aliases=("size", "尺码"),
+                ),
+            ),
+        )
+    )
+    source = {
+        "option1_name": "Color",
+        "option2_name": "Size",
+        "skus": [
+            {"sku_id": "1", "option1_value": "Black", "option2_value": "M"},
+            {"sku_id": "2", "option1_value": "Navy Blue", "option2_value": "X-Large", "image_src": "matched.jpg"},
+            {"sku_id": "3", "option1_value": "Navy", "option2_value": "XL"},
+        ],
+    }
+    hits = [{"_id": "spu-1", "_source": source}]
+
+    decisions = selector.prepare_hits(hits, parsed_query)
+    decision = decisions["spu-1"]
+
+    assert decision.selected_sku_id == "2"
+    assert decision.selected_text == "Navy Blue X-Large"
+    assert decision.matched_stage == "text"
+
+    selector.apply_precomputed_decisions(hits, decisions)
+
+    assert source["skus"][0]["sku_id"] == "2"
+    assert source["image_url"] == "matched.jpg"
+
+
+def test_style_sku_selector_returns_no_match_without_attribute_contains():
+    registry = StyleIntentRegistry.from_query_config(
+        QueryConfig(
+            style_intent_terms={
+                "color": [{"en_terms": ["beige"], "zh_terms": ["米色"], "attribute_terms": ["beige"]}],
+            },
+            style_intent_dimension_aliases={"color": ["color", "颜色"]},
+        )
+    )
+    selector = StyleSkuSelector(registry)
+    parsed_query = SimpleNamespace(
+        style_intent_profile=StyleIntentProfile(
+            intents=(
+                DetectedStyleIntent(
+                    intent_type="color",
+                    canonical_value="beige",
+                    matched_term="米色",
+                    matched_query_text="米色",
+                    attribute_terms=("beige",),
+                    dimension_aliases=("color", "颜色"),
+                ),
+            ),
+        )
+    )
+    hits = [{
+        "_id": "spu-1",
+        "_source": {
+            "option1_name": "Color",
+            "skus": [
+                {"sku_id": "1", "option1_value": "Khaki"},
+                {"sku_id": "2", "option1_value": "Light Brown"},
+            ],
+        },
+    }]
+
+    decisions = selector.prepare_hits(hits, parsed_query)
+
+    assert decisions["spu-1"].selected_sku_id is None
+    assert decisions["spu-1"].matched_stage == "no_match"
+
+
+def test_is_text_match_uses_token_boundaries_for_sizes():
+    registry = StyleIntentRegistry.from_query_config(
+        QueryConfig(
+            style_intent_terms={
+                "size": [{"en_terms": ["l"], "zh_terms": ["大码"], "attribute_terms": ["l"]}],
+            },
+            style_intent_dimension_aliases={"size": ["size", "尺码"]},
+        )
+    )
+    selector = StyleSkuSelector(registry)
+    style_profile = StyleIntentProfile(
+        intents=(
+            DetectedStyleIntent(
+                intent_type="size",
+                canonical_value="l",
+                matched_term="l",
+                matched_query_text="l",
+                attribute_terms=("l",),
+                dimension_aliases=("size", "尺码"),
+            ),
+        ),
+    )
+    selection_context = selector._build_selection_context(style_profile)
+
+    assert selector._is_text_match("size", selection_context, normalized_value="l")
+    assert not selector._is_text_match("size", selection_context, normalized_value="xl")
+    assert not selector._is_text_match("size", selection_context, normalized_value="xxl")
+
+
+def test_is_text_match_handles_punctuation_and_descriptive_attribute_values():
+    registry = StyleIntentRegistry.from_query_config(
+        QueryConfig(
+            style_intent_terms={
+                "color": [{"en_terms": ["blue"], "zh_terms": ["蓝色"], "attribute_terms": ["blue"]}],
+                "style": [{"en_terms": ["off-white"], "zh_terms": ["米白"], "attribute_terms": ["off-white"]}],
+                "accessory": [{"en_terms": ["headscarf"], "zh_terms": ["头巾"], "attribute_terms": ["headscarf"]}],
+                "size": [{"en_terms": ["2xl"], "zh_terms": ["2xl"], "attribute_terms": ["2xl"]}],
+            },
+            style_intent_dimension_aliases={
+                "color": ["color", "颜色"],
+                "style": ["style", "风格"],
+                "accessory": ["accessory", "配饰"],
+                "size": ["size", "尺码"],
+            },
+        )
+    )
+    selector = StyleSkuSelector(registry)
+    style_profile = StyleIntentProfile(
+        intents=(
+            DetectedStyleIntent(
+                intent_type="color",
+                canonical_value="blue",
+                matched_term="blue",
+                matched_query_text="blue",
+                attribute_terms=("blue",),
+                dimension_aliases=("color", "颜色"),
+            ),
+            DetectedStyleIntent(
+                intent_type="style",
+                canonical_value="off-white",
+                matched_term="off-white",
+                matched_query_text="off-white",
+                attribute_terms=("off-white",),
+                dimension_aliases=("style", "风格"),
+            ),
+            DetectedStyleIntent(
+                intent_type="accessory",
+                canonical_value="headscarf",
+                matched_term="headscarf",
+                matched_query_text="headscarf",
+                attribute_terms=("headscarf",),
+                dimension_aliases=("accessory", "配饰"),
+            ),
+            DetectedStyleIntent(
+                intent_type="size",
+                canonical_value="2xl",
+                matched_term="2xl",
+                matched_query_text="2xl",
+                attribute_terms=("2xl",),
+                dimension_aliases=("size", "尺码"),
+            ),
+        ),
+    )
+    selection_context = selector._build_selection_context(style_profile)
+
+    assert selector._is_text_match("color", selection_context, normalized_value="gray blue")
+    assert selector._is_text_match("style", selection_context, normalized_value="off-white/lined")
+    assert selector._is_text_match("accessory", selection_context, normalized_value="army green + headscarf")
+    assert selector._is_text_match("size", selection_context, normalized_value="2xl recommended 65-70kg")
@@ -7,8 +7,8 @@ from query.style_intent import StyleIntentDetector, StyleIntentRegistry
 def test_style_intent_detector_matches_original_and_translated_queries():
     query_config = QueryConfig(
         style_intent_terms={
-            "color": [["black", "黑色", "black"]],
-            "size": [["xl", "x-large", "加大码"]],
+            "color": [{"en_terms": ["black"], "zh_terms": ["黑色"], "attribute_terms": ["black"]}],
+            "size": [{"en_terms": ["xl", "x-large"], "zh_terms": ["加大码"], "attribute_terms": ["x-large"]}],
         },
         style_intent_dimension_aliases={
             "color": ["color", "颜色"],
@@ -31,5 +31,30 @@ def test_style_intent_detector_matches_original_and_translated_queries():
  
     assert profile.is_active is True
     assert profile.get_canonical_values("color") == {"black"}
-    assert profile.get_canonical_values("size") == {"xl"}
+    assert profile.get_canonical_values("size") == {"x-large"}
     assert len(profile.query_variants) == 2
+
+
+def test_style_intent_detector_uses_original_query_when_language_translation_missing():
+    query_config = QueryConfig(
+        style_intent_terms={
+            "color": [{"en_terms": ["black"], "zh_terms": ["黑色"], "attribute_terms": ["black"]}],
+        },
+        style_intent_dimension_aliases={"color": ["color", "颜色"]},
+    )
+    detector = StyleIntentDetector(
+        StyleIntentRegistry.from_query_config(query_config),
+        tokenizer=lambda text: text.split(),
+    )
+
+    parsed_query = SimpleNamespace(
+        original_query="black dress",
+        query_normalized="black dress",
+        rewritten_query="black dress",
+        translations={"zh": "连衣裙"},
+    )
+
+    profile = detector.detect(parsed_query)
+
+    assert profile.get_canonical_values("color") == {"black"}
+    assert profile.intents[0].attribute_terms == ("black",)