Pomoc chronić Wielkiej Rafy Koralowej z TensorFlow na Kaggle Dołącz Wyzwanie

Zgodność wersji TensorFlow

Ten dokument jest przeznaczony dla użytkowników, którzy potrzebują wstecznej kompatybilności w różnych wersjach TensorFlow (dla kodu lub danych) oraz dla programistów, którzy chcą zmodyfikować TensorFlow przy jednoczesnym zachowaniu kompatybilności.

Wersjonowanie semantyczne 2.0

TensorFlow następująco Semantic Versioning 2.0 ( semver ) dla swojego API publicznym. Każda wersja systemu TensorFlow ma postać MAJOR.MINOR.PATCH . Na przykład, TensorFlow wersja 1.2.3 ma MAJOR wersji 1, MINOR wersję 2 oraz PATCH wersji 3. Zmiany do każdego numeru mają następujące znaczenie:

  • Kierunek: Potencjalnie tyłu niekompatybilne zmiany. Kod i dane, które działały z poprzednią wersją główną, niekoniecznie będą działać z nową wersją. Jednak w niektórych przypadkach istniejące wykresy i punkty kontrolne TensorFlow mogą być migrowane do nowszej wersji; zobacz Kompatybilność z wykresów i punktów kontrolnych Szczegółowe informacje na temat zgodności danych.

  • MINOR: wstecznie kompatybilne funkcje, ulepszenia prędkości itp kod i dane, które pracowały z poprzedniej wersji moll i która zależy tylko od nieeksperymentalnych publicznych API będzie nadal działać bez zmian. Szczegółowe informacje na temat tego, co jest i nie jest API publicznych, zobacz Co jest pokryta .

  • Poprawka: wstecznie kompatybilne poprawek.

Na przykład, uwalnianie 1.0.0 wprowadzono wstecznie niezgodnych zmian od wydania 0.12.1. Jednak uwolnienie 1.1.1 był kompatybilny wstecz z wydaniem 1.0.0.

Co obejmuje

Tylko publiczne interfejsy API TensorFlow są wstecznie kompatybilne w wersjach podrzędnych i poprawek. Publiczne interfejsy API składają się z

  • Wszystkie udokumentowane Python funkcje i klasy w tensorflow modułu i jego submodułów, z wyjątkiem

    • Symbole prywatne: każda funkcja, klasy, itd., Których nazwy zaczynają się _
    • Doświadczalne i tf.contrib symboli, patrz poniżej szczegóły.

    Należy pamiętać, że kod w examples/ i tools/ katalogów nie jest osiągalny poprzez tensorflow moduł Pythona, a zatem nie są objęte gwarancją kompatybilności.

    Jeżeli symbol jest dostępna za pośrednictwem tensorflow moduł Pythona lub jej submodules, ale nie jest to udokumentowane, to nie jest traktowana jako część publicznych API.

  • API Kompatybilność (w Pythonie The tf.compat moduł). W wersjach głównych możemy wydać narzędzia i dodatkowe punkty końcowe, aby pomóc użytkownikom w przejściu do nowej wersji głównej. Te symbole API są przestarzałe i nieobsługiwane (tzn. nie dodamy żadnych funkcji i nie będziemy naprawiać błędów innych niż usuwanie luk), ale podlegają naszym gwarantom zgodności.

  • API C .

  • Następujące pliki buforów protokołów:

Co nie jest objęte

Niektóre części TensorFlow mogą w dowolnym momencie ulec zmianie w sposób niekompatybilny wstecznie. Obejmują one:

  • API eksperymentalne: W celu ułatwienia rozwoju, możemy zwolnić niektóre symbole API wyraźnie oznaczone jako eksperymentalne z gwarancji zgodności. W szczególności nie są objęte żadnymi gwarancjami zgodności:

    • każdy symbol w tf.contrib modułu lub jego podmodułów;
    • każdy symbol (moduł, funkcja argument właściwość, klasę, lub stałe), której nazwa zawiera experimental lub Experimental ; lub
    • dowolny symbol, którego pełna nazwa zawiera moduł lub klasę, która sama jest eksperymentalna. Obejmuje pola i podkomunikatach dowolnego buforu jest protokół experimental .
  • Inne języki: API TensorFlow w językach innych niż Python i C, takich jak:

  • Szczegóły kompozytowych ops: Wiele funkcji publicznych w Pythonie rozszerzyć do kilku prymitywnych ops na wykresie, a dane te będą częścią żadnej wykresów zapisanych na dysku jako GraphDef s. Te szczegóły mogą ulec zmianie w przypadku drobnych wydań. W szczególności testy regresji, które sprawdzają dokładne dopasowanie wykresów, prawdopodobnie załamią się w mniejszych wydaniach, nawet jeśli zachowanie wykresu powinno pozostać niezmienione, a istniejące punkty kontrolne nadal będą działać.

  • Zmiennoprzecinkowych dane liczbowe: konkretne wartości zmiennoprzecinkowych obliczone przez OPS może się zmienić w każdej chwili. Użytkownicy powinni polegać tylko na przybliżonej dokładności i stabilności numerycznej, a nie na obliczonych konkretnych bitach. Zmiany formuł numerycznych w wersjach drobnych i poprawek powinny skutkować porównywalną lub lepszą dokładnością, z zastrzeżeniem, że w przypadku uczenia maszynowego zwiększona dokładność określonych formuł może skutkować zmniejszoną dokładnością całego systemu.

  • Liczby losowe: Konkretne liczby losowe obliczone może się zmienić w każdej chwili. Użytkownicy powinni polegać tylko na w przybliżeniu poprawnych rozkładach i sile statystycznej, a nie na obliczonych konkretnych bitach. Zobacz generowania liczb losowych Guide.

  • Wersja odchyleniu rozproszonego Tensorflow: uruchamianie dwóch różnych wersji TensorFlow w jednym zestawie nie jest obsługiwana. Nie ma gwarancji co do wstecznej kompatybilności protokołu przewodowego.

  • Błędy: Zastrzegamy sobie prawo do wprowadzania w tył niezgodną zachowanie (choć nie API) zmienia jeśli obecna implementacja jest wyraźnie uszkodzony, to znaczy, jeżeli jest sprzeczna z dokumentacją lub jeśli dobrze znane i dobrze zdefiniowane zamierzone zachowanie nie jest prawidłowo wdrożone ze względu do błędu. Na przykład, jeśli optymalizator twierdzi, że zaimplementował dobrze znany algorytm optymalizacji, ale nie pasuje do tego algorytmu z powodu błędu, naprawimy optymalizator. Nasza poprawka może złamać kod, polegając na niewłaściwym zachowaniu zbieżności. Takie zmiany odnotujemy w informacjach o wydaniu.

  • Niewykorzystane API: Zastrzegamy sobie prawo do wprowadzania zmian niezgodnych wstecz API dla którego nie znajdujemy udokumentowanych zastosowań (wykonując audyt wykorzystania TensorFlow poprzez wyszukiwanie GitHub). Przed dokonaniem takich zmian, podamy nasz zamiar dokonać zmiany na liście ogłosić @ korespondencji , zapewniając instrukcje jak rozwiązać wszelkie pęknięcia (jeśli dotyczy), i czekać na dwa tygodnie, aby dać naszej Wspólnoty okazję do podzielenia się swoją opinię .

  • Zachowanie błąd: Możemy wymienić błędy z zachowaniem bez błędu. Na przykład możemy zmienić funkcję, aby obliczyć wynik zamiast zgłaszać błąd, nawet jeśli ten błąd jest udokumentowany. Zastrzegamy sobie również prawo do zmiany treści komunikatów o błędach. Ponadto typ błędu może ulec zmianie, chyba że w dokumentacji określono typ wyjątku dla określonego warunku błędu.

Kompatybilność SavedModels, wykresów i punktów kontrolnych

SavedModel jest preferowanym formatem serializacji używanym w programach TensorFlow. SavedModels zawierają dwie części: jednego lub więcej zakodowanych jako wykresy GraphDefs i punkt kontrolny. Wykresy opisują przepływ danych operacji do uruchomienia, a punkty kontrolne zawierają zapisane wartości tensorów zmiennych na wykresie.

Wielu użytkowników TensorFlow tworzy SavedModels, ładuje je i uruchamia w późniejszej wersji TensorFlow. Zgodnie z semver , SavedModels napisane z jednej wersji TensorFlow mogą być ładowane i oceniane z nowszej wersji TensorFlow z tej samej wersji głównej.

Wykonujemy dodatkowych gwarancji dla obsługiwanych SavedModels. Nazywamy SavedModel który został stworzony przy użyciu tylko non-przestarzałe, non-eksperymentalny Apis nie kompatybilnością w TensorFlow główną wersję N SavedModel obsługiwane w wersji N . Każdy SavedModel obsługiwane TensorFlow wersję główną N może być załadowany i wykonywany z TensorFlow wersji głównej N+1 . Jednak funkcjonalność wymagana do zbudowania lub zmodyfikowania takiego modelu może nie być już dostępna, więc ta gwarancja dotyczy tylko niezmodyfikowanego SavedModel.

Dołożymy wszelkich starań, aby zachować kompatybilność wsteczną tak długo, jak to możliwe, aby zserializowane pliki były użyteczne przez długi czas.

Zgodność z GraphDef

Wykresy są szeregowane przez GraphDef buforze protokołu. Aby ułatwić wstecznie niezgodnych zmian w wykresach, każdy GraphDef ma osobny numer wersji z wersji TensorFlow. Na przykład, GraphDef wersja 17 przestarzałe z inv op na korzyść reciprocal . Semantyka to:

  • Każda wersja TensorFlow obsługuje interwał GraphDef wersjach. Odstęp ten będzie stały we wszystkich wydaniach łat i będzie wzrastał tylko w przypadku mniejszych wydań. Spada poparcie dla GraphDef wersji nastąpi tylko dla dużego uwolnienia TensorFlow (i tylko jednej linii ze wsparciem dla wersji gwarantowanej SavedModels).

  • Nowo utworzone wykresy są przypisane najnowszą GraphDef numer wersji.

  • Jeśli dana wersja TensorFlow wspiera GraphDef wersję wykresu, będzie ładować i ocenić z samego zachowania jak wersja TensorFlow wykorzystanych do jego wygenerowania (z wyjątkiem zmiennoprzecinkowych numeryczna szczegóły i liczb losowych, jak opisano powyżej), bez względu na główną wersja TensorFlow. W szczególności GraphDef, który jest kompatybilny z plikiem punktu kontrolnego w jednej wersji TensorFlow (tak jak w przypadku SavedModel) pozostanie kompatybilny z tym punktem kontrolnym w kolejnych wersjach, o ile GraphDef jest obsługiwany.

    Należy pamiętać, że dotyczy to tylko odcinkach wykresów w GraphDefs (i SavedModels): kod, który czyta checkpoint może nie być w stanie odczytać punkty kontrolne wygenerowane przez tego samego kodu działa inną wersję TensorFlow.

  • Jeśli GraphDef górna granica zostaje zwiększona do X w (niewielkie) zwolnienia, nie będzie co najmniej sześć miesięcy przed dolna granica zostaje zwiększona do X. Na przykład (używamy hipotetyczne numery wersji tutaj):

    • TensorFlow 1.2 może obsługiwać GraphDef wersje od 4 do 7.
    • TensorFlow 1.3 można dodać GraphDef wersja 8 i obsługują wersji 4 do 8.
    • Co najmniej sześć miesięcy później TensorFlow 2.0.0 mógł porzucić wsparcie dla wersji 4 do 7, pozostawiając tylko wersję 8.

    Zwróć uwagę, że ponieważ główne wersje TensorFlow są zwykle publikowane w odstępie dłuższym niż 6 miesięcy, gwarancje dla obsługiwanych modeli SavedModels wyszczególnionych powyżej są znacznie silniejsze niż 6-miesięczna gwarancja dla GraphDefs.

Wreszcie, gdy poparcie dla GraphDef upuszczeniu wersji, będziemy starali się zapewnić narzędzia do automatycznej konwersji wykresy do nowszej obsługiwanej GraphDef wersji.

Zgodność wykresów i punktów kontrolnych podczas rozszerzania TensorFlow

Ta sekcja ma zastosowanie jedynie przy dokonywaniu niezgodnych zmian w GraphDef formatu, takie jak podczas dodawania ops, usuwając ops lub zmianę funkcjonalności istniejących ops. Poprzednia sekcja powinna wystarczyć dla większości użytkowników.

Kompatybilność wsteczna i częściowa w przód

Nasz schemat wersjonowania ma trzy wymagania:

  • Kompatybilność wsteczna do wsparcia wykresach załadowczych i kontrolnych stworzony ze starszymi wersjami TensorFlow.
  • Forward zgodność scenariuszy wsparcia gdzie producent wykresu lub kontrolnego zostanie uaktualniony do nowszej wersji TensorFlow przed konsumentem.
  • Włącz ewolucję TensorFlow w niekompatybilny sposób. Na przykład usuwanie operacji, dodawanie atrybutów i usuwanie atrybutów.

Należy zauważyć, że podczas gdy GraphDef mechanizm wersja jest niezależny od wersji TensorFlow, niekompatybilne wstecz zmiany w GraphDef formacie są nadal ograniczone przez Semantic Versioning. Funkcjonalność elementy mogą być usuwane lub zmieniane między tylko MAJOR wersji TensorFlow (na przykład 1.7 do 2.0 ). Dodatkowo, kompatybilność w przód jest egzekwowane w ciągu plaster uwalnia ( 1.x.1 do 1.x.2 na przykład).

Aby osiągnąć zgodność wsteczną i do przodu oraz wiedzieć, kiedy wymusić zmiany w formatach, wykresy i punkty kontrolne mają metadane opisujące, kiedy zostały utworzone. Poniższe sekcje szczegółowo realizacja TensorFlow i wytyczne dotyczące ewoluuje GraphDef wersjach.

Niezależne schematy wersji danych

Istnieją różne wersje danych dla wykresów i punktów kontrolnych. Te dwa formaty danych ewoluują w różnym tempie od siebie, a także w różnym tempie od TensorFlow. Oba systemy wersjonowania są zdefiniowane w core/public/version.h . Za każdym razem, gdy dodawana jest nowa wersja, do nagłówka dodawana jest notatka z wyszczególnieniem zmian i daty.

Dane, producenci i konsumenci

Rozróżniamy następujące rodzaje informacji o wersji danych:

  • producenci: binarne, które produkują danych. Producenci mają wersję ( producer ) i minimalną wersję konsumentów, że są one zgodne z ( min_consumer ).
  • Konsumenci: binarne, które zużywają danych. Konsumenci mają wersję ( consumer ) oraz w wersji minimum producentów, które są zgodne z ( min_producer ).

Każdy kawałek wersjonowanymi danych ma VersionDef versions pole, które rejestruje producer , który wykonany danych, min_consumer że jest ona zgodna z oraz listę bad_consumers wersje, które są niedozwolone.

Domyślnie, gdy producent sprawia, że niektóre dane, dane dziedziczy producenta producer i min_consumer wersje. bad_consumers można ustawić, czy konkretne wersje konsumenckie są znane i zawierają błędów należy unikać. Konsument może zaakceptować fragment danych, jeśli spełnione są wszystkie poniższe warunki:

  • consumer > = Danych min_consumer
  • Dane za producer > = konsumenta min_producer
  • consumer nie jest w Danych bad_consumers

Ponieważ zarówno producenci jak i konsumenci pochodzą z tego samego kodu bazowego TensorFlow, core/public/version.h zawiera główną wersję danych, który jest traktowany jako albo producer lub consumer w zależności od kontekstu i oba min_consumer i min_producer (wymagane przez producentów i konsumentów, odpowiednio) . Konkretnie,

  • Dla GraphDef wersjach, mamy TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER i TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Dla wersji punktów kontrolnych, mamy TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMER i TF_CHECKPOINT_VERSION_MIN_PRODUCER .

Dodaj nowy atrybut z wartością domyślną do istniejącej operacji

Postępowanie zgodnie z poniższymi wskazówkami zapewnia kompatybilność w przód tylko wtedy, gdy zestaw operacji nie uległ zmianie:

  1. Jeśli pożądany jest kompatybilność w przód, ustaw strip_default_attrs do True podczas eksportowania modelu używając albo tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables i tf.saved_model.SavedModelBuilder.add_meta_graph metod SavedModelBuilder klasy lub tf.estimator.Estimator.export_saved_model
  2. Powoduje to usunięcie domyślnych wartości atrybutów w czasie tworzenia/eksportowania modeli. Daje to pewność, że eksportowane tf.MetaGraphDef nie zawiera nową op-atrybut gdy używana jest wartość domyślna.
  3. Posiadanie tej kontrolki może umożliwić nieaktualnym konsumentom (na przykład obsługującym pliki binarne, które pozostają w tyle za treningowymi plikami binarnymi) na dalsze ładowanie modeli i zapobieganie przerwom w udostępnianiu modelu.

Ewoluujące wersje GraphDef

W tym rozdziale opisano sposób korzystania z tego mechanizmu o wersjach do różnych rodzajów zmian GraphDef formacie.

Dodaj op

Dodaj nowy op zarówno konsumentów, jak i producentów w tym samym czasie, a nie zmieniać żadnych GraphDef wersje. Ten typ zmiany jest automatycznie zgodny z poprzednimi wersjami i nie wpływa na plan zgodności w przód, ponieważ istniejące skrypty producenta nie będą nagle korzystać z nowej funkcji.

Dodaj op i zmień istniejące wrappery Pythona, aby z niego korzystać

  1. Wdrożenie nowej funkcjonalności konsumentów i zwiększamy GraphDef wersję.
  2. Jeśli jest możliwe, aby wrappery korzystały z nowej funkcjonalności tylko w przypadkach, które wcześniej nie działały, wrappery można zaktualizować teraz.
  3. Zmień wrappery Pythona, aby korzystać z nowej funkcjonalności. Nie zwiększają min_consumer , od modeli, które nie korzystają z tego op nie należy łamać.

Usuń lub ogranicz funkcjonalność operacji

  1. Napraw wszystkie skrypty producenta (nie sam TensorFlow), aby nie używać zbanowanych operacji lub funkcji.
  2. Zwiększamy GraphDef wersję i wdrożenie nowej funkcjonalności konsumentów, że zakazy usuniętą op lub funkcjonalności dla GraphDefs w nowej wersji i powyżej. Jeśli to możliwe, należy TensorFlow zaprzestać produkcji GraphDefs z zakazanego funkcjonalności. Aby to zrobić, należy dodać REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Poczekaj na wydanie główne, aby uzyskać zgodność z poprzednimi wersjami.
  4. Zwiększ min_producer wersji GraphDef z (2) i zdjąć funkcjonalność całości.

Zmień funkcjonalność operacji

  1. Dodaj nową podobną op nazwie SomethingV2 lub podobny i przejść przez proces dodawania go i przełączania istniejące obwolut Python go używać. Aby zapewnić kompatybilność w przód użyć kontrole sugerowane w compat.py przy zmianie obwolut Python.
  2. Usuń starą operację (może mieć miejsce tylko przy dużej zmianie wersji ze względu na kompatybilność wsteczną).
  3. Zwiększ min_consumer wykluczyć konsumentom starego op, dodać z powrotem starą op jako alias dla SomethingV2 i przejść przez proces, aby przełączyć istniejące obwolut Python go używać.
  4. Przejść przez proces, aby usunąć SomethingV2 .

Zakaz jednej niebezpiecznej wersji konsumenckiej

  1. Odkopanie GraphDef wersji i dodać złą wersję do bad_consumers dla wszystkich nowych GraphDefs. Jeśli to możliwe, należy dodać do bad_consumers tylko dla GraphDefs które zawierają pewną op lub podobny.
  2. Jeśli dotychczasowi konsumenci mają złą wersję, wypchnij ich tak szybko, jak to możliwe.