245 lines
4.8 KiB
Markdown
245 lines
4.8 KiB
Markdown
# AI助手Web客户端 - 后端集成指南
|
||
|
||
## 📋 概述
|
||
|
||
本Web客户端已成功对接im-api后端聊天服务，支持：
|
||
- ✅ 应用列表加载（支持搜索、按创建时间倒排）
|
||
- ✅ 应用选择
|
||
- ✅ SSE流式对话
|
||
- ✅ 推荐问题加载
|
||
- ✅ 完整的对话交互
|
||
|
||
## 🔧 配置说明
|
||
|
||
### 1. 环境变量配置
|
||
|
||
复制 `.env.example` 为 `.env` 并修改：
|
||
|
||
```bash
|
||
# im-api后端服务地址
|
||
IM_API_BASE_URL=http://localhost:8080
|
||
|
||
# 认证Token（可选，如果后端需要认证）
|
||
AUTH_TOKEN=your_jwt_token_here
|
||
|
||
# 服务端口
|
||
PORT=15000
|
||
```
|
||
|
||
### 2. 后端API要求
|
||
|
||
确保im-api后端服务已启动，并提供以下接口：
|
||
|
||
#### 2.1 获取应用列表
|
||
```
|
||
GET /api/ai-assistant/chatapp
|
||
```
|
||
|
||
响应格式：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"id": "app_id",
|
||
"appName": "应用名称",
|
||
"appDescription": "应用描述",
|
||
"appAvatar": "头像URL",
|
||
"category": "分类",
|
||
"sortNum": 1,
|
||
"enableRecommendation": true,
|
||
"conversationStarter": "欢迎语",
|
||
"reasoningEnable": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 2.2 获取推荐问题
|
||
```
|
||
GET /api/ai-assistant/chatapp/{appId}/getRecommendQuestion?pageSize=3¤t=1
|
||
```
|
||
|
||
响应格式：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"question": "推荐问题1"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.3 发送消息（SSE流式）
|
||
```
|
||
POST /api/ai-assistant/chat/completions/message
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求体：
|
||
```json
|
||
{
|
||
"chatId": "chat_id_or_null",
|
||
"appId": "app_id",
|
||
"equipment": "web",
|
||
"messageTag": "AI_TAG",
|
||
"body": {
|
||
"messages": [
|
||
{
|
||
"role": "user",
|
||
"content": "用户消息"
|
||
}
|
||
],
|
||
"channel": "web",
|
||
"attachmentIds": [],
|
||
"recommendQuestions": [],
|
||
"variables": {},
|
||
"reasoning": "false"
|
||
}
|
||
}
|
||
```
|
||
|
||
SSE响应格式：
|
||
```
|
||
event: MESSAGE_DETAIL
|
||
data: {
|
||
"detailId": "detail_id",
|
||
"chatId": "chat_id",
|
||
"question": {
|
||
"content": "用户问题",
|
||
"role": "user"
|
||
},
|
||
"answer": {
|
||
"content": "AI回答",
|
||
"role": "assistant"
|
||
},
|
||
"status": "PROCESSING|FINISH|ERROR"
|
||
}
|
||
```
|
||
|
||
## 🚀 启动步骤
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cd web_client
|
||
pip3 install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
```bash
|
||
# 复制配置文件
|
||
cp .env.example .env
|
||
|
||
# 编辑配置
|
||
vim .env
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
```bash
|
||
# 使用启动脚本
|
||
./start.sh
|
||
|
||
# 或直接运行
|
||
python3 app.py
|
||
```
|
||
|
||
### 4. 访问应用
|
||
|
||
打开浏览器访问：http://localhost:15000
|
||
|
||
## 📝 使用流程
|
||
|
||
1. **选择应用**
|
||
- 页面加载后自动显示应用列表
|
||
- 可以使用搜索框搜索应用
|
||
- 点击应用卡片进入对话
|
||
|
||
2. **开始对话**
|
||
- 进入对话界面后显示欢迎消息
|
||
- 如果应用启用了推荐问题，会显示快捷回复按钮
|
||
- 在输入框输入消息，按Enter或点击发送按钮
|
||
|
||
3. **查看回复**
|
||
- AI回复以流式方式实时显示
|
||
- 支持打字指示器动画
|
||
- 自动滚动到最新消息
|
||
|
||
4. **返回应用列表**
|
||
- 点击左上角返回按钮
|
||
- 可以切换到其他应用
|
||
|
||
## 🔍 故障排查
|
||
|
||
### 问题1：应用列表加载失败
|
||
|
||
**原因**：后端服务未启动或地址配置错误
|
||
|
||
**解决**：
|
||
1. 检查im-api服务是否启动
|
||
2. 检查 `.env` 中的 `IM_API_BASE_URL` 配置
|
||
3. 查看浏览器控制台和后端日志
|
||
|
||
### 问题2：消息发送失败
|
||
|
||
**原因**：认证失败或SSE连接问题
|
||
|
||
**解决**：
|
||
1. 检查是否需要配置 `AUTH_TOKEN`
|
||
2. 检查浏览器是否支持SSE
|
||
3. 查看网络请求详情
|
||
|
||
### 问题3：推荐问题不显示
|
||
|
||
**原因**：应用未启用推荐或后端接口返回空
|
||
|
||
**解决**：
|
||
1. 检查应用的 `enableRecommendation` 字段
|
||
2. 检查后端推荐问题接口是否正常
|
||
|
||
## 📊 技术架构
|
||
|
||
```
|
||
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||
│ 浏览器 │ ───> │ Flask代理层 │ ───> │ im-api后端 │
|
||
│ (前端UI) │ <─── │ (web_client)│ <─── │ (聊天服务) │
|
||
└─────────────┘ └──────────────┘ └─────────────┘
|
||
```
|
||
|
||
### 代理层功能
|
||
|
||
1. **请求转发**：将前端请求代理到im-api后端
|
||
2. **SSE流式转发**：支持Server-Sent Events流式响应
|
||
3. **错误处理**：统一的错误处理和日志记录
|
||
4. **CORS支持**：解决跨域问题
|
||
|
||
## 🎯 下一步优化
|
||
|
||
1. **认证集成**
|
||
- 集成真实的登录系统
|
||
- 从登录获取JWT token
|
||
- 支持token刷新
|
||
|
||
2. **功能增强**
|
||
- 支持文件上传
|
||
- 支持语音输入
|
||
- 支持多会话管理
|
||
- 支持历史记录
|
||
|
||
3. **性能优化**
|
||
- 添加请求缓存
|
||
- 优化SSE连接管理
|
||
- 添加重连机制
|
||
|
||
## 📞 联系方式
|
||
|
||
如有问题，请联系：huazm@glodon.com
|
||
|