| name | multimodal-dataprep-user |
| description | Deploy and consume Intel Multimodal DataPrep from prebuilt images or a repository checkout. Use for configuring VDMS or Milvus vector storage, MinIO or local media storage, checking service dependencies, and ingesting, listing, streaming, or deleting videos and images; submitting batch jobs; adding text-summary embeddings; and inspecting telemetry. This service prepares retrieval data but does not execute semantic search. Use multimodal-dataprep-dev for source changes, tests, or image builds.
|
Multimodal DataPrep — User
Run deployment and API commands when authorized, then report their actual
output. API base: http://localhost:6007/v1/dataprep.
Multimodal DataPrep creates embeddings and metadata for retrieval. It does not
offer a vector-query/search endpoint.
Load project resources as needed
Paths are relative to
microservices/visual-data-preparation-for-retrieval/multimodal-dataprep/.
| Resource | Read when |
|---|
docs/user-guide/api-reference.md and docs/user-guide/api-docs/openapi.yaml | Constructing media, image, batch, summary, download, delete, or telemetry requests |
docs/user-guide/get-started.md | Configuring devices, detection, batching, duplicate policy, or environment variables |
docs/user-guide/pluggable-backends.md | Selecting VDMS/Milvus or MinIO/local and diagnosing backend behavior |
docs/user-guide/telemetry-metrics.md | Reading ingestion telemetry or configuring Metrics Manager |
setup.sh and docker/compose*.yaml | Deploying a stack |
Example scenarios:
1. Select deployment backends
| Vector backend | Media storage | Compose files |
|---|
| VDMS (default) | MinIO (default) | docker/compose.yaml |
| Milvus | MinIO | docker/compose-milvus.yaml |
| VDMS | Local filesystem | docker/compose.yaml then docker/compose.storage-local.yaml |
Use MM_DATAPREP_VECTORDB_BACKEND (vdms or milvus) and
MM_DATAPREP_STORAGE_BACKEND (minio or local) for custom deployments.
Keep the service, retriever, and collection naming consistent.
2. Obtain deployment files
In a repository checkout, run from the microservice root.
Without a checkout, fetch the setup script and the compose file(s) for the
selected backend:
RAW='https://raw.githubusercontent.com/open-edge-platform/edge-ai-libraries/main/microservices/visual-data-preparation-for-retrieval/multimodal-dataprep'
mkdir -p multimodal-dataprep/docker
cd multimodal-dataprep
curl -fsSLo setup.sh "$RAW/setup.sh"
curl -fsSLo docker/compose.yaml "$RAW/docker/compose.yaml"
Also fetch docker/compose-milvus.yaml or
docker/compose.storage-local.yaml when selected.
3. Start the prebuilt stack
Never commit credentials. For the default VDMS + MinIO deployment:
export MINIO_ROOT_USER='<user>'
export MINIO_ROOT_PASSWORD='<strong-password>'
export EMBEDDING_MODEL_NAME='CLIP/clip-vit-b-32'
export REGISTRY_URL='docker.io/intel'
export TAG='latest'
source ./setup.sh --nosetup
docker compose -f docker/compose.yaml up -d --no-build
For Milvus, replace the compose file with docker/compose-milvus.yaml. For
local media storage, layer the storage override after docker/compose.yaml.
setup.sh must be sourced because it exports Compose variables. With no
argument it only exports defaults; it does not start containers.
4. Verify readiness and dependencies
Wait for the in-process embedding client:
until curl -fsS http://localhost:6007/v1/dataprep/health \
| python3 -c 'import json,sys; d=json.load(sys.stdin); raise SystemExit(0 if d.get("status") == "ok" and d.get("embedding_client_status") == "preloaded" else 1)'
do
sleep 10
done
The current fields are embedding_client_status, model_name,
embedding_device, use_openvino, detection_model, and
detection_device.
Check dependencies separately:
docker compose -f docker/compose.yaml ps
curl -fsS http://localhost:6010/minio/health/live
timeout 2 bash -c '</dev/tcp/localhost/6020'
For Milvus, use the Milvus compose file and probe localhost:19530. DataPrep's
health response is not a substitute for checking every dependency.
5. Ingest supported media
Upload a video:
curl -fsS -X POST \
'http://localhost:6007/v1/dataprep/media/upload?frame_interval=15&enable_object_detection=true&tags=camera-1' \
-F 'file=@/path/to/video.mp4;type=video/mp4'
Upload an image through the same multipart endpoint:
curl -fsS -X POST \
'http://localhost:6007/v1/dataprep/media/upload?enable_object_detection=true&tags=inspection' \
-F 'file=@/path/to/image.jpg;type=image/jpeg'
For inline base64 or remote HTTP(S) images, use POST /media/ingest. For media
already in the selected storage backend, use POST /media/process.
Asynchronous workflows:
POST /media/upload/batchPOST /media/process/batchPOST /media/ingest/batchPOST /media/ingest-dir (also store_copy: false to embed files in place
without copying them into storage — such media is still listed by GET /media
with "stored": false and streamable via GET /media/download — and
metadata / meta/<basename>.json sidecars for user-defined filterable
fields)GET /media/jobs/{job_id}DELETE /media/jobs/{job_id} to request cancellation
Clean-up: DELETE /media/{bucket_name}/{video_id} removes one item,
DELETE /media/{bucket_name} clears a whole bucket (storage + embeddings).
Read the API reference for exact request schemas and configured batch limits.
6. Add a text summary
Use the video_id returned by media listing/job results and its bucket:
curl -fsS -X POST 'http://localhost:6007/v1/dataprep/summary' \
-H 'Content-Type: application/json' \
-d '{
"bucket_name": "video-summary",
"video_id": "dp_video_1730000000",
"video_summary": "forklift narrowly misses pedestrian",
"video_start_time": 33,
"video_end_time": 41,
"tags": ["safety"]
}'
The selected model must support text embeddings.
7. Manage and observe
curl -fsS 'http://localhost:6007/v1/dataprep/media'
curl -fsS 'http://localhost:6007/v1/dataprep/telemetry?limit=5'
curl -L 'http://localhost:6007/v1/dataprep/media/download?video_id=dp_video_1730000000' \
-o media.bin
GET /media/download supports HTTP Range requests for seeking.
Deletion removes the entire media directory and its matching vectors:
curl -fsS -X DELETE \
'http://localhost:6007/v1/dataprep/media/video-summary/dp_video_1730000000'
There is no current single-file video_name deletion option. Deletion is
destructive, so obtain explicit confirmation before running it.
Set MM_DATAPREP_METRICS_MANAGER_URL to publish completed-pipeline
dataprep_embeddings_per_second values asynchronously. /telemetry remains
the direct source for detailed per-ingestion stage timings.
Troubleshooting
| Symptom | Action |
|---|
| API is unavailable | Inspect docker compose ... ps and DataPrep logs; initial model/YOLOX downloads can take time |
embedding_client_status is not_loaded or error | Verify EMBEDDING_MODEL_NAME, model compatibility, device access, and startup logs |
| Dimension mismatch | Use a fresh collection compatible with the selected model; never wipe an existing collection without confirmation |
| Milvus connection failure behind a proxy | Use docker/compose-milvus.yaml and ensure Milvus/etcd/in-cluster addresses bypass proxies |
| MinIO authentication failure | Verify the effective MM_DATAPREP_MINIO_* values and reuse the same credentials across restarts |
| Large upload returns 413 | Identify the rejecting proxy/server from headers and logs; stage media in storage and call /media/process |
| Duplicate upload returns 409 | MM_DATAPREP_ALLOW_DUPLICATE_UPLOADS=false is enforcing content-hash deduplication |
| Object crops are absent | Check whether YOLOX downloaded and whether detection is enabled on a supported device |
| Local directory ingest is rejected | Keep dir_path beneath MM_DATAPREP_INGEST_DATA_ROOT; traversal outside that root is intentionally blocked |
