智慧文旅 · 数字人 (Scenic Digital)
移动端体验：数字人伴游 · 智能地图导航 · AI 穿越照相馆
--- ## 🔥 核心特性 - 🎨 **极致的科幻 UI 设计与组件化架构** - 采用 Tailwind CSS v4 构建深色科幻风格（Cyberpunk/Tech风格）。 - 大屏由顶部导航栏（TopNavBar）、左侧全息数字人舱（AvatarPanel）与右侧可切换内容页（景区概览 / 景点导览 / 游览路线 / 景区地图 / 智能问答 / 系统公告）组成。 - 内置 `ParticleLayer` 粒子特效层，配合扫描线、几何裁剪（Clip-path）与光晕发光渲染，营造沉浸式科技氛围。 - 📊 **数据可视化与自定义资源管理** - 后端支持景区基础信息和资源内容的自定义管理。 - 前端基于 Pinia 进行全局状态管理，一处修改，大屏多面板实时联动刷新。 - 📢 **系统公告与版本信息页** - 顶部导航新增「系统公告」入口，集中展示当前版本号、本次更新内容与运行注意事项。 - 原首次访问自动弹窗已迁移为常驻页面，避免误触跳转，便于随时查看。 - 🤖 **大模型 RAG 知识库与智能问答** - 内置 ChromaDB 向量数据库 + BGE 中文 Embedding 模型，实现语义级知识检索。 - 知识库采用 Excel 文件管理（`knowledge.xlsx`），运维人员可直接编辑，上传后自动重建索引。 - 结合大语言模型（LLM）实现上下文增强问答，数字人可根据知识库内容智能回复。 - 🎙️ **云端语音识别与语音交互** - 集成腾讯云一句话识别（ASR）API，支持高精度中文语音转文本。 - 内置 WebSocket 语音服务，通过麦克风采集、ASR 识别和 LLM 回复实现语音问答与导览。 - 支持唤醒词模式（可配置），实现"你好小游"等唤醒交互。 - 支持定时播报系统，可按天固定时刻或按分钟间隔自动推送景区导览与景点介绍。 - ⚙️ **所见即所得的数据管理后台与本地上传** - 内置全局居中覆盖的科幻风格 `AdminOverlay` 数据控制台。 - 支持直接在浏览器拖拽/点击上传本地图片，Flask 后端自动生成 UUID 并提供本地静态文件服务。 - 支持景点列表的完整 CRUD（增删改查）和景区全局基础信息修改。 - 🏗 **标准化的全栈工程架构** - **前端**：Vue 3 组合式 API, Pinia 全局状态, Axios 拦截器封装, `@` 路径别名配置, 环境变量隔离。 - **后端**：Python Flask 蓝图路由分发, Service 业务逻辑层抽离, `.env` 敏感配置隔离。 --- ## 🛠 技术栈 ### 前端 (Frontend) - **核心框架**: Vue 3 (Composition API) - **状态管理**: Pinia - **构建工具**: Vite - **样式方案**: Tailwind CSS v4 - **网络请求**: Axios - **图标库**: Lucide Vue Next ### 后端 (Backend) - **核心框架**: Python Flask - **架构模式**: 蓝图 (Blueprints) 路由分发 + Service 业务逻辑层 - **环境隔离**: python-dotenv - **跨域处理**: Flask-CORS - **文件处理**: Werkzeug (本地安全文件上传) - **数据库驱动**: PyMySQL - **向量数据库**: ChromaDB（持久化存储，余弦相似度检索） - **Embedding 模型**: BAAI/bge-small-zh-v1.5（512 维中文语义向量） - **ASR 语音识别**: 腾讯云一句话识别（SentenceRecognition）API - **Excel 处理**: openpyxl（知识库数据读取） ### 数据库 (Database) - **MySQL 8.0+** (提供完整的建表与测试数据 SQL 脚本) --- ## 🚀 快速开始 ### 1. 环境准备 进入 `backend` 目录，激活虚拟环境并安装后端依赖： ```bash cd backend python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt ``` > **macOS 用户**：语音服务依赖 `portaudio`，请先执行 `brew install portaudio`。 ### 2. 数据库准备 1. 确保已安装并运行 MySQL 服务。 2. 创建数据库并导入初始化脚本： ```bash mysql -u root -p < database/scenic_init.sql ``` ### 3. 环境变量配置 在启动之前，请确保分别配置好前端和后端的环境变量： **后端配置 (`backend/.env`)**： 1. 进入 `backend` 目录，复制模板文件： ```bash cp .env.example .env ``` 2. 修改 `.env` 中的数据库连接密码 `DB_PASSWORD` 及其他信息。 **前端配置 (`.env`)**： 1. 在项目根目录，复制模板文件： ```bash cp .env.example .env ``` 2. 填入您的数字人 `VITE_XMOV_APP_ID` 和 `VITE_XMOV_APP_SECRET`。 > **注**：Xmov SDK 凭证的获取请进入官网 `https://c.c1nd.cn/9C9WW` 邀请码：`JHTA3EQSZP`，注册后可免费试用。 ### 4. 启动项目 **方式一：一键启动脚本（推荐）** 我们为您提供了方便的一键启动脚本，它会自动检测并安装前后端依赖，并同时启动两个服务： - **Windows 用户**: 直接双击根目录 `scripts` 文件夹下的 `start.bat`，或者在命令行执行： ```cmd .\scripts\start.bat ``` **方式二：手动启动（适用于调试）** **步骤1：启动后端服务** ```bash # 进入后端目录 cd backend # 创建Python虚拟环境（首次运行） python -m venv .venv # 激活虚拟环境 # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate # 安装依赖（首次运行） pip install -r requirements.txt # 启动后端服务（包含语音 WebSocket） python run.py ``` **步骤2：启动前端服务** 打开新的终端窗口： ```bash # 安装前端依赖（首次运行） npm install # 启动前端服务 (默认端口5173) npm run dev ``` **步骤3：访问应用** - 前端大屏展示: `http://localhost:5173` - 后端 API 服务: `http://localhost:8888` --- ## 📁 核心目录结构 ```text ├── backend/ # Python Flask 后端目录 │ ├── app/ # 后端核心代码 │ │ ├── routes/ # API 路由 │ │ ├── services/ # 业务逻辑层 │ │ ├── knowledge/ # 知识库模块 │ │ │ ├── data/ # 知识库数据文件 │ │ │ └── chroma/ # ChromaDB 持久化存储 │ │ ├── utils/ # 工具类 │ │ ├── voice_server.py # WebSocket 语音服务 │ │ └── service_container.py # 服务容器与依赖注入 │ ├── scripts/ # 后端工具脚本 │ ├── uploads/ # 本地图片上传存储目录 │ ├── .env.example # 后端环境变量模板 │ └── run.py # 后端启动入口 ├── database/ # 数据库目录 │ └── scenic_init.sql # MySQL 初始化脚本 (建表与 Mock 数据) ├── scripts/ # 项目自动化脚本 │ └── start.bat # Windows 一键启动脚本 ├── src/ # Vue 3 前端源码 │ ├── api/ # Axios 请求封装 │ ├── components/ # UI 组件 │ ├── stores/ # Pinia 状态管理 │ ├── pages/ # 页面组件 │ │ └── admin/ # 管理后台 │ ├── utils/ # 前端工具类 │ └── main.js # Vue 挂载入口 ├── .env.example # 前端环境变量模板 ├── jsconfig.json # IDE 路径智能提示 └── vite.config.js # Vite 构建配置 ``` --- ## 📚 知识库管理 平台内置 RAG（检索增强生成）知识库，让数字人可以基于自定义知识进行智能问答。 ### 数据源 知识库的数据源是 `backend/app/knowledge/data/` 目录下的 **所有 `.xlsx` 文件**。 - 文件名任意，可同时放多个 Excel - **第一行**：表头（列名随意取） - **每行**：一条知识 - 列的数量、顺序、表头名称完全自由，没有任何强制要求 ### 管理方式 - 在**管理后台 → 知识库管理**中拖拽上传 Excel，系统自动合并重建索引 - 也可手动将 Excel 放入 `backend/app/knowledge/data/` 目录，点击"重建索引" - 支持查看已导入文件列表、单独删除某个文件 - 支持下载模板或任意已上传的 Excel 文件 ### 检索配置 在 `backend/.env` 中按需调整： ```bash KNOWLEDGE_TOP_K=3 # 返回条数 KNOWLEDGE_MIN_SCORE=0.4 # 最低相似度阈值 KNOWLEDGE_MAX_DISTANCE=0.55 # 最佳匹配最大距离 ``` --- ## 🤝 参与贡献 欢迎提交 Issue 和 Pull Request 来完善这个项目！ 如果是重大变更，请先开一个 Issue 讨论您想要改变的内容。 ## 📄 开源协议 本项目采用 [MIT License](LICENSE) 开源协议 - 详情请查看 LICENSE 文件。 --- ## 💬 交流探讨 如果您对项目感兴趣，或者在部署过程中遇到问题，欢迎加入我们的交流群：
## 🤝 商务合作
如需定制化开发、技术对接、项目部署等商务合作，请扫码联系：
## ☕ 赞赏支持
开源不易，如果您觉得本项目对您有帮助，欢迎打赏支持，您的支持是我们前进的最大动力：
