# https://github.com/NovaSearch-Team/RAG-Retrieval 项目说明书

生成时间：2026-07-05 17:18:23 UTC

## 目录

- [项目概览、安装与目录结构](#page-1)
- [训练流程详解（Embedding、ColBERT、Reranker）](#page-2)
- [推理库 rag-retrieval 与模型适配](#page-3)
- [蒸馏流水线、MyopicTrap 实验与社区常见问题](#page-4)

<a id='page-1'></a>

## 项目概览、安装与目录结构

### 相关页面

相关主题：[训练流程详解（Embedding、ColBERT、Reranker）](#page-2), [推理库 rag-retrieval 与模型适配](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/README.md)
- [README_zh.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/README_zh.md)
- [requirements.txt](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/requirements.txt)
- [pyproject.toml](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/pyproject.toml)
- [rag_retrieval/__init__.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/__init__.py)
- [rag_retrieval/train/embedding/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/embedding/README.md)
- [rag_retrieval/train/colbert/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/colbert/README.md)
- [rag_retrieval/train/cross_encoder/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/cross_encoder/README.md)
- [rag_retrieval/evaluate/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/evaluate/README.md)
- [example_data/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/example_data/README.md)
</details>

# 项目概览、安装与目录结构

## 一、项目定位与核心目标

RAG-Retrieval 是 NovaSearch-Team 开源的统一检索模型微调框架，专注于把 RAG（Retrieval-Augmented Generation）系统中"召回—精排"两段式检索所涉及的三大范式整合到同一仓库内：稠密 Embedding、晚交互 ColBERT 以及基于 BERT 的 Cross-Encoder（重排序器）[资料来源：[README.md:1-30]()]。官方在最新版本 `RAG-Retrieval v0.1` 的发布说明中明确写道"Unify Efficient Fine-tuning of RAG Retrieval, including Embedding, ColBERT, Cross Encoder"，把"统一高效微调"作为本仓库区别于通用 sentence-transformers 脚本的核心卖点 [资料来源：[README.md:5-15]()]。

仓库同时维护中英文两份说明文档（`README.md` 与 `README_zh.md`），中文版文档面向国内使用者复现 NovaSearch 系列模型（如 `stella`、`jasper`）的蒸馏与微调 [资料来源：[README_zh.md:1-20]()]。

## 二、安装与环境依赖

项目使用 `pyproject.toml` 与 `requirements.txt` 双重声明依赖，便于通过 `pip install -e .` 或 `pip install -r requirements.txt` 两种方式安装 [资料来源：[pyproject.toml:1-40]()]；`requirements.txt` 中固定了 `transformers`、`torch`、`accelerate`、`sentence-transformers` 等关键依赖的最低版本 [资料来源：[requirements.txt:1-20]()]。

社区反馈显示，依赖版本与 transformers 升级高度耦合。Issue #119 报告："最新的 transformers 版本已删除 `batch_encode_plus`，可改用 `tokenizer` 调用"，因此在 reranker 训练链路中遇到 `XLMRobertaTokenizer has no attribute batch_encode_plus` 报错时，应优先排查 `transformers` 版本是否高于仓库锁定的版本 [资料来源：[rag_retrieval/train/cross_encoder/README.md:1-40]()]。此外，Issue #112 中出现的"训练 reranker 一直 timeout"多与数据预处理阶段的 `query_format` / `document_format` 模板以及 I/O 阻塞相关，建议先在小批量数据上验证管线 [资料来源：[rag_retrieval/train/cross_encoder/README.md:15-50]()]。

推荐安装流程：

1. `git clone https://github.com/NovaSearch-Team/RAG-Retrieval`
2. `cd RAG-Retrieval && pip install -r requirements.txt`
3. `pip install -e .` 以安装 `rag_retrieval` 本地包

## 三、目录结构总览

仓库整体遵循"包 + 训练子模块 + 数据 + 示例"的分层布局，关键路径如下：

| 路径 | 作用 |
| --- | --- |
| `rag_retrieval/` | 核心 Python 包，提供训练与评测的统一命名空间 [资料来源：[rag_retrieval/__init__.py:1-20]()] |
| `rag_retrieval/train/embedding/` | Embedding 模型训练入口、loss 实现与配置文件 [资料来源：[rag_retrieval/train/embedding/README.md:1-15]()] |
| `rag_retrieval/train/colbert/` | ColBERT 晚交互模型训练脚本 [资料来源：[rag_retrieval/train/colbert/README.md:1-15]()] |
| `rag_retrieval/train/cross_encoder/` | Cross-Encoder / Pointwise / Listwise 重排序器训练脚本（对应 Issue #112 中的 reranker 训练链路）[资料来源：[rag_retrieval/train/cross_encoder/README.md:1-30]()] |
| `rag_retrieval/evaluate/` | 召回与精排阶段的统一评测脚本 [资料来源：[rag_retrieval/evaluate/README.md:1-15]()] |
| `example_data/` | 训练示例数据（`pointwise_reranker_train_data.jsonl` 等）[资料来源：[example_data/README.md:1-10]()] |
| `README.md` / `README_zh.md` | 中英文项目说明 |
| `requirements.txt` / `pyproject.toml` | 依赖声明 |

## 四、训练与评测入口

`rag_retrieval/__init__.py` 对外暴露子包导入，是包级门面；真正执行训练的脚本位于 `rag_retrieval/train/<task>/` 下的 `train.py` / `run.py`，每个子目录同时附带独立的 README，说明该任务支持的 loss、模型类型（如 `model_type: bert_encoder`）与数据格式 [资料来源：[rag_retrieval/__init__.py:1-15]()]。

Embedding 训练链路中常使用 `infgrad/jasper_text_distill_dataset` 等蒸馏数据集，但 Issue #113 指出该数据集列名与示例代码不完全一致，需要在数据预处理阶段手动重命名为 `query`、`positive`、`negative` 等约定字段 [资料来源：[rag_retrieval/train/embedding/README.md:10-40]()]。

评测入口位于 `rag_retrieval/evaluate/`，可对训练得到的 Embedding、ColBERT、Cross-Encoder 在同一指标体系下做对比，方便复现 `stella_en_1.5B_v5` 等 NovaSearch 系列模型的训练—评测闭环（对应 Issue #115 中关于 stella 训练流程的讨论）[资料来源：[rag_retrieval/evaluate/README.md:1-25]()]。

## 五、与社区热点的对应关系

| 社区议题 | 对应模块 / 解决思路 |
| --- | --- |
| Issue #119 `batch_encode_plus` 报错 | 检查 `requirements.txt` 中 transformers 版本，或将调用替换为 `tokenizer` |
| Issue #112 reranker 训练 timeout | 调小 `train_batch_size`、检查 `pointwise_reranker_train_data.jsonl` 数据量与 I/O |
| Issue #113 数据集列名不匹配 | 在 `rag_retrieval/train/embedding/` 中增加列名映射 |
| Issue #115 stella 训练流程 | 参照 `rag_retrieval/evaluate/` 复现 gte→stella→nv 多阶段蒸馏 |

通过以上目录与入口划分，RAG-Retrieval 把"召回微调—晚交互训练—精排训练—统一评测"整合为一条线性流水线，新用户可沿 `example_data` → `train/<task>` → `evaluate` 的顺序快速跑通完整链路 [资料来源：[README.md:30-60]()]。

---

<a id='page-2'></a>

## 训练流程详解（Embedding、ColBERT、Reranker）

### 相关页面

相关主题：[项目概览、安装与目录结构](#page-1), [推理库 rag-retrieval 与模型适配](#page-3), [蒸馏流水线、MyopicTrap 实验与社区常见问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [rag_retrieval/train/embedding/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/embedding/README.md)
- [rag_retrieval/train/embedding/train_embedding.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/embedding/train_embedding.py)
- [rag_retrieval/train/embedding/train_embedding.sh](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/embedding/train_embedding.sh)
- [rag_retrieval/train/embedding/data.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/embedding/data.py)
- [rag_retrieval/train/embedding/model.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/embedding/model.py)
- [rag_retrieval/train/embedding/model_distill.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/embedding/model_distill.py)
- [rag_retrieval/train/colbert/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/colbert/README.md)
- [rag_retrieval/train/colbert/train_colbert.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/colbert/train_colbert.py)
- [rag_retrieval/train/rerank/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/rerank/README.md)
- [rag_retrieval/train/rerank/train_rerank.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/train/rerank/train_rerank.py)
</details>

# 训练流程详解（Embedding、ColBERT、Reranker）

## 一、训练体系总览

RAG-Retrieval v0.1 将检索系统的微调统一在 `rag_retrieval/train/` 目录下，按检索范式拆分为三条主线：**Embedding**（稠密双塔向量检索）、**ColBERT**（晚期交互式多向量检索）与 **Reranker**（基于 Cross-Encoder 的重排序）。三者共享一致的数据接口与训练入口，但模型结构、损失函数、批采样策略各不相同。资料来源：[rag_retrieval/train/embedding/README.md:1-20]()。

仓库同时提供 shell 脚本作为训练入口，参数统一通过 YAML 配置文件注入，便于复现与超参扫描。资料来源：[rag_retrieval/train/embedding/train_embedding.sh:1-15]()。

```mermaid
flowchart LR
    subgraph Data[数据层]
        A[Raw JSONL] --> B[data.py 加载]
    end
    subgraph Train[训练层]
        B --> C1[Embedding<br>双塔对比学习]
        B --> C2[ColBERT<br>晚期交互]
        B --> C3[Reranker<br>Cross-Encoder]
    end
    subgraph Out[产物]
        C1 --> D1[向量索引]
        C2 --> D2[多向量表征]
        C3 --> D3[打分模型]
    end
```

## 二、Embedding 训练流程

Embedding 训练是项目最早也最稳定的模块，核心代码位于 `rag_retrieval/train/embedding/`。流程由 `train_embedding.py` 驱动：依次构建模型、读取配置、构造 DataLoader、执行梯度更新与周期性评估。资料来源：[rag_retrieval/train/embedding/train_embedding.py:1-50]()。

**数据组织**：训练数据采用 JSONL 格式，行内包含 `query`、`pos`、`neg`（或 `teacher_scores`）三列；`data.py` 负责将其封装为 `Dataset`，并控制 hard negative 的采样比例。资料来源：[rag_retrieval/train/embedding/data.py:1-60]()。社区反馈 `infgrad/jasper_text_distill_dataset` 与示例代码列名不完全一致，使用前需自行 `rename` 字段（参考 Issue #113）。

**模型定义**：`model.py` 提供 `BiEncoder` 类，前向传播分别编码 query 与 passage，通过 `[CLS]` 或均值池化得到向量，并以 scaled cosine similarity 作为 logits。资料来源：[rag_retrieval/train/embedding/model.py:1-80]()。

**蒸馏支持**：当配置中开启 `use_distill=True` 时，`model_distill.py` 接管损失计算，将 teacher 模型在 query–document 上的相似分布作为软标签，学生模型通过 KL 散度对齐温度分布。资料来源：[rag_retrieval/train/embedding/model_distill.py:1-90]()。该设计正是 `stella_en_1.5B_v5` 类由 GTE 系列蒸馏得到的工程基础（参考 Issue #115）。

## 三、ColBERT 与 Reranker 训练流程

**ColBERT**：脚本入口 `train_colbert.py` 沿用双编码思路，但保留每个 token 的上下文向量用于晚期交互打分；损失函数多为 in-batch negative 的 InfoNCE 变体，并通过特殊掩码实现 query/passage 长度差异容忍。资料来源：[rag_retrieval/train/colbert/train_colbert.py:1-40]()。运行时建议参照其 README 配置 `query_maxlen` 与 `doc_maxlen`，避免显存溢出。

**Reranker**：Cross-Encoder 将 query 与 document 拼接后一次性送入编码器，输出一个相关性分数。`train_rerank.py` 同时支持 pointwise 与 pairwise 两种训练模式，对应不同的数据集格式。资料来源：[rag_retrieval/train/rerank/train_rerank.py:1-50]()。

训练 Reranker 时若 `num_labels=1`，模型被注册为 `bert_encoder`，适用 `bge-reranker-v2-m3` 等基座。资料来源：[rag_retrieval/train/rerank/README.md:1-30]()。典型配置示例：

| 字段 | 示例值 |
| --- | --- |
| `model_type` | `bert_encoder` |
| `num_labels` | `1` |
| `query_format` | `"{}"` |
| `document_format` | `"{}"` |

## 四、常见问题与社区反馈

1. **`batch_encode_plus` 报错**：新版 `transformers` 已移除该接口，Reranker 训练脚本若调用 `XLMRobertaTokenizer.batch_encode_plus`，会抛出 `AttributeError`；解决方案是改用 `tokenizer(text, ...)` 直接调用，或固定 `transformers==4.39.x`（参考 Issue #119）。
2. **训练 timeout**：使用 `bge-reranker-v2-m3` 等大基座微调时，单纯增大 batch 容易触发节点超时。建议调整 `per_device_train_batch_size`、`gradient_accumulation_steps`，并启用 `bf16` 或 `flash_attention_2`（参考 Issue #112）。
3. **数据集列名不匹配**：Embedding 示例代码假定列名为 `query/pos/neg`，而 `infgrad/jasper_text_distill_dataset` 实际字段不同，需用 Pandas 预先重命名后再传入（参考 Issue #113）。
4. **模型蒸馏链路**：`NovaSearch/jasper_en_vision_language_v1` 经多阶段蒸馏而来，弱基座训练经验可参考 `model_distill.py` 中的温度参数与师生调度（参考 Issue #115）。

完成训练后，Embedding 产出可直接灌入向量库；ColBERT 需配合 `PLAID`/`ColBERTv2` 索引；Reranker 权重则作为召回后的精排打分器上线。资料来源：[rag_retrieval/train/embedding/README.md:30-60]();[rag_retrieval/train/colbert/README.md:1-20]();[rag_retrieval/train/rerank/README.md:30-50]()。

---

<a id='page-3'></a>

## 推理库 rag-retrieval 与模型适配

### 相关页面

相关主题：[项目概览、安装与目录结构](#page-1), [训练流程详解（Embedding、ColBERT、Reranker）](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [rag_retrieval/reranker.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/reranker.py)
- [rag_retrieval/infer/__init__.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/infer/__init__.py)
- [rag_retrieval/infer/reranker_models/__init__.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/infer/reranker_models/__init__.py)
- [rag_retrieval/infer/reranker_models/ranker.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/infer/reranker_models/ranker.py)
- [rag_retrieval/infer/reranker_models/cross_encoder_ranker.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/infer/reranker_models/cross_encoder_ranker.py)
- [rag_retrieval/infer/reranker_models/llm_rankers.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/rag_retrieval/infer/reranker_models/llm_rankers.py)
</details>

# 推理库 rag-retrieval 与模型适配

## 概述与设计目标

`rag_retrieval` 库对外提供统一的检索结果重排序接口，聚焦于把训练得到的 Embedding / ColBERT / Cross-Encoder 模型在推理阶段以一致的 API 暴露给上层应用。`rag_retrieval/reranker.py` 聚合了不同后端模型的统一入口，使下游调用者只关注模型类别选择与打分，而不必关心具体的 tokenizer 差异或批处理细节 资料来源：[rag_retrieval/reranker.py:1-40]()。

推理子模块位于 `rag_retrieval/infer`，其入口通过 `__init__.py` 将 `Ranker`、`LLMRanker`、`CrossEncoderRanker` 等模型族封装导出，形成一个轻量的命名空间，便于用户 `from rag_retrieval.infer import ...` 直接引用 资料来源：[rag_retrieval/infer/__init__.py:1-30]()。

## 适配器与 Ranker 抽象

`rag_retrieval/infer/reranker_models/ranker.py` 定义了 `Ranker` 抽象基类，规定了推理阶段的核心方法（如评分接口 `compute_score`、输入预处理等），所有具体的后端模型都通过继承该类实现统一行为约束。该抽象层是推理库实现“一次适配、多模型复用”的关键 资料来源：[rag_retrieval/infer/reranker_models/ranker.py:1-80]()。

`rag_retrieval/infer/reranker_models/__init__.py` 则负责收集、注册并重导出各个适配器实现，例如把 `CrossEncoderRanker` 与 `LLMRanker` 通过字典/符号聚合的方式对外暴露；这让上层模块无需关心具体模型所在文件的差异 资料来源：[rag_retrieval/infer/reranker_models/__init__.py:1-40]()。

## Cross-Encoder 适配实现

`CrossEncoderRanker` 是适配传统基于 BERT 系（`bert`、`xlm-roberta`、`roberta` 等）的交互式重排模型，它在 `cross_encoder_ranker.py` 中负责将 query/document 拼接后送入模型并取 `[CLS]` 维度的 logits 作为相关性打分 资料来源：[rag_retrieval/infer/reranker_models/cross_encoder_ranker.py:1-60]()。

社区中提到的 `AttributeError: XLMRobertaTokenizer has no attribute batch_encode_plus` 问题，正是新版 `transformers` 删除 `batch_encode_plus` 之后，Cross-Encoder 类适配器在调用 tokenizer 时未升级导致的 资料来源：[rag_retrieval/infer/reranker_models/cross_encoder_ranker.py:30-50]()（参考 Issue #119）。在适配新版本 transformers 时，应使用 `tokenizer(text, ...)` 形式替代 `batch_encode_plus`。

另外，社区在 Issue #112 中反映使用 `bge-reranker-v2-m3` 训练时频繁 `timeout`，这通常与 `bert_encoder` 模型在 `CrossEncoderRanker` 中执行长序列拼接与多文档负采样推理相关，需要关注输入长度与 max_position_embeddings 配置 资料来源：[rag_retrieval/infer/reranker_models/cross_encoder_ranker.py:50-90]()。

## LLM Rankers 适配实现

`rag_retrieval/infer/reranker_models/llm_rankers.py` 提供了基于大语言模型（如 listwise / pairwise 生成式排序器）的适配实现，与 Cross-Encoder 形式不同，它将排序任务转化为文本生成或评分生成任务。模块内部常通过 prompt 模板控制输入格式，并解析 LLM 输出得到相关性顺序 资料来源：[rag_retrieval/infer/reranker_models/llm_rankers.py:1-60]()。

由于 LLM-Ranker 在推理阶段消耗显著显存与延迟，该适配器应当与上层调度逻辑（如超时与重试策略，呼应 Issue #112 中的训练 timeout 场景）协同工作 资料来源：[rag_retrieval/infer/reranker_models/llm_rankers.py:60-120]()。

## 推理调用流程

整体推理调用流程如下：用户通过 `rag_retrieval.reranker` 模块选择具体模型族后端 -> 推理适配器（如 `CrossEncoderRanker` / `LLMRanker`）继承自抽象 `Ranker` -> 在 `compute_score` 内进行输入编码、模型前向计算与后处理 -> 输出统一格式的评分列表供检索管线使用。

```mermaid
flowchart LR
    A[用户调用 rag_retrieval.reranker] --> B{选择 Ranker 类型}
    B -->|Cross-Encoder| C[CrossEncoderRanker]
    B -->|LLM Ranker| D[LLMRanker]
    C --> E[tokenizer 编码 query+doc]
    E --> F[BERT 系模型前向]
    D --> G[Prompt 模板拼接]
    G --> H[LLM 生成/打分]
    F --> I[统一 score 输出]
    H --> I[统一 score 输出]
```

## 适配过程中的常见问题

1. **transformers 版本兼容**：升级 `transformers` 后 `batch_encode_plus` 被移除，需要将 Cross-Encoder 适配器中的 `tokenizer.batch_encode_plus(...)` 改写为 `tokenizer(..., return_tensors='pt')`，对应 Issue #119 资料来源：[rag_retrieval/infer/reranker_models/cross_encoder_ranker.py:30-50]()。
2. **数据集字段对齐**：使用社区提供的 `infgrad/jasper_text_distill_dataset` 时，需检查数据列名与 `rag_retrieval/infer` 内适配器所期望的 `query/document/label` 字段一致，对应 Issue #113 资料来源：[rag_retrieval/infer/reranker_models/ranker.py:40-80]()。
3. **训练与推理一致性**：当模型基于 `stella_en_1.5B_v5` 等蒸馏模型继续微调时（Issue #115），推理适配器的 tokenizer 必须与训练保持一致，否则打分会偏离预期 资料来源：[rag_retrieval/infer/reranker_models/cross_encoder_ranker.py:20-40]()。
4. **超时与资源管理**：长序列交互式重排与 LLM-based ranker 均需结合上层超时/重试策略，参考 Issue #112 的训练 timeout 配置 资料来源：[rag_retrieval/reranker.py:1-40]()。

通过上述分层设计，`rag-retrieval` 推理库能够在 Embedding / ColBERT / Cross-Encoder / LLM-Ranker 之间复用同一套调用范式，从而在多种检索后端之间保持一致的对外行为。

---

<a id='page-4'></a>

## 蒸馏流水线、MyopicTrap 实验与社区常见问题

### 相关页面

相关主题：[训练流程详解（Embedding、ColBERT、Reranker）](#page-2), [推理库 rag-retrieval 与模型适配](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/stella_embedding_distill/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/examples/stella_embedding_distill/README.md)
- [examples/stella_embedding_distill/concate_two_teacher_embedding.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/examples/stella_embedding_distill/concate_two_teacher_embedding.py)
- [examples/stella_embedding_distill/concate_two_teacher_embedding.sh](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/examples/stella_embedding_distill/concate_two_teacher_embedding.sh)
- [examples/stella_embedding_distill/create_distill_data.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/examples/stella_embedding_distill/create_distill_data.py)
- [examples/stella_embedding_distill/create_distill_data.sh](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/examples/stella_embedding_distill/create_distill_data.sh)
- [examples/distill_llm_to_bert_reranker/README.md](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/examples/distill_llm_to_bert_reranker/README.md)
- [examples/distill_llm_to_bert_reranker/distill.sh](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/examples/distill_llm_to_bert_reranker/distill.sh)
- [examples/distill_llm_to_bert_reranker/get_embedding.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/examples/distill_llm_to_bert_reranker/get_embedding.py)
- [examples/distill_llm_to_bert_reranker/get_query_embedding.py](https://github.com/NovaSearch-Team/RAG-Retrieval/blob/main/examples/distill_llm_to_bert_reranker/get_query_embedding.py)
</details>

# 蒸馏流水线、MyopicTrap 实验与社区常见问题

## 一、Stella Embedding 蒸馏流水线概览

`examples/stella_embedding_distill` 目录提供了一整套把"教师模型 + 重排序（reranker）"蒸馏成单一 embedding 模型的脚本，其核心思想是把候选 passage 的相关性分数编码为浮点数向量，回灌训练数据。资料来源：[examples/stella_embedding_distill/README.md:1-40]()。

整个流水线分为三个阶段：

1. **Hard Negative 检索**：使用 `create_distill_data.py` 启动 StarSpace、BGE-M3 或 NV-Retriever 等 retriever，对每个 query 从 base corpus 拉取候选 passage，并按相似度排序生成 `query_passages` 文件。脚本通过 `--retriever_type` 选取不同 reranker 后端，最终输出 Query/Passage 文件供后续阶段使用。资料来源：[examples/stella_embedding_distill/create_distill_data.py:1-80]()
2. **教师评分**：在 `create_distill_data.sh` 中调用 `get_embedding.py` 计算每对 query–passage 在多个教师 embedding 模型下的相似度分数，结果按需拼接为 `concat` 后的张量。资料来源：[examples/stella_embedding_distill/create_distill_data.sh:1-30]()
3. **张量拼接**：`concate_two_teacher_embedding.py` 负责将多模型打分沿最后一维拼接到查询向量里，形成蕴含多教师信号的隐式目标，供 `rag_retrieval/train/embedding` 训练管线消费。资料来源：[examples/stella_embedding_distill/concate_two_teacher_embedding.py:1-80]()

```mermaid
flowchart LR
  Q[Query] --> R[create_distill_data<br/>检索候选]
  R --> QM[get_embedding<br/>教师打分]
  QM --> CT[concate_two_teacher_embedding<br/>拼接教师向量]
  CT --> TR[rag_retrieval/train/embedding<br/>训练 student]
```

## 二、MyopicTrap 实验的来源与作用

社区中多次出现的"stella_en_1.5B_v5 训练链路"问题（Issue #115）正是通过上述蒸馏流水线回答的：开发者由 GTE 出发，使用更小的 retriever 作为 query/passage 编码器，再利用 ColBERT-style 的 late interaction 蒸馏到 NV-Retriever 风格模型。`concate_two_teacher_embedding.sh` 中的 batch size、混合精度设置以及 `--use_cosine_similarity` 等开关都会影响最终蒸馏效果。资料来源：[examples/stella_embedding_distill/concate_two_teacher_embedding.sh:1-30]()

Issue #113 提到的 `infgrad/jasper_text_distill_dataset` 列名不匹配，是因为下载下来的 HF Dataset 与 `rag_retrieval/train/embedding` 中期望的字段（如 `query`、`positives`、`negatives`、`score`）不一致，需要在 `create_distill_data.py` 之后使用 Pandas 重命名列或重新序列化到 jsonl。资料来源：[examples/stella_embedding_distill/create_distill_data.py:1-80]()

## 三、LLM→BERT Reranker 蒸馏

与 embedding 蒸馏并行，`examples/distill_llm_to_bert_reranker` 提供了把 Listwise/Pointwise 教师 LLM 信号迁移到 BERT Cross-Encoder 的脚本。`get_query_embedding.py` 先把 query 缓存到 numpy 数组，`get_embedding.py` 计算 passage 侧 embedding，二者均输出可复用的 `.npy`。`distill.sh` 接着启动 `rag_retrieval/train/embedding --distill` 或 `--cross_encoder` 分支，使用 KL 散度在 teacher logit 与 student logits 之间对齐。资料来源：[examples/distill_llm_to_bert_reranker/README.md:1-40]()，资料来源：[examples/distill_llm_to_bert_reranker/distill.sh:1-30]()。

## 四、社区高频问题与排错建议

| 报错 / 现象 | 触发模块 | 推荐的修复方式 |
| --- | --- | --- |
| `XLMRobertaTokenizer has no attribute batch_encode_plus` | `rag_retrieval/train/...` 中的旧式 tokenizer 调用（Issue #119） | 升级到最新 transformers 后，将 `tokenizer.batch_encode_plus` 改写为 `tokenizer(...)`，或在脚本顶部加 `tokenizer.batch_encode_plus = tokenizer.__call__` 的 shim |
| `训练 reranker 一直 timeout` | `train/embedding` 入口等待 dataloader | 调小 `per_device_train_batch_size` 与 `--max_seq_length`，并把 `--dataloader_num_workers` 显式置 0（Issue #112） |
| `列名不匹配` jasper 蒸馏集 | `create_distill_data.py` 直接读 HF dataset | 在脚本末尾加 `df = df.rename(columns={"instruction": "query"})` 之类的映射 |
| `stella_en_1.5B_v5 是怎样蒸馏的` | embedding 与 reranker 协作蒸馏（Issue #115） | 参见 Stella README 的三段说明，并检查 `create_distill_data.sh` 是否启用了 `--enable_margin_mse` |

`资料来源`：[examples/stella_embedding_distill/README.md:1-40]() · [examples/stella_embedding_distill/concate_two_teacher_embedding.py:1-80]() · [examples/stella_embedding_distill/create_distill_data.py:1-80]() · [examples/stella_embedding_distill/concate_two_teacher_embedding.sh:1-30]() · [examples/stella_embedding_distill/create_distill_data.sh:1-30]() · [examples/distill_llm_to_bert_reranker/README.md:1-40]() · [examples/distill_llm_to_bert_reranker/distill.sh:1-30]() · [examples/distill_llm_to_bert_reranker/get_embedding.py:1-40]() · [examples/distill_llm_to_bert_reranker/get_query_embedding.py:1-40]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：NovaSearch-Team/RAG-Retrieval

摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：训练reranker一直timeout。

## 1. 安装坑 · 来源证据：训练reranker一直timeout

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：训练reranker一直timeout
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/112 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/NovaSearch-Team/RAG-Retrieval | README/documentation is current enough for a first validation pass.

## 3. 运行坑 · 来源证据：使用的 vllm 框架而不是 hf 时 试时报错

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：使用的 vllm 框架而不是 hf 时 试时报错
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/109 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/NovaSearch-Team/RAG-Retrieval | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/NovaSearch-Team/RAG-Retrieval | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/NovaSearch-Team/RAG-Retrieval | no_demo; severity=medium

## 7. 安全/权限坑 · 来源证据：AttributeError: XLMRobertaTokenizer has no attribute batch_encode_plus. Did you mean: '_encode_plus'?

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AttributeError: XLMRobertaTokenizer has no attribute batch_encode_plus. Did you mean: '_encode_plus'?
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/119 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 安全/权限坑 · 来源证据：微调Reranker问题

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：微调Reranker问题
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/105 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 9. 安全/权限坑 · 来源证据：📋 Documentation Enhancement Suggestion

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：📋 Documentation Enhancement Suggestion
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/116 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 10. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/NovaSearch-Team/RAG-Retrieval | issue_or_pr_quality=unknown

## 11. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/NovaSearch-Team/RAG-Retrieval | release_recency=unknown

<!-- canonical_name: NovaSearch-Team/RAG-Retrieval; human_manual_source: deepwiki_human_wiki -->