Эта страница была переведа с помощью Cloud Translation API.
Switch to English

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

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

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

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

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

  • НЕЗАВИСИМЫЕ : функции обратной совместимости, улучшения скорости и т. Д. Код и данные, которые работали с предыдущим второстепенным выпуском и которые зависят только от неэкспериментального общедоступного 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 и поэтому не покрывается гарантией совместимости.

    Если символ доступен через модуль 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). Прежде чем вносить какие-либо такие изменения, мы объявим о своем намерении внести изменения в список рассылки announce @ , предоставив инструкции по устранению любых неполадок (если применимо), и подождем две недели, чтобы дать нашему сообществу возможность поделиться своими отзывами. .

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

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

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

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

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

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

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

Графики сериализуются через GraphDef протокола GraphDef . Чтобы упростить обратную несовместимость изменений графиков, каждый GraphDef имеет номер версии, GraphDef от версии GraphDef . Например, 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 отделен от версии GraphDef , обратно несовместимые изменения в формате GraphDef по-прежнему ограничиваются семантическим управлением версиями. Это означает, что функциональность может быть удалена или изменена только в MAJOR версиях TensorFlow (например, от 1.7 до 2.0 ). Кроме того, прямая совместимость обеспечивается в выпусках Patch ( 1.x.1 к 1.x.2 , например).

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

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

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

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

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

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

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

По умолчанию, когда производитель создает некоторые данные, данные наследуют min_consumer 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 не содержит новый op-атрибут, когда используется значение по умолчанию.
  3. Наличие этого элемента управления может позволить устаревшим потребителям (например, обслуживающим двоичные файлы, которые отстают от обучающих двоичных файлов) продолжить загрузку моделей и предотвратить перерывы в обслуживании моделей.

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

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

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

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

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

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

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

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

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

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

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

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