peanut/happy-life-star

Fork 0

Files

T

peanut a4e2542b23 聊天工具优化

2025-12-26 13:39:58 +08:00

4.8 KiB

Raw Blame History

AI助手Web客户端 - 后端集成指南

📋 概述

本Web客户端已成功对接im-api后端聊天服务，支持：

✅ 应用列表加载（支持搜索、按创建时间倒排）
✅ 应用选择
✅ SSE流式对话
✅ 推荐问题加载
✅ 完整的对话交互

🔧 配置说明

1. 环境变量配置

复制 .env.example 为 .env 并修改：

# 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

响应格式：

{
  "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&current=1

响应格式：

{
  "code": 200,
  "data": {
    "records": [
      {
        "question": "推荐问题1"
      }
    ]
  }
}

2.3 发送消息（SSE流式）

POST /api/ai-assistant/chat/completions/message
Content-Type: application/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. 安装依赖

cd web_client
pip3 install -r requirements.txt

2. 配置环境变量

# 复制配置文件
cp .env.example .env

# 编辑配置
vim .env

3. 启动服务

# 使用启动脚本
./start.sh

# 或直接运行
python3 app.py

4. 访问应用

打开浏览器访问：http://localhost:15000

📝 使用流程

选择应用
- 页面加载后自动显示应用列表
- 可以使用搜索框搜索应用
- 点击应用卡片进入对话
开始对话
- 进入对话界面后显示欢迎消息
- 如果应用启用了推荐问题，会显示快捷回复按钮
- 在输入框输入消息，按Enter或点击发送按钮
查看回复
- AI回复以流式方式实时显示
- 支持打字指示器动画
- 自动滚动到最新消息
返回应用列表
- 点击左上角返回按钮
- 可以切换到其他应用

🔍 故障排查

问题1：应用列表加载失败

原因：后端服务未启动或地址配置错误

解决：

检查im-api服务是否启动
检查 .env 中的 IM_API_BASE_URL 配置
查看浏览器控制台和后端日志

问题2：消息发送失败

原因：认证失败或SSE连接问题

解决：

检查是否需要配置 AUTH_TOKEN
检查浏览器是否支持SSE
查看网络请求详情

问题3：推荐问题不显示

原因：应用未启用推荐或后端接口返回空

解决：

检查应用的 enableRecommendation 字段
检查后端推荐问题接口是否正常

📊 技术架构

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   浏览器    │ ───> │ Flask代理层  │ ───> │  im-api后端 │
│  (前端UI)   │ <─── │  (web_client)│ <─── │  (聊天服务) │
└─────────────┘      └──────────────┘      └─────────────┘

代理层功能

请求转发：将前端请求代理到im-api后端
SSE流式转发：支持Server-Sent Events流式响应
错误处理：统一的错误处理和日志记录
CORS支持：解决跨域问题

🎯 下一步优化

认证集成
- 集成真实的登录系统
- 从登录获取JWT token
- 支持token刷新
功能增强
- 支持文件上传
- 支持语音输入
- 支持多会话管理
- 支持历史记录
性能优化
- 添加请求缓存
- 优化SSE连接管理
- 添加重连机制

📞 联系方式

如有问题，请联系：huazm@glodon.com

4.8 KiB Raw Blame History Unescape Escape