# Configuration The Behavioral Analysis Service is configured through two complementary mechanisms: 1. Environment variables (loaded through `Settings` in `src/config.py`) 2. `config/patterns.yaml` (pattern logic and VLM settings) ## Deployment Mode The service supports two deployment modes controlled by `DEPLOYMENT_MODE`. | Variable | Default | Supported values | | --- | --- | --- | | `DEPLOYMENT_MODE` | `standalone+api` | `seaweedfs+mqtt`, `standalone+api` | Mode behavior: | Mode | SeaweedFS | MQTT consumer | Primary request path | Typical use | | --- | --- | --- | --- | --- | | `seaweedfs+mqtt` | Enabled | Enabled | MQTT topic `ba/requests` | Async production-style pipeline | | `standalone+api` | Disabled | Disabled | `POST /api/v1/analyze/batch` | Direct API integration and testing | The default mode in the project `.env` file is `standalone+api`. Mode-specific requirements: - `seaweedfs+mqtt` mode: - Configure SeaweedFS and MQTT variables. - Use queue-based processing (`ba/requests` -> `ba/results`). - `standalone+api` mode: - SeaweedFS and MQTT are not required for runtime analysis. - In Docker Compose, OVMS (`ovms-vlm`) starts by default and is used for VLM confirmation when enabled. - Download and place VLM model files before startup under `DOWNLOADED_MODEL_PATH/vlm_models`. - Use the REST batch endpoint `POST /api/v1/analyze/batch`. ## Environment Variables All variables are case-insensitive. ### Service Settings | Variable | Default | Description | | --- | --- | --- | | DEBUG | false | Enable debug mode | | LOG_LEVEL | INFO | Logging level: DEBUG, INFO, WARNING, ERROR | | DEPLOYMENT_MODE | standalone+api | Deployment mode switch | ### Pose Model and Inference | Variable | Default | Description | | --- | --- | --- | | YOLO_POSE_MODEL | /models/yolo_models/yolo26n-pose/yolo26n-pose.xml | Path to YOLO-Pose OpenVINO™ IR model (.xml) | | BA_GST_DEVICE | CPU | OpenVINO™ inference device: CPU, GPU. See the accelerator mapping requirement below. | | BA_CONFIDENCE | 0.5 | Minimum keypoint confidence threshold | Download YOLO26n-pose model: Run this before `docker compose up` when using `standalone+api` mode. This script also downloads the default VLM model (`Qwen/Qwen2.5-VL-7B-Instruct`) and creates the OVMS config required for VLM serving. ```bash cd download-model ./download_yolo_pose.sh ``` Expected output files: - `models/yolo_models/yolo26n-pose/yolo26n-pose.xml` - `models/yolo_models/yolo26n-pose/yolo26n-pose.bin` - `models/vlm_models/config.json` - `models/vlm_models/Qwen/Qwen2.5-VL-7B-Instruct/` (OpenVINO™ IR model files) The host must expose accelerator devices to Docker, and the relevant device entries must be mapped into the `behavioral-analysis` service, because that container performs the YOLO-Pose OpenVINO™ inference. For example, `/dev/dri:/dev/dri` (GPU) or `/dev/accel:/dev/accel` (NPU). > [!NOTE] > If `BA_GST_DEVICE` is set to `GPU` or `NPU`, the corresponding accelerator device must be added to the > `behavioral-analysis` service's `devices:` section. Do this using a Docker Compose override > file instead of editing the tracked `docker-compose.yml` directly, so local device mappings > survive project updates without merge conflicts. GPU setup with `docker-compose.override.yml`: 1. Set `BA_GST_DEVICE=GPU` in `.env`. 2. Copy the GPU template: `cp docker-compose.override.yml.gpu-example docker-compose.override.yml` 3. Start with [Run with Docker Compose](run-container.md). The template (`docker-compose.override.yml.gpu-example`) contains: ```yaml services: behavioral-analysis: devices: - /dev/dri:/dev/dri group_add: - ${RENDERER_GROUP:-992} ``` NPU setup with `docker-compose.override.yml`: 1. Set `BA_GST_DEVICE=NPU` in `.env`. 2. Copy the NPU template: `cp docker-compose.override.yml.npu-example docker-compose.override.yml` 3. Start with [Run with Docker Compose](run-container.md). The template (`docker-compose.override.yml.npu-example`) contains: ```yaml services: behavioral-analysis: devices: - /dev/accel:/dev/accel group_add: - ${RENDER_GROUP_ID:-992} ``` > [!CAUTION] > Only one `docker-compose.override.yml` can be active at a time. If switching > between GPU and NPU, replace the override file with the appropriate template. ### Frame Analysis | Variable | Default in Settings | .env default (project) | Description | | --- | --- | --- | --- | | BA_MIN_FRAMES | 3 | 3 | Minimum frame threshold for v1 accumulation flow | | BA_MAX_FRAMES | 20 | 30 | Maximum frames fetched in SeaweedFS flow | | BA_POSE_FRAMES | 15 | 20 | Fallback/global frame count used in pose scoring | ### SeaweedFS (required only for seaweedfs+mqtt) | Variable | Default | Description | | --- | --- | --- | | SEAWEEDFS_ENDPOINT | | SeaweedFS S3 endpoint | | SEAWEEDFS_BUCKET | behavioral-frames | Bucket name for frames | | SEAWEEDFS_ACCESS_KEY | (empty) | S3 access key | | SEAWEEDFS_SECRET_KEY | (empty) | S3 secret key | ### MQTT (required only for seaweedfs+mqtt) | Variable | Default | Description | | --- | --- | --- | | MQTT_HOST | broker.scenescape.intel.com | MQTT broker host | | MQTT_PORT | 1883 | MQTT broker port | | BA_REQUEST_TOPIC | ba/requests | Incoming request topic | | BA_RESULT_TOPIC | ba/results | Outgoing result topic | ### VLM The global VLM switch is controlled exclusively by the environment variable `VLM_ENABLED`. The YAML `vlm_settings` block is used only for connection/model settings and does not control the global enable/disable state. > [!IMPORTANT] > VLM is disabled by default. Enable it explicitly when the environment is configured for VLM confirmation. Ensure model artifacts are downloaded before launch. In Docker Compose, `ovms-vlm` mounts models from `${DOWNLOADED_MODEL_PATH}/vlm_models` and expects the model configuration to be available there. In Docker Compose, `ovms-vlm` is defined under the `vlm` profile and its `depends_on` from `behavioral-analysis` is optional (`required: false`). This means `ovms-vlm` only starts when the `vlm` profile is active. When `VLM_ENABLED=true`, activate the profile with `docker compose --profile vlm up -d` (or set `COMPOSE_PROFILES=vlm` in your env file); otherwise `ovms-vlm` never starts and VLM confirmation will not work even though the flag is enabled. | Variable | Default | Description | | --- | --- | --- | | VLM_ENABLED | false | Global master switch for VLM confirmation after pose match | | VLM_ENDPOINT | | OpenAI-compatible endpoint | | VLM_MODEL_NAME | Qwen/Qwen2.5-VL-7B-Instruct | Model name for VLM request | | VLM_TIMEOUT | 300.0 | Request timeout in seconds | | VLM_MAX_TOKENS | 50 | Maximum tokens in VLM response | | VLM_TEMPERATURE | 0.1 | Sampling temperature | | VLM_MAX_IMAGE_SIZE | 256 | Maximum frame size for VLM | | VLM_MAX_CONCURRENCY | 1 | Maximum concurrent VLM requests | ### Pattern Config Path | Variable | Default | Description | | --- | --- | --- | | PATTERN_CONFIG_PATH | /app/config/patterns.yaml | Path to pattern config file | ## .env File (Docker Compose) The project `.env` file controls Docker Compose substitution defaults. See the full [environment file](https://github.com/open-edge-platform/edge-ai-libraries/blob/release-2026.3.0/microservices/behavioral-analysis/.env) for more details. ## Pattern Configuration (config/patterns.yaml) Behavioral patterns are defined in YAML and loaded from `PATTERN_CONFIG_PATH`. ### VLM Settings Block ```yaml vlm_settings: endpoint: "http://ovms-vlm:8001" model_name: "Qwen/Qwen2.5-VL-7B-Instruct" timeout: 30.0 max_tokens: 50 temperature: 0.1 max_image_size: 256 max_concurrency: 1 ``` ### Pattern Definition Structure ```yaml patterns: : description: "Human-readable description" enabled: true | false alert_type: pose: per_side: true | false min_pose_confidence: 0.3 min_confidence_for_alert: 0.30 phases: - name: min_frames: conditions: - subject: relation: reference: | | vlm: enabled: true | false num_frames: 4 confidence_threshold: 0.7 prompt: | response_fields: - reasoning - suspicious - confidence ``` ### Available Keypoint Names (COCO 17) nose, left_eye, right_eye, left_ear, right_ear, left_shoulder, right_shoulder, left_elbow, right_elbow, left_wrist, right_wrist, left_hip, right_hip, left_knee, right_knee, left_ankle, right_ankle Virtual reference points: waist_midpoint, chest_midpoint, torso_center, head_center Short names (when `per_side=true`): wrist, elbow, shoulder, hip, knee, ankle, eye, ear ## Volume Mount for Config To customize patterns without rebuilding, mount configuration into `/app/config`. Docker run example: ```bash docker run ... -v ./config:/app/config:ro intel/behavioral-analysis:latest ``` Docker Compose already includes this mount in the project configuration.