# Evaluation

**Repository Path**: one-step-ai/evaluation

## Basic Information

- **Project Name**: Evaluation
- **Description**: 大模型测评
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-30
- **Last Updated**: 2025-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 大模型测评系统

一个高可用的大模型性能测评系统，支持并发测试、性能监控、数据分析和报告生成。

## 🚀 功能特性

### 核心功能
- **并发测试**: 支持多线程/协程并发请求大模型API
- **性能监控**: 实时收集首Token延迟、端到端延迟、吞吐量等指标
- **可视化分析**: 生成延迟折线图、吞吐量图表、瓶颈分析等
- **模型管理**: 动态配置、删除要测评的大模型服务
- **数据存储**: 使用SQLite嵌入式数据库，支持数据迁移
- **报告生成**: 自动生成HTML格式的测评报告

### 性能指标
- 首Token延迟（First Token Latency）
- 端到端延迟（End-to-End Latency）
- 吞吐量（Throughput）
- 错误率（Error Rate）
- Token生成速度（Tokens per Second）
- P50/P90/P99延迟分布
- 响应时间分布

### 技术架构
- **后端**: Python + FastAPI + LangGraph
- **数据库**: SQLite（嵌入式）
- **图表**: Plotly + Matplotlib
- **并发**: asyncio + aiohttp
- **工作流**: LangGraph Agent框架

## 📦 安装部署

### 环境要求
- Python 3.11+
- Windows/Mac/Linux

### 快速开始

1. **克隆项目**
```bash
git clone <repository-url>
cd llm-evaluation-system
```

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

# 安装前端依赖（可选）
npm install
```

3. **启动系统**
```bash
# 进入后端目录
cd backend

# 启动后端服务
python run.py
```

4. **访问系统**
- 后端API: http://localhost:8000
- API文档: http://localhost:8000/docs

## 🔧 配置说明

### 默认模型配置
系统已预配置默认模型：
```python
DEFAULT_MODEL_CONFIG = {
    "name": "Qwen3-235B-A22B-Instruct",
    "api_key": "sk-ccchmtidgsckbcvjioslborykupvizcsjzoqnwynuxsrfrsy",
    "base_url": "https://api.siliconflow.cn/v1",
    "model": "Qwen/Qwen3-235B-A22B-Instruct-2507",
    "temperature": 0.7,
    "max_tokens": 1000,
    "timeout": 30
}
```

### 环境变量
创建 `.env` 文件：
```env
# 数据库配置
DATABASE_URL=sqlite:///./llm_evaluation.db

# API配置
API_V1_STR=/api
PROJECT_NAME=大模型测评系统

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=logs/app.log

# Redis配置（可选）
REDIS_URL=redis://localhost:6379
```

## 📖 使用指南

### 1. 模型管理

#### 添加模型配置
```bash
curl -X POST "http://localhost:8000/api/models/" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的模型",
    "api_key": "your-api-key",
    "base_url": "https://api.example.com/v1",
    "model": "gpt-3.5-turbo",
    "temperature": 0.7,
    "max_tokens": 1000,
    "timeout": 30
  }'
```

#### 获取模型列表
```bash
curl "http://localhost:8000/api/models/"
```

### 2. 性能测试

#### 创建测试
```bash
curl -X POST "http://localhost:8000/api/tests/" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 1,
    "concurrent_users": 5,
    "test_duration": 60,
    "request_payload": "请介绍一下人工智能的发展历史"
  }'
```

#### 获取测试结果
```bash
curl "http://localhost:8000/api/tests/1"
```

### 3. 报告生成

#### 获取HTML报告
```bash
curl "http://localhost:8000/api/reports/1/html"
```

#### 下载报告
```bash
curl "http://localhost:8000/api/reports/1/download?format_type=html"
```

## 🧪 测试验证

### 运行系统测试
```bash
cd backend
python test_system.py
```

### 测试结果
系统会自动测试以下功能：
- ✅ 数据库功能
- ✅ 测试器功能  
- ✅ 图表生成
- ✅ API功能

## 📊 API接口

### 模型管理
- `GET /api/models/` - 获取所有模型
- `POST /api/models/` - 创建模型配置
- `GET /api/models/{id}` - 获取模型详情
- `PUT /api/models/{id}` - 更新模型配置
- `DELETE /api/models/{id}` - 删除模型配置

### 测试管理
- `GET /api/tests/` - 获取测试记录
- `POST /api/tests/` - 创建测试
- `GET /api/tests/{id}` - 获取测试结果
- `GET /api/tests/{id}/metrics` - 获取性能指标
- `DELETE /api/tests/{id}` - 取消测试

### 报告管理
- `GET /api/reports/{id}/html` - 获取HTML报告
- `GET /api/reports/{id}/download` - 下载报告
- `GET /api/reports/dashboard` - 获取仪表板

## 🔍 监控指标

### 延迟指标
- **首Token延迟**: 从请求发送到收到第一个Token的时间
- **端到端延迟**: 从请求发送到完整响应的时间
- **P50/P90/P99延迟**: 不同百分位的延迟分布

### 吞吐量指标
- **RPS**: 每秒请求数
- **并发用户数**: 同时发送请求的用户数
- **Token生成速度**: 每秒生成的Token数

### 错误指标
- **错误率**: 失败请求占总请求的比例
- **错误类型**: 超时、认证失败、服务器错误等
- **成功率**: 成功请求占总请求的比例

## 🛠️ 开发指南

### 项目结构
```
backend/
├── app/
│   ├── core/           # 核心配置和模型
│   ├── routers/        # API路由
│   └── services/       # 业务逻辑服务
├── main.py             # 主应用文件
├── run.py              # 启动脚本
└── test_system.py      # 系统测试脚本
```

### 添加新功能
1. 在 `app/services/` 中添加业务逻辑
2. 在 `app/routers/` 中添加API路由
3. 在 `app/core/models.py` 中定义数据模型
4. 运行测试验证功能

### 数据库迁移
```bash
# 备份数据库
cp llm_evaluation.db llm_evaluation.db.backup

# 删除旧数据库（谨慎操作）
rm llm_evaluation.db

# 重新初始化
python -c "from app.core.database import init_db; import asyncio; asyncio.run(init_db())"
```

## 🐛 故障排除

### 常见问题

1. **依赖安装失败**
```bash
# 升级pip
pip install --upgrade pip

# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
```

2. **数据库连接失败**
```bash
# 检查数据库文件权限
ls -la llm_evaluation.db

# 重新初始化数据库
python -c "from app.core.database import init_db; import asyncio; asyncio.run(init_db())"
```

3. **API请求失败**
```bash
# 检查服务状态
curl http://localhost:8000/health

# 查看日志
tail -f logs/app.log
```

### 日志查看
```bash
# 实时查看日志
tail -f logs/app.log

# 查看错误日志
grep ERROR logs/app.log
```

## 📈 性能优化

### 系统优化建议
1. **并发数调整**: 根据服务器性能调整并发用户数
2. **超时设置**: 合理设置请求超时时间
3. **数据库优化**: 定期清理历史数据
4. **内存管理**: 监控系统内存使用情况

### 监控建议
1. **CPU使用率**: 监控测试期间的CPU使用情况
2. **内存使用**: 关注内存占用和垃圾回收
3. **网络延迟**: 监控客户端到服务器的网络延迟
4. **磁盘IO**: 监控数据库读写性能

## 🤝 贡献指南

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) 文件了解详情。

## 📞 联系方式

- 项目主页: [GitHub Repository]
- 问题反馈: [Issues]
- 邮箱: [your-email@example.com]

---

**注意**: 请确保在使用前配置正确的API密钥和模型参数。本系统仅用于性能测试，请遵守相关服务的使用条款。