🇨🇳 中文 ｜ English
A serverless video pre-labeling pipeline that automatically marks every
frame of in-cabin / dashcam footage as hands_on or hands_off. The
labeled CSV output is meant to be used as training data for in-vehicle
hands-off detection (HoD) models required by ADAS regulations.
这是一个为车内脱手检测模型自动生成训练标签的工具。
This is an automated labeling tool that produces training labels for in-vehicle driver hands-off detection (HoD) models.
车内摄像头视频 云端预标注 训练数据集
in-cabin video ─► auto-label per frame ─► labeled dataset
(.mp4 batch) (timestamp, label, (CSV + frames)
confidence) │
▼
车端 HoD 模型训练
train on-vehicle HoD model
车厂 / 一级供应商在量产符合法规要求的车端实时脱手检测模型（运行在车机 ECU 上的轻量 CNN）时，需要海量带帧级标签的车内视频。人工逐帧标注既慢又贵。 本项目用云端大模型（Bedrock Claude 3.7 Sonnet 或硅基流动 DeepSeek-R1）做 预标注，把人工标注员的工作从"打标签"降级为"审核标签"，大幅压缩成本和周期。
OEMs and Tier-1 suppliers training on-vehicle real-time HoD models need large amounts of frame-labeled in-cabin video to satisfy regulatory requirements. Manual per-frame labeling is slow and expensive. This project uses a cloud foundation model to pre-label the frames, turning human annotators into reviewers instead of labelers — cutting labeling cost and time substantially.
每条视频生成一份 CSV，每帧一行：
One CSV per video, one row per frame:
timestamp,frame,label,confidence
00:00:01.000,frame_0001.jpg,hands_on,0.94
00:00:02.000,frame_0002.jpg,hands_off,0.88
00:00:03.000,frame_0003.jpg,hands_on,0.91
...可直接喂给下游标注平台做人工审核 / 修正，或用作弱监督训练的伪标签。
This feeds directly into a downstream labeling tool for human review, or serves as pseudo-labels for weakly-supervised training.
车端 HoD 模型为什么是必须的：
Why on-vehicle HoD models are mandatory:
- 🇪🇺 / 联合国 ECE — UN R79 (LKAS) 启用车道保持时必须检测双手是否在方向盘上并告警
- 🇪🇺 — UN R157 (ALKS / L3) 必须持续监控驾驶员状态与接管能力
- 🇪🇺 — Regulation (EU) 2019/2144 (GSR)：DDAW 驾驶员疲劳警示（2024-07 全面强制）/ ADDW 分心警示（2026-07 全面强制）
- 🇨🇳 — GB 44495 / 44496 / 44497-2024 智能网联汽车三项强制国标；GB/T 39263-2020 ADAS 术语
- 🇺🇸 — NHTSA NCAP ADAS 评估已纳入驾驶员监控
这些法规共同的诉求：辅助驾驶激活时，车端必须实时识别驾驶员脱手并告警。 本项目不直接满足法规（不上车），但为车端模型训练提供数据。
The common thread: whenever ADAS is engaged, the vehicle must detect hands-off in real time and warn the driver. This project doesn't run in-vehicle — it produces the training data for the model that does.
- 🎬 Fargate 视频切割 — 长视频分段并行处理，比纯 Lambda 快得多
- ⚡ Step Functions 编排 — 上传即触发，全自动
- 🧠 多模型支持 — 全球区 AWS Bedrock（Claude 3.7 Sonnet）/ 中国区 硅基流动（DeepSeek-R1）
- 🌏 多分区适配 — 自动识别
aws / aws-cn / aws-us-gov，IAM ARN 自动适配 - 📊 CloudWatch 监控仪表板 + SNS 通知
- 🔧 集中式参数管理 — 所有可调项放在 Systems Manager Parameter Store
┌─ S3 (input/videos/) ──── upload triggers ────┐
│ │
▼ ▼
Lambda: trigger ──► Step Functions Workflow
│
┌─────────────────┼─────────────────┐
▼ ▼
Fargate: video_cutter (or) Lambda: video_processor
│ │
└────► S3 (processing/segments/) ◄──┘
│
Map state (parallel)
│
▼
Lambda: frame_extractor
│
▼
Lambda: ai_analyzer ─── Bedrock / SiliconFlow
│
▼
Lambda: result_processor
│
▼
S3 (output/reports/) + SNS notification
- Python 3.9+
- Node.js 18+ (for AWS CDK CLI)
- Docker (用于构建 Fargate 镜像)
- AWS CLI 已配置凭证 / AWS CLI configured
pip install -r requirements.txt
npm install -g aws-cdkFFmpeg 二进制不在仓库中，第一次部署前先生成：
bash scripts/build_ffmpeg_layer.sh# 全球区 / Global region
python deploy_all.py
# 中国区 / China region
python deploy_all.py --region cn-north-1deploy_all.py 会：构建 Fargate 镜像 → 推送 ECR → CDK bootstrap → 部署堆栈 → 初始化 Parameter Store。
中国区需要在 Parameter Store 写入硅基流动 API Key，详见
POST_DEPLOYMENT_CONFIG.md。
# 上传视频 / Upload a video
aws s3 cp my-driving.mp4 s3://driverhanddetectionstack-<account-id>/input/videos/
# 查看结果 / Check the report
aws s3 ls s3://driverhanddetectionstack-<account-id>/output/reports/报告是 CSV，每帧一行，包含时间戳、判定结果（hands_on / hands_off）、置信度。
# 列出所有参数 / List all parameters
python manage_params.py list --region us-east-1
# 修改帧间隔（秒） / Change frame interval (seconds)
python manage_params.py set --region us-east-1 config/frame-interval 2
# 安全参数（API Key） / Secure parameter
python manage_params.py set --region cn-north-1 config/api-key sk-xxx --secure完整参数列表见 POST_DEPLOYMENT_CONFIG.md。
.
├── deploy_all.py # 一键部署入口 / Main deploy entrypoint
├── deploy_fargate.py # 仅部署 Fargate 部分 / Fargate-only deploy
├── build_and_push_fargate.py # 构建 + 推送 ECR / Build & push image
├── manage_params.py # Parameter Store 管理工具 / Parameter CLI
├── init_unified_parameters.py # 初始化默认参数 / Init default params
├── scripts/
│ └── build_ffmpeg_layer.sh # 下载并打包 FFmpeg Layer
├── src/
│ ├── cdk/ # CDK 堆栈 / CDK stacks
│ ├── lambda/ # Lambda 函数 / Lambda functions
│ │ ├── ai_analyzer/
│ │ ├── frame_extractor/
│ │ ├── direct_frame_extractor/
│ │ ├── segment_processor/
│ │ ├── video_processor/
│ │ ├── fargate_video_processor/
│ │ ├── fargate_result_processor/
│ │ ├── sqs_result_processor/
│ │ ├── result_processor/
│ │ ├── cleanup_function/
│ │ └── trigger/
│ ├── fargate/ # Fargate 容器代码 / Fargate task code
│ ├── layers/ # Lambda Layers (binaries gitignored)
│ └── utils/ # 共享工具 / Shared utilities
├── docs/ # 详细技术 + 用户文档 / Detailed docs
└── requirements.txt
cdk destroy --region your-regionDEPLOYMENT_GUIDE.md— 详细部署步骤POST_DEPLOYMENT_CONFIG.md— 部署后配置SIMPLIFICATION_SUMMARY.md— 项目演进与简化历史docs/— 技术 / 用户中英双语文档
欢迎 Issue 和 PR。提交前请确保：
cdk synth通过- 没有把账号 ID、API Key、二进制文件提交进 git
MIT — see LICENSE.
孙健 / Jimmy Sun — 亚马逊云科技解决方案架构师 / Solutions Architect, AWS
10+ 年汽车行业从业经验，专注于汽车电子电器分析、自动驾驶解决方案领域，对自动驾驶、软件定义汽车（SDV）等云架构设计及 AI 应用有丰富经验。
10+ years in the automotive industry, focusing on automotive E/E architecture analysis and autonomous driving solutions. Extensive experience in cloud architecture design and AI applications for autonomous driving and software-defined vehicles (SDV).
This project is an AWS-based video pre-labeling pipeline for in-cabin /
dashcam footage. It auto-marks every frame as hands_on or hands_off and
exports per-frame CSV labels. The output is intended as training data
(or pseudo-labels) for in-vehicle hands-off detection (HoD) models that
ADAS regulations such as UN R79, UN R157 and EU GSR 2019/2144 mandate.
It uses Step Functions to orchestrate the pipeline, Fargate for fast video cutting, Lambda for frame extraction and inference, and Bedrock (Claude 3.7 Sonnet) in global regions or SiliconFlow (DeepSeek-R1) in AWS China.
pip install -r requirements.txt
npm install -g aws-cdk
bash scripts/build_ffmpeg_layer.sh
python deploy_all.pyUpload a video to s3://<bucket>/input/videos/ and the report appears under
s3://<bucket>/output/reports/.
See POST_DEPLOYMENT_CONFIG.md for required
post-deployment steps (especially in China regions).
This project produces labels for training data. It does not run on a vehicle and does not make real-time safety decisions. The output of cloud foundation models is best-effort and must be reviewed by human annotators before being used to train production HoD models.