Помогают защитить Большой Барьерный Риф с TensorFlow на Kaggle Присоединяйтесь вызов

Совместимость версий TensorFlow

Этот документ предназначен для пользователей, которым требуется обратная совместимость с различными версиями TensorFlow (для кода или данных), а также для разработчиков, которые хотят изменить TensorFlow при сохранении совместимости.

Семантическое управление версиями 2.0

TensorFlow следует Semantic Versioning 2,0 ( semver ) для его публичного API. Каждая версия выпуск TensorFlow имеет вид MAJOR.MINOR.PATCH . Например, TensorFlow версия 1.2.3 имеет MAJOR версии 1, MINOR версию 2 и PATCH версию 3. Изменения к каждому номеру , имеют следующее значение:

  • MAJOR: Потенциально назад несовместимые изменения. Код и данные, которые работали с предыдущим основным выпуском, не обязательно будут работать с новым выпуском. Однако в некоторых случаях существующие графики и контрольные точки TensorFlow можно перенести на более новую версию; см Совместимость графиков и контрольных точек для подробной информации о совместимости данных.

  • МАЛЫЙ: задом совместимые функции, улучшение скорости и т.д. Код и данные , которые работали с предыдущим выпуском малого и которая зависит только от неэкспериментального общественного API будет продолжать работать без изменений. Более подробную информацию о том , что и не является публичной API см Что покрывает .

  • PATCH: Backwards совместимые исправления ошибок.

Например, выпуск 1.0.0 введены назад несовместимые изменения от выпуска 0.12.1. Тем не менее, релиз 1.1.1 был обратно совместим с версии 1.0.0.

Что покрыто

Только общедоступные API-интерфейсы TensorFlow имеют обратную совместимость между минорными версиями и версиями исправлений. Публичные API состоят из

  • Все документированные Python функции и классы в tensorflow модуле и его подмодулей, за исключением

    • Частные символы: любая функция, класс и т.д., чьи имя начинается с _
    • Экспериментальные и tf.contrib символы, см ниже для деталей.

    Обратите внимание , что код в examples/ и tools/ каталогах не достижим через tensorflow модуль Python и, таким образом , не покрывается гарантией совместимости.

    Если символ доступен через tensorflow модуль Python или его подмодули, но не документирован, то она не считается частью общественного API.

  • API совместимость (в Python, то tf.compat модуль). В основных версиях мы можем выпускать служебные программы и дополнительные конечные точки, чтобы помочь пользователям перейти на новую основную версию. Эти символы API устарели и не поддерживаются (т. Е. Мы не будем добавлять никаких функций и не будем исправлять ошибки, кроме исправления уязвимостей), но они подпадают под наши гарантии совместимости.

  • C API .

  • Следующие файлы буферов протокола:

Что не покрывается

Некоторые части TensorFlow могут измениться обратно несовместимыми способами в любой момент. Это включает:

  • Экспериментальные API: Для облегчения разработки, мы освободить некоторые символы API четко обозначенные как экспериментальные от гарантии совместимости. В частности, гарантии совместимости не распространяются на следующее:

    • любой символ в tf.contrib модуля или его подмодулей;
    • любой символ (модуль, функция, аргумент, свойство, класс, или константа), имя которого содержит experimental или Experimental ; или
    • любой символ, полное имя которого включает модуль или класс, который сам является экспериментальным. Это включает в себя поля и submessages любого буфера протокола называется experimental .
  • Другие языки: TensorFlow API , в других , чем Python и C языков, таких как:

  • Подробная информация о составных опс: Многие общественные функции в Python расширить до нескольких примитивных опсов в графе, и эти детали будут являться частью любых графиков , сохраненных на диск как GraphDef s. Эти детали могут измениться для второстепенных выпусков. В частности, регрессионные тесты, которые проверяют точное соответствие между графиками, вероятно, не работают в незначительных версиях, даже если поведение графика должно быть неизменным, а существующие контрольные точки будут работать.

  • С плавающей точкой числовых деталей: Значения с плавающей точкой конкретных вычисленных ОПСОМ может измениться в любой момент. Пользователи должны полагаться только на приблизительную точность и числовую стабильность, а не на конкретные вычисленные биты. Изменения числовых формул в второстепенных выпусках и версиях исправлений должны привести к сравнимой или улучшенной точности, с оговоркой, что в машинном обучении повышенная точность конкретных формул может привести к снижению точности для всей системы.

  • Номера Случайные: Конкретные случайные числа вычисленных может измениться в любой момент. Пользователи должны полагаться только на приблизительно правильные распределения и статистическую силу, а не на конкретные вычисленные биты. Смотрите случайное число поколения руководства для деталей.

  • Версия перекос в распределенной Tensorflow: Запуск двух различных версий TensorFlow в одном кластере не поддерживается. Нет никаких гарантий относительно обратной совместимости проводного протокола.

  • Ошибки: Мы оставляем за собой право вносить назад несовместимое поведение (хотя и не API) меняется , если текущая реализация явно нарушена, то есть, если это противоречит документации , или если хорошо известно и хорошо определенно предназначенные поведение не должным образом реализован из - за к ошибке. Например, если оптимизатор утверждает, что реализует известный алгоритм оптимизации, но не соответствует этому алгоритму из-за ошибки, мы исправим оптимизатор. Наше исправление может привести к поломке кода из-за неправильного поведения для сходимости. Мы отметим такие изменения в примечаниях к выпуску.

  • Неиспользованный API: Мы оставляем за собой право вносить назад несовместимые изменения в API , для которых мы не находим документированные использования (путем выполнения аудита использования TensorFlow через поиск GitHub). Перед выполнением каких - либо таких изменений, мы заявляем о своем намерении внести изменения на список рассылки объявить @ , предоставляя инструкции о том , как решать любые обрывы (если применимо), и ждать в течение двух недель , чтобы дать нашему сообществу возможность обменяться обратной связи .

  • Поведение ошибки: Мы можем заменить ошибки с поведением , не ошибка. Например, мы можем изменить функцию для вычисления результата вместо того, чтобы выдавать ошибку, даже если эта ошибка задокументирована. Мы также оставляем за собой право изменять текст сообщений об ошибках. Кроме того, тип ошибки может измениться, если в документации не указан тип исключения для конкретного условия ошибки.

Совместимость SavedModels, графиков и контрольных точек

SavedModel - предпочтительный формат сериализации для использования в программах TensorFlow. SavedModels содержат две части: одна или несколько графиков , закодированных в GraphDefs и контрольно - пропускной пункт. Графики описывают поток данных выполняемых операций, а контрольные точки содержат сохраненные тензорные значения переменных на графике.

Многие пользователи TensorFlow создают SavedModels, загружают и выполняют их с помощью более поздней версии TensorFlow. В соответствии с semver , SavedModels написанного с одной версией TensorFlow может быть загружено и оценено с более поздней версией TensorFlow с одной и той же основной версией.

Мы делаем дополнительные гарантии для поддерживаемых SavedModels. Мы называем SavedModel , который был создан с использованием только не осуждается, неэкспериментальной, API без совместимости в TensorFlow основной версии N SavedModel поддерживается в версии N . Любой SavedModel поддерживается в TensorFlow основной версии N может быть загружен и выполнен с TensorFlow главной версией N+1 . Однако функциональные возможности, необходимые для создания или изменения такой модели, могут быть больше недоступны, поэтому эта гарантия распространяется только на немодифицированную SavedModel.

Мы постараемся сохранить обратную совместимость как можно дольше, чтобы сериализованные файлы можно было использовать в течение длительных периодов времени.

Совместимость с GraphDef

Графики сериализовать через GraphDef буфер протокола. Для облегчения назад несовместимые изменения графиков, каждый из GraphDef имеет номер версии отдельно от версии TensorFlow. Например, GraphDef версия 17 осуждала inv ора в пользу reciprocal . Семантика:

  • Каждая версия TensorFlow поддерживает интервал GraphDef версий. Этот интервал будет постоянным для всех выпусков исправлений и будет увеличиваться только для второстепенных выпусков. Удаление поддержки для GraphDef версии будет происходить только для основной версии TensorFlow (и только в соответствии с версией гарантируемой для SavedModels).

  • Вновь созданные графики назначены последние GraphDef номер версии.

  • Если данная версия TensorFlow поддерживает GraphDef версию графа, она будет загружать и оценивать с тем же поведением , как версия TensorFlow используется для его генерации ( с плавающей запятой числовой детали и случайные числа , за исключением того, как описана выше), независимо от основных версия TensorFlow. В частности, GraphDef, который совместим с файлом контрольной точки в одной версии TensorFlow (например, в случае SavedModel), останется совместимым с этой контрольной точкой в ​​последующих версиях, пока поддерживается GraphDef.

    Обратите внимание , что это относится только к сериализованным Графам в GraphDefs (и SavedModels): Код , который гласит контрольная точка не может быть в состоянии прочитать контрольные точки , генерируемые одним и тем же кодом , исполняемый другую версию TensorFlow.

  • Если GraphDef верхняя граница увеличивается до X в (минор) релиз, будет по крайней мере за шесть месяцев до того , как нижняя граница увеличивается до X. Для примера (мы используем гипотетические номера версий здесь):

    • TensorFlow 1,2 может поддерживать GraphDef версий 4 до 7.
    • TensorFlow 1,3 может добавить GraphDef версии 8 и поддержка версии от 4 до 8.
    • По крайней мере, шесть месяцев спустя TensorFlow 2.0.0 может отказаться от поддержки версий с 4 по 7, оставив только версию 8.

    Обратите внимание: поскольку основные версии TensorFlow обычно публикуются с интервалом более 6 месяцев, гарантии для поддерживаемых моделей SavedModels, описанные выше, намного сильнее, чем 6-месячная гарантия для GraphDefs.

Наконец, когда поддержка для GraphDef версии отбрасывается, мы попытаемся предоставить инструменты для автоматического преобразования графики в новой поддерживаемой GraphDef версии.

Совместимость графиков и контрольных точек при расширении TensorFlow

Этот раздел относится только при внесении несовместимых изменений в GraphDef формате, например, при добавлении ОПС, удаление ОПС, или изменение функциональных возможностей существующих ОПС. Предыдущего раздела должно хватить для большинства пользователей.

Обратная и частичная прямая совместимость

Наша схема управления версиями имеет три требования:

  • Обратная совместимость для поддержки загрузки графики и контрольно - пропускных пунктов , созданная с более старыми версиями TensorFlow.
  • Форвард совместимость для сценариев поддержки , где производитель графика или контрольно - пропускного пункта будет повышен до более новой версии TensorFlow до потребителя.
  • Включите развивающийся TensorFlow несовместимыми способами. Например, удаление операций, добавление атрибутов и удаление атрибутов.

Обратите внимание , что в то время как GraphDef версии механизм отделен от версии TensorFlow, назад несовместимые изменения в GraphDef формат все еще ограничены семантические версии. Эти функциональные средства могут быть удалены или изменены только между MAJOR версиями TensorFlow (например, 1.7 до 2.0 ). Кроме того, прямая совместимость обеспечивается в выпусках Patch ( 1.x.1 к 1.x.2 , например).

Чтобы достичь обратной и прямой совместимости и знать, когда применять изменения в форматах, графики и контрольные точки имеют метаданные, которые описывают, когда они были созданы. В нижеследующих разделах подробно реализация TensorFlow и рекомендации по эволюционирует GraphDef версии.

Схемы независимых версий данных

Существуют разные версии данных для графиков и контрольных точек. Эти два формата данных развиваются с разной скоростью друг от друга, а также с разной скоростью по сравнению с TensorFlow. Обе системы управления версиями определены в core/public/version.h . Каждый раз, когда добавляется новая версия, в заголовок добавляется примечание с подробным описанием изменений и датой.

Данные, производители и потребители

Мы различаем следующие типы информации о версии данных:

  • производители: двоичные файлы , которые производят данные. Производители имеют версию ( producer ) и минимальную пользовательскую версию , что они совместимы с ( min_consumer ).
  • потребители: двоичные файлы , которые потребляют данные. Потребители имеют версию ( consumer ) и версию минимум производителя , что они совместимы с ( min_producer ).

Каждая часть версионированных данных имеет VersionDef versions поле , которое записывает producer , который сделал данные, то min_consumer , что он совместим с, и список bad_consumers версий, которые засчитали.

По умолчанию, когда производитель делает какие - то данные, данные наследует продюсер producer и min_consumer версии. bad_consumers может быть установлен , если конкретные варианты потребления , как известно, содержат ошибки и их следует избегать. Потребитель может принять часть данных, если выполняются все следующие условия:

  • consumer > = Дейты min_consumer
  • Дейтов producer > = потребитель min_producer
  • consumer не Дейты bad_consumers

Так как производители , так и потребители приходят из того же базового кода TensorFlow, core/public/version.h содержит основную версию данных , которая рассматривается как либо producer или consumer в зависимости от контекста и оба min_consumer и min_producer (необходимо производителями и потребителями, соответственно) . Конкретно,

  • Для GraphDef версий, у нас есть TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER и TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Для версий контрольных точек, мы имеем TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMER и TF_CHECKPOINT_VERSION_MIN_PRODUCER .

Добавить новый атрибут по умолчанию к существующей операции

Следуя приведенным ниже инструкциям, вы получите прямую совместимость, только если набор операций не изменился:

  1. Если прямая совместимость требуется, установите strip_default_attrs в True , при экспорте модели с использованием как tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables и tf.saved_model.SavedModelBuilder.add_meta_graph методы SavedModelBuilder класса или tf.estimator.Estimator.export_saved_model
  2. Это удаляет атрибуты со значениями по умолчанию во время создания / экспорта моделей. Это гарантирует , что экспортируемые tf.MetaGraphDef не содержит новый операционный атрибут , когда используется значение по умолчанию.
  3. Наличие этого элемента управления может позволить устаревшим потребителям (например, обслуживающим двоичные файлы, которые отстают от обучающих двоичных файлов) продолжить загрузку моделей и предотвратить перерывы в обслуживании моделей.

Развитие версий GraphDef

В этом разделе объясняется , как использовать этот механизм контроля версий , чтобы сделать различные типы изменений в GraphDef формат.

Добавить операцию

Добавьте новый цит для потребителей и производителей в то же время, и не меняйте GraphDef версии. Этот тип изменения автоматически обеспечивает обратную совместимость и не влияет на план прямой совместимости, поскольку существующие сценарии производителей не будут использовать новые функции внезапно.

Добавить операцию и переключить существующие оболочки Python на ее использование

  1. Внедрение новых функциональных возможностей потребителей и увеличивать GraphDef версию.
  2. Если можно заставить оболочки использовать новую функциональность только в случаях, которые раньше не работали, оболочки можно обновить сейчас.
  3. Измените оболочки Python, чтобы использовать новую функциональность. Не инкремент min_consumer , так как модели , которые не используют этот ор не должен ломаться.

Удалить или ограничить функциональность операции

  1. Исправьте все скрипты производителя (не сам TensorFlow), чтобы они не использовали запрещенную операцию или функциональность.
  2. Увеличивает GraphDef версию и реализовать новые функциональные возможности потребителей , что запрет на удаленной оп или функциональности для GraphDefs в новой версии и выше. Если это возможно, TensorFlow прекратить производство GraphDefs с запрещенной функциональностью. Для этого добавьте REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Дождитесь основного выпуска для целей обратной совместимости.
  4. Увеличение min_producer до версии GraphDef из (2) и удалить функциональные возможности полностью.

Изменить функциональность операции

  1. Добавить новую аналогичные оп имя SomethingV2 или аналогичную и пройти через процесс добавления его и переключение существующих оберток Python , чтобы использовать его. Для того, чтобы обеспечить использование прямой совместимости проверок , предложенные в compat.py при изменении оберток Python.
  2. Удалите старую операцию (возможно только при изменении основной версии из-за обратной совместимости).
  3. Увеличение min_consumer , чтобы исключить потребитель со старым оп, добавить обратно старый цит как псевдоним для SomethingV2 , и пройти через процесс для переключения существующих оберток Python , чтобы использовать его.
  4. Пройдите через процесс удаления SomethingV2 .

Запретить одну небезопасную потребительскую версию

  1. Bump в GraphDef версию и добавить плохую версию bad_consumers для всех новых GraphDefs. Если возможно, добавить к bad_consumers только для GraphDefs , которые содержат определенный цит или аналогичный.
  2. Если у существующих потребителей есть плохая версия, вытолкните их как можно скорее.