deep-learning-azure

Public Azure integration layer for deep-learning-core.

deep-learning-azure adds Azure ML execution, Azure storage helpers, and Azure-oriented dataset wrappers on top of deep-learning-core.

Current release: deep-learning-azure==0.0.19. Requires deep-learning-core>=0.0.26,<0.1.

What's New in 0.0.19?

• blob URLs can now be signed with user-delegation SAS tokens; invalid options and signing failures raise explicit errors instead of returning unsigned URLs
• blob cache paths remain beneath the configured cache root, and pooled container clients are isolated by authenticated service instance
• AzCopy commands run without a shell, preserving paths as literal arguments while supplying retry concurrency through the child-process environment
• Azure MLflow workspace discovery now uses the Azure ML v2 client, removing the legacy azureml-core dependency
• generated repositories ignore Azure output and log directories, and Azure submissions exclude local environment files

Install it directly or through the deep-learning-core[azure] extra. The package is kept separate so Azure-specific dependencies and scaffold wiring do not leak into plain deep-learning-core installations.

Install

Install from PyPI through the core extra:

pip install "deep-learning-core[azure]"

Install the package directly:

pip install deep-learning-azure

Install in a uv project:

uv add "deep-learning-core[azure]"

Scope

• Azure ML executor
• Azure storage helpers and AzCopy wrappers
• Azure dataset wrappers
• Azure experiment scaffold integration through dl-init --with-azure

Out Of Scope

• Generic trainer, dataset, and metric abstractions
• Public framework defaults
• Concrete experiment repositories

Quick Start

Install it into an experiment repository through the Azure extra:

uv add "deep-learning-core[azure]"

If the repository was scaffolded with dl-init --with-azure, the experiment package will import dl_azure automatically so its executor and generic dataset wrappers register at runtime, and the scaffold will also create azure-config.json.

The Azure executor is sweep-oriented. Use uv run dl-sweep experiments/lr_sweep.yaml --dry-run before the first real submission in a new repository.

If you need Azure ML to run a custom script instead of the default python -m dl_core.worker ... command, set executor.command in the sweep config. Prefer plain python ... commands because the Azure ML environment already controls the runtime. The command string also supports placeholders such as {config_path} and {run_name}.

Concrete experiment flow:

uv init
uv add deep-learning-azure
uv run dl-init --root-dir . --with-azure
uv run dl-core add dataset AzureSeq --base azure_compute_multiframe
uv run dl-sweep experiments/lr_sweep.yaml --dry-run

Example custom Azure submission:

fixed:
  executor:
    name: azure
    compute_target: gpu-cluster
    environment_name: dl_lab
    environment_version: latest
    # parent_job_name: existing-azure-parent-job
    command: python scripts/preprocessing/fix_nested_frame_dirs.py --config {config_path}

Tracker naming defaults to the repository root name. If you want Azure job submission and Azure MLflow to use a different destination name, set tracking.experiment_name in your sweep config. Use executor.parent_job_name when child Azure jobs should nest under an existing Azure ML parent job; keep tracking.parent_run_id for MLflow nesting.

Azure submissions automatically rewrite the default local runtime.output_dir from artifacts to outputs/artifacts inside the remote job. That keeps checkpoints, plots, metrics, and other run files under Azure ML's managed output directory without changing the local default artifact layout.

When you analyze an Azure-backed sweep with dl-analyze, the Azure metrics source fetches only the metric histories requested on the CLI, for example:

uv run dl-analyze --sweep experiments/lr_sweep.yaml \
  --metric test/eer --mode min \
  --metric test/accuracy --mode max \
  --rank-method rank-sum

Those fetched metric histories are cached in analysis_cache.json next to sweep_tracking.json. Use --force to refresh them.

If you want the tracked Azure job outputs locally after the sweep finishes, run:

uv run dl-sync --sweep experiments/lr_sweep.yaml --artifacts

That downloads the Azure job bundle for each tracked run and patches sweep_tracking.json with the resolved local artifact paths.

Concrete dataset scaffold examples:

uv run dl-core add dataset AzureImages --base azure_compute
uv run dl-core add dataset AzureFrames --base azure_compute_frame
uv run dl-core add dataset AzureSeq --base azure_compute_multiframe
uv run dl-core add dataset AzureStream --base azure_streaming
uv run dl-core add dataset AzureStreamSeq --base azure_streaming_multiframe

Dataset Wrapper Notes

Use the compute wrappers when the dataset is already mounted into the Azure ML job or available locally through a compatible directory layout:

• AzureComputeWrapper
• AzureComputeFrameWrapper
• AzureComputeMultiFrameWrapper

Compute wrappers resolve the dataset root in this order:

• dataset.root_dir
• AZURE_ML_INPUT_<input_name>
• dataset.local_fallback_root when dataset.allow_local_fallback is true

Use the streaming wrappers when you want to read directly from blob storage instead of relying on an Azure ML input mount:

• AzureStreamingWrapper
• AzureStreamingFrameWrapper
• AzureStreamingMultiFrameWrapper

Streaming wrappers require dataset.container_name and an Azure storage config that provides account_name, either in azure-config.json or inline in the dataset config.

AzureClientService.get_blob_sas_url() issues a user-delegation SAS through DefaultAzureCredential; it never silently returns an unsigned URL. The active identity therefore needs permission to request a user delegation key and the required Blob Data role for the requested operation.

Frame wrappers share a few image-specific settings:

• height / width for the output tensor shape
• resize_height / resize_width for pre-augmentation resizing
• use_face_detection to enable metadata-driven face crops
• margin as an int, two-item sequence, or {height, width} mapping

If you enable face_detected_and_resized_cache, processed frame images are stored in the wrapper cache when a cache backend is available. That is most useful for the streaming frame wrappers, where blob reads can be cached locally.

Multiframe wrappers add one multiframe block:

dataset:
  name: AzureSeq
  input_name: dataset_path
  allow_local_fallback: true
  local_fallback_root: data/my_dataset
  height: 224
  width: 224
  use_face_detection: true
  face_detected_and_resized_cache: true
  multiframe:
    mode: consecutive
    num_frames: 5
    frame_stride: 2

multiframe.mode: random draws num_frames unique frames per sample. multiframe.mode: consecutive walks each video in fixed windows and uses frame_stride to skip frames between windows. Videos with fewer than num_frames frames are skipped.

What You Get

• the azure executor
• Azure storage helpers and AzCopy wrappers
• generic Azure dataset foundations: AzureComputeWrapper, AzureStreamingWrapper, AzureComputeFrameWrapper, AzureStreamingFrameWrapper, AzureComputeMultiFrameWrapper, and AzureStreamingMultiFrameWrapper
• dl-init --with-azure scaffold integration
• a managed .amlignore block that preserves user content while excluding common local-only outputs and environment files from Azure submissions
• Azure job output routing to outputs/artifacts for automatic artifact persistence in Azure ML

Companion Packages

• dl-core
• dl-mlflow
• dl-wandb

Documentation

• Documentation Index
• GitHub Repository

License

MIT. See LICENSE.