# zhistack-core **Repository Path**: longjiyi/zhistack-core ## Basic Information - **Project Name**: zhistack-core - **Description**: 基于 FastAPI + LangChain 1.2 + Vue 3.4的AI知识库问答系统、用户端提供多个文件类型的向量解析存储知识库、管理员端管理用户会话、文档、等信息、支持长期、短期记忆，适用于企业内网部署的知识库问答系统 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 4 - **Forks**: 0 - **Created**: 2026-02-09 - **Last Updated**: 2026-03-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 知栈 Core ## 支持用户持久记忆的企业级 AI 问答系统，基于 FastAPI + LangChain 1.2 + Vue 3.4。 ## 核心特性 - ✅ **用户持久记忆系统** - 短期记忆：Redis 缓存最近 30 分钟对话 - 长期记忆：对话摘要 + PGVector 向量存储 - 记忆召回：语义检索相关历史记忆并注入 Prompt - ✅ **LangChain 1.2 中间件链** - MemoryMiddleware：处理记忆注入与更新 - RateLimitMiddleware：基于 Redis 异步限流 - VectorRetrievalMiddleware：调用前检索 PGVector - SummarizationMiddleware：自动摘要长对话历史 - ContextEditingMiddleware：清理或压缩对话上下文 - ✅ **流式返回** - Server-Sent Events (SSE) 实时流式响应 - 前端实时显示 AI 回答 - ✅ **Celery 异步任务** - 定期压缩长期记忆（减少 Token） - 清理过期记忆 ## 技术栈 ### 后端 - FastAPI (异步) - LangChain 1.2.x - PostgreSQL 14+ + PGVector - Redis 7.0+ - Celery 5.3+ - SQLAlchemy 2.0+ (async) - fastapi-users (认证) - fastapi-cache2 (缓存) ### 前端 - Vue 3.4 (Composition API) - Vite 5.0+ - Pinia 2.1+ (持久化) - TypeScript 5.2+ - ECharts 5.4+ - VueUse 10.0+ # 前端界面展示 ## 用户端 ### 用户登陆界面 ![image-20260228164241197](./README.assets/image-20260228164241197.png) ### 首页 ![image-20260228164340242](./README.assets/image-20260228164340242.png) ### 知识库 ![image-20260228164400013](./README.assets/image-20260228164400013.png) ### 个人用户设置 ![image-20260228164439464](./README.assets/image-20260228164439464.png) # 管理员端 ### 首页 ![image-20260228164541635](./README.assets/image-20260228164541635.png) ### 对话管理 ![image-20260228164607231](./README.assets/image-20260228164607231.png) ### 知识库管理 ![image-20260228164637041](./README.assets/image-20260228164637041.png) ### 模型提示词 ![image-20260228164657415](./README.assets/image-20260228164657415.png) ### 系统设置 ![image-20260228164717593](./README.assets/image-20260228164717593.png) ## 快速开始 ### 1. 环境配置 ```bash cp .env.example .env # 编辑 .env 填入配置，特别是 OPENAI_API_KEY ``` ### 2. 配置 PostgreSQL 和 Redis ```shell #pg docker run -d --name postgres-gis -e POSTGRES_PASSWORD='请修改为你的密码' -p 5432:5432 -v /opt/postgres:/var/lib/postgresql registry.cn-hangzhou.aliyuncs.com/qiluo-images/postgres-with-gis:18.1 #redis docker run -d --name redis_8 --restart always -p 6379:6379 -v /opt/redis/data:/data -v /opt/redis/conf/redis.conf:/etc/redis/redis.conf -v /opt/redis/logs:/logs --label createdBy="Apps" redis:8.6.1 redis-server /etc/redis/redis.conf --requirepass "换成你需要设置的密码" ``` ### 3. PostgreSQL：设置模板并创建数据库 ``` docker exec -i postgres-gis psql -U postgres -d postgres <<-'EOF' -- 1. 终止所有其他连接到 'postgres' 数据库的会话（保留当前会话） SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'postgres' AND pid <> pg_backend_pid(); -- 2. 删除旧模板（如果存在） DROP DATABASE IF EXISTS template_postgis; -- 3. 创建新模板库（现在 postgres 是空闲的） CREATE DATABASE template_postgis WITH TEMPLATE = postgres; -- 4. 连接到模板库并安装扩展 \c template_postgis CREATE EXTENSION IF NOT EXISTS postgis; CREATE EXTENSION IF NOT EXISTS postgis_topology; CREATE EXTENSION IF NOT EXISTS fuzzystrmatch; -- 可选扩展（美国地址解析相关，按需启用） -- CREATE EXTENSION IF NOT EXISTS postgis_tiger_geocoder; -- CREATE EXTENSION IF NOT EXISTS address_standardizer; -- 5. 标记为模板数据库（禁止直接连接，仅用于创建新库） UPDATE pg_database SET datistemplate = true WHERE datname = 'template_postgis'; -- 6. 设置 owner 为 postgres，统一权限 ALTER DATABASE template_postgis OWNER TO postgres; -- 7. 验证结果 SELECT datname, datistemplate FROM pg_database WHERE datname = 'template_postgis'; EOF -- 8.创建数据库 docker exec postgres-gis psql -U postgres -d postgres -c "CREATE DATABASE agent_zhistack WITH TEMPLATE template_postgis;" ``` ### 2. 启动服务 ```bash docker compose up -d ``` ### 3. 访问应用 - Docker Compose（默认端口映射） - 前端: http://localhost:7005 - 后端 API: http://localhost:7006 - API 文档: http://localhost:7006/docs - 本地开发（Vite/uvicorn 直跑） - 前端: http://localhost:5173 - 后端 API: http://localhost:8000 - API 文档: http://localhost:8000/docs ## 附件上传与持久化（图片/视频） - Docker Compose 已将宿主机目录挂载到容器内 - `./uploads` -> `/app/uploads` - `./storage` -> `/app/storage` - 后端静态资源挂载路径 - 访问路径统一为：`/uploads/...` - 前端容器已将 `/uploads/` 反代到后端（见 `app_web/nginx.conf`） ### UPLOAD_DIR 配置 - 后端支持通过环境变量覆盖上传根目录：`UPLOAD_DIR` - 默认值：项目根目录下的 `uploads` - Docker 部署建议保持 `UPLOAD_DIR=/app/uploads`（与 compose volume 对齐） ## 流式输出（SSE）部署注意事项 项目聊天使用 SSE 流式接口（例如 `/api/chat/stream`、`/api/chat/stream_with_attachments`）。 如果你的服务器前面还有一层 Nginx/Caddy/Traefik 之类的反向代理，请确保： - 关闭代理缓冲（避免“流式变成一次性返回”） - 适当增大超时时间（长回答不被提前断开） ## 管理员端说明 - 管理员端包含：对话管理、知识库管理、模型/提示词管理、系统设置等 - 在“对话管理”中查看会话详情时： - 支持展示用户上传的图片/视频缩略图 - 点击可预览（依赖附件元数据中的 `url`，统一为 `/uploads/...`） ## 项目结构 ``` agent_zhicai/ ├── backend/ # FastAPI 后端 │ ├── app/ │ │ ├── api/ # API 路由 │ │ ├── auth/ # 认证模块 │ │ ├── celery_app.py # Celery 应用 │ │ ├── core/ # 核心配置 │ │ ├── db/ # 数据库 │ │ ├── langchain_app/ # LangChain 集成 │ │ ├── models/ # 数据模型 │ │ ├── schemas/ # Pydantic 模式 │ │ ├── services/ # 业务服务 │ │ └── tasks/ # Celery 任务 │ ├── Dockerfile │ └── requirements.txt ├── app_web/ # Vue 前端 │ ├── src/ │ │ ├── views/ # 页面组件 │ │ ├── stores/ # Pinia 状态 │ │ ├── composables/ # Composables │ │ └── router/ # 路由配置 │ ├── Dockerfile │ └── package.json ├── docker-compose.yml └── 进度.md ``` ## API 端点 ### 认证 - `POST /auth/register` - 用户注册 - `POST /auth/jwt/login` - 登录 - `POST /auth/forgot-password` - 忘记密码 - `GET /users/me` - 获取当前用户 ### 聊天 - `POST /api/chat` - 非流式聊天 - `POST /api/chat/stream` - 流式聊天 (SSE) ### 记忆管理 - `GET /api/memories` - 获取记忆列表 - `GET /api/memories/search?q=...` - 语义搜索记忆 - `POST /api/memories` - 创建记忆 - `DELETE /api/memories/{id}` - 删除记忆 ## 开发 ### 后端开发 ```bash cd backend pip install -r requirements.txt uvicorn app.main:app --reload ``` ### 前端开发 ```bash cd app_web npm install npm run dev ``` ### Celery 任务 ```bash # Worker celery -A app.celery_app worker -P solo --loglevel=info # Beat (定时任务) celery -A app.celery_app beat --loglevel=info ``` ## 部署 使用 Docker Compose 一键部署所有服务： ```bash docker compose up -d ``` 服务包括： - PostgreSQL (带 PGVector) - Redis - FastAPI 后端 - Celery Worker - Celery Beat - Vue 前端 ## 许可证 MIT