[EP ABI] Add API to select the best compiled model compatibility info from candidate strings

[chilo-ms]

Description

This PR adds a new EP API, SelectBestModelCandidate, that selects the best model variant from a set of candidates described by key-value metadata.

The EP evaluates each candidate's metadata against the given hardware device and optional session options, and returns the index of the best match.

Key design points:

• Each candidate is an OrtKeyValuePairs representing one model variant. This future-proofs the API — additional metadata keys can be added over time without changing the function signature.

• Single-model variants (simple case): The KVP contains a single ep_compatibility_info key with the compatibility string from the ONNX model metadata.

• Multi-model variants: When a variant bundles multiple sub-models (e.g., prefill + decode in a GenAI scenario), the KVP uses indexed keys so the EP can inspect each sub-model independently:

  • num_models — number of sub-models (e.g., "3")
  • <i>.ep_compatibility_info — compatibility string for sub-model i (required per sub-model)
  • <i>.role — role of sub-model i, e.g., "prefill", "decode" (optional)
  • <i>.future_meaningful_info — additional EP-meaningful metadata for sub-model i (optional)

  A basic EP implementation validates all <i>.ep_compatibility_info entries. An advanced implementation can also consider role or other metadata for smarter ranking.

• This approach delegates variant selection entirely to the EP, which has the domain knowledge to handle structurally mismatched variants (different sub-model counts, different roles, etc.) without ORT needing to understand model roles or compute aggregated scores.

Motivation and Context

The existing ValidateCompiledModelCompatibilityInfo() alone is not sufficient for some EPs to determine the best compatible model when there are multiple candidates. For example, an EP may support multiple compilation modes (e.g., "speed optimized" vs "memory optimized") that produce different compatibility strings. The EP can implement this function to evaluate the candidate metadata and select the best compatible variant based on its own criteria and the target device.

[javier-intel]

Here's my feedback:

• Unclear why the need for KV pairs when all keys are all required to be the same, an array of strings would work just as well
• Per the example, choosing speed or memory optimized cache will depend on the app runtime decision, otherwise the choice is made a cache build time and not an issue at cache selection on the target. It seems SelectBestModelCandidate should take a list of session options to consider or null it not
• What should the behavior be when num_devices > 1, optimal entry is device specific and therefore so is the selected_index

[chilo-ms]

• Unclear why the need for KV pairs when all keys are all required to be the same, an array of strings would work just as well

I'm thinking whether in the future different cached models store different EP-defined metadata keys. For example, one model variant might include optimization_level: "speed" while another includes precision: "fp16", and the EP needs to inspect these varying per-model metadata entries to make its selection decision.

That said, ep_compatibility_info is the only required key for now.

• Per the example, choosing speed or memory optimized cache will depend on the app runtime decision, otherwise the choice is made a cache build time and not an issue at cache selection on the target. It seems SelectBestModelCandidate should take a list of session options to consider or null it not

That makes sense and i added session options to the API.

• What should the behavior be when num_devices > 1, optimal entry is device specific and therefore so is the selected_index

Made API take only one device and return one selected_index.

[javier-intel]

Hey @chilo-ms thanks for the responses. I'm ok with "ep_compatibility_info" being the only key at the moment. Regarding num_devices I now understand a bit better how ORT API is dealing with multiple HW devices and how the Validate and this Select function will behave with more than one device. While it's fine to have more than one device it's important to mention in the documentation block that the list of devices passed in device must be the same devices used to generate the strings.

[skottmckay]

• Unclear why the need for KV pairs when all keys are all required to be the same, an array of strings would work just as well

@javier-intel API can't be changed so KV pairs future-proofs things and allows richer information to be passed in when needed. we have had a few places where we've regretted not having this option available.