mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(install): use safe model backends for persistent services (#3646)
## Description Native persistent-service manifests now explicitly select CPU for the memory embedder and ONNX for Kompress by default. This avoids selecting Metal-specific model backends during supervised startup, while preserving explicit backend overrides. Closes #3604 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Add `HEADROOM_EMBEDDER_RUNTIME=cpu` and `HEADROOM_KOMPRESS_BACKEND=onnx` to native `persistent-service` manifests only. - Keep explicit `extra_env` values last so users can intentionally opt into another backend. - Add planner regression coverage for service defaults, overrides, and non-service presets. - Document the independent backend settings and the explicit MPS opt-in boundary. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text python -m pytest -q tests/test_install/test_planner.py tests/test_install/test_supervisors.py tests/test_install/test_runtime.py tests/test_cli/test_install_cli.py 133 passed ruff check headroom/install/planner.py tests/test_install/test_planner.py All checks passed ruff format --check headroom/install/planner.py tests/test_install/test_planner.py All checks passed git diff --check passed ``` ## Real Behavior Proof - Environment: Ubuntu/Linux development host; native macOS launchd and Apple Silicon Metal were not available. - Exact command / steps: Ran the focused planner, supervisor, runtime, and install CLI test suite plus Ruff and diff checks listed above. - Observed result: The planner emits CPU/ONNX defaults for native persistent services, preserves explicit backend overrides, and leaves persistent-task and Docker manifests unchanged; the focused suite passed. - Not tested: Real Apple Silicon macOS 26 behavior, launchd restart recovery, and ambient exported backend variables. The current base source also does not prove that a clean persistent-service install injected MPS; this PR is defensive safe-default hardening rather than a claim of reproducing the reported crash. ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: Standard release. - Stable/default behavior changed: Native `persistent-service` manifests use CPU/ONNX model backends by default. - Kill switch / disable path: Explicit `--env HEADROOM_EMBEDDER_RUNTIME=pytorch_mps` and/or `--env HEADROOM_KOMPRESS_BACKEND=pytorch_mps`, subject to platform and dependency support. - Unsafe override required: No. - Qualification impact: Persistent services no longer select Metal-specific model backends by default. - Rollback path: Revert this PR. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A — this is a manifest, test, and documentation change. ## Additional Notes `mypy` was not locally runnable because the maturin editable build failed: the installed Rust toolchain lacked an applicable cargo component. The PR does not claim CI success or real macOS runtime validation.
This commit is contained in:
@@ -169,6 +169,10 @@ def build_manifest(
|
||||
"HEADROOM_MODE": proxy_mode,
|
||||
"HEADROOM_BACKEND": backend,
|
||||
}
|
||||
if effective_preset == InstallPreset.PERSISTENT_SERVICE.value:
|
||||
# Keep native services away from Metal-specific model backends by default.
|
||||
base_env["HEADROOM_EMBEDDER_RUNTIME"] = "cpu"
|
||||
base_env["HEADROOM_KOMPRESS_BACKEND"] = "onnx"
|
||||
if anyllm_provider:
|
||||
base_env["HEADROOM_ANYLLM_PROVIDER"] = anyllm_provider
|
||||
if region:
|
||||
|
||||
@@ -50,6 +50,8 @@ def test_build_manifest_for_persistent_docker_sets_expected_defaults() -> None:
|
||||
# exist inside the container and would keep /readyz at 503 (#2803). The proxy
|
||||
# resolves the DB under its own cwd, which is the bind-mounted ~/.headroom.
|
||||
assert "--memory-db-path" not in manifest.proxy_args
|
||||
assert "HEADROOM_EMBEDDER_RUNTIME" not in manifest.base_env
|
||||
assert "HEADROOM_KOMPRESS_BACKEND" not in manifest.base_env
|
||||
|
||||
|
||||
def test_build_manifest_python_runtime_keeps_explicit_memory_db_path() -> None:
|
||||
@@ -97,6 +99,8 @@ def test_build_manifest_falls_back_from_windows_service_to_task(monkeypatch) ->
|
||||
|
||||
assert manifest.preset == InstallPreset.PERSISTENT_TASK.value
|
||||
assert manifest.supervisor_kind == "task"
|
||||
assert "HEADROOM_EMBEDDER_RUNTIME" not in manifest.base_env
|
||||
assert "HEADROOM_KOMPRESS_BACKEND" not in manifest.base_env
|
||||
|
||||
|
||||
def test_build_manifest_uses_provider_slice_env_builders_for_all_supported_targets() -> None:
|
||||
@@ -365,3 +369,31 @@ def test_build_manifest_extra_env_wins_over_grok_xai_default() -> None:
|
||||
assert manifest.base_env["OPENAI_TARGET_API_URL"] == "https://gateway.example/v1"
|
||||
idx = manifest.proxy_args.index("--openai-api-url")
|
||||
assert manifest.proxy_args[idx + 1] == "https://gateway.example/v1"
|
||||
|
||||
|
||||
def test_build_manifest_for_persistent_service_uses_safe_model_backends() -> None:
|
||||
manifest = build_manifest(**_base_manifest_kwargs())
|
||||
|
||||
assert manifest.base_env["HEADROOM_EMBEDDER_RUNTIME"] == "cpu"
|
||||
assert manifest.base_env["HEADROOM_KOMPRESS_BACKEND"] == "onnx"
|
||||
|
||||
|
||||
def test_persistent_service_explicit_model_backends_override_safe_defaults() -> None:
|
||||
manifest = build_manifest(
|
||||
**_base_manifest_kwargs(
|
||||
extra_env={
|
||||
"HEADROOM_EMBEDDER_RUNTIME": "pytorch_mps",
|
||||
"HEADROOM_KOMPRESS_BACKEND": "pytorch_mps",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
assert manifest.base_env["HEADROOM_EMBEDDER_RUNTIME"] == "pytorch_mps"
|
||||
assert manifest.base_env["HEADROOM_KOMPRESS_BACKEND"] == "pytorch_mps"
|
||||
|
||||
|
||||
def test_persistent_task_does_not_inherit_service_backend_defaults() -> None:
|
||||
manifest = build_manifest(**_base_manifest_kwargs(preset=InstallPreset.PERSISTENT_TASK.value))
|
||||
|
||||
assert "HEADROOM_EMBEDDER_RUNTIME" not in manifest.base_env
|
||||
assert "HEADROOM_KOMPRESS_BACKEND" not in manifest.base_env
|
||||
|
||||
@@ -27,6 +27,15 @@ headroom install status
|
||||
|
||||
This installs a background service on the current machine, applies persistent tool wiring, and keeps the proxy healthy on port `8787`.
|
||||
|
||||
Native `persistent-service` manifests explicitly default the memory embedder to
|
||||
`cpu` and Kompress to `onnx`. This avoids selecting the Apple Silicon Metal
|
||||
backends during supervised startup, where a native MPS abort cannot be handled
|
||||
by Python. These are safe defaults only: explicit `--env
|
||||
HEADROOM_EMBEDDER_RUNTIME=pytorch_mps` or
|
||||
`--env HEADROOM_KOMPRESS_BACKEND=pytorch_mps` still opts into MPS and requires
|
||||
the matching platform and optional dependencies. The two settings are
|
||||
independent; the Kompress setting does not control memory embedding.
|
||||
|
||||
### Persistent watchdog task
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user