ltcai 11.2.0 → 11.4.0

package/latticeai/services/model_runtime/__init__.py

@@ -0,0 +1,322 @@
+"""Model runtime and provider helpers for Lattice AI.
+
+This module owns local/cloud model preparation, engine detection, model download,
+provider-specific server startup, smoke tests, and runtime feature payloads. It is
+configured by ``server_app`` with app-level state but has no FastAPI app import.
+
+Split into cohesive submodules in v11.3.0 (no behaviour change): ``state`` (the
+immutable ``ModelRuntimeState`` and the consent gates), ``engines`` (engine
+wrappers + the LM Studio client), ``download`` (Hugging Face readiness and
+fetch), ``status`` (``engine_status`` / ``runtime_features`` / ``install_engine``),
+``loading`` (identity resolution and the load entrypoints), ``cloud`` (cloud key
+verification) and ``service`` (the bound ``ModelRuntimeService``). This module
+re-exports every name the single file exposed, so
+``latticeai.services.model_runtime.X`` keeps working — including the private
+names ``model_loading._get_model_runtime_deps`` imports.
+
+Two deliberate omissions: ``engines._LMSTUDIO_MODELS_CACHE`` and
+``_LMSTUDIO_MODELS_CACHE_TS`` are *rebound* by ``get_lmstudio_models``, so a
+re-export here would be a snapshot frozen at import time. They stay reachable
+at ``latticeai.services.model_runtime.engines``, which is where the live values
+are.
+
+Stubbing note: rebinding a name *here* changes only this module's name — the
+lazy ``from latticeai.services.model_runtime import …`` calls in
+``model_engines`` and ``model_loading`` read it, but a submodule that uses the
+name holds its own reference. A test standing in for a helper patches the
+submodule that uses it.
+"""
+
+from __future__ import annotations
+
+# The single file had no ``__all__``, so its public surface was "every module
+# global" — including the names it imported for its own use. Every re-export
+# below therefore uses the redundant-alias form: it reproduces exactly that
+# surface, and it marks each name as deliberate rather than a leftover import.
+from latticeai.core.quiet import quiet as quiet
+from latticeai.models.router import HF_MODELS_ROOT as HF_MODELS_ROOT
+from latticeai.models.router import (
+    OPENAI_COMPATIBLE_PROVIDERS as OPENAI_COMPATIBLE_PROVIDERS,
+)
+from latticeai.models.router import AsyncOpenAI as AsyncOpenAI
+from latticeai.models.router import ensure_mlx_runtime as ensure_mlx_runtime
+from latticeai.models.router import hf_cache_model_dir as hf_cache_model_dir
+from latticeai.models.router import hf_model_dir as hf_model_dir
+from latticeai.models.router import parse_model_ref as parse_model_ref
+
+# Catalog data + version-dedup helpers live in ``model_catalog``; re-exported
+# here so existing ``from ...model_runtime import ENGINE_MODEL_CATALOG`` imports
+# keep working.
+from latticeai.services.model_catalog import (
+    _VERSIONED_MODEL_PATTERNS as _VERSIONED_MODEL_PATTERNS,
+)
+from latticeai.services.model_catalog import (
+    ENGINE_INSTALLERS as ENGINE_INSTALLERS,
+)
+from latticeai.services.model_catalog import (
+    ENGINE_MODEL_CATALOG as ENGINE_MODEL_CATALOG,
+)
+from latticeai.services.model_catalog import (
+    MODEL_ENGINE_ALIASES as MODEL_ENGINE_ALIASES,
+)
+from latticeai.services.model_catalog import (
+    _model_family_version as _model_family_version,
+)
+from latticeai.services.model_catalog import (
+    _version_tuple as _version_tuple,
+)
+from latticeai.services.model_catalog import (
+    filter_lower_family_versions as filter_lower_family_versions,
+)
+from latticeai.services.model_errors import ModelRuntimeError as ModelRuntimeError
+from latticeai.services.model_runtime.cloud import (
+    CLOUD_VERIFY_TTL_SECONDS as CLOUD_VERIFY_TTL_SECONDS,
+)
+from latticeai.services.model_runtime.cloud import (
+    _probe_cloud_model as _probe_cloud_model,
+)
+from latticeai.services.model_runtime.cloud import (
+    verify_cloud_models as verify_cloud_models,
+)
+from latticeai.services.model_runtime.download import (
+    download_hf_model as download_hf_model,
+)
+from latticeai.services.model_runtime.download import (
+    estimate_eta_seconds as estimate_eta_seconds,
+)
+from latticeai.services.model_runtime.download import (
+    hf_model_ready as hf_model_ready,
+)
+from latticeai.services.model_runtime.download import (
+    hf_repo_files_with_sizes as hf_repo_files_with_sizes,
+)
+from latticeai.services.model_runtime.download import (
+    model_download_progress_payload as model_download_progress_payload,
+)
+from latticeai.services.model_runtime.engines import (
+    _LMSTUDIO_MODELS_CACHE_TTL as _LMSTUDIO_MODELS_CACHE_TTL,
+)
+
+# The private aliases the historical module bound for its own use — including
+# the ones ``model_loading._get_model_runtime_deps`` imports by name. They are
+# re-exported from the submodule that already binds them under exactly these
+# names, which is ruff's redundant-alias re-export form.
+from latticeai.services.model_runtime.engines import (
+    _LOCAL_SERVER_PROCESSES as _LOCAL_SERVER_PROCESSES,
+)
+from latticeai.services.model_runtime.engines import (
+    LMSTUDIO_BUNDLED_CLI as LMSTUDIO_BUNDLED_CLI,
+)
+from latticeai.services.model_runtime.engines import (
+    LOCAL_SERVER_PROCESSES as LOCAL_SERVER_PROCESSES,
+)
+from latticeai.services.model_runtime.engines import (
+    VLLM_METAL_BIN as VLLM_METAL_BIN,
+)
+from latticeai.services.model_runtime.engines import (
+    VLLM_METAL_ENV as VLLM_METAL_ENV,
+)
+from latticeai.services.model_runtime.engines import (
+    VLLM_METAL_PYTHON as VLLM_METAL_PYTHON,
+)
+from latticeai.services.model_runtime.engines import (
+    _engine_install_plan as _engine_install_plan,
+)
+from latticeai.services.model_runtime.engines import (
+    _engine_support_status as _engine_support_status,
+)
+from latticeai.services.model_runtime.engines import (
+    _ensure_llamacpp_server as _ensure_llamacpp_server,
+)
+from latticeai.services.model_runtime.engines import (
+    _ensure_lmstudio_server as _ensure_lmstudio_server,
+)
+from latticeai.services.model_runtime.engines import (
+    _ensure_ollama_server as _ensure_ollama_server,
+)
+from latticeai.services.model_runtime.engines import (
+    _ensure_vllm_server as _ensure_vllm_server,
+)
+from latticeai.services.model_runtime.engines import (
+    _find_lmstudio_cli as _find_lmstudio_cli,
+)
+from latticeai.services.model_runtime.engines import (
+    _find_lmstudio_model_key as _find_lmstudio_model_key,
+)
+from latticeai.services.model_runtime.engines import (
+    _get_ollama_pulled_models as _get_ollama_pulled_models,
+)
+from latticeai.services.model_runtime.engines import (
+    _get_openai_compatible_server_models as _get_openai_compatible_server_models,
+)
+from latticeai.services.model_runtime.engines import (
+    _json_request as _json_request,
+)
+from latticeai.services.model_runtime.engines import (
+    _lmstudio_candidate_keys as _lmstudio_candidate_keys,
+)
+from latticeai.services.model_runtime.engines import (
+    _local_binary as _local_binary,
+)
+from latticeai.services.model_runtime.engines import (
+    _pull_ollama_model_with_progress as _pull_ollama_model_with_progress,
+)
+from latticeai.services.model_runtime.engines import (
+    _safe_engine_install_plan as _safe_engine_install_plan,
+)
+from latticeai.services.model_runtime.engines import (
+    _update_env_file as _update_env_file,
+)
+from latticeai.services.model_runtime.engines import (
+    _vllm_executable as _vllm_executable,
+)
+from latticeai.services.model_runtime.engines import (
+    _vllm_metal_python as _vllm_metal_python,
+)
+from latticeai.services.model_runtime.engines import (
+    _wait_for_openai_compatible_server as _wait_for_openai_compatible_server,
+)
+from latticeai.services.model_runtime.engines import (
+    _windows_binary_candidates as _windows_binary_candidates,
+)
+from latticeai.services.model_runtime.engines import (
+    engine_installed as engine_installed,
+)
+from latticeai.services.model_runtime.engines import (
+    engine_support_status as engine_support_status,
+)
+from latticeai.services.model_runtime.engines import (
+    ensure_llamacpp_server as ensure_llamacpp_server,
+)
+from latticeai.services.model_runtime.engines import (
+    ensure_lmstudio_model as ensure_lmstudio_model,
+)
+from latticeai.services.model_runtime.engines import (
+    ensure_lmstudio_server as ensure_lmstudio_server,
+)
+from latticeai.services.model_runtime.engines import (
+    ensure_ollama_server as ensure_ollama_server,
+)
+from latticeai.services.model_runtime.engines import (
+    ensure_vllm_server as ensure_vllm_server,
+)
+from latticeai.services.model_runtime.engines import (
+    find_lmstudio_cli as find_lmstudio_cli,
+)
+from latticeai.services.model_runtime.engines import (
+    get_lmstudio_models as get_lmstudio_models,
+)
+from latticeai.services.model_runtime.engines import (
+    get_ollama_pulled_models as get_ollama_pulled_models,
+)
+from latticeai.services.model_runtime.engines import (
+    get_openai_compatible_server_models as get_openai_compatible_server_models,
+)
+from latticeai.services.model_runtime.engines import (
+    lmstudio_api_base as lmstudio_api_base,
+)
+from latticeai.services.model_runtime.engines import (
+    lmstudio_native_api_base as lmstudio_native_api_base,
+)
+from latticeai.services.model_runtime.engines import (
+    local_binary as local_binary,
+)
+from latticeai.services.model_runtime.engines import (
+    pull_ollama_model_with_progress as pull_ollama_model_with_progress,
+)
+from latticeai.services.model_runtime.engines import (
+    vllm_executable as vllm_executable,
+)
+from latticeai.services.model_runtime.engines import (
+    vllm_metal_python as vllm_metal_python,
+)
+from latticeai.services.model_runtime.engines import (
+    wait_for_openai_compatible_server as wait_for_openai_compatible_server,
+)
+from latticeai.services.model_runtime.engines import (
+    windows_binary_candidates as windows_binary_candidates,
+)
+from latticeai.services.model_runtime.loading import (
+    _LOCAL_SMOKE_ENGINES as _LOCAL_SMOKE_ENGINES,
+)
+from latticeai.services.model_runtime.loading import (
+    _ModelResolution as _ModelResolution,
+)
+from latticeai.services.model_runtime.loading import (
+    _resolve_model_alias as _resolve_model_alias,
+)
+from latticeai.services.model_runtime.loading import (
+    _smoke_test_loaded_model as _smoke_test_loaded_model,
+)
+from latticeai.services.model_runtime.loading import (
+    build_model_resolution as build_model_resolution,
+)
+from latticeai.services.model_runtime.loading import (
+    ensure_engine_ready as ensure_engine_ready,
+)
+from latticeai.services.model_runtime.loading import (
+    normalize_local_model_request as normalize_local_model_request,
+)
+from latticeai.services.model_runtime.loading import (
+    prepare_and_load_model as prepare_and_load_model,
+)
+from latticeai.services.model_runtime.loading import (
+    prepare_and_load_model_stream as prepare_and_load_model_stream,
+)
+from latticeai.services.model_runtime.loading import (
+    sse_event as sse_event,
+)
+from latticeai.services.model_runtime.service import (
+    ModelRuntimeService as ModelRuntimeService,
+)
+from latticeai.services.model_runtime.service import (
+    build_model_runtime as build_model_runtime,
+)
+from latticeai.services.model_runtime.service import (
+    configure_model_runtime as configure_model_runtime,
+)
+from latticeai.services.model_runtime.state import (
+    _MODEL_LOADING_COMPAT_EXPORTS as _MODEL_LOADING_COMPAT_EXPORTS,
+)
+from latticeai.services.model_runtime.state import (
+    _SMOKE_PROMPT as _SMOKE_PROMPT,
+)
+from latticeai.services.model_runtime.state import (
+    ModelRuntimeState as ModelRuntimeState,
+)
+from latticeai.services.model_runtime.state import (
+    _download_allowed as _download_allowed,
+)
+from latticeai.services.model_runtime.state import (
+    _download_block as _download_block,
+)
+from latticeai.services.model_runtime.state import (
+    _engine_install_block as _engine_install_block,
+)
+from latticeai.services.model_runtime.state import (
+    _friendly_model_runtime_error as _friendly_model_runtime_error,
+)
+from latticeai.services.model_runtime.state import (
+    _missing_current_user as _missing_current_user,
+)
+from latticeai.services.model_runtime.state import (
+    _missing_user_api_key as _missing_user_api_key,
+)
+from latticeai.services.model_runtime.state import (
+    _model_runtime_compatibility as _model_runtime_compatibility,
+)
+from latticeai.services.model_runtime.state import (
+    create_model_runtime_state as create_model_runtime_state,
+)
+from latticeai.services.model_runtime.status import (
+    _install_engine as _install_engine,
+)
+from latticeai.services.model_runtime.status import (
+    engine_status as engine_status,
+)
+from latticeai.services.model_runtime.status import (
+    install_engine as install_engine,
+)
+from latticeai.services.model_runtime.status import (
+    runtime_features as runtime_features,
+)

package/latticeai/services/model_runtime/cloud.py

@@ -0,0 +1,87 @@
+"""Cloud model verification — does this key actually answer for this model?
+
+A one-token chat completion per configured cloud model, cached per service
+instance for :data:`CLOUD_VERIFY_TTL_SECONDS`. A model the router already knows
+is unavailable is recorded as such without a network call.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any, Dict, Optional
+
+from latticeai.models.router import (
+    OPENAI_COMPATIBLE_PROVIDERS,
+    AsyncOpenAI,
+    parse_model_ref,
+)
+from latticeai.services.model_runtime.state import ModelRuntimeState
+
+CLOUD_VERIFY_TTL_SECONDS = 600
+
+async def _probe_cloud_model(model_ref: str) -> Dict[str, Any]:
+    provider, model_name = parse_model_ref(model_ref)
+    config = OPENAI_COMPATIBLE_PROVIDERS.get(provider)
+    if not config:
+        return {"ok": False, "reason": f"Unsupported provider: {provider}"}
+
+    api_key = os.getenv(config["env_key"]) or config.get("api_key_fallback")
+    if not api_key:
+        return {"ok": False, "reason": f"Missing API key: {config['env_key']}"}
+
+    base_url = os.getenv(config.get("base_url_env", "")) if config.get("base_url_env") else None
+    base_url = base_url or config.get("base_url")
+    try:
+        # base_url is passed only when configured: an explicit None is not
+        # the same as omitting the argument.
+        client = (
+            AsyncOpenAI(api_key=api_key, base_url=base_url)
+            if base_url
+            else AsyncOpenAI(api_key=api_key)
+        )
+        await asyncio.wait_for(
+            client.chat.completions.create(
+                model=model_name,
+                messages=[{"role": "user", "content": "ping"}],
+                max_tokens=1,
+                temperature=0,
+            ),
+            timeout=15,
+        )
+        return {"ok": True, "reason": "ok"}
+    except Exception as e:
+        return {"ok": False, "reason": str(e)[:220]}
+
+
+async def verify_cloud_models(
+    force: bool = False,
+    provider_filter: Optional[str] = None,
+    *,
+    state: ModelRuntimeState,
+    cache: Dict[str, Dict[str, Any]],
+) -> Dict[str, Dict]:
+    now = time.time()
+    r = state.router
+    cloud_items = [item for item in (r.detected_cloud_models() if r else []) if item.get("tag") == "cloud"]
+    if provider_filter:
+        cloud_items = [item for item in cloud_items if item.get("provider") == provider_filter]
+
+    results: Dict[str, Dict] = {}
+    for item in cloud_items:
+        model_ref = item["id"]
+        cached = cache.get(model_ref)
+        if not force and cached and (now - cached.get("ts", 0) <= CLOUD_VERIFY_TTL_SECONDS):
+            results[model_ref] = cached
+            continue
+        if item.get("available") is False:
+            record = {"ok": False, "reason": item.get("requires") or "API key missing", "ts": now}
+            cache[model_ref] = record
+            results[model_ref] = record
+            continue
+        probe = await _probe_cloud_model(model_ref)
+        record = {"ok": bool(probe.get("ok")), "reason": probe.get("reason", ""), "ts": now}
+        cache[model_ref] = record
+        results[model_ref] = record
+    return results

package/latticeai/services/model_runtime/download.py

@@ -0,0 +1,282 @@
+"""Hugging Face model presence, download, and download progress.
+
+Answers one question — "are the weights actually on this disk?" — and, when
+they are not and the caller has consent, fetches them while emitting a progress
+payload per file. The readiness check is deliberately format-aware: a GGUF
+repo, an MLX 4-bit repo and a vLLM bf16 repo each prove completeness
+differently.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.quiet import quiet
+from latticeai.models.router import hf_cache_model_dir, hf_model_dir
+from latticeai.services.model_errors import ModelRuntimeError
+
+
+def hf_model_ready(repo_id: str, provider: str = "local_mlx") -> bool:
+    model_dir = hf_model_dir(repo_id)
+    if provider in {"local_mlx", "vllm"} and (not model_dir.exists() or not model_dir.is_dir()):
+        hf_cache_repo = Path.home() / ".cache" / "huggingface" / "hub" / f"models--{repo_id.replace('/', '--')}"
+        if hf_cache_repo.exists() and any(hf_cache_repo.glob("snapshots/*")):
+            if provider == "vllm":
+                return True
+            return hf_cache_model_dir(repo_id) is not None
+        return False
+    if not model_dir.exists() or not model_dir.is_dir():
+        return False
+    if provider == "llamacpp":
+        return any(model_dir.rglob("*.gguf"))
+    has_config = (model_dir / "config.json").exists()
+    has_weights = any(model_dir.glob("*.safetensors")) or any(model_dir.glob("*.bin"))
+    has_tokenizer = (
+        (model_dir / "tokenizer.json").exists()
+        or (model_dir / "tokenizer.model").exists()
+        or (model_dir / "tokenizer_config.json").exists()
+    )
+    return has_config and has_weights and has_tokenizer
+
+
+def model_download_progress_payload(
+    stage: str,
+    message: str,
+    *,
+    percent: Optional[float] = None,
+    detail: Optional[str] = None,
+    downloaded_bytes: Optional[int] = None,
+    total_bytes: Optional[int] = None,
+    eta_seconds: Optional[float] = None,
+    file: Optional[str] = None,
+    indeterminate: bool = False,
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {
+        "stage": stage,
+        "message": message,
+        "indeterminate": indeterminate,
+        "ts": time.time(),
+    }
+    if percent is not None:
+        payload["percent"] = max(0, min(100, round(float(percent), 1)))
+    if detail:
+        payload["detail"] = detail
+    if downloaded_bytes is not None:
+        payload["downloaded_bytes"] = max(0, int(downloaded_bytes))
+    if total_bytes is not None:
+        payload["total_bytes"] = max(0, int(total_bytes))
+    if eta_seconds is not None:
+        payload["eta_seconds"] = max(0, round(float(eta_seconds)))
+    if file:
+        payload["file"] = file
+    return payload
+
+
+def estimate_eta_seconds(started_at: float, percent: Optional[float]) -> Optional[float]:
+    if percent is None or percent <= 0 or percent >= 100:
+        return None
+    elapsed = max(0.0, time.time() - started_at)
+    return elapsed * (100.0 - percent) / percent
+
+
+def hf_repo_files_with_sizes(repo_id: str) -> List[Dict[str, Any]]:
+    from huggingface_hub import HfApi
+
+    api = HfApi()
+    try:
+        info = api.model_info(repo_id, files_metadata=True)
+        files = []
+        for sibling in getattr(info, "siblings", []) or []:
+            name = str(getattr(sibling, "rfilename", "") or "").strip()
+            if not name or name.endswith("/"):
+                continue
+            files.append({"name": name, "size": int(getattr(sibling, "size", 0) or 0)})
+        if files:
+            return files
+    except TypeError:
+        quiet()
+    except Exception as e:
+        logging.warning("huggingface model_info failed for %s: %s", repo_id, e)
+
+    return [{"name": str(name), "size": 0} for name in api.list_repo_files(repo_id) if str(name).strip()]
+
+
+def download_hf_model(
+    repo_id: str,
+    provider: str = "local_mlx",
+    progress_emit=None,
+) -> Dict[str, Any]:
+    if importlib.util.find_spec("huggingface_hub") is None:
+        raise ModelRuntimeError(status_code=400, detail="huggingface_hub가 없습니다. 먼저 MLX runtime 설치를 진행해 주세요.")
+
+    target_dir = hf_model_dir(repo_id)
+    if hf_model_ready(repo_id, provider):
+        cached_dir = hf_cache_model_dir(repo_id) if provider == "local_mlx" else None
+        resolved_dir = cached_dir or target_dir
+        if progress_emit:
+            progress_emit(model_download_progress_payload(
+                "download",
+                "이미 다운로드된 모델을 확인했습니다.",
+                percent=100,
+                downloaded_bytes=0,
+                total_bytes=0,
+                eta_seconds=0,
+            ))
+        return {"model": repo_id, "path": str(resolved_dir), "cached": True}
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        from huggingface_hub import hf_hub_download
+
+        started_at = time.time()
+        all_files = hf_repo_files_with_sizes(repo_id)
+        if provider == "llamacpp":
+            ggufs = sorted(
+                [item for item in all_files if str(item["name"]).lower().endswith(".gguf")],
+                key=lambda item: str(item["name"]),
+            )
+            if not ggufs:
+                raise RuntimeError("GGUF 파일을 찾지 못했습니다.")
+            preference = ("q4_k_m", "q4_0", "q4_k_s", "q3_k_m", "q2_k")
+            selected_files = [
+                next(
+                    (item for pref in preference for item in ggufs if pref in str(item["name"]).lower()),
+                    ggufs[0],
+                )
+            ]
+        else:
+            selected_files = all_files
+
+        total_bytes = sum(int(item.get("size") or 0) for item in selected_files) or None
+        downloaded_bytes = 0
+        total_files = max(1, len(selected_files))
+        if progress_emit:
+            progress_emit(model_download_progress_payload(
+                "download",
+                "모델 파일 정보를 확인했습니다.",
+                percent=0,
+                downloaded_bytes=0,
+                total_bytes=total_bytes,
+                indeterminate=total_bytes is None,
+            ))
+
+        for index, item in enumerate(selected_files, start=1):
+            filename = str(item["name"])
+            size = int(item.get("size") or 0)
+            tqdm_class = None
+            if progress_emit:
+                current_percent = (
+                    (downloaded_bytes / total_bytes) * 100 if total_bytes else ((index - 1) / total_files) * 100
+                )
+                progress_emit(model_download_progress_payload(
+                    "download",
+                    "모델 다운로드 중입니다.",
+                    percent=current_percent,
+                    detail=filename,
+                    downloaded_bytes=downloaded_bytes,
+                    total_bytes=total_bytes,
+                    eta_seconds=estimate_eta_seconds(started_at, current_percent),
+                    file=filename,
+                    indeterminate=total_bytes is None and total_files <= 1,
+                ))
+                try:
+                    from tqdm.auto import tqdm as base_tqdm
+
+                    downloaded_before = downloaded_bytes
+                    last_emit = {"at": 0.0, "percent": -1.0}
+
+                    def emit_byte_progress(
+                        done_bytes: float,
+                        # Bound per iteration: this callback outlives the loop
+                        # body when a download runs long, and late binding
+                        # would report every file's progress against the last
+                        # file's offsets.
+                        downloaded_before: int = downloaded_before,
+                        size: Any = size,
+                        index: int = index,
+                        last_emit: dict = last_emit,
+                        filename: str = filename,
+                    ) -> None:
+                        done = max(0, int(done_bytes or 0))
+                        if total_bytes:
+                            aggregate = min(total_bytes, downloaded_before + done)
+                            percent = (aggregate / total_bytes) * 100
+                        else:
+                            file_total = size or done
+                            file_ratio = min(1.0, done / file_total) if file_total else 0.0
+                            aggregate = downloaded_before + done
+                            percent = ((index - 1) + file_ratio) / total_files * 100
+                        now = time.time()
+                        if percent < 100 and now - last_emit["at"] < 0.5 and percent - last_emit["percent"] < 0.3:
+                            return
+                        last_emit["at"] = now
+                        last_emit["percent"] = percent
+                        progress_emit(model_download_progress_payload(
+                            "download",
+                            "모델 다운로드 중입니다.",
+                            percent=percent,
+                            detail=filename,
+                            downloaded_bytes=aggregate,
+                            total_bytes=total_bytes,
+                            eta_seconds=estimate_eta_seconds(started_at, percent),
+                            file=filename,
+                            indeterminate=total_bytes is None and total_files <= 1,
+                        ))
+
+                    class ProgressTqdm(base_tqdm):
+                        def update(self, n=1):
+                            result = super().update(n)
+                            emit_byte_progress(float(getattr(self, "n", 0) or 0))
+                            return result
+
+                    tqdm_class = ProgressTqdm
+                except Exception:
+                    tqdm_class = None
+            local_path = hf_hub_download(
+                repo_id=repo_id,
+                filename=filename,
+                local_dir=str(target_dir),
+                tqdm_class=tqdm_class,
+            )
+            if size <= 0:
+                try:
+                    size = Path(local_path).stat().st_size
+                except OSError:
+                    size = 0
+            downloaded_bytes += size
+            if progress_emit:
+                current_percent = (
+                    (downloaded_bytes / total_bytes) * 100 if total_bytes else (index / total_files) * 100
+                )
+                progress_emit(model_download_progress_payload(
+                    "download",
+                    "모델 다운로드 중입니다.",
+                    percent=current_percent,
+                    detail=filename,
+                    downloaded_bytes=downloaded_bytes,
+                    total_bytes=total_bytes,
+                    eta_seconds=estimate_eta_seconds(started_at, current_percent),
+                    file=filename,
+                    indeterminate=False,
+                ))
+
+        if progress_emit:
+            progress_emit(model_download_progress_payload(
+                "download",
+                "모델 다운로드가 완료되었습니다.",
+                percent=100,
+                downloaded_bytes=downloaded_bytes,
+                total_bytes=total_bytes or downloaded_bytes,
+                eta_seconds=0,
+            ))
+    except Exception as e:
+        raise ModelRuntimeError(status_code=500, detail=f"{repo_id} 다운로드 실패: {str(e)[-2000:]}")
+
+    if not hf_model_ready(repo_id, provider):
+        raise ModelRuntimeError(status_code=500, detail=f"{repo_id} 다운로드가 완료되지 않았습니다. 모델 파일을 찾지 못했습니다.")
+
+    return {"model": repo_id, "path": str(target_dir), "cached": False}