# gitee-embedding-server

**Repository Path**: CMB_1/gitee-embedding-server

## Basic Information

- **Project Name**: gitee-embedding-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-20
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 目录结构

```
.
├── app.py                              # FastAPI 主应用，接口入口
├── embedding_handler.py                # 模型加载与向量生成逻辑
├── requirements.txt                    # 依赖包
├── em_models/                          # 本地模型存放目录
│   └── bge-small-zh-v1.5/              
│   └── nomic-embed-text-v2-moe/        
```

## 环境准备

1. **创建虚拟环境并激活**
   ```bash
   python3 -m venv myenv
   source myenv/bin/activate
   ```

2. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

## 启动服务

```bash
uvicorn app:app --host 127.0.0.1 --port 8000
```

## API 说明

### 1. 单文本向量化接口

**POST** `/embed`

**请求示例：**
```json
{
  // "model": "nomic-embed-text-v2-moe",      // 可选，默认nomic-embed-text-v2-moe
  "input": "你好，世界",              // 必填，单个字符串
}
```

**返回示例：**
```json
{
  "object": "list",
  "data": [
    {"object": "embedding", "embedding": [0.1, 0.2, ...], "index": 0}
  ],
  "model": "nomic-embed-text-v2-moe",
  "usage": {"prompt_tokens": null, "total_tokens": null}
}
```

### 2. 批量文本向量化接口

**POST** `/embed/batch`

**请求示例：**
```json
{
  "input": ["你好", "世界"],
  "model": "nomic-embed-text-v2-moe"   // 可选，默认nomic-embed-text-v2-moe
}
```

**返回示例：**
```json
[
  [0.1, 0.2, ...],   // 第一个文本的embedding
  [0.3, 0.4, ...]    // 第二个文本的embedding
]
```

### 3. 管理与健康检查

- **GET** `/models`  
  查看已加载模型

- **POST** `/models/unload`  
  卸载指定模型  (减少内存等资源占用)
  ```json
  { "model": "nomic-embed-text-v2-moe" }
  ```

- **GET** `/health`  
  健康检查

## 常见问题

- **如何添加新模型？**  
  只需将 Hugging Face 上的模型下载到 `em_models/模型目录/`，接口参数传对应目录名即可。

- **模型路径如何传递？**  
  `model`参数只需传目录名（如 `bge-small-zh-v1.5`），系统会自动拼接 `em_models/` 前缀。

- **支持哪些模型？**  
  只要是 Hugging Face sentence-transformers/transformers 兼容的 embedding 模型均可。

- **首次请求慢？**  
  可通过预加载机制提前加载常用模型，减少首次请求延迟。

## 参考 

- [FastAPI](https://fastapi.tiangolo.com/)
- [SentenceTransformers](https://www.sbert.net/)
- [Hugging Face Models](https://huggingface.co/models)

如有更多问题或定制需求，欢迎提 issue 或联系开发者！