# reserve_platform **Repository Path**: dantes/reserve_platform ## Basic Information - **Project Name**: reserve_platform - **Description**: 个人开源 AI Agent 实战项目，面向家政、家电维修线下预约场景；内置完整安全 RAG 问答链路、多租户双层会话记忆、流式 AI 对话与分层工程化后端，持续迭代 LangGraph 多智能体、业务工具调用编排能力。 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-08-11 - **Last Updated**: 2026-08-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 线下服务预约智能平台 > 🏗️ **个人开源 · 持续迭代 | AI Agent 实战项目** > > 基于 LangChain + LangGraph 搭建面向家政、家电维修场景的 SaaS 式 AI 智能客服平台，整合工程化 RAG 全链路、多租户双层记忆、四端业务管理前端；底层基础框架全部完成，持续迭代多智能体协同、业务工具调用等核心能力。 > > 项目全程独立开发，全量代码开源，支持本地完整部署复现。 ------ ## ✨ 项目核心特性 ### 🤖 AI 智能问答与 Agent 底座（核心模块） - **标准化 RAG 八步处理链路**：隐私脱敏 → Prompt 安全过滤 → 用户画像召回 → 会话记忆加载 → 知识库检索 → LLM 流式生成 → 输出校验过滤 → 记忆持久入库，配套全链路异常捕获与操作审计 - **可插拔文档处理流水线**：分层式文档清洗架构、带重叠区间多级文本分块逻辑，兼容 PDF / DOCX / XLSX / TXT / MD / HTML / CSV 等主流文档格式导入解析 - **双层记忆持久化方案**：短期会话上下文记忆 + 长期用户画像存储，依托租户标识实现多商户数据隔离，支持跨会话自动摘要、模型调用消耗统计 - **完整大模型安全防护**：通过正则规则拦截 Prompt 注入风险，自动识别并脱敏用户隐私信息（手机号 / 身份证 / 银行卡） - **工程化 LLM 调用封装**：兼容标准 OpenAI 接口格式，内置自动重试、超时熔断、服务降级容错机制，配套调用日志追踪 - **中长期迭代方向**：基于 LangGraph 搭建多智能体调度框架，开发订单查询、预约创建等业务专用工具调用 Agent ### 🏗️ 工程化后端支撑 - 采用 API-Service-Repository-DB 四层分层架构，拆分用户、商户、技师、预约、订单等全套业务模块 - 集成 JWT 身份认证 + RBAC 细粒度角色权限体系，统一封装跨域、全局异常、链路追踪中间件 - 自定义 AI 业务专属异常分类，区分模型调用、安全校验、文档处理等各类故障；使用 Alembic 工具统一管理数据库版本迁移脚本 ### 📱 多端流式 AI 交互前端 基于 Vue3 + Element Plus 封装通用 AI 对话基础组件，原生支持 SSE 流式文字输出、离线功能兜底、快捷咨询模板；覆盖 C 端用户咨询、师傅业务查询、商户管理后台、运营总后台四大场景，依靠组件化开发减少重复页面开发工作量。 ------ ## 🏗️ 系统架构 ### AI RAG 链路进度流程图 ```mermaid flowchart LR A[用户提问] --> B[PII 隐私脱敏 ✅已完成] B --> C[Prompt 注入安全过滤 ✅已完成] C --> D[用户画像召回 ✅已完成] D --> E[会话记忆加载 ✅已完成] E --> F[ChromaDB 向量检索 🚧迭代中] F --> G[Prompt 组装 ✅已完成] G --> H[LLM 流式生成 ✅已完成] H --> I[输出内容过滤 📋规划中] I --> J[会话记忆入库 ✅已完成] ``` ### 整体分层技术架构 ``` ┌─────────────────────────────────────────────────┐ │ 前端层 (Vue3) │ │ C端H5 │ 师傅H5 │ 商户后台 │ 运营后台 │ └─────────────────────┬───────────────────────────┘ │ HTTP / SSE 通信 ┌─────────────────────┴───────────────────────────┐ │ 后端层 (FastAPI) │ │ API 层 → Service 层 → Repository 层 → DB 层 │ └─────────────────────┬───────────────────────────┘ │ ┌───────────┼───────────┐ ┌─────┴────┐ ┌────┴─────┐ ┌───┴─────┐ │ MySQL │ │ Redis │ │ChromaDB │ │ 业务主库 │ │ 缓存会话 │ │ 向量库 │ └──────────┘ └──────────┘ └─────────┘ │ ┌───────┴───────┐ │ AI 能力底座 │ │ LangChain │ │ LangGraph │ │ 第三方 LLM API│ └───────────────┘ ``` ------ ## 🛠️ 完整技术栈 | 分类 | 依赖技术 | | ----------------------- | ------------------------------------------------------------ | | **Agent / 大模型应用** | LangChain、LangGraph、Function Calling、Sentence-Transformers | | **向量数据库** | ChromaDB（接入迭代中） | | **Python 后端** | FastAPI、SQLAlchemy、Pydantic、Alembic | | **关系型 & 缓存数据库** | MySQL、Redis | | **安全鉴权** | JWT、RBAC、Passlib、python-jose | | **前端技术** | Vue 3、Vite、Pinia、Vue Router、Element Plus、ECharts、Axios | | **工程工具** | Git、Docker 基础环境 | | **开发语言** | Python、JavaScript | ------ ## 📁 项目目录结构 ### 后端目录 `reserve_platform` ``` reserve_platform/ ├── app/ │ ├── api/v1/ # 统一接口路由层（15+ 模块） │ ├── core/ # 全局配置、异常、安全、链路追踪 │ ├── db/ # 数据库连接初始化 │ ├── middleware/ # 跨域、日志、异常捕获中间件 │ ├── modules/ │ │ ├── ai/ # 核心 AI 模块 │ │ │ ├── domain/ingestion/ # DDD 领域层 - 文档摄入 │ │ │ │ ├── chunkers/ # 文本分块逻辑 │ │ │ │ └── cleaners/ # 分层文档清洗流水线 │ │ │ ├── services/ # RAG、文档解析、安全校验服务 │ │ │ └── repository/ # AI 数据仓储层 │ │ ├── auth/ # 账号权限模块 │ │ ├── user/ # 用户管理模块 │ │ ├── merchant/ # 商户管理模块 │ │ └── ... # 预约、订单、技师等业务模块 │ ├── tasks/ # 后台定时任务 │ └── main.py # 项目启动入口 ├── alembic/ # 数据库迁移脚本 └── requirements.txt # Python 依赖清单 ``` ### 前端目录 `offline-service-booking-platform` ``` src/ ├── api/ # 全局接口请求封装 │ ├── request.js # Axios 统一拦截器 │ └── modules/ # 分业务接口文件 ├── components/ # 全局公共组件 │ ├── AiChatBox.vue # AI 对话核心组件 │ └── ... # 其他通用组件 ├── layouts/ # 页面布局模板 ├── router/ # 路由配置、路由守卫 ├── stores/ # Pinia 全局状态管理 ├── utils/ # 通用工具函数 └── views/ # 页面视图 ├── user-h5/ # C 端用户移动端页面 ├── technician-h5/ # 师傅移动端页面 ├── merchant-admin/ # 商户 PC 管理后台 └── operation-admin/ # 平台运营总后台 ``` ------ ## 🚀 本地快速部署指南 ### 环境基础要求 - Python >= 3.10 - Node.js >= 20.19.0 - MySQL >= 8.0 - Redis >= 6.0 > 💡 Windows 系统建议搭配 WSL 子系统运行 Python 后端，规避路径兼容问题。 ### 后端启动流程 ```bash # 1. 拉取代码仓库 git clone https://gitee.com/xxx/service-reservation-ai-agent.git cd service-reservation-ai-agent/reserve_platform # 2. 安装 Python 依赖 pip install -r requirements.txt # 3. 配置环境变量 cp .env.example .env # 编辑 .env 文件，填入数据库、Redis、LLM 接口密钥、向量库配置 # 4. 初始化数据表结构 alembic upgrade head # 5. 启动后端服务 uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload ``` ### 前端启动流程 ```bash # 进入前端目录 cd offline-service-booking-platform # 安装前端依赖 npm install # 启动移动端 H5 开发环境（端口 5174） npm run dev:h5 # 启动 PC 管理后台开发环境（端口 5173） npm run dev:pc # 生产环境打包 npm run build:h5 npm run build:pc ``` ### AI 模块环境变量配置示例（.env） ```env # 大模型基础配置 AI_LLM_PROVIDER=qwen AI_LLM_API_URL= AI_LLM_API_KEY= AI_LLM_MODEL=qwen3.6-plus AI_LLM_TIMEOUT=30 # 向量库配置 AI_VECTOR_STORE_TYPE=chromadb AI_EMBEDDING_MODEL=text2vec-base-chinese # 容错重试配置 AI_MAX_RETRIES=3 ``` ------ ## 📊 AI 模块开发进度清单 ### ✅ 已完成落地 | 模块 | 功能 | | ------------ | ----------------------------------------------------------- | | RAG 基础链路 | 8 步流程编排 + 异常处理 + 审计追踪 | | 文档解析 | 多格式文档解析（PDF / DOCX / XLSX / TXT / MD / HTML / CSV） | | 文档清洗 | 5 层清洗架构、25+ 清洗器 | | 智能分块 | 三级分块策略（标题 / 段落 / Token）+ overlap | | 安全防护 | Prompt 注入检测、PII 隐私脱敏 | | 记忆系统 | 短期会话记忆 + 长期用户画像 | | 多租户 | tenant_id 数据隔离 | | LLM 调用 | OpenAI 兼容接口、异步调用、超时重试、熔断降级 | | 可观测性 | Trace 全链路追踪、审计日志、Token 用量统计 | | 前端 AI 组件 | AiChatBox 通用对话组件 | | 知识库管理 | 文档上传、列表、上下架管理页面 | | AI 任务监控 | 全链路任务可视化追踪页面 | ### 🚧 迭代开发中 | 模块 | 功能 | | -------- | ------------------------------------ | | 向量检索 | ChromaDB 向量库文档入库 + 相似度搜索 | | 输出过滤 | 回答内容安全校验过滤 | ### 📋 后续迭代规划（AI Agent 核心方向） | 模块 | 功能 | | -------- | -------------------------------- | | 混合检索 | BM25 + 向量混合检索 + 结果重排序 | | 语义缓存 | Redis 语义缓存优化 | | 多智能体 | LangGraph 多智能体协同编排 | | 工具调用 | 预约 / 订单业务工具调用智能体 | | 语音交互 | 实时语音输入 / 输出模块 | ------ ## 🧠 核心架构设计思路 ### 1. 基建优先，渐进式迭代 RAG 整套系统优先落地安全、异常、日志、多租户等底层基础设施，再逐步接入向量检索、多智能体等高阶能力。底层链路统一标准化，新增业务功能无需重构核心流程，所有模块支持独立插拔、故障降级。 ### 2. 分层可扩展文档清洗架构 线下服务场景文档来源杂乱，存在大量页眉页脚、乱码、重复文本等噪声。设计分层流水线依次处理： - **通用层**：编码修复、文本清洗、换行归一化 - **结构层**：页眉页脚移除、目录移除、重复检测 - **内容层**：模板占位符替换、FAQ 归一化、数字 / 日期标准化 - **格式特定层**：针对 PDF / Word / Excel / HTML 的专用清洗器 - **质量层**：乱码检测、质量评分 采用策略模式设计，新增清洗规则仅需新增独立处理器，不改动主处理流程。 ### 3. 双层记忆 + 多租户隔离设计 区分短期会话上下文与长期用户画像两类存储：短期记忆保障单轮对话连贯性，长期画像沉淀用户历史需求与偏好；基于租户 ID 隔离全部 AI 数据，适配多商户 SaaS 运营模式，保障数据安全隔离。 ------ ## 📝 版本迭代规划 - **v1.0（当前版本）**：完成业务平台基础框架、完整 RAG 链路底座、文档处理体系、四端前端页面 - **v1.1（下一版本）**：接入 ChromaDB 向量检索、文档批量入库、输出内容安全过滤 - **v1.2**：混合检索重排序、语义缓存优化 - **v1.3**：LangGraph 多智能体编排、业务工具调用 Agent 开发 - **v1.4**：拓展实时语音交互功能 ------ ## 📄 开源协议 MIT License ------ > 💡 **项目说明**：本项目为个人独立开发的 AI Agent 学习实战项目，完整覆盖 RAG 工程化、大模型应用、Agent 开发全栈技术。项目如实标注开发进度，无虚构功能与线上落地数据，全部代码可本地调试运行。欢迎 Star、Issue 交流学习。