# LLM-modules

**Repository Path**: duzc2/llm-modules

## Basic Information

- **Project Name**: LLM-modules
- **Description**: 提供一些大模型的模块的服务
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-15
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM-modules

基于 Transformers + FastAPI 的模块化嵌入模型服务，提供完全配置化的 OpenAI 兼容 API。

## 🌟 核心特性

- **完全配置化**: 所有设置通过配置文件管理，无任何自动决策
- **OpenAI 兼容**: 完全兼容 OpenAI 嵌入 API 格式
- **灵活部署**: 支持自定义模型、设备、量化等所有参数
- **性能优化**: 可配置的 4-bit 量化、混合精度、设备映射
- **智能缓存**: 可配置的内存缓存系统

## 🚀 快速开始

### 1. 安装依赖

```bash
# 自动安装依赖
python install_deps.py

# 或手动安装
pip install -r requirements.txt
```

### 2. 配置文件

采用双层配置系统：
- `config/app_config_template.json` - 模板配置（版本控制）
- `config/app_config_local.json` - 本地配置（个人定制，git忽略）

本地配置会覆盖模板配置中的相同项：

```json
{
  "model_settings": {
    "hf_endpoint": "https://hf-mirror.com",
    "hf_cache_dir": "./model_cache",        // 模型缓存目录 (HF_HOME)
    "embedding_model_name": "Qwen/Qwen3-Embedding-0.6B",
    "tokenizer_model_name": "Qwen/Qwen3-0.6B-Base",
    "use_4bit_quantization": false,
    "use_mixed_precision": true,
    "device_map": "auto",
    "compute_dtype": "float16"
  },
  "cache_settings": {
    "max_cache_size": 150000,
    "max_text_length": 300
  }
}
```

### 3. 启动服务

```bash
# Windows 推荐
start_server.bat

# 或直接运行
python start.py
```

### 4. 测试 API

```bash
# 健康检查
curl http://localhost:8000/health

# 获取嵌入向量
curl -X POST http://localhost:8000/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"input": "你好，世界"}'

# API 文档
# 访问 http://localhost:8000/docs
```

### 5. 运行测试

```bash
# 运行所有测试
python tests/run_tests.py

# 单独运行API测试
python tests/test_api.py

# 单独运行缓存测试
python tests/test_cache.py
```

## 📡 API 端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/` | GET | 服务器信息 |
| `/health` | GET | 健康检查 |
| `/v1/embeddings` | POST | 创建嵌入向量 |
| `/tokenizer/info` | GET | 分词器信息 |
| `/cache/stats` | GET | 缓存统计 |

## 💻 使用示例

### Python 客户端

```python
import requests

# 获取嵌入
response = requests.post(
    "http://localhost:8000/v1/embeddings",
    json={"input": "你好，世界"}
)
embedding = response.json()["data"][0]["embedding"]
print(f"嵌入维度: {len(embedding)}")
```

### OpenAI SDK 兼容

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000",
    api_key="not-needed"
)

response = client.embeddings.create(
    model="text-embedding-ada-002",
    input="你好，世界"
)
print(f"嵌入维度: {len(response.data[0].embedding)}")
```

## ⚙️ 配置说明

### 模型设置
- `embedding_model_name`: 嵌入模型名称
- `tokenizer_model_name`: 分词器模型名称
- `hf_endpoint`: 模型下载镜像
- `hf_cache_dir`: 模型缓存目录

### 性能优化
- `use_4bit_quantization`: 启用 4-bit 量化
- `use_mixed_precision`: 启用混合精度
- `device_map`: 设备映射 (auto/cuda/cpu/mps)
- `compute_dtype`: 计算类型 (float16/bfloat16)

### 缓存设置
- `max_cache_size`: 最大缓存条目数
- `max_text_length`: 最大文本长度

详细配置说明请查看 [CONFIGURATION.md](CONFIGURATION.md)

## 🛠️ 系统要求
- 8GB+ RAM
- NVIDIA GPU (推荐) 或 CPU

## 📁 项目结构

```
LLM-modules/
├── config/                 # 配置管理
│   ├── app_config.py      # 配置管理类
│   └── app_config.json    # 主配置文件
├── services/              # 核心服务
│   ├── embedding.py       # 嵌入服务
│   └── tokenizer.py       # 分词器服务
├── app/                   # API 路由
├── cache/                 # 缓存系统
├── tests/                 # 测试文件
├── main.py                # 主应用入口
├── start.py               # 启动器
└── start_server.bat       # Windows 启动脚本
```

## 📄 许可证

本项目遵循 Apache 2.0 许可证