> **TL;DR** — 本文介绍 `face-light` 开源项目的设计思路、技术选型、三组核心实验的完整数据分析，以及从基线到蒸馏的优化路径。项目代码已开源：[github.com/lechan775/face-light](https://github.com/lechan775/face-light)。

---

## 1. 项目背景

实时人脸检测与识别是边缘智能视觉的典型场景——从安防门禁、机器人交互到移动端身份核验，都需要在有限算力下完成"检测 → 对齐 → 识别"的端到端流水线。

现有的工业级方案（如 InsightFace）精度顶尖，但模型体积大、部署链路重；而轻量化领域缺少一套"从训练到部署"的完整开源管道。`face-light` 试图填补这个空白：**纯 PyTorch 实现、单文件训练脚本、一行命令 ONNX 导出**，目标是让研究者能在自己的数据集上快速复现和迭代。

项目源自一项本科毕业设计——"基于深度学习的人脸识别边缘端实时检测技术"，但代码设计从一开始就按可复现开源项目的标准来写。

---

## 2. 技术选型

### 2.1 检测器：SCRFD-500M

选择 SCRFD-500M 而非更流行的 YOLO 系列，出于三点考虑：

1. **专为 face 设计**：SCRFD 原生考虑了人脸尺度分布（小脸→大脸），不像通用检测器需要额外的锚点调整
2. **anchor-free 头**：用 Quality Focal Loss + Distribution Focal Loss 替代传统 anchor 匹配，代码更短（~200 行的 label assignment）
3. **极致轻量**：STEM 16 通道起，depthwise separable 全链路，总参数量 ~0.57M

```
Input (3×640×640) → Stem(16ch,s=2) → 4× DSConv + IRB → FPN(out=64)
 → Shared Head(DSConv×2 → cls:1 + reg:36)
 → DFL decode → NMS → [x1,y1,x2,y2,conf]
```

### 2.2 识别器：MobileFaceNet + ArcFace + 知识蒸馏

MobileFaceNet 是移动端人脸识别的事实标准骨干：112×112 输入，纯倒残差结构，512 维嵌入。搭配 ArcFace 的加性角度边距损失。

**蒸馏策略**是本项目的核心优化手段：

- **教师模型**：InsightFace buffalo_l（ResNet-50，512d embedding）
- **蒸馏损失三件套**：

| 损失项 | 权重 | 含义 |
|--------|------|------|
| `L_cls` (ArcFace) | 1.0 | 标准分类监督 |
| `L_feat` (Cosine) | 18.0 | 学生/教师 embedding 方向一致 |
| `L_rel` (SmoothL1) | 32.0 | 学生/教师 embedding 间的相对关系矩阵一致 |

`L_feat` 保证每个样本的 embedding 方向跟教师对齐，`L_rel` 更进一步：保证 batch 内任意两个样本的相似度关系也跟教师一致——这相当于在 embedding 空间做**结构蒸馏**。

### 2.3 为什么不端到端？

检测和识别分开训练，不是做不到端到端，而是刻意为之：

- **独立迭代**：换检测器不影响识别，反之亦然
- **数据策略不同**：检测数据（WIDER Face）和识别数据（身份标注）来源不同、标注成本不同，混在一起反而互相干扰
- **工程灵活性**：部署时检测帧可降频（每 3 帧跑一次），识别只在确认是人脸的帧上跑

---

## 3. 实验设计

共三组实验，从易到难递进：

| 实验 ID | 任务 | 模型 | 关键策略 | 训练轮数 |
|---------|------|------|----------|----------|
| DET_BASE_001 | 检测 | SCRFD-500M | 基线 + 多尺度训练 | 165 (early stop) |
| REC_BASE_001 | 识别 | MobileFaceNet + ArcFace | 基线 | 45 (early stop) |
| REC_DISTILL_001 | 识别 | MobileFaceNet + ArcFace + Distill | 教师蒸馏 + class-balanced sampler | 26 (early stop) |

### 3.1 统一训练配置

- 优化器：SGD + momentum=0.9 + weight_decay=5e-4
- 学习率策略：CosineAnnealingLR + Linear Warmup
- 混合精度：AMP (autocast + GradScaler)
- 早停：patience = 10~20 epochs
- 硬件：单卡 NVIDIA RTX 3060 (12GB) / A800 (80GB)

### 3.2 检测训练细节

```
batch_size: 128
input_size: 640 (multi-scale: [512,544,576,608,640,672])
epochs: 200
lr: 0.01 → warmup 5 epochs → cosine decay to 0.0005
augmentation: hflip(0.5) + brightness(0.2) + contrast(0.2) + HSV(0.1) + blur + jpeg_compression
```

### 3.3 识别蒸馏训练细节

```
batch_size: 256
input_size: 112
epochs: 60
lr: 0.008 → warmup 3 epochs → cosine decay
augmentation: hflip(0.5) + mild color jitter(0.08) + grayscale(0.02) + gaussian blur(0.02)
sampler: class-balanced (power=0.35, replacement)
early_stop_metric: TAR@FAR=1e-4
early_stop_metric_secondary: EER
```

选择 `TAR@FAR=1e-4` 作为主指标而非简单的 accuracy，是因为在安防场景下，低误识率（FAR=万分之一）下的识别通过率才是真正有价值的指标——accuracy 会被大量 easy negatives 拉高，掩盖高难样本上的表现瓶颈。

---

## 4. 实验结果

### 4.1 检测：DET_BASE_001

| 指标 | 初始值 (epoch 0) | 最优值 (epoch 144) | 最终值 (epoch 164) |
|------|------------------|-------------------|-------------------|
| total_loss | 1.8406 | — | 0.9377 |
| cls_loss | 0.0347 | — | 0.0018 |
| box_loss | 0.6332 | — | 0.3455 |
| dfl_loss | 2.1583 | — | 0.9791 |
| **AP50** | — | **0.5458** | — |

**分析**：
- cls_loss 从 0.0347 收敛到 0.0018（下降 94.8%），说明 QFL 分类头收敛良好
- box_loss 从 0.6332 收敛到 0.3455（下降 45.4%），GIoU 回归仍在改善但速度放缓
- dfl_loss 从 2.1583 降至 0.9791（下降 54.6%），DFL 分布回归也在持续优化
- **AP50=0.5458 偏低**，主要原因判断：
 1. 训练数据规模有限（WIDER Face train 子集，约 12,800 张）
 2. 未引入 WIDER Face 的 hard negative mining
 3. 小脸检测是该架构的天然短板（stride=8 的最小检测分辨率有限）

### 4.2 识别基线：REC_BASE_001

| 指标 | 初始值 (epoch 0) | 最优值 (epoch 29) | 最终值 (epoch 44) |
|------|------------------|-------------------|-------------------|
| train_loss | 63.5178 | — | 34.1785 |
| **LFW accuracy** | 0.5383 | **0.7502** | — |
| TAR@FAR=1e-4 | 0.0000 | — | 0.0000 |

**分析**：
- 训练损失下降 46.2%，但 LFW accuracy 仅到 75.02%——**远低于 SOTA（~99.8%）**
- **TAR@FAR=1e-4 始终为 0**：在极端低误识条件下，模型无法区分正负样本对
- 根因判断：基线实验使用了较早版本的训练数据（可能存在标注噪音），且 ArcFace margin（m=0.7, s=80）的组合在 50 epochs 内未能充分收敛
- 这组实验虽然有"翻车"的味道，但恰好证明了：**仅靠 MobileFaceNet + ArcFace 的 naive 训练，无法在有限数据上收敛到可用水平**

### 4.3 识别蒸馏：REC_DISTILL_001

| 指标 | 初始值 (epoch 0) | 最优值 (epoch 15) | 最终值 (epoch 25) |
|------|------------------|-------------------|-------------------|
| total_loss | 61.2342 | — | 23.5628 |
| cls_loss | 43.32 | — | 13.02 |
| feat_loss | 0.9842 | — | 0.5783 |
| rel_loss | 0.0062 | — | 0.0042 |
| **LFW accuracy** | — | **0.9558** | — |
| **TAR@FAR=1e-3** | — | **0.0856** | — |
| **TAR@FAR=1e-4** | — | **0.0416** | — |
| **EER** | — | **0.2549** | — |

**分析**：
- 蒸馏将 LFW accuracy 从 75.02%（基线）提升到 95.58%——**+20.56 个百分点**
- TAR@FAR=1e-4 从 0 突破到 0.0416——终于有了低 FAR 场景下的识别能力
- feat_loss 从 0.9842 降到 0.5783，说明学生 embedding 在逐步对齐教师的方向
- rel_loss 从 0.0062 降到 0.0042，关系矩阵蒸馏也在收敛
- **但 95.58% 仍然显著低于 buffalo_l 教师（~99.8%）和 SOTA**，说明：
 1. 蒸馏权重（cls:1.0 / feat:18.0 / rel:32.0）可能不是最优配比——rel_weight=32 偏高可能过度约束了学生
 2. 仅 26 epochs 就被早停（patience=10, 主指标 TAR@FAR=1e-4 提升缓慢）
 3. class-balanced sampler 的 power=0.35 可能过于激进，导致 long-tail 类别被过度采样

### 4.4 三组实验纵向对比

```
 REC_BASE_001 ──→ REC_DISTILL_001
LFW accuracy: 75.02% ──→ 95.58% (+27.4%)
TAR@FAR=1e-4: 0.0000 ──→ 0.0416 (突破)
EER: N/A ──→ 0.2549

 DET_BASE_001
AP50: 54.58%
cls_loss 收敛: 0.0347 → 0.0018 (-94.8%)
box_loss 收敛: 0.6332 → 0.3455 (-45.4%)
```

三组实验的关系不是割裂的，而是构成了一个完整的优化路径：**基线暴露问题 → 蒸馏解决区分度 → 下一步走向更强的检测器和更细粒度的数据策略**。

---

## 5. 关键发现

### 5.1 蒸馏是轻量级识别的必要手段

基线实验证明了 MobileFaceNet 从零训练**无法**在有限数据上产生有区分度的 embedding。而引入教师蒸馏后，即使只训练 26 个 epoch，accuracy 就从 75% 跃升到 95.6%。这不是简单的"精度提升"，而是**从不可用到基本可用的质变**。

### 5.2 早停指标的选择很关键

基线实验用了 `accuracy` 做早停指标，蒸馏实验用了 `TAR@FAR=1e-4`。后者在低 FAR 场景下严格得多——模型可能在 accuracy 已经平稳时，TAR 仍在缓慢爬升。实践建议：**始终用业务场景的最终指标做早停**，而不是训练阶段的代理指标。

### 5.3 检测和识别的瓶颈不同

- 检测瓶颈在**定位**（box_loss 收敛速度远慢于 cls_loss），需要更多数据或更强的 backbone
- 识别瓶颈在**区分度**（embedding 空间的可分性），可以通过蒸馏和难例挖掘改善

### 5.4 数据质量 > 模型结构

三组实验使用了同一套代码框架，但不同版本的数据（原始版 vs 清洗后版）。蒸馏实验之所以比基线好，除了蒸馏本身，数据清洗（去除低质量身份、平衡类别分布）也贡献了相当一部分收益。

---

## 6. 复现指南

### 环境

```bash
git clone https://github.com/lechan775/face-light.git
cd face-light
pip install -r requirements.txt
```

### 训练检测器

```bash
python train_detector.py \
 --config configs/train/det_scrfd_base.yaml \
 --seed 42 \
 --exp-id DET_MY_EXP \
 --log-dir runs/train/detection/DET_MY_EXP
```

### 训练识别器（蒸馏）

```bash
# 确保教师模型已下载至 ~/.insightface/models/buffalo_l/
python train_recognizer_distill.py \
 --config configs/train/rec_mobilefacenet_arcface_distill.yaml \
 --seed 42 \
 --exp-id REC_DISTILL_MY_EXP \
 --log-dir runs/train/recognition/REC_DISTILL_MY_EXP
```

### 评估

```bash
# 检测器 AP50
python tools/eval/eval_detector.py \
 --model-path runs/train/detection/DET_MY_EXP/best.pt \
 --backend pytorch \
 --dataset-root data/processed/detection \
 --split val --out-dir runs/eval/detection/DET_MY_EXP

# 识别器 TAR@FAR
python tools/eval/eval_recognizer.py \
 --model-path runs/train/recognition/REC_DISTILL_MY_EXP/best.pt \
 --embed-dim 512 \
 --pairs-file data/processed/recognition/eval/protocols/lfw/pairs.txt \
 --lfw-dir data/processed/recognition/eval/lfw \
 --out-dir runs/eval/recognition/REC_DISTILL_MY_EXP
```

### ONNX 导出

```bash
python export_onnx.py --task detection --weights best.pt --imgsz 640 640 --out detector.onnx
python export_onnx.py --task recognition --weights best.pt --imgsz 112 112 --out recognizer.onnx
```

---

## 7. 下一步计划

- [ ] **检测器升级**：尝试 SCRFD-2.5G 或 Nanodet-Plus，配合 WIDER Face 全量数据 + hard negative mining
- [ ] **蒸馏调参**：Grid Search 寻找最优 (feat_weight, rel_weight) 组合
- [ ] **引入更多验证协议**：CFP-FP、AgeDB-30、自建场景集
- [ ] **TensorRT 部署**：FP16 量化 + 端到端延迟基准测试
- [ ] **检测-识别联合优化**：检测输出的 face crop 质量直接反馈到识别 loss

---

## 8. 致谢

本项目使用了以下开源工作：

- [InsightFace](https://github.com/deepinsight/insightface) — 教师模型 buffalo_l 及人脸分析工具链
- [SCRFD](https://arxiv.org/abs/2105.04714) — 轻量级人脸检测架构
- [MobileFaceNet](https://arxiv.org/abs/1804.07573) — 移动端人脸识别骨干
- [ArcFace](https://arxiv.org/abs/1801.07698) — 加性角度边距损失
- [Generalized Focal Loss](https://arxiv.org/abs/2006.04388) — QFL + DFL 检测头

---

<div align="center">

**[⭐ GitHub: lechan775/face-light](https://github.com/lechan775/face-light)** · MIT License

</div>

一套面向边缘端的轻量级人脸检测与识别系统

> 你有没有经历过这样的场景——脑子里有一张清晰的架构图，打开 draw.io 却对着空白画布发呆十分钟？这个项目就是来解决这个问题的。


 <img src="https://img.shields.io/badge/Java-17-orange?logo=java" alt="Java 17">
 <img src="https://img.shields.io/badge/Spring_Boot-3.4.3-brightgreen?logo=springboot" alt="Spring Boot">
 <img src="https://img.shields.io/badge/Next.js-16.1-black?logo=next.js" alt="Next.js">
 <img src="https://img.shields.io/badge/React-19.2-61DAFB?logo=react" alt="React">
 <img src="https://img.shields.io/badge/Google_ADK-0.5.0-4285F4?logo=google" alt="Google ADK">
 <img src="https://img.shields.io/badge/Tailwind-v4-06B6D4?logo=tailwindcss" alt="Tailwind">
 <img src="https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker" alt="Docker">
 <img src="https://img.shields.io/badge/License-Apache_2.0-blue" alt="License">



 🔗 GitHub 仓库：<a href="https://github.com/lechan775/ai-agent-drawio">github.com/lechan775/ai-agent-drawio</a>


---

## 📖 一句话说清楚

**AI Agent Draw.io** 是一个 AI 驱动的智能架构图生成平台。你只需要用中文或英文描述想要画什么——"画一个微服务架构，包含 API Gateway、三个微服务、MySQL 和 Redis"——AI Agent 就能自动在嵌入式 draw.io 画布上渲染出专业级图表。

更关键的是，它**不是一个简单的 ChatGPT 套壳**：后端基于 Google ADK 实现了完整的 Multi-Agent 编排、MCP 协议工具链集成，以及 Sequential / Parallel / Loop 三种 Agent 工作流模式。

---

## 🏗️ 整体架构

```
┌──────────────────────────────────────────────────────────────────┐
│ 🌐 用户浏览器 │
│ │
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
│ │ 💬 对话面板 │ │ 📐 Draw.io 嵌入式画布 │ │
│ │ │ │ │ │
│ │ • Agent 选择下拉 │ ←→ │ • AI 生成的 XML 实时渲染 │ │
│ │ • 多轮对话历史 │ │ • 鼠标拖拽微调 │ │
│ │ • 流式打字效果 │ │ • SVG/PNG 一键导出 │ │
│ │ • 画布上下文携带 │ │ • 多会话画布独立管理 │ │
│ └─────────┬───────────┘ └──────────────────────────────┘ │
└─────────────┼─────────────────────────────────────────────────────┘
 │ HTTP REST + SSE 流式
 ▼
┌──────────────────────────────────────────────────────────────────┐
│ ☕ Spring Boot 后端 (Java 17) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Trigger │ │ App │ │ Domain │ │Infrastructure│ │
│ │ (HTTP) │──▶│ (Config) │──▶│ (Agent) │──▶│ (DB/Redis) │ │
│ └──────────┘ └──────────┘ └────┬─────┘ └──────────────┘ │
│ │ │
│ ┌───────────────────────────┼───────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌─────────────────────┐ ┌──────────────┐ │
│ │ Google ADK │ │ Spring AI │ │ LangChain4j │ │
│ │ Agent 编排 │ │ Tool/LLM/MCP 集成 │ │ MCP/LLM 集成│ │
│ └──────────────┘ └─────────────────────┘ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 🔌 MCP Protocol (Model Context Protocol) │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │SSE Client│ │ STDIO │ │ Local │ ← 工具接入 │ │
│ │ │远程服务 │ │子进程 │ │本地函数 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────┐ │ │
│ │ │ MCP Server (对外暴露) │ → 供其他Agent │ │
│ │ └──────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```

---

## 🔥 核心亮点

### 1. 自然语言 → 图表，端到端闭环

不是把 AI 回复 copy-paste 到 draw.io，而是 **AI 直接操控画布**。后端 Agent 输出 draw.io XML 格式，前端 `react-drawio` 组件实时解析并渲染。

```json
// Agent 响应结构
{
 "type": "drawio", // ← 告诉前端：这是图，直接渲染
 "content": "<mxGraphModel>...</mxGraphModel>"
}
```

当 `type` 为 `user` 时，内容渲染到聊天面板（追问、澄清）；当 `type` 为 `drawio` 时，内容直接推入画布。

### 2. 画布上下文「携带」能力

这是区别于普通 Chat-to-Diagram 工具的关键设计。你可以先在 draw.io 画布上手动拖出大致结构，然后打开「携带画布上下文」开关——当前画布的全部状态会作为上下文回传给 Agent，实现**增量修改**而非每次都从头生成。

### 3. Google ADK 多智能体编排

后端不是简单调一次 LLM，而是基于 **Google Agent Development Kit (ADK)** 构建的完整 Agent 系统：

| 工作流模式 | 说明 | 典型场景 |
|-----------|------|----------|
| `SequentialAgentNode` | 顺序执行多个子 Agent | 先搜索资料 → 再生成图表 |
| `ParallelAgentNode` | 并行执行多个子 Agent | 同时查询多个数据源 |
| `LoopAgentNode` | 循环迭代执行 | 生成 → 自检 → 修正 → 再生成 |

```yaml
# Agent 配置示例 (agent-draw-io.yml)
agent:
 agentId: drawioagent
 agentName: "Draw.io 架构助手"
 chatModel:
 model: gpt-5.1
 tool:
 mcp:
 - name: baidu-search # MCP 工具：联网搜索
 type: sse
 baseUri: http://appbuilder.baidu.com/v2/ai_search/mcp/
```

### 4. MCP 协议深度集成

后端同时作为 **MCP Client** 和 **MCP Server** 运行：

- **Client 侧**：接入百度搜索等外部 MCP 服务，Agent 可以实时检索技术文档来辅助绘图
- **Server 侧**：暴露自定义 MCP 工具供其他 AI Agent 调用，实现 Agent-to-Agent 通信

### 5. DDD 六层架构，工程化拉满

后端严格遵循领域驱动设计（DDD）分层，模块边界清晰：

```
ai-agent-scaffold-draw-io/
├── api/ # RPC 接口契约 + DTO
├── app/ # 启动入口 + 自动配置
├── domain/ # 领域核心（Agent、Chat、MCP、工作流）
├── infrastructure/ # DB/Redis/外部网关
├── trigger/ # HTTP Controller
└── types/ # 通用枚举/异常
```

---

## 🎯 技术选型

| 层级 | 技术选型 | 选型理由 |
|------|---------|----------|
| **后端框架** | Spring Boot 3.4.3 | 生态成熟，配置驱动，与 Spring AI 无缝集成 |
| **AI Agent 引擎** | Google ADK 0.5.0 | 原生支持 Multi-Agent 编排、Session 管理、流式事件 |
| **LLM 集成** | Spring AI + LangChain4j 双通道 | Spring AI 用于主链路，LangChain4j 作为备选与 MCP 补充 |
| **工具协议** | MCP (SSE/STDIO/Local) | 标准化工具接入，AI Agent 互联互通的标准协议 |
| **前端框架** | Next.js 16 + React 19 | SSR 优化 + RSC 架构，生产级性能 |
| **图表引擎** | react-drawio (draw.io 嵌入) | 业界标准图表编辑器，XML 驱动，零学习成本 |
| **样式方案** | Tailwind CSS v4 | 原子化 CSS，设计系统一致性 |
| **部署** | Docker Compose | MySQL + Redis + 前后端一键编排 |

---

## 🚀 一分钟本地跑起来

### 前置条件

- JDK 17+
- Maven 3.6+
- Node.js 20+
- (可选) Docker 24+

### 三步启动

```bash
# Step 1：编译后端
cd ai-agent-scaffold-draw-io
mvn clean package -DskipTests
java -jar ai-agent-scaffold-draw-io-app/target/ai-agent-scaffold-draw-io-app.jar

# Step 2：启动前端（新终端）
cd ai-agent-scaffold-draw-io-front
npm install
NEXT_PUBLIC_API_BASE_URL=http://localhost:8091/api/v1 npm run dev

# Step 3：打开浏览器
# 访问 http://localhost:3000，选择 Agent，开始对话！
```

### Docker 全家桶（生产环境）

```bash
# 基础设施（MySQL + Redis + 管理面板）
docker-compose -f docs/dev-ops/docker-compose-environment-aliyun.yml up -d

# 应用（后端 8091 + 前端 3000）
docker-compose -f docs/dev-ops/docker-compose-app.yml up -d
```

| 服务 | 端口 | 说明 |
|------|------|------|
| 前端 | `:3000` | AI Chat + Draw.io 画布 |
| 后端 API | `:8091` | REST + SSE 流式 |
| phpMyAdmin | `:8899` | MySQL 可视化管理 |
| RedisAdmin | `:8081` | Redis 可视化管理 |

---

## 📡 API 一览

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/query_ai_agent_config_list` | 获取可用 Agent 列表 |
| `POST` | `/api/v1/create_session` | 创建对话 Session |
| `POST` | `/api/v1/chat` | 发送消息，返回 Agent 响应 |
| `POST` | `/api/v1/chat_stream` | SSE 流式对话 |

### 对话接口示例

```bash
curl -X POST http://localhost:8091/api/v1/chat \
 -H "Content-Type: application/json" \
 -d '{
 "agentId": "drawioagent",
 "userId": "demo_user",
 "sessionId": "sess_001",
 "message": "画一个三层架构：前端Next.js、后端Spring Boot、数据库MySQL，用箭头标注数据流向"
 }'
```

响应中包含 `type: "drawio"` 的消息，前端会自动渲染到画布。

---

## 🧭 Agent 内部工作流

一个完整的绘图请求在 Agent 内部经过如下流程：

```
用户输入 "画微服务架构图"
 │
 ▼
┌───────────────────┐
│ RootNode │ ← 接收用户原始输入
│ 意图解析 │
└────────┬──────────┘
 │
 ▼
┌───────────────────┐
│ ChatModelNode │ ← 调用 LLM (GPT/Claude/DeepSeek...)
│ 需求理解 + 检索 │ MCP 工具：百度搜索补充技术细节
└────────┬──────────┘
 │
 ▼
┌───────────────────┐
│ AgentNode │ ← 可选的工作流编排
│ Sequential/ │ 多 Agent 协作处理复杂图表
│ Parallel/Loop │
└────────┬──────────┘
 │
 ▼
┌───────────────────┐
│ RunnerNode │ ← 最终输出 draw.io XML
│ 生成 XML 模板 │ 格式化、自检、修正
└────────┬──────────┘
 │
 ▼
 {"type": "drawio", "content": "<mxGraphModel>..."}
 │
 ▼
 前端 react-drawio 实时渲染 🎉
```

---

## 🔧 Agent 自定义配置

你可以通过环境变量灵活切换 LLM 和工具链：

```bash
# 换个模型试试 Claude
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_AI_API_BASE_URL=https://api.anthropic.com
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_AI_API_API_KEY=sk-ant-xxx
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_CHAT_MODEL_MODEL=claude-3-opus

# 接入你自己的 MCP 服务
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_CHAT_MODEL_TOOL_MCP_LIST_0_SSE_NAME=my-tool
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_CHAT_MODEL_TOOL_MCP_LIST_0_SSE_BASE_URI=https://my-mcp-server
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_CHAT_MODEL_TOOL_MCP_LIST_0_SSE_SSE_ENDPOINT=sse
```

---

## 🎬 使用场景

- **系统设计评审** — 口头描述架构，即时生成可视化图表，省去拖拽时间
- **技术文档配图** — 写 README / 设计文档 / 论文时，用自然语言快速出图
- **教学演示** — 课堂上用对话方式逐步构建架构，学生直观理解组件关系
- **增量修改** — 先让 AI 生成初版，手动微调布局后，再让 AI 添加新模块

---

## 🛣️ 后续规划

- [ ] 支持导出为 PNG/SVG/PDF 多格式
- [ ] Agent Skills 热加载（无需重启即可添加新 Agent）
- [ ] 多模态输入（上传手绘草图 → AI 识别 → 生成规范图表）
- [ ] Langfuse / LangSmith 可观测性集成
- [ ] Kubernetes Helm Chart 部署方案
- [ ] 对话模板市场（社区贡献 Prompt 模板）

---

## 📄 License

Apache License 2.0


 
 ⭐ 如果这个项目对你有帮助，欢迎给个 Star： 
 <a href="https://github.com/lechan775/ai-agent-drawio">github.com/lechan775/ai-agent-drawio</a>
 


---


 
 Built with ❤️ by <a href="https://github.com/lechan775">@lechan775</a> ·
 基础架构源自 <a href="https://bugstack.cn">小傅哥</a> 的 DDD 脚手架

🎨 AI Agent Draw.io：用自然语言「说」出一张架构图

> **论文**：*StarNet-Pose: Heatmap-Free Lightweight Pose Estimation via Multiplicative Feature Interaction and Occlusion-Aware Training*
>
> **期刊**：Neurocomputing (2026)
>
> **作者**：Zheng Luo, Guowei Jiang, Runhang Pan, Qi Qi, Xin Xie, Siyuan Chen
>
> **仓库**：<https://github.com/lechan775/starnet-pose>

---

## 1. 动机：轻量级姿态估计的"不可能三角"

人体姿态估计（2D Human Pose Estimation）在移动端部署、AR/VR、运动分析等场景中对**精度-速度-参数量**三者之间存在持续的张力。以 RTMPose 为代表的轻量级方案在实时性上表现优异，但在 COCO val2017 上的 AP 长期停留在 68-72 AP 区间，与重量级模型（如 ViTPose、HRNet-W48）存在约 5-8 AP 的差距。

问题的核心在于：**主流轻量级 backbone（CSPNeXt、MobileNet、Lite-HRNet）采用加法式特征融合（加性残差连接、通道拼接），在高纬度特征空间中表达效率不足。**

StarNet-Pose 的核心思路是：**将乘法特征交互引入姿态估计 backbone，用更少的参数编码更丰富的特征表征。**

---

## 2. 核心贡献

### 2.1 StarNet Backbone：来自 CVPR 2024 的"星操作"

StarNet 由 Xu Ma 等人在 CVPR 2024 提出，其核心模块 **StarBlock** 将输入特征拆分为两条分支，分别经 Depthwise 7×7 Conv 和 ReLU6 激活后，做**逐元素乘法**（element-wise product）而非加法融合：

```
f1 = ReLU6(DWConv7×7(x))
f2 = DWConv7×7(x)
g = f1 ⊙ f2 # 逐元素乘法 — 而非加法
out = DWConv2(g) + x # 残差连接
```

乘法操作将特征空间从线性展开升级为**多项式展开**，等效于在低维参数空间中隐式构造高维交互项。实验表明，同等参数量下 StarNet 的表征能力显著优于 CSPNeXt 和 Lite-HRNet。

### 2.2 Heatmap-Free 检测头：RTMCC (SimCC)

StarNet-Pose 延续 RTMPose 的 **SimCC 头**（简单坐标分类），直接在 backbone 输出的 1D 特征上做关键点坐标分类，**全程不生成热力图**。相比热力图方案（需上采样至输入分辨率 1/4），SimCC 头将计算量压缩了一个数量级，是达成 300+ FPS 的关键设计选择。

### 2.3 Coordinate Attention：轻量级空间感知

在 StarNet-Pose-S 中，Stage 3 和 Stage 4 的 StarBlock 内部嵌入了 **Coordinate Attention (CA)** 模块（Hou et al., CVPR 2021）。CA 将通道注意力分解为高度和宽度方向的两个 1D 池化编码，在几乎不增加参数量（+0.08M）的前提下，弥补了乘法交互对空间位置信息感知的不足。

### 2.4 遮挡感知训练：CoarseDropout 策略

针对 OCHuman 等重度遮挡场景，系统评估了 CoarseDropout 数据增强策略的影响。核心发现：

- **固定概率 p=0.6** 优于 RTMPose 原生的 1.0→0.5 衰减调度
- 在 COCO-mini 上，StarNet-S1 + fixed p=0.6 达到 **47.48 AP**，比 RTMPose-T 基线（42.14 AP）提升 **+5.34 AP**
- 无需引入额外模块，仅靠数据增强即可获得显著遮挡鲁棒性提升

---

## 3. 模型规格与性能

### 3.1 两种变体

| 指标 | StarNet-Pose-T (Tiny) | StarNet-Pose-S (Small) |
|---|---|---|
| Backbone | StarNet-S1 | StarNet-S3 + CA |
| 参数量 | **3.504 M** | 6.428 M |
| 计算量 | **0.435 GFLOPs** | 0.765 GFLOPs |
| 检测头 | RTMCCHead (192-ch) | RTMCCHead (256-ch) |
| 输入尺寸 | 256×192 | 256×192 |

### 3.2 COCO val2017 主结果

| 模型 | Backbone | Params↓ | GFLOPs↓ | AP↑ | AP⁵⁰↑ | AP⁷⁵↑ | AR↑ |
|---|---|---|---|---|---|---|---|
| RTMPose-t | CSPNeXt-t | 3.34 | 0.360 | 68.20 | 88.30 | 75.90 | 73.60 |
| RTMPose-s | CSPNeXt-s | 5.47 | 0.680 | 71.60 | 89.20 | 78.90 | 76.80 |
| Lite-HRNet-30 | Lite-HRNet-30 | 1.80 | 0.319 | 67.20 | 88.00 | 75.00 | 73.30 |
| LMFormer-L | LMFormer-L | 4.10 | 1.400 | 68.90 | 88.30 | 76.40 | 74.70 |
| **StarNet-Pose-T** | StarNet-S1 | 3.504 | 0.435 | **72.00** | **91.51** | **79.62** | **75.03** |
| **StarNet-Pose-S** | StarNet-S3+CA | 6.428 | 0.765 | **72.99** | **91.64** | **80.69** | **76.01** |

**关键比对**：

- **StarNet-Pose-T vs RTMPose-t**：参数接近（3.50M vs 3.34M），AP 提升 **+3.80**
- **StarNet-Pose-S vs RTMPose-s**：参数接近（6.43M vs 5.47M），AP 提升 **+1.39**
- **StarNet-Pose-T 以 3.5M 参数达到 72.00 AP**，此量级此前无模型突破 70 AP

### 3.3 推理速度（RTX 5090, batch=1, 256×192）

| 模型 | Params (M) | Latency (ms)↓ | FPS↑ | AP↑ |
|---|---|---|---|---|
| Lite-HRNet-18 | 1.10 | 18.14 | 55.1 | 64.80 |
| RTMPose-t | 3.34 | 3.51 | 285.1 | 68.20 |
| **StarNet-Pose-T** | 3.504 | **3.19** | **313.8** | **72.00** |
| RTMPose-s | 5.47 | 3.71 | 269.6 | 71.60 |
| **StarNet-Pose-S** | 6.428 | 5.76 | 173.5 | **72.99** |

**StarNet-Pose-T 在 RTX 5090 上达到 313.8 FPS，同时 AP 超过 RTMPose-t 3.8 个点。** 这是目前同类轻量级姿态估计器中精度-速度综合最优的方案。

---

## 4. 消融实验

### 4.1 注意力机制对比（COCO-mini, 210 epochs）

| 配置 | AP | AP⁵⁰ | AP⁷⁵ | AR |
|---|---|---|---|---|
| StarNet baseline (无注意力) | **50.62** | 77.94 | **54.08** | **54.42** |
| StarNet + CBAM | 49.54 | 77.21 | 54.47 | 53.35 |
| StarNet + CA | 49.65 | **78.15** | 51.26 | 53.46 |

CA 对高 IoU 阈值下的精度帮助有限（AP⁷⁵ 下降 2.82），但在 AP⁵⁰ 上略有提升。最终选择 CA 作为可选的轻量级空间增强模块。

### 4.2 遮挡增强策略对比（COCO-mini, StarNet-S1/Tiny）

| 配置 | Backbone | CoarseDropout | AP |
|---|---|---|---|
| RTMPose-T baseline | CSPNeXt-Tiny | 1.0→0.5 衰减 | 42.14 |
| StarNetCA-S1 | StarNet-S1 | 1.0→0.5 衰减 | 46.86 |
| StarNetCA-S1 + fixed | StarNet-S1 | 固定 p=0.6 | 47.13 |
| **StarNet-S1 + fixed** | **StarNet-S1** | **固定 p=0.6** | **47.48** |

固定概率 CoarseDropout 优于衰减调度，且去掉 CA 反而带来 0.35 AP 增益，表明乘法交互自身已具备足够的表征鲁棒性。

---

## 5. 技术栈与兼容性

- **框架**：基于 OpenMMLab MMPose，完整兼容其训练/评估/部署工具链
- **骨干网络**：StarNet-S1/S3（CVPR 2024）
- **检测头**：RTMCCHead / SimCC（Heatmap-Free）
- **注意力模块**：Coordinate Attention（CVPR 2021）
- **数据增强**：CoarseDropout（Albumentations）
- **许可证**：Apache 2.0

---

## 6. 局限与展望

1. **高分辨率输入**：当前仅验证 256×192 输入。StarNet 在 384×288 下的 AP 上界尚未探索。
2. **密集人群**：Top-down 范式依赖人体检测器，在遮挡密集场景中检测器失效会级联影响姿态估计。
3. **CA 模块的二重性**：CA 在微调阶段对 AP 提升有限（+0.15），其收益可能集中在特定遮挡或小目标场景。
4. **端侧部署**：目前未做 TensorRT/NCNN/MNN 量化部署验证，313.8 FPS 为 PyTorch 直接推理指标，端侧实测算力上限待补充。

后续工作方向包括：高分辨率输入下的 StarNet-Pose 性能上界分析、Bottom-up 范式下的 StarNet 适配、以及端侧量化部署验证。

---

## 7. 引用

```bibtex
@article{pan2025starnetpose,
 title = {StarNet-Pose: Heatmap-Free Lightweight Pose Estimation via
 Multiplicative Feature Interaction and Occlusion-Aware Training},
 author = {Zheng Luo and Guowei Jiang and Runhang Pan and Qi Qi and Xin Xie and Siyuan Chen},
 journal = {Neurocomputing},
 year = {2026},
 url = {https://github.com/lechan775/starnet-pose}
}
```

---

*本文基于 StarNet-Pose 仓库 README 与论文内容整理，项目代码以 Apache 2.0 协议开源于 [GitHub](https://github.com/lechan775/starnet-pose)。*

StarNet-Pose：乘法特征交互驱动的无热力图轻量级人体姿态估计

# mobile-open-claw：基于 Google ADK 构建移动端 AI Agent 应用的全栈实践

> **GitHub 仓库**：[lechan775/mobile-open-claw](https://github.com/lechan775/mobile-open-claw) ⚠️ 私有仓库 
> **后端**：Spring Boot 3.4.3 + Google ADK 0.5.0 + D Domain-Driven Design 
> **前端**：Android Jetpack Compose + Nginx 静态 Web 页面 
> **核心能力**：多智能体自动装配 · MCP 协议集成 · 并行/串行/循环工作流 · SSE 流式对话

---

## 一、项目定位

mobile-open-claw 是一套**移动端 AI Agent 全栈应用**，解决的核心问题是：**如何在一套工程框架内，以声明式配置（YAML）快速定义、装配和运行多个 AI Agent，并通过统一的 REST API 对外暴露对话能力**。

它的设计初衷是降低 AI Agent 应用的工程门槛——你只需要写一份 YAML 配置文件，就可以得到一个拥有 MCP 工具调用、多智能体协作能力、且同时支持 Web 和 Android 客户端的完整应用。

---

## 二、核心架构

### 2.1 整体分层

```mermaid
graph TB
 subgraph Clients["客户端层"]
 Web["🌐 Nginx 静态页面 login.html + index.html"]
 Android["📱 Android App Jetpack Compose + Material3"]
 end

 subgraph Trigger["触发器层 (Trigger)"]
 Controller["AgentServiceController REST API + SSE Stream"]
 end

 subgraph App["应用编排层 (App)"]
 AutoConfig["AiAgentAutoConfig 启动时自动装配 Agent"]
 end

 subgraph Domain["领域层 (Domain) - 核心"]
 Armory["🔧 ArmoryService Agent 装配流水线"]
 Chat["💬 ChatService 会话管理与对话调度"]
 MCP["🔌 MCP 协议 Stdio / SSE / Local"]
 Skills["📦 Skills 技能系统"]
 Workflow["⚙️ Agent 工作流 Parallel / Sequential / Loop"]
 end

 subgraph Infra["基础设施层 (Infrastructure)"]
 DAO["MyBatis DAO"]
 Gateway["外部 Gateway"]
 Redis["Redis 缓存"]
 end

 Web --> Controller
 Android --> Controller
 Controller --> Chat
 AutoConfig --> Armory
 Armory --> Workflow
 Armory --> MCP
 Armory --> Skills
 Chat --> Armory
 Domain --> Infra
```

### 2.2 DDD 六模块划分

| 模块 | 职责 | 关键类 |
|------|------|--------|
| **api** | 接口契约定义 | `IAgentService`, DTOs |
| **app** | 应用启动 & 自动装配 | `Application`, `AiAgentAutoConfig` |
| **domain** | 领域模型 & 核心逻辑 | `ArmoryService`, `ChatService`, Agent 节点树 |
| **infrastructure** | 数据访问 & 外部集成 | DAO, Gateway, Redis |
| **trigger** | HTTP 控制器 & 事件监听 | `AgentServiceController` |
| **types** | 公共枚举/常量/异常 | `ResponseCode`, `AppException` |

---

## 三、Agent 装配流水线：声明式配置 → 运行时 Agent

这是整个项目最核心的设计——**基于责任链模式的 Agent 自动装配引擎**。

### 3.1 YAML 配置示例

```yaml
ai:
 agent:
 config:
 enabled: true
 tables:
 myAgent:
 app-name: MyAssistant
 agent:
 agent-id: 100001
 agent-name: 通用助手
 agent-desc: 支持百度搜索的通用对话助手
 module:
 ai-api:
 base-url: https://apis.xxx.cn
 api-key: sk-xxx
 completions-path: v1/chat/completions
 chat-model:
 model: gpt-4.1
 tool-mcp-list: # MCP 工具列表
 - sse:
 name: baidu-search
 base-uri: http://appbuilder.baidu.com/v2/ai_search/mcp/
 sse-endpoint: sse?api_key=xxx
 - local:
 name: myToolCallbackProvider # 本地工具
 tool-skills-list: # Skills 技能
 - type: resource
 path: agent/skills
 agents:
 - name: assistant
 description: 通用AI助手
 instruction: |
 你是一个全能的AI助手，可以使用百度搜索获取最新信息。
 runner:
 agent-name: assistant
```

### 3.2 装配流水线

应用启动时，`AiAgentAutoConfig` 监听 `ApplicationReadyEvent`，触发以下装配流程：

```mermaid
flowchart LR
 Start(["🚀 应用启动"]) --> Config["读取 YAML 配置 AiAgentAutoConfigProperties"]
 Config --> Factory["DefaultArmoryFactory 构建责任链"]
 Factory --> AiApi["AiApiNode 创建 OpenAI API 客户端"]
 AiApi --> ChatModel["ChatModelNode 装配 ChatModel + MCP + Skills"]
 ChatModel --> Agent["AgentNode 逐条注册 LlmAgent"]
 Agent --> Workflow{"存在 AgentWorkflow?"}
 Workflow -->|Parallel| PNode["ParallelAgentNode 并行执行"]
 Workflow -->|Sequential| SNode["SequentialAgentNode 串行执行"]
 Workflow -->|Loop| LNode["LoopAgentNode 循环迭代"]
 Workflow -->|无| Runner["RunnerNode 注册 InMemoryRunner"]
 PNode --> Runner
 SNode --> Runner
 LNode --> Runner
 Runner --> Done(["✅ Agent 就绪"])
```

### 3.3 责任链节点设计

```java
// 每个 Node 继承 AbstractArmorySupport，实现策略路由
@Service
public class ChatModelNode extends AbstractArmorySupport {
 @Override
 protected AiAgentRegisterVO doApply(ArmoryCommandEntity param, DynamicContext ctx) {
 // 1. 构建 Spring AI ChatModel
 // 2. 注入 MCP 工具回调（Stdio/SSE/Local）
 // 3. 注入 Skills 技能
 // 4. 路由到下一个节点
 return router(requestParameter, dynamicContext);
 }

 @Override
 public StrategyHandler<...> get(...) {
 return agentNode; // 下一站：AgentNode
 }
}
```

> 责任链模式来自 `xfg-wrench-starter-design-framework`（@小傅哥的设计模式框架），每个 Node 只关心自己的装配逻辑，通过 `router()` 传递到下一节点。

---

## 四、多智能体工作流

mobile-open-claw 支持三种 Agent 编排模式，直接封装自 Google ADK：

### 4.1 并行执行（Parallel）

多个子 Agent 同时运行，互不依赖，适用于多维度信息收集：

```yaml
agent-workflows:
 - type: parallel
 name: ParallelResearch
 sub-agents:
 - RenewableEnergyResearcher # 研究可再生能源
 - EVResearcher # 研究电动车技术
 - CarbonCaptureResearcher # 研究碳捕获
```

### 4.2 串行执行（Sequential）

Agent 按顺序执行，后续 Agent 可引用前置 Agent 的输出（通过 `output-key` + `{}` 占位符）：

```yaml
agent-workflows:
 - type: sequential
 name: ResearchAndSynthesis
 sub-agents:
 - ParallelResearch # 先并行研究
 - SynthesisAgent # 再汇总生成报告
```

### 4.3 循环执行（Loop）

子 Agent 迭代执行直到收敛或达到 `maxIterations`：

```yaml
agent-workflows:
 - type: loop
 name: SelfImprovingWriter
 max-iterations: 3
 sub-agents:
 - DraftAgent
 - ReviewAgent
```

---

## 五、MCP 协议集成

支持三种 MCP (Model Context Protocol) 工具接入模式，覆盖本地到远程的全部场景：

| 模式 | 通信方式 | 实现类 | 适用场景 |
|------|----------|--------|----------|
| **Stdio** | 标准输入输出进程 | `StdioToolMcpCreateService` | 本地命令行工具 |
| **SSE** | HTTP Server-Sent Events | `SSEToolMcpCreateService` | 远程 MCP Server |
| **Local** | JVM 直接调用 | `LocalToolMcpCreateService` | Spring Bean 方法 |

```java
// SSE 模式核心实现
HttpClientSseClientTransport transport = HttpClientSseClientTransport
 .builder(baseUri)
 .sseEndpoint(sseEndpoint)
 .build();

McpSyncClient client = McpClient.sync(transport)
 .requestTimeout(Duration.ofMillis(500000))
 .build();

ToolCallback[] callbacks = SyncMcpToolCallbackProvider.builder()
 .mcpClients(client)
 .build()
 .getToolCallbacks();
```

---

## 六、REST API 接口

基础路径：`/api/v1/` | 端口：`8091` | CORS：全部开放

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/query_ai_agent_config_list` | 获取可用 Agent 列表 |
| `POST` | `/api/v1/create_session` | 创建对话会话 |
| `POST` | `/api/v1/chat` | 提交对话（同步） |
| `POST` | `/api/v1/chat_stream` | 流式对话（SSE） |

统一响应结构：

```json
{
 "code": "0000",
 "info": "成功",
 "data": { "content": "..." }
}
```

---

## 七、技术栈一览

| 层级 | 技术 | 版本 |
|------|------|------|
| AI 编排引擎 | Google ADK | 0.5.0 |
| AI 框架 | Spring AI | 1.1.0-M3 |
| | LangChain4j | 1.4.0 |
| 后端框架 | Spring Boot | 3.4.3 |
| 语言 | Java | 17 |
| ORM | MyBatis | 3.0.4 |
| 数据库 | MySQL | 8.x |
| 缓存 | Guava Cache | 32.1.3-jre |
| Android UI | Jetpack Compose + Material3 | — |
| Web 前端 | 原生 HTML/CSS/JS (Nginx) | — |
| 容器化 | Docker + Docker Compose | — |

---

## 八、快速启动

### 环境要求

- Java 17+
- Maven 3.8+
- MySQL 8.x
- Docker（可选）

### 三步运行

```bash
# 1. 克隆仓库
git clone https://github.com/lechan775/mobile-open-claw.git
cd mobile-open-claw/mobile-open-claw

# 2. 配置 application-dev.yml 中的数据库连接 & API Key

# 3. 启动
cd mobile-open-claw-app
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

访问 `http://localhost:8091` 即可使用。

### Docker 一键部署

```bash
cd docs/dev-ops
docker-compose -f docker-compose-environment.yml up -d # MySQL 等基础设施
docker-compose -f docker-compose-app.yml up -d # Nginx + 应用
```

---

## 九、项目结构

```
openclaw_andro/
├── mobile-open-claw/ # 🔧 后端 (Spring Boot + DDD)
│ ├── mobile-open-claw-api/ # API 接口契约层
│ ├── mobile-open-claw-app/ # 应用启动 & 自动配置
│ ├── mobile-open-claw-domain/ # 领域核心（Agent/Workflow/MCP/Skills）
│ ├── mobile-open-claw-infrastructure/ # 基础设施（DAO/Gateway/Redis）
│ ├── mobile-open-claw-trigger/ # HTTP 控制器 & 事件触发
│ ├── mobile-open-claw-types/ # 公共类型 & 异常
│ └── docs/ # 部署脚本 & 开发文档
│
└── mobileopenclawgateway/ # 📱 Android 前端 (Jetpack Compose)
 └── app/
 └── src/main/java/cn/bugstack/ai/mobileopenclawgateway/
```

---

## 十、致谢

- 后端 DDD 脚手架及设计模式框架来自 [@小傅哥](https://github.com/fuzhengwei) 的 `xfg-frame-archetype` v2.2
- Agent 编排能力基于 [Google ADK](https://github.com/google/adk-java)
- AI 对话能力由 Spring AI & LangChain4j 社区驱动

---

## 🔗 相关链接

- **GitHub 仓库**：[lechan775/mobile-open-claw](https://github.com/lechan775/mobile-open-claw)
- 原作者博客：[bugstack.cn](https://bugstack.cn)
- Google ADK 文档：[google.github.io/adk-docs](https://google.github.io/adk-docs/)

---

*本文发布于 2026 年 5 月，项目持续迭代中。*

mobile-open-claw：基于 Google ADK 构建移动端 AI Agent 应用的全栈实践

# BSDPose：面向羽毛球击球动作识别与质量评估的开源框架

> 基于 YOLOv8-Pose、CBAM 注意力机制与运动学特征分析，六分类击球动作识别 + 0~100 质量评分，单条多任务流水线一步到位。

---

## 1. 项目背景

羽毛球击球动作的自动识别与质量评估，在智能训练辅助、比赛战术分析等场景中具有明确应用价值。然而目前该领域存在三方面瓶颈：

- **动作差异细微**：正手/反手高远球、杀球、网前挑球等六类动作在空间上高度相似，常规 CNN 特征难以区分。
- **运动模糊严重**：挥拍阶段帧间位移大，关键点定位精度受严重挑战。
- **质量评分子任务缺失**：多数工作仅做分类，缺乏连续的 0~100 质量评分输出。

BSDPose 在此基础上提出了一套完整的端到端方案，同时在两个子任务上验证了方法有效性。

---

## 2. 核心方法

整体流水线如下：

```
VideoBadminton (.mp4)
        │
        ▼  16帧滑动窗口采样
┌───────────────────────────────┐
│  YOLOv8-Pose + CBAM          │  ← 关键点估计（17点 COCO 格式）
│  PAN FPN 的 P3/P4/P5 注入     │     mAP@0.5:0.95 = 83.46%
│  Channel + Spatial Attention  │
└───────────────────────────────┘
        │
        ▼  每帧 17 个关键点 (x, y, conf)
┌───────────────────────────────────┐
│  运动学特征提取                    │
│  15 维逐帧特征 → 16 帧窗口聚合     │
│  → 62 维特征向量 (mean/std/max/min) │
│  含：关节角度 / 躯干倾角 / 手腕速度  │
│       / 质心位移 / 肢体长度比 等      │
└───────────────────────────────────┘
        │
        ▼
┌───────────────────────────────────┐
│  多任务预测头                      │
│  Shared Encoder: 62 → 128 → 64    │
│  ┌────────────────┬──────────────┐ │
│  │ 分类分支 64→32→6 │ 回归分支     │ │
│  │ Softmax (6类)   │ 64→32→1      │ │
│  │                 │ Sigmoid×100  │ │
│  └────────────────┴──────────────┘ │
│  L = CrossEntropy + 0.5 × MSE      │
└───────────────────────────────────┘
        │
        ▼
  [击球类别 (0~5)] + [质量评分 (0~100)]
```

### 2.1 CBAM 增强的 YOLOv8-Pose

在 YOLOv8-Pose 的 PAN FPN 结构中，对 P3、P4、P5 三个尺度的输出特征图注入 CBAM（Convolutional Block Attention Module）——依次施加通道注意力与空间注意力，使网络在运动模糊场景下更聚焦于人体关键区域，关键点定位精度提升 **+1.00 pp**（82.46% → 83.46%）。

### 2.2 15 维运动学特征工程

从 COCO-17 格式的关键点坐标中手工提取 15 个运动学指标，覆盖三个维度：

| 类别 | 特征示例 |
|------|----------|
| **关节角度** | 右肘角、右肩角、右膝角、右髋角 |
| **姿态几何** | 躯干倾角、两肩连线水平角 |
| **运动学量** | 手腕合速度、质心位移、肢体长度比 |

以 16 帧为窗口，逐窗口计算均值、标准差、最大值、最小值四种聚合统计量，最终得到 **62 维**固定长度特征向量。相比直接使用关键点坐标（34 维），手工特征具有更强的物理可解释性和更低的纬度。

### 2.3 多任务联合学习

设计共享编码器 + 双分支结构：
- **分类分支**：6 类击球动作 Softmax 输出
- **回归分支**：0~100 连续质量评分 Sigmoid 输出
- **联合损失**：`L = L_CE + 0.5·L_MSE`

多任务学习不仅统一了流水线，质量回归的辅助任务还产生了正则化效果——在消融实验中，加入回归分支后分类准确率从 53.48% 提升至 **57.78%**（+4.30 pp）。

---

## 3. 六类击球动作

| 编号 | 英文 | 中文 |
|------|------|------|
| 0 | Forehand Clear | 正手高远球 |
| 1 | Backhand Clear | 反手高远球 |
| 2 | Forehand Smash | 正手杀球 |
| 3 | Backhand Smash | 反手杀球 |
| 4 | Forehand Net Lift | 正手网前挑球 |
| 5 | Backhand Net Lift | 反手网前挑球 |

---

## 4. 实验结果

### 4.1 姿态估计（BSD 测试集）

| 模型 | mAP@0.5:0.95 (%) |
|------|-------------------|
| YOLOv8-Pose (baseline) | 82.46 |
| + SE Attention | 82.19 |
| + CBAM (ours) | **83.46** |

> SE 注意力未能在该任务上带来增益（82.19% vs. 82.46%），CBAM 的空间注意力分支在运动模糊场景下更具优势。

### 4.2 击球动作分类（BSD 测试集）

| 方法 | Accuracy (%) | Precision (%) | Recall (%) | F1 (%) |
|------|:-----------:|:------------:|:---------:|:------:|
| OpenPose + LSTM | 45.79 | 44.00 | 45.79 | 43.49 |
| YOLOv8-Pose + LSTM | 46.15 | 44.00 | 46.15 | 43.29 |
| YOLOv8-Pose + Kinematic + MLP | 56.78 | 57.80 | 56.78 | 57.11 |
| **YOLOv8-Pose + CBAM + Kinematic + Multi-Task (ours)** | **57.78** | **58.80** | **57.78** | **58.11** |

### 4.3 消融实验

| Pose Model | CBAM | Kinematic | Multi-Task | Accuracy (%) | Quality MAE |
|:----------:|:----:|:---------:|:----------:|:-----------:|:-----------:|
| YOLOv8-Pose | ✗ | ✗ | ✗ | 46.15 | — |
| YOLOv8-Pose | ✓ | ✗ | ✗ | 44.50 | — |
| YOLOv8-Pose | ✗ | ✓ | ✓ | 53.48 | 2.41 |
| **YOLOv8-Pose** | **✓** | **✓** | **✓** | **57.78** | **2.20** |

### 4.4 关键发现

1. **CBAM 单独无法提升分类**：与原始 LSTM 结合时反而下降（44.50% vs. 46.15%）。CBAM 的价值在于提供更精准的关键点→进而提升运动学特征的质量，而非直接辅助分类器。
2. **CBAM + 运动学特征存在协同效应**：两者结合后准确率提升 +4.30 pp（53.48% → 57.78%）。
3. **多任务头压缩质量评估误差**：MAE 从 2.41 降至 2.20，联合训练的分类分支也有正向收益。

---

## 5. 快速上手

```bash
# 1. 克隆仓库
git clone https://github.com/lechan775/BSDPose.git
cd BSDPose
pip install -r requirements.txt

# 2. 准备 BSD 数据集（需先下载 VideoBadminton）
python scripts/prepare_bsd.py \
    --source-root data/pose \
    --output-root data/bsd \
    --window-size 16 --seed 42

# 3. 训练姿态估计（三种变体）
python train/train_pose.py --variant all --epochs 200 --batch 16

# 4. 训练分类器
python train/train_classifier.py --variant cbam_kinematic_multitask

# 5. 评估
python eval/eval_pose.py
python eval/eval_classifier.py
python eval/eval_ablation.py
```

依赖：`torch>=2.0` / `ultralytics>=8.0` / `opencv-python` / `pyyaml` / `numpy`

---

## 6. 项目结构

```
BSDPose/
├── models/                 # CBAM/SE 模块 & YOLOv8-Pose 注入逻辑
├── features/
│   └── kinematic.py        # 15维逐帧特征 → 62维窗口聚合
├── classifier/
│   ├── multi_task_head.py  # 多任务头、损失函数、MLP/LSTM基线
│   └── dataset.py          # 特征数据加载器
├── train/                  # 训练脚本（姿态估计 & 分类器）
├── eval/                   # 评估脚本（mAP / Acc / MAE / 消融）
├── scripts/
│   └── prepare_bsd.py      # VideoBadminton → BSD 数据集构建
├── configs/config.yaml     # 超参数 & 实验矩阵
└── paper/journal_draft.md  # 论文手稿（Markdown）
```

---

## 7. 引用

本项目配套论文发表于《湖南理工学院学报（自然科学版）》（2026）：

```bibtex
@article{bsdpose2026,
  title     = {{基于YOLOv8-Pose与运动学特征分析的羽毛球击球动作识别与质量评估研究}},
  author    = {胡竞文 and 罗正 and 潘润杭 and 范飞豪},
  journal   = {湖南理工学院学报(自然科学版)},
  year      = {2026},
  note      = {Submitted}
}
```

---

## 8. 相关信息

- **BSD 数据集**：衍生自 [VideoBadminton](https://github.com/qilimk/VideoBadminton) 公开基准，按 16 帧窗口切分并重新标注
- **开源协议**：MIT License，学术与商业用途自由
- **仓库地址**：[github.com/lechan775/BSDPose](https://github.com/lechan775/BSDPose)

---

*Written on 2026-05-25 by 探微 (Hanako AI Agent)*
