microsoft / microsoft/winml-cli

Document how to use sideloaded execution providers

Open
#1,363 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Python
Stars
40
Forks
11
Avg merge
1d 8h
Merged PRs (30d)
50

Description

Description

Sideloaded execution provider support added through #1019 is not documented in the user-facing WinML CLI docs. The current docs do not explain WINMLCLI_EP_PATH, the --ep <name>@directory source qualifier, source precedence, or how to verify which plugin DLL was selected.

Users therefore have to infer the workflow from implementation details and PR discussion.

Steps to Reproduce

  1. Search the WinML CLI documentation for WINMLCLI_EP_PATH, @directory, or "sideloaded EP".
  2. Try to determine how to run winml perf with an EP plugin DLL from a custom build or unpacked package.
  3. No user-facing instructions or end-to-end example are available.

Expected Behavior

The documentation should describe how to point WinML CLI at one or more EP directories and explicitly select the directory-discovered provider.

$env:WINMLCLI_EP_PATH = "C:\path\to\ep\bin"
winml sys --list-ep
winml perf -m "C:\path\to\model.onnx" --ep qnn@directory --device npu

It should also include an OpenVINO example:

$env:WINMLCLI_EP_PATH = "C:\path\to\openvino\build\Release"
winml perf -m "C:\path\to\model.onnx" --ep openvino@directory --device npu

Actual Behavior

The feature works, but its public usage contract is absent from the documentation.

Acceptance Criteria

  • Document that WINMLCLI_EP_PATH accepts directories, not individual DLL paths.
  • Document the Windows path-list separator (;) and multiple-directory behavior.
  • Explain --ep <alias>@directory and how it differs from unqualified --ep <alias>.
  • Document discovery/source precedence and shadowed EP behavior.
  • Show winml sys --list-ep verification, including source, status, and selected DLL path.
  • Add runnable QNN and OpenVINO winml perf examples.
  • Document which commands support source-qualified EP selection and any commands that reject it.
  • Include troubleshooting for nonexistent directories, missing expected provider DLL names, architecture mismatch, registration failures, and native dependencies located beside the plugin DLL.
  • Link the new guidance from the perf, compile, sys, and EP/device documentation where applicable.

Environment

  • OS: Windows
  • WinML CLI: current main

Additional Context

Related implementation: #1019, "EP registration + monitoring — subprocess isolation, structured failures, universal op-tracing dispatch, lazy CLI startup."

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.

Research direction

Start with the existing user-facing WinML CLI documentation and the implementation context in PR #1019, then trace the winml sys, perf, and compile command entry points for source-qualified provider behavior. Done means the docs cover the listed acceptance criteria, including QNN and OpenVINO examples, discovery precedence, verification output, supported commands, troubleshooting, and links from related EP/device guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell, python
Domain
cli, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.