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

Compatibilidad de la versión de TensorFlow

Este documento está dirigido a 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 sin perder la compatibilidad.

Control de versiones semántico 2.0

TensorFlow sigue semántica de versiones 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. Cambios a cada número tienen el siguiente significado:

MAYOR: Potencialmente cambios hacia atrás incompatibles. El código y los datos que funcionaron con una versión principal anterior no funcionarán necesariamente con la nueva versión. Sin embargo, en algunos casos, los puntos de control y los gráficos de TensorFlow existentes se pueden migrar a la versión más reciente; ver compatibilidad de gráficos y los puestos de control para obtener información sobre la compatibilidad de datos.
MENOR: Al revés funciones compatibles, mejoras en la velocidad, etc. Código y datos que trabajaron con una versión menor anterior y que sólo depende de la API pública no experimental seguirá trabajando sin cambios. Para más detalles sobre lo que es y no es la API pública, ver lo que está cubierto .
PARCHE: correcciones de errores compatibles hacia atrás.

Por ejemplo, la liberación 1.0.0 introdujo cambios hacia atrás incompatibles de liberación 0.12.1. Sin embargo, la liberación 1.1.1 era compatible con la versión 1.0.0.

Que esta cubierto

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

Todos los documentados Python funciones y clases en el tensorflow módulo y sus submódulos, a excepción de
- Símbolos privadas: cualquier función, clase, etc., cuyo nombre comience con _
- Experimental y tf.contrib símbolos, ver a continuación para más detalles.
Tenga en cuenta que el código en los examples/ y tools/ directorios no es accesible a través de la tensorflow módulo de Python 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 tf.compat módulo). 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 obsoletos y no son compatibles (es decir, no agregaremos ninguna función y no corregiremos errores que no sean para corregir vulnerabilidades), pero están cubiertos por nuestras garantías de compatibilidad.
El API C .
Los siguientes archivos de búfer de protocolo:

Lo que no está cubierto

Algunas partes de TensorFlow pueden cambiar de formas incompatibles con versiones anteriores en cualquier momento. Éstos incluyen:

API experimentales: Para facilitar el desarrollo, exceptuamos 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 tf.contrib módulo o los submódulos;
- cualquier símbolo (módulo, la función, el argumento, la propiedad, la clase o constante) cuyo nombre contiene experimental o Experimental ; o
- cualquier símbolo cuyo nombre completo incluya un módulo o clase que sea en sí mismo experimental. Esto incluye campos y submensajes de cualquier tampón protocolo llamado experimental .
Otros idiomas: API TensorFlow en idiomas distintos Python y C, tales como:
- C ++ (expuesto a través de los archivos de cabecera en tensorflow/cc ).
- java ,
- Ir
- JavaScript
Los detalles de operaciones compuestas: Muchas de las funciones públicas en Python se expanden a varias operaciones primitivas en el gráfico, y estos detalles serán parte de los gráficos guardados en el disco como GraphDef s. Estos detalles pueden cambiar para versiones menores. En particular, es probable que las pruebas de regresión que verifican la coincidencia exacta entre gráficos se rompan en versiones menores, aunque el comportamiento del gráfico no debe modificarse y los puntos de control existentes seguirán funcionando.
Punto flotante detalles numéricos: Los valores de punto flotante específicas calculadas por ops puede cambiar en cualquier momento. Los usuarios deben confiar solo 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 versiones menores y de parches deberían dar como resultado una precisión comparable o mejorada, con la salvedad de que en el aprendizaje automático, la precisión mejorada de fórmulas específicas puede resultar en una menor precisión para el sistema en general.
Los números al azar: los números aleatorios específicas calculadas pueden cambiar en cualquier momento. Los usuarios deben confiar solo en distribuciones aproximadamente correctas y fuerza estadística, no en los bits específicos calculados. Vea la generación de números aleatorios guía para más detalles.
Versión asimetría en Tensorflow distribuido: Ejecución de dos versiones diferentes de TensorFlow en un solo grupo no es compatible. No hay garantías sobre la compatibilidad con versiones anteriores del protocolo de cable.
Insectos: Nos reservamos el derecho de hacer que el comportamiento hacia atrás incompatibles (aunque no API) cambia si la implementación actual está claramente roto, es decir, si contradice la documentación o si un bien conocido y comportamiento previsto bien definido no se implementa correctamente debido a un error. Por ejemplo, si un optimizador afirma implementar un algoritmo de optimización conocido pero no coincide con ese algoritmo debido a un error, arreglaremos el optimizador. Nuestra solución puede romper el código basándose en un comportamiento incorrecto para la convergencia. Observaremos estos cambios en las notas de la versión.
API no se usa: Nos reservamos el derecho a realizar cambios hacia atrás incompatibles a las API para las cuales no encontramos usos documentados (mediante la realización de una auditoría del uso TensorFlow través de la búsqueda de GitHub). Antes de realizar cualquiera de estos cambios, vamos a anunciar nuestra intención de hacer el cambio en la lista de correo anunciar @ , que proporciona instrucciones de cómo hacer frente a posibles roturas (en su caso), y esperar dos semanas para dar a nuestra comunidad la oportunidad de compartir sus comentarios .
El comportamiento de error: Podemos reemplazar los errores con el comportamiento de no 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 a cambiar el texto de los mensajes de error. Además, el tipo de error puede cambiar a menos que se especifique en la documentación el tipo de excepción para una condición de error específica.

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

SavedModel es el formato de serialización preferido para usar en los programas de TensorFlow. SavedModels contienen dos partes: una o más gráficos codificados como GraphDefs y un puesto de control. Los gráficos describen el flujo de datos de las 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. En cumplimiento de semver , SavedModels escritos con una versión de TensorFlow se pueden cargar y evaluados con una versión posterior de TensorFlow con la misma versión principal.

Hacemos garantías adicionales para SavedModels compatibles. Llamamos a un SavedModel que fue creada usando sólo no desaprobado no experimental, las API no compatibilidad en TensorFlow versión principal, N un SavedModel apoyado en la versión N . Cualquier SavedModel soportado en TensorFlow versión principal N puede ser cargado y ejecutado con TensorFlow versión principal N+1 . Sin embargo, es posible que la funcionalidad necesaria para crear o modificar dicho modelo ya no esté disponible, por lo que esta garantía solo se aplica al modelo guardado sin modificar.

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

Compatibilidad GraphDef

Los gráficos se serializan a través de la GraphDef búfer de protocolo. Para facilitar los cambios hacia atrás incompatibles a gráficos, cada GraphDef tiene un número de versión separada de la versión TensorFlow. Por ejemplo, GraphDef versión obsoleta del 17 inv op a favor de la reciprocal . La semántica es:

Cada versión de TensorFlow soporta un intervalo de GraphDef versiones. Este intervalo será constante en las versiones de parches y solo aumentará en las versiones menores. Dejar caer soporte para un GraphDef versión sólo ocurrirá para una liberación importante de TensorFlow (y sólo alineada con la ayuda de la versión garantizada para SavedModels).
Gráficos de nueva creación se les asigna la última GraphDef número de versión.
Si una determinada versión de TensorFlow apoya la GraphDef versión de un gráfico, cargará y evaluar con el mismo comportamiento que la versión TensorFlow utilizado para generarla (a excepción de punto flotante numérica detalles y números al azar como se indicó anteriormente), independientemente de la mayor versión de TensorFlow. En particular, un GraphDef que sea compatible con un archivo de punto de control en una versión de TensorFlow (como es el caso en un modelo guardado) seguirá siendo compatible con ese punto de control en versiones posteriores, siempre que se admita GraphDef.
Tenga en cuenta que esto sólo se aplica a los gráficos serializados en GraphDefs (y SavedModels): Código, que se lee en un puesto de control puede no ser capaz de leer los puestos de control generadas por el mismo código que se ejecuta una versión diferente de TensorFlow.
Si el GraphDef límite superior se incrementa a X en un comunicado (menor), habrá por lo menos seis meses antes de que el límite inferior se incrementa a X. Por ejemplo (estamos utilizando números de versión hipotéticos aquí):
- TensorFlow 1.2 podría apoyar GraphDef versiones de 4 a 7.
- TensorFlow 1.3 podría añadir GraphDef Versión 8 y de apoyo a 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 sólidas que la garantía de 6 meses para GraphDefs.

Por último, cuando el apoyo para un GraphDef se deja caer versión, vamos a tratar de proporcionar herramientas para la conversión automática de gráficos a un nuevo apoyado GraphDef versión.

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

Esta sección sólo es relevante cuando se hacen cambios incompatibles a la GraphDef formato, como por ejemplo al añadir operaciones, la eliminación de operaciones, o cambiar la funcionalidad de operaciones existentes. La sección anterior debería ser suficiente para la mayoría de los usuarios.

Compatibilidad con versiones anteriores y posteriores parciales

Nuestro esquema de control de versiones tiene tres requisitos:

Compatibilidad con versiones anteriores a los gráficos de carga de apoyo y puntos de control creado con versiones anteriores de TensorFlow.
Compatibilidad hacia adelante a escenarios de apoyo, donde el productor de un gráfico o de punto de control se actualiza a una versión más reciente de TensorFlow antes de que el consumidor.
Habilite la evolución de TensorFlow de formas incompatibles. Por ejemplo, eliminar operaciones, agregar atributos y eliminar atributos.

Tenga en cuenta que mientras que el GraphDef mecanismo versión es independiente de la versión TensorFlow, cambios hacia atrás incompatibles a la GraphDef formato están siendo restringidas por Semántica de versiones. Esta funcionalidad medios sólo se puede quitar o cambiar entre MAJOR versiones de TensorFlow (tal como 1.7 a 2.0 ). Además, la compatibilidad hacia delante se aplica dentro de comunicados 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 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 TensorFlow y directrices para la evolución de GraphDef versiones.

Esquemas de versión 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 control de versiones se definen en el 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: los binarios que producen datos. Los productores tienen una versión ( producer ) y una versión mínima de consumo que sean compatibles con ( min_consumer ).
consumidores: los binarios que consumen datos. Los consumidores tienen una versión ( consumer ) y una versión mínima productor que sean compatibles con ( min_producer ).

Cada pieza de datos versionados tiene un VersionDef versions campo que registra el producer que hizo que los datos, el min_consumer que es compatible con, y una lista de bad_consumers versiones que se rechazado.

Por defecto, cuando un productor hace algunos datos, los datos hereda del productor producer y min_consumer versiones. bad_consumers se pueden establecer si se conocen versiones específicas de los consumidores a contener errores y deben ser evitados. Un consumidor puede aceptar un dato si todo lo siguiente es cierto:

consumer > = de datos min_consumer
de los datos producer > = consumo de min_producer
consumer no en datos de bad_consumers

Dado que ambos productores y consumidores proceden de la misma base de código TensorFlow, core/public/version.h contiene una versión de datos principal que se trata, ya sea como producer o consumer en función del contexto y ambos min_consumer y min_producer (necesario por los productores y consumidores, respectivamente) . Específicamente,

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

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

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

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
Esto elimina los atributos valorados por defecto en el momento de producir / exportar los modelos. Esto asegura que la exportada tf.MetaGraphDef no contiene el nuevo artículo de atributo cuando se utiliza el valor por defecto.
Tener este control podría permitir que los consumidores desactualizados (por ejemplo, sirviendo binarios que se retrasan con respecto a los binarios de entrenamiento) continúen cargando los modelos y eviten interrupciones en el servicio de modelos.

Evolución de las versiones de GraphDef

En esta sección se explica cómo utilizar este mecanismo de control de versiones para hacer diferentes tipos de cambios en el GraphDef formato.

Agregar una operación

Añadir el nuevo op para los consumidores y productores, al mismo tiempo, y no cambie ningún GraphDef versiones. Este tipo de cambio es automáticamente compatible con versiones anteriores y no afecta el plan de compatibilidad futura, ya que los scripts de productor existentes no usarán repentinamente la nueva funcionalidad.

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

Implementar nuevas funcionalidades del consumidor e incrementar el GraphDef versión.
Si es posible hacer que los contenedores usen la nueva funcionalidad solo en casos que no funcionaban antes, los contenedores se pueden actualizar ahora.
Cambie los envoltorios de Python para usar la nueva funcionalidad. No incrementan min_consumer , ya que los modelos que no utilizan esta operación no debe romper.

Eliminar o restringir la funcionalidad de una operación

Corrija todas las secuencias de comandos del productor (no TensorFlow en sí) para que no utilicen la operación o la funcionalidad prohibidas.
Incrementar el GraphDef versión e implementar nuevas funcionalidades de los consumidores de que las prohibiciones op o funcionalidad eliminado GraphDefs en la nueva versión y por encima. Si es posible, hacer TensorFlow producir parada GraphDefs con la funcionalidad prohibido. Para ello, agregue la REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
Espere una versión importante para fines de compatibilidad con versiones anteriores.
Aumentar min_producer a la versión GraphDef a partir de (2) y retirar la funcionalidad por completo.

Cambiar la funcionalidad de una operación

Añadir un nuevo op similares llamado SomethingV2 o similar y pasar por el proceso de añadir y cambiar las envolturas de Python existentes para utilizarlo. Para asegurar el uso compatibilidad hacia adelante los controles sugeridos en compat.py al cambiar las envolturas de Python.
Elimine la operación anterior (solo se puede realizar con un cambio de versión importante debido a la compatibilidad con versiones anteriores).
Aumentar min_consumer para descartar los consumidores con el viejo op, añadir de nuevo el viejo op como un alias para SomethingV2 , y pasar por el proceso de cambiar las envolturas de Python existentes para utilizarlo.
Ir a través del proceso para eliminar SomethingV2 .

Prohibir una única versión para el consumidor que no sea segura

Volcar el GraphDef versión y añadir la mala versión de bad_consumers para todos los nuevos GraphDefs. Si es posible, añadir a bad_consumers sólo para GraphDefs que contienen una cierta op o similar.
Si los consumidores existentes tienen la versión incorrecta, elimínelos lo antes posible.