# ai_project

**Repository Path**: twsa/ai_project

## Basic Information

- **Project Name**: ai_project
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: fastchat
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-31
- **Last Updated**: 2025-11-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI模型API服务

基于Qwen2.5-1.5B-Instruct和BAAI/bge-m3的本地AI API服务，提供兼容OpenAI格式的文本生成和向量化功能。

## 🚀 功能特性

### 核心功能
- **文本生成**: 基于Qwen2.5-1.5B-Instruct模型的高质量文本生成
- **文本向量化**: 基于BAAI/bge-m3模型的多语言语义向量化
- **OpenAI兼容**: 完全兼容OpenAI API格式，可直接使用OpenAI客户端库
- **FastChat集成**: 支持FastChat分布式架构，可水平扩展
- **统一API网关**: 单一入口提供所有API服务

### 高级特性
- **VRAM管理**: 智能显存监控和自动清理，防止内存溢出
- **流式响应**: 支持实时流式文本生成
- **批量处理**: 高效的批量文本向量化
- **性能监控**: 详细的性能指标和日志记录
- **实时监控**: 彩色界面的实时系统监控面板
- **错误诊断**: 增强的错误日志和请求失败分析
- **配置管理**: 灵活的配置系统，支持运行时调整
- **补丁管理**: 自动FastChat兼容性补丁应用和验证
- **模型切换**: 动态模型加载和零停机切换
- **增强工作器**: 改进的错误处理和批处理优化

## 📋 系统要求

- Python 3.8+
- CUDA 11.0+ (GPU加速)
- 8GB+ VRAM (推荐16GB)
- 50GB+ 磁盘空间

## 🛠️ 安装部署

### 1. 克隆项目
```bash
git clone <repository-url>
cd ai_project
```

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

### 3. 配置模型
确保模型文件位于：
- `/home/cjliu/.cache/modelscope/hub/models/Qwen/Qwen2.5-1.5B-Instruct`
- `/home/cjliu/.cache/modelscope/hub/models/BAAI/bge-m3`

### 4. 启动服务
```bash
# 启动所有服务
./start.sh

# 启动单个服务
./start.sh unified      # 仅启动统一API网关
./start.sh api          # 仅启动FastChat API
./start.sh embedding    # 仅启动嵌入服务
./start.sh controller   # 仅启动控制器
./start.sh worker       # 仅启动模型工作器
./start.sh vram         # 仅启动VRAM监控

# 服务管理
./start.sh stop         # 停止所有服务
./start.sh restart      # 重启所有服务
./start.sh status       # 查看服务状态
./start.sh logs         # 查看日志

# 监控工具
./start.sh monitor      # 启动实时监控面板
./start.sh gpu-monitor  # 启动GPU监控

# 或手动启动
python3 src/unified_api_server.py --host 0.0.0.0 --port 8090
```

## 📖 API文档

### 服务地址
- 统一API网关: `http://localhost:8090` (推荐)
- 健康检查: `http://localhost:8090/health`
- API文档: `http://localhost:8090/docs`
- VRAM监控: `http://localhost:8001/vram`
- FastChat API: `http://localhost:8000/v1`

### 文本生成API
```bash
curl -X POST http://localhost:8090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-chat",
    "messages": [{"role": "user", "content": "你好"}],
    "temperature": 0.7,
    "max_tokens": 1000
  }'
```

### 文本向量化API
```bash
curl -X POST http://localhost:8090/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-embed",
    "input": "这是一个测试文本"
  }'
```

### 模型列表API
```bash
curl http://localhost:8090/v1/models
```

## 🧪 测试验证

### 运行完整测试套件
```bash
# 基础功能测试
python3 tests/test_complete.py

# Embedding功能测试
python3 tests/test_embedding.py

# FastChat功能测试
python3 tests/test_fastchat.py
```

### OpenAI兼容性测试
```python
import openai

client = openai.OpenAI(
    api_key="dummy-key",
    base_url="http://localhost:8090/v1"
)

# 文本生成
response = client.chat.completions.create(
    model="local-chat",
    messages=[{"role": "user", "content": "你好"}]
)

# 文本向量化
embedding = client.embeddings.create(
    model="local-embed",
    input="测试文本"
)
```

## ⚙️ 配置说明

### 基础配置 (src/fastchat_config.py)
```python
# 模型配置
MODEL_NAME = "local-chat"
MODEL_PATH = "/path/to/model"
DEVICE = "cuda"

# API配置
HOST = "0.0.0.0"
PORT = 8000

# VRAM管理配置
ENABLE_VRAM_MONITORING = True
VRAM_CLEANUP_THRESHOLD = 0.7
VRAM_CRITICAL_THRESHOLD = 0.9
```

### VRAM管理配置
- `ENABLE_VRAM_MONITORING`: 启用VRAM监控
- `VRAM_CLEANUP_THRESHOLD`: VRAM清理阈值 (70%)
- `VRAM_CRITICAL_THRESHOLD`: VRAM危险阈值 (90%)
- `VRAM_MONITORING_INTERVAL`: 监控间隔 (5秒)

## 📊 性能指标

### 文本生成性能
- 响应时间: <500ms (首次) / <100ms (后续)
- 吞吐量: ~20 tokens/second
- VRAM使用: ~4GB (FP16精度)

### 向量化性能
- 处理速度: >200 文本/秒
- 向量维度: 1024维
- 批量处理: 支持50+文本批量处理

## 🛠️ 开发指南

### 项目结构
```
ai_project/
├── src/                     # 源代码目录
│   ├── fastchat_config.py   # 统一配置管理
│   ├── unified_api_server.py # 统一API网关
│   ├── enhanced_gpu_monitor.py # 增强GPU监控工具
│   ├── vram_manager.py     # VRAM管理
│   ├── embedding_worker.py  # 向量化工作进程
│   ├── patch_manager.py     # FastChat补丁管理
│   ├── model_switcher.py    # 动态模型切换
│   ├── enhanced_model_worker.py # 增强模型工作器
│   └── vram_monitor_service.py # VRAM监控服务
├── tests/                   # 测试代码
├── docs/                    # 文档目录
│   ├── VRAM_MANAGEMENT_GUIDE.md
│   ├── API_USAGE_GUIDE.md
│   ├── log_management.md
│   └── switch_embedding_model.md
├── tools/                   # 开发工具
│   ├── cleanup.sh           # 清理脚本
│   ├── monitor.sh           # 实时监控脚本
│   ├── logctl               # 日志监控工具
│   └── switch_model.sh      # 模型切换脚本
├── logs/                    # 日志目录
├── start.sh                # 启动脚本
└── requirements.txt        # 依赖列表
```

### 添加新功能
1. 在`src/`目录下添加模块
2. 更新`fastchat_config.py`添加配置项
3. 在`tests/`目录添加测试
4. 更新API文档

### 开发工具使用

```bash
# 清理临时文件和Python缓存
./tools/cleanup.sh

# 实时监控面板（彩色界面）
./tools/monitor.sh               # 启动实时监控面板
./tools/monitor.sh -i 60         # 60秒监控间隔
./tools/monitor.sh -o            # 显示一次状态

# 增强GPU监控
python3 src/enhanced_gpu_monitor.py

# 实时监控日志
./tools/logctl tail api          # API服务日志
./tools/logctl tail vram         # VRAM监控日志
./tools/logctl tail embedding    # Embedding服务日志

# 模型切换（需要提前配置）
./tools/switch_model.sh [model_name]

# 验证FastChat补丁
python3 -c "
import sys
sys.path.insert(0, 'src')
import patch_manager
patch_manager.check_patches_needed()
"
```

### 额外测试

```bash
# 流式响应测试
python3 test_stream_after_patch.py

# 补丁验证测试
python3 test_patch_verification.py

# 简单监控测试
python3 test_simple_monitor.py

# 监控功能测试
python3 -c "
import sys
sys.path.insert(0, 'src')
from enhanced_gpu_monitor import EnhancedGPUMonitor
monitor = EnhancedGPUMonitor()
status = monitor.log_status()
print('监控测试完成')
"
```

## 🔧 故障排除

### 常见问题

**1. VRAM不足**
```bash
# 检查VRAM使用情况
python src/vram_monitor_service.py --status

# 手动清理VRAM
curl -X POST http://localhost:8001/vram/cleanup
```

**2. 模型加载失败**
- 检查模型路径是否正确
- 确认CUDA版本兼容性
- 查看日志文件 `logs/`

**3. API连接失败**
- 检查端口是否被占用
- 确认防火墙设置
- 验证服务状态

### 日志管理和监控
```bash
# 查看实时日志
tail -f logs/api_unified_$(date +%Y%m%d).log    # 统一API日志
tail -f logs/api_console.log                    # FastChat API日志
tail -f logs/vram_monitor.log                   # VRAM监控日志
tail -f logs/enhanced_gpu_monitor.log           # 增强GPU监控日志

# 使用实时监控面板
./tools/monitor.sh              # 彩色监控面板，显示系统状态、API状态、错误统计

# 服务状态和日志
./start.sh status               # 查看所有服务状态
./start.sh logs                 # 查看日志概览和错误统计

# 调整日志级别
# 修改 fastchat_config.py 中的 LOG_LEVEL

# 使用工具监控日志
./tools/logctl tail api         # API服务实时日志
./tools/logctl tail vram        # VRAM监控实时日志
./tools/logctl tail embedding   # Embedding服务实时日志

# 错误诊断
grep "聊天请求失败" logs/api_unified_$(date +%Y%m%d).log  # 查看聊天请求失败详情
grep "请求处理时间" logs/api_unified_$(date +%Y%m%d).log   # 查看慢请求
```

## 🤝 贡献指南

1. Fork项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

## 📄 许可证

本项目基于MIT许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 支持

如有问题或建议，请：
- 创建Issue
- 查看文档 `docs/` 目录
- 检查FAQ和故障排除部分

---

**最后更新**: 2025年11月3日
**版本**: 1.2.0

## 🆕 v1.2.0 更新内容

### 新增功能
- **实时监控面板**: 彩色界面的系统监控工具 (`tools/monitor.sh`)
- **增强GPU监控**: 详细的GPU状态和性能问题检测 (`src/enhanced_gpu_monitor.py`)
- **错误诊断增强**: 详细的聊天请求失败分析和网络错误处理
- **请求处理时间监控**: 慢请求检测和性能告警

### 改进功能
- **启动脚本增强**: 支持单服务启动、停止、状态查看等功能
- **编码兼容性修复**: 解决Python UTF-8编码和版本兼容性问题
- **模块导入优化**: 修复路径问题确保稳定运行

### 监控和日志
- 实时系统状态监控（GPU、内存、API服务）
- 错误统计和慢请求追踪
- 详细的性能指标记录
- 服务健康状态检查

## 📚 详细文档

- [VRAM管理指南](docs/VRAM_MANAGEMENT_GUIDE.md) - 深入了解显存监控和管理
- [API使用指南](docs/API_USAGE_GUIDE.md) - 详细的API使用示例和最佳实践
- [日志管理文档](docs/log_management.md) - 日志配置和监控工具使用
- [模型切换指南](docs/switch_embedding_model.md) - 动态模型切换操作说明

## 🔗 相关链接

- [FastChat官方文档](https://github.com/lm-sys/FastChat)
- [Qwen2.5模型介绍](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct)
- [BGE-M3模型介绍](https://huggingface.co/BAAI/bge-m3)