SavedModel部署实战：从model.save()到TensorFlow Serving的完整指南

干了几年模型上线的工作，我越来越觉得 model.save() 是 TensorFlow 给开发者设下的一个“温柔陷阱”。本地训练完，顺手一句 model.save('my_model')，看着生成了一堆文件，心里踏实得很。可真到了要把模型接到线上服务、或者交给别的团队去部署的时候，才发现问题一堆：环境里没装 Keras 怎么办？自定义层反序列化失败怎么办？模型里那几个预处理节点到底怎么传参？这时候你再回头去研究 saved_model.pb 里到底藏了什么，才会意识到——SavedModel 从来就不是一个“保存格式”，而是一套完整的模型发布方案。

这篇文章，我把自己在实际项目里对 SavedModel 的踩坑和理解完整梳理一遍。不光是讲 model.save() 怎么用，而是从部署视角重新审视：目录结构、签名机制、版本管理、性能优化，以及 TensorFlow Serving 落地时的常见坑。适合那些已经能用 Keras 训练模型、但还没搞明白“训练产物”和“部署产物”本质区别的同学。看完你至少能回答三个问题：SavedModel 到底比 H5 强在哪？签名是干什么的？为什么有些人部署起来又快又稳，而你总是掉链子。

1. SavedModel 和 model.save() 的底层逻辑

1.1 model.save() 到底保存了什么

model.save() 这个 API，在 TF2 里默认保存的就是 SavedModel 格式。但你如果只是把它当成“把模型存下来”的便捷工具，那就漏掉了大量信息。实际上，model.save() 自动为你做了一系列封装：

• 追踪（trace）模型的 call() 方法，生成一个或多个 ConcreteFunction；
• 把权重导出为 checkpoint 格式，放进 variables/ 目录；
• 把模型结构、优化器状态、损失函数等元信息写入 saved_model.pb；
• 顺带序列化一些自定义对象的配置（如果可序列化的话）。

换句话说，model.save() 确实在帮你生成一个 SavedModel，但它生成的是“Keras 视角下的 SavedModel”。它好用，但也隐藏了太多细节。一旦你的模型里有自定义层、预处理的 Lambda、或者需要对外暴露多个入口，model.save() 生成的产物往往不够“干净”——里面混杂了训练期才需要的对象信息，推理时根本用不上，反而让模型变大、加载变慢、调试困难。

1.2 H5 和 SavedModel 的本质区别

很多初学者会问：.h5 一个文件多方便，为什么非要用一个文件夹？我通常用一句话解释：H5 是“存档”，SavedModel 是“安装包”。

H5 适合训练过程中的阶段性保存，它把权重和结构揉在一个二进制文件里。加载时要求你有完整的 Keras 环境，并且自定义对象必须手动注册，否则反序列化直接报错。你可以在单机训练时用它，但一旦要放到服务端、边缘设备、或者用 C++ 去推理，H5 基本就废了。

SavedModel 则是一个自包含的目录，核心是 saved_model.pb 里的图定义和签名（Signature），配合 variables/ 里的权重和 assets/ 里的外部资源。它不依赖 Python 侧的类定义，任何支持 TensorFlow Runtime 的语言都能加载。这就像你把一个应用程序做成了免安装的绿色版，拷到哪都能跑。

1.3 为什么部署视角必须“超越” model.save()

我在多个项目里验证过一件事：用 model.save() 保存模型推上线，遇到问题几乎无法排查。因为你不知道它帮你生成的那几个签名（serving_default 之外可能什么都没有）到底符不符合下游需求。

部署的核心诉求是：提供一个稳定、明确、高性能的接口。你需要控制输入输出的名字、张量形状、是否允许动态 batch、要不要把预处理并进图里。这些 model.save() 也能做一部分，但如果你不理解背后的机制，就只能在接口层面“碰运气”。所以才说，真正进阶的用法是自己手动构建 SavedModel——你不需要每次都手写 protobuf，但你至少要会创建带自定义签名的 ConcreteFunction，再有选择性地导出。

2. SavedModel 目录结构逐层解剖

2.1 从 tree 命令看整棵目录树

先看一个典型的 SavedModel 目录长什么样：

text复制my_model/
├── assets/
├── fingerprint.pb
├── saved_model.pb
└── variables/
    ├── variables.data-00000-of-00001
    └── variables.index

如果你用的是较新的 TensorFlow（2.10 以上），还会多出 fingerprint.pb，它是模型的哈希指纹，用于快速校验模型版本，加载时可以作为缓存依据。

• saved_model.pb：序列化后的 SavedModel protobuf，包含 MetaGraphDef、SignatureDef、图结构信息和变量初始化信息。这个文件是整个模型的核心“说明书”。
• variables/：存放权重。variables.index 是变量名到数据块的索引；variables.data-* 是实际张量数据。带 shard 的格式是为了支持超大模型分片存储。
• assets/：外部资源，比如词汇表、配置 JSON、字典文件。你可以在 tf.saved_model.save 时通过 assets 参数传入，运行时用 tf.saved_model.Asset 访问。

2.2 protobuf 和变量分片背后的设计逻辑

为什么要用 protobuf，而不是 JSON 或 pickle？因为 protobuf 有稳定的 schema，跨语言解析容易，而且对增删字段有良好的兼容性。模型结构本身就是一张有向计算图，用 protobuf 定义节点、边、属性是最自然的表达方式。

变量分片则是为了处理超大模型。比如一个 10GB 的模型，如果只写一个二进制文件，复制、上传、断点续传都不方便。分片之后，variables.index 可以告诉运行时每个变量在哪一块数据里，加载时还能按需读取，而非一次性全量载入。这也是 SavedModel 适合大规模生产部署的原因之一。

2.3 用 saved_model_cli 直接查看模型内容

很多人在部署时犯错，都是因为“盲人摸象”——根本不看模型里到底有什么。TensorFlow 提供了 saved_model_cli 命令行工具，应该成为你排查问题的第一选择。

bash复制saved_model_cli show --dir my_model --all

这条命令会把模型里的全部签名、输入输出、节点信息、资产列表都打出来。举个实际输出：

text复制signature_def['serving_default']:
  The given SavedModel SignatureDef contains the following input(s):
    inputs['input_1'] tensor_info:
        dtype: DT_FLOAT
        shape: (-1, 224, 224, 3)
        name: serving_default_input_1:0
  The given SavedModel SignatureDef contains the following output(s):
    outputs['output_0'] tensor_info:
        dtype: DT_FLOAT
        shape: (-1, 1000)
        name: StatefulPartitionedCall:0
  Method name is: tensorflow/serving/predict

看到 shape: (-1, 224, 224, 3) 说明输入允许动态 batch。看到 Method name is: tensorflow/serving/predict，说明这是一个标准预测签名，TensorFlow Serving 可以直接对接。

注意：不同 TensorFlow 版本生成的输出文本格式会略有差异，但 signature_def、inputs、outputs、Method name 这些关键字段一定在。

2.4 fingerprint.pb 是干什么的

fingerprint.pb 是 TF2 某个版本之后新增的，内容是模型结构图的哈希指纹。它的作用有两个：一是快速对比两个模型是否一致，二是作为模型仓库的缓存键。你手动删掉它一般不影响加载，但我不建议删，因为在 tensorflow/serving 的某些版本中，模型的 version 管理逻辑会参考它。

3. 签名（Signature）才是 SavedModel 的灵魂

3.1 为什么签名如此重要

签名定义了模型的“输入输出接口”，类似 REST API 的 request/response 结构。在部署中，签名决定了调用方以什么格式传数据、拿什么格式的结果。如果你只是用 model.save()，那你得到的几乎只有一个 serving_default 签名，而且输入输出的命名可能很乱（如 input_1、output_0）。这在快速 Demo 里没问题，但在正式的线上服务里，接口的稳定性直接决定了上下游协作效率。

我做过一个推荐系统的模型，上游特征工程有十多个特征，每个特征的名字、dtype、shape 都对不上，就是因为我们只用了默认导出，而没有手动定义签名。后来我重新用 tf.function + input_signature 自定义导出，一切都捋顺了。

3.2 手动创建签名和 ConcreteFunction

手动保存 SavedModel 的核心是理解 tf.function 的“追踪（tracing）”机制。当你给 tf.function 传入 input_signature 时，它会构建一个只接受指定形状和 dtype 的图。我们来写一个实际例子：

python复制import tensorflow as tf

class MyModel(tf.Module):
    def __init__(self):
        super().__init__()
        self.fc = tf.keras.layers.Dense(10, activation='softmax')

    @tf.function(input_signature=[
        tf.TensorSpec(shape=[None, 4], dtype=tf.float32, name='features')
    ])
    def predict(self, features):
        return {'probs': self.fc(features), 'logits': self.fc(features, training=False)}

model = MyModel()
# 随便初始化一下权重
_ = model.predict(tf.ones([1, 4]))

tf.saved_model.save(
    model,
    'saved_model_custom',
    signatures={
        'serving_default': model.predict,
        'other_signature': model.predict  # 你可以定义多个签名
    }
)

这里我们通过 tf.Module 手动定义了一个模型类，然后用 @tf.function(input_signature=...) 明确输入张量的 shape 和 dtype。关键点在于：一个签名下的输入输出名字、类型完全由你控制。

保存后用 saved_model_cli show --dir saved_model_custom --all 查看，你会发现输入是 features，输出是 probs 和 logits，接口清晰多了。

3.3 输入预处理应该放在图里还是图外

这是部署中一个高频争论点。我的经验是：能放进图里就放进图里。

比如图像模型，线上传来的往往是 base64 编码的字符串，如果图外做解码，那就需要另外部署一个预处理服务，或者让调用方自己解码，容易出错。更好的做法是把解码、缩放、归一化全部编译进签名里。

你可以这样做：

python复制@tf.function(input_signature=[
    tf.TensorSpec(shape=[None], dtype=tf.string, name='image_b64')
])
def predict_b64(image_b64):
    def decode_and_preprocess(img):
        # 假设进来了 base64 字符串
        img = tf.io.decode_base64(img)
        img = tf.image.decode_jpeg(img, channels=3)
        img = tf.image.resize(img, [224, 224])
        img = tf.cast(img, tf.float32) / 127.5 - 1.0
        return img

    images = tf.map_fn(decode_and_preprocess, image_b64, fn_output_signature=tf.float32)
    return {'probs': self.model(images, training=False)}

这样，上游直接把 base64 字符串传过来，模型图内部完成解码和预处理。调用方拿到的还是一个模型接口，部署链路大幅简化。当然，“图内预处理”会稍微增加图复杂度，如果你用 TensorFlow Serving 并且并发很高，要考虑解码算子会不会成为瓶颈。但从接口稳定性来看，利远大于弊。

3.4 动态 shape、batch 与显存/内存占用

签名里把形状写成 [None, ...] 就表示允许动态 batch。但动态 batch 有两个坑：

• 图内如果存在 tf.reshape 到固定形状的操作，会导致追踪时报错；
• Serving 端动态 batch 能提高吞吐，但内存占用也会动态变化，需要预估好最大 batch。

我一般会在签名里固定最大 batch 为 32 或 64，然后在 Layer 里手动 tf.ensure_shape 或分桶处理。这样既保持推理并行度，又避免极端大 batch 把显存撑爆。

4. TensorFlow Serving 部署实战与调优

4.1 用 Docker 快速拉起一个模型服务

SavedModel 设计之初就考虑了对 TensorFlow Serving 的无缝支持。实际用起来也确实是最顺滑的方式。先看最基本的部署命令：

bash复制docker run -p 8501:8501 \
  --mount type=bind,source=/path/to/models,target=/models \
  -e MODEL_NAME=my_model \
  -t tensorflow/serving

这里把宿主机上的 /path/to/models 挂载到容器内 /models，然后通过环境变量 MODEL_NAME 指定模型名。TensorFlow Serving 默认从 /models/my_model 读取模型，其中模型目录里的数字子目录对应版本号：

text复制models/
└── my_model/
    ├── 1/
    │   ├── saved_model.pb
    │   └── variables/
    └── 2/
        ├── saved_model.pb
        └── variables/

Serving 默认会加载所有数字版本目录，并以最高版本号为默认服务版本。你可以通过 RESTful API 调用：

bash复制curl -X POST http://localhost:8501/v1/models/my_model:predict \
  -H 'Content-Type: application/json' \
  -d '{"instances": [[1.0, 2.0, 3.0, 4.0]]}'

只要模型签名里的输入匹配，返回结果就是标准的 JSON。

提示：如果模型只有一个版本，也有人把 1 目录下直接放 saved_model.pb，然后用 --model_name 指定。但从可维护性出发，建议保留数字版本目录。

4.2 多模型共享一个 Serving 实例

生产环境通常不会只部署一个模型。Serving 支持多模型加载，方法是写一个 models.config：

text复制model_config_list {
  config {
    name: "model_a"
    base_path: "/models/model_a"
    model_platform: "tensorflow"
  }
  config {
    name: "model_b"
    base_path: "/models/model_b"
    model_platform: "tensorflow"
  }
}

启动时加参数：

bash复制docker run -p 8501:8501 \
  --mount type=bind,source=/path/to/models,target=/models \
  -t tensorflow/serving \
  --model_config_file=/models/models.config

这样多个模型在同一进程内管理，显存和 CPU 资源可以共享。需要留意的是，Serving 默认会在模型加载时占用大量内存，如果多个模型一起加载，要关注容器的资源限制。

4.3 模型热更新与版本策略

SavedModel 的版本策略是我觉得它比 H5 强太多的地方之一。你把新版本模型放在一个新数字目录下，Serving 会自动探测并加载新版本，然后优雅地切换流量，旧版本会在请求排空后卸载。

实际操作中，我推荐用版本目录 + 软链接的方式：

bash复制ln -s /data/models/my_model/3 /models/my_model/current

Serving 的 --model_base_path 指定到 /models/my_model/current，更新时只改软链接指向，避免直接修改挂载目录触发不可预期的 reload。

但要注意：自动版本切换会影响正在处理的请求。官方建议用 --model_config_file_poll_wait_seconds 控制轮询间隔，我用的时候会把它调大到 60 秒，这样在发布时最多延迟一分钟，不会频繁触发加载。

4.4 模型预热、动态 batching 与并发调优

模型上线后最怕的情况是“第一个请求很慢”，因为图里的算子、CUDA context 都要在第一次推理时才初始化。解决办法是模型预热（warmup）。TensorFlow Serving 支持 saved_model.pb 同级放一个 tf.saved_model 的 warmup 请求 proto，官方在 tensorflow_serving 库里提供了生成工具。

不用搞那么复杂的话，也可以用 Serving 的 --tensorflow_session_parallelism 参数来提前初始化会话，配合脚本在启动后发几个 dummy 请求，效果差不多。

动态 batching 是另一个吞吐提升利器。启动参数加：

bash复制--enable_batching=true \
--max_batch_size=64 \
--num_batch_threads=8 \
--batch_timeout_micros=20000

• max_batch_size 表示单个 batch 最大样本数；
• batch_timeout_micros 表示最多等多少微秒凑齐一个 batch；
• num_batch_threads 是执行 batch 推理的线程数。

如果模型本身对单请求延迟敏感，动态 batching 可能增加尾部延迟。我通常把 batch_timeout_micros 控制在 10ms 以内，对吞吐提升明显。

4.5 选型对比：TensorFlow Serving 和其他方案

在正式选型时，总有人问：不用 TensorFlow Serving 行不行？当然行，但每种方案都有代价：

我的建议很直接：如果模型是 TensorFlow 训练并在 TF 运行时上线，优先用 TensorFlow Serving。它的动态 batching 和版本管理是专门为这种场景设计的，自己造轮子很难达到同等稳定度。

5. 精度、性能优化和常见坑位实录

5.1 FP32、FP16、BF16、TF32 在部署里的定位

部署时的精度选择直接影响显存占用、吞吐和效果。这四个浮点格式我简单梳理一下使用场景：

• FP32：默认精度，最安全，兼容性最好。模型小且算力充足时无脑选它。
• FP16：范围和精度都比 FP32 小，需要看模型是否扛得住。适合 GPU 推理，显存能省一半。
• BF16：指数位和 FP32 相同，范围大，精度低。对训练/推理更友好，数值稳定性好，很多新 GPU 原生支持。
• TF32：NVIDIA Ampere 架构引入的“近似 FP32”，矩阵运算时自动使用，精度损失在可接受范围。实际推理时你很难直接感知到它，但吞吐提升明显。

在 TensorFlow Serving 里，最省事的做法是模型保存时保持 FP32，部署时依赖 GPU 的 TF32 自动加速。如果你确定模型对 FP16 不敏感，可以先用 tf.lite 或图优化工具转成 FP16。

5.2 模型瘦身：从 SavedModel 里剔除多余节点

每次加载 SavedModel，里面那些训练期才用的节点（如 optimizer 状态、metrics 累积量）都是拖累。用 model.save() 导出的模型经常很大，一个重要原因就是 variables/ 里存了不少训练状态。

手动构建 SavedModel 会好很多，但如果你手上只有一个已经保存好的 SavedModel，可以用 tf.saved_model 的 graph transformation 工具来精简。不过这属于比较激进的操作，生产环境慎用。更稳妥的思路是：在保存前就只导出推理所需的部分。比如只导出模型 backbone + head，把输入输出之外的东西彻底剥离。

5.3 常见报错与排查方法速查表

这里整理我在实际部署中遇到频率最高的几个问题，全部亲测有效：

5.4 一个真实的 QPS 优化案例

我曾带过一个项目，图像分类模型用的是 EfficientNet-B0，初始用 model.save() 部署在 TensorFlow Serving 上，GPU 是 T4，单实例 QPS 只有 180 左右。

我一步步调优：

1. 把预处理并入 SavedModel 签名，减少图外 Python 操作；
2. 开启动态 batching，max_batch_size=32，QPS 提升到 320；
3. 改用自定义签名，只保留推理必要的节点，模型从 480MB 瘦身到 390MB；
4. 在 Serving 参数里启用 XLA（--xla_compile 在部分版本可用，或用 TF_XLA_FLAGS），QPS 最终稳定在 520 左右。

整个过程没有改动模型结构，只靠部署侧优化，吞吐提升接近 3 倍。这几个参数如果你只是“能用”层面，根本不会去关注——但部署的收益恰恰就藏在这些细节里。

5.5 使用容器和临时目录时的坑

最后说一个常见的低级错误：很多人用 Docker 挂载模型目录时，把宿主机路径写错了，或者挂载后目录权限不对，导致 Serving 一直报找不到模型。启动后第一件事，应该进容器确认挂载是否成功：

bash复制docker exec -it <container_name> ls /models

另外，如果模型是放在 NFS 或网络存储上，Serving 首次加载模型会因网络 IO 变慢，此时可以把模型目录 copy 到本地临时盘再启动，能省下大量时间。

6. 再分享一个部署前的自查清单

每次上线 SavedModel 之前，我都会按下面列表过一遍，避免线上翻车：

1. 用 saved_model_cli show --dir my_model --all 打印签名，确认输入输出名称和 dtype。
2. 检查 variables/ 和 assets/ 是否存在，fingerprint.pb 要不要保留。
3. 用 Docker 在本机先跑起来，用 curl 模拟真实请求，验证预测结果和预期一致。
4. 并发测试一批请求，观察服务端显存/内存和延迟，确认动态 batching 参数是否合理。
5. 检查模型版本目录，确认最高版本号对应的是最新模型。
6. 确认 Serving 日志里模型加载没有 warning，特别是 op mismatch 之类。
7. 如有可能，做一次精度对比，确保 FP32/FP16/TF32 之间切换没有显著掉点。

这一套流程走下来，大部分问题都能在上线前暴露。真等线上流量打过来再发现问题，代价就高了。

我个人这几年最大的体会是：模型训练决定效果上限，模型部署决定效果下限。SavedModel 作为衔接训练与推理的“标准货物包装”，值得你花几天时间彻底搞懂。尤其当你开始接触大规模服务、多模型管理、边缘部署这些场景时，今天花在签名和目录结构上的时间，都会变成明天排查问题的底气。