As described in Compatibility for Graphs and Checkpoints, TensorFlow marks each kind of data with version information in order to maintain backward compatibility. This document provides additional details about the versioning mechanism, and how to use it to safely change data formats.
The two core artifacts exported from and imported into TensorFlow are checkpoints (serialized variable states) and
GraphDefs (serialized computation graphs). Any approach to versioning these artifacts must take into account the following requirements:
GraphDefscreated with older versions of TensorFlow.
GraphDefis upgraded to a newer version of TensorFlow before the consumer.
GraphDefs, backward compatibility is enforced within a major version. This means functionality can only be removed between major versions. Forward compatibility is enforced within Patch releases (1.x.1 -> 1.x.2, for example).
In order to achieve backward and forward compatibility as well as know when to enforce changes in formats, the serialized representations of graphs and variable state need to have metadata that describes when they were produced. The sections below detail the TensorFlow implementation and guidelines for evolving
There are data versions for
GraphDefs and checkpoints. Both data formats evolve at different rates, and also at different speeds than the version of TensorFlow. Both versioning systems are defined in
core/public/version.h. Whenever a new version is added a note is added to the header detailing what changed and the date.
This section discusses version information for data, binaries that produce data (producers), and binaries that consume data (consumers):
producer) and a minimum consumer version that they are compatible with (
consumer) and a minimum producer version that they are compatible with (
VersionDef versionsfield which records the
producerthat made the data, the
min_consumerthat it is compatible with, and a list of
bad_consumersversions that are disallowed.
By default, when a producer makes some data, the data inherits the producer's
bad_consumers can be set if specific consumer versions are known to contain bugs and must be avoided. A consumer can accept a piece of data if
consumernot in data's
Since both producers and consumers come from the same TensorFlow code base,
core/public/version.h contains a main binary version which is treated as either
consumer depending on context and both
min_producer (needed by producers and consumers, respectively). Specifically,
GraphDefversions, we have
This section presents examples of using this versioning mechanism to make changes to the
Adding a new Op:
GraphDefversions. This type of change is automatically backward compatible, and does not impact forward compatibility plan since existing producer scripts will not suddenly use the new functionality.
Adding a new Op and switching existing Python wrappers to use it:
min_consumer, since models which do not use this Op should not break.
Removing an Op or restricting the functionality of an Op:
GraphDefswith the banned functionality. This can be done with
min_producerto the GraphDef version from (2) and remove the functionality entirely.
Changing the functionality of an Op:
SomethingV2or similar and go through the process of adding it and switching existing Python wrappers to use it (may take 3 weeks if forward compatibility is desired).
min_consumerto rule out consumers with the old Op, add back the old Op as an alias for
SomethingV2, and go through the process to switch existing Python wrappers to use it.
Banning a single consumer version that cannot run safely:
bad_consumersfor all new GraphDefs. If possible, add to
bad_consumersonly for GraphDefs which contain a certain Op or similar.
© 2017 The TensorFlow Authors. All rights reserved.
Licensed under the Creative Commons Attribution License 3.0.
Code samples licensed under the Apache 2.0 License.