microsoft / microsoft/winml-cli

[cross-cutting] Unify cache-control flags (--rebuild / --use-cache / --cache-dir) across build, perf, eval

Open
#972 3 comments 0 reactions 2 assignees View on GitHub

@vortex-captain is already working on this.

Since Jul 27, 2026.

dev experience enhancement P2 question refactor triaged
Dominant language
Python
Stars
40
Forks
11
Avg merge
1d 8h
Merged PRs (30d)
50

Description

Summary

Commands that build a model from HF (build, perf, eval, and future model-loaders like run/serve) all flow through WinMLAutoModel.from_pretrained / from_onnx, which share the same cache kwargs:

cache_dir: str | Path | None = None
use_cache: bool = True
force_rebuild: bool = False

But each command exposes (or hides) these inconsistently — different flag names, different defaults, and eval exposes nothing. We should unify them behind a shared decorator in utils/cli.py (the same pattern already used for build_pipeline_extra_kwargs() and overwrite_option()).

Current state

Command Cache opt-in/out Force recompute cache-dir Default
build --use-cache/--no-use-cache (mutually exclusive with -o) --rebuild/--no-rebuild — (uses internal get_cache_dir()) cache off by default
perf --ignore-cache/--no-ignore-cache --rebuild/--no-rebuild cache on by default
eval — (none) — (none) cache on (library default), no way to override
library default use_cache=True force_rebuild=False cache_dir=None cache on

Problems

  1. Opposite spelling for the same conceptbuild --no-use-cache vs perf --ignore-cache both set use_cache=False.
  2. Opposite defaultsbuild defaults to no-cache; perf/eval default to cache-on. Same library, different command behavior.
  3. eval has no cache control at all — a stale cached model is silently reused with no --rebuild to force a fresh build, and no opt-out.
  4. --cache-dir is never exposed — users can't relocate or pin the cache from the CLI even though the library supports it.
  5. --rebuild (force_rebuild) is on build/perf but not eval.

Proposal

Add a shared cache-flags decorator (e.g. cache_options()) + a mapping helper (e.g. cache_extra_kwargs()) in utils/cli.py, analogous to build_pipeline_extra_kwargs(), and wire it into build, perf, eval so they share:

  • --rebuild/--no-rebuild -> force_rebuild
  • a single consistent cache opt-out spelling (pick one: --cache/--no-cache or --use-cache/--no-use-cache) -> use_cache
  • --cache-dir PATH -> cache_dir

…with one consistent default across commands.

Open questions (need a decision)

  • Default: cache on (perf/eval today, matches library) or off (build today)? Leaning cache-on for consistency with the library, but build's -o mode deliberately bypasses cache — need to preserve that (--cache/-o mutual exclusion, or -o implies --no-cache).
  • Canonical opt-out spelling: --no-cache vs --no-use-cache vs keep --ignore-cache. Recommend --cache/--no-cache (shortest, clearest).
  • Back-compat: keep perf --ignore-cache and build --use-cache as hidden deprecated aliases during a transition.
  • Scope: include run/serve now or follow up?

Out of scope

This is the cache-control axis only. It is orthogonal to --overwrite/--no-overwrite (#970, which guards one-shot output files like the eval/perf JSON report — a different artifact from the model cache). The two never refer to the same thing, so --rebuild (cache) and --overwrite (output) correctly coexist (e.g. in perf).

Related: #561, #970

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.