基于 Plotly Dash + WebRTC + TensorRT 的实时推理可视化仪表盘:jetson-inference 的 webrtc-dash 实战指南
基于 Plotly Dash + WebRTC + TensorRT 的实时推理可视化仪表盘:jetson-inference 的 webrtc-dash 实战指南
本篇技术指南以 jetson-inference 仓库中的 webrtc-dash 文档 为主体,系统讲解如何用 Python 的 Plotly Dash 框架,把 WebRTC 实时视频流、TensorRT DNN 推理、事件日志与可插拔动作(Action)插件整合成一个可动态配置的数据驱动仪表盘。读完本文,你将掌握该示例的启动方式、模型加载与视频流配置流程,并能基于仓库内置的 Action/EventFilter 基类自行编写带运行时可调属性的动作插件,把"检测到目标 → 触发响应"的闭环落地到自己的应用里。
概览:Plotly Dash 在 Jetson 推理链路中的角色
Plotly Dash 是一个基于 Python 的 Web 框架,专门用于构建数据驱动的仪表盘和交互式界面。其前端基于 React.js,把界面状态变化连接到运行在服务器端的 Python 回调函数,因此可以快速开发出与后端处理管线、数据分析深度集成的富可视化应用。
在 jetson-inference 的示例中(位于 python/www/dash),用户可以在网页上动态创建视频流(Streams)、加载 DNN 模型(Models)、实时查看事件(Events),并配置由事件触发的可扩展动作(Actions)。整条链路与仓库其他 WebApp 示例(如 webrtc-flask.md、webrtc-recognizer.md)一脉相承:底层同样使用 WebRTC 传输实时视频、使用 TensorRT 执行推理。需要说明的是,文档中明确标注该示例目前仍是一个概念验证(proof-of-concept)性质的在开发样本。
项目目录结构
从源码布局可以清晰看出前后端分层设计(源码见 python/www/dash):
| 目录/文件 | 职责 |
|---|---|
| app.py | Dash 前端 Web 服务器入口(webserver) |
| actions/ | 动作插件目录(如 alert.py),启动时自动加载 |
| assets/ | CSS/JavaScript/图片等前端静态资源(含 webrtc.js) |
| layout/ | UI 组件(导航栏、弹窗、视频播放器、事件表格/时间线等) |
| server/ | 后端流媒体/处理服务(Server、Model、Stream、Event、Action、EventFilter) |
| config.py | 默认配置定义,首次运行时写入 data/config.json |
| requirements.txt | Python 依赖清单 |
其中 server 包对外统一导出 Server、Stream、Action、EventFilter、Event、Model 六个类(见 server/init.py),这也是编写动作插件时的核心 API 面。
运行示例:启动仪表盘
安装依赖并启动
在 Jetson 设备上进入示例目录,安装 Python 依赖后即可启动:
$ cd jetson-inference/python/www/dash
$ pip3 install -r requirements.txt
$ python3 app.py --detection=ssd-mobilenet-v2 --pose=resnet18-hand --action=resnet18-kinetics
- 依赖清单见 requirements.txt,包含
dash、dash_auth、dash_bootstrap_components、dash_bootstrap_templates、dash-draggable、psutil、setproctitle、mergedeep、requests等。其中dash-draggable提供面板拖拽能力,mergedeep用于配置文件的深度合并。 - 启动后浏览器访问
https://<JETSON-IP>:8050即可进入配置界面。8050 是默认端口,可通过--port=N命令行参数修改。
note:强烈建议在运行时启用 HTTPS/SSL。原因有两个:一是保证 WebRTC 流与网页传输的加密安全;二是浏览器只有在 HTTPS 下才允许调用客户端摄像头/麦克风权限。
命令行参数与配置优先级
从 app.py 的 argparse 定义可以看出,webserver 支持以下参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
--host |
0.0.0.0(全部接口) |
前端 Web 服务器绑定的网卡 |
--port |
8050 |
前端 Web 服务器端口 |
--ssl-key |
$SSL_KEY 环境变量 |
PEM 编码的 SSL/TLS 私钥路径,用于启用 HTTPS |
--ssl-cert |
$SSL_CERT 环境变量 |
PEM 编码的 SSL/TLS 证书路径,用于启用 HTTPS |
--resources |
无 | 初始化后端资源(模型/流)所用的 JSON 配置文件路径 |
此外 config.py 明确了整体配置的优先级从低到高为:硬编码默认值 → data/config.json 配置文件 → 环境变量($DASH_CONFIG_FILE、$SSL_CERT、$SSL_KEY、$STUN_SERVER)→ 命令行参数。配置文件会在首次运行时由 load_config() 自动写入默认值,后续可编辑 data/config.json 修改:
{
"dash": {
"title": "Hello AI World",
"host": "0.0.0.0",
"port": 8050,
"refresh": 2500,
"users": {}
},
"server": {
"name": "server-backend",
"host": "0.0.0.0",
"rest_port": 49565,
"webrtc_port": 8554,
"ssl_cert": null,
"ssl_key": null,
"stun_server": null
}
}
dash.refresh:前端每 2500ms 向后端轮询一次服务器状态,用于刷新导航结构(见 app.py 的on_refresh回调,它会调用Server.request('/resources')对比前后配置,若未变化则通过PreventUpdate跳过更新)。dash.users:填入username: password键值对即可启用 Dash 的 HTTP Basic Auth 登录鉴权(app.py)。server.rest_port:后端 JSON REST API 端口(49565)。server.webrtc_port:WebRTC 服务器端口(8554)。server.stun_server:覆盖默认的 WebRTC STUN 服务器(默认stun.l.google.com:19302)。
前后端分离的进程架构
app.py 启动时除了运行 Dash Web 服务器,还会通过 Server(**config<a href="https://link.gitcode.com/i/39e8fff99dff2a3630cfeddc6d779098" target="_blank">'server']).start() 启动一个独立的后端进程(见 [server.py)。这与仓库早期示例(把流媒体跑在 webserver 同一进程的线程里)的关键区别在于:
- 后端进程负责 WebRTC 采集/传输、TensorRT 推理以及事件/动作触发,二者通过 REST JSON 消息共享元数据(视频数据始终留在流媒体进程中)。
- 这种独立进程的设计使得 webserver 可以运行多个 worker 进行负载均衡(例如部署到 Gunicorn 或其他生产级 WSGI 服务器)。当以
import app方式被 Gunicorn 加载时,app.py 走else分支,改为Server(**config<a href="https://link.gitcode.com/i/c64db8c63b9293a8516d832072cbf7ee" target="_blank">'server']).connect()——先尝试连接已存在的后端进程,若不存在则自动拉起(见 [server.py 的connect()重试逻辑)。 - 后端进程是
daemon=True的 multiprocessing 子进程,父进程退出时它会自动退出(server.py)。
后端 Server 内部用 Flask 搭建了一个精简 REST 服务(server.py),暴露的路由包括:/status、/resources、/events、/streams(GET/POST)、/models(GET/POST)、/actions、/actions/types、/actions/<id>(GET/PUT)。前端仪表盘的加载模型、增删流、启停动作等操作,最终都通过 Server.request() 封装成的 REST 请求打到这些路由上。
加载 DNN 模型
进入仪表盘后,第一件事通常是打开 Models -> Load Model 菜单加载模型。目前支持加载预训练的分类与检测模型,也支持导入自定义训练的 ONNX 模型。
选中模型并确认后,主页面底部会出现状态消息。加载通常耗时 5-10 秒;如果某模型是首次加载,TensorRT 可能还要花几分钟生成网络引擎(TensorRT engine)。为避免这种延迟,建议先用仓库的 imagenet.py / detectnet.py 程序预加载一次该模型,再运行本 WebApp。
从源码看,server/model.py 的 Model 类在 type == 'classification' 时构造 imageNet(可设置 threshold 置信度阈值与 smoothing 平滑参数),在 type == 'detection' 时构造 detectNet(output_layers 必须是包含 scores 与 bbox 键的 dict,还可通过 tracking 参数启用目标跟踪)。若类型不在两者之列,会抛出 invalid model type 错误。
导入自定义 ONNX 模型
如果你用 Hello AI World 教程(如 pytorch-cat-dog.md 的 train.py 或 pytorch-collect-detection.md 的 train_ssd.py)训练了自己的分类/检测模型,可以在对话框中切到 Import 标签页填写模型信息:
模型文件需要已存在于服务器上,你只需按使用 imagenet.py/detectnet.py 时的惯例填写输入/输出层名(分类模型参见 pytorch-cat-dog.md 的"Processing Images with TensorRT"一节,检测模型参见 pytorch-ssd.md 的对应小节)。这些层名会作为 input_layers/output_layers 传入 Model.init(),进而映射为 imageNet(input_blob=..., output_blob=...) 或 detectNet(input_blob=..., output_cvg=..., output_bbox=...) 的 TensorRT 引擎输入输出 blob。
创建视频流
通过 Streams -> Add Stream 菜单,可以指定要推送的视频源,以及要套用到该流上的 DNN 模型:
- 各类摄像头与视频设备的连接语法参见 Camera Streaming and Multimedia 文档(涵盖 V4L2 摄像头、MIPI CSI、RTP/RTSP 等)。
- 注意:当前示例尚不支持从浏览器网页摄像头(browser webcams)接收 WebRTC 输入,但文档说明这一能力已在计划中。
- 添加流之后,从
Streams菜单选中它即可打开对应的视频播放器;面板小部件支持拖拽、缩放与折叠。
从源码看,server/stream.py 的 Stream 类用 videoSource(source) 打开输入,用 videoOutput(f"webrtc://@:{server.webrtc_port}{name}") 建立 WebRTC 输出,并在启用了 SSL 证书时自动附加 --ssl-cert/--ssl-key 参数,同时强制 --input-codec=mjpeg 与 --output-encoder=cpu。每个流会克隆(Model.clone(stream=self))已加载模型中指定的若干模型;每帧处理流程见 process():source.Capture() → 每个模型 model.process(img) → model.visualize(img) → output.Render(img)。
事件系统:DNN 输出变化的实时记录
当某个 DNN 的输出发生变化时——例如分类结果改变或检测到新目标——系统会记录一个事件(Event)。打开 Events 菜单下的 Events Table 即可实时监控这些事件:
表格支持按列过滤与排序,还可以在 Event Timeline 中可视化:
事件时间线图中,y 轴表示置信度得分(confidence score),x 轴表示时间,每个目标类别对应一条独立的 trace。快速制作这类动态图表与表格正是 Plotly Dash 的强项,你也可以在自建应用时继续扩展。
Event 对象与产生机制
事件对象定义在 server/event.py,其核心字段包括:
| 属性 | 含义 |
|---|---|
id |
全局自增事件编号 |
stream / model |
产生事件所属的流与模型 |
classID / label |
目标类别 ID 与标签名 |
score / maxScore |
当前得分 / 历史最高得分 |
begin / end |
事件起始 / 最近更新时间戳 |
frames |
事件持续的帧数 |
scores |
(时间, 得分) 序列,供时间线绘制 |
事件的产生逻辑在 server/model.py 的 Model.process() 中:分类模型每次 Classify(img) 后,若最高置信度的类别 ID 发生变化,就创建新 Event(调用 Event(...),其构造器会把事件追加到服务器列表并立即 dispatch());若类别未变,则调用 last_event.update(score) 更新现有事件(追加得分点、累加帧数)。而 Event.dispatch()(server/event.py)会遍历所有已启用的 action,逐个调用其 on_event(self) 回调——这就是事件驱动动作插件的核心枢纽。
Actions:事件驱动的可插拔动作插件
Actions 是过滤事件并触发用户自定义代码的插件,典型用途包括发送告警/通知、播放声音、产生物理响应等。动作的属性会通过 Web UI 暴露出来,从而可以在运行时动态配置:
在项目的 actions/ 目录下添加你自己的动作类型后,应用会在启动时自动加载这些模块并在 UI 中列出(加载机制见 server.py 的 load_actions():它遍历 actions/ 下所有 .py 文件,用 importlib 动态导入,并通过 inspect 找出所有继承 Action 的子类及其 @property 属性)。用户可以创建同一动作类型的多个实例,每个实例拥有相互独立的设置。
编写第一个动作插件
下面是文档给出的动作模板——一个简单的日志动作,把检测到 person 且置信度超过 0.5 的事件打印到服务器终端:
from server import Action
class MyAction(Action):
def __init__(self):
super().__init__()
def on_event(self, event):
if event.label == 'person' and event.score > 0.5:
print("Detected a person!") # do something
动作插件应实现 on_event() 回调,它接收系统中所有新建与更新的事件;插件随后按领域相关标准过滤事件,再触发某种响应。可访问的事件属性参见 Event 类。这段代码运行在后端流媒体进程中,可以直接接触底层数据流,且不会影响推理性能(因为动作分发是在事件层完成的,不阻塞采集/推理主循环的传输路径)。
Filters:内置的事件过滤能力
动作既可以实现自定义过滤逻辑,也可以继承 EventFilter 混入类,后者实现了默认过滤功能——如类别标签、最低置信度、最少持续帧数等——通过 filter() 函数调用。仓库自带的 BrowserAlert 插件就用了这套机制:先过滤,再检查/设置 alert_triggered 属性,防止同一事件重复触发多次告警:
from server import Server, Action, EventFilter
class BrowserAlert(Action, EventFilter):
"""
Action that triggers browser alerts and supports event filtering.
"""
def __init__(self):
super(BrowserAlert, self).__init__()
def on_event(self, event):
if self.filter(event) and not hasattr(event, 'alert_triggered'):
Server.alert(f"Detected '{event.label}' ({event.maxScore * 100:.1f}%)")
event.alert_triggered = True
EventFilter.filter()的判定逻辑(filter.py):有标签列表且事件标签不在其中 → 不通过;min_frames设了且event.frames < min_frames→ 不通过;min_score设了且event.maxScore < min_score→ 不通过。Server.alert(text, level, duration)(server.py)会把提示文本追加到服务器告警队列,由前端轮询展示。- 文档还提示:在更高级的场景中,你可能希望在事件其他方面发生变化时重新触发动作(例如置信度显著偏离、或检测持续超过某段时间)。
Properties:把插件属性暴露到 Web UI
带 @property 装饰器的插件属性会被自动暴露到 UI,用户可在运行时动态修改。客户端/服务器之间的通信通过 REST JSON 查询透明完成。以 EventFilter 中的属性为例:
@property
def labels(self) -> str:
return ';'.join(self._labels)
@labels.setter
def labels(self, labels):
self._labels = [label.strip() for label in labels.split(';')]
@property
def min_frames(self) -> int:
return self._min_frames
@min_frames.setter
def min_frames(self, min_frames):
self._min_frames = int(min_frames)
@property
def min_score(self) -> float:
return self._min_score
@min_score.setter
def min_score(self, min_score):
self._min_score = float(min_score)
关键约定:getter 函数上标注的 Python 类型提示(type hints)会告知前端该用哪种 UI 控件(文本框、滑块、复选框等)。目前支持的类型为 str、int、float 与 bool。若省略类型提示,则默认按字符串处理、显示文本框输入,由你的插件自行负责解析/转换成目标类型。后端在 load_actions() 中正是通过 inspect.signature(prop_obj.fget).return_annotation 提取这些类型注解,并在 Action.to_dict() 序列化时连同当前值、可变性(mutable)一起下发前端的。
运行与部署建议
- HTTPS/SSL:如前所述,务必按 webrtc-server.md 的 Enabling HTTPS / SSL 一节生成自签名证书并设置
$SSL_KEY/$SSL_CERT环境变量(或使用--ssl-key/--ssl-cert参数)。证书可存放在任意位置,若使用 Docker 容器则建议放在/jetson-inference/data下,因为它会被挂载到宿主机、退出容器后依然保留。首次访问使用自签名证书的页面时浏览器会弹出不受信任警告,属正常现象。 - 生产部署:得益于前后端分离设计,可以借助 Gunicorn 等多 worker WSGI 服务器加载本应用(
app.py的非__main__分支会自动connect()到后端进程实现协同)。 - 状态持久化:
data/config.json保存了仪表盘与后端的全部配置,首次运行由 config.py 自动生成;REST 层的/models、/streams路由也支持以 JSON 预载资源(--resources参数 /$DASH_CONFIG_FILE)。
总结
webrtc-dash 展示了 jetson-inference 生态中"Web 前端交互 + 后端流式推理"的一种进阶形态:前端用 Plotly Dash 提供模型管理、流管理、事件可视化与动作配置的整套交互 UI,后端用独立进程承载 WebRTC 采集/编码与 TensorRT 推理,二者以 REST JSON 解耦。对于想构建自定义可视化推理应用的开发者,本文梳理的四个核心扩展点最具复用价值——Model/Stream 的资源化抽象、Event 事件模型、Action + EventFilter 插件机制,以及 @property + 类型提示驱动 UI 控件生成的约定。你可以参照 actions/alert.py 与 server/filter.py 的现成实现,快速迭代出自己的事件驱动应用。






