246 lines
5.6 KiB
Markdown
246 lines
5.6 KiB
Markdown
# 快速开始指南 - 多模型切换功能
|
||
|
||
## 🚀 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 并附上日志信息
|
||
|
||
---
|
||
|
||
**祝您使用愉快！** 🎉
|