实现前后端分离的agent

QUICKSTART.md

@@ -0,0 +1,245 @@
+# 快速开始指南 - 多模型切换功能
+
+## 🚀 5分钟快速启动
+
+### 步骤 1: 启动必要的容器
+
+```bash
+# 使用提供的启动脚本（推荐）
+./start.sh
+
+# 或者手动启动容器
+# 1. 启动 vLLM (如果需要本地模型)
+docker run -d --rm \
+    --group-add=video \
+    --cap-add=SYS_PTRACE \
+    --security-opt seccomp=unconfined \
+    --device=/dev/kfd \
+    --device=/dev/dri \
+    -v /home/huang/Study/AIModel/gemma-4-E2B-it:/models/gemma-4-E2B-it \
+    -e VLLM_ROCM_USE_AITER=0 \
+    -e HF_TOKEN="$HF_TOKEN" \
+    -p 8000:8000 \
+    --ipc=host \
+    --entrypoint vllm \
+    my-vllm-gemma4:working \
+    serve /models/gemma-4-E2B-it \
+    --served-model-name gemma-4-E2B-it \
+    --dtype auto \
+    --api-key token-abc123 \
+    --trust-remote-code \
+    --port 8000 \
+    --gpu-memory-utilization 0.85 \
+    --max-model-len 8192
+
+# 2. 启动 PostgreSQL
+docker run -d \
+  --name postgres-langgraph \
+  -e POSTGRES_PASSWORD=mysecretpassword \
+  -e POSTGRES_DB=langgraph_db \
+  -p 5432:5432 \
+  -v ~/docker_volumes/postgres_data:/var/lib/postgresql/data \
+  postgres:16
+```
+
+### 步骤 2: 配置环境变量
+
+编辑 `.env` 文件：
+
+```env
+ZHIPUAI_API_KEY=your_actual_zhipuai_api_key
+VLLM_LOCAL_KEY=token-abc123
+```
+
+### 步骤 3: 启动服务
+
+```bash
+# 方式1: 使用启动脚本（推荐）
+./start.sh
+
+# 方式2: 手动启动
+# 终端1: 启动后端
+python backend.py
+
+# 终端2: 启动前端
+streamlit run frontend.py
+```
+
+### 步骤 4: 访问应用
+
+浏览器打开: `http://localhost:8501`
+
+---
+
+## 🎯 使用多模型切换功能
+
+### 在前端切换模型
+
+1. **打开侧边栏**：点击左上角的菜单图标
+2. **选择模型**：在"选择大模型"下拉框中选择：
+   - 智谱 GLM-4.7-Flash（在线）
+   - 本地 vLLM（Gemma-4）
+3. **开始对话**：输入您的问题，系统会使用选定的模型处理
+
+### 特性说明
+
+✅ **实时切换**：可以在对话过程中随时切换模型  
+✅ **记忆共享**：同一会话 ID 下，不同模型共享对话历史  
+✅ **自动降级**：如果选择的模型不可用，自动切换到可用模型  
+✅ **状态显示**：每条回复下方会显示实际使用的模型  
+
+---
+
+## 🧪 测试功能
+
+### 运行自动化测试
+
+```bash
+# 确保后端正在运行
+python test_multi_model.py
+```
+
+测试内容包括：
+- 各模型的可用性测试
+- 跨模型会话记忆测试
+- API 响应格式验证
+
+### 手动测试
+
+1. **测试智谱模型**：
+   - 选择"智谱 GLM-4.7-Flash"
+   - 询问："你好，请介绍一下自己"
+   - 观察回复速度和内容质量
+
+2. **测试本地模型**：
+   - 选择"本地 vLLM（Gemma-4）"
+   - 询问相同问题
+   - 对比两个模型的回复差异
+
+3. **测试记忆功能**：
+   - 第一轮（智谱模型）："我叫小明，记住我的名字"
+   - 第二轮（本地模型）："我叫什么名字？"
+   - 验证是否能正确回忆
+
+---
+
+## 🔧 常见问题
+
+### Q1: 某个模型初始化失败怎么办？
+
+**A:** 系统会自动跳过失败的模型，使用其他可用模型。检查日志了解具体原因：
+- 智谱模型：确认 `ZHIPUAI_API_KEY` 是否正确
+- 本地模型：确认 vLLM 容器是否运行
+
+### Q2: 如何添加新模型？
+
+**A:** 在 `agent.py` 中添加：
+
+```python
+def _create_new_model_llm(self):
+    """创建新模型的 LLM"""
+    return YourChatModel(
+        model="model-name",
+        api_key="your-key",
+        # ... 其他参数
+    )
+
+# 在 initialize() 方法的 model_configs 中添加
+model_configs = {
+    "zhipu": self._create_zhipu_llm,
+    "local": self._create_local_llm,
+    "new_model": self._create_new_model_llm,  # 新增
+}
+```
+
+然后在前端 `frontend.py` 的 `MODEL_OPTIONS` 中添加对应选项。
+
+### Q3: 会话记忆是如何工作的？
+
+**A:** 
+- 使用 PostgreSQL 存储对话历史
+- 通过 `thread_id` 关联同一会话的消息
+- 不同模型共享同一个 checkpointer，因此可以跨模型保持上下文
+- 点击"新会话"按钮会生成新的 `thread_id`
+
+### Q4: 性能优化建议
+
+**A:**
+- 智谱模型：适合快速响应场景，无需本地 GPU
+- 本地模型：适合数据隐私要求高的场景，需要 GPU 支持
+- 长时间对话建议定期开启新会话，避免上下文过长
+
+---
+
+## 📊 架构优势
+
+### 预编译 Graph
+
+每个模型在启动时都会预编译独立的 LangGraph：
+- ✅ 避免每次请求都重新编译，提升性能
+- ✅ 各模型独立，互不影响
+- ✅ 支持热插拔，可动态添加/移除模型
+
+### 智能降级
+
+如果选择的模型不可用：
+1. 后端自动切换到第一个可用模型
+2. 返回响应中包含 `model_used` 字段
+3. 前端显示实际使用的模型
+4. 用户无感知，体验流畅
+
+### 统一接口
+
+无论使用哪个模型：
+- API 接口保持一致
+- 工具调用方式相同
+- 会话记忆机制统一
+- 前端操作体验一致
+
+---
+
+## 🎓 进阶使用
+
+### 固定会话 ID
+
+如需在不同浏览器或设备间继续同一会话：
+
+```python
+# 在 frontend.py 中修改
+st.session_state.thread_id = "my_fixed_session_id"
+```
+
+### 自定义超时时间
+
+```python
+# 在 frontend.py 中修改 timeout 参数
+response = requests.post(
+    API_URL,
+    json={...},
+    timeout=120  # 增加到 120 秒
+)
+```
+
+### 批量测试
+
+```python
+# 创建测试脚本
+import requests
+
+messages = ["问题1", "问题2", "问题3"]
+for msg in messages:
+    response = requests.post(API_URL, json={"message": msg, "model": "zhipu"})
+    print(response.json()["reply"])
+```
+
+---
+
+## 📞 获取帮助
+
+- 查看完整文档：[README.md](README.md)
+- 查看项目结构：参考 [README.md](README.md) 中的项目结构部分
+- 报告问题：提交 Issue 并附上日志信息
+
+---
+
+**祝您使用愉快！** 🎉