Class SessionOptions

保存用于创建 InferenceSession 的选项。它强制实例化 OrtEnv 单例。

继承

Object

CriticalFinalizerObject

SafeHandle

SessionOptions

实现

IDisposable

继承成员

SafeHandle.handle

SafeHandle.Close()

SafeHandle.DangerousAddRef(Boolean)

SafeHandle.DangerousGetHandle()

SafeHandle.DangerousRelease()

SafeHandle.Dispose()

SafeHandle.Dispose(Boolean)

SafeHandle.SetHandle(IntPtr)

SafeHandle.SetHandleAsInvalid()

SafeHandle.IsClosed

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

命名空间: Microsoft.ML.OnnxRuntime

程序集: Microsoft.ML.OnnxRuntime.dll

语法

public class SessionOptions : SafeHandle, IDisposable

构造函数

SessionOptions()

构造一个空的 SessionOptions

声明

public SessionOptions()

属性

EnableCpuMemArena

为 CPU 内存分配启用 Arena 分配器。默认值为 true。

声明

public bool EnableCpuMemArena { get; set; }

属性值

类型	描述
Boolean	返回 _enableCpuMemArena 标志值

EnableMemoryPattern

启用在第一次 Run() 调用中使用内存分配模式以用于后续运行。默认值 = true。

声明

public bool EnableMemoryPattern { get; set; }

属性值

类型	描述
Boolean	返回 enableMemoryPattern 标志值

EnableProfiling

启用 InferenceSession.Run() 调用的分析。默认值为 false

声明

public bool EnableProfiling { get; set; }

属性值

类型	描述
Boolean	返回 _enableProfiling 标志值

ExecutionMode

设置会话的执行模式。默认设置为 ORT_SEQUENTIAL。有关更多详细信息，请参阅 [ONNX_Runtime_Perf_Tuning.md]。

声明

public ExecutionMode ExecutionMode { get; set; }

属性值

类型	描述
ExecutionMode	返回 _executionMode 值

GraphOptimizationLevel

设置会话的图优化级别。默认设置为 ORT_ENABLE_ALL。

声明

public GraphOptimizationLevel GraphOptimizationLevel { get; set; }

属性值

类型	描述
GraphOptimizationLevel	返回 _graphOptimizationLevel 值

InterOpNumThreads

设置用于并行执行图（跨节点）的线程数。如果启用顺序执行，则此值将被忽略。值为 0 表示 ORT 将选择默认值

声明

public int InterOpNumThreads { get; set; }

属性值

类型	描述
Int32	返回 _interOpNumThreads 值

IntraOpNumThreads

设置用于在节点内并行执行的线程数。值为 0 表示 ORT 将选择默认值

声明

public int IntraOpNumThreads { get; set; }

属性值

类型	描述
Int32	返回 _intraOpNumThreads 值

IsInvalid

覆盖 SafeHandle.IsInvalid

声明

public override bool IsInvalid { get; }

属性值

类型	描述
Boolean	如果句柄等于零，则返回 true

覆盖

System.Runtime.InteropServices.SafeHandle.IsInvalid

LogId

用于会话的日志 ID。默认为空字符串。

声明

public string LogId { get; set; }

属性值

类型	描述
String	返回 _logId 值

LogSeverityLevel

会话日志的日志严重性级别。默认值 = ORT_LOGGING_LEVEL_WARNING

声明

public OrtLoggingLevel LogSeverityLevel { get; set; }

属性值

类型	描述
OrtLoggingLevel	返回 _logSeverityLevel 值

LogVerbosityLevel

会话日志的日志详细程度级别。默认值 = 0。有效值 >=0。仅当 LogSeverityLevel 设置为 ORT_LOGGING_LEVEL_VERBOSE 时才生效。

声明

public int LogVerbosityLevel { get; set; }

属性值

类型	描述
Int32	返回 _logVerbosityLevel 值

OptimizedModelFilePath

设置优化模型在图级别转换后保存的文件路径。默认为空，表示禁用保存。

声明

public string OptimizedModelFilePath { get; set; }

属性值

类型	描述
String	返回 _optimizedModelFilePath 标志值

ProfileOutputPathPrefix

用于分析数据输出的路径前缀

声明

public string ProfileOutputPathPrefix { get; set; }

属性值

类型	描述
String

方法

AddFreeDimensionOverride(String, Int64)

如果在会话初始化时已知符号维度（通过特定的表示字符串）的实际值，则覆盖它们以启用可利用固定值的优化（例如内存规划等）

声明

public void AddFreeDimensionOverride(string dimDenotation, long dimValue)

参数

类型	名称	描述
String	dimDenotation	表示名称
Int64	dimValue	表示值

AddFreeDimensionOverrideByName(String, Int64)

如果在会话初始化时已知符号维度（通过特定名称字符串）的实际值，则覆盖它们以启用可利用固定值的优化（例如内存规划等）

声明

public void AddFreeDimensionOverrideByName(string dimName, long dimValue)

参数

类型	名称	描述
String	dimName	维度名称
Int64	dimValue	维度值

AddInitializer(String, OrtValue)

向会话添加一个预分配的初始化器。如果模型包含一个与此 API 调用中传递的名称相同的初始化器，ORT 将使用此初始化器实例，而不是从模型文件中反序列化一个。当您希望在多个会话中共享相同的初始化器时，这非常有用。

声明

public void AddInitializer(string name, OrtValue ortValue)

参数

类型	名称	描述
String	name	初始化器的名称
OrtValue	ortValue	包含初始化器的 OrtValue。'val' 和底层初始化器缓冲区的生命周期必须由用户管理（使用 CreateTensorWithDataAsOrtValue API 创建），并且它必须比会话对象更长。

AddSessionConfigEntry(String, String)

将单个会话配置条目设置为一对字符串。如果存在具有相同键的配置，此操作将使用给定的 configValue 覆盖现有配置。

声明

public void AddSessionConfigEntry(string configKey, string configValue)

参数

类型	名称	描述
String	configKey	配置键名
String	configValue	配置键值

AppendExecutionProvider(OrtEnv, IReadOnlyList<OrtEpDevice>, IReadOnlyDictionary<String, String>)

从 GetEpDevices 返回的可用执行提供程序和设备列表中选择执行提供程序。

epDevices 中可以提供一个或多个 OrtEpDevice 实例，但它们必须都用于同一个执行提供程序。

如果您希望使用多个执行提供程序，请多次调用 AppendExecutionProvider。

例如

• 如果执行提供程序 'A' 有一个用于 NPU 和一个用于 GPU 的 OrtEpDevice，并且您希望将其用于这两个设备，请在一次调用中将这两个 OrtEpDevice 实例传入 epDevices 列表。
• 如果您希望将执行提供程序 'B' 用于 GPU，将执行提供程序 'C' 用于 CPU，请两次调用 AppendExecutionProvider，每次调用中的 epDevices 列表中包含一个 OrtEpDevice。

执行提供程序的优先级由它们附加的顺序决定。最高优先级在前。

声明

public void AppendExecutionProvider(OrtEnv env, IReadOnlyList<OrtEpDevice> epDevices, IReadOnlyDictionary<string, string> epOptions)

参数

类型	名称	描述
OrtEnv	env	通过调用 GetEpDevices 提供 OrtEpDevice 实例的 OrtEnv。
IReadOnlyList<OrtEpDevice>	epDevices	要附加的一个或多个 OrtEpDevice 实例。它们必须都具有相同的 EpName 值。
IReadOnlyDictionary<String, String>	epOptions	可选选项，用于配置执行提供程序。可以为 null。

异常

类型	条件
System.ArgumentException	epDevices 为空。

AppendExecutionProvider(String, Dictionary<String, String>)

追加 QNN、SNPE 或 XNNPACK 执行提供程序

声明

public void AppendExecutionProvider(string providerName, Dictionary<string, string> providerOptions = null)

参数

类型	名称	描述
String	providerName	要添加的执行提供程序。目前支持 'QNN', 'SNPE' 'XNNPACK', 'CoreML' 和 'AZURE'。
Dictionary<String, String>	providerOptions	可选键/值对，用于指定执行提供程序选项。

AppendExecutionProvider_CoreML(CoreMLFlags)

仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_CoreML(CoreMLFlags coremlFlags = CoreMLFlags.COREML_FLAG_USE_NONE)

参数

类型	名称	描述
CoreMLFlags	coremlFlags	CoreML 特定标志

AppendExecutionProvider_CPU(Int32)

将 CPU EP 追加到会话可用的执行提供程序列表。

声明

public void AppendExecutionProvider_CPU(int useArena = 1)

参数

类型	名称	描述
Int32	useArena	1 - 使用 arena，0 - 不使用 arena

AppendExecutionProvider_CUDA(OrtCUDAProviderOptions)

将 CUDA EP 实例（基于指定配置）追加到 SessionOptions 实例。仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_CUDA(OrtCUDAProviderOptions cudaProviderOptions)

参数

类型	名称	描述
OrtCUDAProviderOptions	cudaProviderOptions	CUDA EP 提供程序选项

AppendExecutionProvider_CUDA(Int32)

仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_CUDA(int deviceId = 0)

参数

类型	名称	描述
Int32	整数设备 ID	deviceId

AppendExecutionProvider_DML(Int32)

仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_DML(int deviceId = 0)

参数

类型	名称	描述
Int32	整数设备 ID	设备标识

AppendExecutionProvider_Dnnl(Int32)

仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_Dnnl(int useArena = 1)

参数

类型	名称	描述
Int32	useArena	1 - 使用分配 arena，0 - 否则

AppendExecutionProvider_MIGraphX(Int32)

仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_MIGraphX(int deviceId = 0)

参数

类型	名称	描述
Int32	整数设备 ID	设备标识

AppendExecutionProvider_Nnapi(NnapiFlags)

仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_Nnapi(NnapiFlags nnapiFlags = NnapiFlags.NNAPI_FLAG_USE_NONE)

参数

类型	名称	描述
NnapiFlags	nnapiFlags	NNAPI 特定标志掩码

AppendExecutionProvider_OpenVINO(String)

仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_OpenVINO(string deviceId = "")

参数

类型	名称	描述
String	整数设备 ID	设备标识，默认为空字符串

AppendExecutionProvider_ROCm(OrtROCMProviderOptions)

将 ROCm EP 实例（基于指定配置）追加到 SessionOptions 实例。仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_ROCm(OrtROCMProviderOptions rocmProviderOptions)

参数

类型	名称	描述
OrtROCMProviderOptions	rocmProviderOptions	ROCm EP 提供程序选项

AppendExecutionProvider_ROCm(Int32)

仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_ROCm(int deviceId = 0)

参数

类型	名称	描述
Int32	整数设备 ID	设备 ID

AppendExecutionProvider_Tensorrt(OrtTensorRTProviderOptions)

将 TensorRT EP 实例（基于指定配置）追加到 SessionOptions 实例。仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_Tensorrt(OrtTensorRTProviderOptions trtProviderOptions)

参数

类型	名称	描述
OrtTensorRTProviderOptions	trtProviderOptions	TensorRT EP 提供程序选项

AppendExecutionProvider_Tensorrt(Int32)

仅当您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public void AppendExecutionProvider_Tensorrt(int deviceId = 0)

参数

类型	名称	描述
Int32	整数设备 ID	设备标识

DisablePerSessionThreads()

禁用每个会话线程。默认值为 true。这将使进程中的所有会话使用全局 TP。

声明

public void DisablePerSessionThreads()

MakeSessionOptionWithCudaProvider(OrtCUDAProviderOptions)

一个辅助方法，用于构造 CUDA 执行提供程序的 SessionOptions 对象。仅当安装了 CUDA 并且您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public static SessionOptions MakeSessionOptionWithCudaProvider(OrtCUDAProviderOptions cudaProviderOptions)

参数

类型	名称	描述
OrtCUDAProviderOptions	cudaProviderOptions	CUDA EP 提供程序选项

返回

类型	描述
SessionOptions	一个配置为在提供程序选项上执行的 SessionsOptions() 对象

MakeSessionOptionWithCudaProvider(Int32)

一个辅助方法，用于构造 CUDA 执行的 SessionOptions 对象。仅当安装了 CUDA 并且您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public static SessionOptions MakeSessionOptionWithCudaProvider(int deviceId = 0)

参数

类型	名称	描述
Int32	整数设备 ID

返回

类型	描述
SessionOptions	一个配置为在 deviceId 上执行的 SessionsOptions() 对象

MakeSessionOptionWithRocmProvider(OrtROCMProviderOptions)

一个辅助方法，用于构造 ROCm 执行提供程序的 SessionOptions 对象。仅当安装了 ROCm 并且您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public static SessionOptions MakeSessionOptionWithRocmProvider(OrtROCMProviderOptions rocmProviderOptions)

参数

类型	名称	描述
OrtROCMProviderOptions	rocmProviderOptions	ROCm EP 提供程序选项

返回

类型	描述
SessionOptions	一个配置为在提供程序选项上执行的 SessionsOptions() 对象

MakeSessionOptionWithRocmProvider(Int32)

一个辅助方法，用于构造 ROCM 执行的 SessionOptions 对象。仅当安装了 ROCM 并且您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public static SessionOptions MakeSessionOptionWithRocmProvider(int deviceId = 0)

参数

类型	名称	描述
Int32	整数设备 ID	设备 ID

返回

类型	描述
SessionOptions	一个配置为在 deviceId 上执行的 SessionsOptions() 对象

MakeSessionOptionWithTensorrtProvider(OrtTensorRTProviderOptions)

一个辅助方法，用于构造 TensorRT 执行提供程序的 SessionOptions 对象。仅当安装了 CUDA/TensorRT 并且您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public static SessionOptions MakeSessionOptionWithTensorrtProvider(OrtTensorRTProviderOptions trtProviderOptions)

参数

类型	名称	描述
OrtTensorRTProviderOptions	trtProviderOptions	TensorRT EP 提供程序选项

返回

类型	描述
SessionOptions	一个配置为在提供程序选项上执行的 SessionsOptions() 对象

MakeSessionOptionWithTensorrtProvider(Int32)

一个辅助方法，用于构造 TensorRT 执行的 SessionOptions 对象。仅当安装了 CUDA/TensorRT 并且您拥有特定于此执行提供程序的 onnxruntime 包时使用。

声明

public static SessionOptions MakeSessionOptionWithTensorrtProvider(int deviceId = 0)

参数

类型	名称	描述
Int32	整数设备 ID

返回

类型	描述
SessionOptions	一个配置为在 deviceId 上执行的 SessionsOptions() 对象

RegisterCustomOpLibrary(String)

加载名为 'libraryPath' 的 DLL 并查找此入口点：OrtStatus* RegisterCustomOps(OrtSessionOptions* options, const OrtApiBase* api); 然后将提供的会话选项与 api base 一起传递给此函数。

在 v1.15 之前，这会泄漏库句柄，因此添加了 RegisterCustomOpLibraryV2 来解决此问题。

从 v1.15 开始，ONNX Runtime 将管理句柄的生命周期。

声明

public void RegisterCustomOpLibrary(string libraryPath)

参数

类型	名称	描述
String	libraryPath	自定义操作库的路径

RegisterCustomOpLibraryV2(String, out IntPtr)

加载名为 'libraryPath' 的 DLL 并查找此入口点：OrtStatus* RegisterCustomOps(OrtSessionOptions* options, const OrtApiBase* api); 然后将提供的会话选项与 api base 一起传递给此函数。加载库的句柄在 'libraryHandle' 中返回。在使用传入的会话选项的所有会话都被销毁后，或者如果发生错误且不为 null，调用方可以卸载它。提示：.NET Core 3.1 有一个 'NativeLibrary' 类，可用于释放库句柄

声明

public void RegisterCustomOpLibraryV2(string libraryPath, out IntPtr libraryHandle)

参数

类型	名称	描述
String	libraryPath	自定义操作库路径
IntPtr	libraryHandle	out 参数，库句柄

RegisterOrtExtensions()

注册 Microsoft.ML.OnnxRuntime.Extensions NuGet 包中的自定义操作符。必须手动将对 Microsoft.ML.OnnxRuntime.Extensions 的引用添加到您的项目中。

声明

public void RegisterOrtExtensions()

异常

类型	条件
OnnxRuntimeException	如果未找到扩展库，则抛出。

ReleaseHandle()

覆盖 SafeHandle.ReleaseHandle() 以正确释放 SessionOptions 的原生实例

声明

protected override bool ReleaseHandle()

返回

类型	描述
Boolean	始终返回 true

覆盖

System.Runtime.InteropServices.SafeHandle.ReleaseHandle()

SetEpSelectionPolicy(ExecutionProviderDevicePolicy)

如果使用自动执行提供程序选择，则设置执行提供程序选择策略。执行提供程序必须在 OrtEnv 中注册才能用于选择。

声明

public void SetEpSelectionPolicy(ExecutionProviderDevicePolicy policy)

参数

类型	名称	描述
ExecutionProviderDevicePolicy	policy	要使用的策略。

SetEpSelectionPolicyDelegate(SessionOptions.EpSelectionDelegate)

如果使用自动执行提供程序选择，则设置执行提供程序选择策略。执行提供程序必须在 OrtEnv 中注册才能用于选择。

声明

public void SetEpSelectionPolicyDelegate(SessionOptions.EpSelectionDelegate selectionDelegate = null)

参数

类型	名称	描述
SessionOptions.EpSelectionDelegate	selectionDelegate	实现自定义选择策略的委托。

SetLoadCancellationFlag(Boolean)

设置会话的加载取消标志。默认设置为 false。为用户提供取消模型加载的机会。

声明

public void SetLoadCancellationFlag(bool value)

参数

类型	名称	描述
Boolean	value	true 表示请求取消，false 表示继续

实现

System.IDisposable

扩展方法

SessionOptionsContainer.ApplyConfiguration(SessionOptions, String, Boolean)