使用说明
虚拟个人助理
项目介绍
我们的项目旨在解决对智能虚拟助理的高需求，结合可定制的UI、Live2D、MCP和LLM灵活性。为了实现这一目标，我们的项目具有灵活的用户界面，包括Live2D、模型切换、状态监控和语音I/O。
徽章
特性
- 建筑：基于微服务的架构，实现模块化和可扩展性。
- 前端:
- 模型选择和后端状态监控。
- 使用Live2D化身进行文本/语音I/O，以增强用户交互。
- 后端:
- 用于路由请求的API网关。
- MCP服务器用于处理工具调用（例如，时间、日历、地图、RWTH服务（Mensa、GYM））。
- LLM集成:
- 通过Ollama支持本地和远程LLM（例如Qwen、gemma）。
- 提供LLM演示和动态模型切换。
- CI/CD管道：与GitLab CI/CD集成的自动化单元测试。
- 交叉平台的：与Windows、macOS和Linux兼容。
项目结构
该项目具有清晰且可维护的结构：
📦 Virtual Personal Assistant
├── 📁 docs
├── 📁 frontend
│ ├── 📁 Electron
│ │ ├── 📁 Live2D
│ │ │ ├── 📁 Framework
│ │ │ ├── 📁 public
│ │ │ └── 📁 src
│ │ ├── 📁 js
│ │ │ ├── index.js
│ │ │ ├── popup.js
│ │ │ ├── preload.js
│ │ │ ├── render-old.js
│ │ │ ├── renderer.js
│ │ │ ├── 📁 markdown
│ │ │ │ ├── marked.min.js
│ │ │ │ └── purify.min.js
│ │ ├── 📁 _test_
│ │ │ ├── index.test.js
│ │ │ ├── preload.test.js
│ │ │ └── renderer.test.js
│ │ ├── 📁 assets
│ │ │ ├── icon.ico
│ │ │ ├── icon.icns
│ │ │ └── icon.png
│ │ ├── index.html
│ │ └── package.json
├── 📁 backend
│ ├── 📁 MCPServer
│ │ ├── 📁 time-and-direction
│ │ │ ├── requirements.txt
│ │ │ └── main.py
│ │ ├── 📁 RWTH
│ │ │ ├── requirements.txt
│ │ │ ├── main.py
│ │ │ ├── gym.py
│ │ │ └── mensa.py
│ │ ├── 📁 research
│ │ │ └── main.py
│ ├── 📁 api-gateway
│ │ ├── api_gateway.py
│ │ └── 📁 client
│ │ └── vpa_client.py
├── 📁 tests
│ ├── test_api_gateway.py
│ ├── test_mcp_client.py
│ ├── test_MCPServer_research.py
│ ├── test_MCPServer_RWTH.py
│ └── test_MCPServer_time-and-direction.py
├── 📁 google-config
├── requirements.in
├── run.py
├── gitlab-ci.yml
└── README.md
先决条件
- python
3.10+ - 节点。JavaScript
20 - 电子
25 - 紫外线
0.7.17 - 远程服务器部署了LLM
- 深度搜索的API密钥
- 中列出的其他依赖项
requirements.txt和package.json
安装
-
克隆存储库：
git clone git@git.rwth-aachen.de:i5/teaching/bllma-lab/ss2025/virtual-personal-assistant.git -
使用
uv工具(链接):cd Backend- 对于文件夹
api-gateway,MCPServer/research,MCPServer/RWTH,MCPServer/time-and-direction，请执行以下操作：
-
安装依赖项（感谢
uv这可以跳过）：cd <Folder> uv sync # Running the project will also install it to a .venv: uv run <filename.py> -
电子设置
"node": "23.4.0", "npm": "11.3.0"Linux/MacOS
curl https://get.volta.sh | bash视窗
winget install Volta.Volta完成此步骤后，重新启动VSCode，然后打开一个新的终端，测试以下命令：
volta --version node -v npm -v如果您看到的是版本而不是错误，则成功。
cd FrontEnd\Electron npm install npm run start
用法
启动HPC服务器
- 登录HPC帐户并转到终端
cd /hpcwork/yw701564/./startOllama.sh- 在同一位置，使用以下命令启动新终端
./ngrok http 11434获取ngrok URL
启动应用程序
-
启动HPC服务器并获取ngrok URL（例如
https://207f-134-61-46-206.ngrok-free.app/) -
使用启动API网关、MCP服务器、Electron前端
run.py脚本：uv run run.py启动后，可以在终端中输入远程HPC服务器或本地ollama的URL：Enter the ngrok URL without '/' at the end :https://207f-134-61-46-206.ngrok-free.app或
Enter the ngrok URL without '/' at the end : http://localhost:11434
贡献
欢迎投稿！请按照以下步骤操作：
- 分叉存储库。
- 为您的功能或错误修复创建一个新分支。
- 进行更改，并使用清晰、描述性的提交消息进行提交。
- 把你的树枝推到叉子上。
- 向提交合并请求/拉取请求
main原始存储库的分支。
致谢
-
这个应用程序使用了很棒的Electron框架。
-
它利用OpenAI、Ollama和开源LLM的强大功能进行自然语言处理。
-
它集成了Live2D用于交互式化身。
团队贡献
- 阮东安
- 集团协调员和后端开发主管
- 设计了项目的微服务架构，并解耦了代码库以适应这种架构。
- 开发后端组件
- API网关
- MCP客户端、LLM客户端和工具调用的代理工作流
- 快速工程和文本处理以支持代理工作流
- MCP Server工具逻辑的主干设计与实现
- 设置构建和部署：Docker后端和Live2D+Electron应用捆绑
- 期中和期末演示和演示
- Krümpelmann， 芬尼根
- 前端开发主管
- 设计并实现了前端界面和核心功能。
- 集成交互式Live2D角色和增强的用户交互。
- 情感变化的实现及其与代理工作流的集成
- 开发了ASR（自动语音识别）和TTS（文本到- 语音）功能，以提高可用性。
- 将所有前端功能集成在一起，以获得更好的视觉效果。
- 期中和期末报告
- 周、登阳
- LLM部署和集成
- 在远程服务器上部署大型语言模型（LLM），并实现服务器和本地应用程序之间的通信。
- 为应用程序的连接逻辑做出了贡献，并确保了强大的端到端通信。
- 实现了MCP服务器RWTH的功能：查询 基于日期、类型或成分的mensa菜单，并查询GYM的职业。
- 期中和期末报告
- 回购README和技术报告的主要作者
演示视频
- 该应用程序的演示视频可以在GitHub目录（vpa-demo.mp4）中找到。
