3、最小推理工程结构：工程目录、源码文件、构建系统（CMake/Make）、依赖管理

TFLite Micro 的推理工程虽然面向嵌入式环境，但其工程组织方式与现代软件工程实践一脉相承。理解一个最小推理工程的目录结构、源码文件划分、构建系统组织以及依赖管理方式，是后续分析 main() 到 Invoke() 调用链的基础。本章将从一个典型的端侧推理工程出发，拆解其物理结构、逻辑分层与构建流程，帮助读者建立对 TFLite Micro 工程的整体认知。

上图展示了最小推理工程的三大组成模块：工程目录、源码文件与构建系统。三者之间通过引用与编译关系相互连接，形成完整的可执行镜像。下面分别对每个模块进行深入拆解。

3.1 工程目录：物理结构与逻辑分层

核心原理

TFLite Micro 最小推理工程的目录设计遵循“分离关注点”原则。一个典型的工程目录通常包含以下层级：应用层（main.cc、业务逻辑）、模型层（model.cc/h，存放序列化模型数据）、张量管理层（tensors.cc/h，封装输入输出张量操作）、第三方依赖层（third_party/tflite-micro，包含 TFLite Micro 核心库）、构建产物层（build/，存放编译中间文件与最终可执行文件）。这种分层结构使得模型替换、算子扩展、平台移植等操作可以在不影响其他模块的前提下独立进行。

判断方法或操作流程

在创建工程目录时，建议遵循以下流程：

1. 创建顶层目录：以项目名称命名，如 my_project/。
2. 划分源码目录：将应用代码与第三方库分离，通常将 TFLite Micro 源码放在 third_party/ 下。
3. 建立构建目录：使用 build/ 目录存放 CMake 生成的中间文件，保持源码目录整洁。
4. 添加脚本目录：将编译、烧录、测试等脚本放入 scripts/，便于自动化。

案例拆解

以 STM32F746 平台上的关键词识别（KWS）工程为例，其目录结构如下：

kws_project/
├── CMakeLists.txt
├── main.cc
├── model.cc
├── model.h
├── tensors.cc
├── tensors.h
├── third_party/
│   └── tflite-micro/
│       ├── tensorflow/lite/micro/
│       ├── tensorflow/lite/schema/
│       └── ...
├── build/
│   ├── CMakeCache.txt
│   └── kws_project.elf
└── scripts/
    ├── build.sh
    └── flash.sh

其中 model.cc 包含经过量化的 int8 模型数组，tensors.cc 封装了输入特征向量的填充与输出概率的读取。这种结构使得更换模型时只需替换 model.cc 中的数组内容，而无需修改其他文件。

常见误区或总结复盘

3.2 源码文件：职责划分与关键实现

核心原理

最小推理工程的源码文件通常分为四类：入口文件（main.cc）、模型数据文件（model.cc/h）、张量封装文件（tensors.cc/h）以及核心库文件（tflite-micro 源码）。入口文件负责初始化解释器、分配张量内存、执行推理循环；模型数据文件以 C 数组形式存储 FlatBuffer 序列化后的模型；张量封装文件提供对输入输出张量的便捷访问接口；核心库文件则实现了解释器、算子注册、内存规划等底层机制。

判断方法或操作流程

在编写源码文件时，应遵循以下职责划分原则：

• main.cc：只负责初始化硬件、创建解释器、调用推理函数，不包含业务逻辑。
• model.cc/h：只包含模型数组的定义与长度声明，不包含任何推理逻辑。
• tensors.cc/h：封装输入张量的数据填充与输出张量的结果解析，提供类型安全的接口。
• 业务逻辑：如音频采集、图像预处理等，应放在独立的模块中，避免与推理代码耦合。

案例拆解

以下是一个典型的 main.cc 初始化片段：

#include "tensorflow/lite/micro/micro_interpreter.h"
#include "tensorflow/lite/micro/micro_mutable_op_resolver.h"
#include "model.h"

int main() {
  // 1. 创建算子解析器，注册需要的算子
  static tflite::MicroMutableOpResolver<10> resolver;
  resolver.AddFullyConnected();
  resolver.AddSoftmax();

  // 2. 创建解释器，传入模型数据与张量内存池
  static tflite::MicroInterpreter interpreter(
      tflite::GetModel(g_model), resolver,
      tensor_arena, kTensorArenaSize);

  // 3. 分配张量内存
  interpreter.AllocateTensors();

  // 4. 获取输入输出张量
  TfLiteTensor* input = interpreter.input(0);
  TfLiteTensor* output = interpreter.output(0);

  // 5. 执行推理
  interpreter.Invoke();
  return 0;
}

这段代码展示了从创建解释器到调用 Invoke() 的完整流程。其中 tensor_arena 是预先分配的静态内存池，大小由模型需求决定。

常见误区或总结复盘

3.3 构建系统：CMake 与 Make 的工程组织

核心原理

TFLite Micro 官方推荐使用 CMake 作为构建系统，因为它支持交叉编译、依赖管理和多平台生成。CMake 通过 CMakeLists.txt 文件描述工程结构，生成适用于不同平台的构建文件（如 Makefile、Ninja、Visual Studio 工程等）。对于嵌入式开发，CMake 可以方便地指定交叉编译工具链，并通过 add_subdirectory() 引入 TFLite Micro 核心库。

判断方法或操作流程

一个最小推理工程的 CMakeLists.txt 通常包含以下关键步骤：

1. 指定 CMake 最低版本：cmake_minimum_required(VERSION 3.16)
2. 定义工程名称：project(kws_project CXX C)
3. 引入 TFLite Micro 子目录：add_subdirectory(third_party/tflite-micro)
4. 添加可执行目标：add_executable(kws_project main.cc model.cc tensors.cc)
5. 链接核心库：target_link_libraries(kws_project tensorflow-lite-micro)
6. 设置编译选项：如 -DTF_LITE_STATIC_MEMORY 启用静态内存模式。

案例拆解

以下是一个完整的 CMakeLists.txt 示例：

cmake_minimum_required(VERSION 3.16)
project(kws_project CXX C)

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 引入 TFLite Micro 核心库
add_subdirectory(third_party/tflite-micro)

# 添加可执行目标
add_executable(kws_project
  main.cc
  model.cc
  tensors.cc
)

# 链接 TFLite Micro 库
target_link_libraries(kws_project tensorflow-lite-micro)

# 启用静态内存模式，减少动态分配
target_compile_definitions(kws_project PRIVATE TF_LITE_STATIC_MEMORY)

# 优化级别
target_compile_options(kws_project PRIVATE -O2)

对于使用 Make 的工程，TFLite Micro 也提供了 Makefile 支持，但 CMake 在依赖管理和跨平台方面更具优势。建议新工程优先使用 CMake。

常见误区或总结复盘

3.4 依赖管理：版本锁定与第三方库集成

核心原理

TFLite Micro 的依赖管理主要涉及两个方面：核心库版本锁定与平台相关依赖。核心库版本锁定通常通过 Git Submodule 或 CMake FetchContent 实现，确保所有开发者使用相同版本的 TFLite Micro 源码。平台相关依赖包括 CMSIS、HAL 库、编译器内置头文件等，这些依赖需要根据目标平台进行配置。

判断方法或操作流程

推荐使用 CMake FetchContent 进行依赖管理，流程如下：

1. 指定依赖仓库地址与版本：使用 FetchContent_Declare() 指定 TFLite Micro 的 Git 仓库 URL 和提交哈希。
2. 获取依赖：调用 FetchContent_MakeAvailable() 自动下载并添加子目录。
3. 配置平台依赖：根据目标平台设置 CMAKE_TOOLCHAIN_FILE 或添加平台相关的编译定义。

案例拆解

使用 FetchContent 管理 TFLite Micro 的 CMakeLists.txt 片段：

include(FetchContent)

FetchContent_Declare(
  tflite-micro
  GIT_REPOSITORY https://github.com/tensorflow/tflite-micro.git
  GIT_TAG 5f8e3a2b1c9d4e7f8a0b1c2d3e4f5a6b7c8d9e0f
)

FetchContent_MakeAvailable(tflite-micro)

这种方式确保了依赖版本的确定性，避免了不同开发者之间因依赖版本不一致导致的编译问题。

常见误区或总结复盘

3.5 工程结构对比与选型建议

对于 TFLite Micro 最小推理工程，强烈推荐使用 CMake 作为构建系统。它不仅能够简化依赖管理，还能通过工具链文件轻松适配不同嵌入式平台。在工程结构上，建议保持“应用层-模型层-张量层-核心库”的清晰分层，避免将业务逻辑与推理代码混在一起。