Skip to content

feat(mlx): wire LoRA configuration - #527

Open
adohe wants to merge 1 commit into
mainfrom
feat/lora_cfg_for_mlx
Open

feat(mlx): wire LoRA configuration#527
adohe wants to merge 1 commit into
mainfrom
feat/lora_cfg_for_mlx

Conversation

@adohe

@adohe adohe commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

This PR implements the configuration and API-wiring foundation for MLX LoRA support.

  • Adds PEFT-compatible LoRA, base-model, and reference-mode fields to MlxConfig.
  • Propagates LoRA configuration through MLX training and serving setup while preserving the legacy MLX-LM-native adapter_path behavior.
  • Rejects ambiguous or unsupported MLX combinations and fails fast before model loading until adapter injection is implemented in the next phase.
  • Keeps backend-neutral MLX/config imports Torch-free by lazily loading Torch-backed adapter and API symbols, while preserving TorchDynamo setup for CUDA backends and spawned workers.

This is the configuration phase only. MLX adapter injection, PEFT weight conversion, adapter checkpoint export, and functional LoRA serving remain intentionally blocked by an explicit NotImplementedError.

Related issue

None.

Type of change

  • 🐛 Bug fix
  • ✨ New feature
  • 💥 Breaking change (public API / CLI behavior changes in a non-backward-compatible way)
  • 📝 Documentation update
  • ♻️ Refactoring
  • ⚡ Performance improvement
  • ✅ Test coverage improvement

How was it tested?

.venv/bin/python -m pytest \
  tests/test_adapter_imports_cpu.py \
  tests/test_config_data_cpu.py::ConfigAndDataTest::test_trainer_config_propagates_lora_reference_view \
  tests/test_config_data_cpu.py::ConfigAndDataTest::test_trainer_config_propagates_lora_to_mlx_config \
  tests/test_config_data_cpu.py::ConfigAndDataTest::test_mlx_config_rejects_ambiguous_adapter_inputs \
  tests/test_config_data_cpu.py::ConfigAndDataTest::test_mlx_config_rejects_lora_with_multimodal_unfreezing \
  tests/test_config_data_cpu.py::ConfigAndDataTest::test_mlx_trainer_rejects_unsupported_reference_and_multimodal_unfreezing \
  tests/test_import_boundaries_cpu.py \
  tests/test_mlx_training_cpu.py::test_mlx_backend_forwards_legacy_native_adapter_path \
  tests/test_mlx_training_cpu.py::test_mlx_backend_rejects_peft_lora_before_loading_provider \
  tests/test_serve_cli_cpu.py::test_mlx_serve_runtime_receives_peft_lora_config

Result: 12 passed in 2.87s.

Additional checks:

  • Ruff passed for all changed and added Python files.
  • python -m compileall passed for the changed Python files.
  • git diff --check passed.

Hardware limitations: validation was performed on macOS without running Metal training or GPU tests. Functional MLX LoRA execution is outside this phase and remains explicitly disabled.

Checklist

  • The PR title summarizes the contribution.
  • Linked the related issue in the description (if any).
  • Existing tests pass (pytest tests/ -k cpu).
  • New behavior is covered by tests.
  • Described the test commands run and any hardware limitations.
  • Public API / CLI changes are additive and backward-compatible (see CONTRIBUTING.md).

Propagate PEFT-compatible LoRA settings through MLX training and serving configuration while keeping adapter execution fail-fast until injection support lands.

Preserve Torch-free imports for MLX-only installations and defer CUDA runtime setup to Torch-backed entry points and spawned workers.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant