此页面由 Cloud Translation API 翻译。
Switch to English

Zgodność wersji TensorFlow

Ten dokument jest przeznaczony dla użytkowników, którzy potrzebują wstecznej kompatybilności z różnymi wersjami TensorFlow (dla kodu lub danych), oraz dla programistów, którzy chcą modyfikować TensorFlow, zachowując zgodność.

Wersja semantyczna 2.0

TensorFlow jest zgodny z Semantic Versioning 2.0 ( semver ) dla publicznego interfejsu API. Każda wydana wersja TensorFlow ma postać MAJOR.MINOR.PATCH . Na przykład TensorFlow w wersji 1.2.3 ma MAJOR wersji 1, MINOR wersji 2 i PATCH wersji 3. Zmiany każdego numeru mają następujące znaczenie:

  • GŁÓWNY : Potencjalnie wstecznie niezgodne zmiany. Kod i dane, które działały w poprzedniej wersji głównej, 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 Zgodność wykresów i punktów kontrolnych, aby uzyskać szczegółowe informacje na temat zgodności danych.

  • MNIEJSZE : Funkcje kompatybilne wstecz, ulepszenia szybkości itp. Kod i dane, które działały z poprzednią pomniejszą wersją i które zależą tylko od nieeksperymentalnego publicznego interfejsu API, będą nadal działać bez zmian. Szczegółowe informacje na temat tego, co jest i nie jest API publicznych, zobacz Co jest pokryta .

  • PATCH : kompatybilne wstecz poprawki błędów.

Na przykład w wersji 1.0.0 wprowadzono wstecznie niezgodne zmiany z wersji 0.12.1. Jednak wersja 1.1.1 była wstecznie kompatybilna z wersją 1.0.0.

Co obejmuje ubezpieczenie

Tylko publiczne interfejsy API TensorFlow są wstecznie kompatybilne z wersjami pomocniczymi i poprawkami. Publiczne interfejsy API składają się z

  • Wszystkie udokumentowane funkcje i klasy Pythona w module tensorflow i jego modułach tensorflow , z wyjątkiem

    • Symbole prywatne: dowolna funkcja, klasa itp., Których nazwa zaczyna się od _
    • Symbole eksperymentalne i tf.contrib , patrz szczegóły poniżej .

    Zwróć uwagę, że kod w katalogach examples/ i tools/ nie jest osiągalny przez moduł tensorflow Python i dlatego nie jest objęty gwarancją zgodnoś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.

  • Zgodność API (w Pythonie, moduł tf.compat ). W głównych wersjach możemy udostępniać narzędzia i dodatkowe punkty końcowe, aby pomóc użytkownikom w przejściu na nową wersję główną. Te symbole API są przestarzałe i nie są obsługiwane (tj. Nie będziemy dodawać żadnych funkcji i nie naprawiamy błędów innych niż naprawianie luk), ale podlegają one naszym gwarancjom zgodności.

  • C API .

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

Co nie jest objęte gwarancją

Niektóre części TensorFlow mogą w dowolnym momencie zmienić się w sposób niezgodny wstecz. Obejmują one:

  • Eksperymentalne interfejsy API : aby ułatwić programowanie, wyłączamy niektóre symbole API wyraźnie oznaczone jako eksperymentalne z gwarancji zgodności. W szczególności następujące gwarancje zgodności nie są objęte:

    • dowolny symbol w module tf.contrib lub jego podmodułach;
    • dowolny symbol (moduł, funkcja, argument, właściwość, klasa lub stała), którego nazwa zawiera experimental lub Experimental ; lub

    • dowolny symbol, którego w pełni kwalifikowana nazwa zawiera moduł lub klasę, która sama w sobie jest eksperymentalna. Obejmuje to pola i podkomunikaty dowolnego bufora protokołu zwanego experimental .

  • Inne języki : API TensorFlow w językach innych niż Python i C, takie jak:

  • Szczegóły złożonych operacji: Wiele funkcji publicznych w Pythonie rozwija się do kilku prymitywnych operacji na wykresie, a te szczegóły będą częścią dowolnych wykresów zapisanych na dysku jako GraphDef s. Te szczegóły mogą ulec zmianie w przypadku mniejszych wersji. W szczególności testy regresji, które sprawdzają dokładne dopasowanie między wykresami, prawdopodobnie zepsują się w mniejszych wersjach, nawet jeśli zachowanie wykresu powinno pozostać niezmienione, a istniejące punkty kontrolne będą nadal działać.

  • Szczegóły liczbowe zmiennoprzecinkowe: Określone wartości zmiennoprzecinkowe obliczane przez ops mogą ulec zmianie w dowolnym momencie. Użytkownicy powinni polegać tylko na przybliżonej dokładności i stabilności numerycznej, a nie na konkretnych obliczonych bitach. Zmiany w formułach liczbowych w wydaniach mniejszych i poprawkach powinny skutkować porównywalną lub poprawioną dokładnością, z zastrzeżeniem, że w uczeniu maszynowym zwiększona dokładność określonych formuł może skutkować zmniejszoną dokładnością całego systemu.

  • Liczby losowe: określone obliczone liczby losowe mogą ulec zmianie w dowolnym momencie. Użytkownicy powinni polegać tylko na w przybliżeniu poprawnych rozkładach i sile statystycznej, a nie na konkretnych obliczonych bitach. Szczegółowe informacje można znaleźć w przewodniku po generowaniu liczb losowych .

  • Pochylenie wersji w rozproszonym Tensorflow: uruchamianie dwóch różnych wersji TensorFlow w jednym klastrze nie jest obsługiwane. Nie ma gwarancji zgodności wstecznej protokołu przewodowego.

  • Błędy: Zastrzegamy sobie prawo do wprowadzania wstecznie niekompatybilnych zmian zachowania (choć nie API), jeśli obecna implementacja jest wyraźnie zepsuta, to znaczy, jeśli jest sprzeczna z dokumentacją lub jeśli dobrze znane i dobrze zdefiniowane zamierzone zachowanie nie jest prawidłowo wdrożone z powodu na błąd. Na przykład, jeśli optymalizator twierdzi, że implementuje dobrze znany algorytm optymalizacji, ale nie pasuje do tego algorytmu z powodu błędu, naprawimy optymalizator. Nasza poprawka może złamać kod, opierając się na niewłaściwym zachowaniu dla konwergencji. Takie zmiany odnotujemy w informacjach o wydaniu.

  • Nieużywane API: Zastrzegamy sobie prawo do wprowadzania wstecznie niezgodnych zmian w API, dla których nie znajdujemy udokumentowanych zastosowań (poprzez przeprowadzenie audytu użycia TensorFlow za pomocą wyszukiwania GitHub). Przed wprowadzeniem jakichkolwiek takich zmian ogłosimy nasz zamiar wprowadzenia zmiany na liście mailingowej announce @ , podając instrukcje dotyczące rozwiązywania problemów (jeśli dotyczy) i poczekamy dwa tygodnie, aby dać naszej społeczności szansę podzielenia się swoją opinią .

  • Zachowanie błędów: możemy zastąpić błędy zachowaniem bez błędów. Na przykład możemy zmienić funkcję, aby obliczała 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 konkretnego warunku błędu.

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

SavedModel to preferowany format serializacji używany w programach TensorFlow. SavedModels zawiera dwie części: jeden lub więcej wykresów zakodowanych jako GraphDefs i Checkpoint. 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 oraz ładuje je i wykonuje w późniejszej wersji TensorFlow. Zgodnie z semver , SavedModels napisane w jednej wersji TensorFlow mogą być ładowane i oceniane w późniejszej wersji TensorFlow z tą samą główną wersją.

Dajemy dodatkowe gwarancje dla obsługiwanych SavedModels. Nazywamy SavedModel, który został utworzony przy użyciu tylko nieaktualnych, nieeksperymentalnych i niezgodnych interfejsów API w głównej wersji N TensorFlow, a SavedModel obsługiwanego w wersji N Każdy SavedModel obsługiwany w wersji głównej N TensorFlow może być ładowany i wykonywany za pomocą wersji głównej TensorFlow N+1 . Jednak funkcjonalność wymagana do zbudowania lub zmodyfikowania takiego modelu może nie być już dostępna, więc niniejsza gwarancja dotyczy tylko niezmodyfikowanego SavedModel.

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

Zgodność z GraphDef

Wykresy są serializowane poprzez bufor protokołu GraphDef . Aby ułatwić wstecznie niezgodne zmiany w wykresach, każdy GraphDef ma numer wersji inny niż wersja TensorFlow. Na przykład GraphDef wersji 17 GraphDef inv op na rzecz reciprocal . Oto semantyka:

  • Każda wersja TensorFlow obsługuje interwał wersji GraphDef . Odstęp ten będzie stały dla wszystkich wydań łatek i będzie się wydłużał tylko w przypadku mniejszych wydań. GraphDef wersji GraphDef będzie miało miejsce tylko w przypadku głównej wersji TensorFlow (i będzie zgodne tylko z obsługą wersji gwarantowanej dla SavedModels).

  • Nowo utworzonym GraphDef przypisywany jest numer najnowszej wersji GraphDef .

  • Jeśli dana wersja TensorFlow obsługuje wersję GraphDef wykresu, załaduje się i oceni z takim samym zachowaniem, jak wersja TensorFlow użyta do jej wygenerowania (z wyjątkiem liczb zmiennoprzecinkowych i liczb losowych, jak opisano powyżej), niezależnie od wersja TensorFlow. W szczególności GraphDef, który jest zgodny z plikiem punktu kontrolnego w jednej wersji TensorFlow (na przykład w SavedModel), pozostanie zgodny z tym punktem kontrolnym w kolejnych wersjach, o ile GraphDef jest obsługiwany.

    Należy zauważyć, że dotyczy to tylko zserializowanych wykresów w GraphDefs (i SavedModels): Kod, który odczytuje punkt kontrolny, może nie być w stanie odczytać punktów kontrolnych wygenerowanych przez ten sam kod, na którym działa inna wersja TensorFlow.

  • Jeśli górna granica GraphDef zostanie zwiększona do X w (podrzędnej) wersji, minie co najmniej sześć miesięcy, zanim dolna granica zostanie zwiększona do X. Na przykład (używamy tutaj hipotetycznych numerów wersji):

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

    Należy zauważyć, że ponieważ główne wersje TensorFlow są zwykle publikowane w odstępie ponad 6 miesięcy, gwarancje dla obsługiwanych modeli SavedModels opisane powyżej są znacznie silniejsze niż 6-miesięczna gwarancja dla GraphDefs.

Wreszcie, gdy wsparcie dla wersji GraphDef zostanie usunięte, spróbujemy zapewnić narzędzia do automatycznej konwersji wykresów do nowszej obsługiwanej wersji GraphDef .

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

Ta sekcja ma znaczenie tylko w przypadku wprowadzania niezgodnych zmian w formacie GraphDef , takich jak dodawanie operacji, usuwanie operacji lub zmienianie funkcjonalności istniejących operacji. Większości użytkowników powinna wystarczyć poprzednia sekcja.

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

Nasz schemat wersjonowania ma trzy wymagania:

  • Kompatybilność wsteczna w celu obsługi ładowania wykresów i punktów kontrolnych utworzonych w starszych wersjach TensorFlow.
  • Zgodność w przód w celu obsługi scenariuszy, w których producent wykresu lub punktu kontrolnego jest uaktualniany do nowszej wersji TensorFlow przed konsumentem.
  • Włącz rozwijające się TensorFlow na niekompatybilne sposoby. Na przykład usuwanie operacji, dodawanie atrybutów i usuwanie atrybutów.

Należy zauważyć, że chociaż mechanizm wersji GraphDef jest niezależny od wersji TensorFlow, wstecznie niezgodne zmiany w formacie GraphDef są nadal ograniczone przez wersjonowanie semantyczne. Funkcjonalność elementy mogą być usuwane lub zmieniane między tylko MAJOR wersji TensorFlow (na przykład 1.7 do 2.0 ). Ponadto zgodność z 1.x.2 wersjami jest wymuszana w wydaniach poprawek (na przykład 1.x.1 do 1.x.2 ).

Aby osiągnąć kompatybilność wsteczną i wsteczną oraz wiedzieć, kiedy wymusić zmiany w formatach, wykresy i punkty kontrolne mają metadane opisujące, kiedy zostały utworzone. Poniższe sekcje szczegółowo opisują implementację TensorFlow i wskazówki dotyczące ewolucji wersji GraphDef .

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 innym tempie niż 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 datą.

Dane, producenci i konsumenci

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

  • producenci : pliki binarne, które generują dane. Producenci mają wersję ( producer ) i minimalną wersję konsumencką, z którą są zgodni ( min_consumer ).
  • konsumenci : pliki binarne, które zużywają dane. Konsumenci mają wersję ( consumer ) i minimalną wersję producenta, z którą są kompatybilni ( min_producer ).

Każdy fragment wersjonowanych danych ma pole VersionDef versions które rejestruje producer który utworzył dane, min_consumer , z którym są one zgodne, oraz listę wersji bad_consumers które są niedozwolone.

Domyślnie, gdy producent tworzy jakieś dane, dane dziedziczą wersję producer i min_consumer . bad_consumers można ustawić, jeśli wiadomo, że określone wersje konsumenckie zawierają błędy i należy ich unikać. Konsument może zaakceptować dane, jeśli wszystkie następujące warunki są prawdziwe:

  • consumer > = min_consumer danych
  • producer danych> = min_producer konsumenta
  • consumer nie w bad_consumers danych

Ponieważ zarówno producenci, jak i konsumenci pochodzą z tej samej bazy kodu TensorFlow, core/public/version.h zawiera główną wersję danych, która jest traktowana jako producer lub consumer zależności od kontekstu oraz zarówno min_consumer jak i min_producer (potrzebne odpowiednio producentom i konsumentom) . Konkretnie,

  • W GraphDef wersji GraphDef mamy TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER i TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • W przypadku wersji z punktami kontrolnymi 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 zgodność 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. Spowoduje to usunięcie atrybutów o wartości domyślnej w momencie tworzenia / eksportowania modeli. Daje to pewność, że wyeksportowany tf.MetaGraphDef nie zawiera nowego atrybutu op, gdy używana jest wartość domyślna.
  3. Posiadanie tej kontroli może pozwolić nieaktualnym konsumentom (na przykład obsługującym pliki binarne, które pozostają w tyle za szkoleniowymi plikami binarnymi) na dalsze ładowanie modeli i zapobieganie przerwom w udostępnianiu modeli.

Ewoluujące wersje GraphDef

W tej sekcji wyjaśniono, jak używać tego mechanizmu wersjonowania do wprowadzania różnych typów zmian w formacie GraphDef .

Dodaj op

Dodaj nową GraphDef zarówno dla konsumentów, jak i producentów w tym samym czasie i nie zmieniaj żadnych wersji GraphDef . Ten typ zmiany jest automatycznie kompatybilny z poprzednimi wersjami i nie wpływa na plan kompatybilności w przód, ponieważ istniejące skrypty producenta nie będą nagle używać nowej funkcjonalności.

Dodaj op i przełącz istniejące otoki języka Python, aby z niego korzystać

  1. Zaimplementuj nowe funkcje konsumenckie i GraphDef wersję GraphDef .
  2. Jeśli możliwe jest, aby opakowania korzystały z nowej funkcjonalności tylko w przypadkach, które wcześniej nie działały, opakowania można zaktualizować teraz.
  3. Zmień opakowania Pythona, aby korzystały z nowej funkcjonalności. Nie zwiększaj wartości min_consumer , ponieważ modele, które nie używają tej min_consumer , nie powinny się zepsuć.

Usuń lub ogranicz funkcjonalność operacji

  1. Napraw wszystkie skrypty producenta (nie sam TensorFlow), aby nie korzystały z zakazanej operacji lub funkcji.
  2. Zwiększ wersję GraphDef i zaimplementuj nową funkcjonalność konsumencką, która blokuje usuniętą operację lub funkcjonalność dla GraphDefs w nowej wersji i nowszych. Jeśli to możliwe, zatrzymaj GraphDefs tworzeniu GraphDefs z zablokowaną funkcjonalnością. Aby to zrobić, dodaj REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Poczekaj na główną wersję w celu zapewnienia zgodności z poprzednimi wersjami.
  4. Zwiększ min_producer do wersji GraphDef z (2) i całkowicie usuń funkcjonalność.

Zmień funkcjonalność operacji

  1. Dodaj nową podobną operację o nazwie SomethingV2 lub podobną i przejdź przez proces dodawania go i przełączania istniejących opakowań Pythona, aby z niego korzystać. Aby zapewnić kompatybilność w przód, podczas zmiany opakowań Pythona użyj sprawdzeń sugerowanych w compliance.py .
  2. Usuń starą operację (może to nastąpić tylko przy dużej zmianie wersji ze względu na kompatybilność wsteczną).
  3. Zwiększ wartość min_consumer aby wykluczyć konsumentów ze starego op, dodaj z powrotem stary op jako alias dla SomethingV2 i przejdź przez proces, aby przełączyć istniejące opakowania Pythona, aby z niego korzystać.
  4. Przejdź przez proces, aby usunąć SomethingV2 .

Zablokuj jedną niebezpieczną wersję konsumencką

  1. GraphDef wersję GraphDef i dodaj złą wersję do bad_consumers dla wszystkich nowych GraphDefs. Jeśli to możliwe, dodaj do bad_consumers tylko dla GraphDefs, które zawierają pewne op lub podobne.
  2. Jeśli obecni konsumenci mają złą wersję, wypchnij ich jak najszybciej.