ailine/QUICKSTART.md

# 快速开始指南 - 多模型切换功能

## 🚀 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 并附上日志信息

---

**祝您使用愉快！** 🎉