Files

赵杰 Jie Zhao （雄狮汽车科技） da4736c323 feat: 重大功能更新 v1.4.0 - 飞书集成、AI语义相似度、前端优化

主要更新内容:
- 🚀 飞书多维表格集成，支持工单数据同步
- 🤖 AI建议与人工描述语义相似度计算
- 🎨 前端UI全面优化，现代化设计
- 📊 智能知识库入库策略（AI准确率<90%使用人工描述）
- 🔧 代码重构，模块化架构优化
- 📚 完整文档整合和更新
- 🐛 修复配置导入和数据库字段问题

技术特性:
- 使用sentence-transformers进行语义相似度计算
- 快速模式结合TF-IDF和语义方法
- 响应式设计，支持移动端
- 加载状态和动画效果
- 配置化AI准确率阈值

2025-09-19 19:32:42 +01:00

15 KiB

Raw Blame History

TSP智能助手完整文档

📋 目录

项目概述
系统架构
核心功能
技术栈
安装部署
配置说明
使用指南
API接口
数据库设计
开发指南
故障排除
更新日志

🚀 项目概述

TSP智能助手是一个基于大语言模型的智能客服系统，专为TSP（Telematics Service Provider）车辆服务提供商设计。系统集成了智能对话、工单管理、知识库、数据分析、飞书集成等核心功能。

核心特性

智能Agent架构: 多工具集成，智能规划，自主学习
实时对话系统: WebSocket支持，上下文理解，VIN识别
数据驱动分析: 真实数据统计，可视化展示，系统监控
企业级管理: 多环境部署，版本控制，热更新，自动备份
飞书集成: 支持飞书多维表格数据同步和管理
AI准确率优化: 智能判断AI建议质量，优先使用高质量内容入库

🏗️ 系统架构

整体架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端界面      │    │   后端服务      │    │   数据存储      │
│                 │    │                 │    │                 │
│ • 仪表板        │◄──►│ • Flask API     │◄──►│ • MySQL DB      │
│ • 智能对话      │    │ • WebSocket     │    │ • 知识库        │
│ • Agent管理     │    │ • Agent核心     │    │ • 工单系统      │
│ • 数据分析      │    │ • LLM集成       │    │ • 车辆数据      │
│ • 飞书同步      │    │ • 备份系统      │    │ • SQLite备份    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

模块化设计

Web层: Flask蓝图架构，模块化API设计
业务层: Agent核心、对话管理、工单处理
数据层: MySQL主库 + SQLite备份，ORM映射
集成层: 飞书API、LLM服务、监控系统

🎯 核心功能

1. 智能对话系统 💬

多轮对话: 支持上下文关联的连续对话
VIN识别: 自动识别车辆VIN并获取实时数据
知识库检索: 基于TF-IDF和余弦相似度的智能检索
工单创建: 对话中直接创建和关联工单

2. Agent管理系统 🤖

工具管理: 10+内置工具，支持自定义工具注册
执行监控: 实时监控Agent任务执行状态
性能统计: 工具使用频率和成功率分析
智能规划: 基于目标的任务分解和执行

3. 工单管理系统 📋

AI建议生成: 基于知识库生成工单处理建议
人工审核: 支持人工输入和AI建议对比
语义相似度: 使用sentence-transformers进行准确度评估
智能入库: AI准确率<90%时优先使用人工描述入库
知识库更新: 高相似度建议自动入库

4. 知识库管理 📚

多格式支持: TXT、PDF、DOC、DOCX、MD文件
智能提取: 自动从文档中提取Q&A对
向量化检索: TF-IDF + 余弦相似度搜索
质量验证: 支持知识条目验证和置信度设置

5. 数据分析系统 📊

实时趋势: 基于真实数据的性能趋势分析
多维度统计: 工单、预警、满意度等关键指标
系统健康: CPU、内存、响应时间监控
可视化展示: 丰富的图表和仪表板

6. 飞书集成系统 📱

多维表格同步: 自动同步飞书多维表格数据
字段映射: 智能映射飞书字段到本地数据库
实时更新: 支持增量同步和全量同步
数据预览: 同步前预览数据，确保准确性

7. 系统设置管理 ⚙️

API管理: 支持多种LLM提供商配置
模型参数: 温度、最大令牌数等参数调节
端口配置: Web服务和WebSocket端口管理
日志级别: 灵活的日志级别控制

🛠️ 技术栈

后端技术

Python 3.8+: 核心开发语言
Flask: Web框架和API服务
SQLAlchemy: ORM数据库操作
WebSocket: 实时通信支持
psutil: 系统资源监控

前端技术

Bootstrap 5: UI框架
Chart.js: 数据可视化
JavaScript ES6+: 前端逻辑
WebSocket: 实时通信客户端

AI/ML技术

大语言模型: 支持OpenAI、通义千问等
sentence-transformers: 语义相似度计算
TF-IDF: 文本向量化
余弦相似度: 语义相似度计算
Agent框架: 智能任务规划

部署运维

Docker: 容器化部署
Nginx: 反向代理和静态文件服务
Systemd: 服务管理
Git: 版本控制

🚀 安装部署

环境要求

Python 3.8+
Node.js 16+ (可选，用于前端构建)
Git
MySQL 8.0+

安装步骤

克隆项目

git clone http://jeason.online:3000/zhaojie/assist.git
cd assist

安装依赖

pip install -r requirements.txt

配置数据库

# 创建MySQL数据库
mysql -u root -p
CREATE DATABASE tsp_assistant CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

初始化数据库

python init_database.py

启动服务

python start_dashboard.py

访问系统

打开浏览器访问: http://localhost:5000
默认端口: 5000 (可在系统设置中修改)

Windows快速启动

# 双击运行
快速启动.bat

⚙️ 配置说明

环境变量

# 数据库配置
DATABASE_URL=mysql+pymysql://user:password@host:port/database

# LLM配置
LLM_PROVIDER=openai
LLM_API_KEY=your_api_key
LLM_MODEL=gpt-3.5-turbo

# 服务配置
SERVER_PORT=5000
WEBSOCKET_PORT=8765
LOG_LEVEL=INFO

配置文件结构

config/
├── llm_config.py              # LLM客户端配置
├── integrations_config.json   # 飞书集成配置
├── ai_accuracy_config.py      # AI准确率配置
└── README.md                  # 配置说明文档

飞书集成配置

{
  "feishu": {
    "app_id": "cli_a8b50ec0eed1500d",
    "app_secret": "ccxkE7ZCFQZcwkkM1rLy0ccZRXYsT2xK",
    "app_token": "XXnEbiCmEaMblSs6FDJcFCqsnIg",
    "table_id": "tblnl3vJPpgMTSiP",
    "status": "active"
  },
  "system": {
    "sync_limit": 10,
    "ai_suggestions_enabled": true,
    "auto_sync_interval": 0
  }
}

AI准确率配置

# 默认配置
auto_approve_threshold = 0.95      # 自动审批阈值
use_human_resolution_threshold = 0.90  # 使用人工描述阈值
manual_review_threshold = 0.80     # 人工审核阈值

📖 使用指南

基础操作

1. 智能对话

在"智能对话"页面输入问题
系统自动检索知识库并生成回答
支持VIN码识别和车辆数据查询

2. 工单管理

创建工单并获取AI建议
输入人工处理描述
系统自动计算语义相似度
根据相似度决定入库策略

3. 知识库维护

手动添加Q&A对
上传文档自动提取知识
设置置信度和验证状态

4. 飞书数据同步

配置飞书应用凭证
在主仪表板"飞书同步"标签页
测试连接并执行数据同步

高级功能

1. Agent工具管理

查看工具使用统计
注册自定义工具
监控执行历史

2. 数据分析

多维度数据统计
自定义时间范围
导出分析报告

3. 系统配置

API和模型参数配置
端口和日志级别设置
环境变量管理

🔌 API接口

工单管理API

POST /api/workorders/{id}/ai-suggestion
POST /api/workorders/{id}/human-resolution
POST /api/workorders/{id}/approve-to-knowledge
GET  /api/workorders
POST /api/workorders
PUT  /api/workorders/{id}
DELETE /api/workorders/{id}

知识库API

GET  /api/knowledge
POST /api/knowledge
PUT  /api/knowledge/{id}
DELETE /api/knowledge/{id}
POST /api/knowledge/search
POST /api/knowledge/upload

对话API

POST /api/chat/session
GET  /api/chat/session/{id}
DELETE /api/chat/session/{id}
POST /api/chat/message

Agent管理API

GET  /api/agent/status
POST /api/agent/tools/execute
POST /api/agent/tools/register
GET  /api/agent/tools/stats

🗄️ 数据库设计

核心表结构

work_orders (工单表)

CREATE TABLE work_orders (
    id INT PRIMARY KEY AUTO_INCREMENT,
    order_id VARCHAR(50) UNIQUE NOT NULL,
    title VARCHAR(200) NOT NULL,
    description TEXT NOT NULL,
    category VARCHAR(100) NOT NULL,
    priority VARCHAR(20) NOT NULL,
    status VARCHAR(20) NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    resolution TEXT,
    satisfaction_score FLOAT,
    
    -- 飞书集成字段
    feishu_record_id VARCHAR(100),
    source VARCHAR(50),
    module VARCHAR(100),
    created_by VARCHAR(100),
    wilfulness VARCHAR(100),
    date_of_close DATETIME,
    vehicle_type VARCHAR(100),
    vin_sim VARCHAR(50),
    app_remote_control_version VARCHAR(100),
    hmi_sw VARCHAR(100),
    parent_record VARCHAR(100),
    has_updated_same_day VARCHAR(50),
    operating_time VARCHAR(100)
);

work_order_suggestions (工单建议表)

CREATE TABLE work_order_suggestions (
    id INT PRIMARY KEY AUTO_INCREMENT,
    work_order_id INT NOT NULL,
    ai_suggestion TEXT,
    human_resolution TEXT,
    ai_similarity FLOAT,
    approved BOOLEAN DEFAULT FALSE,
    use_human_resolution BOOLEAN DEFAULT FALSE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (work_order_id) REFERENCES work_orders(id)
);

knowledge_entries (知识库表)

CREATE TABLE knowledge_entries (
    id INT PRIMARY KEY AUTO_INCREMENT,
    question TEXT NOT NULL,
    answer TEXT NOT NULL,
    category VARCHAR(100),
    confidence_score FLOAT DEFAULT 0.5,
    usage_count INT DEFAULT 0,
    is_active BOOLEAN DEFAULT TRUE,
    is_verified BOOLEAN DEFAULT FALSE,
    verified_by VARCHAR(100),
    verified_at DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

👨‍💻 开发指南

项目结构

tsp-assistant/
├── src/                        # 源代码
│   ├── agent/                  # Agent核心模块
│   ├── analytics/              # 数据分析模块
│   ├── config/                 # 配置模块
│   ├── core/                   # 核心模块
│   ├── dialogue/               # 对话模块
│   ├── integrations/           # 集成模块
│   ├── knowledge_base/         # 知识库模块
│   ├── utils/                  # 工具模块
│   ├── vehicle/                # 车辆数据模块
│   └── web/                    # Web应用模块
├── config/                     # 配置文件
├── scripts/                    # 脚本文件
├── uploads/                    # 上传文件
├── requirements.txt            # 依赖文件
├── init_database.py           # 数据库初始化
└── start_dashboard.py         # 启动脚本

代码规范

Python: 遵循PEP 8规范
JavaScript: 使用ES6+语法
提交信息: 使用约定式提交格式
文档: 新功能需要添加相应的文档

开发流程

Fork项目到个人仓库
创建功能分支: git checkout -b feature/new-feature
提交更改: git commit -m "Add new feature"
推送分支: git push origin feature/new-feature
创建Pull Request

🚨 故障排除

常见问题

1. 数据库连接失败

# 检查数据库服务状态
systemctl status mysql

# 检查连接配置
python -c "from src.core.database import db_manager; print(db_manager.test_connection())"

2. 飞书集成问题

检查飞书应用权限配置
验证app_token和table_id是否正确
确认网络连接和API访问权限

3. AI建议生成失败

检查LLM API配置
验证知识库数据完整性
查看应用日志

4. 数据库字段缺失

# 运行数据库迁移
python init_database.py

# 手动添加字段
mysql -u root -p tsp_assistant
ALTER TABLE work_order_suggestions ADD COLUMN use_human_resolution BOOLEAN DEFAULT FALSE;

日志位置

应用日志: logs/tsp_assistant.log
访问日志: Nginx访问日志
错误追踪: 详细的错误堆栈信息

性能优化

数据库索引: 为常用查询字段添加索引
缓存策略: 使用Redis缓存热点数据
异步处理: 耗时操作使用异步处理
连接池: 配置数据库连接池

📝 更新日志

v1.4.0 (2025-09-19)

✅ 飞书集成功能：支持飞书多维表格数据同步
✅ 页面功能合并：飞书同步页面合并到主仪表板
✅ 数据库架构优化：扩展工单表字段，支持飞书数据
✅ 代码重构优化：大文件拆分，降低运行风险
✅ 字段映射完善：智能映射飞书字段到本地数据库
✅ 数据库初始化改进：集成字段迁移到初始化流程
✅ AI准确率优化：AI准确率<90%时优先使用人工描述入库
✅ 语义相似度计算：使用sentence-transformers提升准确度

v1.3.0 (2025-09-17)

✅ 数据库架构优化：MySQL主数据库+SQLite备份系统
✅ 工单详情API修复：解决数据库会话管理问题
✅ 备份管理系统：自动备份MySQL数据到SQLite
✅ 数据库状态监控：实时监控MySQL和SQLite状态
✅ 备份管理API：支持数据备份和恢复操作

v1.2.0 (2025-09-16)

✅ 系统设置扩展：API管理、模型参数配置、端口管理
✅ 真实数据分析：修复性能趋势图表显示问题
✅ 工单AI建议功能：智能生成处理建议
✅ 知识库搜索优化：提升检索准确率
✅ Agent管理改进：工具使用统计和自定义工具

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

📞 支持与联系

项目地址: http://jeason.online:3000/zhaojie/assist
问题反馈: 请在Issues中提交问题
功能建议: 欢迎提交Feature Request

🙏 致谢

感谢所有为项目做出贡献的开发者和用户！

TSP智能助手 - 让车辆服务更智能，让客户体验更美好！ 🚗✨

15 KiB Raw Blame History Unescape Escape