NVML API 参考指南 :: GPU 部署和管理文档

NVML API 参考指南 (PDF) - vR570 (旧版本) - 最后更新于 2025 年 1 月 29 日 - 发送反馈

4.28. 多实例 GPU 管理

本章介绍与多实例 GPU (MIG) 管理相关的 NVML 操作。

类

struct nvmlComputeInstanceProfileInfo_t
struct nvmlComputeInstanceProfileInfo_v2_t
struct nvmlComputeInstanceProfileInfo_v3_t
struct nvmlGpuInstanceProfileInfo_t
struct nvmlGpuInstanceProfileInfo_v2_t
struct nvmlGpuInstanceProfileInfo_v3_t

定义

#define NVML_COMPUTE_INSTANCE_ENGINE_PROFILE_SHARED 0x0: 除了多处理器之外的所有引擎都将被共享。
#define NVML_COMPUTE_INSTANCE_PROFILE_1_SLICE 0x0
#define NVML_COMPUTE_INSTANCE_PROFILE_CAPS_GFX 0x1
#define NVML_DEVICE_MIG_DISABLE 0x0
#define NVML_DEVICE_MIG_ENABLE 0x1
#define NVML_GPU_INSTANCE_PROFILE_1_SLICE 0x0
#define NVML_GPU_INSTANCE_PROFILE_CAPS_P2P 0x1
#define NVML_GPU_INTSTANCE_PROFILE_CAPS_P2P 0x1: 已弃用，请勿使用。
#define nvmlComputeInstanceProfileInfo_v2
#define nvmlComputeInstanceProfileInfo_v3
#define nvmlGpuInstanceProfileInfo_v2
#define nvmlGpuInstanceProfileInfo_v3

函数

nvmlReturn_t nvmlComputeInstanceDestroy ( nvmlComputeInstance_t computeInstance )
nvmlReturn_t nvmlComputeInstanceGetInfo_v2 ( nvmlComputeInstance_t computeInstance, nvmlComputeInstanceInfo_t* info )
nvmlReturn_t nvmlDeviceCreateGpuInstance ( nvmlDevice_t device, unsigned int profileId, nvmlGpuInstance_t* gpuInstance )
nvmlReturn_t nvmlDeviceCreateGpuInstanceWithPlacement ( nvmlDevice_t device, unsigned int profileId, const nvmlGpuInstancePlacement_t* placement, nvmlGpuInstance_t* gpuInstance )
nvmlReturn_t nvmlDeviceGetComputeInstanceId ( nvmlDevice_t device, unsigned int* id )
nvmlReturn_t nvmlDeviceGetDeviceHandleFromMigDeviceHandle ( nvmlDevice_t migDevice, nvmlDevice_t* device )
nvmlReturn_t nvmlDeviceGetGpuInstanceById ( nvmlDevice_t device, unsigned int id, nvmlGpuInstance_t* gpuInstance )
nvmlReturn_t nvmlDeviceGetGpuInstanceId ( nvmlDevice_t device, unsigned int* id )
nvmlReturn_t nvmlDeviceGetGpuInstancePossiblePlacements_v2 ( nvmlDevice_t device, unsigned int profileId, nvmlGpuInstancePlacement_t* placements, unsigned int* count )
nvmlReturn_t nvmlDeviceGetGpuInstanceProfileInfo ( nvmlDevice_t device, unsigned int profile, nvmlGpuInstanceProfileInfo_t* info )
nvmlReturn_t nvmlDeviceGetGpuInstanceProfileInfoV ( nvmlDevice_t device, unsigned int profile, nvmlGpuInstanceProfileInfo_v2_t* info )
nvmlReturn_t nvmlDeviceGetGpuInstanceRemainingCapacity ( nvmlDevice_t device, unsigned int profileId, unsigned int* count )
nvmlReturn_t nvmlDeviceGetGpuInstances ( nvmlDevice_t device, unsigned int profileId, nvmlGpuInstance_t* gpuInstances, unsigned int* count )
nvmlReturn_t nvmlDeviceGetMaxMigDeviceCount ( nvmlDevice_t device, unsigned int* count )
nvmlReturn_t nvmlDeviceGetMigDeviceHandleByIndex ( nvmlDevice_t device, unsigned int index, nvmlDevice_t* migDevice )
nvmlReturn_t nvmlDeviceGetMigMode ( nvmlDevice_t device, unsigned int* currentMode, unsigned int* pendingMode )
nvmlReturn_t nvmlDeviceIsMigDeviceHandle ( nvmlDevice_t device, unsigned int* isMigDevice )
nvmlReturn_t nvmlDeviceSetMigMode ( nvmlDevice_t device, unsigned int mode, nvmlReturn_t* activationStatus )
nvmlReturn_t nvmlGpuInstanceCreateComputeInstance ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, nvmlComputeInstance_t* computeInstance )
nvmlReturn_t nvmlGpuInstanceCreateComputeInstanceWithPlacement ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, const nvmlComputeInstancePlacement_t* placement, nvmlComputeInstance_t* computeInstance )
nvmlReturn_t nvmlGpuInstanceDestroy ( nvmlGpuInstance_t gpuInstance )
nvmlReturn_t nvmlGpuInstanceGetComputeInstanceById ( nvmlGpuInstance_t gpuInstance, unsigned int id, nvmlComputeInstance_t* computeInstance )
nvmlReturn_t nvmlGpuInstanceGetComputeInstancePossiblePlacements ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, nvmlComputeInstancePlacement_t* placements, unsigned int* count )
nvmlReturn_t nvmlGpuInstanceGetComputeInstanceProfileInfo ( nvmlGpuInstance_t gpuInstance, unsigned int profile, unsigned int engProfile, nvmlComputeInstanceProfileInfo_t* info )
nvmlReturn_t nvmlGpuInstanceGetComputeInstanceProfileInfoV ( nvmlGpuInstance_t gpuInstance, unsigned int profile, unsigned int engProfile, nvmlComputeInstanceProfileInfo_v2_t* info )
nvmlReturn_t nvmlGpuInstanceGetComputeInstanceRemainingCapacity ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, unsigned int* count )
nvmlReturn_t nvmlGpuInstanceGetComputeInstances ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, nvmlComputeInstance_t* computeInstances, unsigned int* count )
nvmlReturn_t nvmlGpuInstanceGetInfo ( nvmlGpuInstance_t gpuInstance, nvmlGpuInstanceInfo_t* info )

定义

#define NVML_COMPUTE_INSTANCE_ENGINE_PROFILE_SHARED 0x0
#define NVML_COMPUTE_INSTANCE_PROFILE_1_SLICE 0x0: 计算实例配置文件。

这些宏应传递给 nvmlGpuInstanceGetComputeInstanceProfileInfo 以检索有关计算实例的详细信息，例如配置文件 ID、引擎计数
#define NVML_COMPUTE_INSTANCE_PROFILE_CAPS_GFX 0x1: MIG 计算实例配置文件能力。

表示 MIG 配置文件能力的位字段值 nvmlComputeInstanceProfileInfo_v3_t::capabilities
#define NVML_DEVICE_MIG_DISABLE 0x0: 禁用多实例 GPU 模式。
#define NVML_DEVICE_MIG_ENABLE 0x1: 启用多实例 GPU 模式。
#define NVML_GPU_INSTANCE_PROFILE_1_SLICE 0x0: GPU 实例配置文件。

这些宏应传递给 nvmlDeviceGetGpuInstanceProfileInfo 以检索有关 GPU 实例的详细信息，例如配置文件 ID、引擎计数。
#define NVML_GPU_INSTANCE_PROFILE_CAPS_P2P 0x1: MIG GPU 实例配置文件能力。

表示 MIG 配置文件能力的位字段值 nvmlGpuInstanceProfileInfo_v3_t::capabilities
#define NVML_GPU_INTSTANCE_PROFILE_CAPS_P2P 0x1
#define nvmlComputeInstanceProfileInfo_v2: 结构版本标识符值，用于 nvmlComputeInstanceProfileInfo_v2_t::version。

值

NVML_STRUCT_VERSION(ComputeInstanceProfileInfo, 2)
#define nvmlComputeInstanceProfileInfo_v3: 结构版本标识符值，用于 nvmlComputeInstanceProfileInfo_v3_t::version。

值

NVML_STRUCT_VERSION(ComputeInstanceProfileInfo, 3)
#define nvmlGpuInstanceProfileInfo_v2: 结构版本标识符值，用于 nvmlGpuInstanceProfileInfo_v2_t::version。

值

NVML_STRUCT_VERSION(GpuInstanceProfileInfo, 2)
#define nvmlGpuInstanceProfileInfo_v3: 结构版本标识符值，用于 nvmlGpuInstanceProfileInfo_v3_t::version。

值

NVML_STRUCT_VERSION(GpuInstanceProfileInfo, 3)

函数

nvmlReturn_t nvmlComputeInstanceDestroy ( nvmlComputeInstance_t computeInstance )

参数

computeInstance: 计算实例句柄

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 computeInstance 无效
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限
NVML_ERROR_IN_USE 如果计算实例正在使用中。如果进程（例如 CUDA 应用程序）在计算实例上处于活动状态，则会返回此错误。

描述

销毁计算实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlComputeInstanceGetInfo_v2 ( nvmlComputeInstance_t computeInstance, nvmlComputeInstanceInfo_t* info )

参数

computeInstance: 计算实例句柄
info: 返回计算实例信息

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 computeInstance 或 info 无效
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取计算实例信息。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlDeviceCreateGpuInstance ( nvmlDevice_t device, unsigned int profileId, nvmlGpuInstance_t* gpuInstance )

参数

device: 目标设备的标识符
profileId: GPU 实例配置文件 ID。请参阅 nvmlDeviceGetGpuInstanceProfileInfo
gpuInstance: 返回 GPU 实例句柄

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、profile、profileId 或 gpuInstance 无效
NVML_ERROR_NOT_SUPPORTED 如果设备未启用 MIG 模式或在 vGPU 访客中
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限
NVML_ERROR_INSUFFICIENT_RESOURCES 如果无法创建请求的 GPU 实例

描述

创建 GPU 实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

如果父设备未绑定、重置或 GPU 实例被显式销毁，则 GPU 实例句柄将变为无效。必须重新创建 GPU 实例以获取有效的句柄。

nvmlReturn_t nvmlDeviceCreateGpuInstanceWithPlacement ( nvmlDevice_t device, unsigned int profileId, const nvmlGpuInstancePlacement_t* placement, nvmlGpuInstance_t* gpuInstance )

参数

device: 目标设备的标识符
profileId: GPU 实例配置文件 ID。请参阅 nvmlDeviceGetGpuInstanceProfileInfo
placement: 请求的放置。请参阅 nvmlDeviceGetGpuInstancePossiblePlacements_v2
gpuInstance: 返回 GPU 实例句柄

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、profile、profileId、placement 或 gpuInstance 无效
NVML_ERROR_NOT_SUPPORTED 如果设备未启用 MIG 模式或在 vGPU 访客中
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限
NVML_ERROR_INSUFFICIENT_RESOURCES 如果无法创建请求的 GPU 实例

描述

使用指定的放置创建 GPU 实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

如果父设备未绑定、重置或 GPU 实例被显式销毁，则 GPU 实例句柄将变为无效。必须重新创建 GPU 实例以获取有效的句柄。

nvmlReturn_t nvmlDeviceGetComputeInstanceId ( nvmlDevice_t device, unsigned int* id )

参数

device: 目标 MIG 设备句柄
id: 计算实例 ID

返回值

NVML_SUCCESS 如果成功检索到实例 ID
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device 或 id 引用无效
NVML_ERROR_NOT_SUPPORTED 如果设备不支持此查询
NVML_ERROR_UNKNOWN 任何意外错误

描述

获取给定 MIG 设备句柄的计算实例 ID。

计算实例 ID 在每个 GPU 实例中是唯一的，并且在计算实例被销毁之前保持有效。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlDeviceGetDeviceHandleFromMigDeviceHandle ( nvmlDevice_t migDevice, nvmlDevice_t* device )

参数

migDevice: MIG 设备句柄
device: Device handle

返回值

NVML_SUCCESS 如果设备句柄已成功创建
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 migDevice 或 device 无效
NVML_ERROR_NOT_SUPPORTED 如果设备不支持此查询
NVML_ERROR_UNKNOWN 任何意外错误

描述

从 MIG 设备句柄获取父设备句柄。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlDeviceGetGpuInstanceById ( nvmlDevice_t device, unsigned int id, nvmlGpuInstance_t* gpuInstance )

参数

device: 目标设备的标识符
id: GPU 实例 ID
gpuInstance: 返回 GPU 实例

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、id 或 gpuInstance 无效
NVML_ERROR_NOT_SUPPORTED 如果设备未启用 MIG 模式
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限
NVML_ERROR_NOT_FOUND 如果未找到 GPU 实例。

描述

获取给定实例 ID 的 GPU 实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlDeviceGetGpuInstanceId ( nvmlDevice_t device, unsigned int* id )

参数

device: 目标 MIG 设备句柄
id: GPU 实例 ID

返回值

NVML_SUCCESS 如果成功检索到实例 ID
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device 或 id 引用无效
NVML_ERROR_NOT_SUPPORTED 如果设备不支持此查询
NVML_ERROR_UNKNOWN 任何意外错误

描述

获取给定 MIG 设备句柄的 GPU 实例 ID。

GPU 实例 ID 在每个设备中是唯一的，并且在 GPU 实例被销毁之前保持有效。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlDeviceGetGpuInstancePossiblePlacements_v2 ( nvmlDevice_t device, unsigned int profileId, nvmlGpuInstancePlacement_t* placements, unsigned int* count )

参数

device: 目标设备的标识符
profileId: GPU 实例配置文件 ID。请参阅 nvmlDeviceGetGpuInstanceProfileInfo
placements: 返回配置文件允许的放置。可以为 NULL 以发现此配置文件允许的放置数量。如果为非 NULL，则必须足够大以容纳配置文件支持的放置。
count: 返回配置文件允许的放置数量。

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、profileId 或 count 无效
NVML_ERROR_NOT_SUPPORTED 如果设备不支持 MIG 或 profileId 不受支持
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取 GPU 实例放置。

放置表示 GPU 实例在设备中的位置。此 API 仅返回给定配置文件的所有可能放置，无论是否启用 MIG。创建的 GPU 实例占用其放置描述的内存切片。如果与已占用的内存切片重叠，则新的 GPU 实例的创建将失败。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlDeviceGetGpuInstanceProfileInfo ( nvmlDevice_t device, unsigned int profile, nvmlGpuInstanceProfileInfo_t* info )

参数

device: 目标设备的标识符
profile: NVML_GPU_INSTANCE_PROFILE_* 之一
info: 返回详细的配置文件信息

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、profile 或 info 无效
NVML_ERROR_NOT_SUPPORTED 如果设备不支持 MIG 或 profile 不受支持
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取 GPU 实例配置文件信息

此 API 提供的信息在 MIG 模式的整个生命周期内都是不可变的。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlDeviceGetGpuInstanceProfileInfoV ( nvmlDevice_t device, unsigned int profile, nvmlGpuInstanceProfileInfo_v2_t* info )

参数

device: 目标设备的标识符
profile: NVML_GPU_INSTANCE_PROFILE_* 之一
info: 返回详细的配置文件信息

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、profile、info 或 info->version 无效
NVML_ERROR_NOT_SUPPORTED 如果设备未启用 MIG 模式或 profile 不受支持
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

围绕 nvmlDeviceGetGpuInstanceProfileInfo 的版本化包装器，它接受版本化的 nvmlGpuInstanceProfileInfo_v2_t 或更高版本的输出结构。

注意

调用者必须在调用此函数之前将 nvmlGpuInstanceProfileInfo_v2_t::version 字段设置为适当的版本。例如

‎     nvmlGpuInstanceProfileInfo_v2_t profileInfo =
               { .version = nvmlGpuInstanceProfileInfo_v2 };
           nvmlReturn_t result = nvmlDeviceGetGpuInstanceProfileInfoV(device,
                                                                      profile,
                                                                      &profileInfo);

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlDeviceGetGpuInstanceRemainingCapacity ( nvmlDevice_t device, unsigned int profileId, unsigned int* count )

参数

device: 目标设备的标识符
profileId: GPU 实例配置文件 ID。请参阅 nvmlDeviceGetGpuInstanceProfileInfo
count: 返回配置文件 ID 的剩余实例计数

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、profileId 或 count 无效
NVML_ERROR_NOT_SUPPORTED 如果设备未启用 MIG 模式或不支持 profileId
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取 GPU 实例配置文件容量。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlDeviceGetGpuInstances ( nvmlDevice_t device, unsigned int profileId, nvmlGpuInstance_t* gpuInstances, unsigned int* count )

参数

device: 目标设备的标识符
profileId: GPU 实例配置文件 ID。请参阅 nvmlDeviceGetGpuInstanceProfileInfo
gpuInstances: 返回预先存在的 GPU 实例，缓冲区必须足够大以容纳配置文件支持的实例。请参阅 nvmlDeviceGetGpuInstanceProfileInfo
count: 返回的 GPU 实例计数

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、profileId、gpuInstances 或 count 无效
NVML_ERROR_NOT_SUPPORTED 如果设备未启用 MIG 模式
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取给定配置文件 ID 的 GPU 实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlDeviceGetMaxMigDeviceCount ( nvmlDevice_t device, unsigned int* count )

参数

device: 目标设备句柄
count: MIG 设备计数

返回值

NVML_SUCCESS 如果成功检索到计数
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device 或 count 引用无效
NVML_ERROR_UNKNOWN 任何意外错误

描述

获取给定父 NVML 设备下可以存在的最大 MIG 设备数量。

如果不支持或未启用 MIG，则返回零。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlDeviceGetMigDeviceHandleByIndex ( nvmlDevice_t device, unsigned int index, nvmlDevice_t* migDevice )

参数

device: 父 GPU 设备句柄的引用
index: MIG 设备的索引
migDevice: MIG 设备句柄的引用

返回值

NVML_SUCCESS 如果成功创建 migDevice 句柄
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、index 或 migDevice 引用无效
NVML_ERROR_NOT_SUPPORTED 如果设备不支持此查询
NVML_ERROR_NOT_FOUND 如果在索引处未找到有效的 MIG 设备
NVML_ERROR_UNKNOWN 任何意外错误

描述

获取给定索引下其父 NVML 设备的 MIG 设备句柄。

如果计算实例被显式销毁，或者通过销毁、重置或解除绑定父 GPU 实例或 GPU 设备本身，MIG 设备句柄将保持无效，并且必须使用此 API 再次请求。句柄可能会被重用，并且它们的属性可能会在此过程中更改。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlDeviceGetMigMode ( nvmlDevice_t device, unsigned int* currentMode, unsigned int* pendingMode )

参数

device: 目标设备的标识符
currentMode: 返回当前模式，NVML_DEVICE_MIG_DISABLE 或 NVML_DEVICE_MIG_ENABLE
pendingMode: 返回待定模式，NVML_DEVICE_MIG_DISABLE 或 NVML_DEVICE_MIG_ENABLE

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、currentMode 或 pendingMode 无效
NVML_ERROR_NOT_SUPPORTED 如果设备不支持 MIG 模式

描述

获取设备的 MIG 模式。

适用于 Ampere 或更新的完全支持的设备。

更改 MIG 模式可能需要设备解除绑定或重置。“待定”MIG 模式是指下一次激活触发后将生效的目标模式。

nvmlReturn_t nvmlDeviceIsMigDeviceHandle ( nvmlDevice_t device, unsigned int* isMigDevice )

参数

device: 要测试的 NVML 句柄
isMigDevice: 当句柄引用 MIG 设备时为 True

返回值

NVML_SUCCESS 如果成功检索到设备状态
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果设备句柄或 isMigDevice 引用无效
NVML_ERROR_NOT_SUPPORTED 如果设备不支持此检查
NVML_ERROR_UNKNOWN 任何意外错误

描述

测试给定的句柄是否引用 MIG 设备。

MIG 设备句柄是一个 NVML 抽象概念，它映射到一个 MIG 计算实例。这些重载的引用可以（在某些限制下）与 GPU 设备句柄互换使用，以在每个计算实例粒度执行查询。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlDeviceSetMigMode ( nvmlDevice_t device, unsigned int mode, nvmlReturn_t* activationStatus )

参数

device: 目标设备的标识符
mode: 要设置的模式，NVML_DEVICE_MIG_DISABLE 或 NVML_DEVICE_MIG_ENABLE
activationStatus: activationStatus 状态

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、mode 或 activationStatus 无效
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限
NVML_ERROR_NOT_SUPPORTED 如果设备不支持 MIG 模式

描述

设置设备的 MIG 模式。

适用于 Ampere 或更新的完全支持的设备。需要 root 用户权限。

此模式确定是否可以创建 GPU 实例。

此 API 可能会解除绑定或重置设备以激活请求的模式。因此，与设备关联的属性（例如次要设备号）可能会更改。此 API 的调用者应再次查询此类属性。

在某些平台（如直通虚拟化）上，重置功能可能未直接公开，因此需要重启 VM。对于这种情况，activationStatus 将返回 NVML_ERROR_RESET_REQUIRED。

如果激活不成功，activationStatus 将返回相应的错误代码。例如，如果设备未空闲导致设备解除绑定失败，则会返回 NVML_ERROR_IN_USE。此 API 的调用者应使设备空闲并重试设置模式。

注意

在 Windows 上，仅支持禁用 MIG 模式。由于 Windows 不支持通过此 API 进行 GPU 重置，activationStatus 将返回 NVML_ERROR_NOT_SUPPORTED。

nvmlReturn_t nvmlGpuInstanceCreateComputeInstance ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, nvmlComputeInstance_t* computeInstance )

参数

gpuInstance: 目标 GPU 实例的标识符
profileId: 计算实例配置文件 ID。请参阅 nvmlGpuInstanceGetComputeInstanceProfileInfo
computeInstance: 返回计算实例句柄

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 gpuInstance、profile、profileId 或 computeInstance 无效
NVML_ERROR_NOT_SUPPORTED 如果 profileId 不受支持
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限
NVML_ERROR_INSUFFICIENT_RESOURCES 如果无法创建请求的计算实例

描述

创建计算实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

如果父设备被解除绑定、重置，或者父 GPU 实例被销毁，或者计算实例被显式销毁，则计算实例句柄将变为无效。必须重新创建计算实例以获取有效的句柄。

nvmlReturn_t nvmlGpuInstanceCreateComputeInstanceWithPlacement ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, const nvmlComputeInstancePlacement_t* placement, nvmlComputeInstance_t* computeInstance )

参数

gpuInstance: 目标 GPU 实例的标识符
profileId: 计算实例配置文件 ID。请参阅 nvmlGpuInstanceGetComputeInstanceProfileInfo
placement: 请求的放置。请参阅 nvmlGpuInstanceGetComputeInstancePossiblePlacements
computeInstance: 返回计算实例句柄

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 gpuInstance、profile、profileId 或 computeInstance 无效
NVML_ERROR_NOT_SUPPORTED 如果 profileId 不受支持
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限
NVML_ERROR_INSUFFICIENT_RESOURCES 如果无法创建请求的计算实例

描述

使用指定的放置创建计算实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlGpuInstanceDestroy ( nvmlGpuInstance_t gpuInstance )

参数

gpuInstance: GPU 实例句柄

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 gpuInstance 无效
NVML_ERROR_NOT_SUPPORTED 如果设备未启用 MIG 模式或在 vGPU 访客中
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限
NVML_ERROR_IN_USE 如果 GPU 实例正在使用中。如果进程（例如 CUDA 应用程序）或计算实例在 GPU 实例上处于活动状态，则会返回此错误。

描述

销毁 GPU 实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlGpuInstanceGetComputeInstanceById ( nvmlGpuInstance_t gpuInstance, unsigned int id, nvmlComputeInstance_t* computeInstance )

参数

gpuInstance: 目标 GPU 实例的标识符
id: 计算实例 ID
computeInstance: 返回计算实例

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 device、ID 或 computeInstance 无效
NVML_ERROR_NOT_SUPPORTED 如果设备未启用 MIG 模式
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限
NVML_ERROR_NOT_FOUND 如果未找到计算实例。

描述

获取给定实例 ID 的计算实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlGpuInstanceGetComputeInstancePossiblePlacements ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, nvmlComputeInstancePlacement_t* placements, unsigned int* count )

参数

gpuInstance: 目标 GPU 实例的标识符
profileId: 计算实例配置文件 ID。请参阅 nvmlGpuInstanceGetComputeInstanceProfileInfo
placements: 返回配置文件允许的放置。可以为 NULL 以发现此配置文件允许的放置数量。如果为非 NULL，则必须足够大以容纳配置文件支持的放置。
count: 返回配置文件允许的放置数量。

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 gpuInstance、profileId 或 count 无效
NVML_ERROR_NOT_SUPPORTED 如果设备未启用 MIG 模式或不支持 profileId
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取计算实例放置。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

放置表示计算实例在 GPU 实例中的位置。此 API 仅返回给定配置文件的所有可能放置。创建的计算实例占用其放置描述的计算切片。如果与已占用的计算切片重叠，则创建新的计算实例将失败。

nvmlReturn_t nvmlGpuInstanceGetComputeInstanceProfileInfo ( nvmlGpuInstance_t gpuInstance, unsigned int profile, unsigned int engProfile, nvmlComputeInstanceProfileInfo_t* info )

参数

gpuInstance: 目标 GPU 实例的标识符
profile: NVML_COMPUTE_INSTANCE_PROFILE_* 之一
engProfile: NVML_COMPUTE_INSTANCE_ENGINE_PROFILE_* 之一
info: 返回详细的配置文件信息

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 gpuInstance、profile、engProfile 或 info 无效
NVML_ERROR_NOT_SUPPORTED 如果 profile 不受支持
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取计算实例配置文件信息。

此 API 提供的信息在 MIG 模式的整个生命周期内都是不可变的。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlGpuInstanceGetComputeInstanceProfileInfoV ( nvmlGpuInstance_t gpuInstance, unsigned int profile, unsigned int engProfile, nvmlComputeInstanceProfileInfo_v2_t* info )

参数

gpuInstance: 目标 GPU 实例的标识符
profile: NVML_COMPUTE_INSTANCE_PROFILE_* 之一
engProfile: NVML_COMPUTE_INSTANCE_ENGINE_PROFILE_* 之一
info: 返回详细的配置文件信息

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 gpuInstance、profile、engProfile、info 或 info->version 无效
NVML_ERROR_NOT_SUPPORTED 如果 profile 不受支持
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

围绕 nvmlGpuInstanceGetComputeInstanceProfileInfo 的版本化包装器，它接受版本化的 nvmlComputeInstanceProfileInfo_v2_t 或更高版本的输出结构。

注意

调用者必须在调用此函数之前将 nvmlGpuInstanceProfileInfo_v2_t::version 字段设置为适当的版本。例如

‎     nvmlComputeInstanceProfileInfo_v2_t profileInfo =
               { .version = nvmlComputeInstanceProfileInfo_v2 };
           nvmlReturn_t result = nvmlGpuInstanceGetComputeInstanceProfileInfoV(gpuInstance,
                                                                               profile,
                                                                               engProfile,
                                                                               &profileInfo);

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

nvmlReturn_t nvmlGpuInstanceGetComputeInstanceRemainingCapacity ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, unsigned int* count )

参数

gpuInstance: 目标 GPU 实例的标识符
profileId: 计算实例配置文件 ID。请参阅 nvmlGpuInstanceGetComputeInstanceProfileInfo
count: 返回配置文件 ID 的剩余实例计数

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 gpuInstance、profileId 或 availableCount 无效
NVML_ERROR_NOT_SUPPORTED 如果 profileId 不受支持
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取计算实例配置文件容量。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlGpuInstanceGetComputeInstances ( nvmlGpuInstance_t gpuInstance, unsigned int profileId, nvmlComputeInstance_t* computeInstances, unsigned int* count )

参数

gpuInstance: 目标 GPU 实例的标识符
profileId: 计算实例配置文件 ID。请参阅 nvmlGpuInstanceGetComputeInstanceProfileInfo
computeInstances: 返回预先存在的计算实例，缓冲区必须足够大以容纳配置文件支持的实例。请参阅 nvmlGpuInstanceGetComputeInstanceProfileInfo
count: 返回的计算实例计数

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 gpuInstance、profileId、computeInstances 或 count 无效
NVML_ERROR_NOT_SUPPORTED 如果 profileId 不受支持
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取给定配置文件 ID 的计算实例。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。需要特权用户。

nvmlReturn_t nvmlGpuInstanceGetInfo ( nvmlGpuInstance_t gpuInstance, nvmlGpuInstanceInfo_t* info )

参数

gpuInstance: GPU 实例句柄
info: 返回 GPU 实例信息

返回值

NVML_SUCCESS 成功时返回
NVML_ERROR_UNINITIALIZED 如果库未成功初始化
NVML_ERROR_INVALID_ARGUMENT 如果 gpuInstance 或 info 无效
NVML_ERROR_NO_PERMISSION 如果用户没有执行此操作的权限

描述

获取 GPU 实例信息。

适用于 Ampere 或更新的完全支持的设备。仅在 Linux 上支持。

NVML API 参考指南 (PDF) - vR570 (旧版本) - 最后更新于 2025 年 1 月 29 日 - 发送反馈