Apppublic

knight-gt/ai-guide-cloud

sourceHugging Faceupdated 3mo agoView on Hugging Face

1likes

App README

灵山 AI 数字导游

一键运行

第一次换电脑或换 Python 环境、API Key 时，只需要修改根目录下的 run.config.bat。

如果项目里还没有 run.config.bat，先复制模板：

bat

copy run.config.example.bat run.config.bat

然后修改这些配置：

bat

set "PYTHON_EXE=D:\app\conda\Acnaconda\envs\hci\python.exe"
set "NPM_CMD=npm.cmd"
set "DEEPSEEK_API_KEY=sk-please-change-me"
set "DEEPSEEK_BASE_URL=https://api.deepseek.com"
set "DEEPSEEK_MODEL=deepseek-chat"

—PYTHON_EXE：后端要使用的 Python 解释器路径。项目内有 backend\venv\Scripts\python.exe 时，run.bat 会优先使用它，避免误用缺少 edge_tts 等依赖的其他 Python 环境。
—NPM_CMD：前端 npm 命令。电脑已经配置 npm 环境变量时保持 npm.cmd 即可；否则改成 npm 的完整路径。
—DEEPSEEK_API_KEY：大模型 API Key。
—DEEPSEEK_BASE_URL：大模型接口地址，默认 DeepSeek。
—DEEPSEEK_MODEL：大模型名称，默认 deepseek-chat。
—BACKEND_HOST、BACKEND_PORT、FRONTEND_HOST：服务地址配置，通常不用改。

run.config.bat 里会放本机路径和 API Key，默认不会上传到 Git；仓库只保留 run.config.example.bat 模板。

RAG 知识库向量文件不上传到 Git。需要使用知识库问答时，请把 guide.index 和 documents.pkl 放到 backend/data/faiss_db/。

地图导览使用真实景区地图作为底图。当前源图在 picture/灵山地图.jpg，前端运行时读取：

text

frontend/public/map/lingshan-map.jpg

如果更换地图，请替换这个前端图片文件。地图上的景点热点配置在 frontend/src/components/ScenicMap.vue，坐标使用百分比 x、y，换图后只需要微调对应景点的坐标。访问 http://localhost:5173/?mapDebug=1 可开启地图坐标调试模式，点击地图空白处会显示当前位置的百分比坐标。

点击景点后，页面会显示本地简介，并自动向聊天区发送“请介绍一下某景点”的问题；详细讲解仍由后端 /chat 通过 backend/data/faiss_db/ 知识库生成。生成完成后，讲解内容也会回填到地图右侧卡片，方便游客不离开地图直接查看。

地图导览还支持：

—按“核心景点、服务设施、餐饮休息、交通站点”筛选热点。
—点击景点后会高亮推荐下一站，右侧卡片也可直接跳转到下一站。
—已经讲解过或正在讲解的同一景点不会重复发送聊天请求。

页面右侧提供快捷功能区：

—地图导览：打开景区地图弹层。
—智能路线：自动请求一条灵山景区游览路线。
—天气建议：结合当前天气生成穿着、雨具、防滑、防晒、补水和路线建议。
—服务设施：询问游客中心、卫生间、餐饮、观光车和休息点等信息。
—应急提示：询问迷路、下雨、老人儿童同行时的处理建议。

除地图导览外，快捷功能都会复用现有聊天问答链路，回答会进入聊天区并由数字人朗读。

配置完成后，双击运行：

bat

run.bat

脚本会自动启动：

—后端 FastAPI：http://127.0.0.1:8000
—前端 Vite：默认一般是 http://localhost:5173

中英文一键切换

打开右下角账号菜单后，底部左侧的 中 / EN 按钮可在中文和 English 之间切换。切换后会同步影响：

—页面 UI 文案、欢迎语、时间日期和天气显示。
—浏览器语音识别语言。
—数字人朗读语言和 Edge TTS 音色。
—/chat、/recommend 和地图景点简介接口的输出语言。
—地图热点名称、本地简介和知识库简介翻译。

英文模式下，前端仍会用中文景点名向后端知识库检索，返回内容再由后端翻译为英文，因此地图热点不会因为显示英文名而查不到知识库。

工作人员切换形象与声音

系统提供隐藏工作人员面板，用来直接切换数字人形象和讲解声音。

启动项目后，在浏览器访问：

text

http://localhost:5173/?staff=1

页面左侧数字人区域顶部会出现“工作人员设置”面板。选择“数字人形象”和“讲解声音”后，点击“保存”即可生效。

—形象预设来自 frontend/public/avatars/ 下的 guide1.vrm、guide2.vrm、guide3.vrm。
—声音预设使用内置 Edge TTS 中文神经语音，例如 zh-CN-XiaoxiaoNeural、zh-CN-YunxiNeural。
—设置会保存到后端数据库 backend/data/user_data.db，连接同一个后端的页面刷新后仍会使用已保存的形象和声音。
—当前版本不做密码保护，请只在可信内网或比赛演示环境使用 ?staff=1 入口。

管理后台与游客情感分析

启动项目后，管理后台入口是：

text

http://localhost:5173/admin.html

默认管理员密码来自后端环境变量 ADMIN_PASSWORD；没有设置时使用 admin123。建议演示前在 run.config.bat 里配置：

bat

set "ADMIN_PASSWORD=admin123"

后台的 数据统计 页面会汇总游客互动数据，包括：

—今日用户数、今日问题数、历史提问总量和累计用户。
—问题分类分布、热门问题 TOP10 和最近访问记录。
—游客情感分布：正向、中性、负向。
—中性互动：问候、闲聊、路线请求、票价/设施/名人咨询等在饼图中归为中性，但不进入景区改进建议。
—情感主题归因：服务接待、交通路线、门票排队、环境卫生、餐饮休息、景点体验、天气舒适等。
—景区改进建议：根据负面情绪集中的主题生成运营建议，便于后续优化服务、动线、讲解内容和现场管理。

情感分析使用本地规则，不调用大模型，不接入 /tts、/tts-sync 或数字人朗读队列。游客问答会先返回和朗读，日志记录与情感分析在后台完成，避免影响数字人开始吐词速度。历史记录没有情感字段时，后台统计会按原始提问临时分析，保证旧数据也能参与统计。

手动运行

后端：

bat

cd backend
call ..\run.config.bat
"%PYTHON_EXE%" -m uvicorn main:app --reload

前端：

bat

cd frontend
npm run dev

一键上传

双击运行：

bat

upload.bat

默认提交信息是 finish frontend and backend。也可以在命令行里自定义提交信息：

bat

upload.bat "update digital human demo"

右下角账号菜单

页面右下角提供 ChatGPT 风格账号入口。未登录时显示“登录 / 注册”；登录后显示头像、昵称、个人资料入口，并把常用功能收进同一个菜单：

—地图导览：打开景区地图弹层。
—智能路线：自动请求一条灵山景区游览路线。
—天气建议：结合当前天气生成穿着、雨具、防滑、防晒、补水和路线建议。
—服务设施：询问游客中心、卫生间、餐饮、观光车和休息点等信息。
—应急提示：询问迷路、下雨、老人儿童同行时的处理建议。

账号菜单支持注册、登录、退出登录，也可以编辑头像、昵称、游客类型、兴趣偏好和个人简介。头像会在浏览器端压缩成小尺寸 data URL，再保存到后端 SQLite；登录资料保存在 backend/data/user_data.db 的 users 表，浏览器也会缓存当前用户，刷新后先恢复显示，再尝试从后端同步。

除地图导览外，快捷功能都会复用现有聊天问答链路，回答会进入聊天区并由数字人朗读。这是比赛演示级账号能力，不包含短信、邮箱验证码或第三方登录；请不要在演示环境里使用真实敏感密码。

换电脑运行和修改配置说明

如果队友克隆项目后要在另一台 Windows 电脑运行，建议按下面顺序处理。项目代码可以上传 Git，但本地配置、虚拟环境、数据库和向量库不要上传。

1. 需要安装的软件

—Python 3.10 或 3.11。
—Node.js LTS，安装后确认命令行能运行 node -v 和 npm -v。
—Git。

2. 解压或克隆项目

把项目放到一个不要频繁移动的位置，例如：

text

D:\AI_Guide

压缩包里不要带 backend/venv/ 和 frontend/node_modules/。这两个目录是每台电脑本地生成的，直接复制很容易坏。

3. 创建并修改本机配置

项目根目录执行：

bat

copy run.config.example.bat run.config.bat

然后打开 run.config.bat，按本机情况修改这些值：

bat

set "PYTHON_EXE=%~dp0backend\venv\Scripts\python.exe"
set "NPM_CMD=npm.cmd"

set "BACKEND_HOST=127.0.0.1"
set "BACKEND_PORT=8000"
set "FRONTEND_HOST=127.0.0.1"
set "FRONTEND_PORT=5173"

set "DEEPSEEK_API_KEY=你的 DeepSeek Key"
set "DEEPSEEK_BASE_URL=https://api.deepseek.com"
set "DEEPSEEK_MODEL=deepseek-chat"
set "ADMIN_PASSWORD=admin123"

说明：

—run.config.bat 是每台电脑自己的本地配置，不要上传 Git。
—PYTHON_EXE 保持默认值即可；run.bat 会自动创建或重建 backend\venv。
—NPM_CMD 正常写 npm.cmd 即可；如果电脑识别不到 npm，可以改成 npm 的完整路径。
—ADMIN_PASSWORD 是管理员后台登录密码，不设置时后端默认使用 admin123。

4. 复制本地向量数据

向量库不上传 Git。需要 RAG 知识库回答时，把原电脑的下面文件夹复制到新电脑同样位置：

text

backend/data/faiss_db/

通常里面至少需要：

text

backend/data/faiss_db/guide.index
backend/data/faiss_db/documents.pkl

如果没有复制向量库，项目仍可启动，但知识库检索、部分推荐补充内容会降级，回答可能不够完整。

5. 本地数据库说明

本地数据库文件路径：

text

backend/data/user_data.db

这个文件保存游客问答日志、管理员后台统计、知识缺口、手动知识库和用户资料。它会在后端启动时自动创建，不需要手动新建，也不要上传 Git。

如果希望新电脑保留旧电脑的后台统计和用户记录，可以手动复制 backend/data/user_data.db；如果只是重新演示，可以不复制。

6. 启动项目

双击项目根目录的：

bat

run.bat

第一次启动时，脚本会自动做这些事：

text

检查 backend\venv 是否可用
坏掉或不存在时自动重建 backend\venv
自动安装 backend\requirements.txt
检查 frontend\node_modules 是否存在
不存在时自动 npm install
启动 FastAPI 后端和 Vite 前端

启动后终端会打印访问地址：

text

Backend:  http://127.0.0.1:8000
Frontend: http://127.0.0.1:5173
Admin:    http://127.0.0.1:5173/admin.html

如果 5173 被占用，run.bat 会自动寻找附近可用端口，实际以前端窗口打印的地址为准。

7. 管理员后台

管理员入口：

text

http://127.0.0.1:5173/admin.html

默认密码：

text

admin123

正式演示或提交前，建议在 run.config.bat 中设置自己的 ADMIN_PASSWORD。

8. 上传 Git 时不要上传的内容

这些文件或目录只属于本机环境，已经加入 .gitignore，不要强行添加：

text

run.config.bat
backend/venv/
frontend/node_modules/
backend/data/faiss_db/
backend/data/user_data.db
backend/data/user_data.db-*
backend1/
frontend1/

正常应该上传的是代码、配置模板和依赖清单，例如：

text

run.bat
run.config.example.bat
backend/*.py
backend/requirements.txt
frontend/package.json
frontend/package-lock.json
frontend/src/
frontend/admin.html
README.md

9. 常见问题

如果前端显示“后端连接失败”，先看后端窗口的报错。常见原因包括：

—DEEPSEEK_API_KEY 没有配置或 Key 无效。
—后端依赖安装失败，可以删除 backend\venv 后重新双击 run.bat。
—后端端口不是 8000，但前端仍在请求旧地址。
—向量库缺失导致 RAG 降级，虽然通常不应该导致服务崩溃。

如果 npm 无法运行：

—重新安装 Node.js LTS。
—或者把 run.config.bat 里的 NPM_CMD 改成 npm.cmd 的完整路径。

如果看到 No Python at ...：

—说明复制过来的 backend\venv 指向了别人电脑的 Python。
—新版 run.bat 会自动删除坏掉的 backend\venv 并重新创建。
—如果仍失败，确认命令行里能运行 python --version。

如果看到 No module named uvicorn：

—说明 backend\venv 能运行，但后端依赖没有装完整。
—新版 run.bat 会在启动前检查 uvicorn、fastapi 等后端依赖，缺包时自动重新安装 backend\requirements.txt。

如果要检查前端是否能打包：

bat

cd frontend
npm.cmd run build
cd ..

如果要检查后端 Python 文件是否有语法错误：

bat

cd backend
venv\Scripts\python.exe -m py_compile main.py database.py user_service.py question_router.py weather.py
cd ..

11. 关于封装 exe

当前项目更适合先按源码方式在其他电脑运行，因为它包含 FastAPI 后端、Vite 前端、TTS、FAISS 向量库和本地数据库。后续可以做一个 Windows 启动器 exe，用来自动启动后端和前端；不建议第一版直接打成单个 exe，因为依赖体积大、模型和向量库也不适合塞进 Git 或单文件程序里。