スーパーマーケット商品認識 — デプロイガイド

プリセット

Rockchip NPU — RK3588 / RK3576

A reComputer RK3588 or RK3576 runs product detection and embedding on the NPU; a Linux server runs the registration service, management UI, MQTT broker and gallery.

  • Server: a Linux server with Docker; no GPU needed.
  • Camera: an RTSP or USB camera over the checkout or facing the shelf.
  • Model conversion: an x86_64 machine; rknn-toolkit2 does not run on the board.
  • Model licences: the detector and embedder are non-commercial only and not shipped with this solution; a commercial deployment must retrain them on first-party or permissively licensed data.
1

Deploy the Registration Console

Starts the registration service, management UI and MQTT broker on the server, and sets the role tokens.

前提条件
  • A Linux server with Docker and the compose plugin, reachable from the recognition device.
  • At least an admin token. The service allows no anonymous access.
  • A TLS reverse proxy in front of the UI before it is reachable from outside the local network.
  • The published images are used by default; to use your own build, override RETAIL_SERVER_IMAGE and RETAIL_WEB_IMAGE.
トラブルシューティング
SymptomAction
"MISSING: <image>" before compose runsCheck the server can reach the registry; for a self-built image, build it on this host first.
docker compose not foundInstall docker-compose-plugin.
Anonymous GET /v1/gallery returns 200The token check is not in effect. Stop and check the configuration.
GET /v1/gallery with the admin token returns an empty galleryExpected before the first registration.
Port 8089 already in useChange the service port and use the same port in the device configuration.
デプロイ方法

Deploy to a Linux server the recognition devices can reach.

入力が必要な項目（SenseCraft Solution アプリで入力）
  • Console Host IP*
  • SSH Username*既定値 ubuntu
  • SSH Password*
  • Registration Service Image*既定値 sensecraft-missionpack.seeed.cn/solution/edge-retail-console-server:0.2.0

    Published at sensecraft-missionpack.seeed.cn/solution/edge-retail-console-server:0.2.0 (linux/amd64 + linux/arm64). To use your own build instead, build it on this host from the upstream repository with platforms/console/Dockerfile.server and put the tag you built here. Pin a digest if your registry gives you one: gallery vectors written by one build are only comparable to vectors written by the same embedding model and the same preprocessing, and the symptom of a mismatch is "nothing is recognised", not a version error.

  • Management UI Image*既定値 sensecraft-missionpack.seeed.cn/solution/edge-retail-console-web:0.1.0

    Published at sensecraft-missionpack.seeed.cn/solution/edge-retail-console-web:0.1.0 (linux/amd64 + linux/arm64). To build your own instead, build the SPA first (`npm --prefix web/ui ci && npm --prefix web/ui run build`), then build this image with platforms/console/Dockerfile.web. The image does not run npm.

  • Admin Token*

    Registers SKUs, replaces them and rolls the gallery back. Give it to whoever decides what is in the product catalogue.

  • Operator Token

    Read access plus the device-side publishing role. Cannot change the gallery.

  • Viewer Token

    Read only — events, summaries, gallery versions. Cannot register anything.

  • Registration Service Port*既定値 8089

    Devices pull the gallery from this port. It must be reachable from every recognition device, not only from the browser.

  • Management UI Port*既定値 8080

    Put a reverse proxy terminating TLS in front of this before anyone outside the local network can reach it. A shared bearer token over plain HTTP is not authentication.

  • MQTT Port*既定値 1883

    The bundled broker configuration is anonymous plaintext and says so at the top of config/mosquitto.conf. Anyone who can reach this port can publish forged recognition events onto retail/v1/events. Bench only — add accounts and TLS before this leaves a lab bench.

2

Place the Embedding Model

Place the DINOv2-base embedding model in the console's model directory and enable it.

前提条件
  • The console from Step 1 deployed.
  • dinov2b_arcface_products10k_224_b1.onnx (348 MB, sha256 01ae07d10f638a2ebeb85100325ad79765a325d1026b728b60f1ee106e76eaae), obtained yourself; non-commercial use only.
  • 350 MB of free space on the server.
トラブルシューティング
SymptomAction
Registration works but every lookup returns the wrong SKUThe embedding model is not enabled. Set RETAIL_EMBEDDER=onnx, restart, and register every SKU again.
server container exits immediately after setting RETAIL_EMBEDDER=onnxConfirm RETAIL_EMBEDDER_ONNX is set, and the file is in assets/console/models/ with a matching name.
Galleries registered before and after a model change disagreeGalleries from different models cannot be mixed. Register every SKU again on the new model.
A commercial deployment is plannedRetrain the embedder on first-party or permissively licensed data and rebuild the gallery.
3

Register SKUs

In the console's gallery, register each SKU with 3 to 8 photos. Each registration creates a new gallery version.

前提条件
  • The admin token from Step 1.
  • 3 to 8 photos per SKU: at least front, back and side, in two lighting conditions.
  • Settle the embedding model first; changing it later means rebuilding every gallery version.
トラブルシューティング
SymptomAction
Registration refused with "fewer than three images"Upload at least three.
The same sku_id returns 409Pass replace=true to replace it.
A new version appears but the device still misses the SKUDevice-side fetching, verification and switching of gallery versions is not implemented yet.
Top-1 is clearly lowAdd more registration photos per SKU first; if still low, fine-tune the model on photos from your site.
4

Convert and Check the Detector on Rockchip

Convert the detector ONNX to .rknn on an x86_64 host and copy it to the board.

前提条件
  • An x86_64 machine with rknn-toolkit2 2.3.2, onnx 1.16.1 and setuptools below 81.
  • The toolkit version matches the board's librknnrt.so; a mismatch can load and still produce wrong results.
  • The detector ONNX, obtained yourself; academic and non-commercial use only.
  • The embedder ONNX from Step 2.
  • In the device-side runtime, give detection and embedding separate NPU cores: RETAIL_RKNN_DET_CORE_MASK=2, RETAIL_RKNN_EMBED_CORE_MASK=01. Do not use AUTO.
トラブルシューティング
SymptomAction
load_onnx fails on onnx.mappingInstall onnx 1.16.1.
pkg_resources not foundDowngrade setuptools below 81.
INT8 agreement much worse than 98%Sample calibration images evenly across the whole validation set rather than taking the first N by name.
The board has no cv2 or PILLetterbox on another machine and ship one (N, 640, 640, 3) uint8 BGR .npy; the device script needs only numpy and rknnlite.
5

Verify Registration, Retrieval and the Device Artifact

Verify console registration and download, and check the converted model against the CPU results.

前提条件
  • Steps 1 to 4 complete.
  • A clone of the upstream repository with uv sync done.
  • Photos of your own SKUs from angles you did not register.
トラブルシューティング
SymptomAction
Box agreement far below the referenceCheck the decode path and the output layout.
The software loop passes but nothing works on the boardThe loop verifies protocol behaviour only; troubleshoot the board as in Step 4.
Gallery download verifies on the server but not on the deviceCompare the sha256 on both sides and transfer the file again.
デプロイ後

Quick verification

  • uv run python tools/verify_software_loop.py passes.
  • With the admin token the gallery version increases by one per registration; with no token the console returns 401 or 403.
  • GET /v1/gallery/current/download returns a tar.gz whose SHA256SUMS verify.
  • Box agreement of the .rknn against the CPU results (IoU ≥ 0.5) is near 99.85% for fp16 and 98.35% for INT8.

Next steps

  • Fine-tune both models on data from your own shelf or checkout.
  • The device-side process platforms/rk3588/runtime.py (config platforms/rk3588/runtime.yaml) joins detection, embedding, lookup and publishing; this preset does not deploy or supervise it.
  • Measure end-to-end latency with a live camera and real store traffic.