Skip to content
Charlie-31-codePublic

About

StudyPet 是一个面向大学生的学习伙伴(搭子),基于 py-xiaozhi 项目进行二次开发。

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

54 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

简体中文 | English

项目简介

StudyPet 是一个面向大学生的学习伙伴(搭子),基于 py-xiaozhi 项目进行二次开发。该项目通过AI技术帮助大学生提高学习专注度,提供语音交互和视觉监控功能。

本项目基于 py-xiaozhi 进行二次开发,继承其 MIT 许可证。根据 MIT 许可证的规定:

  • 原项目版权归 Junsen 所有
  • 二次开发中新添加的代码和功能归 StudyPet Team(Charlie-31-code,Mia-au,Xenia-www,Sylvia0601) 所有
  • 对原项目代码的修改部分由原作者和二次开发团队共同拥有版权

功能特点

🎯 核心AI功能

  • AI语音交互:支持语音输入与识别,实现智能人机交互,提供自然流畅的对话体验
  • 视觉多模态:支持图像识别和处理,提供多模态交互能力,理解图像内容
  • 智能唤醒:支持多种唤醒词激活交互,免去手动操作的烦恼(可配置开启)
  • 自动对话模式:实现连续对话体验,提升用户交互流畅度
  • YOLO人脸检测:集成YOLO深度学习模型,实现高精度人脸检测与专注度分析,支持实时监控用户状态。通过分析人脸位置、尺寸和角度来判断用户是否专注,提供更准确的学习状态监测

🔧 MCP工具生态系统

  • 系统控制工具:系统状态监控、应用程序管理、音量控制、设备管理等
  • 日程管理工具:全功能日程管理,支持创建、查询、更新、删除事件,智能分类和提醒
  • 定时任务工具:倒计时器功能,支持延时执行MCP工具,多任务并行管理
  • 音乐播放工具:在线音乐搜索播放,支持播放控制、歌词显示、本地缓存管理
  • 搜索工具:网络搜索和网页内容获取,支持必应搜索和智能内容解析
  • 菜谱工具:丰富菜谱库,支持菜谱搜索、分类查询、智能推荐
  • 摄像头工具:图像捕获和AI分析,支持拍照识别和智能问答
  • YOLO视觉分析:基于YOLO模型的人脸检测与专注度监控,用于学习效率评估和用户状态感知。支持训练自定义模型以提高检测准确性和适应不同使用场景

🖥️ 用户界面

  • 图形化界面:基于PyQt5的现代GUI,支持小智表情与文本显示,增强视觉体验
  • 命令行模式:支持CLI运行,适用于嵌入式设备或无GUI环境
  • 系统托盘:后台运行支持,集成系统托盘功能
  • 全局快捷键:支持全局快捷键操作,提升使用便捷性
  • 设置界面:完整的设置管理界面,支持配置自定义

YOLOv8 人脸检测增强功能

为了提高专注度监测的准确性,项目集成了先进的YOLOv8人脸检测模型。此模型能够更精确地识别人脸位置、尺寸和角度,从而更准确地判断用户的专注状态。

特性

  • 高精度检测:使用专门训练的YOLOv8人脸检测模型
  • 实时监控:支持实时人脸检测和专注度分析
  • GPU加速:支持CUDA GPU加速,提高检测速度
  • 多种状态识别:
    • focused(专注):检测到人脸且位于画面中心区域,尺寸和角度合理
    • distracted(分心):检测到人脸但位置偏离中心或角度异常
    • absent(缺席):未检测到人脸
    • blocked(遮挡):摄像头被遮挡或画面过暗

模型训练

项目提供了完整的模型训练脚本,支持自定义数据集训练:

  1. 准备标注好的人脸数据集(YOLO格式)
  2. 使用train_yolo_face.py脚本进行模型训练
  3. 支持GPU加速训练,显著提高训练速度
  4. 默认使用yolov8n.pt作为预训练模型

模型测试

提供测试脚本验证模型性能:

  1. 使用test_yolo_face.py脚本测试训练好的模型
  2. 支持图像文件和实时摄像头测试
  3. 支持GPU加速推理

人脸专注度判定逻辑

系统根据以下因素判断用户专注状态:

  • 人脸位置:是否位于画面中心区域
  • 尺寸比例:人脸大小与预期大小的比值
  • 宽高比:判断人脸是否为正面朝向
  • 光照条件:检测画面是否过暗或被遮挡

系统要求

基础要求

  • Python版本:3.9 - 3.12
  • 操作系统:Windows 10+、macOS 10.15+、Linux
  • 音频设备:麦克风和扬声器设备
  • 网络连接:稳定的互联网连接(用于AI服务和在线功能)

推荐配置

  • 内存:至少4GB RAM(推荐8GB+)
  • 处理器:支持AVX指令集的现代CPU
  • 存储:至少2GB可用磁盘空间(用于模型文件和缓存)
  • 音频:支持16kHz采样率的音频设备

可选功能要求

  • 语音唤醒:需要下载Sherpa-ONNX语音识别模型
  • 摄像头功能:需要摄像头设备和OpenCV支持
  • YOLO人脸检测:需要安装YOLO相关依赖(ultralytics)以实现高精度人脸检测和专注度分析

技术架构

核心架构设计

  • 事件驱动架构: 基于asyncio的异步事件循环,支持高并发处理
  • 分层设计: 清晰的应用层、协议层、设备层、UI层分离
  • 单例模式: 核心组件采用单例模式,确保资源统一管理
  • 插件化: MCP工具系统和IoT设备支持插件化扩展

关键技术组件

  • 音频处理: Opus编解码、WebRTC回声消除、实时重采样、系统音频录制
  • 语音识别: Sherpa-ONNX离线模型、语音活动检测、唤醒词识别
  • 协议通信: WebSocket/MQTT双协议支持、加密传输、自动重连
  • 配置系统: 分层配置、点记法访问、动态更新、JSON/YAML支持

性能优化

  • 异步优先: 全系统异步架构,避免阻塞操作
  • 内存管理: 智能缓存、垃圾回收
  • 音频优化: 5ms低延迟处理、队列管理、流式传输
  • 并发控制: 任务池管理、信号量控制、线程安全

安全机制

  • 加密通信: WSS/TLS加密、证书验证
  • 设备认证: 双协议激活、设备指纹识别
  • 权限控制: 工具权限管理、API访问控制
  • 错误隔离: 异常隔离、故障恢复、优雅降级

开发指南

项目结构

StudyPet-4/
├── main.py                     # 应用程序主入口(CLI参数处理)
├── src/
│   ├── application.py          # 应用程序核心逻辑
│   ├── audio_codecs/           # 音频编解码器
│   │   ├── aec_processor.py    # 音频回声消除处理器
│   │   ├── audio_codec.py      # 音频编解码基础类
│   ├── audio_processing/       # 音频处理模块
│   │   ├── vad_detector.py     # 语音活动检测
│   │   └── wake_word_detect.py # 唤醒词检测
│   ├── constants/              # 常量定义
│   ├── core/                   # 核心组件
│   │   ├── ota.py             # 在线更新模块
│   │   └── system_initializer.py # 系统初始化器
│   ├── display/                # 显示界面抽象层
│   ├── mcp/                    # MCP工具系统
│   │   ├── mcp_server.py      # MCP服务器
│   │   └── tools/             # 各种工具模块
│   │       ├── calendar/      # 日历工具
│   │       ├── camera/        # 摄像头工具
│   │       ├── music/         # 音乐播放工具
│   │       ├── screenshot/    # 截图工具
│   │       ├── system/        # 系统工具
│   │       └── timer/         # 计时器工具
│   ├── network/                # 网络通信模块
│   ├── plugins/                # 插件系统
│   ├── protocols/              # 通信协议
│   ├── study/                  # 学习专注功能模块
│   │   ├── face.py            # 人脸专注度监控(支持Haar Cascade和YOLO)
│   │   └── tomato.py          # 番茄工作法计时器
│   ├── utils/                  # 工具函数
│   └── views/                  # UI视图组件
├── libs/                       # 第三方原生库
│   └── webrtc_apm/            # WebRTC音频处理模块
├── config/                     # 配置文件目录
├── models/                     # 模型文件目录
│   ├── yolov8n.pt             # YOLOv8预训练人脸检测模型
│   └── yolo11n.pt             # YOLO11预训练人脸检测模型
├── assets/                     # 静态资源文件
├── scripts/                    # 辅助脚本
├── requirements.txt            # Python依赖包列表
└── pyproject.toml             # 项目配置文件

开发环境设置

# 克隆项目
git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi

# 安装依赖
pip install -r requirements.txt

# 安装YOLO依赖以启用高级视觉功能(人脸检测、专注度分析)
pip install ultralytics

# 项目已包含预训练模型文件,可直接使用:
# - yolov8n.pt: 轻量级YOLOv8模型,适合实时检测
# - yolo11n.pt: YOLO11模型,提供更高精度检测

# 代码格式化
./format_code.sh

# 运行程序 - GUI模式(默认)
python main.py

# 运行程序 - CLI模式
python main.py --mode cli

# 指定通信协议
python main.py --protocol websocket  # WebSocket(默认)
python main.py --protocol mqtt       # MQTT协议

训练自定义YOLOv8人脸检测模型

项目提供了训练和测试自定义人脸检测模型的工具,以提高专注度监测的准确性:

# 1. 准备训练数据(确保数据按照YOLO格式组织)
#    数据目录结构应如下:
#    models/face_data/
#    ├── images/
#    │   ├── train/
#    │   └── val/
#    └── labels/
#        ├── train/
#        └── val/

# 2. 训练模型(支持GPU加速)
python train_yolo_face.py --epochs 100 --batch 16 --device 0

# 3. 测试模型(支持GPU加速)
python test_yolo_face.py --model runs/detect/face_model/weights/best.pt --image path/to/test/image.jpg --device 0

# 4. 实时摄像头测试
python test_yolo_face.py --model runs/detect/face_model/weights/best.pt --webcam --device 0

# 5. 评估模型性能
python test_yolo_face.py --model runs/detect/face_model/weights/best.pt --eval --device 0

核心开发模式

  • 异步优先: 使用async/await语法,避免阻塞操作
  • 错误处理: 完整的异常处理和日志记录
  • 配置管理: 使用ConfigManager统一配置访问
  • 测试驱动: 编写单元测试,确保代码质量

扩展开发

  • 添加MCP工具: 在src/mcp/tools/目录创建新工具模块
  • 添加协议: 实现Protocol抽象基类
  • 添加界面: 扩展BaseDisplay实现新的UI组件

状态流转图

                        +----------------+
                        |                |
                        v                |
+------+  唤醒词/按钮  +------------+   |   +------------+
| IDLE | -----------> | CONNECTING | --+-> | LISTENING  |
+------+              +------------+       +------------+
   ^                                            |
   |                                            | 语音识别完成
   |          +------------+                    v
   +--------- |  SPEAKING  | <-----------------+
     完成播放 +------------+

开源许可证

本项目基于 py-xiaozhi 项目进行二次开发,并采用 MIT 许可证。

版权所有 (c) 2025 Junsen 版权所有 (c) 2025 StudyPet Team(Mia-au,Charlie-31-code,Xenia-www,Sylvia0601)

特此免费授予任何获得本软件及相关文档文件(以下简称"软件")副本的人使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利,以及允许软件提供者这样做,但须符合以下条件:

上述版权声明和本许可声明应包含在软件的所有副本或重要部分中。

本软件按"原样"提供,不提供任何明示或暗示的保证,包括但不限于适销性、特定用途适用性和非侵权的保证。在任何情况下,作者或版权持有人均不对因软件或使用或其他处理软件而引起的任何索赔、损害或其他责任承担责任,无论是在合同诉讼、侵权诉讼或其他诉讼中。

About

StudyPet 是一个面向大学生的学习伙伴(搭子),基于 py-xiaozhi 项目进行二次开发。

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages