reComputer RK3588 或 RK3576 在 NPU 上运行商品检测和嵌入,一台 Linux 服务器运行注册服务、管理界面、MQTT broker 和商品库。
- 服务器: 一台装有 Docker 的 Linux 服务器,不需要 GPU。
- 摄像头: RTSP 或 USB 摄像头,对准收银台或货架。
- 模型转换: 一台 x86_64 机器,rknn-toolkit2 不能在板卡上运行。
- 模型许可: 检测器和嵌入模型仅限非商用,不随本方案提供;商用部署需要用自采或许可宽松的数据重训。
reComputer RK3588 或 RK3576 在 NPU 上运行商品检测和嵌入,一台 Linux 服务器运行注册服务、管理界面、MQTT broker 和商品库。
在服务器上启动注册服务、管理界面和 MQTT broker,并设置角色 token。
RETAIL_SERVER_IMAGE 和 RETAIL_WEB_IMAGE。| 现象 | 处理 |
|---|---|
compose 运行前提示 "MISSING: <image>" | 检查服务器能否访问镜像仓库;使用自建镜像时先在本机构建。 |
找不到 docker compose | 安装 docker-compose-plugin。 |
匿名 GET /v1/gallery 返回 200 | token 校验没有生效,停止使用并检查配置。 |
带 admin token 的 GET /v1/gallery 返回空库 | 首次注册前属正常。 |
| 8089 端口被占用 | 修改服务端口,设备端配置使用同一个端口。 |
部署到识别设备可以访问的一台 Linux 服务器。
ubuntusensecraft-missionpack.seeed.cn/solution/edge-retail-console-server:0.2.0已发布在 sensecraft-missionpack.seeed.cn/solution/edge-retail-console-server:0.2.0 (linux/amd64 + linux/arm64)。要用自建镜像的话,在这台主机上用上游仓库的 platforms/console/Dockerfile.server 构建,把构建出的 tag 填在这里。 registry 给得出 digest 就钉 digest:一个构建写出的商品库向量,只与同一个嵌入模型、 同一套预处理写出的向量可比,对不上的症状是"什么都认不出来",不是显眼的版本错误。
sensecraft-missionpack.seeed.cn/solution/edge-retail-console-web:0.1.0已发布在 sensecraft-missionpack.seeed.cn/solution/edge-retail-console-web:0.1.0 (linux/amd64 + linux/arm64)。要自建的话,先构建 SPA (`npm --prefix web/ui ci && npm --prefix web/ui run build`), 再用 platforms/console/Dockerfile.web 构建这个镜像。镜像里不跑 npm。
可以注册 SKU、替换 SKU、回滚商品库。发给有权决定"商品目录里有什么"的人。
只读权限,外加设备侧的上报角色。不能改商品库。
只读——事件、汇总、商品库版本。不能注册任何东西。
8089设备从这个端口拉商品库。它必须对每一台识别设备可达,不只是对浏览器可达。
8080在本地网络之外能访问它之前,先在前面放一个终止 TLS 的反向代理。共享 bearer token 走明文 HTTP 等于没有鉴权。
1883随包的 broker 配置是匿名明文,config/mosquitto.conf 开头就写了这一条。 任何能访问这个端口的人都能往 retail/v1/events 上灌伪造事件。只能用于台面测试—— 离开实验台之前先加账号与 TLS。
把 DINOv2-base 嵌入模型放到管理端的模型目录,并启用它。
dinov2b_arcface_products10k_224_b1.onnx(348 MB,sha256 01ae07d10f638a2ebeb85100325ad79765a325d1026b728b60f1ee106e76eaae),需自行获取,仅限非商用。| 现象 | 处理 |
|---|---|
| 注册成功,但每次检索都返回错的 SKU | 嵌入模型没有启用。设置 RETAIL_EMBEDDER=onnx,重启服务,然后重新注册所有 SKU。 |
设置 RETAIL_EMBEDDER=onnx 后 server 容器立刻退出 | 确认 RETAIL_EMBEDDER_ONNX 已填写,文件在 assets/console/models/ 里且文件名一致。 |
| 换模型前后注册的商品库对不上 | 不同模型的商品库不能混用,用新模型重新注册所有 SKU。 |
| 计划商用部署 | 用自采或许可宽松的数据重训嵌入模型,并重建商品库。 |
在管理界面的商品库中,为每个 SKU 上传 3 到 8 张图完成注册,每次注册生成一个新的商品库版本。
| 现象 | 处理 |
|---|---|
| 注册被拒,提示图片少于三张 | 至少上传 3 张。 |
| 同一个 sku_id 返回 409 | 需要替换时带 replace=true。 |
| 出了新版本,但设备仍然认不出这个 SKU | 设备端拉取、校验并切换商品库版本的功能尚未实现。 |
| top-1 明显偏低 | 先增加每个 SKU 的注册图数量;仍偏低时用现场图片微调模型。 |
在 x86_64 主机上把检测器 ONNX 转成 .rknn,拷到板卡上。
librknnrt.so 版本一致,不一致时可能加载成功但结果错误。RETAIL_RKNN_DET_CORE_MASK=2、RETAIL_RKNN_EMBED_CORE_MASK=01,不要用 AUTO。| 现象 | 处理 |
|---|---|
load_onnx 在 onnx.mapping 上失败 | 安装 onnx 1.16.1。 |
找不到 pkg_resources | 把 setuptools 降到 81 以下。 |
| INT8 一致率明显低于 98% | 校准图从整个验证集等间隔抽取,不要按文件名取前 N 张。 |
| 板卡上没有 cv2 和 PIL | 在其他机器上做 letterbox 预处理,打包成 (N, 640, 640, 3) uint8 BGR 的 .npy;设备端只需要 numpy 和 rknnlite。 |
验证管理端注册与下载,并核对转换后的模型与 CPU 结果一致。
uv sync。| 现象 | 处理 |
|---|---|
| 检测框一致率远低于参考值 | 检查解码路径和输出布局。 |
| 软件闭环通过但板卡上不工作 | 软件闭环只验证协议,板卡问题按步骤 4 排查。 |
| 商品库在服务器上校验通过、在设备上不通过 | 对比两边的 sha256,重新传输文件。 |
uv run python tools/verify_software_loop.py 通过。GET /v1/gallery/current/download 返回的 tar.gz 中 SHA256SUMS 校验通过。.rknn 与 CPU 结果的检测框一致率(IoU ≥ 0.5):fp16 接近 99.85%,INT8 接近 98.35%。platforms/rk3588/runtime.py(配置 platforms/rk3588/runtime.yaml)串联检测、嵌入、检索与上报,本套餐不负责部署和托管它。reComputer R2000(Hailo-8)在 NPU 上运行商品检测、在 CPU 上运行嵌入,一台 Linux 服务器运行注册服务、管理界面、MQTT broker 和商品库。
在设备能访问的服务器上启动注册服务、管理界面和 MQTT broker。
RETAIL_SERVER_IMAGE 和 RETAIL_WEB_IMAGE。| 现象 | 处理 |
|---|---|
compose 运行前提示 "MISSING: <image>" | 检查服务器能否访问镜像仓库;使用自建镜像时先在本机构建。 |
匿名 GET /v1/gallery 返回 200 | token 校验没有生效,停止使用并检查配置。 |
| 设备访问不到服务端口 | 在设备上直接测试服务端口,设备从该端口拉取商品库。 |
| 8089 端口被占用 | 修改服务端口,设备端配置使用同一个端口。 |
部署到识别设备可以访问的一台 Linux 服务器。
ubuntusensecraft-missionpack.seeed.cn/solution/edge-retail-console-server:0.2.0已发布在 sensecraft-missionpack.seeed.cn/solution/edge-retail-console-server:0.2.0 (linux/amd64 + linux/arm64)。要用自建镜像的话,在这台主机上用上游仓库的 platforms/console/Dockerfile.server 构建,把构建出的 tag 填在这里。 registry 给得出 digest 就钉 digest:一个构建写出的商品库向量,只与同一个嵌入模型、 同一套预处理写出的向量可比,对不上的症状是"什么都认不出来",不是显眼的版本错误。
sensecraft-missionpack.seeed.cn/solution/edge-retail-console-web:0.1.0已发布在 sensecraft-missionpack.seeed.cn/solution/edge-retail-console-web:0.1.0 (linux/amd64 + linux/arm64)。要自建的话,先构建 SPA (`npm --prefix web/ui ci && npm --prefix web/ui run build`), 再用 platforms/console/Dockerfile.web 构建这个镜像。镜像里不跑 npm。
可以注册 SKU、替换 SKU、回滚商品库。发给有权决定"商品目录里有什么"的人。
只读权限,外加设备侧的上报角色。不能改商品库。
只读——事件、汇总、商品库版本。不能注册任何东西。
8089设备从这个端口拉商品库。它必须对每一台识别设备可达,不只是对浏览器可达。
8080在本地网络之外能访问它之前,先在前面放一个终止 TLS 的反向代理。共享 bearer token 走明文 HTTP 等于没有鉴权。
1883随包的 broker 配置是匿名明文,config/mosquitto.conf 开头就写了这一条。 任何能访问这个端口的人都能往 retail/v1/events 上灌伪造事件。只能用于台面测试—— 离开实验台之前先加账号与 TLS。
把 INT8 量化的 DINOv2-small 嵌入模型放到管理端的模型目录,并启用它。商品库必须用设备运行的同一个模型建立,不能和其他套餐的模型混用。
dinov2s_arcface_products10k_224_b1_dynint8.onnx(sha256 50e886aeab7b61a7eebe6ea3492b2d3ba0e74a859acedcbb9e9917b2b60454f6),需自行获取,仅限非商用。| 现象 | 处理 |
|---|---|
| 注册成功,但每次检索都返回错的 SKU | 嵌入模型没有启用。设置 RETAIL_EMBEDDER=onnx,重启服务,然后重新注册所有 SKU。 |
设置 RETAIL_EMBEDDER=onnx 后 server 容器立刻退出 | 确认 RETAIL_EMBEDDER_ONNX 已填写,文件在 assets/console/models/ 里且文件名一致。 |
| 换模型前后注册的商品库对不上 | 不同模型的商品库不能混用,用新模型重新注册所有 SKU。 |
| 计划商用部署 | 用自采或许可宽松的数据重训嵌入模型,并重建商品库。 |
每个 SKU 上传 3 到 8 张图完成注册,每次注册生成一个新的商品库版本。
| 现象 | 处理 |
|---|---|
| 注册被拒,提示图片少于三张 | 至少上传 3 张。 |
| 商品库用 base 模型建立,设备运行 small 模型 | 用设备运行的模型重建商品库。 |
| 出了新版本,但设备仍然认不出这个 SKU | 设备端拉取、校验并切换商品库版本的功能尚未实现。 |
| 注册很慢 | 嵌入在服务器 CPU 上计算,每个 SKU 只在注册时计算一次。 |
在 x86_64 主机上编译检测器 HEF,并在设备上准备 HailoRT 环境。
/etc/modprobe.d/hailo.conf 里有 force_desc_page_size=4096。/dev/hailo0 存在且没有被其他进程占用。| 现象 | 处理 |
|---|---|
| single-context 编译失败 | 属正常,编译器会自动改用两 context 分区。 |
| 编译容器写不了 cache | 把挂载的工作目录设为所有用户可写。 |
| 框数量对、坐标全错 | 用 HEF.get_output_vstream_infos() 获取输出顺序,不要按名字排序。 |
其他进程占用 /dev/hailo0 | 停掉占用的进程。 |
| 嵌入速度明显偏慢 | 确认使用四线程,且运行的是 INT8 模型而不是 fp32 模型。 |
验证管理端注册,并核对 HEF 与 CPU 结果一致。
uv sync。| 现象 | 处理 |
|---|---|
| 一致率正常但画面上的检测不对 | 检查解码阈值(0.25)和 letterbox 预处理。 |
| 检测延迟偏高 | 确认没有其他进程占用加速器,且管线已激活。 |
| 读不到芯片温度或功耗 | 该平台不支持读取,记为 unavailable。 |
| 检索效果明显偏低 | 用自己货架的数据测试并微调模型。 |
uv run python tools/verify_software_loop.py 通过。hailortcli benchmark 约 110 fps。reComputer J40(Orin NX 16GB)或 J30(Orin Nano 8GB)用 TensorRT fp16 在 GPU 上运行商品检测和嵌入,一台 Linux 服务器运行注册服务、管理界面、MQTT broker 和商品库。
在服务器上启动注册服务、管理界面和 MQTT broker,并设置角色 token。
RETAIL_SERVER_IMAGE 和 RETAIL_WEB_IMAGE。| 现象 | 处理 |
|---|---|
compose 运行前提示 "MISSING: <image>" | 检查服务器能否访问镜像仓库;使用自建镜像时先在本机构建。 |
匿名 GET /v1/gallery 返回 200 | token 校验没有生效,停止使用并检查配置。 |
找不到 docker compose | 安装 docker-compose-plugin。 |
| 8089 端口被占用 | 修改服务端口。 |
部署到识别设备可以访问的一台 Linux 服务器。
ubuntusensecraft-missionpack.seeed.cn/solution/edge-retail-console-server:0.2.0已发布在 sensecraft-missionpack.seeed.cn/solution/edge-retail-console-server:0.2.0 (linux/amd64 + linux/arm64)。要用自建镜像的话,在这台主机上用上游仓库的 platforms/console/Dockerfile.server 构建,把构建出的 tag 填在这里。 registry 给得出 digest 就钉 digest:一个构建写出的商品库向量,只与同一个嵌入模型、 同一套预处理写出的向量可比,对不上的症状是"什么都认不出来",不是显眼的版本错误。
sensecraft-missionpack.seeed.cn/solution/edge-retail-console-web:0.1.0已发布在 sensecraft-missionpack.seeed.cn/solution/edge-retail-console-web:0.1.0 (linux/amd64 + linux/arm64)。要自建的话,先构建 SPA (`npm --prefix web/ui ci && npm --prefix web/ui run build`), 再用 platforms/console/Dockerfile.web 构建这个镜像。镜像里不跑 npm。
可以注册 SKU、替换 SKU、回滚商品库。发给有权决定"商品目录里有什么"的人。
只读权限,外加设备侧的上报角色。不能改商品库。
只读——事件、汇总、商品库版本。不能注册任何东西。
8089设备从这个端口拉商品库。它必须对每一台识别设备可达,不只是对浏览器可达。
8080在本地网络之外能访问它之前,先在前面放一个终止 TLS 的反向代理。共享 bearer token 走明文 HTTP 等于没有鉴权。
1883随包的 broker 配置是匿名明文,config/mosquitto.conf 开头就写了这一条。 任何能访问这个端口的人都能往 retail/v1/events 上灌伪造事件。只能用于台面测试—— 离开实验台之前先加账号与 TLS。
把 fp32 的 DINOv2-small 嵌入模型放到管理端的模型目录,并启用它。步骤 4 用同一份文件构建 TensorRT engine;不能和其他套餐的模型混用。
dinov2s_arcface_products10k_224_b1.onnx(sha256 7f0136ef6459fdd5461e39e95070c7e964fbe2df4b53309f15f452c60da615be),需自行获取,仅限非商用。| 现象 | 处理 |
|---|---|
| 注册成功,但每次检索都返回错的 SKU | 嵌入模型没有启用。设置 RETAIL_EMBEDDER=onnx,重启服务,然后重新注册所有 SKU。 |
设置 RETAIL_EMBEDDER=onnx 后 server 容器立刻退出 | 确认 RETAIL_EMBEDDER_ONNX 已填写,文件在 assets/console/models/ 里且文件名一致。 |
| 换模型前后注册的商品库对不上 | 不同模型的商品库不能混用,用新模型重新注册所有 SKU。 |
| 计划商用部署 | 用自采或许可宽松的数据重训嵌入模型,并重建商品库。 |
每个 SKU 上传 3 到 8 张图完成注册,每次注册生成一个新的商品库版本。
| 现象 | 处理 |
|---|---|
| 注册被拒,提示图片少于三张 | 至少上传 3 张。 |
| 同一个 sku_id 返回 409 | 需要替换时带 replace=true。 |
| 版本号不增加 | 注册没有通过图片质量检查,响应里会指出是哪一张图。 |
在板卡上构建检测和嵌入两个 fp16 engine,并校验 SHA。
16d1347 或更新版本中的 platforms/jetson/build_engines.py。| 现象 | 处理 |
|---|---|
trtexec 报 "Static model does not take explicit shapes" | 不要传 --shapes;使用 commit 16d1347 及以后的 build_engines.py。 |
| 一块板卡上构建的 engine 在另一块上跑不了 | 在每块板卡上分别构建。 |
runtime.py --dry-run 以 exit code 2 退出 | 重新构建,或执行 build_engines.py --update-config 更新配置中的哈希。 |
| 检测框一致率明显偏低 | 检查解码和输出布局。 |
| 检索结果差异明显 | 核对嵌入模型 ONNX 的 sha256 是否为 7f0136ef…。 |
验证管理端注册与下载、engine 校验,以及设备端检测和检索结果。
uv sync。| 现象 | 处理 |
|---|---|
runtime.py --dry-run 以 exit code 2 退出 | 执行 build_engines.py --update-config 重新构建,新哈希会写回配置。 |
| 延迟明显偏高 | 确认 nvpmodel -q 为 MAXN_SUPER,且没有其他进程占用 GPU。 |
| 软件闭环通过 | 软件闭环只验证协议,设备精度以上面的一致率检查为准。 |
| 需要确认各套餐验证范围 | 本套餐和 RK3588 套餐做过设备端运行实测;Hailo-8 与 RK3576 套餐只验证到模型转换。 |
uv run python tools/verify_software_loop.py 通过。GET /v1/gallery/current/download 返回的 tar.gz 中 SHA256SUMS 校验通过。platforms/jetson/runtime.py --config platforms/jetson/runtime.yaml --dry-run 通过。platforms/jetson/runtime.py 回放一段收银台画面,/healthz 中 frames_dropped、capture_drop、embed_drop 均为 0。在自己的板卡上运行设备端程序,需要在 runtime.yaml 中准备四项:
sources[0].kind 改成 usb、uri 改成设备路径(如 /dev/video0);接 RTSP 按 runtime.yaml 里的注释配置。python3 platforms/make_runtime_gallery.py --config platforms/jetson/runtime.yaml --skus-json <SKU 列表> 在 gallery.root 下建立。mqtt.host 改成你自己的 broker。python3 platforms/jetson/runtime.py --config platforms/jetson/runtime.yaml --dry-run,通过后去掉 --dry-run 运行。需要开机自启时使用 platforms/jetson/retail-runtime.service。