数据分类 SDK 的架构与核心模块

这一章，咱们直接聊点实在的：数据分类 SDK 到底长什么样？它的骨架是怎么搭的？

我刚开始接触 SDK 设计时，喜欢把代码揉成一团，觉得能跑就行。结果后面做兼容适配，差点把自己整崩溃。所以今天，我带你拆透它的核心架构。

说白了，一个成熟的数据分类 SDK，它的工作流是一条清晰的流水线：输入 → 预处理 → 推理 → 后处理。每一步都有独立的模块，耦合低，好替换。

1. 输入模块：数据入口的“守门员”

输入模块的作用很简单——接收外部数据，做基础校验，再转成内部统一格式。

你想想看，外界传来的数据可能是图片路径、Bitmap、ByteBuffer，甚至直接是一个 Uri。如果每个模块都去处理这些五花八门的格式，代码会变得一团糟。

• 数据源抽象：通过 DataSource 接口统一管理，支持多种数据源灵活切换。
• 格式校验：检查数据是否为空、格式是否合法、大小是否越界。我曾经遇到过，传了个空指针进来，SDK 直接崩溃，用户反馈“一打开就闪退”。后来我加了一层校验，问题就解决了。
• 类型转换：把外部类型转成内部统一的 InputData 对象。比如 Bitmap 转成 RGB 字节数组。

2. 预处理模块：把数据“喂”给模型

预处理模块是数据进入模型前的最后一道工序。这里做的事，直接决定了推理结果的准确度。

我见过不少开发者，预处理写得很随便，以为“反正模型能处理”。结果模型跑出来的结果，跟训练时差了一大截。为什么？因为线上数据的分布，跟训练集不一样了。

1. 尺寸调整：把输入缩放到模型要求的固定尺寸。注意保持宽高比，不足的部分用 padding 填充。
2. 像素值归一化：把 [0, 255] 的像素值映射到 [0, 1] 或 [-1, 1] 区间，这模型才能“吃”得舒服。
3. 通道转换：Android 默认的 Bitmap 是 ARGB 格式，但大部分模型要 RGB。这个转换要小心，不然颜色就反了。
4. 数据类型转换：uint8 转 float32，这一步通常会丢精度。

3. 推理引擎：核心算力的“发动机”

推理引擎是整个 SDK 最核心的部分。它负责加载模型，执行推理计算，输出原始结果。

说白了吧，推理引擎就是个“解释器”，把模型文件里的数学运算，搬到硬件上去跑。但它要跑得快，跑得稳，还要兼容各种 Android 设备。

• 模型加载：从 assets 或文件系统加载 .tflite / .onnx 等模型文件。加载后做一次基础校验，检查模型版本和输入输出节点。
• 硬件加速选择：根据设备能力自动挑选 CPU、GPU、NNAPI 或 DSP。我在项目中遇到过，同一款模型在骁龙 8 Gen 1 上跑 GPU 飞快，在联发科设备上却直接报错。所以最好做一个回退机制：GPU 不行就切 CPU。
• 推理执行：调用 Interpreter 的 run 方法，传入预处理后的数据，拿到 float 数组。
• 性能监控：记录推理耗时、内存占用。嗯，这里要注意，不要在主线程跑推理，否则 ANR 等着你。

4. 后处理模块：把机器语言变成人话

推理引擎吐出来的，通常是一堆 float 数组。后处理模块的任务，就是把这些数字变回有意义的结果。

举个例子，分类模型输出一个长度为 1000 的 float 数组，代表 1000 个类别的置信度。后处理要做的是：找到置信度最高的前 N 个类别，给出对应的标签名和概率值。

1. Softmax / Sigmoid 计算：把原始得分映射到 [0, 1] 概率区间。
2. Top-K 筛选：取概率最高的 K 个结果，降低输出数据量。
3. 标签映射：把类别索引转为可读的字符串标签。这里要注意，不同模型的标签顺序可能不一样。
4. 阈值过滤：低于置信度阈值的结果直接丢弃，避免输出低质量的预测。

5. 模块间的协作与数据流

这几个模块不是孤立的，它们串成一条完整的 Pipeline。数据从输入模块进来，经过预处理、推理、后处理，最后输出结果。

我个人喜欢用接口定义每个模块的输入输出，再通过一个 Pipeline 编排器把它们串联起来。这样，每个模块都可以单独替换和测试，方便得很。

// 伪代码示意：Pipeline 编排
class ClassificationPipeline {
    private val inputModule: InputModule
    private val preprocessModule: PreprocessModule
    private val inferenceEngine: InferenceEngine
    private val postprocessModule: PostprocessModule

    fun execute(rawData: Any): ClassificationResult {
        val inputData = inputModule.handle(rawData)
        val processedData = preprocessModule.process(inputData)
        val rawOutput = inferenceEngine.run(processedData)
        return postprocessModule.process(rawOutput)
    }
}

想一想，如果哪天要换一个模型，只需要替换推理引擎模块，其他部分完全不用动。这就是模块化架构带来的好处。