采用向量数据库实现长期记忆

2026-04-15 23:52:13 +08:00
parent de68916c5a
commit a92a220ff3
24 changed files with 1237 additions and 713 deletions
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -22,11 +22,13 @@ vim .env  # 或使用你喜欢的编辑器

 **必需配置项**：
 - `ZHIPUAI_API_KEY` - 智谱 AI API 密钥（从 [智谱开放平台](https://open.bigmodel.cn/) 获取）
- `VLLM_LOCAL_KEY` - 本地 vLLM 服务认证 Token（与 vLLM 容器的 `--api-key` 参数一致）
+- `LLAMACPP_API_KEY` - llama.cpp 服务认证 Token（与容器启动参数一致，默认 `token-abc123`）

 **可选配置项**：
- `VLLM_BASE_URL` - vLLM 服务地址（默认已配置为 FRP 穿透地址）
- `DB_URI` - PostgreSQL 连接字符串（默认已配置，使用 Docker 服务名 `postgres`）
+- `VLLM_BASE_URL` - LLM 服务地址（默认已配置为 `http://localhost:8081/v1`）
+- `VLLM_EMBEDDING_URL` - Embedding 服务地址（默认已配置为 `http://localhost:8082/v1`）
+- `DB_URI` - PostgreSQL 连接字符串（默认已配置，使用远程服务器地址）
+- `QDRANT_URL` - Qdrant 向量数据库地址（默认已配置，使用远程服务器地址）

 **注意**：Docker Compose 部署时，`API_URL` 由 `docker-compose.yml` 自动注入，无需在 `.env` 中配置。

@@ -70,60 +72,51 @@ docker compose down
 #### 前置要求

 - Python 3.10+
- Docker（用于 PostgreSQL）

-#### 1. 启动 PostgreSQL
-
-```bash
-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. 安装依赖
+#### 1. 安装依赖

 ```bash
 pip install -r requirement.txt
 ```

-#### 3. 配置环境变量
+#### 2. 配置环境变量

 复制并编辑 `.env` 文件：

 ```
-# 基于 Docker 模板创建，然后修改为本地配置
+# 基于 Docker 模板创建
 cp .env.docker .env
 vim .env
 ```

 **本地开发需要修改以下配置**：

-```env
+``env
 ZHIPUAI_API_KEY=your_api_key_here
-VLLM_LOCAL_KEY=token-abc123
+LLAMACPP_API_KEY=token-abc123

-# 本地开发时，vLLM 和数据库都在 localhost
-VLLM_BASE_URL=http://localhost:8000/v1
-DB_URI=postgresql://postgres:mysecretpassword@localhost:5432/langgraph_db?sslmode=disable
+# 本地开发时，llama.cpp 服务在 localhost
+VLLM_BASE_URL=http://localhost:8081/v1
+VLLM_EMBEDDING_URL=http://localhost:8082/v1
+
+# 数据库和向量存储使用远程服务器
+DB_URI=postgresql://postgres:mysecretpassword@115.190.121.151:5432/langgraph_db?sslmode=disable
+QDRANT_URL=http://115.190.121.151:6333

 # 本地开发时，后端也在 localhost
-API_URL=http://localhost:8001/chat
+API_URL=http://localhost:8003/chat
 ```

-#### 4. 启动服务
+#### 3. 启动服务

 **终端 1 - 后端：**
 ```bash
-python backend.py
+python app/backend.py
 ```

 **终端 2 - 前端：**
 ```bash
-streamlit run frontend.py
+cd frontend && streamlit run app.py
 ```

 浏览器自动打开前端页面（如果配置了 Nginx，访问 `http://your-domain.com`；否则访问 http://localhost:8501）
@@ -136,7 +129,7 @@ streamlit run frontend.py

 | 文件 | 用途 |
 |------|------|
-| `docker-compose.yml` | 服务编排配置 |
+| `docker-compose.yml` | 服务编排配置（仅包含 backend 和 frontend） |
 | `Dockerfile.backend` | 后端镜像构建 |
 | `Dockerfile.frontend` | 前端镜像构建 |
 | `.gitea/workflows/deploy.yml` | CI/CD 自动化部署 |
@@ -145,49 +138,32 @@ streamlit run frontend.py

 ```yaml
 services:
-  postgres:     # PostgreSQL 数据库
-  backend:      # FastAPI 后端服务
+  backend:      # FastAPI 后端服务（连接远程 PostgreSQL 和 Qdrant）
  frontend:     # Streamlit 前端界面
 ```

 **特性：**
- ✅ PostgreSQL 健康检查，确保数据库就绪后才启动后端
- ✅ 数据持久化到 Docker volume
+- ✅ 通过环境变量连接远程 PostgreSQL 和 Qdrant
 - ✅ 自动重启策略（`restart: unless-stopped`）
- ✅ 内部网络隔离，外部无法直接访问数据库
+- ✅ 内部网络隔离

 ### 只更新特定服务

 ```bash
-# 只重新构建后端（不影响数据库）
+# 只重新构建后端
 docker compose up -d --build backend

 # 只重新启动前端
 docker compose up -d frontend
 ```

-### 数据持久化
-
-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 /
-```
-
 ---

 ## 🔧 开发指南

 ### 添加新工具

-在 `tools.py` 中添加：
+在 `app/tools.py` 中添加：

 ```python
@tool
@@ -209,7 +185,7 @@ def my_new_tool(param: str) -> str:

 ### 添加新模型

-在 `agent.py` 中：
+在 `app/agent.py` 中：

 ```python
 def _create_new_model_llm(self):
@@ -227,7 +203,7 @@ model_configs = {
 }
 ```

-在前端 `frontend.py` 中添加选项：
+在前端 `frontend/app.py` 中添加选项：

 ```python
 MODEL_OPTIONS = {
@@ -246,11 +222,8 @@ docker compose exec backend bash
 # 查看实时日志
 docker compose logs -f backend

-# 检查数据库连接
-docker compose exec postgres psql -U postgres -d langgraph_db -c "\dt"
-
 # 测试后端 API
-curl http://localhost:8001/
+curl http://localhost:8001/health
 ```

 ---
@@ -267,11 +240,10 @@ curl http://localhost:8001/

 **部署流程：**
 1. 检出代码
-2. 安装 Python 依赖（验证用）
-3. 准备环境变量
-4. 重新构建并启动前后端（不影响数据库）
-5. 健康检查（等待后端就绪）
-6. 清理无用 Docker 资源
+2. 准备环境变量
+3. 重新构建并启动前后端（不影响远程数据库）
+4. 健康检查（等待后端就绪）
+5. 清理无用 Docker 资源

 **配置 Secrets：**

@@ -285,23 +257,20 @@ curl http://localhost:8001/

 ### 常见问题

-#### 1. PostgreSQL 连接失败
+#### 1. 无法连接远程数据库

 ```bash
-# 检查容器状态
-docker compose ps postgres
+# 测试 PostgreSQL 连接
+psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT version();"

-# 查看日志
-docker compose logs postgres
-
-# 测试连接
-docker compose exec postgres pg_isready -U postgres
+# 测试 Qdrant 连接
+curl http://115.190.121.151:6333/collections
 ```

 **解决方案：**
- 确认容器正在运行
- 检查密码是否正确
- 等待健康检查通过（约 10-30 秒）
+- 确认远程服务器防火墙开放了 5432 和 6333 端口
+- 检查网络连接是否正常
+- 验证用户名和密码是否正确

 #### 2. 后端启动失败

@@ -318,71 +287,32 @@ lsof -i :8001
 - 端口 8001 被占用
 - 依赖包缺失

-#### 3. 前端无法连接后端（NameResolutionError）
+#### 3. 前端无法连接后端

 **错误信息：**
 ```
-HTTPConnectionPool(host='backend', port=8001): Max retries exceeded with url: /chat 
-(Caused by NameResolutionError("HTTPConnection(host='backend', port=8001): Failed to resolve 'backend'"))
+HTTPConnectionPool(host='backend', port=8001): Max retries exceeded
 ```

-**原因分析：**
- 前端容器和后端容器不在同一个 Docker 网络中
- docker-compose.yml 中的服务名配置错误
- 环境变量 `API_URL` 配置不正确
-
 **解决方案：**

 1. **检查容器是否在同一网络中：**
 ```bash
-# 查看所有 Docker 网络
-docker network ls
-
-# 检查 ai-network 网络中的容器
 docker network inspect docker_ai-network
 ```

-2. **确认服务名正确：**
+2. **验证环境变量配置：**
 ```bash
-# 查看运行中的容器
-docker compose ps
-
-# 应该看到：ai-backend, ai-frontend, ai-postgres
-```
-
-3. **验证环境变量配置：**
-```bash
-# 进入前端容器检查环境变量
 docker compose exec frontend env | grep API_URL
-
-# 应该输出：API_URL=http://backend:8001/chat
 ```

-4. **重启服务：**
+3. **重启服务：**
 ```bash
-# 完全停止并重新启动所有服务
 docker compose down
 docker compose up -d --build
-
-# 查看启动日志
 docker compose logs -f
 ```

-5. **测试网络连通性：**
-```bash
-# 从前端容器 ping 后端服务
-docker compose exec frontend ping backend
-
-# 从前端容器访问后端 API
-docker compose exec frontend curl http://backend:8001/health
-```
-
-**重要提示：**
- Docker Compose 会自动创建名为 `<项目目录>_ai-network` 的网络
- 容器间通过**服务名**（而非容器名）进行通信
- 在 `docker-compose.yml` 中，服务名是 `backend`、`frontend`、`postgres`
- 确保所有服务都连接到同一个自定义网络（`ai-network`）
-
 #### 4. 模型初始化失败

 ```bash
@@ -405,36 +335,21 @@ docker compose logs backend | grep -i "model\|error"

 1. **检查 .env 文件格式：**
 ```bash
-# 确保文件末尾没有多余字符（如 EOF）
 cat -A .env
-
-# 正确格式应该是每行一个变量，无多余空格或特殊字符
 ```

 2. **验证环境变量已加载：**
 ```bash
-# 检查后端容器的环境变量
 docker compose exec backend env | grep ZHIPUAI_API_KEY
-
-# 检查前端容器的环境变量
 docker compose exec frontend env | grep API_URL
 ```

 3. **重新构建容器：**
 ```bash
-# 修改 .env 后需要重新创建容器
 docker compose down
 docker compose up -d --build
 ```

-4. **确认 .env 文件位置：**
-```bash
-# .env 文件应该在项目根目录（与 docker-compose.yml 的父目录同级）
-ls -la .env
-
-# docker-compose.yml 中使用了 context: .. ，所以 .env 应该在上一级目录
-```
-
 ---

 ## 📊 监控和维护
@@ -468,11 +383,11 @@ docker compose logs -f backend frontend
 ### 备份和恢复

 ```bash
-# 备份数据库
-docker compose exec postgres pg_dump -U postgres langgraph_db > backup.sql
+# 备份远程数据库
+pg_dump -h 115.190.121.151 -U postgres langgraph_db > backup.sql

 # 恢复数据库
-cat backup.sql | docker compose exec -T postgres psql -U postgres langgraph_db
+cat backup.sql | psql -h 115.190.121.151 -U postgres langgraph_db
 ```

 ---
@@ -491,14 +406,13 @@ cat backup.sql | docker compose exec -T postgres psql -U postgres langgraph_db
 - 启用 HTTPS
 - 配置日志轮转
 - 设置资源限制（CPU、内存）
- 定期备份数据库
+- 定期备份远程数据库

 ---

 ## 📞 获取帮助

 - **完整文档**: [README.md](README.md)
- **RAG 示例**: `rag_example.py`
 - **报告问题**: 提交 Issue 并附上日志

 ---