Run Standalone#

Running the service outside Docker requires Python 3.12, OpenVINO Runtime, and all Python dependencies installed locally. This mode is primarily useful for development and testing.

Note: The container image (intel/dlstreamer:2026.1.0-ubuntu24) provides OpenVINO and GStreamer pre-installed. Replicating this environment locally requires manual OpenVINO installation.

Prerequisites#

  • Python 3.12

  • OpenVINO Runtime (matching the version in intel/dlstreamer:2026.1.0-ubuntu24)

  • Git (required for the git+https:// dependency in requirements.txt)

  • Running instances of SeaweedFS, MQTT broker, and OVMS (if VLM is enabled)

  • YOLO-Pose model files (.xml + .bin) accessible at a local path

1. Install Dependencies#

# From the behavioral-analysis/ directory
python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

2. Configure the Environment#

Use a local environment file and source it in your shell:

cp .env .env.local
# Edit .env.local with your deployment-specific values
set -a
source .env.local
set +a

See Configuration for the full list of required variables.

3. Start the Service#

# From the behavioral-analysis/ directory
source .venv/bin/activate
PYTHONPATH=src python3 -m uvicorn main:app --host 0.0.0.0 --port 8080

The service starts on port 8080 by default. To use a different port:

PYTHONPATH=src python3 -m uvicorn main:app --host 0.0.0.0 --port 8085

To enable auto-reload during development:

PYTHONPATH=src python3 -m uvicorn main:app --host 0.0.0.0 --port 8080 --reload

4. Verify the Service#

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy",
  "model_loaded": true,
  "seaweedfs_connected": true
}

Runtime Arguments#

Uvicorn arguments relevant to this service:

Argument

Description

Example

--host

Bind address

0.0.0.0

--port

Listen port

8080

--reload

Auto-reload on code changes (dev only)

—

--workers

Number of worker processes (not recommended because the service has a singleton YOLO model)

1

--log-level

Uvicorn log level

info, debug

Logs#

Logs are written to standard output. Redirect to a file:

PYTHONPATH=src python3 -m uvicorn main:app --host 0.0.0.0 --port 8080 > app.log 2>&1 &

Shutdown#

Send SIGTERM or press Ctrl+C. The service performs a graceful shutdown:

  1. MQTT consumer awaits all in-flight analyses.

  2. VLM HTTP client connection pool is closed.

# If running in background
kill -TERM <uvicorn-pid>

Troubleshooting#

ModuleNotFoundError: No module named 'openvino'#

Install OpenVINO Runtime for Python:

pip install openvino

ModuleNotFoundError: No module named 'gstgva'#

gstgva is provided by the DL Streamer base image and is not available in standalone Python environments. The service’s YOLOPoseOV wrapper does not require it; this error only appears if an import path includes the GStreamer extension.

SeaweedFS or MQTT connection errors at startup#

Ensure the external services are running and the environment variables point to the correct host/port. See Troubleshooting for details.