Get Started#

This guide walks you through the installation, configuration, and first-run of the Take-Away Order Accuracy system.

Table of Contents#

  1. Prerequisites

  2. Installation

  3. Configuration

  4. Starting the Services

  5. Verify the Installation

  6. First Order Validation

Prerequisites#

For detailed hardware and software requirements, see the System Requirements guide.

Hardware Requirements#

Component

Minimum

Recommended

CPU

Intel Xeon 8 cores

Intel Xeon 16+ cores

RAM

16GB

64GB+

GPU

Intel Arc A770 (8GB)

Intel Arc

Storage

50GB SSD

200GB NVMe

Note

RAM note 16 GB system RAM is sufficient for inference. For first-time model export (setup_models.sh), a higher-memory host (48–64 GB recommended) avoids potential OOM — export there and copy ovms-service/models/ to the target system. 64 GB+ is recommended for production or multi-station deployments.

KV Cache on iGPU / low-RAM systems: On iGPU platforms, the KV cache is allocated from system RAM. Set export CACHE_SIZE=2 before running setup_models.sh to reduce KV cache to 2 GB (default is 4 GB). See ovms-service/README.md — Tuning the KV Cache Size for a full per-platform guide.

Software Requirements#

Software

Version

Purpose

Docker

24.0+

Container runtime

Docker Compose

V2+

Service orchestration

Intel GPU Driver

Latest

GPU support

Intel NPU Driver

Latest

NPU support (optional, see Running on the NPU)

Verify Prerequisites#

docker --version          # Docker version 24.0.x or higher
docker compose version    # Docker Compose version v2.x.x

Installation#

Step 1: Clone the Repository#

git clone -b main --single-branch https://github.com/intel-retail/order-accuracy.git
cd order-accuracy/take-away

Step 2: Configure the Environment#

# Create .env from template
make init-env
# Edit .env if needed — defaults work for most setups

# Initialize git submodules (for benchmark tools)
make update-submodules

Edit the generated .env file as needed. See Configuration below.

Step 3: Setup OVMS Model (First Time Only)#

Set TARGET_DEVICE in your .env before running this step. The script reads that value to export the model in the correct format for the target device.

cd ../ovms-service
./setup_models.sh --app take-away    # Downloads and exports model (~30-60 min first time)
cd ../take-away

This downloads and exports:

  • MiniCPM-V-4_5 INT4 (OpenVINO™ format)

  • YOLOv11 model (INT8 OpenVINO™)

  • EasyOCR detection and recognition models

Note

Re-run this step any time you change TARGET_DEVICE in .env.

Step 4: Build and Start Services#

# Pull images from registry (default)
make build
make up

# OR build locally from source
make build REGISTRY=false
make up

Configuration#

Environment File (.env)#

# =============================================================================
# VLM Backend
# =============================================================================
VLM_BACKEND=ovms
OVMS_ENDPOINT=http://ovms-vlm:8000
OVMS_MODEL_NAME=openbmb/MiniCPM-V-4_5-int4
VLM_PRECISION=int4           # must match the -int4 suffix in OVMS_MODEL_NAME
TARGET_DEVICE=GPU            # 'GPU', 'CPU' or 'NPU' — also set OPENVINO_DEVICE to match

# =============================================================================
# VLM Image / Decoding Options
# =============================================================================
VLM_IMAGE_MAX_SIZE=448       # frames are fitted into a 448x448 square canvas
VLM_ENABLE_THINKING=false    # keep MiniCPM's <think> reasoning disabled

# =============================================================================
# Inference Device (must match TARGET_DEVICE)
# =============================================================================
OPENVINO_DEVICE=GPU          # Used by benchmark targets

# =============================================================================
# Semantic Service
# =============================================================================
SEMANTIC_VLM_BACKEND=ovms
DEFAULT_MATCHING_STRATEGY=hybrid   # 'exact', 'semantic', or 'hybrid'
SIMILARITY_THRESHOLD=0.85
OVMS_TIMEOUT=60

# =============================================================================
# MinIO Storage
# =============================================================================
MINIO_ROOT_USER=<your-minio-username>
MINIO_ROOT_PASSWORD=<your-minio-password>
MINIO_ENDPOINT=minio:9000

Note

Changing the inference device: Set both TARGET_DEVICE and OPENVINO_DEVICE to the same value (GPU, CPU or NPU), then re-run ./setup_models.sh --app take-away to re-export the model for that device. See Running on the NPU for NPU-specific steps.

Note

VLM_ENABLE_THINKING: MiniCPM-V-4.5 is a hybrid reasoning model. Leave this false. When enabled, the model spends the whole token budget on a <think> reasoning block and the detected-item list is truncated, which shows up as missing items and ~4x higher latency.

Note

VLM_IMAGE_MAX_SIZE: Each selected frame is fitted into a square canvas of this size (aspect ratio preserved, white padding), matching the dine-in pipeline. Larger values increase detail but also prompt tokens and latency.

Running on the NPU#

The VLM (MiniCPM-V-4.5 INT4) can run on the Intel® NPU. Only the VLM runs on the NPU; YOLO and OCR are unaffected.

  1. Install the Intel NPU driver and confirm the device is visible and accessible to your user:

    ls -l /dev/accel/accel0    # must exist; group is typically 'render'
    
  2. Set the device in .env:

    TARGET_DEVICE=NPU
    OPENVINO_DEVICE=NPU
    # Optional: max prompt length (tokens) compiled into the NPU model (default 4096)
    # NPU_MAX_PROMPT_LEN=4096
    
  3. Re-export the model. The NPU needs a different export (non-continuous-batching VLM pipeline and symmetric INT4 weights), so setup_models.sh re-exports automatically when switching to or from NPU (the first NPU export takes a while):

    cd ../ovms-service && ./setup_models.sh --app take-away && cd ../take-away
    
  4. Start the services with make up. The Makefile maps /dev/accel (instead of /dev/dri) into the OVMS container. If you use docker compose directly, also set OVMS_DEVICE_NODE=/dev/accel in .env.

Note

The first start compiles the model for the NPU and can take several minutes; wait until curl http://localhost:8001/v1/config reports AVAILABLE. make check-env fails if the exported model does not match TARGET_DEVICE=NPU; re-run setup_models.sh in that case.

Validate Configuration#

make check-env    # Validate required variables
make show-config  # Show current configuration

Starting the Services#

Single Mode (default)#

make up

Parallel Worker Mode (multi-station)#

make up-parallel WORKERS=4

RTSP Streamer (live stream testing)#

To feed a looping video as a live RTSP stream:

Note

Prerequisite: Place a test video at storage/videos/test.mp4 first, or run make download-sample-video.

WORKERS=1 docker compose --profile parallel up -d --no-deps rtsp-streamer

Access From

URL

Host machine

rtsp://localhost:8554/station_1

Other containers

rtsp://rtsp-streamer:8554/station_1

Increase WORKERS for multiple stations (station_1, station_2, etc.).

View Logs#

make logs

Verify the Installation#

Health Check#

make test-api

This checks both the order accuracy API (localhost:8000) and OVMS (localhost:8001).

Service URLs#

Service

URL

Order Accuracy API

http://localhost:8000

OVMS VLM

http://localhost:8001

Gradio UI

http://localhost:7860

MinIO Console

http://localhost:9001

Semantic Service

http://localhost:8080

Service Status#

make status

First Order Validation#

Via Gradio UI#

  1. Open http://localhost:7860

  2. Upload a test video or enter an RTSP URL

  3. Click “Upload and Start Processing”

  4. View results showing matched, missing, and extra items

Via REST API#

# Upload video and validate
curl -X POST http://localhost:8000/upload-video \
  -F "file=@storage/videos/test.mp4" \
  -F "video_id=test_001"

# Check results
curl http://localhost:8000/results/test_001

Via Make Target#

Note

Prerequisite: Ensure storage/videos/test.mp4 exists. Run make download-sample-video if needed.

make benchmark

Quick Reference#

make update-submodules      # Init submodules (first time)
make download-sample-video  # Download sample video
make init-env               # Create .env from template
make build && make up       # Build images and start services
make status                 # Check service status
make logs                   # View logs
make test-api               # Test API health
make down                   # Stop services
make clean                  # Stop containers and remove volumes
make benchmark              # Run fixed-workers benchmark
make benchmark-stream-density  # Run stream density benchmark

Next Steps#