microsoft / microsoft/winml-cli
[cross-cutting] Unify cache-control flags (--rebuild / --use-cache / --cache-dir) across build, perf, eval
@vortex-captain is already working on this.
Since Jul 27, 2026.
- 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
- Opposite spelling for the same concept —
build --no-use-cachevsperf --ignore-cacheboth setuse_cache=False. - Opposite defaults —
builddefaults to no-cache;perf/evaldefault to cache-on. Same library, different command behavior. evalhas no cache control at all — a stale cached model is silently reused with no--rebuildto force a fresh build, and no opt-out.--cache-diris never exposed — users can't relocate or pin the cache from the CLI even though the library supports it.--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-cacheor--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-omode deliberately bypasses cache — need to preserve that (--cache/-omutual exclusion, or-oimplies--no-cache). - Canonical opt-out spelling:
--no-cachevs--no-use-cachevs keep--ignore-cache. Recommend--cache/--no-cache(shortest, clearest). - Back-compat: keep
perf --ignore-cacheandbuild --use-cacheas hidden deprecated aliases during a transition. - Scope: include
run/servenow 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.