Как TensorFlow обрабатывает обратную совместимость в разных версиях
machine-learning tensorflow-savedmodel tensorflow-versioning tensorflow-compatibility tensorflow-graphdef tensorflow-api-changes tensorflow-lite-versioning tensorflow-upgrade-guide tf-backward-compatibility

Как TensorFlow обрабатывает обратную совместимость в разных версиях

14 августа 2025 г.

Обзор контента

  • Семантические версии 2.0
  • Что покрыто
  • Отдельный номер версии Forthensorflow Lite
  • Отдельный номер версии для API расширения TensorFlow Lite
  • Что не покрыто
  • Совместимость сохраненных моделей, графиков и контрольных точек
  • Совместимость графика
  • Совместимость с графиками и контрольной точкой при расширении TensorFlow
  • Обратная и частичная совместимость вперед
  • Независимые схемы версий данных
  • Данные, производители и потребители
  • Добавить новый атрибут по умолчанию к существующему OP
  • Развивающиеся версии графика

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

Семантические версии 2.0

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

  • ГЛАВНЫЙ: Потенциально назад несовместимые изменения. Код и данные, которые работали с предыдущим крупным выпуском, не обязательно будут работать с новым выпуском. Тем не менее, в некоторых случаях существующие графики тензора и контрольные точки могут быть перенесены на более новый релиз; видетьСовместимость графиков и контрольных точекДля получения подробной информации о совместимости данных.
  • НЕЗНАЧИТЕЛЬНЫЙ: Обратно совместимые функции, улучшения скорости и т. Д. Код и данные, которые работали с предыдущим незначительным выпускомичто зависит только от неэкспериментального общественного API, будет продолжать работать без изменений. Для получения подробной информации о том, что является и не является публичным API, см.Что покрытоПолем Обратите внимание, что TensorFlow иногда вносит нарушающие изменения в новых незначительных выпусках, где ожидается, что воздействие будет незначительным. Примеры таких изменений см. В разделе «Разрушенные изменения» для прошлых незначительных выпусков вhttps://github.com/tensorflow/tensorflow/releases
  • ПЛАСТЫРЬ: Обратно совместимых исправлений ошибок.

Например, релиз 1.0.0 введен назаднесовместимыйИзменения от выпуска 0,12,1. Тем не менее, релиз 1.1.1 был задом напередсовместимыйС выпуском 1.0.0.

Что покрыто

Только публичные APIS Tensorflow являются обратно, совместимы с минорными и патч -версиями. Общественные API состоят из

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

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

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

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

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

  • TensorFlow C API:

    • TensorFlow/C/C_API.H

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

    • attr_value
    • config
    • event
    • graph
    • op_def
    • reader_base
    • summary
    • tensor
    • tensor_shape
    • types

Отдельный номер версии для TensorFlow Lite

В настоящее время Tensorflow Lite распределяется как часть Tensorflow. Тем не менее, мы оставляем за собой право в будущих изменениях выпуска на API -интерфейсы Tensorflow Lite в другом графике, чем для других API -интерфейсов Tensorflow, или даже перемещать Tensorflow Lite в отдельное распределение источника и/или отдельное хранилище источника, чем TensorFlow.

Из -за этого мы используем другой номер версии для Tensorflow Lite (TFLITE_VERSION_STRINGвtensorflow/lite/version.h, иTfLiteVersion()вtensorflow/lite/c/c_api.h), чем для TensorFlow (TF_VERSION_STRINGвtensorflow/core/public/release_version.h, иTF_Version()вtensorflow/c/c_api.h) В настоящее время эти два номера версий имеют одинаковое значение. Но в будущем они могут расходиться; Например, мы можем увеличить основной номер версии для Tensorflow Lite, не увеличивая основной номер версии для TensorFlow, или наоборот.

Поверхность API, покрытая номером версии TensorFlow Lite, состоит из следующих публичных API:

  • TensorFlow Lite C API:
    • tensorflow/lite/c/c_api.h
    • tensorflow/lite/c/c_api_types.hПолем
  • Tensorflow Lite Android (Java/Kotlin) API:
    • Вorg.tensorflow.lite:
      • org.tensorflow.lite.tensorflowtite
      • org.tensorflow.lite.interpreterapi
      • org.tensorflow.lite.delegate
      • org.tensorflow.lite.delegatefactory
      • org.tensorflow.lite.tensor
      • org.tensorflow.lite.datatype
      • org.tensorflow.lite.runtimeflavor
    • Вorg.tensorflow.lite.gpu:
      • org.tensorflow.lite.gpu.gpudelegate
      • org.tensorflow.lite.gpu.gpudelegatefactory
  • Tensorflow Lite Objective-C APIS:
    • tensorflow/lite/objc/apis/
      • Tflcoremldelegate.h
      • Tfldelegate.h
      • Tflinterpreter.h
      • Tflinterpreteroptions.h
      • Tflmetaldelegate.h
      • TflquantizationParameters.h
      • Tflsignaturerunner.h
      • Tfltensorflowlite.h
      • Tfltensor.h
  • Tensorflow Lite Swift API:
    • tensorflow/lite/swift/источники/Полем
      • Coremldelegate.swift
      • Delegate.swift
      • Interpretererror.swift
      • Переводчик.swift
      • Metalledelegate.swift
      • Model.Swift
      • Квантование PPARAMETERS.Swift
      • SignatureRunnerRor.swift
      • Signaturerunner.swift
      • Tensorflowlite.swift
      • Tensor.Swift

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

Отдельный номер версии для API расширения TensorFlow Lite

TensorFlow Lite предоставляет API C для расширения интерпретатора TensorFlow Lite с помощью «пользовательские операции», которые предоставляют пользовательские операции на графике или «делегаты», которые позволяют делегировать вычисление для графа (или для подмножества графа) в пользовательскую подкладную. Эти API, которые мы в совокупности называем «API расширения TensorFlow Lite», требуют более интимных зависимостей от некоторых деталей реализации Tensorflow Lite.

Мы оставляем за собой право в будущих изменениях в этих API, которые потенциально включают в себя не совместимые с Backwards изменения, в другом графике, чем для других API-интерфейсов Tensorflow Lite. Таким образом, мы используем другой номер версии для API расширения Tensorflow Lite, чем номера версий для Tensorflow Lite или TensorFlow (которые были описаны в предыдущем разделе). Мы представляем некоторые новые API в Tensorflow Lite версии 2.15, чтобы получить версию API расширения TensorFlow Lite (TFLITE_EXTENSION_APIS_VERSION_STRINGвtensorflow/lite/version.hи tfliteextensionApisversion () вtensorflow/lite/c/c_api.h) Номер версии для API расширения Tensorflow Lite в настоящее время совпадает с номером версии для Tensorflow и Tensorflow Lite. Но в будущем они могут расходиться; Например, мы можем увеличить основной номер версии для API расширения TensorFlow Lite, не увеличивая основной номер версии для TensorFlow Lite, или наоборот.

Поверхность API, покрытая номером версии API удлинения TensorFlow Lite, состоит из следующих публичных API:

  • tensorflow/lite/c/c_api_opaque.h
  • tensorflow/lite/c/common.h
  • tensorflow/lite/c/buldin_op_data.h
  • Tensorflow/lite/buldin_ops.h

Опять же, экспериментальные символы не покрыты; видетьнижеДля получения подробной информации.

Что такоенетпокрытый

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

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

    • любой символ вtf.contribмодуль или его подмодули;
    • Любой символ (модуль, функция, аргумент, свойство, класс, константа, тип, пакет и т. Д.)experimentalилиExperimental; или
    • Любой символ которого полностью квалифицированное имя, включает в себя модуль, класс или пакет, который сам по себе является экспериментальным. Это включает в себя поля и подводные материалы любого буфера протокола под названиемexperimentalПолем

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

    • C ++(выставлены через файлы заголовков вtensorflow/cc/)
    • ЯваВ
    • Идти
    • JavaScript

    и TensorflowЛайтAPI в языках, отличных от Java/Kotlin, C, Objective-C и Swift, в частности

    • C ++(выставлены через файлы заголовков вtensorflow/lite/)

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

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

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

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

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

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

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

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

SaveedModel - это предпочтительный формат сериализации для использования в программах Tensorflow. Сохраненные модели содержат две части: один или несколько графиков, кодируемых какGraphDefsи контрольно -пропускной пункт. Графики описывают поток данных OPS, который будет выполнен, а контрольные точки содержат сохраненные тензорные значения переменных на графике.

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

Мы делаем дополнительные гарантии дляПоддерживаетсяСохраненные модели. Мы называем SavedModel, которая была создана с помощьюТолько не изящные, неэкспериментальные, не совместимые APISв основной версии TensorFlowNаSaveedModel поддержана в версииNПолем Любая сохраненная модель, поддерживаемая в основной версии TensorFlowNможет быть загружен и выполнен с помощью основной версии TensorFlowN+1Полем Тем не менее, функциональность, необходимая для создания или изменения такой модели, может больше не быть доступна, поэтому эта гарантия применяется только к немодифицированной сохраненной модели.

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

Совместимость графика

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

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

  • Недавно созданному графикам назначается последняяGraphDefномер версии.

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

    Обратите внимание, что это относится только к сериализованным графикам в графиках (и сохраненных моделях):Кодкоторый считывает контрольно -пропускной пункт, может быть не в состоянии прочитать контрольные точки, сгенерированные одним и тем же кодом с другой версией 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 месяцев, гарантии для поддерживаемых сохраненных моделей, подробно описанных выше, намного сильнее, чем гарантия GraphDefs 6 месяцев.

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

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

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

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

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

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

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

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

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

Существуют разные версии данных для графиков и контрольных точек. Два формата данных развиваются в разных скоростях друг от друга, а также с разными скоростями от Tensorflow. Обе системы управления версиями определены вcore/public/version.hиcore/public/release_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Полем

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

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

  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формат.

Добавить оп

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

Добавьте OP и переключатель существующих оберток Python, чтобы использовать его

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

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

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

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

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

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

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

Первоначально опубликовано наTensorflowВеб -сайт, эта статья появляется здесь под новым заголовком и имеет лицензию в CC на 4.0. Образцы кода, разделенные по лицензии Apache 2.0.

Оригинал

Recent Post

Categories

PREVIOUS ARTICLE
NEXT ARTICLE