From ff1c0ba7cf8a3492cc4a046040ff3eea436dc397 Mon Sep 17 00:00:00 2001 From: "Shiyi Zheng (from Dev Box)" Date: Tue, 2 Jun 2026 20:59:34 +0800 Subject: [PATCH 1/3] docs(intelligentapps): add Windows ML CLI build flow section to modelconversion --- .../modelconversion/winmlcli-build-flow.png | 3 + .../modelconversion/winmlcli-history.png | 3 + .../modelconversion/winmlcli-local-onnx.png | 3 + .../modelconversion/winmlcli-model-list.png | 3 + .../winmlcli-recommend-process.png | 3 + docs/intelligentapps/modelconversion.md | 60 +++++++++++++++++++ 6 files changed, 75 insertions(+) create mode 100644 docs/intelligentapps/images/modelconversion/winmlcli-build-flow.png create mode 100644 docs/intelligentapps/images/modelconversion/winmlcli-history.png create mode 100644 docs/intelligentapps/images/modelconversion/winmlcli-local-onnx.png create mode 100644 docs/intelligentapps/images/modelconversion/winmlcli-model-list.png create mode 100644 docs/intelligentapps/images/modelconversion/winmlcli-recommend-process.png diff --git a/docs/intelligentapps/images/modelconversion/winmlcli-build-flow.png b/docs/intelligentapps/images/modelconversion/winmlcli-build-flow.png new file mode 100644 index 00000000000..bb1cd19f485 --- /dev/null +++ b/docs/intelligentapps/images/modelconversion/winmlcli-build-flow.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8e7ac9bc345172b8dea3b29acaa303e7c9a2cee1e7047b1132dbe621d2b61147 +size 61677 diff --git a/docs/intelligentapps/images/modelconversion/winmlcli-history.png b/docs/intelligentapps/images/modelconversion/winmlcli-history.png new file mode 100644 index 00000000000..fe9e7b7217e --- /dev/null +++ b/docs/intelligentapps/images/modelconversion/winmlcli-history.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5af729d8f4f6d14fa32164b83a05a538634fb815ac4925564ac03a7acf014901 +size 30174 diff --git a/docs/intelligentapps/images/modelconversion/winmlcli-local-onnx.png b/docs/intelligentapps/images/modelconversion/winmlcli-local-onnx.png new file mode 100644 index 00000000000..d107476863d --- /dev/null +++ b/docs/intelligentapps/images/modelconversion/winmlcli-local-onnx.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e9d55033abff6dd96534bbf5014e8e83d0bd4812a39d3999178581387e0106e7 +size 67853 diff --git a/docs/intelligentapps/images/modelconversion/winmlcli-model-list.png b/docs/intelligentapps/images/modelconversion/winmlcli-model-list.png new file mode 100644 index 00000000000..265ec6d0f5c --- /dev/null +++ b/docs/intelligentapps/images/modelconversion/winmlcli-model-list.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9b9f67139730caf132f974218f5355e60fe95c45e0a510e097000baaa84fff46 +size 87884 diff --git a/docs/intelligentapps/images/modelconversion/winmlcli-recommend-process.png b/docs/intelligentapps/images/modelconversion/winmlcli-recommend-process.png new file mode 100644 index 00000000000..950c6b8c2da --- /dev/null +++ b/docs/intelligentapps/images/modelconversion/winmlcli-recommend-process.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1176d7512df063498903a9fe57b65be73ed16f17a7bacb165bac64e4003dc602 +size 46114 diff --git a/docs/intelligentapps/modelconversion.md b/docs/intelligentapps/modelconversion.md index f511eb2c171..5f7bd764092 100644 --- a/docs/intelligentapps/modelconversion.md +++ b/docs/intelligentapps/modelconversion.md @@ -250,6 +250,65 @@ The default runtime is: `C:\Users\{user_name}\.aitk\bin\model_lab_runtime\Python Go to the History board. Select **Export** to share the model project with others. This copies the model project without history folder. If you want to share models with others, select the corresponding jobs. This copies the selected history folder containing the model and its configuration. +## Build with Windows ML CLI (preview) + +In addition to the Olive-based conversion workflow, Foundry Toolkit also provides a streamlined **Build** flow powered by [Windows ML CLI](https://learn.microsoft.com/en-us/windows/ai/new-windows-ml/overview). It analyzes your model, downloads the matching execution providers (EPs) for the local device, and produces optimized ONNX artifacts with minimal configuration. + +Use Windows ML CLI when you want to: + +- Quickly bring a Hugging Face model or an existing local ONNX file onto Windows. +- Let the toolkit pick the right EPs and optimization recipe for the current hardware. +- Iterate on **Build**, **Evaluation**, and **Performance** runs from a single panel. + +### Choose a Windows ML CLI base model + +When you create a new model project (or add a model to an existing one), the **Choose a Base Model** page exposes a **Recommend Process** area powered by Windows ML CLI: + +![Screenshot that shows the Recommend Process area with Hugging Face Hub and Local ONNX Files cards.](./images/modelconversion/winmlcli-recommend-process.png) + +- **Hugging Face Hub**: enter any Hugging Face model ID and let Windows ML CLI download, analyze, and build the model. +- **Local ONNX Files**: browse to an ONNX file on disk and let Windows ML CLI analyze and optimize it. + +You can also pick a curated Hugging Face model that is already validated for Windows ML CLI. Open the **Provided By** filter and select **Windows ML CLI** to see the supported list. + +![Screenshot that shows HuggingFace Models filtered by the Windows ML CLI provider.](./images/modelconversion/winmlcli-model-list.png) + +### Run the Build flow + +After the project opens, the **Run Workflows** panel shows a **Build Flow** card for each selected Windows ML CLI model. + +![Screenshot that shows the Build Flow card with Edit Config and Build buttons for a Hugging Face model.](./images/modelconversion/winmlcli-build-flow.png) + +For Hugging Face models, the toolkit automatically downloads the model and starts an initial configuration pass. The card transitions through three states: + +- **Configuring**: the model is being downloaded and analyzed. +- **Configured**: a configuration is ready. Select **Edit Config** to review or tweak the generated recipe per precision (for example `fp16`, `w8a8`, `w8a16`), then select **Build** to produce the optimized model. +- **Failed**: configuration could not be completed. The card shows the failure inline and exposes a **Re-config** button (placed to the left of **Edit Config**) so you can retry without leaving the workflow. + +> [!NOTE] +> Configuration only runs automatically on first entry, or after you explicitly select **Re-config**. The toolkit does not retry a failed configuration on its own, so you can inspect the log and decide when to try again. + +For Local ONNX models, no download is required. Select **Build** directly to let Windows ML CLI analyze the file and report EP compatibility. + +![Screenshot that shows the Build Flow card for a local ONNX model with just a Build button.](./images/modelconversion/winmlcli-local-onnx.png) + +### Inspect Build, Evaluation, and Performance results + +Each Build run produces an entry in the **Generated Flow History** table. From there you can: + +- Select **View Config** to open the configuration file used for the run. +- Select **View Analysis** to open the EP compatibility analysis. +- Select **Performance** to launch a performance run against a chosen EP. +- Select **logs** next to the status to open the raw Windows ML CLI log. +- Select **Export** to copy the artifact, or **Delete** to remove it. + +![Screenshot that shows the Generated Flow History table with View Config, View Analysis, Performance, Export, and Delete actions.](./images/modelconversion/winmlcli-history.png) + +Performance results (device, latency, throughput) are shown directly in the table so you can compare runs at a glance. + +> [!TIP] +> If a Build, Evaluation, or Performance run fails, the log shows a `Run WinMLCLI error with code !` message. Open the linked log file to view the underlying Windows ML CLI output. + ## What you learned In this article, you learned how to: @@ -263,6 +322,7 @@ In this article, you learned how to: - Re-evaluate a model using different execution providers or datasets. - Handle failed jobs and adjust configurations for re-runs. - Understand the supported models and their requirements for conversion and quantization. +- Build a Hugging Face or local ONNX model with the Windows ML CLI flow. ## See also From 4599414bdebbd4953539ebbac1b23b1b64ce2b90 Mon Sep 17 00:00:00 2001 From: "Shiyi Zheng (from Dev Box)" Date: Tue, 2 Jun 2026 22:36:36 +0800 Subject: [PATCH 2/3] docs(intelligentapps): refine WinML CLI section (built-in models, eval, history image) --- .../modelconversion/winmlcli-history.png | 4 ++-- docs/intelligentapps/modelconversion.md | 24 ++++++++----------- 2 files changed, 12 insertions(+), 16 deletions(-) diff --git a/docs/intelligentapps/images/modelconversion/winmlcli-history.png b/docs/intelligentapps/images/modelconversion/winmlcli-history.png index fe9e7b7217e..e48c75c18ec 100644 --- a/docs/intelligentapps/images/modelconversion/winmlcli-history.png +++ b/docs/intelligentapps/images/modelconversion/winmlcli-history.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:5af729d8f4f6d14fa32164b83a05a538634fb815ac4925564ac03a7acf014901 -size 30174 +oid sha256:f103c03b4675ea1c8352cd119e196206ab7bfb3300e78ea3241616bd6ed342d2 +size 38163 diff --git a/docs/intelligentapps/modelconversion.md b/docs/intelligentapps/modelconversion.md index 5f7bd764092..0dec596d096 100644 --- a/docs/intelligentapps/modelconversion.md +++ b/docs/intelligentapps/modelconversion.md @@ -279,14 +279,16 @@ After the project opens, the **Run Workflows** panel shows a **Build Flow** card ![Screenshot that shows the Build Flow card with Edit Config and Build buttons for a Hugging Face model.](./images/modelconversion/winmlcli-build-flow.png) -For Hugging Face models, the toolkit automatically downloads the model and starts an initial configuration pass. The card transitions through three states: +The behavior on first entry depends on how the model was added to the project: -- **Configuring**: the model is being downloaded and analyzed. -- **Configured**: a configuration is ready. Select **Edit Config** to review or tweak the generated recipe per precision (for example `fp16`, `w8a8`, `w8a16`), then select **Build** to produce the optimized model. -- **Failed**: configuration could not be completed. The card shows the failure inline and exposes a **Re-config** button (placed to the left of **Edit Config**) so you can retry without leaving the workflow. +- **Built-in models** (the curated entries that already have a model card) ship with a prepared configuration. The Build Flow card opens directly in the **Configured** state — no auto-configuration runs. Select **Edit Config** to review the prepared recipe, then select **Build**. +- **Hugging Face models added by ID** are downloaded and analyzed automatically on first entry. The card transitions through these states: + - **Configuring**: the model is being downloaded and analyzed. + - **Configured**: a configuration is ready. Select **Edit Config** to review or tweak the generated recipe per precision (for example `fp16`, `w8a8`, `w8a16`), then select **Build** to produce the optimized model. + - **Failed**: configuration could not be completed. The card shows the failure inline and exposes a **Re-config** button (placed to the left of **Edit Config**) so you can retry without leaving the workflow. > [!NOTE] -> Configuration only runs automatically on first entry, or after you explicitly select **Re-config**. The toolkit does not retry a failed configuration on its own, so you can inspect the log and decide when to try again. +> Auto-configuration only runs on first entry for Hugging Face models added by ID, or after you explicitly select **Re-config**. The toolkit does not retry a failed configuration on its own, so you can inspect the log and decide when to try again. For Local ONNX models, no download is required. Select **Build** directly to let Windows ML CLI analyze the file and report EP compatibility. @@ -298,16 +300,10 @@ Each Build run produces an entry in the **Generated Flow History** table. From t - Select **View Config** to open the configuration file used for the run. - Select **View Analysis** to open the EP compatibility analysis. -- Select **Performance** to launch a performance run against a chosen EP. -- Select **logs** next to the status to open the raw Windows ML CLI log. -- Select **Export** to copy the artifact, or **Delete** to remove it. +- Select **Performance** to launch a performance run against a chosen EP and view device, latency, and throughput results directly in the table. +- Select **Evaluation** to run a quality evaluation. Evaluation is only available for **built-in models**, which ship with a prepared evaluation dataset and metrics. -![Screenshot that shows the Generated Flow History table with View Config, View Analysis, Performance, Export, and Delete actions.](./images/modelconversion/winmlcli-history.png) - -Performance results (device, latency, throughput) are shown directly in the table so you can compare runs at a glance. - -> [!TIP] -> If a Build, Evaluation, or Performance run fails, the log shows a `Run WinMLCLI error with code !` message. Open the linked log file to view the underlying Windows ML CLI output. +![Screenshot that shows the Generated Flow History table with View Config, View Analysis, Performance, and Evaluation actions.](./images/modelconversion/winmlcli-history.png) ## What you learned From 04fcf9d6d5f7c959e7fea77ab09d60109a3be265 Mon Sep 17 00:00:00 2001 From: "Shiyi Zheng (from Dev Box)" Date: Tue, 2 Jun 2026 22:52:50 +0800 Subject: [PATCH 3/3] docs(intelligentapps): fix WinML CLI link --- docs/intelligentapps/modelconversion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intelligentapps/modelconversion.md b/docs/intelligentapps/modelconversion.md index 0dec596d096..24af82886ff 100644 --- a/docs/intelligentapps/modelconversion.md +++ b/docs/intelligentapps/modelconversion.md @@ -252,7 +252,7 @@ Go to the History board. Select **Export** to share the model project with other ## Build with Windows ML CLI (preview) -In addition to the Olive-based conversion workflow, Foundry Toolkit also provides a streamlined **Build** flow powered by [Windows ML CLI](https://learn.microsoft.com/en-us/windows/ai/new-windows-ml/overview). It analyzes your model, downloads the matching execution providers (EPs) for the local device, and produces optimized ONNX artifacts with minimal configuration. +In addition to the Olive-based conversion workflow, Foundry Toolkit also provides a streamlined **Build** flow powered by [Windows ML CLI](https://github.com/microsoft/winml-cli). It analyzes your model, downloads the matching execution providers (EPs) for the local device, and produces optimized ONNX artifacts with minimal configuration. Use Windows ML CLI when you want to: