# bge-reranker-server

**Repository Path**: lyDevelop/bge-reranker-server

## Basic Information

- **Project Name**: bge-reranker-server
- **Description**: BAAI/bge-reranker-v2-m3 模型的重排序服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BGE Reranker Server

基于 [BAAI/bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3) 模型的重排序服务，使用 FastAPI 提供 HTTP API。

支持 GPU（CUDA）自动检测，优先使用 GPU 加速推理，无 GPU 时自动回退到 CPU。

## 快速开始

### 一键部署

```bash
chmod +x install.sh
./install.sh
```

脚本会自动创建虚拟环境、安装依赖、下载模型并生成启动脚本。

### 手动部署

```bash
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 下载模型
python download.py

# 启动服务
./start.sh
```

## 使用方法

### 启动 / 停止

```bash
./start.sh   # 启动服务（默认端口 8001）
./stop.sh    # 停止服务
```

### API 接口

服务默认运行在 `http://localhost:8001`。

#### 健康检查

```bash
curl http://localhost:8001/
```

响应示例：

```json
{
  "status": "ok",
  "device": "cuda",
  "model": "BAAI/bge-reranker-v2-m3"
}
```

#### 重排序

```bash
curl -X POST http://localhost:8001/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "pairs": [
      {"query": "什么是机器学习？", "document": "机器学习是人工智能的一个分支"},
      {"query": "什么是机器学习？", "document": "今天天气不错"}
    ]
  }'
```

响应示例：

```json
{
  "scores": [0.95, 0.12]
}
```

`scores` 数组与输入 `pairs` 一一对应，分数越高表示 query 与 document 的相关性越强。

## 项目结构

```
.
├── app.py              # FastAPI 服务主程序
├── download.py         # 模型下载脚本
├── install.sh          # 一键部署脚本
├── start.sh            # 启动服务
├── stop.sh             # 停止服务
├── requirements.txt    # Python 依赖
├── models/             # 模型文件目录
│   └── bge-reranker-v2-m3/
└── venv/               # Python 虚拟环境
```

## 环境要求

- Python 3.10+
- CUDA（可选，有 GPU 时自动使用）
- 约 2GB 磁盘空间（模型文件）