TimeSformer 实时动作识别系统

基于 FastAPI、Streamlit 和 facebook/timesformer-base-finetuned-k400 的视频动作识别系统，支持视频上传识别、实时摄像头连续帧识别、批量处理、历史记录统计与可视化。

项目结构

.
├── app.py                                # Streamlit 前端启动入口
├── backend.py                            # FastAPI 后端启动入口
├── start.sh                              # macOS / Linux 一键启动脚本
├── requirements.txt                      # Python 依赖
├── src/
│   └── timesformer_action_recognition/
│       ├── api.py                        # FastAPI 路由与请求处理
│       ├── config.py                     # 路径、端口、模型等配置
│       ├── frontend.py                   # Streamlit 页面与交互逻辑
│       ├── history.py                    # 识别历史读写
│       ├── inference.py                  # TimeSformer 加载与推理
│       ├── schemas.py                    # Pydantic 数据模型
│       └── system.py                     # 系统状态采集
├── components/camera/index.html          # 浏览器摄像头采集组件
├── data/recognition_history.json         # 历史识别记录
└── docs/local_run.md                     # 本地运行详细指南

功能

• 视频/图片上传识别：抽帧后调用 TimeSformer 输出 Top-5 动作概率。
• 实时摄像头识别：浏览器持续采集帧，后端按会话缓存 8 帧后自动推理。
• 批量处理：支持多视频顺序识别并导出 CSV。
• 历史记录：保存最近识别结果，展示置信度趋势、动作频率和来源分布。
• 系统监控：展示 CPU、内存、磁盘使用情况。

快速启动

推荐 Python 3.10 或 3.11。首次运行会从 Hugging Face 下载模型权重，耗时取决于网络。

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

chmod +x start.sh
./start.sh

访问地址：

• Web 界面：http://localhost:8501
• API 文档：http://localhost:8000/docs

手动启动

# 终端 1：后端
python3 backend.py

# 终端 2：前端
BACKEND_URL=http://localhost:8000 \
BACKEND_PUBLIC_URL=http://localhost:8000 \
python3 -m streamlit run app.py --server.port 8501

代码结构说明

• app.py 和 backend.py 只负责启动，便于本地运行和部署脚本保持简单。
• src/timesformer_action_recognition/config.py 统一管理路径、端口、模型名称和运行时目录。
• src/timesformer_action_recognition/inference.py 负责模型加载、视频帧采样和 Top-K 推理。
• src/timesformer_action_recognition/api.py 只保留 API 路由与请求编排。
• src/timesformer_action_recognition/frontend.py 负责 Streamlit 页面。

常用环境变量

变量	默认值	说明
TIMESFORMER_MODEL	facebook/timesformer-base-finetuned-k400	后端加载的模型名称
TIMESFORMER_HISTORY_FILE	data/recognition_history.json	历史记录文件路径
TIMESFORMER_UPLOAD_DIR	uploads	上传临时文件目录
TIMESFORMER_REALTIME_BUFFER_SIZE	8	实时识别触发推理所需帧数
BACKEND_URL	http://localhost:8000	Streamlit 服务端访问后端的地址
BACKEND_PUBLIC_URL	http://localhost:8000	浏览器摄像头组件访问后端的地址

API 概览

• GET /：后端健康状态和模型信息。
• GET /system/stats：系统资源使用情况。
• POST /predict：上传视频/图片进行动作识别。
• POST /realtime/frame：提交实时摄像头帧。
• GET /history：读取历史记录。
• DELETE /history：清空历史记录。

说明

实时摄像头功能需要浏览器允许摄像头权限。本地使用 http://localhost:8501 可以正常调用摄像头；如果部署到远程服务器，需要配置 HTTPS，并将 BACKEND_PUBLIC_URL 设置为浏览器可访问的后端地址。