Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Compatibilidad con la versión TensorFlow

Este documento es para usuarios que necesitan compatibilidad con versiones anteriores de diferentes versiones de TensorFlow (ya sea para código o datos), y para desarrolladores que desean modificar TensorFlow y preservar la compatibilidad.

Versiones semánticas 2.0

TensorFlow sigue a Semantic Versioning 2.0 ( semver ) para su API pública. Cada versión de lanzamiento de TensorFlow tiene la forma MAJOR.MINOR.PATCH . Por ejemplo, TensorFlow versión 1.2.3 tiene MAJOR versión 1, MINOR versión 2 y PATCH versión 3. Los cambios en cada número tienen el siguiente significado:

  • MAYOR : Cambios potencialmente incompatibles hacia atrás. El código y los datos que funcionaron con una versión principal anterior no necesariamente funcionarán con la nueva versión. Sin embargo, en algunos casos, los gráficos y puntos de control existentes de TensorFlow pueden migrarse a la versión más reciente; Consulte Compatibilidad de gráficos y puntos de control para obtener detalles sobre la compatibilidad de datos.

  • MENOR : características compatibles con versiones anteriores, mejoras de velocidad, etc. El código y los datos que funcionaron con una versión menor anterior y que depende solo de la API pública no experimental continuarán funcionando sin cambios. Para obtener detalles sobre qué es y qué no es la API pública, consulte Qué está cubierto .

  • PARCHE : correcciones de errores compatibles con versiones anteriores.

Por ejemplo, la versión 1.0.0 introdujo cambios incompatibles con versiones anteriores de la versión 0.12.1. Sin embargo, la versión 1.1.1 era compatible con versiones 1.0.0.

Lo que está cubierto

Solo las API públicas de TensorFlow son compatibles con versiones anteriores y parches. Las API públicas consisten en

  • Todas las funciones y clases de Python documentadas en el módulo tensorflow y sus submódulos, excepto

    • Símbolos privados: cualquier función, clase, etc., cuyo nombre comience por _
    • Símbolos experimentales y tf.contrib , ver más abajo para más detalles.

    Tenga en cuenta que el código en los examples/ y tools/ directorios no es accesible a través del módulo Python tensorflow y, por lo tanto, no está cubierto por la garantía de compatibilidad.

    Si un símbolo está disponible a través de la tensorflow módulo de Python o sus submódulos, pero no está documentado, entonces no se considera parte de la API pública.

  • La API de compatibilidad (en Python, el módulo tf.compat ). En las versiones principales, podemos lanzar utilidades y puntos finales adicionales para ayudar a los usuarios con la transición a una nueva versión principal. Estos símbolos de API están en desuso y no son compatibles (es decir, no agregaremos ninguna característica, y no corregiremos errores que no sean para corregir vulnerabilidades), pero sí están cubiertos por nuestras garantías de compatibilidad.

  • La API de C.

  • Los siguientes archivos de búfer de protocolo:

Lo que no está cubierto

Algunas partes de TensorFlow pueden cambiar de forma incompatible hacia atrás en cualquier momento. Éstos incluyen:

  • API experimentales : para facilitar el desarrollo, eximimos algunos símbolos API claramente marcados como experimentales de las garantías de compatibilidad. En particular, lo siguiente no está cubierto por ninguna garantía de compatibilidad:

    • cualquier símbolo en el módulo tf.contrib o sus submódulos;

    • cualquier símbolo (módulo, función, argumento, propiedad, clase o constante) cuyo nombre contenga experimental o Experimental ; o

    • cualquier símbolo cuyo nombre completamente calificado incluya un módulo o clase que sea experimental. Esto incluye campos y submensajes de cualquier búfer de protocolo llamado experimental .

  • Otros lenguajes : API de TensorFlow en lenguajes distintos de Python y C, como:

  • Detalles de operaciones compuestas: muchas funciones públicas en Python se expanden a varias operaciones primitivas en el gráfico, y estos detalles serán parte de cualquier gráfico guardado en el disco como GraphDef s. Estos detalles pueden cambiar para lanzamientos menores. En particular, es probable que las pruebas de regresión que verifican la coincidencia exacta entre los gráficos rompan entre las versiones menores, a pesar de que el comportamiento del gráfico no debería modificarse y los puntos de control existentes seguirán funcionando.

  • Detalles numéricos de coma flotante: los valores de coma flotante específicos calculados por operaciones pueden cambiar en cualquier momento. Los usuarios deben confiar únicamente en la precisión aproximada y la estabilidad numérica, no en los bits específicos calculados. Los cambios en las fórmulas numéricas en lanzamientos menores y parches deben dar como resultado una precisión comparable o mejorada, con la advertencia de que en el aprendizaje automático la precisión mejorada de fórmulas específicas puede resultar en una precisión disminuida para el sistema general.

  • Números aleatorios: los números aleatorios específicos calculados pueden cambiar en cualquier momento. Los usuarios deben confiar únicamente en distribuciones aproximadamente correctas y fuerza estadística, no en los bits específicos calculados. Consulte la guía de generación de números aleatorios para más detalles.

  • Versión sesgada en Tensorflow distribuido: no se admite la ejecución de dos versiones diferentes de TensorFlow en un solo clúster. No hay garantías sobre la compatibilidad con versiones anteriores del protocolo de cable.

  • Errores: Nos reservamos el derecho de realizar cambios de comportamiento incompatibles hacia atrás (aunque no API) si la implementación actual está claramente rota, es decir, si contradice la documentación o si un comportamiento intencionado bien conocido y bien definido no se implementa adecuadamente debido a un error. Por ejemplo, si un optimizador afirma implementar un algoritmo de optimización bien conocido pero no coincide con ese algoritmo debido a un error, repararemos el optimizador. Nuestra solución puede romper el código dependiendo del comportamiento incorrecto para la convergencia. Notaremos tales cambios en las notas de la versión.

  • API no utilizada: nos reservamos el derecho de realizar cambios incompatibles hacia atrás en las API para las que no encontramos usos documentados (al realizar una auditoría del uso de TensorFlow a través de la búsqueda de GitHub). Antes de realizar dichos cambios, anunciaremos nuestra intención de realizar el cambio en la lista de correo de publicidad @ , brindando instrucciones sobre cómo abordar cualquier interrupción (si corresponde) y esperaremos dos semanas para que nuestra comunidad tenga la oportunidad de compartir sus comentarios. .

  • Comportamiento de error: podemos reemplazar los errores con un comportamiento sin error. Por ejemplo, podemos cambiar una función para calcular un resultado en lugar de generar un error, incluso si ese error está documentado. También nos reservamos el derecho de cambiar el texto de los mensajes de error. Además, el tipo de error puede cambiar a menos que el tipo de excepción para una condición de error específica se especifique en la documentación.

Compatibilidad de modelos guardados, gráficos y puntos de control

SavedModel es el formato de serialización preferido para usar en los programas TensorFlow. Los modelos guardados contienen dos partes: uno o más gráficos codificados como GraphDefs y un punto de control. Los gráficos describen el flujo de datos de operaciones que se ejecutarán, y los puntos de control contienen los valores de tensor guardados de las variables en un gráfico.

Muchos usuarios de TensorFlow crean modelos guardados y los cargan y ejecutan con una versión posterior de TensorFlow. De conformidad con semver , los modelos guardados escritos con una versión de TensorFlow se pueden cargar y evaluar con una versión posterior de TensorFlow con la misma versión principal.

Hacemos garantías adicionales para los modelos guardados compatibles . Llamamos un modelo guardado que se creó utilizando solo API no obsoletas, no experimentales y de compatibilidad en la versión principal de TensorFlow N un modelo guardado compatible con la versión N Cualquier modelo guardado compatible con TensorFlow versión principal N se puede cargar y ejecutar con TensorFlow versión principal N+1 . Sin embargo, la funcionalidad requerida para construir o modificar dicho modelo puede que ya no esté disponible, por lo que esta garantía solo se aplica al modelo guardado no modificado.

Nos esforzaremos por preservar la compatibilidad con versiones anteriores el mayor tiempo posible, de modo que los archivos serializados sean utilizables durante largos períodos de tiempo.

Compatibilidad con GraphDef

Los gráficos se serializan a través del GraphDef protocolo GraphDef . Para facilitar cambios incompatibles hacia atrás en los gráficos, cada GraphDef tiene un número de versión separado de la versión TensorFlow. Por ejemplo, GraphDef versión obsoleta del 17 inv op a favor de la reciprocal . Las semánticas son:

  • Cada versión de TensorFlow admite un intervalo de versiones GraphDef . Este intervalo será constante en las versiones de parches y solo crecerá en las versiones menores. La eliminación del soporte para una versión GraphDef solo se producirá para una versión principal de TensorFlow (y solo se alineará con el soporte de la versión garantizado para SavedModels).

  • A los gráficos recién creados se les asigna el último número de versión de GraphDef .

  • Si una versión dada de TensorFlow es compatible con la versión GraphDef de un gráfico, se cargará y evaluará con el mismo comportamiento que la versión TensorFlow utilizada para generarlo (excepto los detalles numéricos de coma flotante y los números aleatorios como se describe anteriormente), independientemente del principal versión de TensorFlow. En particular, un GraphDef que es compatible con un archivo de punto de control en una versión de TensorFlow (como es el caso de un modelo guardado) seguirá siendo compatible con ese punto de control en versiones posteriores, siempre que el GraphDef sea compatible.

    Tenga en cuenta que esto solo se aplica a los gráficos serializados en GraphDefs (y SavedModels): el código que lee un punto de control puede no ser capaz de leer los puntos de control generados por el mismo código que ejecuta una versión diferente de TensorFlow.

  • Si el GraphDef superior de GraphDef se aumenta a X en una versión (menor), habrá al menos seis meses antes de que el límite inferior se incremente a X. Por ejemplo (aquí estamos usando números de versión hipotéticos):

    • TensorFlow 1.2 podría ser compatible con GraphDef versiones 4 a 7.
    • TensorFlow 1.3 podría agregar GraphDef versión 8 y admitir las versiones 4 a 8.
    • Al menos seis meses después, TensorFlow 2.0.0 podría dejar de admitir las versiones 4 a 7, dejando solo la versión 8.

    Tenga en cuenta que debido a que las versiones principales de TensorFlow generalmente se publican con más de 6 meses de diferencia, las garantías para los modelos guardados compatibles que se detallan anteriormente son mucho más fuertes que la garantía de 6 meses para GraphDefs.

Finalmente, cuando se GraphDef soporte para una versión GraphDef , intentaremos proporcionar herramientas para convertir automáticamente los gráficos a una versión GraphDef compatible más GraphDef .

Compatibilidad de gráficos y puntos de control al extender TensorFlow

Esta sección es relevante solo cuando se realizan cambios incompatibles en el formato GraphDef , como al agregar operaciones, eliminar operaciones o cambiar la funcionalidad de operaciones existentes. La sección anterior debería ser suficiente para la mayoría de los usuarios.

Compatibilidad hacia atrás y hacia adelante parcial

Nuestro esquema de versiones tiene tres requisitos:

  • Compatibilidad con versiones anteriores para admitir la carga de gráficos y puntos de control creados con versiones anteriores de TensorFlow.
  • Compatibilidad directa para soportar escenarios en los que el productor de un gráfico o punto de control se actualiza a una versión más nueva de TensorFlow antes que el consumidor.
  • Habilite TensorFlow en evolución de formas incompatibles. Por ejemplo, eliminar operaciones, agregar atributos y eliminar atributos.

Tenga en cuenta que si bien el mecanismo de la versión GraphDef es independiente de la versión TensorFlow, los cambios incompatibles hacia atrás en el formato GraphDef todavía están restringidos por el control de versiones semántico. Esto significa que la funcionalidad solo se puede eliminar o cambiar entre versiones MAJOR de TensorFlow (como 1.7 a 2.0 ). Además, la compatibilidad hacia adelante se aplica en las versiones de parche ( 1.x.1 a 1.x.2 por ejemplo).

Para lograr la compatibilidad con versiones anteriores y posteriores y saber cuándo aplicar los cambios en los formatos, los gráficos y los puntos de control tienen metadatos que describen cuándo se produjeron. Las secciones a continuación detallan la implementación de TensorFlow y las pautas para la evolución de GraphDef versiones de GraphDef .

Esquemas de versiones de datos independientes

Existen diferentes versiones de datos para gráficos y puntos de control. Los dos formatos de datos evolucionan a diferentes velocidades entre sí y también a diferentes velocidades de TensorFlow. Ambos sistemas de versiones están definidos en core/public/version.h . Cada vez que se agrega una nueva versión, se agrega una nota al encabezado que detalla qué cambió y la fecha.

Datos, productores y consumidores.

Distinguimos entre los siguientes tipos de información de versión de datos:

  • productores : binarios que producen datos. Los productores tienen una versión ( producer ) y una versión mínima para el consumidor con la que son compatibles ( min_consumer ).
  • consumidores : binarios que consumen datos. Los consumidores tienen una versión ( consumer ) y una versión de productor mínimo con la que son compatibles ( min_producer ).

Cada pieza de datos versionados tiene un campo de VersionDef versions que registra el producer que hizo los datos, el min_consumer que es compatible y una lista de versiones de bad_consumers que no están permitidas.

Por defecto, cuando un productor min_consumer algunos datos, los datos heredan las versiones producer y min_consumer del producer . bad_consumers se puede establecer si se sabe que las versiones específicas del consumidor contienen errores y deben evitarse. Un consumidor puede aceptar un dato si se cumple lo siguiente:

  • consumer > = min_consumer de datos
  • producer de datos> = min_producer del consumidor
  • consumer no está en los bad_consumers consumer de datos

Dado que tanto los productores como los consumidores provienen de la misma base de código de TensorFlow, core/public/version.h contiene una versión de datos principales que se trata como producer o consumer según el contexto y min_consumer y min_producer (necesarios para productores y consumidores, respectivamente) . Específicamente,

  • Para GraphDef versiones de GraphDef , tenemos TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER y TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Para las versiones de puntos de control, tenemos TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMER y TF_CHECKPOINT_VERSION_MIN_PRODUCER .

Agregue un nuevo atributo por defecto a una operación existente

Seguir la guía a continuación le brinda compatibilidad hacia adelante solo si el conjunto de operaciones no ha cambiado:

  1. Si se desea la compatibilidad hacia adelante, establecer strip_default_attrs a True al exportar el modelo usando las tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables y tf.saved_model.SavedModelBuilder.add_meta_graph métodos de la SavedModelBuilder clase, o tf.estimator.Estimator.export_saved_model
  2. Esto elimina los atributos valorados por defecto al momento de producir / exportar los modelos. Esto asegura que el tf.MetaGraphDef exportado no contenga el nuevo atributo op cuando se usa el valor predeterminado.
  3. Tener este control podría permitir que los consumidores desactualizados (por ejemplo, sirviendo binarios que se quedan atrás de los binarios de entrenamiento) continúen cargando los modelos y eviten interrupciones en el servicio de modelos.

Evolución de las versiones de GraphDef

Esta sección explica cómo usar este mecanismo de control de versiones para realizar diferentes tipos de cambios en el formato GraphDef .

Agregar una operación

Agregue la nueva operación a consumidores y productores al mismo tiempo, y no cambie ninguna versión de GraphDef . Este tipo de cambio es automáticamente compatible con versiones anteriores y no afecta el plan de compatibilidad con versiones posteriores, ya que los scripts de productores existentes no utilizarán repentinamente la nueva funcionalidad.

Agregue una operación y cambie los envoltorios de Python existentes para usarlo

  1. Implemente nuevas funcionalidades para el consumidor e incremente la versión GraphDef .
  2. Si es posible hacer que los contenedores utilicen la nueva funcionalidad solo en casos que no funcionaban antes, los contenedores pueden actualizarse ahora.
  3. Cambie los envoltorios de Python para usar la nueva funcionalidad. No incremente min_consumer , ya que los modelos que no usan esta min_consumer no deberían romperse.

Eliminar o restringir la funcionalidad de un operador

  1. Arregle todos los scripts de productor (no el propio TensorFlow) para que no utilicen la operación o funcionalidad prohibida.
  2. Incremente la versión GraphDef e implemente una nueva funcionalidad para el consumidor que GraphDef la GraphDef o funcionalidad eliminada para GraphDefs en la nueva versión y superior. Si es posible, haga que TensorFlow deje de producir GraphDefs con la funcionalidad prohibida. Para hacerlo, agregue el REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Espere una versión importante para fines de compatibilidad con versiones anteriores.
  4. Aumente min_producer a la versión GraphDef de (2) y elimine la funcionalidad por completo.

Cambiar la funcionalidad de una operación

  1. Agregue una nueva operación similar llamada SomethingV2 o similar y realice el proceso de agregarla y cambiar los envoltorios de Python existentes para usarla. Para garantizar la compatibilidad hacia adelante, utilice las comprobaciones sugeridas en compat.py al cambiar los envoltorios de Python.
  2. Elimine la operación anterior (solo puede tener lugar con un cambio de versión importante debido a la compatibilidad con versiones anteriores).
  3. Aumente min_consumer para descartar consumidores con la min_consumer anterior, agregue la min_consumer anterior como un alias para SomethingV2 y realice el proceso para cambiar los envoltorios de Python existentes para usarlo.
  4. Siga el proceso para eliminar SomethingV2 .

Prohibir una única versión de consumidor insegura

  1. GraphDef versión GraphDef y agregue la versión incorrecta a bad_consumers para todos los nuevos GraphDefs. Si es posible, agregue a bad_consumers solo para GraphDefs que contienen un cierto op o similar.
  2. Si los consumidores existentes tienen la versión incorrecta, retírelos lo antes posible.