这是一个可直接运行的视觉搜索项目骨架：用户上传短视频、选择暂停点并圈选动作部位，系统提取前后各 2 秒，运行姿态估计、角度/轨迹计算、VLM 动作语义理解、DTW 跟练对齐、规则评分和有边界的 Coach Agent，最终输出慢速描摹视频、反馈 JSON 和分享卡。
- MediaPipe / RTMPose：只负责可观测的关键点、置信度和轨迹。
- 几何规则：只负责角度、身体中心代理位移和画面质量。
- DTW：只负责参考动作与用户动作的时间对齐。
- VLM：只解释动作语义、用户圈选意图、场景和拍摄问题，不生成精确角度。
- Coach Agent：确定性调用质量检测、重拍决策和本地教学搜索，再让 LLM 把算法事实写成自然反馈。
cp .env.example .env
python -m venv .venv
source .venv/bin/activate # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt
# 建议系统安装 ffmpeg，以输出浏览器兼容的 H.264 视频
python scripts/download_models.py
uvicorn app.main:app --reload --port 8000打开 http://localhost:8000。
不填写 FREEZE_OPENAI_API_KEY 也能运行，VLM/LLM 会使用规则降级；填写后启用远程视觉理解和反馈生成。
cp .env.example .env
docker compose up --buildcurl -X POST http://localhost:8000/api/jobs \
-F reference_video=@demo.mp4 \
-F pause_ms=2400 \
-F query='这个动作怎么发力？' \
-F roi_json='{"x":0.5,"y":0.1,"width":0.4,"height":0.7}' \
-F practice_video=@my_try.mp4 \
-F pose_backend=mediapipe然后轮询：
curl http://localhost:8000/api/jobs/<job_id>RTMPose 依赖 OpenMMLab 和与硬件匹配的 PyTorch/MMCV。推荐先按 PyTorch 官方方式安装正确的 CPU/CUDA 版本，再执行：
pip install -r requirements-rtmpose.txt
mim install 'mmengine>=0.9'
mim install 'mmcv>=2.0.1'启动时设置：
FREEZE_POSE_BACKEND=rtmpose
FREEZE_RTMPOSE_MODEL=human
FREEZE_RTMPOSE_DEVICE=cuda:0比赛演示建议默认 MediaPipe，服务器增强版再切 RTMPose。
- 统一骨架：MediaPipe 33 点和 RTMPose 输出都映射为公共 17 点。
- 身体归一化：以髋中心为原点，以躯干长度/肩宽为尺度，降低人物大小和画面位置影响。
- DTW 帧成本：按关键点可见度加权的归一化欧氏距离，并使用约束窗口限制搜索带宽；圈选区域和 VLM 识别的目标部位会提高对应关节权重。
- 角度偏差：沿 DTW 路径比较肘、肩、髋、膝八个关节角。
- 评分：
0.65 * 姿态分 + 0.35 * 角度分；MVP 系数需用真实跟练样本校准。 - 重拍规则：关键关节可见率低、手脚越界多、人物过小即停止评分，优先给重拍建议。
app/
pose/ MediaPipe 与 RTMPose 后端
analysis/ 角度、轨迹、DTW、评分规则
llm/ VLM、教学搜索、Coach Agent
render/ 骨架视频、拼图、分享卡
video/ 视频切片与抽帧
web/ H5 演示页
skill/ 赛题 Skill 文档
tests/ 算法单测
- 把
BackgroundTasks + 文件状态换成 Redis + Celery/RQ，支持多实例与失败重试。 - 教学搜索从
data/tutorials.json换成抖音内容索引/模拟搜索服务。 - 给不同动作类别配置不同关节权重和规则模板。
- 增加多人跟踪、镜像检测、摄像机运动补偿、3D pose lifting。
- 用 200–500 对参考/跟练视频标注教练评分，校准评分函数与重拍阈值。