前言

在昇腾AI处理器的软件栈中，CANN（Compute Architecture for Neural Networks）作为连接上层AI框架与底层硬件的核心枢纽，承载着算子编译、模型优化、运行调度等关键职责。而runtime运行时库则是这座桥梁中最贴近硬件的一层，直接管理着设备资源、内存分配、流调度和算子执行。对于想要深入理解昇腾计算架构或者进行性能调优的开发者来说，掌握runtime的使用方法几乎是必经之路。

为什么runtime如此重要？在深度学习训练和推理过程中，框架层（如TensorFlow、PyTorch）通过算子库调用底层硬件，而runtime正是这个调用链中承上启下的关键环节。它屏蔽了硬件细节，提供了统一的设备管理接口，同时负责内存池管理、流队列调度、事件同步等底层机制。理解runtime的工作原理，不仅能帮助你在遇到性能瓶颈时找到调优方向，还能在调试底层问题时快速定位根因。

runtime能解决什么问题

runtime运行时库的核心职责可以归纳为四个方面：运行时管理、资源调度、执行控制和错误处理。

运行时管理涉及设备的初始化、状态查询和资源释放。在昇腾AI处理器的使用场景中，一个服务器可能配置了多张NPU卡，runtime提供了设备枚举、属性查询和指定设备激活的能力。通过这些接口，开发者可以灵活地选择目标设备，或者在多卡场景下实现负载均衡。

资源调度是runtime的另一个核心功能。昇腾设备的计算资源包括AI Core、AI CPU、DVPP等不同类型的处理单元，runtime负责将这些资源分配给具体的计算任务。同时，runtime还管理着设备端内存的分配与回收，这部分内存与主机端内存分离，需要通过特定的API进行拷贝和同步。在内存管理层面，runtime实现了内存池机制，通过预分配大块内存并按需切分，减少了频繁内存申请带来的开销。

执行控制是runtime与上层框架交互最频繁的部分。昇腾设备支持流（Stream）和事件（Event）两种并发控制机制。流是一系列操作的有序队列，同一个流内的操作按提交顺序依次执行；不同流之间的操作可以并行执行。事件则用于流之间的同步，一个流可以等待另一个流中的某个事件完成后再继续执行。这种机制使得数据拷贝与计算可以重叠进行，显著提升了整体吞吐量。

错误处理机制贯穿runtime的所有功能模块。无论是设备初始化失败、内存分配不足，还是算子执行异常，runtime都会返回详细的错误码，并记录相应的日志信息。开发者可以根据这些信息快速定位问题原因，比如设备是否被其他进程占用、内存是否泄露、算子是否支持当前设备型号等。

核心架构解析

runtime运行时库的架构设计遵循模块化和层次化的原则，主要包含设备管理、内存管理、流管理和算子执行四个核心模块。

设备管理模块负责与NPU硬件的交互。在初始化阶段，runtime会扫描系统中的所有昇腾设备，读取设备的属性信息（如设备型号、内存大小、算力等级等），并建立设备索引。当上层应用调用设备激活接口时，runtime会为当前进程分配设备上下文，建立与驱动的通信通道。这个上下文包含了该进程在该设备上的所有状态信息，包括已分配的内存、创建的流、提交的任务等。设备管理模块还负责处理设备的重置和资源回收，确保进程退出时能够正确释放占用的硬件资源。

内存管理模块是runtime中逻辑最复杂的部分。昇腾设备的内存模型与CPU不同，采用设备端内存和主机端内存分离的架构。主机端内存即服务器的主内存，设备端内存则是NPU卡上的专用内存。两者的寻址空间相互独立，无法直接互相访问。runtime提供了内存分配、拷贝和同步的接口，开发者需要在主机端分配内存、准备数据，然后通过拷贝接口将数据传输到设备端。为了提升性能，runtime内部实现了内存池机制，通过预分配大块内存并按需切分，减少了向驱动申请内存的次数。同时，runtime还支持锁页内存（Pinned Memory），这部分主机内存被锁定在物理地址上，不会被操作系统换出到磁盘，设备可以直接通过DMA方式访问，传输效率更高。

流管理模块负责任务的调度和并发控制。在昇腾设备上，每个流对应一个硬件队列，提交到同一个流的操作会按顺序执行。runtime允许创建多个流，不同流之间的操作可以并行执行。比如，可以创建一个流专门负责数据拷贝，另一个流负责计算，两者的执行可以重叠。流管理模块还提供了流的同步接口，允许主机端等待某个流中的所有操作完成，或者等待某个特定事件的发生。事件是流同步的重要工具，可以插入到流的任意位置，用于标记某个操作的完成状态。其他流可以等待这个事件，实现流之间的依赖控制。

算子执行模块是runtime与上层框架对接的入口。在CANN架构中，算子通常以离线模型的形式加载到设备上执行。runtime提供了模型加载、输入输出张量管理和模型执行的接口。模型加载时，runtime会将离线模型文件解析为设备可执行的形式，并在设备内存中分配相应的空间。执行时，runtime会将输入数据的地址、输出数据的地址以及相关的参数传递给设备驱动，由驱动调度具体的计算单元执行。对于动态Shape的模型，runtime还支持在执行时指定实际的输入尺寸，并根据输入尺寸动态调整内存分配。

在CANN多层架构中的协作关系

CANN的整体架构可以划分为应用层、框架层、算子层、运行时层和驱动层五个层次。runtime运行时库位于运行时层，向上对接算子层和框架层，向下对接驱动层。

在典型的模型执行流程中，上层框架（如TensorFlow或PyTorch）通过CANN的适配层将模型转换为昇腾设备可执行的离线模型。转换过程中，算子层的工具（如ATC）会根据设备的算力特性和内存约束，对模型进行图优化和算子融合，生成高效的执行计划。这个执行计划以.om文件的形式存储，包含了算子的执行顺序、内存布局、流分配策略等信息。

当应用加载这个离线模型并执行推理时，runtime开始介入。首先，runtime会初始化设备上下文，为模型执行准备运行环境。然后，runtime加载.om文件，解析其中的元数据和指令序列，在设备内存中分配模型运行所需的缓冲区。这些缓冲区包括输入输出张量的存储空间、中间结果的存储空间以及算子执行所需的临时空间。分配完成后，runtime会建立主机端地址到设备端地址的映射关系，使得应用可以通过主机端的指针访问设备端的内存。

在执行推理时，应用需要将输入数据从主机端拷贝到设备端。runtime提供了异步拷贝接口，允许数据拷贝与计算并行进行。应用可以先提交数据拷贝任务到一个流，然后在另一个流中提交模型执行任务，通过事件同步机制确保数据拷贝完成后再开始计算。计算完成后，应用再将输出数据从设备端拷贝回主机端。

在整个执行过程中，runtime与驱动层紧密协作。驱动层负责将runtime提交的任务转换为硬件指令，并调度到具体的计算单元执行。runtime不需要关心硬件指令的具体格式，只需要按照约定的接口传递任务参数。驱动层还负责处理硬件中断和错误报告，当设备发生异常时，驱动会将错误信息传递给runtime，由runtime向上层应用报告。

runtime还与CANN的其他组件有交互。比如，与DVPP（数字视频预处理）组件协作时，runtime负责管理DVPP的通道资源和内存缓冲区，使得视频解码、图像预处理等操作可以与模型推理无缝衔接。与HCCL（集合通信库）协作时，runtime负责管理多卡通信所需的内存和同步资源，支持分布式训练和推理场景。

典型使用场景与配置方法

runtime的使用场景可以分为设备管理、内存操作、流管理和模型执行四个方面。下面通过具体的代码示例演示每个场景的典型用法。

场景一：设备初始化与属性查询

在使用昇腾设备之前，必须先进行设备初始化。runtime提供了设备枚举和属性查询的接口，开发者可以根据需要选择目标设备。

#include <runtime/runtime_api.h>
#include <iostream>

int main() {
    // 查询系统中的设备数量
    uint32_t device_count = 0;
    aclError ret = aclrtGetDeviceCount(&device_count);
    if (ret != ACL_SUCCESS) {
        std::cerr << "Failed to get device count" << std::endl;
        return -1;
    }
    
    std::cout << "Found " << device_count << " devices" << std::endl;
    
    // 遍历所有设备并查询属性
    for (uint32_t i = 0; i < device_count; i++) {
        aclrtDeviceInfo info;
        ret = aclrtGetDeviceInfo(i, &info);
        if (ret != ACL_SUCCESS) {
            std::cerr << "Failed to get device " << i << " info" << std::endl;
            continue;
        }
        std::cout << "Device " << i << ": " << info.name 
                  << ", Memory: " << info.total_memory / (1024*1024) << "MB" << std::endl;
    }
    
    // 激活设备0
    ret = aclrtSetDevice(0);
    if (ret != ACL_SUCCESS) {
        std::cerr << "Failed to set device 0" << std::endl;
        return -1;
    }
    
    std::cout << "Device 0 activated" << std::endl;
    
    // 释放设备资源
    aclrtResetDevice(0);
    return 0;
}

这段代码演示了设备管理的完整流程。首先调用aclrtGetDeviceCount获取系统中可用的设备数量，这是多卡场景下负载均衡的基础。然后通过aclrtGetDeviceInfo查询每个设备的属性，包括设备名称和内存大小，这些信息可以帮助开发者根据模型规模选择合适的设备。最后调用aclrtSetDevice激活目标设备，后续的所有操作都会在这个设备上执行。使用完毕后，调用aclrtResetDevice释放设备资源，这是良好的编程习惯，可以避免资源泄露。注意，aclrtSetDevice是进程级别的操作，每个进程需要单独调用，且同一个进程内切换设备会产生较大的开销，建议在初始化时确定目标设备并保持不变。

场景二：设备内存分配与数据拷贝

设备内存的管理是runtime使用中最频繁的操作之一。开发者需要在主机端准备数据，然后拷贝到设备端进行计算。

#include <runtime/runtime_api.h>
#include <cstdlib>

int main() {
    aclrtSetDevice(0);
    
    // 主机端数据准备
    size_t data_size = 1024 * 1024 * sizeof(float);  // 4MB
    float* host_data = (float*)malloc(data_size);
    for (int i = 0; i < 1024*1024; i++) {
        host_data[i] = static_cast<float>(i) / 1000.0f;
    }
    
    // 设备端内存分配
    void* device_ptr = nullptr;
    aclError ret = aclrtMalloc(&device_ptr, data_size, ACL_MEM_MALLOC_NORMAL_ONLY);
    if (ret != ACL_SUCCESS) {
        std::cerr << "Failed to allocate device memory" << std::endl;
        free(host_data);
        return -1;
    }
    
    // 同步数据拷贝
    ret = aclrtMemcpy(device_ptr, data_size, host_data, data_size, ACL_MEMCPY_HOST_TO_DEVICE);
    if (ret != ACL_SUCCESS) {
        std::cerr << "Failed to copy data to device" << std::endl;
        aclrtFree(device_ptr);
        free(host_data);
        return -1;
    }
    
    std::cout << "Data copied to device successfully" << std::endl;
    
    // 释放资源
    aclrtFree(device_ptr);
    free(host_data);
    aclrtResetDevice(0);
    return 0;
}

这段代码展示了主机端到设备端的数据传输流程。首先在主机端分配内存并初始化数据，这部分使用的是普通的malloc函数，内存可能被操作系统换出到磁盘。然后调用aclrtMalloc在设备端分配内存，ACL_MEM_MALLOC_NORMAL_ONLY表示分配普通设备内存，不与主机共享地址空间。接着调用aclrtMemcpy进行数据拷贝，ACL_MEMCPY_HOST_TO_DEVICE明确指定拷贝方向。这里的拷贝是同步的，会阻塞主机端直到拷贝完成。在性能敏感的场景下，可以使用异步拷贝接口配合流机制实现拷贝与计算的重叠。最后，设备内存和主机内存都需要显式释放，runtime不会自动回收。在实际项目中，建议使用锁页内存（aclrtMallocHost接口）代替普通malloc，可以显著提升数据传输速度。

场景三：流管理与并发执行

流是runtime实现并发控制的核心机制。通过合理使用流，可以让数据拷贝与计算并行执行，提升整体性能。

#include <runtime/runtime_api.h>
#include <iostream>

int main() {
    aclrtSetDevice(0);
    
    // 创建两个流
    aclrtStream copy_stream = nullptr;
    aclrtStream compute_stream = nullptr;
    aclrtCreateStream(&copy_stream);
    aclrtCreateStream(&compute_stream);
    
    // 创建事件用于同步
    aclrtEvent copy_done = nullptr;
    aclrtCreateEvent(&copy_done);
    
    // 分配内存
    size_t data_size = 1024 * 1024 * sizeof(float);
    void* device_input = nullptr;
    void* device_output = nullptr;
    float* host_input = (float*)malloc(data_size);
    float* host_output = (float*)malloc(data_size);
    
    aclrtMalloc(&device_input, data_size, ACL_MEM_MALLOC_NORMAL_ONLY);
    aclrtMalloc(&device_output, data_size, ACL_MEM_MALLOC_NORMAL_ONLY);
    
    // 异步数据拷贝（在copy_stream中执行）
    aclrtMemcpyAsync(device_input, data_size, host_input, data_size, 
                     ACL_MEMCPY_HOST_TO_DEVICE, copy_stream);
    
    // 记录事件，表示拷贝完成
    aclrtRecordEvent(copy_done, copy_stream);
    
    // 计算流等待拷贝完成
    aclrtStreamWaitEvent(compute_stream, copy_done);
    
    // 提交计算任务（在compute_stream中执行）
    // 这里假设有一个模型执行函数，实际使用时替换为具体的模型推理调用
    // ModelExecute(compute_stream, device_input, device_output);
    
    std::cout << "Tasks submitted to streams" << std::endl;
    
    // 等待计算完成
    aclrtSynchronizeStream(compute_stream);
    
    // 异步拷贝结果回主机
    aclrtMemcpyAsync(host_output, data_size, device_output, data_size,
                     ACL_MEMCPY_DEVICE_TO_HOST, copy_stream);
    aclrtSynchronizeStream(copy_stream);
    
    std::cout << "Execution completed" << std::endl;
    
    // 清理资源
    aclrtDestroyEvent(copy_done);
    aclrtDestroyStream(copy_stream);
    aclrtDestroyStream(compute_stream);
    aclrtFree(device_input);
    aclrtFree(device_output);
    free(host_input);
    free(host_output);
    aclrtResetDevice(0);
    return 0;
}

这段代码演示了流和事件的使用方法，是实现高性能推理的关键技术。首先创建两个流：copy_stream专门负责数据传输，compute_stream专门负责计算。两个流可以并行执行，互不干扰。然后创建一个事件copy_done，用于标记数据拷贝的完成状态。在copy_stream中提交异步拷贝任务后，立即调用aclrtRecordEvent记录事件。此时事件还未触发，因为拷贝可能还在进行中。接下来在compute_stream中调用aclrtStreamWaitEvent，让计算流等待拷贝事件完成。这个等待是非阻塞的，只是建立了一个依赖关系，compute_stream会在copy_stream完成拷贝后才开始执行。通过这种方式，数据拷贝和后续计算任务的准备工作可以重叠进行。最后调用aclrtSynchronizeStream同步等待计算完成，这是主机端的阻塞操作，确保结果可用后再继续。在实际项目中，通常会将输入拷贝、计算、输出拷贝形成流水线，多个推理请求可以并发处理，大幅提升吞吐量。

场景四：模型加载与推理执行

runtime与离线模型的交互是实际应用中最常见的场景。下面演示模型加载和推理执行的完整流程。

#include <runtime/runtime_api.h>
#include <iostream>

int main() {
    // 初始化运行时
    aclError ret = aclInit(nullptr);
    if (ret != ACL_SUCCESS) {
        std::cerr << "Failed to initialize runtime" << std::endl;
        return -1;
    }
    
    aclrtSetDevice(0);
    
    // 加载离线模型
    uint32_t model_id = 0;
    ret = aclmdlLoadFromFile("model.om", &model_id);
    if (ret != ACL_SUCCESS) {
        std::cerr << "Failed to load model" << std::endl;
        aclFinalize();
        return -1;
    }
    
    // 获取模型描述信息
    aclmdlDesc* model_desc = aclmdlCreateDesc();
    ret = aclmdlGetDesc(model_desc, model_id);
    if (ret != ACL_SUCCESS) {
        std::cerr << "Failed to get model desc" << std::endl;
        aclmdlUnload(model_id);
        aclFinalize();
        return -1;
    }
    
    // 查询输入输出信息
    size_t input_num = aclmdlGetNumInputs(model_desc);
    size_t output_num = aclmdlGetNumOutputs(model_desc);
    std::cout << "Model has " << input_num << " inputs, " 
              << output_num << " outputs" << std::endl;
    
    // 创建输入输出数据集
    aclmdlDataset* input_dataset = aclmdlCreateDataset();
    aclmdlDataset* output_dataset = aclmdlCreateDataset();
    
    // 为输入分配内存并添加到数据集
    for (size_t i = 0; i < input_num; i++) {
        aclmdlIODims dims;
        aclmdlGetInputDims(model_desc, i, &dims);
        size_t buffer_size = aclmdlGetInputSizeByIndex(model_desc, i);
        
        void* buffer = nullptr;
        aclrtMalloc(&buffer, buffer_size, ACL_MEM_MALLOC_NORMAL_ONLY);
        
        aclDataBuffer* data_buffer = aclCreateDataBuffer(buffer, buffer_size);
        aclmdlAddDatasetBuffer(input_dataset, data_buffer);
    }
    
    // 为输出分配内存
    for (size_t i = 0; i < output_num; i++) {
        size_t buffer_size = aclmdlGetOutputSizeByIndex(model_desc, i);
        void* buffer = nullptr;
        aclrtMalloc(&buffer, buffer_size, ACL_MEM_MALLOC_NORMAL_ONLY);
        
        aclDataBuffer* data_buffer = aclCreateDataBuffer(buffer, buffer_size);
        aclmdlAddDatasetBuffer(output_dataset, data_buffer);
    }
    
    // 执行推理
    ret = aclmdlExecute(model_id, input_dataset, output_dataset);
    if (ret != ACL_SUCCESS) {
        std::cerr << "Failed to execute model" << std::endl;
    } else {
        std::cout << "Inference completed successfully" << std::endl;
    }
    
    // 清理资源
    aclmdlDestroyDataset(input_dataset);
    aclmdlDestroyDataset(output_dataset);
    aclmdlDestroyDesc(model_desc);
    aclmdlUnload(model_id);
    aclFinalize();
    return 0;
}

这段代码展示了离线模型推理的完整生命周期。首先调用aclInit初始化runtime全局状态，这是使用其他runtime接口的前提。然后通过aclmdlLoadFromFile加载.om格式的离线模型文件，返回的model_id是模型的唯一标识。加载后，调用aclmdlGetDesc获取模型描述信息，包括输入输出的数量、维度、数据类型等。根据这些信息，创建输入输出数据集，并为每个输入输出分配设备内存。内存大小可以通过aclmdlGetInputSizeByIndex和aclmdlGetOutputSizeByIndex查询，这两个接口考虑了模型的具体配置，包括内存对齐、中间结果缓冲等因素。准备好数据后，调用aclmdlExecute执行推理，这是一个同步接口，会阻塞直到推理完成。如果需要异步执行，可以传递流参数。推理完成后，输出数据已经写入输出数据集对应的设备内存，可以通过拷贝接口取回主机端。最后，依次释放数据集、模型描述、卸载模型，并调用aclFinalize关闭runtime。这个顺序很重要，先释放依赖资源，再卸载模型，最后关闭runtime，避免悬空指针和资源泄露。

技术边界与适用场景分析

runtime运行时库虽然功能强大，但并非适用于所有场景。理解其技术边界，可以帮助开发者在合适的场景下发挥其价值，避免不必要的复杂度。

runtime不适合的场景主要包括：纯CPU计算任务、小批量数据的简单处理、对实时性要求极高的边缘场景。对于纯CPU计算任务，如传统的数值计算、字符串处理等，runtime提供的设备加速反而会带来额外的数据传输开销，得不偿失。对于小批量数据的简单处理，数据在主机和设备之间往返的时间可能比计算本身还长，此时使用CPU直接处理更高效。对于对实时性要求极高的边缘场景，比如自动驾驶的实时感知，runtime的初始化和模型加载可能需要几秒到几十秒的时间，不适合冷启动场景，需要预先加载并常驻内存。

runtime最适合的场景包括：大模型的训练和推理、批量数据的预处理和后处理、多卡并行计算、对吞吐量有要求的在线服务。在大模型场景下，计算密集型任务占据了主要时间，数据传输开销相对较小，runtime的并发机制和内存池优化能够显著提升性能。在多卡场景下，runtime提供了设备管理接口，可以灵活指定计算目标设备，配合HCCL实现分布式训练和推理。在在线服务场景下，通过流管理和异步执行，可以实现高吞吐的推理服务，充分利用设备算力。

还需要注意，runtime是底层接口，直接使用需要处理很多细节。对于大多数AI应用开发者来说，通过框架层（如TensorFlow、PyTorch）间接使用runtime是更推荐的方式。框架层封装了runtime的复杂性，提供了更友好的API。只有在需要深度定制、性能调优或者调试底层问题时，才需要直接使用runtime接口。

使用前后的效率对比

在没有使用runtime的场景下，开发者需要通过驱动层直接与硬件交互，这意味着需要手动管理设备句柄、解析硬件指令格式、处理硬件中断和错误状态。驱动的接口通常比较底层，参数众多且容易出错。同时，每次内存分配都需要向驱动申请，缺乏内存池机制，在小内存频繁分配的场景下性能较差。任务提交也是串行的，无法利用设备内部的并行能力，整体吞吐量受限。

使用runtime后，设备管理变得更加简单，几个接口调用就能完成设备的初始化和激活。内存管理方面，runtime内部的内存池机制减少了与驱动交互的次数，内存分配和释放的延迟显著降低。通过流和事件机制，开发者可以轻松实现数据传输与计算的重叠，设备利用率大幅提升。对于多卡场景，runtime提供了统一的设备管理接口，不需要关心不同型号设备的差异，代码的可移植性更好。

从开发效率角度看，使用runtime可以让开发者将精力集中在业务逻辑上，而不是底层细节。runtime提供的错误码和日志信息也更容易理解和调试。从运行效率角度看，runtime的内存池、流并发、异步执行等优化机制，能够充分发挥硬件的并行能力，在典型场景下显著提升吞吐量和降低延迟。

总结

runtime运行时库作为CANN软件栈的核心组件，承担着设备管理、内存调度、流控制和算子执行的重要职责。通过本文的介绍和示例代码，相信读者已经对runtime的使用方法有了基本的了解。从设备初始化到模型推理，runtime提供了完整的接口体系，能够满足各类AI应用的需求。

官方仓库 https://atomgit.com/cann/runtime

Logo
鲲鹏昇腾开发者社区是面向全社会开放的“联接全球计算开发者，聚合华为+生态”的社区，内容涵盖鲲鹏、昇腾资源，帮助开发者快速获取所需的知识、经验、软件、工具、算力，支撑开发者易学、好用、成功，成为核心开发者。

鲲鹏昇腾开发者社区是面向全社会开放的“联接全球计算开发者，聚合华为+生态”的社区，内容涵盖鲲鹏、昇腾资源，帮助开发者快速获取所需的知识、经验、软件、工具、算力，支撑开发者易学、好用、成功，成为核心开发者。

更多推荐

cover

深入解析昇腾CANN开源项目atvoss（ATVOSS），基于Ascend C的Vector算子模板库，提供手把手实战教程与可视化分析指南

avatar 鲲鹏昇腾开发者社区
cover

CANN技术解读｜hcomm通信库主机侧网络优化与零拷贝技术：深入剖析分布式训练通信瓶颈的高效解决方案

avatar 鲲鹏昇腾开发者社区
cover

CANN架构解析｜graph-autofusion算子自动融合框架的设计原理与工程实现全链路深度解读

avatar 鲲鹏昇腾开发者社区