microsoft · vortex-captain · May 9, 2026 · May 9, 2026 · May 11, 2026 · May 11, 2026
@@ -134,6 +134,15 @@ def _delete_onnx_with_external_data(onnx_path: Path) -> None:
     default=None,
     help='JSON with shape overrides (e.g., {"sequence_length": 2048, "height": 640}).',
 )
+@click.option(
+    "--loader-config-overrides",
+    "loader_config_overrides_path",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help="JSON file with overrides patched recursively onto the loaded HF "
+    'config (e.g., {"scale": 2} for Real-ESRGAN). Deep-merges with any '
+    "loader.loader_config_overrides set in --config; CLI keys win.",
+)
 @cli_utils.build_config_option
 @click.pass_context
 def export(
@@ -149,6 +158,7 @@ def export(
     input_specs: Path | None,
     export_config: Path | None,
     shape_config: Path | None,
+    loader_config_overrides_path: Path | None,
     config_file: Path | None,
 ) -> None:
     r"""Export HuggingFace model to ONNX format with HTP.
@@ -198,17 +208,50 @@ def export(
 
     # Apply build config defaults (CLI explicit options take precedence)
     _build_export_cfg = None
+    loader_config_overrides: dict | None = None
     if config_file is not None:
         build_cfg = cli_utils.load_build_config(config_file)
         if build_cfg.export:
             _build_export_cfg = build_cfg.export
         if build_cfg.loader and not cli_utils.is_cli_provided(ctx, "task"):
             task = build_cfg.loader.task
+        if build_cfg.loader and build_cfg.loader.loader_config_overrides:
+            loader_config_overrides = dict(build_cfg.loader.loader_config_overrides)
         if _build_export_cfg and not cli_utils.is_cli_provided(ctx, "no_hierarchy"):
             no_hierarchy = not _build_export_cfg.enable_hierarchy_tags
         if _build_export_cfg and not cli_utils.is_cli_provided(ctx, "dynamo"):
             dynamo = _build_export_cfg.dynamo
 
+    # Sidecar --loader-config-overrides JSON deep-merges on top of any value
+    # carried by --config. CLI keys win on conflicts.
+    if loader_config_overrides_path is not None:
+        try:
+            cli_overrides = json.loads(loader_config_overrides_path.read_text())
+        except json.JSONDecodeError as e:
+            raise click.ClickException(
+                f"Invalid JSON in --loader-config-overrides "
+                f"{loader_config_overrides_path}: {e}"
+            ) from e
+        if not isinstance(cli_overrides, dict):
+            raise click.ClickException(
+                f"--loader-config-overrides must contain a JSON object, "
+                f"got {type(cli_overrides).__name__}"
+            )
+
+        def _deep_merge(base: dict, top: dict) -> dict:
+            out = dict(base)
+            for k, v in top.items():
+                if isinstance(v, dict) and isinstance(out.get(k), dict):
+                    out[k] = _deep_merge(out[k], v)
+                else:
+                    out[k] = v
+            return out
+
+        loader_config_overrides = _deep_merge(loader_config_overrides or {}, cli_overrides)
+        console.print(
+            f"[dim]Loader config overrides: {loader_config_overrides}[/dim]"
+        )
+
     from ..export import InputTensorSpec, OutputTensorSpec, WinMLExportConfig
     from ..export import export_pytorch as export_onnx
     from ..loader import load_hf_model
@@ -362,7 +405,11 @@ def export(
         console.print("\n[bold]Starting HTP export...[/bold]")
 
         # Load model with task detection (CLI is the orchestration layer)
-        pytorch_model, _, detected_task = load_hf_model(model, task=task)
+        pytorch_model, _, detected_task = load_hf_model(
+            model,
+            task=task,
+            loader_config_overrides=loader_config_overrides,
+        )
         if task:
             console.print(f"[dim]Task (override): {detected_task}[/dim]")
         else:

@@ -183,6 +183,9 @@ def _load_model(config: WinMLEvaluationConfig) -> WinMLPreTrainedModel:
         # ignored here (mirrors winml perf's ONNX path).
         from transformers import AutoConfig
 
+        from ..export.io import ensure_hf_models_registered
+
+        ensure_hf_models_registered()
         hf_config = AutoConfig.from_pretrained(config.model_id)
         model = WinMLAutoModel.from_onnx(
             onnx_path=config.model_path,
@@ -214,10 +217,12 @@ def _resolve_task(config: WinMLEvaluationConfig) -> str:
 
     from transformers import AutoConfig
 
-    from ..loader.task import _detect_task_from_config
+    from ..export.io import ensure_hf_models_registered
+    from ..loader.task import _detect_task_and_class_from_config
 
+    ensure_hf_models_registered()
     hf_config = AutoConfig.from_pretrained(config.model_id)
-    return _detect_task_from_config(hf_config)
+    return _detect_task_and_class_from_config(hf_config)[0]
 
 
 def evaluate(config: WinMLEvaluationConfig) -> EvalResult:

@@ -45,6 +45,12 @@ class WinMLLoaderConfig:
             Requires trust_remote_code=True for security.
         trust_remote_code: Whether to trust remote/custom code.
             Required when using user_script.
+        loader_config_overrides: Optional patch applied recursively to the HF
+            config object after ``AutoConfig.from_pretrained``. Keys are
+            attribute names; nested dicts are merged into sub-configs (e.g.
+            ``{"vision_config": {"image_size": 320}}``). Use cases include
+            selecting a non-default hyperparameter (``{"scale": 2}`` for
+            Real-ESRGAN) without committing a separate ``config.json``.
 
     Example:
         # Standard usage with auto-detection
@@ -71,6 +77,7 @@ class WinMLLoaderConfig:
     module_path: str | None = None
     user_script: str | None = None
     trust_remote_code: bool = False
+    loader_config_overrides: dict[str, Any] | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """Serialize to dictionary.
@@ -91,6 +98,8 @@ def to_dict(self) -> dict[str, Any]:
             result["user_script"] = self.user_script
         if self.trust_remote_code:
             result["trust_remote_code"] = self.trust_remote_code
+        if self.loader_config_overrides:
+            result["loader_config_overrides"] = self.loader_config_overrides
         return result
 
     @classmethod
@@ -110,9 +119,69 @@ def from_dict(cls, data: dict[str, Any]) -> WinMLLoaderConfig:
             module_path=data.get("module_path"),
             user_script=data.get("user_script"),
             trust_remote_code=data.get("trust_remote_code", False),
+            loader_config_overrides=data.get("loader_config_overrides"),
         )
 
 
+def _deep_merge_dicts(base: dict, top: dict) -> dict:
+    """Return a new dict deep-merging ``top`` on top of ``base``.
+
+    Nested dicts on both sides are merged recursively; otherwise ``top``'s
+    value wins. ``base`` is not mutated.
+    """
+    out = dict(base)
+    for key, value in top.items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _deep_merge_dicts(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def apply_loader_config_overrides(
+    hf_config: PretrainedConfig,
+    overrides: dict[str, Any] | None,
+) -> PretrainedConfig:
+    """Return a new HF config with ``overrides`` deep-merged onto ``hf_config``.
+
+    Serializes the original config via :meth:`PretrainedConfig.to_dict`,
+    recursively deep-merges ``overrides`` into the resulting plain dict
+    (``overrides`` keys win on conflict, nested dicts merge into nested
+    dicts), then reconstructs the config via
+    ``type(hf_config).from_dict(merged)``.
+
+    Going through ``to_dict`` / ``from_dict`` lets the config class's own
+    constructor handle validation, defaulting, and sub-config reconstruction
+    — including nested :class:`PretrainedConfig` fields like
+    ``CLIPConfig.vision_config`` (HF's ``from_dict`` rebuilds them from
+    nested dicts automatically). A raw ``setattr`` loop, by contrast, can
+    silently create attributes the model class never reads when the
+    override key is missing on the original config.
+
+    Empty / ``None`` overrides return the original config unchanged.
+
+    Args:
+        hf_config: The HF :class:`PretrainedConfig` to patch.
+        overrides: Nested dict of overrides, or ``None``.
+
+    Returns:
+        A :class:`PretrainedConfig` of the same concrete type as
+        ``hf_config`` with the overrides applied. May be the original
+        instance (when overrides are empty) or a freshly constructed one.
+    """
+    if not overrides:
+        return hf_config
+
+    merged = _deep_merge_dicts(hf_config.to_dict(), overrides)
+    new_config = type(hf_config).from_dict(merged)
+    logger.debug(
+        "Applied loader_config_overrides to %s: %s",
+        type(hf_config).__name__,
+        overrides,
+    )
+    return new_config
+
+
 def resolve_loader_config(
     model_id: str | None = None,
     *,
@@ -121,6 +190,7 @@ def resolve_loader_config(
     model_type: str | None = None,
     trust_remote_code: bool = False,
     library_name: str = "transformers",
+    loader_config_overrides: dict[str, Any] | None = None,
 ) -> tuple[WinMLLoaderConfig, PretrainedConfig, type]:
     """Resolve all loader concerns from raw user inputs.
 
@@ -154,6 +224,11 @@ def resolve_loader_config(
             When provided without task, the first supported task is used.
         trust_remote_code: Whether to trust remote/custom code.
         library_name: Source library for TasksManager lookup.
+        loader_config_overrides: Optional nested dict patched recursively onto
+            the HF config after it is loaded — see
+            :func:`apply_loader_config_overrides`. Stored on the returned
+            :class:`WinMLLoaderConfig` so downstream
+            ``resolved_class.from_pretrained`` consumers can re-apply it.
 
     Returns:
         Tuple of:
@@ -169,8 +244,13 @@ def resolve_loader_config(
     """
     from transformers import AutoConfig
 
+    from ..export.io import ensure_hf_models_registered
     from .task import get_supported_tasks, resolve_task_and_model_class
 
+    # Ensure HF model registrations (AutoConfig.register, OnnxConfig overwrites,
+    # task-mapping fallbacks) have run before any AutoConfig / TasksManager calls.
+    ensure_hf_models_registered()
+
     # 1. Load hf_config (depends on: model_id, model_type, or model_class)
     if model_id is not None:
         hf_config = AutoConfig.from_pretrained(
@@ -206,6 +286,10 @@ def resolve_loader_config(
             f"attribute. Cannot proceed with config generation."
         )
 
+    # 1a. Apply caller-supplied overrides — returns a new config when overrides
+    # are non-empty so the config class's own __init__ / from_dict validates.
+    hf_config = apply_loader_config_overrides(hf_config, loader_config_overrides)
+
     # 2. Infer task (depends on: model_type param or hf_config.architectures)
     if task is None and model_type is not None:
         supported = get_supported_tasks(model_type, library_name=library_name)
@@ -241,6 +325,7 @@ def resolve_loader_config(
         model_class=resolved_class.__name__,
         model_type=resolved_model_type,
         trust_remote_code=trust_remote_code,
+        loader_config_overrides=loader_config_overrides or None,
     )
 
     return loader_config, resolved_hf_config, resolved_class
@@ -313,4 +398,8 @@ def _resolve_hf_config_for_class(
     return hf_config, hf_config.model_type
 
 
-__all__ = ["WinMLLoaderConfig", "resolve_loader_config"]
+__all__ = [
+    "WinMLLoaderConfig",
+    "apply_loader_config_overrides",
+    "resolve_loader_config",
+]
@@ -145,6 +145,7 @@ def load_hf_model(
     model_class: str | None = None,
     user_script: str | None = None,
     trust_remote_code: bool = False,
+    loader_config_overrides: dict | None = None,
 ) -> tuple[nn.Module, PretrainedConfig, str]:
     """Load, detect task, and prepare HuggingFace model.
 
@@ -194,6 +195,12 @@ def load_hf_model(
     """
     logger.info("Loading HF model: %s", model_name_or_path)
 
+    # Ensure HF model registrations (AutoConfig.register, OnnxConfig overwrites,
+    # task-mapping fallbacks) have run before any AutoConfig / TasksManager calls.
+    from ..export.io import ensure_hf_models_registered
+
+    ensure_hf_models_registered()
+
     # Validate user_script requirements before any network calls
     if user_script is not None:
         if not trust_remote_code:
@@ -210,6 +217,15 @@ def load_hf_model(
         trust_remote_code=trust_remote_code,
     )
 
+    # [1a] Apply optional ``loader_config_overrides`` (e.g. ESRGAN ``scale``)
+    # before task resolution so downstream lookups see the patched values.
+    # ``apply_loader_config_overrides`` returns a new config instance built via
+    # ``from_dict`` so the class constructor validates / reconstructs.
+    if loader_config_overrides:
+        from .config import apply_loader_config_overrides
+
+        hf_config = apply_loader_config_overrides(hf_config, loader_config_overrides)
+
     # [2] Task & Model Class Resolution
     if user_script is not None:
         resolved_class = _load_class_from_script(user_script, model_class)
@@ -230,11 +246,18 @@ def load_hf_model(
                 f"Cannot resolve task/model for {model_name_or_path}. Original error: {e}"
             ) from e
 
-    # [4] Model Instantiation
+    # [4] Model Instantiation. When overrides were applied, pass the patched
+    # ``hf_config`` as ``config=`` so the model class uses it instead of
+    # re-loading from disk/Hub and losing the patches.
     logger.debug("Loading model with class: %s", resolved_class.__name__)
+    from_pretrained_kwargs: dict = {
+        "trust_remote_code": trust_remote_code,
+    }
+    if loader_config_overrides:
+        from_pretrained_kwargs["config"] = hf_config
     model = resolved_class.from_pretrained(
         model_name_or_path,
-        trust_remote_code=trust_remote_code,
+        **from_pretrained_kwargs,
     )
 
     # [5] Export Preparation