Upload LycheeMem reranker v1 (Qwen3-Reranker-0.6B + LoRA rank=16, V4 Pro 5-level distillation)

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,3 +1,203 @@
 ---
 license: apache-2.0
+base_model: Qwen/Qwen3-Reranker-0.6B
+library_name: peft
+tags:
+  - reranker
+  - memory-retrieval
+  - long-term-memory
+  - dialog
+  - lora
+  - distillation
+  - lycheemem
+language:
+  - en
+pipeline_tag: text-classification
 ---
+
+# LycheeMem Reranker v1
+
+A LoRA adapter on top of **Qwen3-Reranker-0.6B**, fine-tuned for **long-term memory dialog retrieval** in conversational AI memory systems. Trained with V4 Pro 5-level distillation labels on consumer hardware (RTX 4060 Ti 8 GB).
+
+Built as a drop-in reranker for [LycheeMem](https://github.com/LycheeMem/lycheemem) and similar systems where the candidate set is past conversation snippets (not generic passages).
+
+## Highlights
+
+- **18 MB LoRA adapter** on top of 0.6 B base — runs on a single RTX 4060 Ti 8 GB, zero API cost at inference
+- **MAP 0.919** on LongMemEval-S held-out (373 queries unseen during training); **+5.4 pp over BGE-Reranker-v2-m3** (560 M industrial baseline) on the same data
+- **MAP 0.706** on HotpotQA distractor (7,405 queries) — completely out-of-distribution, never seen during training
+- **No GPT/Claude/Gemini API used** during training (V4 Pro distillation uses DeepSeek, which permits derivative models)
+- **2 h 5 min training**, ¥12.47 one-time labeling cost — fully reproducible on consumer hardware
+
+## Evaluation
+
+All evaluations use queries strictly held out from training. The "in-domain" benchmarks remove the queries that overlapped with our training set (held-out subsets). The "out-of-domain" benchmark is the standard HotpotQA distractor validation set, never seen during training.
+
+### Headline numbers (MAP, higher is better)
+
+| Model | Params | LongMemEval-S<br/>(373 q held-out) | MSC-MemFuse-MC10<br/>(27 q held-out) | HotpotQA distractor<br/>(7,405 q, OOD) |
+|---|---|---|---|---|
+| **LycheeMem reranker v1 (this)** | 0.6B + LoRA | **0.9185** | **0.7457** | **0.7063** |
+| BGE-Reranker-v2-m3 | 560M | 0.8647 | 0.5503 | 0.8002 |
+| Δ vs BGE | | **+5.4 pp** | **+19.5 pp** | **−9.4 pp** |
+
+### Full metric breakdown
+
+| Benchmark | hit@10 | Recall@5 | Recall@10 | **MAP** | NDCG@10 |
+|---|---|---|---|---|---|
+| LongMemEval-S held-out | 1.000 | 0.964 | 0.988 | **0.919** | 0.940 |
+| MSC-MemFuse-MC10 held-out | 1.000 | 0.799 | 0.896 | **0.746** | 0.786 |
+| HotpotQA distractor (OOD) | 0.987 | 0.793 | 0.890 | **0.706** | 0.769 |
+
+### Domain trade-off (honest)
+
+This model is **specialized for memory dialog retrieval**, not a drop-in general-purpose reranker:
+
+- **In-domain (memory dialog)**: outperforms BGE-Reranker-v2-m3 by +5.4 to +19.5 pp MAP. Use this model.
+- **Out-of-domain (Wikipedia QA)**: trails BGE-Reranker-v2-m3 by 9.4 pp MAP. Use BGE for general retrieval.
+- The trade-off is intentional — distillation labels were biased toward memory dialog semantics.
+
+## Training pipeline
+
+```text
+Base:         Qwen/Qwen3-Reranker-0.6B
+Adapter:      LoRA r=16, alpha=32, dropout=0.05
+              target_modules = q_proj, k_proj, v_proj, o_proj
+
+Stage 1: Pair construction (18,947 pairs, two sources)
+  - LongMemEval-S-cleaned-overlap: 127 queries × ~47 candidates
+  - MSC-MemFuse-MC10-answer-turn: 299 queries × 50 candidates
+  - Initial labels:
+      candidate.id ∈ evidence_ids       → 1.0   (hard positive)
+      candidate.id ∈ baseline-top-10    → 0.4   (mid-tier, refined in Stage 2)
+      else                              → 0.0
+
+Stage 2: V4 Pro 5-level label distillation (4,223 calls, ¥12.47)
+  - DeepSeek V4 Pro re-scored all mid-tier candidates + 5% calibration sample
+  - Replaced binary mid-tier labels with continuous 0.0/0.2/0.4/0.6/0.8 scores
+  - 658 mid-tier candidates received nuanced (non-extreme) labels
+  - "thinking" mode disabled for speed; agree-with-baseline rate 97%
+
+Stage 3: BCE training with float labels (2 h 5 min on RTX 4060 Ti 8 GB)
+  - 3 epochs, effective batch size 16, lr=2e-4, cosine schedule
+  - bf16 + gradient checkpointing, VRAM peak 1.7 GB
+  - BCEWithLogitsLoss against continuous targets
+
+Trainable parameters: 4.59M / 600.37M = 0.76%
+```
+
+## Intended use
+
+**Primary**: rerank candidate memory snippets in a long-term memory system. Inputs are (user query, candidate past-conversation snippet); output is a relevance score. Use the top-K scored candidates as context for downstream LLM answering.
+
+**Input format** (Qwen3-Reranker convention):
+
+```text
+<Instruct>: Given a user query, retrieve memory snippets that answer the query
+<Query>: {user_query}
+<Document>: {candidate_memory_snippet}
+```
+
+## How to use
+
+```python
+import torch
+from peft import PeftModel
+from transformers import AutoTokenizer, AutoModelForSequenceClassification
+
+BASE = "Qwen/Qwen3-Reranker-0.6B"
+ADAPTER = "fuhao23/reranker_v1"  # this repo
+
+# 1. Load base + LoRA adapter
+tok = AutoTokenizer.from_pretrained(BASE, trust_remote_code=True)
+if tok.pad_token is None:
+    tok.pad_token = tok.eos_token
+
+base = AutoModelForSequenceClassification.from_pretrained(
+    BASE,
+    num_labels=1,
+    torch_dtype=torch.bfloat16,
+    trust_remote_code=True,
+)
+base.config.pad_token_id = tok.pad_token_id
+model = PeftModel.from_pretrained(base, ADAPTER).eval().to("cuda")
+
+# 2. Score (query, candidate) pairs
+INSTRUCT = "Given a user query, retrieve memory snippets that answer the query"
+
+def score(query: str, candidates: list[str], max_len: int = 512) -> list[float]:
+    texts = [
+        f"<Instruct>: {INSTRUCT}\n<Query>: {query}\n<Document>: {c}"
+        for c in candidates
+    ]
+    enc = tok(texts, padding=True, truncation=True, max_length=max_len,
+              return_tensors="pt").to(model.device)
+    with torch.inference_mode():
+        logits = model(**enc).logits.squeeze(-1).float().cpu().tolist()
+    return logits
+
+# 3. Rerank top-K
+query = "What cuisines have I tried recently?"
+candidates = [
+    "user: I cooked Thai tom yum soup last weekend.",
+    "user: The Tokyo restaurants we discussed earlier.",
+    "user: My tax filing reminder for next quarter.",
+]
+scores = score(query, candidates)
+ranked = sorted(zip(scores, candidates), reverse=True)
+for s, c in ranked:
+    print(f"{s:+7.3f}  {c}")
+# Higher logit = more relevant. Pass through sigmoid if you need [0, 1] probabilities.
+```
+
+## Limitations
+
+Read carefully before deployment:
+
+1. **Specialized for dialog memory, not general retrieval.** On Wikipedia QA (HotpotQA, an OOD test), this model trails BGE-Reranker-v2-m3 by 9.4 pp MAP. For general-purpose retrieval, use BGE.
+
+2. **English-only training distribution.** All training data is English personal-dialog (LongMemEval-S + MSC-MemFuse-MC10). Chinese, technical, code, and other languages are not evaluated.
+
+3. **MSC held-out sample is small (27 queries).** The MSC-MemFuse-MC10 benchmark number has wide confidence intervals due to sample size; use LongMemEval-S as the primary in-domain reference.
+
+4. **Distillation teacher is DeepSeek V4 Pro.** Comparisons against models stronger than V4 Pro may have ceiling effects from the labeling source.
+
+5. **No end-to-end downstream evaluation reported.** This model card reports retrieval-stage MAP / NDCG / Recall. End-to-end LLM answer accuracy with this reranker integrated into a memory system is not yet measured.
+
+6. **No real user feedback data used.** Training is fully offline distillation; no preference / DPO signals from real deployments.
+
+## Methodology details
+
+Full pipeline, ablation studies (including a negative result on InfoNCE second-stage training and an iterative hard-negative mining dead-end), and reproducibility scripts are in the [LycheeMem repository](https://github.com/LycheeMem/lycheemem):
+
+- `examples/build_reranker_v1_train_data.py` — pair construction
+- `examples/label_reranker_v1_v4pro.py` — V4 Pro 5-level distillation
+- `examples/reranker_v1_merge_v4pro.py` — label merge
+- `examples/reranker_v1_train.py` — BCE training with `--label-mode float`
+- `examples/reranker_v1_eval.py` — unified evaluation
+
+## Citation
+
+```bibtex
+@misc{lycheemem_reranker_v1,
+  title  = {LycheeMem Reranker v1: A Domain-Specialized Reranker for Long-Term Memory Dialog Retrieval},
+  author = {LycheeMem Project},
+  year   = {2026},
+  url    = {https://huggingface.co/fuhao23/reranker_v1}
+}
+```
+
+Base model:
+
+```bibtex
+@misc{qwen3_embedding,
+  title  = {Qwen3 Embedding Series},
+  author = {Qwen Team},
+  year   = {2025},
+  url    = {https://huggingface.co/Qwen/Qwen3-Reranker-0.6B}
+}
+```
+
+## License
+
+Apache 2.0 (matches the base Qwen3-Reranker-0.6B license).

adapter_config.json

@@ -0,0 +1,48 @@
+{
+  "alora_invocation_tokens": null,
+  "alpha_pattern": {},
+  "arrow_config": null,
+  "auto_mapping": null,
+  "base_model_name_or_path": "Qwen/Qwen3-Reranker-0.6B",
+  "bias": "none",
+  "corda_config": null,
+  "ensure_weight_tying": false,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 32,
+  "lora_bias": false,
+  "lora_dropout": 0.05,
+  "lora_ga_config": null,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": [
+    "classifier",
+    "score"
+  ],
+  "peft_type": "LORA",
+  "peft_version": "0.19.1",
+  "qalora_group_size": 16,
+  "r": 16,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": [
+    "k_proj",
+    "q_proj",
+    "v_proj",
+    "o_proj"
+  ],
+  "target_parameters": null,
+  "task_type": "SEQ_CLS",
+  "trainable_token_indices": null,
+  "use_bdlora": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false
+}

adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:451395873de451f04f0e1ce2512ffbf9f165867d442d74557b9f6f0a572e861c
+size 18382152

added_tokens.json

@@ -0,0 +1,28 @@
+{
+  "</think>": 151668,
+  "</tool_call>": 151658,
+  "</tool_response>": 151666,
+  "<think>": 151667,
+  "<tool_call>": 151657,
+  "<tool_response>": 151665,
+  "<|box_end|>": 151649,
+  "<|box_start|>": 151648,
+  "<|endoftext|>": 151643,
+  "<|file_sep|>": 151664,
+  "<|fim_middle|>": 151660,
+  "<|fim_pad|>": 151662,
+  "<|fim_prefix|>": 151659,
+  "<|fim_suffix|>": 151661,
+  "<|im_end|>": 151645,
+  "<|im_start|>": 151644,
+  "<|image_pad|>": 151655,
+  "<|object_ref_end|>": 151647,
+  "<|object_ref_start|>": 151646,
+  "<|quad_end|>": 151651,
+  "<|quad_start|>": 151650,
+  "<|repo_name|>": 151663,
+  "<|video_pad|>": 151656,
+  "<|vision_end|>": 151653,
+  "<|vision_pad|>": 151654,
+  "<|vision_start|>": 151652
+}

chat_template.jinja

@@ -0,0 +1,15 @@
+{%- set instruction = messages | selectattr("role", "eq", "system") | map(attribute="content") | first | default("Given a web search query, retrieve relevant passages that answer the query") -%}
+{%- set query_text = messages | selectattr("role", "eq", "query") | map(attribute="content") | first -%}
+{%- set document_text = messages | selectattr("role", "eq", "document") | map(attribute="content") | first -%}
+<|im_start|>system
+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|>
+<|im_start|>user
+<Instruct>: {{ instruction }}
+<Query>: {{ query_text }}
+<Document>: {{ document_text }}<|im_end|>
+<|im_start|>assistant
+<think>
+
+</think>
+
+

special_tokens_map.json

@@ -0,0 +1,31 @@
+{
+  "additional_special_tokens": [
+    "<|im_start|>",
+    "<|im_end|>",
+    "<|object_ref_start|>",
+    "<|object_ref_end|>",
+    "<|box_start|>",
+    "<|box_end|>",
+    "<|quad_start|>",
+    "<|quad_end|>",
+    "<|vision_start|>",
+    "<|vision_end|>",
+    "<|vision_pad|>",
+    "<|image_pad|>",
+    "<|video_pad|>"
+  ],
+  "eos_token": {
+    "content": "<|im_end|>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "pad_token": {
+    "content": "<|endoftext|>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  }
+}

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1574cf58b63a2a56db9bc28f6ddcac4ece87690840939153189077692486f4ee
+size 11422920

tokenizer_config.json

@@ -0,0 +1,239 @@
+{
+  "add_bos_token": false,
+  "add_prefix_space": false,
+  "added_tokens_decoder": {
+    "151643": {
+      "content": "<|endoftext|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151644": {
+      "content": "<|im_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151645": {
+      "content": "<|im_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151646": {
+      "content": "<|object_ref_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151647": {
+      "content": "<|object_ref_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151648": {
+      "content": "<|box_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151649": {
+      "content": "<|box_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151650": {
+      "content": "<|quad_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151651": {
+      "content": "<|quad_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151652": {
+      "content": "<|vision_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151653": {
+      "content": "<|vision_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151654": {
+      "content": "<|vision_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151655": {
+      "content": "<|image_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151656": {
+      "content": "<|video_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151657": {
+      "content": "<tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151658": {
+      "content": "</tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151659": {
+      "content": "<|fim_prefix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151660": {
+      "content": "<|fim_middle|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151661": {
+      "content": "<|fim_suffix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151662": {
+      "content": "<|fim_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151663": {
+      "content": "<|repo_name|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151664": {
+      "content": "<|file_sep|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151665": {
+      "content": "<tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151666": {
+      "content": "</tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151667": {
+      "content": "<think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151668": {
+      "content": "</think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    }
+  },
+  "additional_special_tokens": [
+    "<|im_start|>",
+    "<|im_end|>",
+    "<|object_ref_start|>",
+    "<|object_ref_end|>",
+    "<|box_start|>",
+    "<|box_end|>",
+    "<|quad_start|>",
+    "<|quad_end|>",
+    "<|vision_start|>",
+    "<|vision_end|>",
+    "<|vision_pad|>",
+    "<|image_pad|>",
+    "<|video_pad|>"
+  ],
+  "bos_token": null,
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "extra_special_tokens": {},
+  "model_max_length": 131072,
+  "pad_token": "<|endoftext|>",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null
+}