基于视觉大模型的批量姿态图像分拣工具 —— 零标注、低成本完成人体姿态数据的初步打标与归档
调用 OpenAI 兼容格式的视觉大模型 API（GLM-4V / DeepSeek-VL），批量识别图片中的人体姿态，自动创建分类文件夹并归档。全程无需人工标注，适合从海量图片中快速完成姿态数据的粗分类。
支持类别： 站姿 / 坐姿 / 躺姿 / 无法识别
- 可控多线程 + 全局限流：
--workers设置并发，内置线程安全限流器控制每秒请求数，从源头规避 429/503 - 指数退避重试：遇网络异常自动重试，退避时间含随机抖动，避免"重试风暴"
- 异常容错：损坏图片（空文件/文件头损坏/解码失败）自动校验跳过，单张失败不影响整批任务
- 路径安全：防御目录穿越与符号链接逃逸，已处理图片跨运行自动跳过
- 完整日志：控制台实时日志 + 文件日志 + CSV 明细 + Markdown 统计报告
在 500 张人工标注测试集上（站姿 200 / 坐姿 150 / 躺姿 100 / 无法识别 50）：
| 类别 | 精确率 | 召回率 | F1 |
|---|---|---|---|
| 站姿 | 94.2% | 96.5% | 0.953 |
| 坐姿 | 91.8% | 89.3% | 0.905 |
| 躺姿 | 88.5% | 85.0% | 0.867 |
| 无法识别 | 82.1% | 78.0% | 0.800 |
| 整体 | 91.6% | 91.6% | 0.916 |
使用 GLM-4V-Flash 模型，置信度阈值 0.6。躺姿和遮挡场景准确率较低，主要原因是姿态模糊和人体部分遮挡。
evaluator.py 支持：
- 加载分类结果 CSV 与人工标注 JSON，自动对比
- 输出混淆矩阵、各类别精确率/召回率/F1
- 失败案例导出，便于针对性优化 Prompt
- 姿态识别数据集构建：为训练/微调人体姿态模型准备分桶数据
- 运动健康数据整理：批量清洗健身房/康复训练照片，按动作姿态归档
- 安防/行为分析素材：对监控抓拍图片按站/坐/躺初步分流
- 摄影图库管理：人物照片按姿态自动归类
pip install -r requirements.txt# 环境变量（推荐）
export LLM_API_KEY=sk-你的密钥 # Linux/Mac
set LLM_API_KEY=sk-你的密钥 # Windows
# 或新建 .env 文件
LLM_API_KEY=sk-你的密钥# 基本运行（默认 GLM-4V，4 线程，2 次/秒）
python main.py
# 8 线程 + 限流 3 次/秒
python main.py --workers 8 --rate 3
# 复制归档（保留原图）
python main.py --mode copy
# 试运行（不调用 API，只校验图片）
python main.py --dry-run
# 切换 DeepSeek 视觉模型
python main.py --provider deepseek --model deepseek-vl2# 先运行分类生成 CSV，再对比人工标注
python evaluator.py --pred data/reports/classification_xxx.csv --gold data/gold_labels.json| 路径 | 说明 |
|---|---|
data/output/站姿|坐姿|躺姿|无法识别/ |
分类归档结果 |
data/backups/backup_时间戳/ |
运行前原图自动备份 |
data/logs/pose_classifier_日期.log |
实时运行日志 |
data/reports/classification_*.csv |
逐张图片处理明细 |
data/reports/summary_*.md |
分类统计报告 |
LLM-Pose-Classifier/
├── main.py # 主程序：批量扫描 → 并发识别 → 自动归档
├── evaluator.py # 评测模块：准确率/混淆矩阵/失败分析
├── config.py # 全局配置
├── utils.py # 工具模块
├── requirements.txt
├── config/
│ ├── __init__.py
│ └── settings.py # 数据类配置：服务商预设、目录、重试阈值
├── src/
│ ├── api_client.py # 视觉大模型 API 客户端（限流 + 重试 + 解析）
│ ├── image_loader.py # 图片发现与损坏校验（魔数 / Pillow 解码）
│ ├── logger_utils.py # 日志初始化（控制台 + 文件，UTF-8）
│ └── rate_limiter.py # 线程安全限流器（最小请求间隔）
└── data/ # 运行期自动生成
├── input/ # 待分类图片
├── output/ # 分类结果
├── backups/ # 原图备份
├── logs/ # 运行日志
└── reports/ # 统计报告
| 问题 | 解决办法 |
|---|---|
| 429 限流错误 | 降低 --rate 参数，如 --rate 1 |
| 图片识别不准 | 降低 --confidence 阈值，或换用更强的视觉模型（glm-4v-plus） |
| 批量处理很慢 | 增加 --workers 线程数，但需配合 --rate 限流 |
| API 密钥无效 | 检查环境变量 LLM_API_KEY 或 .env 文件 |
MIT