Skip to content

Document how to use sideloaded execution providers #1363

Description

@hi-brenda

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."

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions