Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: return freed host memory to the OS after diffusion and video unload (#11795)

Daniel Han3d2e576cb506
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index e93134e2457..dcb34ed9a06 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -112,6 +112,7 @@ from .diffusion_memory import (
raise_on_image_activation_shortfall,
raise_on_unified_memory_shortfall,
reclaimable_snapshot_device_memory,
+ reclaim_host_memory,
reclaim_offload_host_memory,
refine_memory_plan_for_components,
settled_snapshot_device_memory,
@@ -7839,6 +7840,8 @@ class DiffusionBackend:
self._state = None
del state
clear_gpu_cache()
+ # Must follow clear_gpu_cache() (runs gc) so the freed staging buffers can be returned.
+ reclaim_host_memory(logger = logger)
def status(self) -> dict[str, Any]:
state = self._state
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index 3e5a8182e25..e5842da5e11 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -117,10 +117,16 @@ def _resolve_host_memory_reclaimer() -> Optional[Callable[[], None]]:
def reclaim_offload_host_memory(offload_policy: str, logger: Any = None) -> bool:
"""Return unused allocator pages after whole-model CPU offload, without touching live
tensors, Python GC, or device caches. Unsupported allocators and failures are non-fatal."""
- global _host_memory_reclaim_warning_logged
- global _host_memory_reclaim_unsupported_logged
if offload_policy != OFFLOAD_MODEL:
return False
+ return reclaim_host_memory(logger = logger)
+
+
+def reclaim_host_memory(logger: Any = None) -> bool:
+ """Return freed allocator pages to the OS regardless of offload policy (unload / teardown).
+ Best effort: unsupported allocators and failures return False."""
+ global _host_memory_reclaim_warning_logged
+ global _host_memory_reclaim_unsupported_logged
try:
reclaim = _resolve_host_memory_reclaimer()
if reclaim is None:
@@ -130,7 +136,7 @@ def reclaim_offload_host_memory(offload_policy: str, logger: Any = None) -> bool
try:
logger.info(
"diffusion.memory: no host allocator pressure API on this platform "
- "(%s); offloaded host pages will not be returned early",
+ "(%s); freed host pages will not be returned early",
sys.platform,
)
except Exception: # noqa: BLE001
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index ce28b480c4d..17518e3e805 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -80,6 +80,7 @@ from .diffusion_memory import (
normalize_memory_mode,
plan_diffusion_memory,
raise_on_unified_memory_shortfall,
+ reclaim_host_memory,
reclaim_offload_host_memory,
settled_snapshot_device_memory,
)
@@ -6896,6 +6897,7 @@ class VideoBackend:
)
del state
clear_gpu_cache()
+ reclaim_host_memory(logger = logger)
def unload(self, *, expected_account: Optional[str] = None) -> dict[str, Any]:
with self._lock:
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 3d454279dec..8e3869bd786 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -8664,6 +8664,30 @@ def test_a_raising_unload_still_drains_the_teardown_fence(fake_runtime, tmp_path
assert backend.generate(prompt = "after", steps = 2)["images"]
+def test_unload_returns_freed_host_pages_after_the_gpu_cache(fake_runtime, tmp_path, monkeypatch):
+ # The trim must run after clear_gpu_cache() (which runs gc) and with the state gone.
+ from core.inference import diffusion as diffusion_module
+
+ backend = _loaded_backend(tmp_path)
+ order = []
+ real_clear = diffusion_module.clear_gpu_cache
+
+ def _clear(*args, **kwargs):
+ order.append("clear")
+ return real_clear(*args, **kwargs)
+
+ def _trim(logger = None):
+ order.append(("trim", backend._state is None))
+ return True
+
+ monkeypatch.setattr(diffusion_module, "clear_gpu_cache", _clear)
+ monkeypatch.setattr(diffusion_module, "reclaim_host_memory", _trim)
+ assert backend.unload()["loaded"] is False
+ assert order == ["clear", ("trim", True)]
+ backend.unload()
+ assert order == ["clear", ("trim", True)]
+
+
class _RecordingGate(threading.Event):
"""Teardown gate that reports every time a generation parks on it."""
diff --git a/studio/backend/tests/test_diffusion_memory.py b/studio/backend/tests/test_diffusion_memory.py
index ac839114571..ff77828225e 100644
--- a/studio/backend/tests/test_diffusion_memory.py
+++ b/studio/backend/tests/test_diffusion_memory.py
@@ -167,6 +167,26 @@ def test_host_memory_reclaimer_is_policy_scoped_and_best_effort(monkeypatch):
assert diffusion_memory.reclaim_offload_host_memory(OFFLOAD_MODEL) is False
+def test_reclaim_host_memory_ignores_the_offload_policy(monkeypatch):
+ calls = []
+ monkeypatch.setattr(
+ diffusion_memory, "_resolve_host_memory_reclaimer", lambda: lambda: calls.append(0)
+ )
+ assert diffusion_memory.reclaim_host_memory() is True
+ assert calls == [0]
+ for policy in (OFFLOAD_NONE, OFFLOAD_GROUP, OFFLOAD_SEQUENTIAL):
+ assert diffusion_memory.reclaim_offload_host_memory(policy) is False
+ assert calls == [0]
+
+ def call_failure():
+ raise OSError("allocator unavailable")
+
+ monkeypatch.setattr(diffusion_memory, "_resolve_host_memory_reclaimer", lambda: call_failure)
+ assert diffusion_memory.reclaim_host_memory() is False
+ monkeypatch.setattr(diffusion_memory, "_resolve_host_memory_reclaimer", lambda: None)
+ assert diffusion_memory.reclaim_host_memory() is False
+
+
def test_host_memory_reclaimer_caches_unsupported_or_missing_apis(monkeypatch):
loads = []
monkeypatch.setattr(diffusion_memory.sys, "platform", "linux")
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 70f254cdebc..1e476747499 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -4994,6 +4994,22 @@ def test_a_raising_teardown_still_drains_the_fence(fake_runtime, tmp_path, monke
assert backend.generate(prompt = "after", steps = 2)["mp4_bytes"] == b"MP4"
+def test_teardown_returns_freed_host_pages_after_the_gpu_cache(fake_runtime, tmp_path, monkeypatch):
+ from core.inference import video as video_mod
+
+ backend = VideoBackend()
+ _load_gguf(backend, tmp_path)
+ order = []
+ monkeypatch.setattr(video_mod, "clear_gpu_cache", lambda: order.append("clear"))
+ monkeypatch.setattr(
+ video_mod,
+ "reclaim_host_memory",
+ lambda logger = None: order.append(("trim", backend._state is None)) or True,
+ )
+ assert backend.unload()["loaded"] is False
+ assert order == ["clear", ("trim", True)]
+
+
# ── the H3 native path and the audio VAE ─────────────────────────────────────
def test_the_h3_native_load_never_puts_the_vae_on_the_cpu():
"""`low_vram` maps to the `model` policy, which emits `--vae-on-cpu` for everyone else.