tsp-assistant/README.md

# TSP助手 - 基于大模型的AI客服机器人

## 项目简介

TSP助手是一个基于阿里云千问大模型的智能客服机器人系统，具备以下核心功能：

- **智能对话处理**：基于大模型进行自然语言理解和回复生成
- **知识库学习**：从历史工单中自动学习问题处理经验
- **实时数据分析**：统计工单处理情况，生成分析报告
- **智能预警系统**：监控关键指标，及时发现问题
- **工单管理**：完整的工单生命周期管理

## 系统架构

```
TSP_assistant/
├── src/
│   ├── config/          # 配置文件
│   ├── core/            # 核心模块
│   ├── knowledge_base/  # 知识库管理
│   ├── dialogue/        # 对话管理
│   ├── analytics/       # 分析统计
│   └── utils/           # 工具函数
├── data/                # 数据存储
├── logs/                # 日志文件
└── requirements.txt    # 依赖包
```

## 核心功能

### 1. 智能对话处理
- 基于阿里云千问大模型进行自然语言理解
- 支持上下文记忆和对话历史管理
- 自动从知识库检索相关信息
- 生成准确、有用的回复

### 2. 知识库学习
- 从已解决的工单中自动提取问题和答案
- 使用TF-IDF向量化进行相似度匹配
- 支持知识库条目的增删改查
- 自动更新和优化知识库内容

### 3. 工单管理
- 创建、更新、查询工单
- 支持工单分类和优先级设置
- 记录完整的对话历史
- 工单状态跟踪和满意度评分

### 4. 数据分析与统计
- 每日自动生成分析报告
- 统计工单处理效率、满意度等指标
- 支持多维度数据分析
- 生成可视化趋势图表

### 5. 智能预警系统
- 监控关键性能指标
- 自动检测异常情况
- 支持多级别预警（低、中、高、严重）
- 预警历史记录和解决跟踪

## 安装和配置

### 1. 环境要求
- Python 3.8+
- MySQL数据库（推荐）或SQLite数据库
- 阿里云千问API密钥

### 2. 安装步骤

```bash
# 克隆项目
git clone <repository-url>
cd TSP_assistant

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

# 创建必要目录
mkdir -p data logs

# 设置MySQL数据库（如果使用MySQL）
python create_mysql_db.py

# 初始化数据库
python init_database.py

# 配置API密钥
# 在 src/config/config.py 中设置您的阿里云API密钥
```

### 3. MySQL数据库设置

如果使用MySQL数据库，需要先运行：
```bash
python create_mysql_db.py
```

此脚本会：
- 创建名为 `tsp_assistant` 的数据库
- 设置正确的字符集（utf8mb4）
- 创建专用用户（可选）
- 测试数据库连接

### 4. 数据库初始化

数据库初始化脚本会自动：
- 创建所有必要的数据库表
- 插入示例知识库数据
- 检查数据库连接状态
- 显示各表的记录数统计

如果数据库已存在，脚本会跳过初始数据插入，避免重复数据。

### 5. 数据库选择

系统支持两种数据库：

**MySQL（推荐）**：
- 性能更好，支持并发
- 适合生产环境
- 需要安装MySQL服务器

**SQLite**：
- 轻量级，无需额外安装
- 适合开发和测试
- 单文件存储

### 6. 配置说明

在 `src/config/config.py` 中配置以下参数：

```python
# 阿里云千问API配置
ALIBABA_API_KEY = "your-api-key"
ALIBABA_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
ALIBABA_MODEL_NAME = "qwen-plus-latest"

# 数据库配置
# MySQL配置（推荐）
DATABASE_URL = "mysql+pymysql://root:123456@localhost/tsp_assistant?charset=utf8mb4"
# SQLite配置（备用）
# DATABASE_URL = "sqlite:///tsp_assistant.db"

# 其他系统参数
MAX_HISTORY_LENGTH = 10
RESPONSE_TIMEOUT = 30
```

## 使用方法

### 1. 启动系统

```python
from src.main import TSPAssistant

# 创建助手实例
assistant = TSPAssistant()

# 测试系统
test_results = assistant.test_system()
print("系统测试结果:", test_results)
```

### 2. 处理用户消息

```python
# 处理用户消息
response = assistant.process_message(
    message="我的账户无法登录",
    user_id="user123",
    work_order_id=1
)
print("回复:", response["response"])
```

### 3. 创建工单

```python
# 创建工单
work_order = assistant.create_work_order(
    title="账户登录问题",
    description="用户反映无法登录账户",
    category="账户问题",
    priority="high"
)
```

### 4. 搜索知识库

```python
# 搜索知识库
results = assistant.search_knowledge("账户登录", top_k=3)
print("搜索结果:", results)
```

### 5. 生成分析报告

```python
# 生成分析报告
analytics = assistant.generate_analytics("last_7_days")
print("分析报告:", analytics)
```

## API接口

### 对话接口
- `process_message(message, user_id, work_order_id)` - 处理用户消息
- `create_work_order(title, description, category, priority)` - 创建工单
- `update_work_order(work_order_id, **kwargs)` - 更新工单

### 知识库接口
- `search_knowledge(query, top_k)` - 搜索知识库
- `add_knowledge(question, answer, category, confidence_score)` - 添加知识

### 分析接口
- `generate_analytics(date_range)` - 生成分析报告
- `get_alerts()` - 获取预警信息
- `get_system_status()` - 获取系统状态

## 数据模型

### 工单 (WorkOrder)
- 工单基本信息（ID、标题、描述、类别、优先级）
- 状态跟踪（创建时间、更新时间、解决时间）
- 满意度评分

### 对话记录 (Conversation)
- 用户消息和助手回复
- 时间戳和置信度评分
- 使用的知识库条目

### 知识库条目 (KnowledgeEntry)
- 问题和答案对
- 类别和置信度评分
- 使用次数统计

### 分析数据 (Analytics)
- 每日统计指标
- 趋势分析数据
- 类别分布信息

## 监控和预警

系统自动监控以下指标：

- **客户满意度**：低于0.6时触发预警
- **平均解决时间**：超过24小时时触发预警
- **知识库命中率**：低于0.5时触发预警
- **错误率**：超过0.1时触发预警

## 性能优化

- 使用向量化技术提高知识库检索效率
- 支持并发处理多个用户请求
- 数据库连接池管理
- 内存使用监控和优化

## 扩展功能

- 支持多种大模型API（可扩展）
- 支持多种数据库后端（PostgreSQL、MySQL等）
- 支持Web界面和API接口
- 支持多语言处理
- 支持语音识别和合成

## 故障排除

### 常见问题

1. **API连接失败**
   - 检查API密钥是否正确
   - 检查网络连接
   - 检查API配额是否充足

2. **数据库错误**
   - 检查数据库文件权限
   - 检查SQLite版本兼容性
   - 检查磁盘空间

3. **知识库检索失败**
   - 检查向量化器是否正确初始化
   - 检查知识库数据完整性
   - 检查内存使用情况

### 日志查看

系统日志保存在 `logs/tsp_assistant.log` 文件中，包含详细的运行信息和错误记录。

## 贡献指南

欢迎提交Issue和Pull Request来改进项目。

## 许可证

本项目采用MIT许可证。