# Get Started Guide

- **Time to Complete:** 10 mins
- **Programming Language:** Python

## Get Started

### Prerequisites

- Install Docker: [Installation Guide](https://docs.docker.com/get-docker/).
- Install Docker Compose: [Installation Guide](https://docs.docker.com/compose/install/).
- Install Intel Client GPU driver: [Installation Guide](https://dgpu-docs.intel.com/driver/client/overview.html).

### Step 1: Get the docker images

#### Option 1: build from source

Clone the source code repository if you do not have it:

```bash
git clone https://github.com/open-edge-platform/edge-ai-libraries.git -b release-2026.2.0
cd edge-ai-libraries/microservices
```

Run the command to build images:

```bash
docker build -t dataprep-visualdata-milvus:latest --build-arg https_proxy=$https_proxy --build-arg http_proxy=$http_proxy --build-arg no_proxy=$no_proxy -f visual-data-preparation-for-retrieval/milvus/src/Dockerfile .

# build the dependency image
cd multimodal-embedding-serving
docker build -t multimodal-embedding-serving:latest --build-arg https_proxy=$https_proxy --build-arg http_proxy=$http_proxy --build-arg no_proxy=$no_proxy -f docker/Dockerfile .
```

#### Option 2: use remote prebuilt images

Set a remote registry by exporting environment variables:

```bash
export REGISTRY="intel/"
export TAG="2025.2.0"
```

> **Note:** If you are using a release version package, you will have a pre-defined docker compose file where image registry and tag are already set to the release version. In such case, you do not need to set the environment variables above, simply move forward to the next step. You may refer to the release notes for details on the version number or check the docker compose file that is used in the steps below.

### Step 2: Prepare host directories for data

```
mkdir -p $HOME/data
```

Make sure to put all your data (images and video) in the created data directory (`$HOME/data` in the example commands) BEFORE deploying the service.

Additionally, make sure the created path matches with the `HOST_DATA_PATH` variable in `deployment/docker-compose/env.sh`.

> **Note:** The supported media types are: jpg, png, mp4.

### Step 3: Deploy

#### Deploy the application together with the Milvus Server

1. Go to the deployment files

   ```bash
   cd visual-data-preparation-for-retrieval/milvus/deployment/docker-compose/
   ```

2. Set up environment variables, note that you need to set an embedding model first for Multimodal Embedding Serving

   ```bash
   export EMBEDDING_MODEL_NAME="CLIP/clip-vit-h-14" # Replace with your preferred model
   source env.sh
   ```

   > **Important:** You must set `EMBEDDING_MODEL_NAME` before running `env.sh`.
   > See [Supported Models](https://docs.openedgeplatform.intel.com/2026.2/edge-ai-libraries/multimodal-embedding-serving/supported-models.html) for Multimodal Embedding Serving for available options.

   > **Note:** `env.sh` sets `HF_ENDPOINT` to a Hugging Face mirror, which is necessary for users in the PRC to download models. Users in other regions may remove or unset this variable to use the default Hugging Face endpoint:
   >
   > ```bash
   > unset HF_ENDPOINT
   > ```

   <details>
   <summary>For EMT-S platform</summary>
   If you are on an EMT-S platform, please set up the variables correspondingly by running

   ```bash
   cd emt-s   # go to emt-s specific files
   export EMBEDDING_MODEL_NAME="CLIP/clip-vit-h-14" # Replace with your preferred model
   source env.sh
   ```

   </details>

3. Deploy with docker compose

   ```bash
   docker compose -f compose_milvus.yaml up -d
   ```

It might take some time to start the services for the first time, as the service prepares the models.

Check if all microservices are up and running:

```bash
docker compose -f compose_milvus.yaml ps
```

Example expected output:

```text
NAME                         COMMAND                  SERVICE                                 STATUS              PORTS
dataprep-visualdata-milvus   "uvicorn dataprep_vi…"   dataprep-visualdata-milvus              running (healthy)   0.0.0.0:9990->9990/tcp, :::9990->9990/tcp
milvus-etcd                  "etcd -advertise-cli…"   milvus-etcd                             running (healthy)   2379-2380/tcp
milvus-minio                 "/usr/bin/docker-ent…"   milvus-minio                            running (healthy)   0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp
milvus-standalone            "/tini -- milvus run…"   milvus-standalone                       running (healthy)   0.0.0.0:9091->9091/tcp, 0.0.0.0:19530->19530/tcp, :::9091->9091/tcp, :::19530->19530/tcp
multimodal-embedding   gunicorn -b 0.0.0.0:8000 - ...   Up (health: starting)   0.0.0.0:9777->8000/tcp,:::9777->8000/tcp
```

## Sample curl commands

### Info

```bash
curl -X GET http://localhost:$DATAPREP_SERVICE_PORT/v1/dataprep/info
```

### Ingest Files

> **Note:** the file directory or single file sent in the request should be under the specific host directory created in Step 2.

- For Directory:

  ```bash
  curl -X POST http://localhost:$DATAPREP_SERVICE_PORT/v1/dataprep/ingest \
  -H "Content-Type: application/json" \
  -d '{
      "file_dir": "/path/to/directory",
      "frame_extract_interval": 15,
      "do_detect_and_crop": true
  }'
  ```

- For Single File:

  ```bash
  curl -X POST http://localhost:$DATAPREP_SERVICE_PORT/v1/dataprep/ingest \
  -H "Content-Type: application/json" \
  -d '{
      "file_path": "/path/to/file",
      "meta": {
          "key": "value"
      },
      "frame_extract_interval": 15,
      "do_detect_and_crop": true
  }'
  ```

### Get File Info

```bash
curl -X GET http://localhost:$DATAPREP_SERVICE_PORT/v1/dataprep/get?file_path=/path/to/file
```

### Delete File in Database

```bash
curl -X DELETE http://localhost:$DATAPREP_SERVICE_PORT/v1/dataprep/delete?file_path=/path/to/file
```

### Clear Database

```bash
curl -X DELETE http://localhost:$DATAPREP_SERVICE_PORT/v1/dataprep/delete_all
```

## Troubleshooting

### Network failure when downloading models

If service startup fails with errors that look like a network failure while downloading models from Hugging Face, the configured `HF_ENDPOINT` mirror may be unreachable from your network. Try unsetting it before redeploying:

```bash
unset HF_ENDPOINT
docker compose -f compose_milvus.yaml down
docker compose -f compose_milvus.yaml up -d
```

This falls back to the default Hugging Face endpoint, which is typically the right choice for users outside the PRC.

## Learn More

- Check the [API reference](./api-reference.md)
- The visual data preparation microservice usually pairs with a retriever microservice. For more information, check the retriever's [Get Started guide](https://docs.openedgeplatform.intel.com/2026.2/edge-ai-libraries/vector-retriever-milvus/get-started.html)
- This microservice depends on the [Multimodal Embedding Service](https://docs.openedgeplatform.intel.com/2026.2/edge-ai-libraries/multimodal-embedding-serving/get-started.html) for embedding extraction.


:::{toctree}
:hidden:

./get-started/system-requirements.md

:::