# bge-server

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

## Basic Information

- **Project Name**: bge-server
- **Description**: BGE-M3 Embedding + BGE-Reranker-v2-m3 统一服务，基于 FastAPI 构建
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BGE Model Server

BGE-M3 Embedding + BGE-Reranker-v2-m3 统一服务，基于 FastAPI 构建，单进程运行两个模型。

## 功能特性

- **BGE-M3** — 文本嵌入，支持批量文本，向量自动归一化
- **BGE-Reranker-v2-m3** — 重排序，query-document 对打分
- 自动检测 GPU/CPU，优先使用 CUDA 加速
- 单一 FastAPI 进程，统一管理两个模型
- 提供健康检查接口

## 快速开始

### 一键部署（推荐）

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

### 手动部署

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

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

# 下载模型（首次需要，约 2-3GB）
python download.py

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

## 启动 / 停止

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

## API 接口

服务运行在 `http://localhost:8000`。

### 服务状态

```bash
curl http://localhost:8000/
```

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

### 健康检查

```bash
curl http://localhost:8000/health
```

```json
{
  "status": "ok",
  "embedding_loaded": true,
  "reranker_loaded": true
}
```

### 文本嵌入

```bash
curl -X POST http://localhost:8000/embedding \
  -H "Content-Type: application/json" \
  -d '{"texts": ["Hello world", "测试文本"]}'
```

```json
{
  "embedding_dim": 1024,
  "embeddings": [[0.1, 0.2, ...], [0.3, 0.4, ...]]
}
```

### 重排序

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

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

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

## 项目结构

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

## 环境要求

- Python 3.10+
- CUDA（可选，有 GPU 时自动使用）
- 约 3-4GB 磁盘空间（两个模型）

## 许可证

MIT License