Skip to content

README.md

Latest commit

 

History

History
89 lines (63 loc) · 5.19 KB

README.md

File metadata and controls

89 lines (63 loc) · 5.19 KB
Raw

OrcaHello SRKW Inference System

Southern Resident Killer Whale call detection model and live inference orchestrator (together called the "Inference System").

Quick Start: Standalone SRKW Detector Model

Model on HuggingFace: orcasound/orcahello-srkw-detector-v1

Prerequisites:

cd InferenceSystem
uv sync
from src.model import OrcaHelloSRKWDetectorV1

model = OrcaHelloSRKWDetectorV1.from_pretrained("orcasound/orcahello-srkw-detector-v1")
result = model.detect_srkw_from_file("audio.wav")

print(f"Orca detected: {result.global_prediction}")
print(f"Confidence: {result.global_confidence:.2f}")

For more details see MODEL_CARD.md for usage, and DEVELOPMENT.md for development & convenience scripts.

Quick Start: Live Inference Orchestrator

The inference orchestrator streams audio from Orcasound's S3 buckets, runs AI inference on audio segments, and uploads positive detections to the OrcaHello Azure backend (Blob Storage, CosmosDB). Entry point: src/LiveInferenceOrchestrator.py.

cd InferenceSystem
uv sync --group prod

The model is downloaded automatically from HuggingFace Hub on first use.

uv run python src/LiveInferenceOrchestrator.py \
  --orch_config tests/orch_configs/LiveHLS/LiveHLS_OrcasoundLab.yml \
  --max_live_iterations 2

Since this is a test meant to run locally, upload_to_azure within orch_config is set to false and no updates are made to the backend (Azure Blob Storage, CosmosDB). See tests/orch_configs for more config examples.

2026-03-20 15:38:00,012 INFO --- [iter 1] LiveHLS poll: fetching segments in [1774046160, 1774046220] (now=1774046280, delay=60.0s)
2026-03-20 15:38:00,319 INFO Found 1 folders in date range
2026-03-20 15:38:00,576 INFO Dropping 10.0s tail audio (1 ts_segments)
2026-03-20 15:38:00,577 INFO [iter 1] LiveHLS poll: got 1 segments
2026-03-20 15:38:00,577 INFO Segment: folder=1773990017, indices=[5614:5620), start=2026-03-20T22:35:59Z, duration=60.0s
2026-03-20 15:38:02,144 INFO Processing clip: rpi-north-sjc_2026_03_20_15_35_59_PDT.wav, start_timestamp=2026-03-20T22:35:59Z
2026-03-20 15:38:02,662 DEBUG Generated spectrogram: wav_dir/rpi-north-sjc_2026_03_20_15_35_59_PDT.png
.../.venv/lib/python3.11/site-packages/torchaudio/functional/functional.py:582: UserWarning: At least one mel filterbank has all zero values. The value for `n_mels` (256) may be set too high. Or, the value for `n_freqs` (1281) may be set too low.
  warnings.warn(

=== Performance ===
File duration:   59.00s
Processing time: 0.30s
Realtime factor: 196.25x

=== Summary ===
1/29 segments predicted positive
Detected at times: [14.0]
global_confidence: 0.491
global_prediction: 0
2026-03-20 15:38:02,964 INFO Inference: prediction=0, confidence=0.491, positive_segments=1/29
2026-03-20 15:38:02,964 DEBUG Deleted local files: wav_dir/rpi-north-sjc_2026_03_20_15_35_59_PDT.wav, wav_dir/rpi-north-sjc_2026_03_20_15_35_59_PDT.png
2026-03-20 15:38:02,964 DEBUG Sleeping for 57.0s until 1774046340

Releasing the live inference system

Run InferenceSystem-deploy manually. Select a branch or tag in Use workflow from (normally main), enter an unused release version such as v2.2.0, and check every hydrophone location you want to deploy. The build uses the exact commit selected for the run; no separate source argument is needed. The workflow publishes the image and records its immutable digest, then waits for approval before deploying that same image to all selected locations in the same run.

A repository administrator must first configure required reviewers on the inference-production environment. Without that protection rule, the deployment job will not pause. After publishing, review the image summary and select Review deployments > Approve and deploy. You do not need to copy a publish run ID.

Deployment applies the namespace's ConfigMap and full deployment manifest, stops the old pods, and starts the published image. Failures attempt to restore the saved configuration and deployment. Verify pod health, logs, and the Orcanode monitor, then update each selected namespace's repository manifest to match the deployed image digest.

ConfigMap changes pushed to main automatically start InferenceSystem-deploy-configmaps. It applies the ConfigMaps changed in the latest commit and restarts their existing images without an approval step. A manual run applies all ConfigMaps. Image and ConfigMap deployments share one global lock and run sequentially.

See DEVELOPMENT.md for environment setup, release instructions, and the manual fallback, and AzurePlaybook.md for troubleshooting.

Development

For local scripts, testing, Docker, deployment, and contributing: DEVELOPMENT.md