第5章 模型部署与推理

5.1 代码生成

STM32Cube.AI的代码生成是将训练完成的神经网络模型转换为可在STM32微控制器上高效运行的C代码的关键步骤。这一过程涉及模型解析、图优化、算子映射、内存规划等多个环节，是整个部署流程中最核心的技术环节。

5.1.1 STM32Cube.AI代码生成流程

代码生成流程可以概括为以下主要阶段：

1. 模型导入与验证 — 将训练好的模型（.tflite、.onnx、.h5等格式）导入STM32Cube.AI工具链。工具首先进行模型格式验证，检查算子兼容性，确认所有层类型都在目标芯片的支持列表中。
2. 图优化（Graph Optimization） — 对计算图进行优化，包括常量折叠（Constant Folding）、死代码消除（Dead Code Elimination）、算子融合（Operator Fusion）等。例如将Conv2D + BatchNormalization融合为单个卷积操作，减少运行时计算量。
3. 算子映射（Operator Mapping） — 将高层框架中的算子映射为STM32Cube.AI内部支持的底层算子。每种算子都有针对ARM Cortex-M架构优化的C实现，充分利用CMSIS-NN库的加速函数。
4. 内存规划（Memory Planning） — 分析各层激活值的生命周期，通过内存复用技术最小化RAM占用。采用"峰值内存"优化算法，确保在有限的SRAM中完成推理。
5. 代码生成（Code Generation） — 生成标准化的C99源代码文件，包括网络结构定义、权重数据、推理函数等。生成的代码不依赖任何外部库（除CMSIS-NN可选加速外），可直接编译。
6. 验证与报告 — 对生成的代码进行数值验证，确保推理输出与原始模型一致（在量化误差范围内）。同时生成详细的资源使用报告。

5.1.2 生成的C代码结构

STM32Cube.AI生成的代码通常包含以下文件：

以下是一个典型的生成代码头文件结构示例：

/* network.h - 自动生成的网络接口 */
#ifndef NETWORK_H
#define NETWORK_H

#include "ai_platform.h"
#include "ai_datatypes.h"

/* 网络参数宏定义 */
#define AI_NETWORK_MODEL_NAME          "network"
#define AI_NETWORK_IN_NUM              (1)
#define AI_NETWORK_OUT_NUM             (1)

/* 输入/输出张量信息 */
#define AI_NETWORK_IN_1_HEIGHT         (32)
#define AI_NETWORK_IN_1_WIDTH          (32)
#define AI_NETWORK_IN_1_CHANNEL        (1)
#define AI_NETWORK_OUT_1_SIZE          (10)

/* API函数声明 */
AI_EXPORTED ai_error ai_network_create(
    ai_handle* network,
    const ai_buffer* network_config);

AI_EXPORTED ai_u32 ai_network_get_n_inputs(
    ai_handle network);

AI_EXPORTED ai_u32 ai_network_get_n_outputs(
    ai_handle network);

AI_EXPORTED ai_bool ai_network_run(
    ai_handle network,
    const ai_buffer* input,
    ai_buffer* output);

AI_EXPORTED ai_error ai_network_destroy(
    ai_handle network);

#endif /* NETWORK_H */

5.1.3 生成参数配置

在代码生成过程中，需要配置以下关键参数：

5.1.4 代码生成的内部机制

理解代码生成的内部机制有助于我们更好地优化部署效果：

图优化（Graph Optimization）是代码生成的第一步。工具对导入的计算图执行多种优化Pass：

• 常量折叠：将可以在编译期计算的表达式提前求值，减少运行时计算
• 算子融合：将Conv2D + BN + ReLU融合为单个"ConvBNReLU"算子，减少内存读写和中间结果存储
• 死节点消除：移除对最终输出没有贡献的计算节点
• Transpose优化：将NCHW格式转换为NHWC格式（ARM处理器对NHWC有更好的支持）

算子融合是最关键的优化手段。以典型的CNN层为例，融合前后的对比：

内存规划采用贪心算法，通过分析各层激活值的"活跃区间"（从产生到最后一次使用），将生命周期不重叠的激活值分配到同一内存区域。这种技术可以将峰值内存需求降低30%-60%。

5.1.5 验证生成代码的正确性

代码生成后，必须进行严格的正确性验证：

1. 数值一致性验证：使用相同的测试输入，比较PC端模型推理结果和生成代码的推理结果。在量化误差允许范围内（通常INT8量化误差<1%），两者应一致。
2. 边界条件测试：测试全零输入、全一输入、随机噪声输入等边界情况，确保代码不会崩溃或产生异常输出。
3. 内存安全检查：使用STM32的硬件内存保护单元（MPU）或AddressSanitizer工具检查是否存在越界访问。
4. 长时间运行测试：连续运行数千次推理，检查是否存在内存泄漏或累积误差。

5.2 C代码集成

生成C代码后，下一步是将其集成到STM32CubeIDE项目中，编写应用层代码来调用AI推理引擎。这一步需要理解API调用规范、数据格式要求和内存管理策略。

5.2.1 将生成的AI代码集成到STM32CubeIDE项目

集成步骤如下：

1. 复制生成文件：将STM32Cube.AI生成的所有.c和.h文件复制到项目的App/或AI/目录下。
2. 配置包含路径：在STM32CubeIDE的项目属性中，添加生成文件所在目录到C/C++ Include Paths。
3. 添加CMSIS-NN库：如果使用硬件加速，需要引入CMSIS-NN库。在项目中添加ARM/CMSIS/CMSIS-NN/Include和Source目录。
4. 配置编译器选项：确保启用C99标准（-std=c99），并根据目标芯片选择合适的优化级别（推荐-O2或-O3）。
5. 链接配置：确保链接器脚本（.ld文件）分配了足够的RAM和Flash空间。AI模型通常需要较大的Flash空间存储权重数据。
6. 编译验证：首次编译可能遇到头文件依赖问题，需要按照编译错误提示逐一解决。

5.2.2 关键API函数

STM32Cube.AI提供了一套简洁的C API来管理AI推理的完整生命周期：

以下是一个完整的推理调用示例：

#include "network.h"
#include "network_data.h"

/* 全局变量 */
static ai_handle network = AI_HANDLE_NULL;
static ai_buffer* ai_input;
static ai_buffer* ai_output;

/* 工作缓冲区 - 激活值内存 */
static ai_u8 scratch_buffer[AI_NETWORK_DATA_ACTIVATIONS_SIZE];

/* 初始化AI网络 */
int ai_model_init(void) {
    ai_error err;
    const ai_network_params params = {
        AI_NETWORK_DATA_WEIGHTS(ai_network_data_params),
        AI_NETWORK_DATA_CONFIG(ai_network_data_config)
    };

    /* 创建网络实例 */
    err = ai_network_create(&network,
        AI_NETWORK_DATA_CONFIG(ai_network_data_config));

    if (err.type != AI_ERROR_NONE) {
        printf("AI创建错误: type=0x%x, code=0x%x\n",
               err.type, err.code);
        return -1;
    }

    /* 初始化网络 */
    if (ai_network_init(network, &params) == false) {
        printf("AI初始化失败\n");
        ai_network_destroy(network);
        return -1;
    }

    /* 获取输入/输出缓冲区信息 */
    ai_input = ai_network_get_input(network);
    ai_output = ai_network_get_output(network);

    return 0;
}

/* 执行推理 */
int ai_model_inference(float* input_data, float* output_data) {
    /* 填充输入缓冲区 */
    ai_input_fill(ai_input, input_data,
                  AI_NETWORK_IN_1_SIZE);

    /* 执行前向推理 */
    if (ai_network_run(network, ai_input,
                       ai_output) == false) {
        printf("推理失败\n");
        return -1;
    }

    /* 读取输出结果 */
    ai_output_read(ai_output, output_data,
                   AI_NETWORK_OUT_1_SIZE);
    return 0;
}

5.2.3 输入数据缓冲区准备

输入数据的格式直接影响推理的正确性。以下是关键注意事项：

/* 图像数据准备示例 (32x32灰度图, INT8量化) */
#define IMG_W    32
#define IMG_H    32
#define SCALE    0.00392f   /* 1/255 */
#define ZERO_PT  -128

__ALIGNED(4) int8_t input_buffer[IMG_W * IMG_H];

void prepare_camera_input(int8_t* buf) {
    uint8_t raw[IMG_W * IMG_H];
    camera_capture(raw);  /* 从摄像头获取原始数据 */

    for (int i = 0; i < IMG_W * IMG_H; i++) {
        /* 归一化到[0,1]再量化到INT8 */
        float normalized = raw[i] * SCALE;
        buf[i] = (int8_t)(normalized / SCALE + ZERO_PT);
    }
}

5.2.4 输出数据解析

推理输出的数据需要根据模型类型进行解析：

分类模型：输出为各类别的概率值（经过Softmax）或logits（未经Softmax）。需要找到最大值对应的类别索引：

/* 分类结果解析 */
int get_predicted_class(float* output, int num_classes) {
    int max_idx = 0;
    float max_val = output[0];
    for (int i = 1; i < num_classes; i++) {
        if (output[i] > max_val) {
            max_val = output[i];
            max_idx = i;
        }
    }
    return max_idx;
}

/* INT8量化模型的输出反量化 */
float dequantize_output(int8_t q_val, float scale,
                        int32_t zero_point) {
    return (q_val - zero_point) * scale;
}

5.2.5 内存管理策略

嵌入式系统的内存极其有限，合理的内存管理策略至关重要：

5.3 推理执行与调试

将模型集成到项目后，需要确保推理过程正确、高效地运行。本节介绍完整的推理流程、性能测试方法、常见错误排查以及调试技巧。

5.3.1 推理流程详解

一次完整的AI推理包含以下阶段：

1. 初始化阶段（ai_init）：创建网络实例，加载权重数据到RAM（或配置XIP从Flash直接执行），分配激活值缓冲区。此阶段只需执行一次，通常在系统启动时完成。
2. 数据准备阶段（ai_input_fill）：从传感器获取数据，进行预处理（归一化、量化、格式转换），填充到AI输入缓冲区。此阶段是推理延迟的重要组成部分，特别是涉及DMA传输或复杂预处理时。
3. 前向推理阶段（ai_run）：执行模型的所有层计算。数据从输入层开始，逐层经过卷积、激活、池化等运算，最终到达输出层。这是CPU占用最高的阶段。
4. 结果解析阶段（ai_output_read）：从输出缓冲区读取推理结果，进行反量化（如果需要）、Softmax转换、类别映射等后处理，得到最终的应用层结果。

5.3.2 推理性能测试方法

准确测量推理性能是优化的前提。以下是两种常用的测时方法：

方法一：DWT周期计数器

/* 使用DWT Cycle Counter精确测时 */
volatile uint32_t *DWT_CYCCNT = (uint32_t *)0xE0001004;
volatile uint32_t *DWT_CONTROL = (uint32_t *)0xE0001000;
volatile uint32_t *SCB_DEMCR = (uint32_t *)0xE000EDFC;

void dwt_init(void) {
    *SCB_DEMCR |= 0x01000000;  /* 使能DWT */
    *DWT_CONTROL |= 1;          /* 使能计数器 */
}

uint32_t measure_inference_time(void) {
    uint32_t start, end, cycles;

    dwt_init();
    start = *DWT_CYCCNT;

    ai_network_run(network, ai_input, ai_output);

    end = *DWT_CYCCNT;
    cycles = end - start;

    /* 转换为微秒 (假设主频168MHz) */
    uint32_t us = cycles / (SystemCoreClock / 1000000);
    printf("推理耗时: %lu us (%lu cycles)\n", us, cycles);
    return cycles;
}

方法二：GPIO翻转测时

/* GPIO翻转 + 示波器测时 */
void inference_with_timing_pin(void) {
    HAL_GPIO_WritePin(GPIOB, GPIO_PIN_0, GPIO_PIN_SET);

    ai_network_run(network, ai_input, ai_output);

    HAL_GPIO_WritePin(GPIOB, GPIO_PIN_0, GPIO_PIN_RESET);
    /* 用示波器测量PB0高电平持续时间即为推理时间 */
}

5.3.3 常见推理错误排查

5.3.4 调试技巧

使用Serial打印调试信息是最直接的调试方式。在关键位置插入printf语句，通过SWD或UART输出到PC端串口助手：

/* 逐层调试：打印中间激活值 */
void debug_layer_outputs(void) {
    /* 使用ai_forward逐层执行 */
    for (int layer = 0; layer < n_layers; layer++) {
        ai_network_forward(network, layer);

        /* 获取当前层输出 */
        ai_buffer* layer_out = get_layer_output(network, layer);
        float* data = (float*)layer_out->data;

        printf("Layer %d: ", layer);
        for (int i = 0; i < 5; i++) {  /* 打印前5个值 */
            printf("%.4f ", data[i]);
        }
        printf("\n");
    }
}

使用STM32CubeMonitor可以进行非侵入式实时监控。通过SWD接口读取变量值，无需在代码中插入任何调试语句，特别适合生产环境中的性能监控。

5.3.5 实际案例

5.4 性能分析与优化

在嵌入式AI部署中，性能优化是永恒的主题。有限的计算资源（CPU频率、RAM、Flash）要求我们在推理速度、内存占用和精度之间找到最佳平衡点。

5.4.1 推理时间分析

推理时间（Inference Latency）是衡量AI系统实时性的关键指标。一次推理的总时间可以分解为：

总推理时间 = 数据预处理 + 各层计算 + 后处理
           = T_pre + Σ(T_layer_i) + T_post

对于大多数模型，卷积层通常占总推理时间的70%-90%。因此，优化卷积运算的性能是提升推理速度的关键。

每层耗时分解是性能分析的基础。STM32Cube.AI支持逐层性能分析模式：

/* 逐层耗时分析 */
void profile_layers(void) {
    uint32_t total_cycles = 0;
    uint32_t layer_cycles[MAX_LAYERS];

    for (int i = 0; i < n_layers; i++) {
        uint32_t start = *DWT_CYCCNT;
        ai_network_forward(network, i);
        uint32_t end = *DWT_CYCCNT;
        layer_cycles[i] = end - start;
        total_cycles += layer_cycles[i];
    }

    printf("=== 层耗时分析 ===\n");
    for (int i = 0; i < n_layers; i++) {
        float pct = 100.0f * layer_cycles[i] / total_cycles;
        printf("Layer %2d: %8lu cycles (%5.1f%%)\n",
               i, layer_cycles[i], pct);
    }
    printf("总计: %lu cycles (%.2f ms @ %lu MHz)\n",
           total_cycles,
           total_cycles / (SystemCoreClock / 1000000.0f),
           SystemCoreClock / 1000000);
}

5.4.2 内存占用分析

嵌入式AI系统的内存占用分为以下几个部分：

5.4.3 优化策略

算子融合是最有效的优化手段之一。通过融合相邻算子，可以减少内存访问次数（嵌入式系统中内存访问的能耗远高于计算本身）：

• Conv + BN + Activation → 融合算子（减少2次内存读写）
• MatMul + Bias + Activation → 融合全连接（减少1次内存读写）
• 多个小卷积 → 分组卷积（减少参数和计算量）

内存复用通过生命周期分析，让不重叠的激活值共享内存区域：

/* 内存复用示意 */
/* 层1的输出在层2计算后不再需要 */
/* 层3的激活值可以复用层1的内存空间 */

/* 优化前：每层独立内存 */
/* Layer1: [0-999], Layer2: [1000-1999], Layer3: [2000-2999] */
/* 峰值RAM = 3000 */

/* 优化后：内存复用 */
/* Layer1: [0-999], Layer2: [1000-1999], Layer3: [0-999] */
/* 峰值RAM = 2000（节省33%）*/

DMA加速可以将CPU从数据搬运中解放出来：

• 使用DMA将传感器数据直接传输到输入缓冲区，CPU可以并行执行其他任务
• 使用DMA双缓冲机制，在推理当前帧的同时采集下一帧数据
• 对于外部RAM中的权重数据，使用DMA预取到内部缓存中

5.4.4 功耗优化

对于电池供电的AIoT设备，功耗优化与性能优化同等重要：

/* DVFS功耗优化策略 */
void inference_with_dvfs(void) {
    /* 推理前：升频到最高性能 */
    HAL_RCC_ClockConfig(&HighPerfClockConfig);

    /* 执行推理 */
    ai_network_run(network, ai_input, ai_output);

    /* 推理后：降频到低功耗模式 */
    HAL_RCC_ClockConfig(&LowPowerClockConfig);

    /* 处理结果... */
    process_result();
}

5.4.5 基准测试：不同STM32芯片上的推理性能对比

以下数据基于STM32Cube.AI基准测试（典型模型，INT8量化）：

本章小结

章节测验