1. 报错现场还原这行红字到底卡在哪一层先说清楚这个场景。一个跑在 TensorFlow 1.0 上的老项目模型训练阶段早就结束了权重也固化好了现在要做的只是在推理侧把图模型重新读进来。代码大概率就三行with tf.gfile.GFile(model.pb, rb) as f: graph_def tf.GraphDef() graph_def.ParseFromString(f.read())然后控制台甩出一行DecodeError: Error parsing message没有任何文件名、没有行号、没有提示是哪个字段解析失败连是文件问题还是代码问题都不告诉你。我第一次遇到的时候盯着这行字看了半小时因为从字面上看它只说明了一件事protobuf 解不出这段字节。除此之外什么都没说。这篇文章面向的是正在做模型部署、模型转换、或者复现别人实验结果的人尤其是还在维护 TensorFlow 1.x 遗留代码的同学。我会把DecodeError: Error parsing message这个报错拆到字节级别告诉你它为什么会出现、怎么在五分钟内定位到具体原因、以及每种原因对应的修法。内容偏实操代码可以直接抄。1.1 protobuf 和图模型之间是什么关系要理解这个报错得先知道 TensorFlow 1.x 的图模型到底是个什么东西。它不是序列化后的 pickle也不是 JSON而是一个protobuf 消息。TensorFlow 在源码里定义了一大堆.proto文件其中graph.proto定义了GraphDefnode_def.proto定义了NodeDefattr_value.proto定义了AttrValue。你在 Python 里拿到的tf.GraphDef类其实是这些.proto文件被 protoc 编译出来的 Python 类它继承自google.protobuf.message.Message。这就决定了一件事GraphDef对象只有在被序列化成二进制时才是一串字节流读取它的唯一正确方式是ParseFromString(bytes)。而 protobuf 的二进制格式是一套自描述的 TLVTag-Length-Value变体每个字段先写一个 varint 编码的 tagtag 里打包了字段编号和 wire type然后根据 wire type 决定后面跟的是 varint、固定长度值、还是长度前缀的字节块。解析器严格按这个规则往下滚滚到哪一个字节对不上就抛DecodeError。所以这行报错的本质用一句人话说就是你喂给解析器的这堆字节不符合 protobuf 的语法规则。它可能是被截断了可能是里面混进了不该有的字符可能压根就不是一个GraphDef甚至可能是个 HTML 页面。1.2 报错会在哪几个位置冒出来很多人以为是ParseFromString那一行抛的其实不一定。同一个DecodeError在 TensorFlow 1.x 里至少有四个常见触发点而它们的排查方向并不完全一样触发位置内部做了什么常见诱因graph_def.ParseFromString(data)按 GraphDef 的 schema 逐字段解析文件损坏、格式不对、文本图当二进制读tf.import_graph_def(graph_def)把已解析的 GraphDef 构建成图通常是 schema 版本不匹配导致的属性解析失败tf.saved_model.loader.load(sess, tags, dir)读取目录下的saved_model.pb目录结构不对、该文件被替换或截断tf.train.write_graph之后的回读写文件时as_text参数选错文本图和二进制图搞混我在实际排查里见得最多的是第一种和第四种。第一种是真文件坏了第四种是自己坑自己写的时候as_textTrue存成了文本格式读的时候却用二进制方式解析必然炸。1.3 哪些人最容易撞上这个问题有三类人几乎躲不掉。第一类是做模型部署的模型文件动辄几百兆从训练机器传到服务机器中间经过网盘、对象存储、内网跳板任何一环出问题都会变成文件能打开但解析失败。第二类是做模型转换的把别的框架的模型转成 TensorFlow 冻结图转换工具版本不一致时输出的.pb可能本身就带病。第三类是复现别人实验的尤其是那些托管在大文件仓库里的模型权重克隆下来如果没拉全本地看到的只是一个几百字节的指针文本文件长得像.pb内容完全不是。这三类场景的共同点是文件不是你自己现场生成的你对它的完整性没有把握。所以后面的排查思路第一条永远是从文件本身开始而不是从代码开始。2. 五步定位法把玄学问题压到一行代码遇到这个报错我一般不做任何猜测直接按固定顺序走五步。这套流程的价值在于每一步都能给出一个明确的是或否绝不会让你在两个可能之间反复横跳。五步走完原因基本就锁死了。2.1 第一步确认文件大小和文件头先看大小。这个是成本最低的检查一条命令的事ls -lh model.pb正常情况下一个包含卷积网络的冻结图至少是几兆到几百兆。如果你看到的是 132 字节、1KB 这种数字基本可以直接判定为失败往下看文件头确认。xxd -l 64 model.pbxxd打出的是十六进制加 ASCII 的双栏视图。protobuf 二进制文件的开头通常是一个合理的 tag 字节你会看到0a xx这类模式0a是字段 1、wire type 2 的组合GraphDef的第一个字段就是node编号 1、类型是 message。如果是文本格式的 pbtxt你会看到node {这样的可读字符直接出现在右边那一栏。如果看到的是html、!DOCTYPE、version https://git-lfs...那答案就更明显了——你拿到的不是模型文件。注意不要用文本编辑器打开.pb文件然后看一眼。很多编辑器会自动做编码转换甚至在你不知情的情况下保存把一个本来只是可疑的文件彻底弄坏。看二进制内容一律用xxd、od或hexdump。2.2 第二步校验文件完整性如果你手上有一个官方或上游提供的哈希值直接比对。没有哈希值的话退一步的做法是用md5sum或sha256sum算出本地值然后再重新下载一次比对两次结果是否一致。听起来很笨但这是唯一能确认传输过程中没丢字节的办法。sha256sum model.pb对于从大文件仓库克隆下来的仓库还有一条更省事的路径git lfs ls-files git lfs pull很多模型仓库用了大文件存储机制克隆时默认只拉指针文件。指针文件本身是一段纯文本几十到一百多字节长这样version https://git-lfs.github.com/spec/v1 oid sha256:xxxxxxxx size 102400000这种文件被当成.pb读进来ParseFromString必然报DecodeError。这个问题在团队协作里特别隐蔽因为git status是干净的文件也确实存在只有在你真的去解析它的时候才暴露。2.3 第三步分清 GraphDef、SavedModel 和 CheckpointTensorFlow 1.x 的模型存储有三套完全不同的形态很多报错源于用错 API 去读。GraphDef冻结图单个.pb文件图结构和常量权重都固化了用tf.GraphDef().ParseFromString()读是纯二进制。SavedModel一个目录里面至少要有saved_model.pb和一个variables/子目录用tf.saved_model.loader.load()读。Checkpoint一组文件model.ckpt-1000.index、model.ckpt-1000.data-00000-of-00001、model.ckpt-1000.meta.meta也是 protobuf但它存的是MetaGraphDef不是GraphDef。这三者的区别不是学术问题。我见过有人把 SavedModel 目录里的saved_model.pb单独拖出来用GraphDef去解析报DecodeError。原因不复杂saved_model.pb里存的是SavedModel消息它的字段布局和GraphDef完全不同解析器按GraphDef的 schema 去读读到不认识的字段编号就会出错。判断方法很简单一条命令区分file model.pb python -c import tensorflow as tf; print(tf.GraphDef.DESCRIPTOR.full_name); print(tf.saved_model.SavedModel.DESCRIPTOR.full_name)或者用 Python 试探性地看第一个字段的 tag 值后面第 4 节我会给一个自动嗅探的函数。2.4 第四步对齐 protobuf 运行时版本TensorFlow 1.0 发布于 2017 年初那个时期绑定的 protobuf 是 3.1 到 3.2 之间的版本。如果你在一个已经装了 protobuf 4.x 的环境里跑 TensorFlow 1.0即使文件本身完好也可能出问题。protobuf 4.x 对 Python 后端的实现做了大幅重构引入了 upb 后端生成的_pb2.py文件和运行时库之间存在代际兼容问题典型表现就是解析失败或描述符构建失败。python -c import google.protobuf; print(google.protobuf.__version__) pip index versions protobuf 2/dev/null | head -5我实践下来TensorFlow 1.0 到 1.4 之间的版本配 protobuf 3.1.x 到 3.6.x 比较稳。TensorFlow 1.15 配 protobuf 3.7 到 3.20 之间比较稳。这不是绝对规律但作为起点足够用。注意pip install protobuf3.6.1这种降级操作在装了很多依赖的虚拟环境里容易连锁破坏别的包。建议单独建一个虚拟环境专跑 TensorFlow 1.x 相关的活别和现在的主力环境混在一起。2.5 第五步写一个最小复现脚本走到这一步如果文件大小正常、哈希对得上、形态也判断对了那就用一段十几行的脚本把读这个动作单独拎出来测import tensorflow as tf path model.pb with tf.gfile.GFile(path, rb) as f: raw f.read() print(bytes:, len(raw)) print(head_hex:, raw[:16].hex()) gd tf.GraphDef() try: gd.ParseFromString(raw) print(parsed nodes:, len(gd.node)) print(first nodes:, [n.name for n in gd.node[:5]]) except Exception as e: print(parse failed:, type(e).__name__, e)这段脚本的关键是先把raw读出来再解析而不是边读边解析。这样你至少能确认我到底读到了多少字节。如果bytes打印出来是 0那问题在路径如果是几万但parse failed问题在内容。分开看就不会一锅粥。3. 六类成因逐条拆解定位完成之后接下来就是针对具体成因动手。下面这六种是我在过去几年里反复遇到过的覆盖了绝大多数情况。3.1 文件在传输或存储环节被截断这是最经典的一类。下载中断、网盘限速断连、容器镜像构建时COPY被中断、对象存储返回了分片数据都会造成文件存在但不完整。表现特征非常明显文件大小是一个奇怪的、不整的数字且远小于预期。验证方式有两种。一种是对比上游给出的文件大小另一种是直接解析看报错发生在什么位置。如果解析器报错时已经成功读出了前面几百个节点说明文件前半段是好的只是尾部被截掉了这类修复只能是重新拉取。修复时有个小技巧值得说如果文件很大而网络又不稳定用支持断点续传的方式获取并且获取完成后立刻算一次哈希并记录下来。这样以后再出问题你能一眼判断是这次没拉全还是上次就坏了。3.2 文本模式读写把字节改写了这一类的破坏力最大也最难察觉。看这段代码# 错误写法 with open(model.pb, r) as f: data f.read()看起来无害实际上在 Windows 平台上文本模式会把\r\n归一化成\n在某些默认编码下非法字节会被替换成替换字符。一个二进制文件经过这么一遭长度变了、内容也变了但文件仍然能打开。这类文件拿去解析DecodeError几乎是必然的。同理写文件也一样# 错误写法 with open(out.pb, w) as f: f.write(graph_def.SerializeToString())SerializeToString()返回的是bytes用文本模式写会直接抛TypeError运气好当场就发现了。但如果中间经过了某些做隐式转换的库就可能悄悄存下一个被污染的文件。记住一条铁律.pb文件的读写两头都必须是rb/wb。TensorFlow 生态里更推荐用tf.gfile.GFile(path, rb)它在本地和分布式文件系统上行为一致。3.3as_textTrue写出的文本图被当二进制解析tf.train.write_graph有一个as_text参数默认False但很多老教程里会写成True因为文本格式人眼可读方便调试。问题在于这两种格式的读取方式完全不同# 读取文本格式pbtxt from google.protobuf import text_format with tf.gfile.GFile(graph.pbtxt, r) as f: graph_def tf.GraphDef() text_format.Merge(f.read(), graph_def) # 读取二进制格式 with tf.gfile.GFile(graph.pb, rb) as f: graph_def tf.GraphDef() graph_def.ParseFromString(f.read())如果你拿ParseFromString去读一个 pbtxt报错就是DecodeError: Error parsing message。判断方法很简单用head -c 200 graph.pb看一下如果是node {、name:这样的明文那它就是文本图。这种情况的反向也成立拿text_format.Merge去读二进制文件报错信息会是ParseError: Expected identifier之类指向上完全不同所以从报错文案也能反推格式。3.4 protobuf 版本错配导致的解析失败这一类比较隐蔽因为文件本身是好的代码也没错坏的是环境。症状通常是同一个.pb文件在 A 机器上能读在 B 机器上报DecodeError或者升级了某个依赖之后原本正常的脚本突然读不了了。原因是 protobuf 的 wire format 虽然长期稳定但 Python 端的实现经历过几次大的后端切换纯 Python 实现 → C 实现 → upb 实现。在版本跨度很大的情况下某些消息类型的解析行为会出现差异尤其是当.proto定义里用到了oneof、map或Any这些较新的特性时。排查办法是固定环境版本然后做二分pip install protobuf3.6.1 tensorflow1.0.0 python -c import google.protobuf, tensorflow as tf; print(google.protobuf.__version__, tf.__version__)我自己的经验是TensorFlow 1.x 的环境尽量不要和其他现代框架共享。用conda或者venv单独隔离把版本号写进一个requirements.txt里锁死是唯一省心的做法。3.5 把 SavedModel 目录当成单文件读前面提过saved_model.pb里存的是SavedModel消息不是GraphDef。这两者的字段定义完全不同用错 schema 解析DecodeError或者解析出空对象都是正常结果。正确的打开方式是这样with tf.Session(graphtf.Graph()) as sess: tf.saved_model.loader.load(sess, [serve], saved_model_dir) graph tf.get_default_graph()注意第二个参数是 tag 集合通常是[serve]。如果你不知道 tag 是什么可以用tf.saved_model.loader.maybe_saved_model_directory()先判断目录是否是合法的 SavedModel再用tf.saved_model.main_op或者直接调loader.load的变体去枚举。还有一点容易踩SavedModel 目录里必须同时有saved_model.pb和variables/目录。如果variables/缺失比如打包时只复制了 pb 文件加载时会在恢复变量阶段报另一个错。所以复制模型时务必整目录复制别挑文件。3.6 下载到的其实是错误页面或指针文件这一类在国内网络环境下不算罕见尤其是从一些镜像源或者自建服务拉取文件时。症状很有辨识度文件只有几 KBxxd一看开头是!DOCTYPE html或者一段 XML 错误信息。另一种是私有仓库的权限问题服务端返回了一个 JSON 格式的 401 响应但客户端把响应当成文件内容存了下来。文件能打开大小也不是 0肉眼看不出来解析时直接炸。实操建议凡是从网络获取的模型文件获取完成后第一件事不是直接加载而是先校验文件头。培养这个习惯能省掉大量排查时间。4. 完整实操一套能自动分流的加载器讲完原因给一套我自己的做法。这套代码的价值不是它多复杂而是它把猜这个环节彻底去掉了任何输入进去输出的都是一句能看懂的话。4.1 环境准备与依赖锁定先说清楚环境。下面是 TensorFlow 1.x 场景下我常用的组合用venv隔离python -m venv tf1env source tf1env/bin/activate # Windows 下用 tf1env\Scripts\activate pip install --upgrade pip pip install tensorflow1.15.5 protobuf3.20.3 numpy1.18.5选择 1.15.5 而不是 1.0.0 的理由很实际1.0 原版在现在的 Python 版本上基本装不上、跑不动而 1.15 是 1.x 系列的最后一个版本API 保留了tf.compat.v1兼容层能读老的.pb也能跑老的代码。如果你确实被绑在 1.0 上那 Python 版本也得跟着降到 3.5 或 3.6这是硬约束没法绕。装完之后立刻验一下版本把结果记进项目文档python -c import sys, numpy, google.protobuf import tensorflow as tf print(sys.version) print(tf, tf.__version__) print(np, numpy.__version__) print(pb, google.protobuf.__version__) 4.2 文件嗅探先判断你手上是什么这段函数不解析模型只做一件事看前几十个字节判断格式类别。import os import gzip def sniff_model_file(path): if not os.path.exists(path): return missing, 0 size os.path.getsize(path) if size 0: return empty, 0 with open(path, rb) as f: head f.read(64) # 魔数判断 if head[:2] b\x1f\x8b: return gzip, size if head[:2] bPK: return zip, size if head[:15] bversion https:/: return git_lfs_pointer, size stripped head.lstrip() if stripped[:1] b: return html_or_xml, size if bnode { in head or bnode{ in head: return pbtxt, size # 二进制 protobuf 的启发式首个字节通常是 0x0a if head[:1] b\x0a: return protobuf_binary, size return unknown, size这段逻辑的核心依据是GraphDef的第一个字段是node字段编号 1、wire type 2所以第一个字节是0x0a。这不像PK、\x1f\x8b那样是强制的魔数但作为启发式足够可靠配合文件大小综合判断准确率很高。4.3 按类型分支加载嗅探结果出来之后分支处理就明确了import tensorflow as tf from google.protobuf import text_format def load_graph_def(path): kind, size sniff_model_file(path) print(sniff:, kind, size) if kind in (missing, empty): raise ValueError(file not found or empty: %s % path) if kind git_lfs_pointer: raise ValueError(this is a LFS pointer, run: git lfs pull) if kind html_or_xml: raise ValueError(downloaded an error page instead of a model) if kind zip: raise ValueError(this is a zip archive, maybe a SavedModel dir or a .npz) if kind gzip: with gzip.open(path, rb) as f: raw f.read() else: with tf.gfile.GFile(path, rb) as f: raw f.read() gd tf.GraphDef() if kind pbtxt: text_format.Merge(raw.decode(utf-8), gd) else: gd.ParseFromString(raw) print(parsed ok, nodes:, len(gd.node)) return gd这里有两点值得展开。第一gzip分支不是凑数的有些分发渠道会把.pb压缩成.pb.gz但文件名被改回了.pb这种情况下直接解析必然失败。第二zip分支对应的是新版 SavedModel 的打包格式以及某些模型压缩包判断出来之后应该解压再处理而不是硬解析。4.4 加载后的验收标准解析成功不代表万事大吉。我一般会做三项检查确认这个图是能用的而不是能读的检查项做法期望结果节点数量len(gd.node)大于 10与模型复杂度相符输入输出找 placeholder 和 output 节点名字符合预期维度正确常量完整性统计Const节点数量冻结图应有大量 Constplaceholders [n.name for n in gd.node if n.op Placeholder] consts [n for n in gd.node if n.op Const] print(inputs:, placeholders) print(const count:, len(consts))如果placeholders为空但节点数很多说明这是一个只含推理路径的图输入可能通过别的 op 名暴露。如果consts数量是 0但节点里有大量Variable相关 op说明这不是冻结图而是一个未固化的训练图你还需要跑一遍convert_variables_to_constants或者恢复 checkpoint。5. 常见问题速查与踩坑记录5.1 问题速查表下面这张表是我贴在项目 README 里的遇到报错先对号入座能覆盖八成情况现象最可能原因处理动作文件 130 字节左右内容是version https://大文件指针未拉取执行大文件拉取命令文件几 KB开头是下载到了错误页检查地址与鉴权重新下载解析报错但文件很大传输截断比对哈希后重新完整获取同一文件换机器能读protobuf 或 Python 版本不一致锁定版本重建隔离环境解析成功但len(gd.node) 0读错了 schema如 SavedModel换对应的 loader报错指向values或tensor字段图与 schema 版本代际不匹配统一生成端与读取端版本解析时报\r相关异常文本模式读写污染全部改成rb/wbSavedModel 加载时找不到变量variables/目录缺失整个目录复制不挑文件5.2 几条用时间换来的经验第一条永远先怀疑文件再怀疑代码。我早期的习惯是看到报错就去读源码、翻 issue结果折腾半天最后发现是文件没拉全。现在我的顺序完全反过来了ls看大小、xxd看头部、sha256sum对比三分钟之内就能排除掉一大半可能。第二条给每个模型文件配一份身份证。我的做法是在模型目录下放一个manifest.json记录文件大小、哈希、生成时的框架版本、生成脚本的 git commit。听起来有点重但只要经历过一次半年前的模型现在读不出来了你就会觉得这点成本完全值得。第三条不要试图修复损坏的.pb文件。protobuf 没有纠错能力一个字节错了整个文件就废了。有些工具号称能抢救截断的 pb实际上只是把能解析的前半截抠出来得到的图大概率缺节点跑起来报的是更难查的错。宁可重新生成不要修。第四条版本问题优先用隔离环境解决不要用降级全局包。全局降级 protobuf 会影响机器上所有依赖它的项目副作用不可控。建个专用环境成本是几百兆磁盘收益是不用再跟环境打架。第五条如果这个.pb是别人给你的直接要生成脚本。这是我踩过最深的一个坑一个第三方给的模型怎么读都报DecodeError沟通几轮之后才知道对方是用一个魔改过的转换工具导出的字段定义和官方 schema 有出入。这种情况下任何排查都是徒劳根子在生成端。所以拿到外部模型时我的第一个问题永远是这个东西是怎么生成的能不能把脚本给我。我个人在实际操作中的体会是DecodeError: Error parsing message这个报错之所以让人难受不是因为它难解决而是因为它不告诉你任何上下文。你唯一能做的就是自己把上下文补上——文件多大、头部长什么样、从哪来的、用什么版本生成的。这四件事问清楚了问题基本也就解决了。