Совместимость с версией 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. Изменения каждого номера имеют следующее значение:

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

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

  • ИСПРАВЛЕНИЕ : Исправлены ошибки, совместимые с предыдущими версиями.

Например, в выпуске 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 ; или
    • любой символ, полное имя которого включает модуль или класс, который сам по себе является экспериментальным. Сюда входят поля и подсообщения любого буфера протокола, называемого experimental .

  • Другие языки : API-интерфейсы TensorFlow на языках, отличных от Python и C, например:

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

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

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

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

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

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

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

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

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

Многие пользователи TensorFlow создают модели SavedModel, а затем загружают и выполняют их в более поздних версиях 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 op в пользу reciprocal . Семантика такова:

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

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

  • Если данная версия GraphDef поддерживает версию графа 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 ). Кроме того, в выпусках исправлений применяется прямая совместимость (например, с 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. Увеличьте версию GraphDef и добавьте неверную версию в bad_consumers для всех новых GraphDef. Если возможно, добавьте в bad_consumers только те GraphDef, которые содержат определенную операцию или что-то подобное.
  2. Если у существующих потребителей плохая версия, вытесните их как можно скорее.