Skip to content
BranchesTags

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
backend
backend
 
 
docs
docs
 
 
frontend
frontend
 
 
scripts
scripts
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 

Repository files navigation

FitPose AI Coach

FitPose AI Coach 是一个面向求职展示的企业级 AI 健身教练项目。它不是单纯的人体姿态识别 Demo，而是把计算机视觉、规则分析、主动学习、模型训练、模型版本管理和大语言模型教练能力串成一个可持续优化的 AI 产品闭环。

当前 MVP 聚焦深蹲训练，已经具备从实时识别到数据采集、样本标注、模型训练、AI 问答和历史分析的完整链路。

核心亮点

  • 实时人体姿态识别：基于 OpenCV + MediaPipe Pose 解析摄像头画面。
  • 深蹲动作分析：阶段识别、自动计数、动作评分、错误姿势提示。
  • 主动学习闭环：训练帧 -> 训练 Session -> 标注样本 -> 样本质量评估 -> 模型训练。
  • 模型管理：模型版本、训练指标、启用/回滚、artifact 清理、训练报告。
  • AI 教练：支持本地规则教练、OpenAI API、DeepSeek API 等兼容大模型。
  • 数据血缘：样本可追溯到训练 Session，模型可追溯到样本和 Session 来源。
  • 企业级分层：FastAPI + Clean Architecture，姿态引擎、分析器、数据集、模型、AI Provider 均可替换。

当前功能

实时训练

  • 打开摄像头
  • WebSocket 实时发送视频帧
  • 关键点检测和骨架覆盖
  • 深蹲阶段识别：站立、下蹲、最低点、起身
  • 深蹲次数、评分、反馈
  • 当前训练 Session 自动创建和结束

主动学习

  • 保存当前 Session 或最近训练帧为训练样本
  • 标注标准 / 不标准
  • 标注错误原因：下蹲不够、膝盖内扣、背部前倾等
  • 样本质量评估：是否可训练、缺失阶段、置信度不足等
  • 按 Session 筛选样本
  • 查看每个 Session 贡献的样本数和可训练样本数

模型管理

  • 使用可训练样本重新训练深蹲分类模型
  • 保存模型版本
  • 查看 Accuracy / Precision / Recall / F1
  • 启用历史模型
  • 删除历史模型
  • 清理非当前模型 artifact
  • 查看训练报告：
    • 标签分布
    • 来源 Session
    • 过滤样本数
    • 可训练样本数

AI 教练

  • 训练总结
  • 训练问答
  • 问答历史
  • 支持本地规则模式，无需 API Key
  • 支持 OpenAI / DeepSeek 等 Chat Completions 兼容接口
  • AI 问答会读取：
    • 最近训练帧
    • 训练历史趋势
    • 当前模型版本
    • 模型训练报告

架构

Browser
  -> WebSocket
  -> FastAPI
  -> Pose Engine
  -> Feature Extractor
  -> Action Analyzer
  -> Score / Feedback
  -> Workout Session
  -> Dataset Manager
  -> Model Trainer
  -> Model Manager
  -> AI Coach Agent
  -> Database

后端采用 Clean Architecture 思路组织：

backend/app
  api/              # HTTP 和 WebSocket 入口
  application/      # 用例层
  domain/           # 领域实体和端口
  infrastructure/   # MediaPipe、SQLAlchemy、AI Provider、ML Trainer 等实现
  core/             # 配置、日志、异常

前端采用 Vue3 + TypeScript：

frontend/src
  pages/            # 训练、分析、数据集、模型、AI 教练页面
  components/       # 摄像头、图表、实时指标、反馈面板
  services/         # HTTP API 和 WebSocket Client
  types/            # 前端类型定义

技术栈

后端：

  • FastAPI
  • Python
  • SQLAlchemy
  • OpenCV
  • MediaPipe Pose
  • NumPy
  • scikit-learn 兼容训练边界
  • 本地规则 AI / OpenAI 兼容 Provider

前端：

  • Vue3
  • TypeScript
  • Vite
  • Element Plus 兼容方向
  • ECharts
  • lucide-vue-next

默认数据库：

  • 本地 SQLite，方便快速运行
  • 配置 DATABASE_URL 后可切换 MySQL

本地访问地址

默认端口：

Frontend:  http://127.0.0.1:15173/
Backend:   http://127.0.0.1:18000
WebSocket: ws://127.0.0.1:18000/ws/pose

无 Docker 本地开发脚本

如果暂时不安装 Docker，可以使用 scripts/ 下的本地脚本管理开发服务。

环境检查：

scripts/check-env.sh

一键启动后端和前端：

scripts/dev-start.sh

停止通过脚本启动的服务：

scripts/dev-stop.sh

脚本默认使用：

BACKEND_PORT=18000
FRONTEND_PORT=15173

可以临时覆盖端口：

BACKEND_PORT=18001 FRONTEND_PORT=15174 scripts/dev-start.sh

脚本日志和 PID 文件会写入 .dev-runtime/，该目录不会提交到 Git。

后端启动

进入后端目录：

cd backend

创建环境文件：

cp .env.example .env

使用现有虚拟环境启动：

MPLCONFIGDIR=/private/tmp/fitpose-mpl .venv-pose/bin/uvicorn app.main:app --host 127.0.0.1 --port 18000

如果需要重新创建 Python 环境，建议使用 Python 3.11 或 3.12：

python3.11 -m venv .venv-pose
source .venv-pose/bin/activate
pip install -e ".[dev,pose]"

健康检查：

curl http://127.0.0.1:18000/api/v1/health

前端启动

进入前端目录：

cd frontend

常规方式：

pnpm install
pnpm dev

当前 Codex 工作区也可以直接使用已安装依赖和内置 Node 启动：

/Users/accs/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node node_modules/vite/bin/vite.js --host 127.0.0.1 --port 15173

AI Provider 配置

后端默认使用本地规则教练，不需要 API Key：

AI_PROVIDER=local
AI_MODEL=rule-based-coach

OpenAI 示例：

AI_PROVIDER=openai
AI_API_KEY=sk-...
AI_BASE_URL=https://api.openai.com/v1
AI_MODEL=gpt-4o-mini

DeepSeek 示例：

AI_PROVIDER=deepseek
AI_API_KEY=sk-...
AI_BASE_URL=https://api.deepseek.com
AI_MODEL=deepseek-chat

只要目标服务兼容 Chat Completions 协议，也可以通过 AI_BASE_URL 和 AI_MODEL 接入其它大模型网关。

推荐演示路径

完整新手使用手册见：docs/USER_GUIDE.md。

  1. 打开前端：http://127.0.0.1:15173/
  2. 进入“训练”页面，点击“开始”
  3. 站到摄像头前完成深蹲
  4. 查看实时次数、评分、阶段和反馈
  5. 点击“保存样本”，选择标准或不标准标签
  6. 进入“数据集”页面，查看样本、质量和来源 Session
  7. 进入“模型”页面，点击“重新训练”
  8. 查看模型版本、指标和训练数据报告
  9. 进入“AI 教练”页面，提问：
    • 我最近有没有进步？
    • 为什么我总是背部前倾？
    • 这次模型为什么效果一般？
    • 是不是样本来源太单一？

常用接口

GET  /api/v1/health
GET  /api/v1/workouts/analytics
POST /api/v1/workouts/sessions
PATCH /api/v1/workouts/sessions/{session_id}/finish
GET  /api/v1/datasets/samples
GET  /api/v1/datasets/samples?session_id=1
GET  /api/v1/datasets/session-stats
POST /api/v1/models/train
GET  /api/v1/models/versions
GET  /api/v1/models/readiness
POST /api/v1/ai-coach/summary
POST /api/v1/ai-coach/chat
GET  /api/v1/ai-coach/chats

测试和构建

后端测试：

cd backend
MPLCONFIGDIR=/private/tmp/fitpose-mpl .venv-pose/bin/python -m pytest tests

前端构建：

cd frontend
PATH=/Users/accs/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin:$PATH npm run build

如果当前环境没有 npm 命令，也可以直接使用 Vite：

cd frontend
/Users/accs/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node node_modules/vite/bin/vite.js --host 127.0.0.1 --port 15173

已实现阶段

  • FastAPI 企业级目录结构
  • Pose Engine 抽象和 MediaPipe 适配
  • 深蹲规则分析器
  • WebSocket 实时识别
  • Vue3 实时训练页面
  • 数据集与主动学习入口
  • 训练 Session 和样本血缘
  • 模型训练和模型版本管理
  • AI 教练总结、问答和历史记录
  • 模型训练报告与 AI 模型质量解释

后续计划

  • Docker Compose：FastAPI + 前端 + MySQL
  • Alembic 数据库迁移
  • 多动作支持：俯卧撑、平板支撑、开合跳、弓步蹲等
  • 更强模型：XGBoost / LightGBM / PyTorch
  • 更细的训练 Session 分析和周报
  • 摄像头画面录制与样本视频归档

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages