<!--
SPDX-FileCopyrightText: (C) 2026 Intel Corporation
SPDX-License-Identifier: Apache-2.0
-->

# Get Started

The Video Search and Summarization (VSS) sample application helps developers create a summary of long form video, search for the right video, and combine both search and summarization pipelines. This guide will help you set up, run, and modify the sample application on local and Edge AI systems.

This guide shows how to:

- **Set up the sample application**: Use the setup script to quickly deploy the application in your environment.
- **Run different application modes**: Deploy in summary-only, search-only, dual-UI, or unified mode.
- **Modify application parameters**: Customize settings like inference models and deployment configurations to adapt the application to your specific requirements.

## Deployment Modes

The application supports **four** deployment modes. Each mode deploys only the services and UI(s) relevant to the selected functionality:

| Mode | Features | UI Layout | Description | Command Option |
| ---- | -------- | --------- | ----------- | -------------- |
| **Summary** | Video summarization only | Summary UI available at `/` (root URI) | Summarize a given video with several tunable parameters. | `--summary` |
| **Search** | Video Search only | Search UI available at `/` (root URI). | Search for entities in a given video. **Embedding used for search:** Video frame embeddings | `--search` |
| **Dual UI** | Video Summarization and Video Search | Two separate UIs available at `/summary/` and `/search/` URI. | **Embedding used for search:** Video frame embeddings | `--summary --search` |
| **Unified UI** | Video Summarization and **Modified** Video Search | A single unified UI available at `/` (root URI). | **Embedding used for search:** Summarized content text embeddings | `--summary-and-search` |

> **NOTE :** The video search in **Unified UI** mode is modified for creating the embeddings of video summary texts and searching over them, rather than creating and using video frame embeddings. Hence, this mode includes video summarization feature, as well, in the same UI.

## Prerequisites

- Verify that your system meets the [minimum requirements](./get-started/system-requirements.md).
- Install Docker tool: [Installation Guide](https://docs.docker.com/get-docker/).
- Install Docker Compose tool: [Installation Guide](https://docs.docker.com/compose/install/).
- Install Python programming language v3.11

## Project Structure

The repository is organized as follows:

```text
sample-applications/video-search-and-summarization/
├── config/                        # Runtime configs
│   ├── nginx/                     # Nginx templates used by setup.sh + compose
│   │   ├── nginx.conf
│   │   ├── dual_ui.conf
│   │   └── singleton_ui.conf
│   └── rmq.conf                   # RabbitMQ configuration
├── docker/                        # Docker Compose base and overlays
│   ├── compose.base.yaml
│   ├── compose.ui.yaml
│   ├── compose.summary.yaml
│   ├── compose.search.yaml
│   ├── compose.search.vdms.yaml   # VDMS vector-DB backend overlay (default)
│   ├── compose.search.milvus.yaml # Milvus vector-DB backend overlay
│   ├── compose.vllm.yaml          # vLLM CPU backend
│   ├── compose.vllm.xpu.yaml      # vLLM Intel Arc Pro B-series GPU/XPU backend (experimental)
│   ├── compose.gpu_ovms.yaml
│   └── compose.metrics-manager.yaml
├── docs/
│   └── user-guide/                # User guides and tutorials
├── pipeline-manager/              # Orchestrates summarization and search pipelines
├── search-ms/                     # Video search microservice
├── video-ingestion/               # Video ingestion and processing service
├── ui/
│   └── react/                     # Frontend application
├── cli/                           # Terminal UI and CLI workflows
├── scripts/                       # Utility and helper scripts
├── data/                          # Default watcher/input data directory
├── ov_models/                     # Local model cache/artifacts
├── build.sh                       # Script for building application images
├── setup.sh                       # Main setup and deployment script
└── README.md
```

## Set Required Environment Variables

Before running the application, you need to set several environment variables:

1. **Configure the registry**:
   The application uses registry URL and tag to pull the required images.

   ```bash
   export REGISTRY_URL=intel
   export TAG=2026.2.0-rc2
   ```

2. **Set required credentials for some services**:
   Following variables **must** be set on your current shell before running the setup script:

   ```bash
   # MinIO credentials (object storage)
   export MINIO_ROOT_USER=<your-minio-username>
   export MINIO_ROOT_PASSWORD=<your-minio-password>

   # PostgreSQL credentials (database)
   export POSTGRES_USER=<your-postgres-username>
   export POSTGRES_PASSWORD=<your-postgres-password>

   # RabbitMQ credentials (message broker)
   export RABBITMQ_USER=<your-rabbitmq-username>
   export RABBITMQ_PASSWORD=<your-rabbitmq-password>
   ```

3. **Set environment variables for model selection**:

   You **must** set these environment variables on your current shell. Setting these variables is **mandatory** as they **do not** have any default values.

   - **Mode-specific environment variables to set Models:**

      | Variable | Mode | Purpose |
      | -------- | ---- | ------- |
      | `VLM_MODEL_NAME` | Summary, Dual UI, Unified UI | VLM model for video captioning and summarization. |
      | `ENABLED_WHISPER_MODELS` | Summary, Dual UI, Unified UI | Whisper model(s) for audio analysis. |
      | `OD_MODEL_NAME` | Summary, Dual UI, Unified UI | YOLO model for object detection during video ingestion. |
      | `MULTIMODAL_EMBEDDING_MODEL` | Search, Dual UI | Multimodal model for generating video frame embeddings. |
      | `TEXT_EMBEDDING_MODEL` | Unified UI | Text embedding model for generating summary text embeddings. |
      | `OVMS_LLM_MODEL_NAME` | _(Optional)_ Summary, Dual UI, or Unified UI | LLM for OVMS-based final summary generation. When set and different from `VLM_MODEL_NAME`, enables split-model mode (separate VLM for captioning, LLM for summarization). |
      | `PM_AUDIO_USE_FULL_TRANSCRIPT_SUMMARY` | _(Optional)_ Summary, Dual UI | Enables condensed transcript summary injection in the prompt to generate video summary. |

     **Common to all modes except `--search`:**

      ```bash
      # For VLM-based chunk captioning and video summarization on CPU
      export VLM_MODEL_NAME="Qwen/Qwen3-VL-4B-Instruct"  # or any other supported VLM model on CPU

      # For VLM-based chunk captioning and video summarization on GPU
      export VLM_MODEL_NAME="OpenVINO/Phi-3.5-vision-instruct-int8-ov"  # or any other supported VLM model on GPU
      export VLM_TARGET_DEVICE="GPU"  # Options: CPU, GPU, NPU, HETERO:GPU,CPU

      # (OPTIONAL) For OVMS split-model summarization, set a dedicated LLM model for final summary.
      # If this is not set, OVMS falls back to VLM_MODEL_NAME as the LLM model source.
      # OVMS uses shared mode only when model source, target device, and compression format all match.
      export OVMS_LLM_MODEL_NAME="Qwen/Qwen3-4B-Instruct-2507"  # or any other supported LLM model
      export LLM_TARGET_DEVICE="CPU"  # Options: CPU, GPU, NPU, HETERO:GPU,CPU

      # When ENABLE_VLLM=true, vLLM is the only inference backend and setup.sh ignores OVMS_LLM_MODEL_NAME.

      # Model used by Audio Analyzer service. Only Whisper models variants are supported.
      # Common Supported models: tiny.en, small.en, medium.en, base.en, large-v1, large-v2, large-v3.
      # You can provide just one or comma-separated list of models.
      export ENABLED_WHISPER_MODELS="tiny.en,small.en,medium.en"

      # Object detection model used for Video Ingestion Service. Only generic
      # YOLO models supported by the model-download ultralytics hub are
      # supported (e.g. yolov8l, yolov8s).
      export OD_MODEL_NAME="yolov8l"
      ```

     **Required in `--search` and `--summary --search` mode:**

      ```bash
      # Required for searching on video frame embeddings
      export MULTIMODAL_EMBEDDING_MODEL="CLIP/clip-vit-b-32"
      ```

     **Required in `--summary-and-search` mode:**

      ```bash
      # Required for searching on video summary text embeddings
      export TEXT_EMBEDDING_MODEL="QwenText/qwen3-embedding-0.6b"
      ```

      > **Note:** Review the supported model list in [supported-models](https://docs.openedgeplatform.intel.com/2026.2/edge-ai-libraries/multimodal-embedding-serving/supported-models.html) before choosing model names.

4. **Configure summarization to use audio transcript (Summary and Dual UI mode):**

   Used in `--summary` and `--summary --search` mode:

      ```bash
      # (OPTIONAL) Default value is true. Users can override this per-video in the upload modal.
      export PM_AUDIO_USE_FULL_TRANSCRIPT_SUMMARY=false
      ```

      > **Audio Transcript Summarization (`PM_AUDIO_USE_FULL_TRANSCRIPT_SUMMARY`)**:
      > When enabled (the default), the pipeline runs a separate LLM-based map-reduce summarization pass over the complete audio transcript *before* generating the final video summary. The condensed transcript summary is then injected into the video summary prompt via the `%audio_summary%` placeholder, giving the LLM a coherent, high-quality representation of spoken content rather than raw subtitle fragments. This significantly improves accuracy for dialogue-heavy or narration-heavy videos. When disabled, audio transcripts are only used at the chunk captioning level, each chunk's VLM prompt includes its time-matched portion of the transcript but no audio content is included in the final map-reduce video summary.
      >
      > This environment variable sets the **default** value. Users can override it per-video using the **"Use Audio in Summary"** checkbox in the Audio Settings section of the video upload modal.

5. **Configure Directory Watcher (Search and Dual UI mode)**:

   For automated video ingestion into the search pipeline (available only  in `--search` and `--summary --search` modes), you can use the directory watcher service:

      ```bash
      # Path to the directory to watch on the host system. Default: "edge-ai-libraries/sample-applications/video-search-and-summarization/data"
      export VS_WATCHER_DIR="/path/to/your/video/directory"
      ```

   > **Directory Watcher**: For complete setup instructions, configuration options, and usage details, see the [Directory Watcher Service Guide](./directory-watcher-guide.md). This service only works with `--search` and `--summary --search` modes.

6. **Control the frame extraction interval (Search and Dual UI mode)**:

   The DataPrep microservice samples frames from uploaded videos according to the `FRAME_INTERVAL` environment variable. Set this variable before running `source setup.sh` to control how often frames are selected for processing.

   ```bash
   export FRAME_INTERVAL=15
   ```

   In the example above, DataPrep processes every fifteenth frame: each selected frame (optionally after object detection) is converted into embeddings and stored in the vector database. Lower values improve recall at the cost of higher compute and storage usage, while higher values reduce processing load but may skip important frames. If you do not set this variable, the service falls back to its configured default.

7. **Control duplicate-upload behavior in DataPrep (Search and Dual UI mode)**:

   This setting controls whether DataPrep accepts repeated uploads of the same video content:

   ```bash
   # Default true: allow content-identical re-uploads (historical behavior)
   # Set false to reject duplicate-content uploads with HTTP 409.
   export MM_DATAPREP_ALLOW_DUPLICATE_UPLOADS=true
   ```

   Duplicate detection is **content-based** (SHA-256 of uploaded bytes), not filename-based. A renamed copy of the same video is still detected as duplicate content, while two different videos that share the same filename are treated as different uploads.

8. **Enable ROI consolidation (Search and Dual UI mode)**:

   ROI consolidation groups overlapping object detections into merged regions of interest (ROIs) before cropping for embeddings. Enable this feature and tune it with the following environment variables:

   ```bash
   # Enable ROI consolidation (default: false)
   export ROI_CONSOLIDATION_ENABLED=true

   # IoU threshold for grouping ROIs (higher = stricter merging)
   export ROI_CONSOLIDATION_IOU_THRESHOLD=0.2

   # Only merge ROIs with the same class label when true
   export ROI_CONSOLIDATION_CLASS_AWARE=false

   # Expand merged ROIs by a fraction of width/height
   export ROI_CONSOLIDATION_CONTEXT_SCALE=0.2
   ```

   The IoU calculation follows the standard formula:

   $$
   IoU(A, B) = \frac{|A \cap B|}{|A \cup B|}
   $$

   > **Note:** Enabling ROI consolidation can improve search relevance by creating more meaningful regions for embedding, but it may also increase processing time.

9. **(Optional) Metrics Manager (Search, Dual UI, and Unified UI modes)**:

   Metrics Manager collects CPU, RAM, Intel® GPU, and Intel® NPU metrics and
   serves them to the UI over server-sent events. Multimodal DataPrep publishes
   each completed embedding pipeline's embeddings-per-second value directly to
   Metrics Manager; Pipeline Manager is not part of this path.

   ```bash
   # Disabled by default
   export ENABLE_METRICS_MANAGER=false

   # Enable live metrics
   export ENABLE_METRICS_MANAGER=true
   ```

   This integration requires the coordinated `multimodal-dataprep` image that
   supports `MM_DATAPREP_METRICS_MANAGER_URL`. Metrics publishing is
   non-blocking: video ingestion continues if Metrics Manager is unavailable.
   GPU and NPU panels remain empty on hosts without those devices.

10. **Tune Inference Concurrency (Summary and Dual UI mode)**:

    Control how many concurrent inference requests the pipeline manager sends to OVMS or vLLM. These values affect throughput and resource utilization:

    ```bash
    # Maximum concurrent VLM requests for chunk captioning (default: 6 for CPU, 1 for GPU)
    export PM_VLM_CONCURRENT=6

    # Maximum concurrent LLM requests for final summarization (default: 1)
    export PM_LLM_CONCURRENT=1
    ```

    > **Note:** For OVMS deployments, these values should not exceed the `max_num_seqs` parameter configured during model export (default: 256). For GPU deployments, lower concurrency (1-2) is recommended to avoid memory pressure. The setup script automatically adjusts these defaults based on the selected device (CPU vs GPU).

11. **Override OVMS Model Weight Compression Format (Summary and Dual UI mode)**:

    When using OVMS for inference, the setup script auto-selects the model weight compression format based on the target device (`int8` for CPU, `int4` for GPU/NPU). You can override this auto-detection by setting these variables before running the setup script:

    ```bash
    # Override VLM model weight compression format (default: int8 for CPU, int4 for GPU/NPU)
    export VLM_COMPRESSION_WEIGHT_FORMAT=int4

    # Override LLM model weight compression format (default: int8 for CPU, int4 for GPU/NPU)
    export LLM_COMPRESSION_WEIGHT_FORMAT=int4
    ```

    > **Note:** Lower precision formats like `int4` reduce memory usage and can improve throughput, but may affect output quality. The default auto-detection (`int8` for CPU, `int4` for GPU/NPU) is recommended for most use cases.

12. **Configure Embedding Execution (Search and Dual UI mode)**:

    The `multimodal-dataprep` service loads the embedding model in-process and generates
    embeddings during video search indexing. Enable OpenVINO™ optimization for the
    in-process embedding path:

    ```bash
    # Enable OpenVINO optimization for in-process embedding (default: true)
    # Automatically set to true when using GPU/NPU mode
    export SDK_USE_OPENVINO=true
    ```

    > **Note:** `multimodal-dataprep` embeds in-process (no separate embedding service is required for indexing). The standalone `multimodal-embedding-serving` service is used by `vector-retriever` to embed queries at search time.

13. **Select devices per processing component (Search and Unified UI mode)**:

    Each processing component picks its device independently. All default to `CPU`; set any to `GPU` or `NPU` as needed.

    ```bash
    # Embedding in multimodal-dataprep (in-process)
    export DATAPREP_EMBEDDING_DEVICE=GPU
    # YOLOX object detection in multimodal-dataprep
    export DATAPREP_DETECTION_DEVICE=CPU
    # Embedding in multimodal-embedding-serving (used by vector-retriever at query time)
    export MME_EMBEDDING_DEVICE=GPU
    ```

    There is no "baseline" device, each component is configured directly, matching the Helm chart's per-component model.

    > **Device note:** `DATAPREP_EMBEDDING_DEVICE` controls in-process embedding execution in `multimodal-dataprep`. `DATAPREP_DETECTION_DEVICE` controls YOLOX object detection in `multimodal-dataprep`. `MME_EMBEDDING_DEVICE` controls embedding execution in `multimodal-embedding-serving`, which `vector-retriever` uses to embed queries at search time. `ENABLE_EMBEDDING_GPU=true` is a shortcut that sets `DATAPREP_EMBEDDING_DEVICE=GPU`. For NPU, set the explicit device variables.

14. **🧪 EXPERIMENTAL: Configure vLLM Intel Arc Pro B-series GPU/XPU Backend**:

    > **⚠️ Experimental Feature:** Intel Arc Pro B-series GPU (XPU) support with vLLM is in early development stages and may have stability issues. Not recommended for production use.

    Enable GPU-accelerated vLLM inference on Intel Arc Pro B-series GPUs (XPUs):

    ```bash
    # Enable vLLM with Intel Arc Pro B-series GPU/XPU support (default: false)
    export ENABLE_VLLM_GPU=true

    # Set the VLM model for vLLM GPU inference
    export VLM_MODEL_NAME="Qwen/Qwen2.5-VL-3B-Instruct"
    ```

    **Additional vLLM GPU/XPU configuration options:**

    | Variable | Description | Default |
    | -------- | ----------- | ------- |
    | `VLLM_XPU_IMAGE` | Docker image for vLLM XPU service | `intel/vllm:0.14.1-xpu` |
    | `VLLM_DTYPE` | Model precision | `bfloat16` |
    | `VLLM_GPU_MEM` | GPU memory utilization (0-1) | `0.8` |
    | `VLLM_MAX_MODEL_LEN` | Maximum sequence length | `32000` |
    | `VLLM_MAX_NUM_SEQS` | Maximum concurrent sequences | `256` |
    | `VLLM_BLOCK_SIZE` | KV cache block size | `128` |
    | `VLLM_MAX_NUM_BATCHED_TOKENS` | Maximum batched tokens | `2048` |
    | `VLLM_TENSOR_PARALLEL_SIZE` | Tensor parallel size | `1` |
    | `VLLM_HOST_PORT` | Host port for vLLM service | `8200` |

    **System Requirements:**
    - Intel Arc Pro B-series GPU (e.g., Intel Arc Pro B60, B65, B70)
    - Intel GPU drivers installed on host
    - User in `video` and `render` groups
    - Minimum 8GB GPU memory

    **Behavior when enabled:**
    - Automatically sets `VLLM_HOST=vllm-xpu-service`
    - Disables OVMS backend completely
    - Uses the same VLM model for captioning and summarization
    - Reduces concurrency to prevent GPU memory issues
    - Launches `vllm-xpu-service` with GPU device access

    > **Note:** See the [Run the Application](#run-the-application) section below for complete usage examples with `ENABLE_VLLM_GPU=true`.

**Work with Gated Models**:

To run a **GATED MODEL** like Llama models, you will need to pass your [huggingface token](https://huggingface.co/docs/hub/security-tokens#user-access-tokens). You will need to request for an access to a specific model by going to the respective model page on Hugging Face website.

Go to <https://huggingface.co/settings/tokens> to get your token.

```bash
export GATED_MODEL=true
export HUGGINGFACE_TOKEN=<your_huggingface_token>
```

Once exported, run the setup script as mentioned [here](#run-the-application). Switch off the `GATED_MODEL` flag by running `export GATED_MODEL=false`, once you no longer use gated models. This avoids unnecessary authentication step during setup.

## Application Overview

The Video Search and Summarization application supports multiple deployment modes, each served behind a single nginx reverse proxy on one port. The mode determines which services and UI(s) are brought up.

> **Note:** The application runs on port 12345 by default. You can change this by setting `APP_HOST_PORT` environment variable to another port number.

| Mode | Command Option | UI Instances | Default URL(s) |
| ---- | -------------- | ------------ | -------------- |
| Summary | `--summary` | Single Summary UI | `http://<host-ip>:12345/` |
| Search | `--search` | Single Search UI | `http://<host-ip>:12345/` |
| Dual UI | `--summary --search` | Separate Summary and Search UIs | `http://<host-ip>:12345/summary/` and `http://<host-ip>:12345/search/` |
| Unified UI | `--summary-and-search` | Single unified UI (summary + search) | `http://<host-ip>:12345/` |

> **Note:** In `--summary --search` mode, visiting `http://<host-ip>:12345/` redirects to the Video Summarization UI.

In modes, where Video Search is available (Search, Dual UI and Unified UI mode), the Vector DB index, the modality of input being used for creating embeddings and the embedding models would differ with modes.

| Mode | Vector-DB Index | Search Modality | Environment Variable Used |
| ---- | --------------- | --------------- | ------------------------- |
| Search | `video_frame_embeddings` | Multimodal embeddings of video frames | `MULTIMODAL_EMBEDDING_MODEL` |
| Dual UI | `video_frame_embeddings` | Multimodal embeddings of video frames | `MULTIMODAL_EMBEDDING_MODEL` |
| Unified UI | `video_summary_embeddings` | Text embeddings of generated summaries | `TEXT_EMBEDDING_MODEL` |

> **Automated Video Ingestion**: The Video Search pipeline includes an optional Directory Watcher service for automated video processing. See the [Directory Watcher Service Guide](./directory-watcher-guide.md) for details.

### Deployment Options for Video Summarization

| **Deployment Option** | **Chunk-Wise Summary<sup>(1)</sup> Configuration** | **Final Summary<sup>(2)</sup> Configuration** | **Environment Variables to Set** | **Recommended Models** | **Recommended Usage Model** |
|--------|--------------------|---------------------|-----------------------|----------------|----------------|
| OVMS shared-model CPU | OVMS-hosted VLM on CPU | Same OVMS-hosted VLM on CPU | Default | VLM: `Qwen/Qwen3-VL-4B-Instruct` | Default CPU-only summarization flow. |
| OVMS shared-model GPU | OVMS-hosted VLM on GPU | Same OVMS-hosted VLM on GPU | `VLM_TARGET_DEVICE=GPU` with `LLM_TARGET_DEVICE=GPU` | VLM: `OpenVINO/Phi-3.5-vision-instruct-int8-ov` | Single-model OVMS deployment with GPU acceleration. |
| OVMS split-model CPU/CPU | OVMS-hosted VLM on CPU | OVMS-hosted LLM on CPU | `OVMS_LLM_MODEL_NAME=<llm-model>` | VLM: `Qwen/Qwen3-VL-4B-Instruct`<br>LLM: `Qwen/Qwen3-4B-Instruct-2507` | One OVMS instance hosts separate VLM and LLM models on CPU. |
| OVMS split-model GPU/CPU | OVMS-hosted VLM on GPU | OVMS-hosted LLM on CPU | `VLM_MODEL_NAME=Qwen/Qwen3-VL-4B-Instruct` + `VLM_TARGET_DEVICE=GPU` + `LLM_TARGET_DEVICE=CPU` (optionally set `OVMS_LLM_MODEL_NAME=<llm-model>`) | VLM: `Qwen/Qwen3-VL-4B-Instruct`<br>LLM: `Qwen/Qwen3-VL-4B-Instruct` (or dedicated `OVMS_LLM_MODEL_NAME`) | Use GPU for captioning while keeping final summary on CPU; also supports same-source split by device/weight. |
| OVMS split-model CPU/GPU | OVMS-hosted VLM on CPU | OVMS-hosted LLM on GPU | `VLM_MODEL_NAME=Qwen/Qwen3-VL-4B-Instruct` + `LLM_TARGET_DEVICE=GPU` (optionally set `OVMS_LLM_MODEL_NAME=<llm-model>`) | VLM: `Qwen/Qwen3-VL-4B-Instruct`<br>LLM: `Qwen/Qwen3-VL-4B-Instruct` (or dedicated `OVMS_LLM_MODEL_NAME`) | Use GPU for final summary while keeping captioning on CPU; also supports same-source split by device/weight. |
| OVMS split-model CPU/NPU | OVMS-hosted VLM on CPU | OVMS-hosted LLM on NPU | `LLM_TARGET_DEVICE=NPU` (optionally set `OVMS_LLM_MODEL_NAME=<llm-model>` for a dedicated LLM) | VLM: `Qwen/Qwen3-VL-4B-Instruct`<br>LLM: `OpenVINO/Qwen3-8B-int4-cw-ov` | Use NPU for the final-summary LLM while keeping captioning on CPU. |
| vLLM-only CPU | vLLM-hosted VLM on CPU | Same vLLM-hosted VLM on CPU | `ENABLE_VLLM=true` | VLM: `Qwen/Qwen2.5-VL-3B-Instruct` | All-vLLM mode for CPU-only deployments. |
| 🧪 vLLM-only GPU/XPU (**EXPERIMENTAL**) | vLLM-hosted VLM on Intel Arc Pro B-series GPU | Same vLLM-hosted VLM on Intel Arc Pro B-series GPU | `ENABLE_VLLM_GPU=true` | VLM: `Qwen/Qwen2.5-VL-3B-Instruct` | **EXPERIMENTAL**: All-vLLM mode with Intel Arc Pro B-series GPU/XPU acceleration. Early-stage feature. |

> **Note:**
>
> 1) Chunk-Wise Summary is a method of summarization where it breaks videos into chunks and then summarizes each chunk.
> 2) Final Summary is a method of summarization where it summarizes the whole video.
> 3) Mixed OVMS+vLLM deployments are not supported in the compose setup. Choose either OVMS-only, vLLM-CPU-only, or vLLM-GPU-only for summarization.
> 4) `VLM_TARGET_DEVICE` and `LLM_TARGET_DEVICE` support values: `CPU`, `GPU`, `NPU`, or `HETERO:GPU,CPU` for heterogeneous execution.
> 5) **NPU Support:** Not all models support NPU execution. Verify model compatibility at the [OpenVINO™ Supported Models](https://docs.openvino.ai/2026/documentation/compatibility-and-support/supported-models.html) page before selecting `NPU` as target device.
> 6) OVMS mode selection is based on effective VLM/LLM settings: if model source, target device, and compression format are all identical, setup uses shared mode; otherwise it uses split mode.
> 7) For same-source split examples (same model name on different devices/formats), prefer non-`OpenVINO/` source models (for example, `Qwen/Qwen3-VL-4B-Instruct`). `OpenVINO/` namespace models are pre-converted and use model-intrinsic/fixed weight formats.
> 8) **🧪 EXPERIMENTAL - Intel Arc Pro B-series GPU Support:** vLLM on Intel Arc Pro B-series GPUs/XPUs (`ENABLE_VLLM_GPU=true`) is **experimental** and in early development stages. This feature provides GPU-accelerated inference for both VLM captioning and LLM summarization but may have stability issues and requires specific Intel Arc Pro B-series GPU hardware (e.g., B60, B65, B70). When enabled, it automatically disables OVMS and uses vLLM exclusively. Not recommended for production use.

### Deployment Options for Video Search

| **Deployment Option** | **Embedding Pipeline Configuration** | **Detection Configuration** | **Environment Variables to Set** | **Recommended Models** | **Recommended Usage Model** |
|--------|--------------------|---------------------|-----------------------|----------------|----------------|
| Shared CPU | In-process embedding in `multimodal-dataprep` on CPU | Detection on CPU | (defaults — no device overrides) | Search/Dual: `CLIP/clip-vit-b-32`<br>Unified: `QwenText/qwen3-embedding-0.6b` | Default CPU-only search flow. |
| Shared GPU | In-process embedding in `multimodal-dataprep` on GPU | Detection on GPU | `DATAPREP_EMBEDDING_DEVICE=GPU` + `DATAPREP_DETECTION_DEVICE=GPU` | Search/Dual: `CLIP/clip-vit-b-32` | Run both detection and embedding execution on GPU. |
| Shared NPU | In-process embedding in `multimodal-dataprep` on NPU | Detection on NPU | `DATAPREP_EMBEDDING_DEVICE=NPU` + `DATAPREP_DETECTION_DEVICE=NPU` | Search/Dual: NPU-supported multimodal model | Run both detection and embedding execution on NPU. |
| Split CPU/NPU | In-process embedding in `multimodal-dataprep` on NPU | Detection on CPU | `DATAPREP_EMBEDDING_DEVICE=NPU` + `DATAPREP_DETECTION_DEVICE=CPU` | Search/Dual: NPU-supported multimodal model | Keep detection on CPU while offloading embedding to NPU. |
| Split CPU/GPU | In-process embedding in `multimodal-dataprep` on CPU | Detection on GPU | `DATAPREP_EMBEDDING_DEVICE=CPU` + `DATAPREP_DETECTION_DEVICE=GPU` | Search/Dual: `CLIP/clip-vit-b-32` | Offload object detection only while keeping embedding on CPU. |
| Split CPU/NPU (Detection) | In-process embedding in `multimodal-dataprep` on CPU | Detection on NPU | `DATAPREP_EMBEDDING_DEVICE=CPU` + `DATAPREP_DETECTION_DEVICE=NPU` | Search/Dual: `CLIP/clip-vit-b-32` | Offload object detection to NPU while keeping embedding on CPU. |

> **Note:**
>
> 1) These options apply to modes where search is enabled: `--search`, `--summary --search`, and `--summary-and-search`.
> 2) Each component device defaults to `CPU` and is set independently — there is no "baseline" device.
> 3) Embedding for indexing runs **in-process** in `multimodal-dataprep` and follows `DATAPREP_EMBEDDING_DEVICE`; object detection follows `DATAPREP_DETECTION_DEVICE`.
> 4) `MME_EMBEDDING_DEVICE` controls `multimodal-embedding-serving`, which `video-search` uses to embed **queries at search time** — set it independently of the indexing devices above.
> 5) **NPU Support:** Verify model compatibility at the [OpenVINO™ Supported Models](https://docs.openvino.ai/2026/documentation/compatibility-and-support/supported-models.html) page before selecting `NPU`.
> 6) `ENABLE_EMBEDDING_GPU=true` is a shortcut that sets `DATAPREP_EMBEDDING_DEVICE=GPU`. For NPU, use explicit device variables.
> 7) **4K/8K videos:** By default the shared-memory block size is sized for 1080p frames, so ingesting 4K/8K video can stall the DataPrep worker. Before ingesting high-resolution content, raise `SDK_VIDEO_SHM_BLOCK_SIZE` as described in [Troubleshooting](./troubleshooting.md#4k8k-video-ingestion-stalls-with-a-worker-timeout).

#### Vector Database Backend (VDMS or Milvus)

The search path is vector-database agnostic. All vector similarity search is delegated to the standalone `vector-retriever` microservice — which is part of the search stack for every backend — while `video-search` keeps only query orchestration and frame-to-video aggregation. Select the backend with the `VECTORDB_BACKEND` environment variable before running `setup.sh` (object storage stays on MinIO for both):

| `VECTORDB_BACKEND` | Vector database | Query path |
|--------------------|-----------------|------------|
| `vdms` (default)   | VDMS            | `video-search` delegates similarity search to the `vector-retriever-vdms` image, which reads the VDMS collection. |
| `milvus`           | Milvus (standalone) | `video-search` delegates similarity search to the `vector-retriever-milvus` image, which reads the same Milvus collection. |

```bash
# Default — VDMS backend (no variable needed)
source setup.sh --search

# Milvus backend
export VECTORDB_BACKEND=milvus
source setup.sh --search
```

> **Note:**
>
> - For **both** backends, `video-search` delegates the raw vector search to the always-on `vector-retriever` microservice and never talks to a vector database directly. `VECTORDB_BACKEND` selects the backend-baked `vector-retriever` image (`vector-retriever-${VECTORDB_BACKEND}`, via the `RETRIEVER_BACKEND` build arg). The frame-to-video aggregation still runs in `video-search`, so search results are identical in shape across backends.
> - `setup.sh` applies exactly one vector-DB overlay, so only the selected backend's containers start. `VECTORDB_BACKEND=vdms` (default) adds `docker/compose.search.vdms.yaml`, which starts `vdms-vector-db`; `VECTORDB_BACKEND=milvus` adds `docker/compose.search.milvus.yaml`, which starts a Milvus standalone stack (`milvus-etcd` + `milvus-standalone`) and no VDMS container. `multimodal-dataprep` writes embeddings to the selected backend and the matching `vector-retriever` image reads them back.
> - The similarity metric/index (`VDB_METRIC_TYPE=IP`, `VDB_INDEX_TYPE=FLAT`) is shared between `multimodal-dataprep` and `vector-retriever` and must match on both — the defaults already align.

> **Important — clean the data when switching backends:** embeddings live only in the vector database, but uploaded videos and their metadata live in MinIO and the Pipeline Manager's PostgreSQL database, which are shared across backends. Switching `VECTORDB_BACKEND` without clearing them leaves the previously ingested videos visible in the UI while the new backend holds no embeddings for them, so search returns nothing for those videos. Always wipe the user data first:
>
> ```bash
> source setup.sh --clean-data
> export VECTORDB_BACKEND=milvus   # or vdms
> source setup.sh --search
> ```
>
> `--clean-data` stops the stack and removes the MinIO, PostgreSQL, dataprep, VDMS and Milvus data volumes. Model-cache volumes are preserved, so no models are re-downloaded. Alternatively, re-ingest every video after the switch instead of cleaning.

## Using Edge Microvisor Toolkit

If you are running the VSS application on an OS image built with **Edge Microvisor Toolkit (EMT)**, an Azure Linux-based build pipeline for Intel® platforms, the deployment approach depends on the EMT flavor. Refer to the detailed documentation for [EMT-D](https://github.com/open-edge-platform/edge-microvisor-toolkit/blob/3.0/docs/developer-guide/emt-architecture-overview.md#developer-node-mutable-iso-image) and [EMT-S](https://github.com/open-edge-platform/edge-microvisor-toolkit-standalone-node) for full details.

### EMT-D (Mutable)

EMT-D is a **mutable** image that supports standard package management. You can run the VSS `setup.sh` script directly on the node after installing the required dependencies.

Install the `mesa-libGL` package (required by the Audio Analyzer service):

```bash
sudo dnf install mesa-libGL
# Or using TDNF:
sudo tdnf install mesa-libGL
```

Install additional tools such as `git` and `wget` using the same package manager. Once dependencies are in place, proceed with [running the application](#run-the-application) normally.

### EMT-S (Immutable)

EMT-S is an **immutable** OS image, standard package managers such as `apt` are not available, and the VSS `setup.sh` script **cannot be run directly on the EMT-S node** (doing so will fail with `sudo: apt: command not found`). Use one of the following approaches:

- **Option 1 (USB provisioning):** While preparing the USB drive, copy the required Docker images under `/opt/user-apps` on the image, then flash and deploy the Edge node.
- **Option 2 (Remote copy):** On a Ubuntu development system, pull/build all required Docker images and prepare the project directory. Copy the entire directory to the EMT-S node without modifications and deploy from there. This approach has been verified to successfully bring up all VSS containers.

When packages must be installed on EMT-S (for example, `mesa-libGL`), use the installroot method:

```bash
sudo env no_proxy="localhost,127.0.0.1" dnf --installroot=/opt/user-apps/tools/ -y install mesa-libGL
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/user-apps/tools/usr/lib/
```

The same method applies to any other required packages (for example, `git`, `wget`). Refer to the [EMT-S documentation](https://github.com/open-edge-platform/edge-microvisor-toolkit-standalone-node) for further details.

> **For GPU deployments on EMT-S host :** If the host does not include the host OpenCL runtime required by OpenVINO™ GPU discover, the script uses a conservative integrated-GPU OVMS cache size and continues; inference still runs inside the GPU-enabled OVMS container. Set `OVMS_CACHE_SIZE_GB` before sourcing `setup.sh` if you need an explicit cache size.

## Run the Application

Follow these steps to run the application:

1. Clone the repository and navigate to the project directory:

   ```bash
   # Clone the latest on mainline
   # git clone https://github.com/open-edge-platform/edge-ai-libraries.git edge-ai-libraries
   # Clone the release branch
   git clone https://github.com/open-edge-platform/edge-ai-libraries.git edge-ai-libraries -b release-2026.2.0

   cd edge-ai-libraries/sample-applications/video-search-and-summarization
   ```

2. [Set the required environment variables](#set-required-environment-variables).

3. Run the setup script with the desired deployment mode:

   - First, bring down any running deployment before starting:

      ```bash
      source setup.sh --stop    # or, `source setup.sh --down`
      ```

      > **IMPORTANT:** You should always run the above command before changing modes _(for example: changing from --summary mode to --search mode)_.

      > **Clean-up Tip**: If you encounter issues or want to completely reset the application data, use `source setup.sh --clean-data` to stop all containers and remove all Docker volumes including user data. This provides a fresh start for troubleshooting.

   - **Summary mode: Setup only video summarization:**

     ```bash
     source setup.sh --summary
     ```

   - **Search mode: Setup only video search:**

     ```bash
     source setup.sh --search
     ```

   - **Dual UI mode: Setup both video summarization and video search application with separate UIs:**

     ```bash
     source setup.sh --summary --search      # or, `source setup.sh --search --summary`
     ```

     When the script finishes, it prints the URLs for the both summary and search UI.

   - **Unified UI mode: Single UI containing video summarization and modified video search:**

     ```bash
     source setup.sh --summary-and-search    # or, `source setup.sh --search-and-summary`
     ```

      > **Live metrics:** Metrics Manager is disabled by default. Enable it with:
      >
      > ```bash
      > ENABLE_METRICS_MANAGER=true source setup.sh --search
      > # or
      > ENABLE_METRICS_MANAGER=true source setup.sh --summary --search
      > # or
      > ENABLE_METRICS_MANAGER=true source setup.sh --summary-and-search
      > ```

      > **Directory Watcher**: For automated video ingestion into the Search pipeline, see the [Directory Watcher Service Guide](./directory-watcher-guide.md).

   - **To run Video Summarization with OVMS using a dedicated LLM for final summary:**

      ```bash
      # Note: If OVMS_LLM_MODEL_NAME is not set, setup falls back to VLM_MODEL_NAME for final summary model source.
      # Shared vs split mode is then decided from effective model/device/compression equality.

      # For Summary mode
      OVMS_LLM_MODEL_NAME="Qwen/Qwen3-4B-Instruct-2507" source setup.sh --summary

      # For Dual UI mode
      OVMS_LLM_MODEL_NAME="Qwen/Qwen3-4B-Instruct-2507" source setup.sh --summary --search

      # For Unified UI mode
      OVMS_LLM_MODEL_NAME="Qwen/Qwen3-4B-Instruct-2507" source setup.sh --summary-and-search
      ```

   - **Use vLLM as the only inference backend (CPU):**

      ```bash
      ENABLE_VLLM=true source setup.sh --summary                 # for Summary mode
      ENABLE_VLLM=true source setup.sh --summary --search        # for Dual UI mode
      ENABLE_VLLM=true source setup.sh --summary-and-search      # for Unified UI mode
      ```

    > **Note:**
    > - The vLLM configuration has been tested on Intel® Xeon® 6 processors.
    > - Review [docker/compose.vllm.yaml](https://github.com/open-edge-platform/edge-ai-libraries/blob/release-2026.2.0/sample-applications/video-search-and-summarization/docker/compose.vllm.yaml) to understand the VLLM engine and environment variables exposed. Modify it as per your use case. Refer to the [vLLM Engine Arguments documentation](https://docs.vllm.ai/en/stable/configuration/engine_args/) and [vLLM Environment Variables documentation](https://docs.vllm.ai/en/stable/configuration/env_vars/) for more details.

   - **🧪 EXPERIMENTAL: Use vLLM with Intel Arc Pro B-series GPU/XPU acceleration:**

      > **⚠️ Experimental Feature - Intel Arc Pro B-series GPU Support:**
      > Intel Arc Pro B-series GPU/XPU support with vLLM is currently **experimental** and in early stages. This implementation provides foundational infrastructure for Intel Arc Pro B-series enablement and may require further tuning and optimization. Performance characteristics on Intel Arc Pro B-series hardware are still being evaluated.

      **System Requirements:**
      - Intel Arc Pro B-series GPU hardware (e.g., B60, B65, B70)
      - Intel GPU drivers properly installed on the host system
      - User must be a member of the `video` and `render` groups
      - Access to `/dev/dri` devices
      - Minimum 8GB GPU memory recommended

      **Verify GPU access before enabling:**

      ```bash
      # Check if /dev/dri devices exist
      ls -la /dev/dri/

      # Verify user group memberships
      groups | grep -E "video|render"
      ```

      **Usage:**

      ```bash
      ENABLE_VLLM_GPU=true source setup.sh --summary                 # for Summary mode
      ENABLE_VLLM_GPU=true source setup.sh --summary --search        # for Dual UI mode
      ENABLE_VLLM_GPU=true source setup.sh --summary-and-search      # for Unified UI mode
      ```

      **Optional: Tune vLLM GPU parameters:**

      ```bash
      export VLLM_GPU_MEM=0.8                         # GPU memory utilization (default: 0.8)
      export VLLM_MAX_MODEL_LEN=32000                 # Maximum sequence length (default: 32000)
      export VLLM_MAX_NUM_SEQS=256                    # Maximum concurrent sequences (default: 256)
      export VLLM_DTYPE=bfloat16                      # Model precision (default: bfloat16)

      ENABLE_VLLM_GPU=true source setup.sh --summary
      ```

    > **Note:**
    > - When `ENABLE_VLLM_GPU=true`, the application automatically sets `VLLM_HOST=vllm-xpu-service` and disables OVMS completely
    > - The same VLM model is used for both chunk captioning and final summarization (split-model mode is not supported)
    > - Default concurrency is reduced to `PM_VLM_CONCURRENT=1` and `PM_LLM_CONCURRENT=1` to prevent GPU memory pressure
    > - Review [docker/compose.vllm.xpu.yaml](https://github.com/open-edge-platform/edge-ai-libraries/blob/release-2026.2.0/sample-applications/video-search-and-summarization/docker/compose.vllm.xpu.yaml) to understand the vLLM XPU configuration. Refer to the [vLLM Engine Arguments documentation](https://docs.vllm.ai/en/stable/configuration/engine_args/) for parameter details.
    > - For troubleshooting, check container logs: `docker logs vllm-xpu-service`

4. (Optional) Verify the resolved environment variables and setup configurations:

      ```bash
      # To just set environment variables without starting containers
      source setup.sh --setenv

      # To see the fully resolved compose configuration (defaults to Dual UI mode)
      source setup.sh config

      # To see resolved config for a specific mode
      source setup.sh --summary config                # for Summary mode
      source setup.sh --search config                 # for Search Mode
      source setup.sh --summary --search config       # for Dual UI Mode
      source setup.sh --search-and-summary config     # for Unified UI Mode

      # To see resolved configurations for OVMS split-model summarization without starting containers.
      # (for other modes, combine --summary with --search option or replace all options with --summary-and-search)
      OVMS_LLM_MODEL_NAME="Qwen/Qwen3-4B-Instruct-2507" source setup.sh --summary config

      # To see resolved configurations for summarization services with vLLM enabled without starting containers.
      # (for other modes, combine --summary with --search option or replace all options with --summary-and-search)
      ENABLE_VLLM=true source setup.sh --summary config
      ```

### Use GPU/NPU Acceleration

> **Note:** Offloading models to different devices (e.g., VLM on CPU and LLM on NPU) is only supported with the OVMS backend. The vLLM backend runs a single model on a single device.
>
> **⚠️ NPU Support is Experimental:** Running VLM/LLM models on NPU is experimental and may not work with all models or configurations. Not all model architectures are supported on NPU. If you encounter issues, verify model compatibility at the [OpenVINO™ Supported Models](https://docs.openvino.ai/2026/documentation/compatibility-and-support/supported-models.html) page and consider falling back to CPU or GPU.

> **Note:** To bring down a running deployment before re-running with different options, run:
>
> ```bash
> source setup.sh --stop    # or, `source setup.sh --down`
> ```

#### Use GPU acceleration for VLM inference

   ```bash
   # for Summary mode
   VLM_TARGET_DEVICE=GPU source setup.sh --summary

   # for Dual UI mode
   VLM_TARGET_DEVICE=GPU source setup.sh --summary --search

   # for Unified UI mode
   VLM_TARGET_DEVICE=GPU source setup.sh --summary-and-search
   ```

#### Use GPU acceleration for the OVMS final-summary LLM

   ```bash
   # for Summary mode
   LLM_TARGET_DEVICE=GPU OVMS_LLM_MODEL_NAME=Qwen/Qwen3-4B-Instruct-2507 source setup.sh --summary

   # for Dual UI mode
   LLM_TARGET_DEVICE=GPU OVMS_LLM_MODEL_NAME=Qwen/Qwen3-4B-Instruct-2507 source setup.sh --summary --search

   # for Unified UI mode
   LLM_TARGET_DEVICE=GPU OVMS_LLM_MODEL_NAME=Qwen/Qwen3-4B-Instruct-2507 source setup.sh --summary-and-search
   ```

> **Note:** Search-indexing embedding runs in-process in `multimodal-dataprep` and follows `DATAPREP_EMBEDDING_DEVICE`. `MME_EMBEDDING_DEVICE` controls `multimodal-embedding-serving`, which `video-search` uses for query-time embeddings. `ENABLE_EMBEDDING_GPU=true` is a shortcut that sets `DATAPREP_EMBEDDING_DEVICE=GPU`.

To offload only specific DataPrep components during search (for example, keep embedding on CPU and move detection to GPU):

```bash
DATAPREP_EMBEDDING_DEVICE=CPU DATAPREP_DETECTION_DEVICE=GPU source setup.sh --search
```

To verify the configuration and resolved environment variables without running the application:

#### Use NPU acceleration for the final-summary LLM (split-model mode)

   ```bash
   # for Summary mode
   LLM_TARGET_DEVICE=NPU OVMS_LLM_MODEL_NAME=OpenVINO/Qwen3-8B-int4-cw-ov source setup.sh --summary

   # for Dual UI mode
   LLM_TARGET_DEVICE=NPU OVMS_LLM_MODEL_NAME=OpenVINO/Qwen3-8B-int4-cw-ov source setup.sh --summary --search

   # for Unified UI mode
   LLM_TARGET_DEVICE=NPU OVMS_LLM_MODEL_NAME=OpenVINO/Qwen3-8B-int4-cw-ov source setup.sh --summary-and-search
   ```

#### Use GPU acceleration for search-indexing embedding

   ```bash
   # for Search mode
   ENABLE_EMBEDDING_GPU=true source setup.sh --search

   # for Dual UI mode
   ENABLE_EMBEDDING_GPU=true source setup.sh --summary --search
   ```

   ```bash
   # to run the in-process embedding on NPU instead
   DATAPREP_EMBEDDING_DEVICE=NPU source setup.sh --search
   ```

#### Verify the configuration and resolved environment variables

   These commands help to validate the deployment configuration without actually deploying the application.

   ```bash
   # For VLM inference on GPU
   VLM_TARGET_DEVICE=GPU source setup.sh config --summary                             # for Summary mode
   VLM_TARGET_DEVICE=GPU source setup.sh config --summary --search                    # for Dual UI mode
   VLM_TARGET_DEVICE=GPU source setup.sh config --summary-and-search                  # for Unified UI mode
   ```

   ```bash
   # For LLM on NPU (split-model mode)
   LLM_TARGET_DEVICE=NPU OVMS_LLM_MODEL_NAME=OpenVINO/Qwen3-8B-int4-cw-ov source setup.sh config --summary                 # for Summary mode
   LLM_TARGET_DEVICE=NPU OVMS_LLM_MODEL_NAME=OpenVINO/Qwen3-8B-int4-cw-ov source setup.sh config --summary --search        # for Dual UI mode
   LLM_TARGET_DEVICE=NPU OVMS_LLM_MODEL_NAME=OpenVINO/Qwen3-8B-int4-cw-ov source setup.sh config --summary-and-search     # for Unified UI mode
   ```

   ```bash
   # For search-indexing embedding on GPU
   ENABLE_EMBEDDING_GPU=true source setup.sh config --search                  # for Search mode
   ENABLE_EMBEDDING_GPU=true source setup.sh config --search --summary        # for Dual UI mode

   # For search-indexing embedding on NPU
   DATAPREP_EMBEDDING_DEVICE=NPU source setup.sh config --search
   ```

   ```bash
   # For component-specific offload in DataPrep
   DATAPREP_EMBEDDING_DEVICE=CPU DATAPREP_DETECTION_DEVICE=GPU source setup.sh --search config
   ```

> **Tip:** `VLM_TARGET_DEVICE` and `LLM_TARGET_DEVICE` support values: `CPU` (default), `GPU`, `NPU`, or `HETERO:GPU,CPU` for heterogeneous execution with fallback.

> **Note:** Avoid setting the `ENABLE_VLM_GPU`, `ENABLE_OVMS_LLM_SUMMARY_GPU`, or `ENABLE_EMBEDDING_GPU` flags explicitly on the shell using `export`, because you need to switch these flags off as well, to return to the CPU configuration.

## Access the Application

After successfully starting the application, access the application UI on following URLs based on chosen mode:

### `--summary` mode

| UI | URL |
|----|-----|
| Video Summarization | `http://<host-ip>:12345/` |

### `--search` mode

| UI | URL |
|----|-----|
| Video Search | `http://<host-ip>:12345/` |

### `--summary --search` mode

| UI | URL |
|----|-----|
| Video Summarization | `http://<host-ip>:12345/summary/`
| Video Search       | `http://<host-ip>:12345/search/` |

Visiting the root URL `http://<host-ip>:12345/` redirects to the Video Summarization UI.

### `--summary-and-search` mode

| UI | URL |
|----|-----|
| Unified Summary/Search | `http://<host-ip>:12345/` |

### Customizing Application Port

- The port where we access the application is customizable by setting the `APP_HOST_PORT` environment variable (default `12345`).

## Monitoring OVMS Metrics

When running in summary mode with OVMS, Prometheus-compatible metrics are available at `http://<host-ip>:12345/ovms/metrics`. These metrics provide insights into inference performance:

```bash
curl http://localhost:12345/ovms/metrics
```

Key metrics include `ovms_requests_success`, `ovms_inference_time_us`, and `ovms_current_requests`. See [Deploy with Helm - Monitoring and Metrics](./deploy-with-helm.md#monitoring-and-metrics) for the full metrics list.

## CLI Usage

Refer to [CLI Usage](https://github.com/open-edge-platform/edge-ai-libraries/blob/release-2026.2.0/sample-applications/video-search-and-summarization/cli/README.md) for details on using the application from a text user interface (terminal-based UI).

## Running in Kubernetes Cluster

Refer to [Deploy with Helm](./deploy-with-helm.md) for the details. Ensure the prerequisites mentioned on this page are addressed before proceeding to deploy with Helm chart.

## Advanced Setup Options

For alternative ways to set up the sample application, see [How to Build from Source](./build-from-source.md)

## Supporting Resources

- [How it works](./how-it-works.md)
- [Troubleshooting](./troubleshooting.md)
- [Docker Compose Documentation](https://docs.docker.com/compose/)

## Connect AI Agents via MCP

Once VSS is running, you can connect AI agents to it using the included MCP server. The MCP server exposes VSS capabilities as typed tools and read-only resources for any MCP-compatible client.

See the [MCP Server guide](./mcp-server.md) for setup instructions.


:::{toctree}
:hidden:

get-started/system-requirements

:::