Jetson 人物检测 Demo 复刻手册

0. 你需要准备什么

1. 整体结构

一条流水线，单进程多线程，每一帧顺序做六件事：

代码文件（app/）

设备目录

2. 开发机：SSH 免密 + 同步代码

ssh-keygen -t ed25519 -N "" -f ~/.ssh/jetson_orin_nx
ssh-copy-id -i ~/.ssh/jetson_orin_nx.pub -p <端口> <用户>@<设备地址>   # 这一步要输一次设备密码

在 ~/.ssh/config 里加别名，后面全部用 ssh jetson：

Host jetson
  HostName <设备地址>
  User linux
  Port <端口>
  IdentityFile ~/.ssh/jetson_orin_nx

同步代码，以后每次改完代码都是这一条：

rsync -az --delete --exclude __pycache__ ./app/ jetson:~/demo/app/

2b. 不用开发机，直接在设备上操作

如果你就坐在 Jetson 前面（接了显示器键盘），第 2 步整个跳过，代码这样拿：

mkdir -p ~/demo && cd ~/demo
wget https://jetson.weorgcloud.com/jetson-demo-src.zip && unzip -o jetson-demo-src.zip   # 得到 app/ scripts/ docs/
bash scripts/setup_jetson.sh 2>&1 | tee setup.log                                        # 后面全自动

没网的话用 U 盘把 app/ 和 scripts/ 拷到 ~/demo/ 下也一样。以后改代码直接在设备上改 ~/demo/app/ 里的文件（nano 或 VS Code 都行），改完 sudo systemctl restart person-demo 生效。

3. 设备：一键脚本

把 scripts/setup_jetson.sh 拷到设备后执行，它按下面五个阶段走，每个阶段可以单独重跑：

scp scripts/setup_jetson.sh jetson:~/demo/
ssh jetson 'bash ~/demo/setup_jetson.sh 2>&1 | tee ~/demo/setup.log'

阶段 1：apt 源和 JetPack 组件（约 10 分钟）

出厂系统只有 CUDA，没有 cuDNN 和 TensorRT。

阶段 2：模型和轮子（约 3 分钟）

为什么不用 PyPI：PyPI 上的 torch 是 CPU 版；Jetson 专用轮子站 pypi.jetson-ai-lab.io 从国内只有 80KB/s。

阶段 3：Python 环境（约 5 分钟）

python3 -m venv --system-site-packages ~/demo/venv   # 继承系统包：才有 apt 装的 TensorRT 绑定和带硬解的 OpenCV
source ~/demo/venv/bin/activate
pip install --no-deps torch-2.10.0*.whl torchvision-0.25.0*.whl onnxruntime_gpu-1.23.0*.whl
pip install "numpy<2" filelock networkx jinja2 fsspec packaging protobuf flatbuffers coloredlogs pillow
pip install -U "sympy>=1.13.3" "typing_extensions>=4.10"   # 系统旧 sympy 会让 torch 无法 import
# cuDSS（torch 2.10 依赖）：aria2 从 developer.download.nvidia.cn 拿 deb，dpkg -i 后 apt install cudss
pip install --no-deps ultralytics                          # 不带依赖，否则拉 CPU 版 torch 和无硬解 opencv
pip install matplotlib pyyaml requests scipy tqdm psutil py-cpuinfo ultralytics-thop polars pandas seaborn lap onnx onnxslim
pip install cython && pip install insightface fastapi "uvicorn[standard]" python-multipart aiofiles
pip uninstall -y onnxruntime opencv-python-headless opencv-python   # insightface 顺带装的，会盖掉 GPU 版和系统 OpenCV
pip install --no-deps onnxruntime_gpu-1.23.0*.whl

验证（都要为真）：torch.cuda.is_available()；cv2 的 build 信息里 GStreamer YES；onnxruntime.get_available_providers() 含 CUDA 和 TensorRT；import tensorrt 成功。

最终版本：torch 2.10.0 / torchvision 0.25.0 / onnxruntime-gpu 1.23.0 / TensorRT 10.3 / cuDNN 9.3 / OpenCV 4.8（系统）/ ultralytics 8.4.138 / insightface 1.0.1 / numpy 1.26.4。

阶段 4：导出 TensorRT 引擎（3 个模型，共约 20 分钟）

cd ~/demo/app && source ~/demo/venv/bin/activate
python export_engines.py ~/demo/models/yolo26n-pose.pt ~/demo/models/heads/head_abcfsa_yolov8n.pt ~/demo/models/gestures/YOLOv10n_gestures.pt

引擎只能在目标机、同版本 TensorRT 上生成；换 JetPack 要重做。代码里 resolve_model() 会自动优先使用同名 .engine。

阶段 5：服务化与散热

• person-demo.service：run.sh --source /dev/video0 --port 8080，开机自启，失败自动重启。
• thermal-log.service：每 30 秒把温度、风扇、GPU 频率记到 ~/demo/thermal.log。
• 风扇：/etc/nvfancontrol.conf 里 FAN_DEFAULT_PROFILE 改 cool。
• 电源档：散热正常用 nvpmodel -m 0（MAXN SUPER）并在服务里加 ExecStartPre=+/usr/bin/jetson_clocks 锁频，可稳 30 帧；这台散热差，用 nvpmodel -m 3（25W，要重启）且不锁频，约 20～23 帧。
• 程序内温控（config.py）：90°C 降低识别频率，97°C 暂停识别，92°C 以下恢复；硬件自身 99°C 强制降频、104°C 断电。

4. 摄像头怎么验证

v4l2-ctl -d /dev/video0 --list-formats-ext | head          # 支持的分辨率/帧率
v4l2-ctl -d /dev/video0 --set-fmt-video=width=1920,height=1080,pixelformat=MJPG --stream-mmap --stream-count=120   # 原始帧率，应接近 30
# 硬解通路（程序里用的就是这条管线）
gst-launch-1.0 v4l2src device=/dev/video0 num-buffers=120 ! "image/jpeg,width=1920,height=1080,framerate=30/1" ! jpegparse ! nvv4l2decoder mjpeg=1 ! nvvidconv ! "video/x-raw,format=BGRx" ! fpsdisplaysink video-sink=fakesink text-overlay=false sync=false -v 2>&1 | grep -oE "average: [0-9.]+" | tail -1

实测：这只摄像头 nvjpegdec 只有 11 帧，nvv4l2decoder 32 帧，CPU 解码 30 帧占 1 核。程序开不了硬解时自动回退到 V4L2 + CPU 解码。

5. 运行、验证、更新

sudo systemctl status person-demo                 # 状态
journalctl -u person-demo -f                      # 实时日志
curl -s localhost:8080/api/status | python3 -m json.tool    # 帧率、各阶段耗时、温度、原始手势输出
curl -s -X POST -H "Content-Type: application/json" -d '{"kind":"demo"}' localhost:8080/api/source   # 切到内置演示视频，camera 切回
curl -s -F "name=张三" -F "files=@photo.jpg" localhost:8080/api/register   # 命令行注册人脸

网页：http://<设备局域网 IP>:8080。改代码：开发机改 → rsync → sudo systemctl restart person-demo。

本机单元测试（不需要设备）：python3 scripts/test_common.py，覆盖头框估算、身份确认、手势平滑、双手校验。

6. 会踩的坑（都已在脚本里处理）

7. 许可与合规

YOLO（AGPL-3.0）、InsightFace 预训练模型（仅非商用）、HaGRID（CC BY-SA 4.0）都只适合内部 demo；产品化要换可商用模型或购买授权。人脸数据只存设备本地，需符合《人脸识别技术应用安全管理办法》。