基于 Plotly Dash + WebRTC + TensorRT 的实时推理可视化仪表盘:jetson-inference 的 webrtc-dash 实战指南

原创2026-09-24 19:37:041,657 阅读
文章标签:人工智能计算机视觉深度学习嵌入式

基于 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)性质的在开发样本。

webrtc-dash 仪表盘整体界面

项目目录结构

从源码布局可以清晰看出前后端分层设计(源码见 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 的现成实现,快速迭代出自己的事件驱动应用。

登录后查看全文
jetson-inference