302 lines
9.3 KiB
Markdown
302 lines
9.3 KiB
Markdown
# 🎯 AI Agent 新功能说明
|
||
|
||
## 新增功能概览
|
||
|
||
本次更新实现了三大核心功能：**用户登录隔离**、**对话历史管理**、**流式实时响应**。
|
||
|
||
---
|
||
|
||
## 一、用户登录系统
|
||
|
||
### 功能特性
|
||
- ✅ **可选登录**：用户可以选择输入用户名或直接使用默认用户
|
||
- ✅ **对话隔离**：不同用户的对话历史完全隔离，避免污染
|
||
- ✅ **默认用户**：未登录时使用 `default_user`，所有未登录用户共享对话
|
||
|
||
### 使用方式
|
||
1. 启动前端后，左侧栏显示登录界面
|
||
2. 输入用户名（可选），点击"进入"
|
||
3. 如需切换用户，点击"切换用户"按钮
|
||
|
||
### 技术实现
|
||
- 前端：`st.session_state.user_id` 和 `st.session_state.logged_in` 管理登录状态
|
||
- 后端：所有 API 请求携带 `user_id` 参数，用于数据隔离
|
||
- 数据库：LangGraph checkpoint 的 `metadata` 字段存储 `user_id`
|
||
|
||
---
|
||
|
||
## 二、对话历史管理
|
||
|
||
### 功能特性
|
||
- ✅ **历史列表**：左侧栏显示用户的所有对话历史
|
||
- ✅ **摘要展示**：每个历史对话显示摘要（第一条消息或生成的 summary）
|
||
- ✅ **一键加载**：点击历史对话，自动加载完整消息历史
|
||
- ✅ **新对话**：点击"新对话"按钮创建全新对话线程
|
||
- ✅ **实时更新**：每次对话结束后自动刷新历史列表
|
||
|
||
### 使用方式
|
||
1. 点击"刷新列表"按钮加载历史对话
|
||
2. 点击任意历史对话，自动加载完整消息历史
|
||
3. 点击"新对话"开始全新话题
|
||
|
||
### 技术实现
|
||
|
||
#### 后端新增接口
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/threads` | GET | 获取用户的对话历史列表 |
|
||
| `/thread/{thread_id}/messages` | GET | 获取指定线程的完整消息历史 |
|
||
| `/thread/{thread_id}/summary` | GET | 获取指定线程的摘要信息 |
|
||
|
||
#### 新增模块
|
||
- `app/history.py`: `ThreadHistoryService` 类，封装历史查询逻辑
|
||
- 直接查询 LangGraph 的 `checkpoints` 表，通过 `metadata->>'user_id'` 过滤
|
||
|
||
#### 前端实现
|
||
- 左侧栏显示历史列表，每个对话显示摘要、时间和消息数量
|
||
- 当前选中的对话高亮显示（primary 按钮样式）
|
||
- 点击历史对话调用 `/thread/{thread_id}/messages` 加载完整历史
|
||
|
||
---
|
||
|
||
## 三、流式实时响应
|
||
|
||
### 功能特性
|
||
- ✅ **逐字输出**：AI 回复实时逐字显示，提升用户体验
|
||
- ✅ **工具调用状态**：显示工具调用的开始和完成状态
|
||
- ✅ **Token 统计**：对话结束后显示消耗的 token 数量和耗时
|
||
- ✅ **错误处理**：流式响应异常时友好提示用户
|
||
|
||
### 使用方式
|
||
- 在输入框输入问题后，AI 回复会逐字显示，无需等待完整响应
|
||
- 如果 AI 调用工具，会显示"🔧 调用工具: xxx..."的提示
|
||
- 工具调用完成后显示"✅ 工具 xxx 完成"
|
||
- 回复完成后显示 token 消耗和耗时统计
|
||
|
||
### 技术实现
|
||
|
||
#### 后端流式接口
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/chat/stream` | POST | 流式对话接口（SSE） |
|
||
|
||
#### SSE 事件类型
|
||
```json
|
||
{
|
||
"type": "token", // AI 逐字输出
|
||
"content": "你好"
|
||
}
|
||
|
||
{
|
||
"type": "tool_start", // 工具调用开始
|
||
"tool": "search_calendar"
|
||
}
|
||
|
||
{
|
||
"type": "tool_end", // 工具调用完成
|
||
"tool": "search_calendar"
|
||
}
|
||
|
||
{
|
||
"type": "done", // 对话完成
|
||
"reply": "完整回复内容",
|
||
"token_usage": {"total_tokens": 123},
|
||
"elapsed_time": 2.5
|
||
}
|
||
|
||
{
|
||
"type": "error", // 错误信息
|
||
"message": "错误详情"
|
||
}
|
||
```
|
||
|
||
#### Agent 流式处理
|
||
- `AIAgentService.process_message_stream()` 方法
|
||
- 使用 LangGraph 的 `astream_events()` API 获取流式事件
|
||
- 支持所有模型（zhipu, deepseek, local）
|
||
|
||
#### 前端流式消费
|
||
- 使用 `requests.post(..., stream=True)` 消费 SSE 流
|
||
- 逐行解析 `data: {...}` 格式的事件
|
||
- 实时更新 UI 显示 token 和工具状态
|
||
|
||
---
|
||
|
||
## 四、三栏布局设计
|
||
|
||
### 布局结构
|
||
```
|
||
┌──────────────┬──────────────────────────┬──────────────┐
|
||
│ 左侧栏 (1) │ 中间栏 (3) │ 右侧栏 (1) │
|
||
│ │ │ │
|
||
│ 👤 用户 │ 🤖 AI 个人助手 │ 📊 会话信息 │
|
||
│ [登录] │ │ │
|
||
│ │ [模型选择器] │ 当前对话 │
|
||
│ 📚 历史 │ ┌────────────────────┐ │ xxx... │
|
||
│ [刷新] │ │ │ │ │
|
||
│ [新对话] │ │ 聊天消息区域 │ │ 消息统计 │
|
||
│ │ │ │ │ 用户: 5 │
|
||
│ 💬 对话1 │ └────────────────────┘ │ AI: 4 │
|
||
│ 💬 对话2 │ │ │
|
||
│ 💬 对话3 │ [输入框] │ 💡 使用提示 │
|
||
│ │ │ │
|
||
└──────────────┴──────────────────────────┴──────────────┘
|
||
```
|
||
|
||
### 各栏功能
|
||
|
||
#### 左侧栏（宽度 1/5）
|
||
- **用户登录**：输入用户名，切换用户
|
||
- **历史列表**：刷新、点击加载、新对话按钮
|
||
|
||
#### 中间栏（宽度 3/5）
|
||
- **模型选择**：下拉框选择 AI 模型
|
||
- **聊天区域**：显示消息历史，支持流式输出
|
||
- **输入框**：输入用户问题
|
||
|
||
#### 右侧栏（宽度 1/5）
|
||
- **会话信息**：显示当前线程 ID
|
||
- **消息统计**：用户消息和 AI 回复数量
|
||
- **使用提示**：功能说明
|
||
|
||
---
|
||
|
||
## 五、配置说明
|
||
|
||
### 环境变量
|
||
|
||
#### 本地开发（.env）
|
||
```bash
|
||
# API 地址（注意：不需要 /chat 后缀）
|
||
API_URL=http://localhost:8083
|
||
|
||
# 日志调试配置（本地开发推荐 DEBUG）
|
||
LOG_LEVEL=DEBUG
|
||
DEBUG=true
|
||
ENABLE_GRAPH_TRACE=true
|
||
```
|
||
|
||
#### Docker 部署（.env.docker）
|
||
```bash
|
||
# API 地址（Docker 内部网络）
|
||
API_URL=http://backend:8083
|
||
|
||
# 日志调试配置（生产环境推荐 WARNING）
|
||
LOG_LEVEL=WARNING
|
||
DEBUG=false
|
||
ENABLE_GRAPH_TRACE=false
|
||
```
|
||
|
||
### 端口分配
|
||
|
||
| 服务 | 端口 | 说明 |
|
||
|------|------|------|
|
||
| llama.cpp LLM | 8081 | Gemma-4-E2B GGUF 模型 |
|
||
| llama.cpp Embedding | 8082 | embeddinggemma-300M GGUF 模型 |
|
||
| Backend (FastAPI) | 8083 | AI Agent 后端服务 |
|
||
| Frontend (Streamlit) | 8501 | Web 界面 |
|
||
|
||
---
|
||
|
||
## 六、文件变更清单
|
||
|
||
### 新增文件
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `app/history.py` | 历史查询服务 `ThreadHistoryService` |
|
||
|
||
### 修改文件
|
||
| 文件 | 修改内容 |
|
||
|------|---------|
|
||
| `app/agent.py` | • 添加 `process_message_stream()` 流式处理方法<br>• `process_message()` 写入 `metadata` 支持历史查询 |
|
||
| `app/backend.py` | • 添加 `/threads`、`/thread/{id}/messages`、`/thread/{id}/summary` 接口<br>• 添加 `/chat/stream` 流式接口<br>• 注入 `history_service` |
|
||
| `frontend/frontend.py` | • 完全重写为三栏布局<br>• 实现用户登录和历史管理<br>• 支持流式响应消费 |
|
||
| `.env`, `.env.docker`, `.env.example` | • 移除 `API_URL` 中的 `/chat` 后缀 |
|
||
|
||
---
|
||
|
||
## 七、使用示例
|
||
|
||
### 1. 本地开发启动
|
||
```bash
|
||
# 启动后端和前端
|
||
./scripts/start.sh both
|
||
|
||
# 访问前端
|
||
open http://localhost:8501
|
||
```
|
||
|
||
### 2. Docker 部署
|
||
```bash
|
||
# 配置环境变量
|
||
cp .env.docker .env
|
||
# 编辑 .env 填入 API Key
|
||
|
||
# 启动服务
|
||
cd docker
|
||
docker compose up -d
|
||
```
|
||
|
||
### 3. API 测试
|
||
```bash
|
||
# 获取历史列表
|
||
curl "http://localhost:8083/threads?user_id=test_user"
|
||
|
||
# 获取线程消息
|
||
curl "http://localhost:8083/thread/{thread_id}/messages?user_id=test_user"
|
||
|
||
# 流式对话
|
||
curl -X POST "http://localhost:8083/chat/stream" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"message": "你好",
|
||
"thread_id": "test-thread",
|
||
"model": "zhipu",
|
||
"user_id": "test_user"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 八、注意事项
|
||
|
||
### 1. 数据库查询性能
|
||
- 当前直接查询 `checkpoints` 表的 JSONB `metadata` 字段
|
||
- 如果用户对话数量很大，建议在 `checkpoints` 表上创建 GIN 索引：
|
||
```sql
|
||
CREATE INDEX idx_checkpoints_metadata_user_id
|
||
ON checkpoints USING GIN ((metadata->>'user_id'));
|
||
```
|
||
|
||
### 2. 流式响应缓冲
|
||
- 如果使用 Nginx 反向代理，需要关闭缓冲：
|
||
```nginx
|
||
location /chat/stream {
|
||
proxy_pass http://backend:8083;
|
||
proxy_buffering off;
|
||
proxy_cache off;
|
||
}
|
||
```
|
||
|
||
### 3. 历史列表分页
|
||
- 当前默认返回 50 条历史记录
|
||
- 如需支持更多历史，可在 `/threads` 接口添加 `offset` 参数实现分页
|
||
|
||
### 4. 用户认证增强
|
||
- 当前用户登录仅为前端输入，无密码验证
|
||
- 如需加强安全性，可集成 OAuth2 或 JWT 认证
|
||
|
||
---
|
||
|
||
## 九、下一步优化建议
|
||
|
||
1. **对话摘要生成**：在 `summarize` 节点中生成对话摘要，存入 checkpoint metadata
|
||
2. **历史记录搜索**：添加关键词搜索功能，快速定位历史对话
|
||
3. **对话导出**：支持导出对话历史为 Markdown 或 JSON 格式
|
||
4. **多设备同步**：同一用户的不同设备共享对话历史
|
||
5. **对话标签**：支持为对话添加标签和分类
|
||
6. **收藏功能**：支持收藏重要对话，方便快速访问
|
||
|
||
---
|
||
|
||
**🎉 新功能已全部实现并测试通过！** |