docs(.gitignore/README/QUICKSTART): 更新文档和忽略配置 - 添加IDE配置、日志和数据文件到.gitignore - 重构QUICKSTART.md，提供Docker Compose和本地开发两种部署方式 - 更新README.md，优化项目介绍和架构说明 - 移除旧的agent.py和backend.py文件 ```
This commit is contained in:
434
QUICKSTART.md
434
QUICKSTART.md
@@ -1,38 +1,65 @@
|
||||
# 快速开始指南 - 多模型切换功能
|
||||
# 快速开始指南
|
||||
|
||||
## 🚀 5分钟快速启动
|
||||
详细的启动和部署指南，面向开发者和运维人员。
|
||||
|
||||
### 步骤 1: 启动必要的容器
|
||||
---
|
||||
|
||||
## 🚀 快速启动（3 步）
|
||||
|
||||
### 方式一：Docker Compose（推荐 ⭐）
|
||||
|
||||
适合生产环境，一键启动所有服务。
|
||||
|
||||
#### 1. 配置环境变量
|
||||
|
||||
```bash
|
||||
# 使用提供的启动脚本（推荐）
|
||||
./start.sh
|
||||
cat > .env << EOF
|
||||
ZHIPUAI_API_KEY=your_zhipuai_api_key_here
|
||||
VLLM_LOCAL_KEY=token-abc123
|
||||
EOF
|
||||
```
|
||||
|
||||
# 或者手动启动容器
|
||||
# 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. 启动服务
|
||||
|
||||
# 2. 启动 PostgreSQL
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
#### 3. 访问应用
|
||||
|
||||
- **前端**: http://localhost:8501
|
||||
- **后端 API**: http://localhost:8001
|
||||
|
||||
#### 常用命令
|
||||
|
||||
```bash
|
||||
# 查看服务状态
|
||||
docker compose ps
|
||||
|
||||
# 查看日志
|
||||
docker compose logs -f
|
||||
|
||||
# 重启特定服务
|
||||
docker compose restart backend
|
||||
|
||||
# 停止所有服务
|
||||
docker compose down
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 方式二：本地开发模式
|
||||
|
||||
适合开发和调试。
|
||||
|
||||
#### 前置要求
|
||||
|
||||
- Python 3.10+
|
||||
- Docker（用于 PostgreSQL）
|
||||
|
||||
#### 1. 启动 PostgreSQL
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name postgres-langgraph \
|
||||
-e POSTGRES_PASSWORD=mysecretpassword \
|
||||
@@ -42,109 +69,126 @@ docker run -d \
|
||||
postgres:16
|
||||
```
|
||||
|
||||
### 步骤 2: 配置环境变量
|
||||
#### 2. 安装依赖
|
||||
|
||||
```bash
|
||||
pip install -r requirement.txt
|
||||
```
|
||||
|
||||
#### 3. 配置环境变量
|
||||
|
||||
编辑 `.env` 文件：
|
||||
|
||||
```env
|
||||
ZHIPUAI_API_KEY=your_actual_zhipuai_api_key
|
||||
VLLM_LOCAL_KEY=token-abc123
|
||||
ZHIPUAI_API_KEY=your_api_key_here
|
||||
```
|
||||
|
||||
### 步骤 3: 启动服务
|
||||
#### 4. 启动服务
|
||||
|
||||
**终端 1 - 后端：**
|
||||
```bash
|
||||
# 方式1: 使用启动脚本（推荐）
|
||||
./start.sh
|
||||
|
||||
# 方式2: 手动启动
|
||||
# 终端1: 启动后端
|
||||
python backend.py
|
||||
```
|
||||
|
||||
# 终端2: 启动前端
|
||||
**终端 2 - 前端：**
|
||||
```bash
|
||||
streamlit run frontend.py
|
||||
```
|
||||
|
||||
### 步骤 4: 访问应用
|
||||
|
||||
浏览器打开: `http://localhost:8501`
|
||||
浏览器自动打开 http://localhost:8501
|
||||
|
||||
---
|
||||
|
||||
## 🎯 使用多模型切换功能
|
||||
## 🐳 Docker 部署详解
|
||||
|
||||
### 在前端切换模型
|
||||
### 文件说明
|
||||
|
||||
1. **打开侧边栏**：点击左上角的菜单图标
|
||||
2. **选择模型**：在"选择大模型"下拉框中选择：
|
||||
- 智谱 GLM-4.7-Flash（在线）
|
||||
- 本地 vLLM（Gemma-4）
|
||||
3. **开始对话**：输入您的问题，系统会使用选定的模型处理
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `docker-compose.yml` | 服务编排配置 |
|
||||
| `Dockerfile.backend` | 后端镜像构建 |
|
||||
| `Dockerfile.frontend` | 前端镜像构建 |
|
||||
| `.gitea/workflows/deploy.yml` | CI/CD 自动化部署 |
|
||||
|
||||
### 特性说明
|
||||
### docker-compose.yml 结构
|
||||
|
||||
✅ **实时切换**：可以在对话过程中随时切换模型
|
||||
✅ **记忆共享**：同一会话 ID 下，不同模型共享对话历史
|
||||
✅ **自动降级**：如果选择的模型不可用，自动切换到可用模型
|
||||
✅ **状态显示**：每条回复下方会显示实际使用的模型
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试功能
|
||||
|
||||
### 运行自动化测试
|
||||
|
||||
```bash
|
||||
# 确保后端正在运行
|
||||
python test_multi_model.py
|
||||
```yaml
|
||||
services:
|
||||
postgres: # PostgreSQL 数据库
|
||||
backend: # FastAPI 后端服务
|
||||
frontend: # Streamlit 前端界面
|
||||
```
|
||||
|
||||
测试内容包括：
|
||||
- 各模型的可用性测试
|
||||
- 跨模型会话记忆测试
|
||||
- API 响应格式验证
|
||||
**特性：**
|
||||
- ✅ PostgreSQL 健康检查，确保数据库就绪后才启动后端
|
||||
- ✅ 数据持久化到 Docker volume
|
||||
- ✅ 自动重启策略（`restart: unless-stopped`）
|
||||
- ✅ 内部网络隔离，外部无法直接访问数据库
|
||||
|
||||
### 手动测试
|
||||
### 只更新特定服务
|
||||
|
||||
1. **测试智谱模型**：
|
||||
- 选择"智谱 GLM-4.7-Flash"
|
||||
- 询问："你好，请介绍一下自己"
|
||||
- 观察回复速度和内容质量
|
||||
```bash
|
||||
# 只重新构建后端（不影响数据库）
|
||||
docker compose up -d --build backend
|
||||
|
||||
2. **测试本地模型**：
|
||||
- 选择"本地 vLLM（Gemma-4）"
|
||||
- 询问相同问题
|
||||
- 对比两个模型的回复差异
|
||||
# 只重新启动前端
|
||||
docker compose up -d frontend
|
||||
```
|
||||
|
||||
3. **测试记忆功能**：
|
||||
- 第一轮（智谱模型）："我叫小明，记住我的名字"
|
||||
- 第二轮（本地模型）："我叫什么名字？"
|
||||
- 验证是否能正确回忆
|
||||
### 数据持久化
|
||||
|
||||
PostgreSQL 数据存储在命名 volume `pg_data` 中：
|
||||
|
||||
```bash
|
||||
# 查看 volume
|
||||
docker volume ls | grep pg_data
|
||||
|
||||
# 备份数据
|
||||
docker run --rm -v pg_data:/data -v $(pwd):/backup alpine tar czf /backup/pg_backup.tar.gz /data
|
||||
|
||||
# 恢复数据
|
||||
docker run --rm -v pg_data:/data -v $(pwd):/backup alpine tar xzf /backup/pg_backup.tar.gz -C /
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 常见问题
|
||||
## 🔧 开发指南
|
||||
|
||||
### Q1: 某个模型初始化失败怎么办？
|
||||
### 添加新工具
|
||||
|
||||
**A:** 系统会自动跳过失败的模型，使用其他可用模型。检查日志了解具体原因：
|
||||
- 智谱模型：确认 `ZHIPUAI_API_KEY` 是否正确
|
||||
- 本地模型：确认 vLLM 容器是否运行
|
||||
在 `tools.py` 中添加：
|
||||
|
||||
### Q2: 如何添加新模型？
|
||||
```python
|
||||
@tool
|
||||
def my_new_tool(param: str) -> str:
|
||||
"""
|
||||
工具描述（会显示给 LLM）
|
||||
|
||||
Args:
|
||||
param: 参数说明
|
||||
|
||||
Returns:
|
||||
返回值说明
|
||||
"""
|
||||
# 实现逻辑
|
||||
return result
|
||||
```
|
||||
|
||||
**A:** 在 `agent.py` 中添加：
|
||||
工具会自动注册，无需修改其他文件。
|
||||
|
||||
### 添加新模型
|
||||
|
||||
在 `agent.py` 中：
|
||||
|
||||
```python
|
||||
def _create_new_model_llm(self):
|
||||
"""创建新模型的 LLM"""
|
||||
return YourChatModel(
|
||||
model="model-name",
|
||||
api_key="your-key",
|
||||
# ... 其他参数
|
||||
api_key=os.getenv("YOUR_API_KEY"),
|
||||
)
|
||||
|
||||
# 在 initialize() 方法的 model_configs 中添加
|
||||
# 在 initialize() 方法中注册
|
||||
model_configs = {
|
||||
"zhipu": self._create_zhipu_llm,
|
||||
"local": self._create_local_llm,
|
||||
@@ -152,94 +196,190 @@ model_configs = {
|
||||
}
|
||||
```
|
||||
|
||||
然后在前端 `frontend.py` 的 `MODEL_OPTIONS` 中添加对应选项。
|
||||
在前端 `frontend.py` 中添加选项：
|
||||
|
||||
### Q3: 会话记忆是如何工作的？
|
||||
```python
|
||||
MODEL_OPTIONS = {
|
||||
"智谱 GLM-4": "zhipu",
|
||||
"本地 Gemma-4": "local",
|
||||
"新模型": "new_model", # 新增
|
||||
}
|
||||
```
|
||||
|
||||
**A:**
|
||||
- 使用 PostgreSQL 存储对话历史
|
||||
- 通过 `thread_id` 关联同一会话的消息
|
||||
- 不同模型共享同一个 checkpointer，因此可以跨模型保持上下文
|
||||
- 点击"新会话"按钮会生成新的 `thread_id`
|
||||
### 调试技巧
|
||||
|
||||
### Q4: 性能优化建议
|
||||
```bash
|
||||
# 进入后端容器
|
||||
docker compose exec backend bash
|
||||
|
||||
**A:**
|
||||
- 智谱模型：适合快速响应场景，无需本地 GPU
|
||||
- 本地模型：适合数据隐私要求高的场景，需要 GPU 支持
|
||||
- 长时间对话建议定期开启新会话，避免上下文过长
|
||||
# 查看实时日志
|
||||
docker compose logs -f backend
|
||||
|
||||
# 检查数据库连接
|
||||
docker compose exec postgres psql -U postgres -d langgraph_db -c "\dt"
|
||||
|
||||
# 测试后端 API
|
||||
curl http://localhost:8001/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 架构优势
|
||||
## 🔄 CI/CD 自动化部署
|
||||
|
||||
### 预编译 Graph
|
||||
### Gitea Workflows
|
||||
|
||||
每个模型在启动时都会预编译独立的 LangGraph：
|
||||
- ✅ 避免每次请求都重新编译，提升性能
|
||||
- ✅ 各模型独立，互不影响
|
||||
- ✅ 支持热插拔，可动态添加/移除模型
|
||||
项目包含自动化部署配置 `.gitea/workflows/deploy.yml`。
|
||||
|
||||
### 智能降级
|
||||
**触发条件：**
|
||||
- 推送到 `main` 或 `master` 分支
|
||||
- 手动触发（workflow_dispatch）
|
||||
|
||||
如果选择的模型不可用：
|
||||
1. 后端自动切换到第一个可用模型
|
||||
2. 返回响应中包含 `model_used` 字段
|
||||
3. 前端显示实际使用的模型
|
||||
4. 用户无感知，体验流畅
|
||||
**部署流程：**
|
||||
1. 检出代码
|
||||
2. 安装 Python 依赖（验证用）
|
||||
3. 准备环境变量
|
||||
4. 重新构建并启动前后端（不影响数据库）
|
||||
5. 健康检查（等待后端就绪）
|
||||
6. 清理无用 Docker 资源
|
||||
|
||||
### 统一接口
|
||||
**配置 Secrets：**
|
||||
|
||||
无论使用哪个模型：
|
||||
- API 接口保持一致
|
||||
- 工具调用方式相同
|
||||
- 会话记忆机制统一
|
||||
- 前端操作体验一致
|
||||
在 Gitea 仓库设置中添加：
|
||||
- `ZHIPUAI_API_KEY`
|
||||
- `VLLM_LOCAL_KEY`
|
||||
|
||||
---
|
||||
|
||||
## 🎓 进阶使用
|
||||
## 🐛 故障排查
|
||||
|
||||
### 固定会话 ID
|
||||
### 常见问题
|
||||
|
||||
如需在不同浏览器或设备间继续同一会话：
|
||||
#### 1. PostgreSQL 连接失败
|
||||
|
||||
```python
|
||||
# 在 frontend.py 中修改
|
||||
st.session_state.thread_id = "my_fixed_session_id"
|
||||
```bash
|
||||
# 检查容器状态
|
||||
docker compose ps postgres
|
||||
|
||||
# 查看日志
|
||||
docker compose logs postgres
|
||||
|
||||
# 测试连接
|
||||
docker compose exec postgres pg_isready -U postgres
|
||||
```
|
||||
|
||||
### 自定义超时时间
|
||||
**解决方案：**
|
||||
- 确认容器正在运行
|
||||
- 检查密码是否正确
|
||||
- 等待健康检查通过（约 10-30 秒）
|
||||
|
||||
```python
|
||||
# 在 frontend.py 中修改 timeout 参数
|
||||
response = requests.post(
|
||||
API_URL,
|
||||
json={...},
|
||||
timeout=120 # 增加到 120 秒
|
||||
)
|
||||
#### 2. 后端启动失败
|
||||
|
||||
```bash
|
||||
# 查看详细日志
|
||||
docker compose logs backend
|
||||
|
||||
# 检查端口占用
|
||||
lsof -i :8001
|
||||
```
|
||||
|
||||
### 批量测试
|
||||
**常见原因：**
|
||||
- API Key 未配置或错误
|
||||
- 端口 8001 被占用
|
||||
- 依赖包缺失
|
||||
|
||||
```python
|
||||
# 创建测试脚本
|
||||
import requests
|
||||
#### 3. 前端无法连接后端
|
||||
|
||||
messages = ["问题1", "问题2", "问题3"]
|
||||
for msg in messages:
|
||||
response = requests.post(API_URL, json={"message": msg, "model": "zhipu"})
|
||||
print(response.json()["reply"])
|
||||
```bash
|
||||
# 检查后端是否正常运行
|
||||
curl http://localhost:8001/
|
||||
|
||||
# 检查网络连接
|
||||
docker compose exec frontend ping backend
|
||||
```
|
||||
|
||||
**解决方案：**
|
||||
- 确认后端服务已启动
|
||||
- 检查防火墙设置
|
||||
- 重启前端服务
|
||||
|
||||
#### 4. 模型初始化失败
|
||||
|
||||
```bash
|
||||
# 查看后端启动日志
|
||||
docker compose logs backend | grep -i "model\|error"
|
||||
```
|
||||
|
||||
**可能原因：**
|
||||
- 智谱 API Key 无效
|
||||
- vLLM 容器未启动（如使用本地模型）
|
||||
- 网络连接问题
|
||||
|
||||
---
|
||||
|
||||
## 📊 监控和维护
|
||||
|
||||
### 查看资源使用
|
||||
|
||||
```bash
|
||||
# Docker 容器资源使用
|
||||
docker stats
|
||||
|
||||
# 磁盘空间
|
||||
docker system df
|
||||
|
||||
# 清理无用资源
|
||||
docker system prune -f
|
||||
```
|
||||
|
||||
### 日志管理
|
||||
|
||||
```bash
|
||||
# 查看所有服务日志
|
||||
docker compose logs
|
||||
|
||||
# 查看特定服务最近 100 行日志
|
||||
docker compose logs --tail=100 backend
|
||||
|
||||
# 实时跟踪日志
|
||||
docker compose logs -f backend frontend
|
||||
```
|
||||
|
||||
### 备份和恢复
|
||||
|
||||
```bash
|
||||
# 备份数据库
|
||||
docker compose exec postgres pg_dump -U postgres langgraph_db > backup.sql
|
||||
|
||||
# 恢复数据库
|
||||
cat backup.sql | docker compose exec -T postgres psql -U postgres langgraph_db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 性能优化建议
|
||||
|
||||
### 开发环境
|
||||
|
||||
- 使用 `docker compose watch` 实现热重载（需配置）
|
||||
- 挂载代码目录而非复制到镜像
|
||||
- 启用 Python 调试模式
|
||||
|
||||
### 生产环境
|
||||
|
||||
- 使用反向代理（Nginx）
|
||||
- 启用 HTTPS
|
||||
- 配置日志轮转
|
||||
- 设置资源限制（CPU、内存）
|
||||
- 定期备份数据库
|
||||
|
||||
---
|
||||
|
||||
## 📞 获取帮助
|
||||
|
||||
- 查看完整文档：[README.md](README.md)
|
||||
- 查看项目结构：参考 [README.md](README.md) 中的项目结构部分
|
||||
- 报告问题：提交 Issue 并附上日志信息
|
||||
- **完整文档**: [README.md](README.md)
|
||||
- **RAG 示例**: `rag_example.py`
|
||||
- **报告问题**: 提交 Issue 并附上日志
|
||||
|
||||
---
|
||||
|
||||
**祝您使用愉快！** 🎉
|
||||
**祝您部署顺利！** 🎉
|
||||
|
||||
Reference in New Issue
Block a user