Quick Start#

In this the microservice can be run as an ephemeral (one-shot) container that downloads or converts a model and exits automatically. This is useful for CI/CD pipelines, pre-provisioning model caches, or scripted workflows.

Prerequisites#

Docker installed and running. Installation guide here
curl and python3 available on the host

One-liner Setup#

Download and run directly — no repo clone needed. The script starts a temporary Docker container, downloads the model to your local disk, and automatically removes the container once the operation completes.

curl -sSLO https://raw.githubusercontent.com/open-edge-platform/edge-ai-libraries/main/microservices/model-download/scripts/get_model.sh && source ./get_model.sh --model-name sentence-transformers/all-MiniLM-L6-v2 --hub huggingface --plugins huggingface

Quick Examples#

Download a HuggingFace model#

. ./get_model.sh \
  --model-name sentence-transformers/all-MiniLM-L6-v2 \
  --hub huggingface --plugins huggingface

Download and convert to OpenVINO (OVMS-ready)#

. ./get_model.sh \
  --model-name meta-llama/Llama-3.2-1B \
  --hub openvino \
  --type llm \
  --is-ovms \
  --precision int8 \
  --device CPU \
  --plugins huggingface,openvino

Download an Ollama model#

. ./get_model.sh \
  --model-name llama3.2 \
  --hub ollama \
  --plugins ollama

Download an Ultralytics model#

. ./get_model.sh \
  --model-name yolov8s \
  --hub ultralytics \
  --plugins ultralytics

Advanced Options#

Model Parameters#

Argument	Description	Required
`--model-name <name>`	Model identifier (e.g. `meta-llama/Llama-3.2-1B`)	Yes
`--hub <hub>`	Source hub: `huggingface`, `ultralytics`, `ollama`, `openvino`, `geti`, `hls`	Yes
`--type <type>`	Model type: `llm`, `vlm`, `embeddings`, `rerank`, `vision`, `3d-pose`, `rppg`, `ai-ecg`	No
`--revision <rev>`	Branch, tag, or commit hash	No
`--is-ovms`	Convert to OpenVINO format after downloading	No
`--precision <prec>`	Weight precision: `int4`, `int8`, `fp16`, `fp32` (default: `int8`)	No
`--device <dev>`	Target device: `CPU`, `GPU`, `NPU` (default: `CPU`)	No
`--cache-size <gb>`	KV cache size in GB (for LLM/VLM conversion)	No
`--download-path <path>`	Sub-directory under models dir for downloads	No

Docker Options#

Argument	Description	Default
`--model-path <path>`	Host path for model storage	`./models`
`--image-tag <tag>`	Docker image tag	`latest`
`--plugins <list>`	Comma-separated plugins to enable	`all`
`--ovms-release-tag <tag>`	OVMS release tag	`v2025.4.1`

Environment Variables#

Variable	Purpose
`HF_TOKEN` or `HUGGINGFACEHUB_API_TOKEN`	HuggingFace authentication for gated models
`GETI_HOST`	Geti server hostname
`GETI_TOKEN`	Geti authentication token
`GETI_WORKSPACE_ID`	Geti workspace ID

Troubleshooting#

On failure, the script creates an error log at:

.model_download_logs/model_download_YYYYMMDD_HHMMSS.log

The log path is printed at the end of a failed run.

Reading the error log#

The log file contains structured sections:

===== Model Download Ephemeral Mode - Error Log =====
Timestamp: 2026-05-22T12:46:17+05:30
Command: source ./get_model.sh --model-name ... --hub ...
Image: model-download:latest
Model Path: /home/user/models
Plugins: huggingface,openvino

[2026-05-22T12:46:44+05:30] ERROR: Job xxx failed: <error message>

===== Job Failure: <job-id> =====
{ full JSON response from API }

===== Container Logs =====
<last 100 lines of container output>

Common issues#

Plugin not activated

Plugin 'openvino' was not activated during container startup. Active plugins: huggingface

Fix: Add the required plugin to --plugins (e.g., --plugins huggingface,openvino).

Gated model access denied

Access to Gated or private models is restricted. You must be authenticated.

Fix: Set HF_TOKEN with a token that has access to the model:

export HF_TOKEN="hf_..."
source ./get_model.sh --model-name meta-llama/Llama-2-7b-hf --hub huggingface

Container failed to start

ERROR: Failed to get mapped port for container.

Fix: Check that the Docker image exists (docker images | grep model-download) and rebuild if needed.

Service health timeout

ERROR: Service failed to start within 180s.

Fix: Check the container logs in the error log file. Common causes: missing dependencies, network issues during plugin setup.

Cleanup stale containers#

If the script was interrupted, you may need to remove the leftover container:

docker rm -f model-download-ephemeral