25 KiB
25 KiB
TSP智能助手 - 完整使用指南
📋 目录
🎯 系统概述
TSP智能助手是一个基于大语言模型的智能客服系统,集成了知识库管理、车辆数据监控、工单处理、分析报告等功能。
主要特性
- 🤖 智能对话: 基于阿里云千问大模型的自然语言对话
- 📚 知识库管理: 支持手动添加和文件自动生成知识库
- 🚗 车辆数据: 实时车辆数据监控和管理
- 🎯 Agent模式: 自主决策和任务执行能力
- 📊 数据分析: 智能分析和报告生成
- 🚨 预警系统: 实时监控和异常预警
- 🎫 工单管理: 完整的客服工单流程
- 🌐 Web界面: 现代化的用户界面
技术架构
- 后端: Python + Flask
- 数据库: MySQL/SQLite
- 前端: HTML5 + Bootstrap 5 + Chart.js
- AI模型: 阿里云千问 (Qwen)
- 实时通信: WebSocket
🚀 快速开始
1. 环境要求
- Python 3.8+
- MySQL 5.7+ (可选,默认使用SQLite)
- 阿里云千问API密钥
2. 安装依赖
pip install -r requirements.txt
3. 配置系统
编辑 src/config/config.py:
class Config:
# 阿里云千问API配置
ALIBABA_API_KEY = "your-api-key"
ALIBABA_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
ALIBABA_MODEL_NAME = "qwen-plus-latest"
# 数据库配置
DATABASE_URL = "mysql+pymysql://user:password@localhost/tsp_assistant?charset=utf8mb4"
# 或使用SQLite: DATABASE_URL = "sqlite:///tsp_assistant.db"
4. 初始化数据库
python init_database.py
5. 启动系统
python start_dashboard.py
6. 访问界面
打开浏览器访问: http://localhost:5000
🎛️ 核心功能
1. 智能对话系统
- 实时对话: 基于WebSocket的实时聊天
- 知识库集成: 自动搜索相关知识库内容
- 车辆数据集成: 结合实时车辆数据提供准确回答
- 上下文记忆: 维护对话历史和上下文
2. Agent模式
- 自主决策: AI Agent可以自主分析和决策
- 任务规划: 自动分解复杂任务
- 工具调用: 集成多种工具和API
- 主动监控: 实时监控系统状态
3. 知识库管理
- 手动添加: 通过界面手动添加知识条目
- 文件导入: 支持TXT、PDF、DOC、DOCX、MD文件
- 自动提取: 使用LLM自动从文件中提取知识
- 验证机制: 人工验证确保知识质量
- 分页显示: 支持大量知识库的分页浏览
4. 车辆数据管理
- 实时数据: 存储和查询车辆实时数据
- 数据汇总: 生成车辆状态摘要
- 历史记录: 保存车辆数据历史
- 多车辆支持: 支持多辆车辆的数据管理
🌐 Web界面使用
主界面布局
Web界面采用现代化的单页应用设计,包含以下主要区域:
- 侧边栏导航: 功能模块切换
- 主内容区: 当前功能的具体操作界面
- 状态栏: 系统状态和通知
功能模块
1. 仪表板 (Dashboard)
- 系统概览和关键指标
- 实时数据图表
- 快速操作入口
2. 智能对话 (Chat)
- 实时聊天界面
- 支持文本和语音输入
- 对话历史记录
3. Agent模式 (Agent)
- Agent状态监控
- 任务执行情况
- 主动监控设置
4. 预警管理 (Alerts)
- 预警规则配置
- 预警历史记录
- 预警处理状态
5. 知识库 (Knowledge)
- 知识条目管理
- 文件上传功能
- 知识验证操作
6. 工单管理 (Work Orders)
- 工单创建和编辑
- 工单状态跟踪
- 工单统计分析
7. 数据分析 (Analytics)
- 数据统计图表
- 趋势分析报告
- 性能指标监控
8. 系统设置 (Settings)
- 系统参数配置
- 用户权限管理
- 系统维护操作
页面状态保持
系统会自动保存当前页面状态,刷新后会自动恢复到之前的页面。
🔌 API接口
基础URL
http://localhost:5000/api
1. 对话接口
发送消息
POST /api/chat/message
Content-Type: application/json
{
"message": "用户消息内容",
"work_order_id": 123,
"user_id": "user123",
"vehicle_id": "V001"
}
WebSocket连接
const ws = new WebSocket('ws://localhost:5000/ws');
ws.onmessage = function(event) {
const data = JSON.parse(event.data);
console.log('收到消息:', data);
};
2. 知识库接口
获取知识库列表
GET /api/knowledge?page=1&per_page=10
添加知识条目
POST /api/knowledge/add
Content-Type: application/json
{
"question": "问题内容",
"answer": "答案内容",
"category": "分类",
"confidence_score": 0.8
}
上传文件生成知识库
POST /api/knowledge/upload
Content-Type: multipart/form-data
file: [文件内容]
process_method: auto
category: 分类
confidence_score: 0.8
验证知识条目
POST /api/knowledge/verify/{knowledge_id}
取消验证
POST /api/knowledge/unverify/{knowledge_id}
删除知识条目
DELETE /api/knowledge/{knowledge_id}
3. 车辆数据接口
获取车辆数据
GET /api/vehicle/data?vehicle_id=V001&limit=10
获取最新车辆数据
GET /api/vehicle/data/{vehicle_id}/latest
获取车辆摘要
GET /api/vehicle/data/{vehicle_id}/summary
添加车辆数据
POST /api/vehicle/data
Content-Type: application/json
{
"vehicle_id": "V001",
"vehicle_vin": "1HGBH41JXMN109186",
"data_type": "location",
"data_value": "{\"lat\": 39.9042, \"lng\": 116.4074}"
}
初始化示例数据
POST /api/vehicle/init-sample-data
4. Agent接口
获取Agent状态
GET /api/agent/status
切换Agent模式
POST /api/agent/toggle
Content-Type: application/json
{
"enabled": true
}
启动主动监控
POST /api/agent/monitoring/start
停止主动监控
POST /api/agent/monitoring/stop
5. 工单接口
获取工单列表
GET /api/work-orders?page=1&per_page=10
创建工单
POST /api/work-orders
Content-Type: application/json
{
"title": "工单标题",
"description": "工单描述",
"priority": "high",
"category": "技术问题",
"customer_id": "customer123"
}
更新工单状态
PUT /api/work-orders/{work_order_id}
Content-Type: application/json
{
"status": "resolved",
"resolution": "问题已解决"
}
6. 分析接口
获取分析报告
GET /api/analytics/report?date=2025-09-06
获取KPI数据
GET /api/analytics/kpi
7. 预警接口
获取预警列表
GET /api/alerts?status=active
处理预警
POST /api/alerts/{alert_id}/resolve
Content-Type: application/json
{
"resolution": "处理说明"
}
🗄️ 数据库管理
数据库初始化
系统提供了完整的数据库初始化脚本:
python init_database.py
该脚本会自动执行以下操作:
- 创建所有必要的数据库表
- 添加新字段(如知识库验证字段)
- 插入初始示例数据
- 添加示例车辆数据
- 验证所有知识库条目
数据库表结构
1. 知识库表 (knowledge_entries)
CREATE TABLE knowledge_entries (
id INTEGER PRIMARY KEY,
question TEXT NOT NULL,
answer TEXT NOT NULL,
category VARCHAR(100),
confidence_score FLOAT DEFAULT 0.5,
usage_count INTEGER DEFAULT 0,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
is_active BOOLEAN DEFAULT TRUE,
is_verified BOOLEAN DEFAULT FALSE,
verified_by VARCHAR(100),
verified_at DATETIME,
vector_embedding TEXT
);
2. 车辆数据表 (vehicle_data)
CREATE TABLE vehicle_data (
id INTEGER PRIMARY KEY,
vehicle_id VARCHAR(50) NOT NULL,
vehicle_vin VARCHAR(17),
data_type VARCHAR(50) NOT NULL,
data_value TEXT NOT NULL,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
is_active BOOLEAN DEFAULT TRUE
);
3. 工单表 (work_orders)
CREATE TABLE work_orders (
id INTEGER PRIMARY KEY,
title VARCHAR(200) NOT NULL,
description TEXT,
status VARCHAR(50) DEFAULT 'open',
priority VARCHAR(20) DEFAULT 'medium',
category VARCHAR(100),
customer_id VARCHAR(100),
assigned_to VARCHAR(100),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
resolved_at DATETIME,
resolution TEXT
);
4. 对话表 (conversations)
CREATE TABLE conversations (
id INTEGER PRIMARY KEY,
user_id VARCHAR(100),
work_order_id INTEGER,
vehicle_id VARCHAR(50),
message TEXT NOT NULL,
response TEXT,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
session_id VARCHAR(100)
);
5. 分析表 (analytics)
CREATE TABLE analytics (
id INTEGER PRIMARY KEY,
date DATE NOT NULL,
metric_name VARCHAR(100) NOT NULL,
metric_value FLOAT NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
6. 预警表 (alerts)
CREATE TABLE alerts (
id INTEGER PRIMARY KEY,
alert_type VARCHAR(100) NOT NULL,
title VARCHAR(200) NOT NULL,
description TEXT,
severity VARCHAR(20) DEFAULT 'medium',
status VARCHAR(20) DEFAULT 'active',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
resolved_at DATETIME,
resolution TEXT
);
数据库维护
重置数据库
python reset_database.py
创建MySQL数据库
python create_mysql_db.py
🤖 Agent功能
Agent架构
TSP智能助手集成了完整的Agent架构,包括:
- Agent核心 (Agent Core): 中央协调器
- 规划器 (Planner): 任务规划和分解
- 执行器 (Executor): 任务执行管理
- 工具管理器 (Tool Manager): 工具注册和调用
- 推理引擎 (Reasoning Engine): 逻辑推理和决策
- 目标管理器 (Goal Manager): 目标设定和跟踪
Agent工具
系统内置了多种Agent工具:
- search_knowledge: 搜索知识库
- create_work_order: 创建工单
- update_work_order: 更新工单
- generate_response: 生成回复
- analyze_data: 数据分析
- send_notification: 发送通知
- schedule_task: 任务调度
- web_search: 网络搜索
Agent模式使用
启用Agent模式
// 通过Web界面
fetch('/api/agent/toggle', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({enabled: true})
});
启动主动监控
fetch('/api/agent/monitoring/start', {method: 'POST'});
获取Agent状态
fetch('/api/agent/status')
.then(response => response.json())
.then(data => console.log('Agent状态:', data));
🚗 车辆数据管理
车辆数据类型
系统支持多种车辆数据类型:
- 位置数据 (location): GPS坐标和地址信息
- 状态数据 (status): 车辆运行状态
- 电池数据 (battery): 电池电量和健康状态
- 引擎数据 (engine): 引擎运行参数
- 故障数据 (fault): 故障码和诊断信息
数据格式示例
位置数据
{
"lat": 39.9042,
"lng": 116.4074,
"address": "北京市朝阳区",
"speed": 60,
"direction": 180
}
状态数据
{
"engine_status": "running",
"door_status": "locked",
"window_status": "closed",
"light_status": "on"
}
电池数据
{
"battery_level": 85,
"charging_status": "not_charging",
"voltage": 12.6,
"temperature": 25
}
车辆数据操作
添加车辆数据
from src.vehicle.vehicle_data_manager import VehicleDataManager
vehicle_manager = VehicleDataManager()
# 添加位置数据
vehicle_manager.add_vehicle_data(
vehicle_id="V001",
vehicle_vin="1HGBH41JXMN109186",
data_type="location",
data_value={"lat": 39.9042, "lng": 116.4074}
)
# 添加状态数据
vehicle_manager.add_vehicle_data(
vehicle_id="V001",
data_type="status",
data_value={"engine_status": "running", "door_status": "locked"}
)
查询车辆数据
# 获取最新数据
latest_data = vehicle_manager.get_latest_vehicle_data("V001")
# 获取历史数据
history_data = vehicle_manager.get_vehicle_data("V001", limit=10)
# 获取数据摘要
summary = vehicle_manager.get_vehicle_summary("V001")
车辆数据集成
车辆数据会自动集成到对话系统中:
- 实时查询: 对话时自动查询相关车辆数据
- 上下文整合: 将车辆数据与知识库内容结合
- 智能分析: 基于车辆数据提供更准确的建议
📚 知识库管理
知识库结构
每个知识库条目包含以下字段:
- 问题 (question): 用户可能提出的问题
- 答案 (answer): 对应的详细答案
- 分类 (category): 问题所属类别
- 置信度 (confidence_score): 答案的可信度 (0-1)
- 使用次数 (usage_count): 该条目被使用的次数
- 验证状态 (is_verified): 是否经过人工验证
- 验证人 (verified_by): 验证人员
- 验证时间 (verified_at): 验证时间
知识库分类
系统支持以下知识库分类:
- 账户问题: 用户账户相关的问题
- 支付问题: 支付和财务相关的问题
- 技术问题: 技术故障和解决方案
- 服务问题: 客户服务相关问题
- 远程控制: 车辆远程控制功能
- APP功能: 移动应用功能使用
- 车辆绑定: 车辆绑定和管理
- 其他: 其他类型的问题
手动添加知识
通过Web界面
- 进入"知识库"标签页
- 点击"添加知识"按钮
- 填写问题、答案、分类和置信度
- 点击"保存"按钮
通过API
POST /api/knowledge/add
Content-Type: application/json
{
"question": "如何重置密码?",
"answer": "您可以通过以下步骤重置密码:1. 点击登录页面的'忘记密码'链接 2. 输入您的邮箱地址 3. 检查邮箱并点击重置链接 4. 设置新密码",
"category": "账户问题",
"confidence_score": 0.9
}
文件导入知识库
支持的文件格式
- TXT: 纯文本文件
- PDF: PDF文档
- DOC/DOCX: Word文档
- MD: Markdown文件
导入流程
- 进入"知识库"标签页
- 点击"上传文件"按钮
- 选择要上传的文件
- 选择处理方式(自动/手动)
- 设置分类和置信度
- 点击"上传"按钮
自动知识提取
系统使用LLM自动从文件中提取问答对:
- 内容分析: 分析文件内容结构
- 问题识别: 识别潜在的问题点
- 答案生成: 生成对应的详细答案
- 分类建议: 自动建议问题分类
- 置信度评估: 评估答案的可信度
知识库验证
验证机制
- 自动验证: 系统初始化的知识库条目自动标记为已验证
- 人工验证: 新添加的知识库条目需要人工验证
- 验证状态: 只有已验证的知识库条目才会在对话中使用
验证操作
- 进入"知识库"标签页
- 找到未验证的知识条目
- 点击"验证"按钮确认知识正确性
- 或点击"取消验证"按钮标记为未验证
知识库搜索
系统使用TF-IDF向量化技术进行知识库搜索:
- 向量化: 将问题和答案转换为向量
- 相似度计算: 计算用户问题与知识库的相似度
- 排序返回: 按相似度排序返回最相关的知识
💬 对话系统
对话流程
- 接收用户消息: 通过WebSocket或HTTP接收用户输入
- 上下文分析: 分析对话历史和上下文
- 知识库搜索: 搜索相关的知识库内容
- 车辆数据查询: 如果涉及车辆,查询相关车辆数据
- LLM生成回复: 使用大语言模型生成回复
- 回复优化: 结合知识库和车辆数据优化回复
- 返回结果: 将最终回复返回给用户
对话特性
1. 上下文记忆
- 维护对话历史
- 理解上下文关系
- 支持多轮对话
2. 知识库集成
- 自动搜索相关知识
- 只使用已验证的知识
- 结合多个知识条目
3. 车辆数据集成
- 实时查询车辆状态
- 结合车辆数据提供建议
- 支持车辆特定问题
4. 工单关联
- 自动创建工单
- 关联对话和工单
- 跟踪问题解决进度
对话API使用
WebSocket连接
const ws = new WebSocket('ws://localhost:5000/ws');
ws.onopen = function() {
console.log('WebSocket连接已建立');
};
ws.onmessage = function(event) {
const data = JSON.parse(event.data);
console.log('收到消息:', data.message);
};
// 发送消息
ws.send(JSON.stringify({
message: '我的车辆无法启动',
vehicle_id: 'V001'
}));
HTTP接口
fetch('/api/chat/message', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
message: '我的车辆无法启动',
vehicle_id: 'V001',
user_id: 'user123'
})
})
.then(response => response.json())
.then(data => console.log('回复:', data.response));
🎫 工单管理
工单状态
工单有以下状态:
- open: 新建工单
- in_progress: 处理中
- pending: 等待用户反馈
- resolved: 已解决
- closed: 已关闭
工单优先级
- low: 低优先级
- medium: 中等优先级
- high: 高优先级
- urgent: 紧急
工单分类
- 技术问题: 技术故障和bug
- 功能请求: 新功能需求
- 账户问题: 用户账户相关问题
- 支付问题: 支付和财务问题
- 其他: 其他类型问题
工单操作
创建工单
fetch('/api/work-orders', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
title: '车辆无法远程启动',
description: '用户反馈车辆无法通过APP远程启动',
priority: 'high',
category: '技术问题',
customer_id: 'customer123'
})
});
更新工单状态
fetch('/api/work-orders/123', {
method: 'PUT',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
status: 'resolved',
resolution: '已修复远程启动功能'
})
});
获取工单列表
fetch('/api/work-orders?page=1&per_page=10')
.then(response => response.json())
.then(data => console.log('工单列表:', data));
📊 分析报告
分析指标
系统提供以下分析指标:
- 对话统计: 对话数量、响应时间、满意度
- 知识库使用: 知识库命中率、热门问题
- 工单分析: 工单数量、解决时间、分类统计
- 车辆数据: 车辆状态分布、故障统计
- 用户行为: 用户活跃度、功能使用情况
报告生成
获取分析报告
fetch('/api/analytics/report?date=2025-09-06')
.then(response => response.json())
.then(data => console.log('分析报告:', data));
获取KPI数据
fetch('/api/analytics/kpi')
.then(response => response.json())
.then(data => console.log('KPI数据:', data));
数据可视化
Web界面提供多种图表:
- 折线图: 趋势分析
- 柱状图: 分类统计
- 饼图: 比例分析
- 仪表盘: 实时指标
🚨 预警系统
预警类型
- 系统预警: 系统性能异常
- 业务预警: 业务指标异常
- 安全预警: 安全相关事件
- 数据预警: 数据异常
预警级别
- low: 低级别预警
- medium: 中等级别预警
- high: 高级别预警
- critical: 严重预警
预警处理
获取预警列表
fetch('/api/alerts?status=active')
.then(response => response.json())
.then(data => console.log('活跃预警:', data));
处理预警
fetch('/api/alerts/123/resolve', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
resolution: '已修复相关问题'
})
});
🔧 故障排除
常见问题
1. 数据库连接失败
症状: 启动时提示数据库连接失败 解决方案:
- 检查数据库配置是否正确
- 确认数据库服务是否运行
- 检查网络连接和防火墙设置
2. API密钥无效
症状: LLM调用失败 解决方案:
- 检查阿里云千问API密钥是否正确
- 确认API密钥是否有效且有足够额度
- 检查网络连接
3. 文件上传失败
症状: 文件上传时提示"文件被占用" 解决方案:
- 重启系统
- 检查临时文件目录权限
- 清理临时文件
4. 知识库显示异常
症状: 知识库内容无法正常显示 解决方案:
- 运行数据库初始化脚本
- 检查数据库表结构
- 重新加载知识库
日志查看
查看系统日志
# Windows
Get-Content logs/tsp_assistant.log -Tail 50
# Linux/Mac
tail -50 logs/tsp_assistant.log
日志级别
- DEBUG: 详细调试信息
- INFO: 一般信息
- WARNING: 警告信息
- ERROR: 错误信息
- CRITICAL: 严重错误
性能优化
1. 数据库优化
- 定期清理历史数据
- 添加必要的索引
- 优化查询语句
2. 缓存优化
- 启用知识库缓存
- 缓存频繁查询的数据
- 使用Redis等缓存系统
3. 并发优化
- 调整WebSocket连接数
- 优化数据库连接池
- 使用异步处理
👨💻 开发指南
项目结构
TSP_assistant/
├── src/ # 源代码目录
│ ├── agent/ # Agent相关模块
│ ├── analytics/ # 分析模块
│ ├── config/ # 配置模块
│ ├── core/ # 核心模块
│ ├── dialogue/ # 对话模块
│ ├── knowledge_base/ # 知识库模块
│ ├── utils/ # 工具模块
│ ├── vehicle/ # 车辆数据模块
│ └── web/ # Web模块
├── logs/ # 日志目录
├── data/ # 数据目录
├── requirements.txt # 依赖包
├── init_database.py # 数据库初始化
└── start_dashboard.py # 启动脚本
开发环境设置
1. 克隆项目
git clone <repository-url>
cd TSP_assistant
2. 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
venv\Scripts\activate # Windows
3. 安装依赖
pip install -r requirements.txt
4. 配置环境
cp src/config/config.py.example src/config/config.py
# 编辑配置文件
代码规范
1. Python代码规范
- 使用PEP 8代码风格
- 添加类型注解
- 编写文档字符串
- 使用日志记录
2. JavaScript代码规范
- 使用ES6+语法
- 添加JSDoc注释
- 使用const/let替代var
- 处理异步操作
3. 数据库规范
- 使用ORM而不是原生SQL
- 添加适当的索引
- 使用事务处理
- 处理异常情况
测试
1. 单元测试
python -m pytest tests/
2. 集成测试
python test_new_features.py
3. 功能测试
python comprehensive_frontend_test.py
部署
1. 生产环境配置
- 使用生产数据库
- 配置HTTPS
- 设置环境变量
- 启用日志轮转
2. Docker部署
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "start_dashboard.py"]
3. 监控和运维
- 设置健康检查
- 配置监控告警
- 定期备份数据
- 性能监控
📞 技术支持
联系方式
- 邮箱: support@example.com
- 电话: 400-123-4567
- 在线客服: 通过系统内置客服功能
文档更新
本文档会定期更新,请关注最新版本。
反馈建议
如果您在使用过程中遇到问题或有改进建议,请通过以下方式反馈:
- 通过系统内置反馈功能
- 发送邮件到技术支持邮箱
- 提交GitHub Issue
版本: v2.0
更新日期: 2025-09-06
维护团队: TSP智能助手开发团队