使用插件执行提供程序库

本页提供关于如何结合 ONNX Runtime API 使用插件 EP 库的参考。

此页面上的代码为 C++，并使用了 ONNX Runtime C++ API。

这里也有一些其他语言的使用示例

内容

插件 EP 库注册
使用显式 OrtEpDevice 创建会话
使用自动 EP 选择创建会话
API 参考

插件 EP 库注册

以下示例应用程序代码使用以下 API 函数来注册和注销插件 EP 库。

const char* lib_registration_name = "ep_lib_name";
Ort::Env env;

// Register plugin EP library with ONNX Runtime.
env.RegisterExecutionProviderLibrary(
  lib_registration_name,   // Registration name can be anything the application chooses.
  ORT_TSTR("ep_path.dll")  // Path to the plugin EP library.
);

{
  Ort::Session session(env, /*...*/);
  // Run a model ...
}

// Unregister the library using the application-specified registration name.
// Must only unregister a library after all sessions that use the library have been released.
env.UnregisterExecutionProviderLibrary(lib_registration_name);

如以下时序图所示，注册插件 EP 库会促使 ONNX Runtime 加载该库并调用库的 CreateEpFactories() 函数。在调用 CreateEpFactories() 期间，ONNX Runtime 通过使用其在初始化期间发现的所有硬件设备调用 OrtEpFactory::GetSupportedDevices()，来确定每个工厂所支持的硬件设备子集。

工厂从 OrtEpFactory::GetSupportedDevices() 返回 OrtEpDevice 实例。每个 OrtEpDevice 实例将一个工厂与该工厂支持的硬件设备配对。例如，如果单个工厂实例同时支持 CPU 和 NPU，则对 OrtEpFactory::GetSupportedDevices() 的调用会返回两个 OrtEpDevice 实例

ep_device_0: (factory_0, CPU)
ep_device_1: (factory_0, NPU)

Sequence diagram showing registration and unregistration of a plugin EP library

使用显式 OrtEpDevice 创建会话

下方的应用程序代码使用 API 函数 SessionOptionsAppendExecutionProvider_V2 将来自库的 EP 添加到 ONNX Runtime 会话中。

应用程序首先调用 GetEpDevices 获取应用程序可用的 OrtEpDevices 列表。每个 OrtEpDevice 代表一个由 OrtEpFactory 支持的硬件设备。SessionOptionsAppendExecutionProvider_V2 函数接受一个 OrtEpDevice 实例数组作为输入，其中所有的 OrtEpDevice 实例都指向同一个 OrtEpFactory。

Ort::Env env;
env.RegisterExecutionProviderLibrary(/*...*/);

{
  std::vector<Ort::ConstEpDevice> ep_devices = env.GetEpDevices();

  // Find the Ort::EpDevice for "my_ep".
  std::vector<Ort::ConstEpDevice> selected_ep_devices{};
  for (Ort::ConstEpDevice ep_device : ep_devices) {
    if (std::strcmp(ep_device.EpName(), "my_ep") == 0) {
      selected_ep_devices.push_back(ep_device);
      break;
    }
  }

  if (selected_ep_devices.empty()) {
    // Did not find EP. Report application error ...
  }

  Ort::KeyValuePairs ep_options(/*...*/);  // Optional EP options.
  Ort::SessionOptions session_options;
  session_options.AppendExecutionProvider_V2(env, selected_ep_devices, ep_options);

  Ort::Session session(env, ORT_TSTR("model.onnx"), session_options);

  // Run model ...
}

env.UnregisterExecutionProviderLibrary(/*...*/);

如以下时序图所示，ONNX Runtime 在创建会话期间调用 OrtEpFactory::CreateEp()，以便创建插件 EP 的实例。

Sequence diagram showing session creation with explicit ep devices

使用自动 EP 选择创建会话

下方的应用程序代码使用 API 函数 SessionOptionsSetEpSelectionPolicy，使 ONNX Runtime 能够根据用户的策略（例如 PREFER_NPU）自动选择 EP。如果向 ONNX Runtime 注册的插件 EP 库中包含支持 NPU 的工厂，则 ONNX Runtime 可能会从该工厂中选择一个 EP 来运行模型。

Ort::Env env;
env.RegisterExecutionProviderLibrary(/*...*/);

{
  Ort::SessionOptions session_options;
  session_options.SetEpSelectionPolicy(OrtExecutionProviderDevicePolicy::PREFER_NPU);

  Ort::Session session(env, ORT_TSTR("model.onnx"), session_options);

  // Run model ...
}

env.UnregisterExecutionProviderLibrary(/*...*/);

Sequence diagram showing session creation with automatic EP selection

API 参考

下表列出了与插件 EP 库注册以及在会话中使用插件 EP 相关的 API 函数。

函数	描述
RegisterExecutionProviderLibrary	向 ORT 注册 EP 库。该库必须导出 `CreateEpFactories` 和 `ReleaseEpFactory` 函数。
UnregisterExecutionProviderLibrary	从 ORT 注销 EP 库。在调用此函数之前，调用者必须确保没有任何 `OrtSession` 实例正在使用该库创建的 EP。
GetEpDevices	获取可用 OrtEpDevice 实例的列表。每个 `OrtEpDevice` 实例都包含有关执行提供程序及其将使用的设备的详细信息。
SessionOptionsAppendExecutionProvider_V2	将负责所提供的 `OrtEpDevice` 实例的执行提供程序追加到会话选项中。
SessionOptionsSetEpSelectionPolicy	设置会话的执行提供程序选择策略。允许用户为自动 EP 选择指定设备选择策略。如果需要自定义选择，请改用 `SessionOptionsSetEpSelectionPolicyDelegate`。
SessionOptionsSetEpSelectionPolicyDelegate	设置会话的执行提供程序选择策略委托。允许用户为自动 EP 选择提供自定义的设备选择策略。