ONNX 导出与推理优化 - 技术学习笔记

一句话总结

模型文件的本质就是一堆浮点数矩阵的序列化--理解了这一点,"导出""部署""跨平台推理"就不再神秘.
本篇先解决前置认知:模型文件是什么,存在哪,为什么能搬到别的机器上用.

前置知识:模型文件的本质

在开始讲 ONNX 导出之前,先搞清楚一个基础问题:下载/训练出来的"模型"到底是个什么东西?

模型文件 = 配置 + 权重

一个完整的模型由两部分组成:

文件	内容	Go 类比	体积
`config.json`	模型架构描述(几层,每层多宽,多少注意力头)	结构体定义 `type Model struct{...}`	~1KB
`model.safetensors` 或 `pytorch_model.bin`	所有参数的数值(Embedding 表 + 各层权重矩阵)	结构体实例 `gob.Encode` 后的二进制数据	几十MB~几GB
`vocab.txt` / `tokenizer.json`	词表和分词器配置	配置文件	几百KB~几MB

权重文件里面存的就是一堆命名的多维数组(tensor):

model.safetensors 内容(概念展示):

embedding.weight:       shape [21128, 768]   ← Embedding 查找表
layer0.attention.Q:     shape [768, 768]     ← 第0层注意力的 Q 矩阵
layer0.attention.K:     shape [768, 768]     ← 第0层注意力的 K 矩阵
layer0.attention.V:     shape [768, 768]     ← 第0层注意力的 V 矩阵
...
layer11.ffn.weight:     shape [3072, 768]    ← 第11层前馈网络
classifier.weight:      shape [3, 768]       ← 分类头(3类输出)

总计: 数千万个 float32 数字

// 用 Go 类比模型文件的结构

// config.json 相当于类型定义
type BERTConfig struct {
    NumLayers   int // 12
    HiddenSize  int // 768
    VocabSize   int // 21128
    NumClasses  int // 3(对应 positive/negative/neutral)
}

// safetensors 相当于这个实例序列化后的二进制
type BERTWeights struct {
    EmbeddingTable [21128][768]float32   // 那张 ID→向量 查找表
    Layers         [12]TransformerLayer  // 12 层的所有矩阵
    Classifier     [3][768]float32       // 最后的分类头
}

// 加载模型 = 读取二进制文件 → 反序列化到内存中的结构体
func LoadModel(path string) *BERTWeights {
    data, _ := os.ReadFile(path)
    var weights BERTWeights
    deserialize(data, &weights)  // 把字节流还原为浮点数矩阵
    return &weights
}

模型文件 = Go 二进制中的全局变量段(.data section). 存的全是初始化好的数据,没有可执行指令. 加载模型 = 把数据段映射进内存;推理 = 用固定的计算逻辑(框架提供)读取这些数据做矩阵运算.

模型缓存在哪

用 Python 生态下载的模型不在项目目录或虚拟环境(.venv/)中,而是在用户级缓存目录:

下载库	缓存路径	示例
HuggingFace(transformers)	`~/.cache/huggingface/hub/`	BERT,DistilBERT 等 Transformer 模型
Gensim(gensim.downloader)	`~/gensim-data/`	Word2Vec,FastText 预训练向量
PyTorch Hub	`~/.cache/torch/hub/`	torchvision 模型等

虚拟环境 vs 模型缓存

uv/pip 管理的 .venv/ 只装 Python 包(代码和库). 模型权重文件体积太大(几百MB~几GB),不适合放在包管理中,所以各框架自己管理缓存. 删除 .venv/ 重建环境不会丢失已下载的模型.

HuggingFace 的缓存结构:

~/.cache/huggingface/hub/
└── models--lxyuan--distilbert-base-multilingual-.../
    ├── refs/main                  ← 版本指针(git commit hash)
    └── blobs/
        ├── ...config.json         (759B)    ← 架构配置
        ├── ...tokenizer.json      (972K)    ← 分词器
        ├── ...vocab               (2.8M)    ← 词表
        └── ...safetensors         (516M)    ← 模型权重(核心大文件)

为什么模型能跨机器迁移

模型文件里存的是纯数字--浮点数矩阵的序列化. 它不包含:

没有编译后的机器码(不像 Go binary 区分 linux/amd64 和 darwin/arm64)
没有文件路径依赖(不像有些配置文件写死了绝对路径)
没有系统库链接(不像 .so/.dylib 有动态链接)

所以模型文件可以:

Mac 上训练 → Linux 服务器上部署(跨操作系统)
Python 中训练 → 导出为 ONNX → Go/C++/Rust 中推理(跨语言)
GPU 上训练 → CPU 上推理(跨硬件,需要对应的推理引擎)

模型文件 = JSON 文件. 一个 JSON 能在任何操作系统,任何编程语言中读取,因为它只是结构化数据. 模型文件也一样--只是浮点数数组换了个序列化格式(safetensors/ONNX/bin),任何能解析该格式的推理引擎都能加载并执行计算.

对部署场景意味着什么

可以在 Mac 上用 Python + PyTorch 训练/微调模型,导出为 ONNX 格式,然后在 Linux 服务器上用 Go + onnxruntime-go 加载推理. 模型文件直接 scp 过去就能用,不需要在服务器上装 Python 或 PyTorch. 这就是后续要讲的 ONNX 导出的核心价值.

(本篇正文--ONNX 导出与推理优化--将在阶段三完成后继续编写.)