Workers Deployment

Inference workers run the BirdNET model to identify bird species from audio chunks submitted by satellites.

What Workers Do

• BirdNET inference — classify 3-second audio chunks using TFLite and birdnetlib
• Enhanced re-processing — extended window analysis, frequency isolation, and cross-chunk correlation for improved accuracy
• Workers are stateless — they pull jobs from Redis (BullMQ), fetch audio from MinIO, run inference, and write results to PostgreSQL

Docker Deployment (Default)

The default deployment runs workers alongside the hub via Docker Compose. This is the simplest setup and requires no extra configuration.

Workers are included in the standard docker-compose.yml stack. To scale:

# Run 4 inference workers
docker compose up --scale worker=4 -d

Workers are stateless — add as many as needed for your detection volume. Each worker connects to the shared Redis, MinIO, and PostgreSQL services within the Docker network.

Standalone Linux Deployment

Workers can run on a separate machine (or multiple machines) outside Docker, connecting to the hub's Redis, MinIO, and PostgreSQL over the network. This is useful for distributing inference load across hardware.

Requirements

• Python 3.11
• pip
• Network access to the hub's Redis, MinIO, and PostgreSQL

Setup

# Clone the repository (replace with your Git server URL)
git clone <your-git-server>/birdnet-ng.git
cd birdnet-ng/packages/inference

python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configuration

Create a .env file or export environment variables:

The inference worker uses pydantic-settings for configuration, so environment variables and .env files are both supported.

Run

source venv/bin/activate
python -m inference

For production, set up a systemd service:

sudo tee /etc/systemd/system/birdnet-worker.service << 'EOF'
[Unit]
Description=BirdNET-NG Inference Worker
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=birdnet
WorkingDirectory=/opt/birdnet-ng/packages/inference
EnvironmentFile=/opt/birdnet-ng/packages/inference/.env
ExecStart=/opt/birdnet-ng/packages/inference/venv/bin/python -m inference
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now birdnet-worker

Windows Deployment

::: warning Coming Soon Windows standalone worker deployment is planned but not yet documented. The inference package requires Python 3.11 and numpy<2. Contributions welcome. :::

macOS Deployment

::: warning Coming Soon macOS standalone worker deployment is planned but not yet documented. The inference package requires Python 3.11 and numpy<2. Contributions welcome. :::

GPU Acceleration

By default, workers use CPU inference via TFLite. For higher throughput, GPU acceleration can be enabled:

CUDA (NVIDIA GPUs)

Install the TFLite GPU delegate or use the full TensorFlow package with CUDA support. This requires:

• NVIDIA GPU with CUDA support
• CUDA toolkit and cuDNN installed
• tflite-runtime replaced with GPU-enabled build, or full tensorflow package

TFLite GPU Delegate

The TFLite GPU delegate can offload inference to the GPU with minimal configuration changes. Refer to the TFLite GPU delegate documentation for setup instructions.

Scaling

• Docker: docker compose up --scale worker=N -d — each worker is an independent container
• Standalone: run multiple worker processes on the same or different machines, all pointing at the same Redis queue
• Workers automatically distribute jobs via BullMQ's built-in concurrency — no manual partitioning needed