插件执行提供程序库打包指南

本页为 ONNX Runtime 插件 EP 实现者提供有关插件 EP 打包的指导建议。

内容

• 通用指南
  • 用法
    • 手动注册 EP 库
  • 结构
    • 目录
    • 对 ONNX Runtime 的依赖
    • 需要提供的附加信息
    • 包命名
• 特定包的指南
  • PyPI
    • 包命名
    • 辅助函数
    • 示例
  • NuGet
    • 包命名
    • 辅助函数
    • 示例

通用指南

使用方法

注意：通常，在提及 ORT API 时，我们指的是 C API 函数。对于支持插件 EP 使用的其他语言绑定，应存在对应的等效函数。

手动注册 EP 库

用户需要调用 OrtApi::RegisterExecutionProviderLibrary() 来注册插件 EP 库。然后，他们可以选择使用自动 EP 选择机制，或者手动调用 OrtApi::SessionOptionsAppendExecutionProvider_V2() 来显式使用该插件 EP。

结构

内容

插件 EP 包应包含插件 EP 共享库文件以及任何需要与其一起分发的文件。

插件 EP 包不应包含 ORT 共享库或其他核心 ORT 库（例如 onnxruntime.dll 或 libonnxruntime.so）。用户应单独获取 ORT 库，通常通过安装单独的 ONNX Runtime 包来实现。

对 ONNX Runtime 的依赖

插件 EP 包不应指定对 ONNX Runtime 包的显式依赖。由于插件 EP 库是由在运行时已存在的 ORT 加载的，因此不应需要此类依赖。此外，ONNX Runtime 包可能有多种变体（例如 Python 的 onnxruntime 和 onnxruntime-gpu），对其中一个进行显式依赖可能会造成过多的限制。

但是，插件 EP 库本身应验证在运行时加载它的 ONNX Runtime 库版本是否兼容，如果不兼容则应优雅地失败。

需要提供的附加信息

库路径

应该有一种方法来获取包的插件 EP 库路径。用户将需要该插件 EP 库路径来调用 OrtApi::RegisterExecutionProviderLibrary()。

例如，包可以提供一个返回插件 EP 库路径的辅助函数。此辅助函数的推荐名称是 “get library path”。

EP 名称

应该有一种方法来获取包提供的插件 EP 名称。用户可能需要插件 EP 名称来选择合适的 OrtEpDevice 实例以提供给 OrtApi::SessionOptionsAppendExecutionProvider_V2()。

例如，插件 EP 名称可以有良好的文档记录，或者通过包提供的辅助函数来获取。返回所有 EP 名称的辅助函数的推荐名称是 “get EP names”。此外，如果只有一个 EP 名称，为了方便起见，可以提供一个返回单个值的名为 “get EP name” 的辅助函数。

包命名

包的名称应表明该包包含一个插件 EP，并且应易于与其他 ORT 包区分开来。

例如，这可以通过使用特殊的前缀或后缀来实现。

特定包的指南

PyPI

包命名

前缀 “onnxruntime-ep” 可用于标识插件 EP。

建议的包命名约定为 “onnxruntime-ep-<EP 标识符>”。

例如，“onnxruntime-ep-contoso-ai”。

辅助函数

包应提供辅助函数 get_library_path() 来获取 EP 库路径。

包应提供辅助函数 get_ep_names() 来获取 EP 名称。

如果只有一个 EP 名称，包可以提供辅助函数 get_ep_name() 来获取该单个 EP 名称。

示例

请参考Python 包设置示例及其用法示例。

NuGet

包命名

NuGet 包可以使用保留的 ID 前缀。

建议的包命名约定为 “<供应商前缀>.ML.OnnxRuntime.EP.<EP 标识符>”。

例如，“Contoso.ML.OnnxRuntime.EP.ContosoAI”。

辅助函数

包应提供辅助函数 GetLibraryPath() 来获取 EP 库路径。

包应提供辅助函数 GetEpNames() 来获取 EP 名称。

如果只有一个 EP 名称，包可以提供辅助函数 GetEpName() 来获取该单个 EP 名称。

示例

请参考NuGet 包设置示例及其用法示例。