四块需求全部上线，设备上跑到摄像头满帧 30 帧/秒，网页界面可用，开机自启。唯一没做的是用真人和未参与注册的照片做准确率验证，这一步需要你在现场配合。
完成情况
| 你的需求 | 状态 | 现在能做到什么 |
|---|
| 框出人形大小和位置并显示 | 完成 | 实时人框、跟踪编号、17 个骨架关键点，多人同时 |
| 识别头部位置和尺寸 | 完成 | 专用头部检测模型出实线框；检测不到时用关键点估算出虚线框并标"估"；尺寸显示宽×高 |
| 标注常用手势（加分项） | 完成 | 身体动作：举手、挥手、双手举起。手部手势 30 余种：点赞、OK、比耶、手掌、握拳、比心、合十、拍照等 |
| 上传照片注册人脸、识别是谁 | 完成 | 网页上传或抓拍注册，画面上显示名字和相似度，可补加照片、删除 |
| 目标平台 Jetson Orin NX | 完成 | 四个模型都用 TensorRT 加速，30 帧/秒，systemd 服务开机自启 |
| 展示界面 | 完成 | 演示大屏风格网页：直播画面、现场人物卡片、事件流、注册面板、显示开关、演示视频切换、全屏 |
| 真人准确率验证 | 未做 | 缺真人视频和未参与注册的照片，摄像头至今朝天花板 |
系统是怎么搭的
一条流水线，单进程多线程。每一帧顺序经过下面六步，括号里是设备上锁频后的实测耗时。
采集USB 摄像头 1080p MJPEG，Jetson 硬件解码（nvv4l2decoder），不占 CPU。
30 fps · 解码 0 ms CPU
人 + 姿态YOLO26n-pose（TensorRT 半精度）一次给出人框和 17 个关键点，ByteTrack 给每个人稳定编号，每帧跑。
11 ms / 帧
头部SCUT-HEAD 数据集训练的 YOLOv8n 头部检测器（TensorRT），每 3 帧跑一次，中间按人框位移平移缓存；检测不到时用耳、眼、肩关键点估算。
9.6 ms / 次
人脸InsightFace（SCRFD 检测 + ArcFace 512 维特征），每 3 帧检测一次；对每个跟踪编号节流比对：未确认时 0.4 秒复查，确认后 2 秒复核；连续两次匹配同一人才显示名字，之后有惯性不闪烁。
GPU · 按人节流
手势HaGRIDv2 官方 YOLOv10n 手势检测器（TensorRT），每 3 帧跑一次，按离手腕最近归到人；连续两次一致才显示，漏检一次重新计数，人走即清；双手类手势另加"两只手腕都在框内且置信度 ≥ 0.75"校验。姿态规则（举手、挥手）作为补充。
每 3 帧一次
展示FastAPI 网页：MJPEG 直播（最高 15 帧）加每 0.7 秒拉一次的数据面板。画面叠加层按状态着色。
绘制 1 ms
绿 = 已识别的人黄 = 未注册的人青 = 头部框（实线检测 / 虚线估算）橙 = 手势
选型依据、候选对比、许可和合规说明在同目录的《调研与选型报告.md》。
操作记录
评估与调研
- 口头评估可行性与工期（3～4 周），给出硬件建议；你确认 Orin NX 16GB 加 USB 单摄。
- 派出四路并行调研（人形+头部、手势、人脸、平台部署），三路当晚返回，结论写入 findings.md。手势那一路卡死 5 小时后被停掉，改为自己完成。
设备接入与系统组件
- 你给出公网 SSH 地址。我不输密码：生成专用密钥，你跑一次 ssh-copy-id 后免密登录。
- 设备体检：JetPack 6.2.1，只有 CUDA、缺 cuDNN 和 TensorRT；Python 3.10；摄像头支持 1080p30 MJPEG；sudo 免密。
- 安装 JetPack 组件连撞三个网络坑：NVIDIA 源单连接 100KB/s、换国内镜像后 apt 依赖冲突（自带优先级规则只认 .com 域名，补了 .cn 规则）、Ubuntu 源 72KB/s（换清华镜像）。最终 aria2 16 线程预取 1.5GB 后安装，几分钟完成。
Python 环境、代码、第一次跑通
- PyTorch 轮子站只有 80KB/s，改用 Ultralytics 在 GitHub 提供的 Jetson 版 torch 2.10 / torchvision 0.25 / onnxruntime-gpu 1.23。
- 装 insightface 时它顺带装了 CPU 版 onnxruntime 和无硬解的 OpenCV，把 GPU 版盖掉，卸掉重装；系统旧版 sympy 让 torch 无法导入，升级解决。
- 写第一版代码，导出 TensorRT 引擎（7 分钟）。冒烟测试只有 7 帧：给 TensorRT 模型传了 half=True，Ultralytics 每帧重建推理器；去掉后 30 帧。
- 端到端功能测试（样图拼的视频）：3 人检出跟踪，网页上传照片注册，识别出并显示名字。建 systemd 服务；你在局域网打开页面看到 29.7 帧。
头部检测器、性能定型
- 原定 CrowdHuman 头部权重的 Google Drive 链接失效；找到 4 个可直接下载的候选，同一组样图对比，选召回最好的 SCUT-HEAD YOLOv8n。
- 加头部检测后掉到 19 帧，查出 Jetson 没锁频；锁频后每个模型快一倍多，回到 30 帧，锁频写进服务启动前置。
- 修缩略图损坏：文件名用了随机哈希，服务重启后对不上，改为固定的 md5 文件名。
界面 v2、手势模型
- 界面按"演示大屏优先"重做：现场人物卡片、事件流、注册重做、已注册卡片、显示开关、演示视频切换、全屏。
- 我到设备的远程隧道只有 17KB/s 看不了视频，界面细节在本机用假后端核对，接口在设备上逐个验证。
- 手势：下载 HaGRIDv2 官方 YOLOv10n，验证加载、导出引擎，写归属与平滑逻辑；用 HaGRID 示例拼的视频测试，比心、手枪、捏、合十、暂停、拍照、叉全部认对。
两轮外部评审修复
- 第一轮六条全部属实并修复：估算头框改虚线标"估"、关键点不可靠时不出框；手势连击计数漏检清零、人走即清、原始输出可查；人脸需连续两次匹配才显示；修上传控件消失的前端 bug；抓拍注册改为定格一帧并编号选脸；帧率标"处理帧率"、头部尺寸宽×高。纯逻辑抽成独立模块并写了本机单元测试。
- 第二轮两条："指"误判成"比心"，加双手类手势校验，演示视频 30 秒 0 误报、九种真双手手势全部保留；脚本加版本号防浏览器缓存新旧混用。
验证方法与局限
| 层次 | 在哪跑 | 覆盖什么 |
|---|
| 单元测试 | 本机 | 零置信度关键点不出头框、"命中→漏检→命中"不显示手势、单次 0.41 不确认身份、双手校验 |
| 接口测试 | 设备 | 每次部署后检查状态、切换信号源、抓拍、注册、删除 |
| 端到端测试 | 设备 | 两段测试视频（样图拼接、HaGRID 示例拼接）跑真实流水线，截图人工看叠加层 |
| 界面测试 | 本机 + 你的局域网 | 假后端配真页面截图；你在局域网的实际体验与两轮评审 |
局限：所有识别相似度数据来自"注册同一张照片"，只能证明流程通，不能证明准确率；摄像头至今朝天花板，没有真人画面。
踩坑备查
| 现象 | 原因 | 解决 |
|---|
| 设备下载极慢 | 国外源单连接限速 | GitHub 走代理镜像；apt 用 .cn 镜像加优先级规则；aria2 多线程预取 |
| apt 依赖冲突 | NVIDIA 优先级规则只认 .com | 新增 *.nvidia.cn 规则 |
| torch 导不进 | venv 继承系统旧 sympy | 在 venv 内升级 |
| 人脸跑在 CPU、硬解失效 | insightface 顺带装了 CPU 版 onnxruntime 和无 GStreamer 的 OpenCV | 卸掉，用 GPU 轮子和系统 OpenCV |
| 只有 7 帧 | 给 TensorRT 模型传 half=True 每帧重建推理器 | 去掉参数 |
| 只有 19 帧 | 没锁频 | jetson_clocks 写进服务 |
| 硬解只有 11 帧 | nvjpegdec 元件慢 | 换 nvv4l2decoder |
| 缩略图损坏 | 随机哈希文件名 | md5 固定文件名 |
| 远程命令误杀自己 | pkill 模式匹配到 ssh 自身 | 脚本落盘执行 |
| 远程脚本中断 | ffmpeg 吃掉脚本标准输入 | 加 -nostdin |
| 新页面旧脚本 | 浏览器缓存 | 脚本带版本号并禁止缓存 |
文件与位置
- Mac 项目目录
~/Documents/AI/work/jetson-person-demo/：调研与选型报告.md（选型、实测、许可、合规）、findings.md（全部调研原始资料）、progress.md（逐条操作日志，本文依据）、task_plan.md、app/（代码约 1900 行）、docs/（设计与本文）- 设备目录
~/demo/app 代码、~/demo/venv、~/demo/models 各模型与引擎、~/demo/data/faces 人脸库、~/demo/setup_phase*.log 安装日志- 运行
sudo systemctl status person-demo；网页 http://192.168.1.128:8080（同一局域网）- 改代码
- Mac 上改 → rsync 到设备 →
sudo systemctl restart person-demo
- 关键版本
- JetPack 6.2.1 · TensorRT 10.3 · cuDNN 9.3 · torch 2.10.0 · onnxruntime-gpu 1.23.0 · OpenCV 4.8（系统版）· insightface 1.0.1
需要你做的三件事
- 把摄像头摆正对着人，让人在 3 米内走动、做手势，在局域网打开页面看实际效果。
- 提供几个人的照片（每人 2～3 张不同角度）和一段真人视频，我用来做正式的准确率验证并调阈值。
- 改掉设备的默认密码，并只保留密钥登录。
风险提示
三个模型（YOLO、InsightFace 模型、HaGRID）的许可都只适合内部 demo，做产品前要换成可商用版本或购买授权，替代方案见选型报告。人脸属于敏感个人信息，正式使用需符合《人脸识别技术应用安全管理办法》；demo 只在设备本地存特征向量，可随时删除。