Ce document est destiné aux utilisateurs qui ont besoin d'une rétrocompatibilité entre différentes versions de TensorFlow (que ce soit pour le code ou les données), et pour les développeurs qui souhaitent modifier TensorFlow tout en préservant la compatibilité.
Versionnement sémantique 2.0
Tensorflow suit sémantique Versioning 2.0 ( semver ) pour son API publique. Chaque version de tensorflow a la forme MAJOR.MINOR.PATCH
. Par exemple, la version 1.2.3 a tensorflow MAJOR
version 1, MINOR
version 2 et PATCH
version 3. Les modifications apportées à chaque numéro ont la signification suivante:
MAJOR: changements potentiellement incompatibles en arrière. Le code et les données qui fonctionnaient avec une version majeure précédente ne fonctionneront pas nécessairement avec la nouvelle version. Cependant, dans certains cas, les graphiques et points de contrôle TensorFlow existants peuvent être migrés vers la nouvelle version ; voir Compatibilité des graphiques et des points de contrôle pour plus de détails sur la compatibilité des données.
MINOR: Backwards caractéristiques compatibles, améliorations de la vitesse, etc. Code et les données qui ont travaillé avec une version mineure précédente et qui ne dépend que de l'API publique non expérimentale continuera à travailler sans changement. Pour plus de détails sur ce qui est et ne l'API publique, voir Ce qui est couvert .
PATCH: corrections de bugs Rétrocompatible.
Par exemple, la libération 1.0.0 a introduit des changements en arrière incompatibles de la libération 0.12.1. Cependant, version 1.1.1 est rétrocompatible avec la version 1.0.0.
Ce qui est couvert
Seules les API publiques de TensorFlow sont rétrocompatibles entre les versions mineures et les correctifs. Les API publiques se composent de
Tous les documentés Python fonctions et classes dans le
tensorflow
module et ses sous - modules, à l' exception- Symboles privés: toute fonction, classe, etc., dont le nom commence par
_
- Expérimentale et
tf.contrib
symboles, voir ci - dessous pour plus de détails.
Notez que le code dans les
examples/
ettools/
répertoires n'est pas accessible par letensorflow
le module Python et est donc pas couvert par la garantie de compatibilité.Si un symbole est disponible via le
tensorflow
le module Python ou ses sous - modules, mais n'est pas documenté, il ne fait pas partie de l'API réfléchie publique.- Symboles privés: toute fonction, classe, etc., dont le nom commence par
L'API de compatibilité (en Python, le
tf.compat
module). Dans les versions majeures, nous pouvons publier des utilitaires et des points de terminaison supplémentaires pour aider les utilisateurs lors de la transition vers une nouvelle version majeure. Ces symboles d'API sont obsolètes et non pris en charge (c'est-à-dire que nous n'ajouterons aucune fonctionnalité et nous ne corrigerons pas les bogues autres que pour corriger les vulnérabilités), mais ils relèvent de nos garanties de compatibilité.L' API C .
Les fichiers tampons de protocole suivants :
Ce qui est non couvert
Certaines parties de TensorFlow peuvent changer de manière rétrocompatible à tout moment. Ceux-ci inclus:
API expérimentales: Pour faciliter le développement, nous exempter certains symboles de l' API clairement identifiés comme expérimentale des garanties de compatibilité. En particulier, ne sont couverts par aucune garantie de compatibilité :
- un symbole dans le
tf.contrib
module ou ses sous - modules; - un symbole (module, la fonction, l' argument, la propriété, la classe, ou constante) dont le nom contient
experimental
ouExperimental
; ou - tout symbole dont le nom pleinement qualifié comprend un module ou une classe qui est elle-même expérimentale. Cela comprend des champs et des sous - messages de tout tampon de protocole appelé
experimental
.
- un symbole dans le
Autres langues: API tensorflow dans les langues autres que Python et C, tels que:
- C ++ (exposé à travers les fichiers d' en- tête dans
tensorflow/cc
). - Java ,
- Aller
- JavaScript
- C ++ (exposé à travers les fichiers d' en- tête dans
Détails des opérations composites: De nombreuses fonctions publiques en Python étendre à plusieurs opérations primitives dans le graphique, et ces détails feront partie de tous les graphiques enregistrés sur le disque comme
GraphDef
s. Ces détails peuvent changer pour les versions mineures. En particulier, les tests de régression qui vérifient la correspondance exacte entre les graphiques sont susceptibles de s'appliquer aux versions mineures, même si le comportement du graphique doit rester inchangé et que les points de contrôle existants fonctionneront toujours.Virgule flottante détails numériques: Les valeurs de virgule flottante spécifiques calculés par ops peut changer à tout moment. Les utilisateurs doivent se fier uniquement à la précision approximative et à la stabilité numérique, et non aux bits spécifiques calculés. Les modifications apportées aux formules numériques dans les versions mineures et les correctifs devraient entraîner une précision comparable ou améliorée, avec la mise en garde que l'amélioration de la précision de l'apprentissage automatique de formules spécifiques peut entraîner une diminution de la précision pour l'ensemble du système.
Nombres aléatoires: Les nombres aléatoires spécifiques calculés peuvent changer à tout moment. Les utilisateurs doivent se fier uniquement à des distributions et à une force statistique approximativement correctes, et non aux bits spécifiques calculés. Voir la génération de nombres aléatoires guide pour les détails.
Version distribuée dans skew tensorflow: Exécution de deux versions différentes de tensorflow dans un cluster est non pris en charge. Il n'y a aucune garantie quant à la rétrocompatibilité du protocole filaire.
Bugs: Nous nous réservons le droit de rendre les comportements en arrière incompatibles (mais pas l' API) change si l'implémentation actuelle est clairement rompue, qui est, si elle contredit la documentation ou si un bien connu et n'est pas correctement mis en œuvre un comportement bien intentionné défini en raison à un bogue. Par exemple, si un optimiseur prétend implémenter un algorithme d'optimisation bien connu mais ne correspond pas à cet algorithme en raison d'un bogue, nous corrigerons l'optimiseur. Notre correctif peut casser le code en s'appuyant sur un comportement incorrect pour la convergence. Nous noterons ces changements dans les notes de version.
API non utilisée: Nous nous réservons le droit de modifier en arrière incompatible avec les API pour lesquelles on ne trouve pas des utilisations documentées (en effectuant la vérification de l' utilisation tensorflow grâce à la recherche GitHub). Avant de procéder à ces changements, nous allons annoncer notre intention de faire le changement sur l' annonce @ liste de diffusion , fournissant des instructions sur la façon de régler les casses ( le cas échéant), et attendre deux semaines pour donner à notre communauté une chance de partager leurs commentaires .
Comportement d'erreur: On peut remplacer les erreurs avec le comportement non-erreur. Par exemple, nous pouvons modifier une fonction pour calculer un résultat au lieu de générer une erreur, même si cette erreur est documentée. Nous nous réservons également le droit de modifier le texte des messages d'erreur. De plus, le type d'une erreur peut changer à moins que le type d'exception pour une condition d'erreur spécifique ne soit spécifié dans la documentation.
Compatibilité des SavedModels, des graphiques et des points de contrôle
SavedModel est le format de sérialisation préféré à utiliser dans les programmes TensorFlow. SavedModels contiennent deux parties: Un ou plusieurs graphiques codés comme GraphDefs
et un point de contrôle. Les graphiques décrivent le flux de données des opérations à exécuter et les points de contrôle contiennent les valeurs de tenseur enregistrées des variables dans un graphique.
De nombreux utilisateurs de TensorFlow créent des SavedModels, les chargent et les exécutent avec une version ultérieure de TensorFlow. Conformément à semver , SavedModels écrit avec une version de tensorflow peuvent être chargées et évaluées avec une version ultérieure tensorflow avec le même version majeure.
Nous faisons des garanties supplémentaires pour SavedModels pris en charge. Nous appelons SavedModel qui a été créée en utilisant uniquement non dépréciée, API non expérimentale, non-compatibilité dans tensorflow version majeure N
un SavedModel pris en charge dans la version N
. Tout SavedModel pris en charge dans tensorflow version majeure N
peut être chargé et exécuté avec version majeure tensorflow N+1
. Cependant, la fonctionnalité requise pour construire ou modifier un tel modèle peut ne plus être disponible, donc cette garantie ne s'applique qu'au SavedModel non modifié.
Nous nous efforcerons de préserver la rétrocompatibilité le plus longtemps possible, afin que les fichiers sérialisés soient utilisables sur de longues périodes.
Compatibilité GraphDef
Les graphiques sont sérialisés par l'intermédiaire du GraphDef
tampon de protocole. Pour faciliter les changements en arrière incompatibles aux graphiques, chaque GraphDef
a un numéro de version distincte de la version tensorflow. Par exemple, GraphDef
version 17 dépréciée l' inv
op en faveur de la reciprocal
. La sémantique est :
Chaque version de tensorflow prend en charge un intervalle de
GraphDef
versions. Cet intervalle sera constant d'une version de correctif à l'autre et n'augmentera que dans les versions mineures. Laissant tomber soutien à uneGraphDef
la version ne se produira pour une version majeure de tensorflow (et seulement aligné avec le support de la version garantie pour SavedModels).Graphiques nouvellement créés sont attribués le dernier
GraphDef
numéro de version.Si une version donnée de tensorflow soutient la
GraphDef
version d'un graphique, il va charger et d' évaluer avec le même comportement que la version tensorflow utilisée pour générer (sauf pour plus de détails numérique à virgule flottante et nombres aléatoires comme indiqué ci - dessus), quelle que soit la majeure version de TensorFlow. En particulier, un GraphDef qui est compatible avec un fichier de point de contrôle dans une version de TensorFlow (comme c'est le cas dans un SavedModel) restera compatible avec ce point de contrôle dans les versions suivantes, tant que le GraphDef est pris en charge.Notez que cela ne vaut que pour les graphiques sérialisés dans GraphDefs (et SavedModels): Code qui se lit comme suit un point de contrôle ne peut pas être en mesure de lire les points de contrôle générés par le même code exécutant une version différente de tensorflow.
Si la
GraphDef
limite supérieure est augmentée à X dans un communiqué (mineur), il y aura au moins six mois avant la limite inférieure est augmentée à X. Par exemple (nous utilisons les numéros de version hypothétiques ici):- Tensorflow 1.2 peut prendre en charge
GraphDef
versions 4 à 7. - Tensorflow 1.3 pourrait ajouter
GraphDef
versions version 8 et support 4 à 8. - Au moins six mois plus tard, TensorFlow 2.0.0 pourrait abandonner la prise en charge des versions 4 à 7, ne laissant que la version 8.
Notez qu'étant donné que les versions majeures de TensorFlow sont généralement publiées à plus de 6 mois d'intervalle, les garanties pour les SavedModels pris en charge détaillées ci-dessus sont beaucoup plus solides que la garantie de 6 mois pour les GraphDefs.
- Tensorflow 1.2 peut prendre en charge
Enfin, lorsque le support pour une GraphDef
version est abandonnée, nous tenterons de fournir des outils pour convertir automatiquement des graphiques à une nouvelle prise en charge GraphDef
la version.
Compatibilité des graphiques et des points de contrôle lors de l'extension de TensorFlow
Cette section concerne uniquement en cas de modifications incompatibles au GraphDef
format, tel que lors de l' ajout ops, la suppression ops, ou de modifier la fonctionnalité des opérations existantes. La section précédente devrait suffire à la plupart des utilisateurs.
Compatibilité ascendante et ascendante partielle
Notre schéma de version a trois exigences :
- Rétrocompatibilité support graphiques de chargement et des points de contrôle créé avec les anciennes versions de tensorflow.
- Postcompatibilité à des scénarios de soutien où le producteur d'un graphique ou point de contrôle est mis à niveau vers une version plus récente de tensorflow avant que le consommateur.
- Activez l'évolution de TensorFlow de manière incompatible. Par exemple, supprimer des opérations, ajouter des attributs et supprimer des attributs.
Notez que si le GraphDef
mécanisme de version est distincte de la version tensorflow, les changements en arrière incompatibles au GraphDef
format sont encore limités par sémantique Versioning. Cette fonctionnalité de moyens ne peut être supprimé ou modifié entre MAJOR
versions de tensorflow ( par exemple 1.7
à 2.0
). De plus, la compatibilité ascendante est appliquée dans les versions Patch ( 1.x.1
à 1.x.2
par exemple).
Pour obtenir une compatibilité ascendante et descendante et savoir quand appliquer les changements de format, les graphiques et les points de contrôle ont des métadonnées qui décrivent quand ils ont été produits. Les sections ci - dessous détaillent la mise en œuvre tensorflow et des lignes directrices pour l' évolution GraphDef
versions.
Schémas de version de données indépendants
Il existe différentes versions de données pour les graphiques et les points de contrôle. Les deux formats de données évoluent à des rythmes différents l'un de l'autre et également à des rythmes différents de TensorFlow. Les deux systèmes versioning sont définis dans core/public/version.h
. Chaque fois qu'une nouvelle version est ajoutée, une note est ajoutée à l'en-tête détaillant ce qui a changé et la date.
Données, producteurs et consommateurs
Nous distinguons les types d'informations de version de données suivants :
- producteurs: binaires qui produisent des données. Les producteurs ont une version (
producer
) et une version minimale des consommateurs qu'ils sont compatibles avec (min_consumer
). - les consommateurs: les binaires qui consomment des données. Les consommateurs ont une version (
consumer
) et une version de production minimum qu'ils sont compatibles avec (min_producer
).
Chaque morceau de données versionnées a une VersionDef versions
domaine qui enregistre le producer
qui a fait les données, le min_consumer
qu'il est compatible avec, et une liste des bad_consumers
versions qui sont interdites.
Par défaut, lorsqu'un producteur fait des données, les données hérite du producteur producer
et min_consumer
versions. bad_consumers
peuvent être réglés si des versions spécifiques des consommateurs sont connus pour contenir des bogues et doivent être évités. Un consommateur peut accepter une donnée si toutes les conditions suivantes sont vraies :
-
consumer
> = ses donnéesmin_consumer
- de données
producer
> = consommateur demin_producer
-
consumer
non de donnéesbad_consumers
Étant donné que les producteurs et les consommateurs proviennent de la même base de code tensorflow, core/public/version.h
contient une version de données principale qui est considérée soit comme producer
ou consumer
selon le contexte et les deux min_consumer
et min_producer
(nécessaire par les producteurs et les consommateurs, respectivement) . Spécifiquement,
- Pour
GraphDef
versions, nous avonsTF_GRAPH_DEF_VERSION
,TF_GRAPH_DEF_VERSION_MIN_CONSUMER
etTF_GRAPH_DEF_VERSION_MIN_PRODUCER
. - Pour les versions de point de contrôle, nous avons
TF_CHECKPOINT_VERSION
,TF_CHECKPOINT_VERSION_MIN_CONSUMER
etTF_CHECKPOINT_VERSION_MIN_PRODUCER
.
Ajouter un nouvel attribut par défaut à une opération existante
Suivre les instructions ci-dessous vous donne une compatibilité ascendante uniquement si l'ensemble d'opérations n'a pas changé :
- Si la compatibilité ascendante est souhaitée, mettre
strip_default_attrs
àTrue
lors de l' exportation du modèle en utilisant soit lestf.saved_model.SavedModelBuilder.add_meta_graph_and_variables
ettf.saved_model.SavedModelBuilder.add_meta_graph
méthodes de laSavedModelBuilder
classe, outf.estimator.Estimator.export_saved_model
- Cela supprime les attributs valorisés par défaut au moment de la production/exportation des modèles. Cela fait en sorte que l'exportation
tf.MetaGraphDef
ne contient pas le nouveau op-attribut est utilisé lorsque la valeur par défaut. - Le fait de disposer de ce contrôle pourrait permettre aux consommateurs obsolètes (par exemple, les binaires de diffusion qui sont en retard par rapport aux binaires d'entraînement) de continuer à charger les modèles et d'éviter les interruptions de la diffusion des modèles.
Évolution des versions de GraphDef
Cette section explique comment utiliser ce mécanisme pour faire versioning différents types de modifications au GraphDef
format.
Ajouter une opération
Ajouter le nouveau op aux consommateurs et aux producteurs en même temps, et ne changent pas de GraphDef
versions. Ce type de modification est automatiquement rétrocompatible et n'a pas d'impact sur le plan de compatibilité ascendante, car les scripts de producteur existants n'utiliseront pas soudainement la nouvelle fonctionnalité.
Ajouter une opération et changer les wrappers Python existants pour l'utiliser
- Mettre en œuvre de nouvelles fonctionnalités à la consommation et incrémenter la
GraphDef
la version. - S'il est possible de faire en sorte que les wrappers utilisent la nouvelle fonctionnalité uniquement dans des cas qui ne fonctionnaient pas auparavant, les wrappers peuvent être mis à jour maintenant.
- Modifiez les wrappers Python pour utiliser la nouvelle fonctionnalité. Ne pas incrément
min_consumer
, puisque les modèles qui n'utilisent pas cette op ne devrait pas se casser.
Supprimer ou restreindre la fonctionnalité d'une opération
- Corrigez tous les scripts de producteur (pas TensorFlow lui-même) pour ne pas utiliser l'opération ou la fonctionnalité interdite.
- Incrémenter la
GraphDef
version et la mise en œuvre de nouvelles fonctionnalités de consommation qui interdit l'op ou supprimé fonctionnalité pour GraphDefs à la nouvelle version et au- dessus. Si possible, faire cesser la production tensorflowGraphDefs
avec la fonctionnalité interdite. Pour ce faire, ajoutez leREGISTER_OP(...).Deprecated(deprecated_at_version, message)
. - Attendez une version majeure à des fins de compatibilité descendante.
- Augmenter
min_producer
à la version GraphDef de (2) et de supprimer entièrement la fonctionnalité.
Modifier la fonctionnalité d'une opération
- Ajouter une nouvelle op similaire nommée
SomethingV2
ou similaire et passer par le processus d'ajout et de commutation wrappers Python existants pour l' utiliser. Pour assurer une utilisation de compatibilité avant les contrôles proposés dans compat.py lors du changement des emballages Python. - Supprimez l'ancienne opération (ne peut avoir lieu qu'avec un changement de version majeur en raison de la rétrocompatibilité).
- Augmenter
min_consumer
pour écarter les consommateurs avec l'ancien op, rajoutez l'ancien op comme un alias pourSomethingV2
et passer par le processus pour passer wrappers Python existant pour l' utiliser. - Passez par le processus pour enlever
SomethingV2
.
Interdire une seule version grand public non sécurisée
- Bump la
GraphDef
la version et ajouter la mauvaise version à l'bad_consumers
pour tous les nouveaux GraphDefs. Si possible, ajouter àbad_consumers
uniquement pour GraphDefs qui contiennent un certain op ou similaire. - Si les consommateurs existants ont la mauvaise version, poussez-les dès que possible.