# Reranker 模块

**请求示例**见 `docs/QUICKSTART.md` §3.5。扩展规范见 `docs/MODULE_EXTENSION_SPEC.md`。

---

Reranker 服务提供统一的 `/rerank` API，支持可插拔后端（BGE、Qwen3-vLLM）。调用方通过 HTTP 访问，不关心具体后端。

**特性**
- 多后端：`bge`（BAAI/bge-reranker-v2-m3）、`qwen3_vllm`（Qwen3-Reranker-0.6B + vLLM）
- 统一配置：`config/config.yaml` → `services.rerank.backend` / `services.rerank.backends.<name>`
- 文档去重、分数与输入顺序一致、FP16/GPU 支持（视后端）

## 目录与入口
- `reranker/server.py`：FastAPI 服务，启动时按配置加载一个后端
- `reranker/backends/`：后端实现与工厂
  - `backends/__init__.py`：`get_rerank_backend(name, config)`
  - `backends/bge.py`：BGE 后端
  - `backends/qwen3_vllm.py`：Qwen3-Reranker-0.6B + vLLM 后端
- `reranker/bge_reranker.py`：BGE 核心推理（被 bge 后端封装）
- `reranker/config.py`：服务端口、MAX_DOCS、NORMALIZE 等（后端参数在 config.yaml）

## 依赖
- 通用：`torch`、`modelscope`、`fastapi`、`uvicorn`（见项目 `requirements.txt` / `requirements_ml.txt`）
- **Qwen3-vLLM 后端**：`vllm>=0.8.5`、`transformers`（可选，仅当使用 `backend: qwen3_vllm` 时安装）
  ```bash
  pip install vllm>=0.8.5 transformers
  ```

## 配置
- **后端选择**：`config/config.yaml` 中 `services.rerank.backend`（`bge` | `qwen3_vllm`），或环境变量 `RERANK_BACKEND`。
- **后端参数**：`services.rerank.backends.bge` / `services.rerank.backends.qwen3_vllm`，例如：

```yaml
services:
  rerank:
    backend: "bge"   # 或 qwen3_vllm
    backends:
      bge:
        model_name: "BAAI/bge-reranker-v2-m3"
        device: null
        use_fp16: true
        batch_size: 64
        max_length: 512
        cache_dir: "./model_cache"
        enable_warmup: true
      qwen3_vllm:
        model_name: "Qwen/Qwen3-Reranker-0.6B"
        max_model_len: 8192
        tensor_parallel_size: 1
        gpu_memory_utilization: 0.8
        enable_prefix_caching: true
        instruction: "Given a web search query, retrieve relevant passages that answer the query"
```

- 服务端口、请求限制等仍在 `reranker/config.py`（或环境变量 `RERANKER_PORT`、`RERANKER_HOST`）。

## 运行
```bash
uvicorn reranker.server:app --host 0.0.0.0 --port 6007
```
使用 Qwen3-vLLM 时需先安装 vLLM 与 transformers，并将 `services.rerank.backend` 设为 `qwen3_vllm` 或设置 `RERANK_BACKEND=qwen3_vllm`。

## API
### Health
```
GET /health
```
Response 含 `backend`（当前后端名）、`model`、`model_loaded`、`status`。

### Rerank
```
POST /rerank
Content-Type: application/json

{
  "query": "wireless mouse",
  "docs": ["logitech mx master", "usb cable", "wireless mouse bluetooth"]
}
```

Response:
```
{
  "scores": [0.93, 0.02, 0.88],
  "meta": {
    "input_docs": 3,
    "usable_docs": 3,
    "unique_docs": 3,
    "dedup_ratio": 0.0,
    "elapsed_ms": 12.4,
    "model": "BAAI/bge-reranker-v2-m3",
    "device": "cuda",
    "fp16": true,
    "batch_size": 64,
    "max_length": 512,
    "normalize": true,
    "service_elapsed_ms": 13.1
  }
}
```

## Logging
The service uses standard Python logging. For structured logs and full output,
run uvicorn with:
```bash
uvicorn reranker.server:app --host 0.0.0.0 --port 6007 --log-level info
```

## Notes
- 无请求级缓存；输入按字符串去重后推理，再按原始顺序回填分数。
- 空或 null 的 doc 跳过并计为 0。
- **Qwen3-vLLM**：参考 [Qwen3-Reranker-0.6B](https://huggingface.co/Qwen/Qwen3-Reranker-0.6B)，需 GPU 与较多显存；与 BGE 相比适合长文本、高吞吐场景（vLLM 前缀缓存）。