# Get Started This guide walks you through installation, configuration, and first run of the Dine-In Order Accuracy system. ## Table of Contents 1. [Prerequisites](#prerequisites) 2. [Installation](#installation) 3. [Verify the Installation](#verify-the-installation) 4. [First Order Validation](#first-order-validation) ## Prerequisites For detailed hardware and software requirements, see the [System Requirements](./get-started/system-requirements.md) guide. - Docker 24.0+ with Compose V2 - Intel GPU with drivers installed (or an Intel NPU with its driver — see [Running on the NPU](#running-on-the-npu)) - 16 GB RAM minimum (64 GB recommended for production) - 50 GB free disk space > [!NOTE] > **KV Cache on iGPU / low-RAM systems:** 16 GB RAM is sufficient for **inference**. > For first-time model export, a higher-memory host (48–64 GB) is recommended. > 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](https://github.com/intel-retail/order-accuracy/blob/main/ovms-service/README.md#tuning-the-kv-cache-size) for a full per-platform guide. ```bash docker --version docker compose version ``` ## Installation ### Step 1: Clone the Repository ```bash git clone -b main --single-branch https://github.com/intel-retail/order-accuracy.git cd order-accuracy/dine-in ``` ### Step 2: Configure the Environment ```bash # 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 ``` ### Step 3: Setup OVMS Model (First Time Only) The setup script reads model configuration (device, precision, model name) from `dine-in/.env` (created in Step 2), so **complete Step 2 before running this step**. ```bash cd ../ovms-service ./setup_models.sh --app dine-in # Downloads and exports model (~30-60 min first time) cd ../dine-in ``` This downloads MiniCPM-V-4.5 and converts it to OpenVINO™ INT4 format. This is only needed once — the model files are shared with Take-Away. ### Step 4: Prepare Test Data Before running the application, you must prepare your test data: 1. **Add Images**: Place your food tray images in the `images/` folder - Supported formats: `.jpg`, `.jpeg` or `.png` - Images should clearly show the food items on the tray 2. **Update Orders**: Edit `configs/orders.json` with your test orders - Each order should have an `items_ordered` entry, each with `item` and `quantity` - `image_id` should match your image filenames in the `images/` folder 3. **Update Inventory**: Edit `configs/inventory.json` to match your menu items - Define all possible food items that can appear in orders - Include item names, categories, and any relevant metadata ### Step 5: Build and Start ```bash # Pull images from registry (default) make build && make up # OR build locally from source make build REGISTRY=false && make up ``` This starts 4 containers: | Container | Ports | Purpose | | ------------------------- | ---------- | ----------------------- | | `dinein_app` | 7861, 8083 | Gradio UI + FastAPI | | `dinein_ovms_vlm` | 8002 | VLM model server (OVMS) | | `dinein_semantic_service` | 8081, 9091 | Semantic matching | | `metrics-collector` | 9000 | System metrics | --- ## Verify the Installation ```bash # API health check make test-api # Or directly curl http://localhost:8083/health # Check OVMS model curl http://localhost:8002/v1/config | jq . ``` Open `http://localhost:7861` for the Gradio UI, or `http://localhost:8083/docs` for the REST API docs. --- ## First Order Validation ### Via Gradio UI 1. Open `http://localhost:7861` 2. Select a scenario from the dropdown 3. Review the order manifest 4. Click **"Validate Plate"** 5. View accuracy score, matched/missing/extra items, and performance metrics ### Via REST API The bundled `MCD-1001.png` image shows **Filet-O-Fish** and **Cheesy Fries** on the tray. Two test scenarios are provided: **Negative test case** — order does not match tray (demonstrates mismatch detection): ```bash curl -X POST "http://localhost:8083/api/validate" \ -F "image=@images/MCD-1001.png" \ -F 'order={"items":[{"name":"Cheeseburger","quantity":1},{"name":"French Fries","quantity":1}]}' # Expected: order_complete=false, accuracy_score=0.0 ``` **Positive test case** — order matches tray (demonstrates successful validation): ```bash curl -X POST "http://localhost:8083/api/validate" \ -F "image=@images/MCD-1001.png" \ -F 'order={"items":[{"name":"Filet-O-Fish","quantity":1},{"name":"Cheesy Fries","quantity":1}]}' # Expected: order_complete=true, accuracy_score=1.0 ``` ### Via Make Target ```bash # Services must be running first make benchmark-single IMAGE_ID=MCD-1001 ``` --- ## Changing Inference Device To switch between GPU, CPU and NPU, update `TARGET_DEVICE` in `.env` and re-run model setup: ```bash # In .env TARGET_DEVICE=CPU cd ../ovms-service && ./setup_models.sh --app dine-in && cd ../dine-in make down && make up ``` ### Running on the NPU The VLM (MiniCPM-V-4.5 INT4) can run on the Intel® NPU. 1. Install the Intel NPU driver and confirm the device is visible and accessible to your user: ```bash ls -l /dev/accel/accel0 # must exist; group is typically 'render' ``` 2. Set the device in `.env`: ```bash TARGET_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: ```bash cd ../ovms-service && ./setup_models.sh --app dine-in && cd ../dine-in ``` 4. Run `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:8002/v1/config` reports `AVAILABLE`. > `make up` fails (via `check-device`) if the exported model does not match `TARGET_DEVICE=NPU`; re-run `setup_models.sh` in that case. > The model is shared with Take-Away, so switching the device here also changes the model used by Take-Away. ## Quick Reference ```bash make up # Start services (registry image) make up REGISTRY=false # Start with locally built image make down # Stop services make logs # View logs make test-api # Health check make benchmark-single IMAGE_ID=... # Quick test make benchmark # Full benchmark make benchmark-stream-density # Stream density test make clean # Stop and remove volumes make clean-images # Remove dangling Docker images make clean-all # Remove all unused Docker resources make help # All commands ``` ## Next Steps - [System Requirements](./get-started/system-requirements.md) - Check the detailed requirements - [Build from Source](./get-started/build-from-source.md) - Build from source - [How It Works](./how-it-works.md) - Learn about the architecture - [How to Use](./how-to-use.md) - Customize settings - [Benchmarking Guide](./di-benchmarking.md) - Run benchmarks - [API Reference](./api-reference.md) - Learn the API - [Troubleshooting](./troubleshooting.md) - Resolve common issues - [Release Notes](./release-notes.md) - Read about updates and improvements :::{toctree} :hidden: ./get-started/system-requirements.md ./get-started/build-from-source.md :::