Kompatibilitas versi TensorFlow

Dokumen ini ditujukan untuk pengguna yang membutuhkan kompatibilitas mundur di berbagai versi TensorFlow (baik untuk kode atau data), dan untuk developer yang ingin memodifikasi TensorFlow sambil mempertahankan kompatibilitas.

Versi semantik 2.0

TensorFlow berikut Semantic Versi 2.0 ( semver ) untuk API publik. Setiap versi rilis TensorFlow memiliki bentuk MAJOR.MINOR.PATCH . Misalnya, TensorFlow versi 1.2.3 memiliki MAJOR versi 1, MINOR versi 2, dan PATCH versi 3. Perubahan ke setiap nomor memiliki arti sebagai berikut:

  • UTAMA: Berpotensi perubahan mundur kompatibel. Kode dan data yang bekerja dengan rilis besar sebelumnya belum tentu berfungsi dengan rilis baru. Namun, dalam beberapa kasus, grafik dan pos pemeriksaan TensorFlow yang ada mungkin dapat dipindahkan ke rilis yang lebih baru; melihat Kompatibilitas grafik dan pos pemeriksaan untuk rincian tentang kompatibilitas data.

  • MINOR: Backwards fitur yang kompatibel, peningkatan kecepatan, dll Kode dan data yang bekerja dengan rilis minor sebelumnya dan yang hanya bergantung pada non-eksperimental API publik akan terus bekerja tidak berubah. Untuk rincian tentang apa yang bisa dan tidak API publik, lihat Apa yang tertutup .

  • PATCH: perbaikan bug Backwards kompatibel.

Sebagai contoh, rilis 1.0.0 memperkenalkan perubahan mundur kompatibel dari rilis 0.12.1. Namun, rilis 1.1.1 adalah kompatibel dengan rilis 1.0.0.

Apa yang tercakup

Hanya API publik TensorFlow yang kompatibel dengan versi minor dan patch. API publik terdiri dari

  • Semua didokumentasikan Python fungsi dan kelas di tensorflow modul dan submodul yang, kecuali untuk

    • Simbol pribadi: setiap fungsi, kelas, dll, bernama diawali dengan _
    • Eksperimental dan tf.contrib simbol, lihat di bawah ini untuk rincian.

    Perhatikan bahwa kode dalam examples/ dan tools/ direktori tidak dapat dijangkau melalui tensorflow modul Python dan dengan demikian tidak tercakup oleh jaminan kompatibilitas.

    Jika simbol tersedia melalui tensorflow modul Python atau submodul, tetapi tidak didokumentasikan, maka tidak dianggap bagian dari API publik.

  • Kompatibilitas API (Python, yang tf.compat modul). Pada versi utama, kami dapat merilis utilitas dan titik akhir tambahan untuk membantu pengguna dengan transisi ke versi utama yang baru. Simbol API ini tidak digunakan lagi dan tidak didukung (yaitu, kami tidak akan menambahkan fitur apa pun, dan kami tidak akan memperbaiki bug selain untuk memperbaiki kerentanan), tetapi simbol tersebut termasuk dalam jaminan kompatibilitas kami.

  • The C API .

  • File buffer protokol berikut:

Apa yang tidak tercakup

Beberapa bagian TensorFlow dapat berubah dengan cara yang tidak kompatibel di titik mana pun. Ini termasuk:

  • API eksperimental: Untuk memfasilitasi pengembangan, kami membebaskan beberapa simbol API jelas ditandai sebagai eksperimental dari jaminan kompatibilitas. Secara khusus, berikut ini tidak dicakup oleh jaminan kompatibilitas apa pun:

    • simbol di tf.contrib modul atau submodul nya;
    • simbol (modul, fungsi, argumen, properti, kelas, atau konstan) yang namanya mengandung experimental atau Experimental ; atau
    • simbol apa pun yang namanya sepenuhnya memenuhi syarat termasuk modul atau kelas yang itu sendiri eksperimental. Ini termasuk bidang dan submessages dari setiap penyangga protokol yang disebut experimental .
  • Bahasa lainnya: API TensorFlow dalam bahasa lain selain Python dan C, seperti:

  • Rincian ops komposit: Banyak fungsi publik dalam Python memperluas ke beberapa ops primitif dalam grafik, dan rincian ini akan menjadi bagian dari grafik disimpan ke disk sebagai GraphDef s. Detail ini dapat berubah untuk rilis kecil. Secara khusus, uji regresi yang memeriksa kecocokan yang tepat antara grafik cenderung menembus rilis kecil, meskipun perilaku grafik tidak akan berubah dan pos pemeriksaan yang ada akan tetap berfungsi.

  • Floating point rincian numerik: The spesifik nilai-nilai floating point dihitung dengan ops dapat berubah sewaktu-waktu. Pengguna harus mengandalkan hanya pada akurasi perkiraan dan stabilitas numerik, bukan pada bit tertentu yang dihitung. Perubahan pada formula numerik dalam rilis minor dan patch harus menghasilkan akurasi yang sebanding atau ditingkatkan, dengan peringatan bahwa dalam machine learning akurasi yang ditingkatkan dari formula tertentu dapat mengakibatkan penurunan akurasi untuk sistem secara keseluruhan.

  • Angka acak: The nomor acak tertentu dihitung dapat berubah sewaktu-waktu. Pengguna harus hanya mengandalkan distribusi dan kekuatan statistik yang kira-kira benar, bukan bit spesifik yang dihitung. Lihat nomor generasi acak panduan untuk rincian.

  • Versi condong di didistribusikan Tensorflow: Menjalankan dua versi yang berbeda dari TensorFlow dalam satu cluster tidak didukung. Tidak ada jaminan tentang kompatibilitas mundur dari protokol kawat.

  • Bugs: Kami berhak untuk membuat perilaku mundur kompatibel (meskipun tidak API) berubah jika implementasi saat ini jelas rusak, yaitu, jika bertentangan dokumentasi atau jika terkenal dan didefinisikan dengan baik perilaku yang dimaksud tidak benar dilaksanakan karena ke bug. Misalnya, jika pengoptimal mengklaim menerapkan algoritme pengoptimalan yang terkenal tetapi tidak cocok dengan algoritme itu karena bug, maka kami akan memperbaiki pengoptimal. Perbaikan kami dapat merusak kode dengan mengandalkan perilaku yang salah untuk konvergensi. Kami akan mencatat perubahan tersebut dalam catatan rilis.

  • Terpakai API: Kami berhak untuk melakukan perubahan mundur kompatibel untuk API yang kami menemukan tidak ada penggunaan didokumentasikan (dengan melakukan audit penggunaan TensorFlow melalui GitHub pencarian). Sebelum membuat perubahan, kami akan mengumumkan niat kami untuk membuat perubahan pada mengumumkan @ milis , memberikan petunjuk untuk bagaimana untuk mengatasi pecah apapun (jika ada), dan menunggu selama dua minggu untuk memberikan masyarakat kita kesempatan untuk berbagi umpan balik mereka .

  • Perilaku Kesalahan: Kami dapat menggantikan kesalahan dengan perilaku non-error. Misalnya, kami dapat mengubah fungsi untuk menghitung hasil alih-alih meningkatkan kesalahan, bahkan jika kesalahan itu didokumentasikan. Kami juga berhak mengubah teks pesan kesalahan. Selain itu, jenis kesalahan dapat berubah kecuali jenis pengecualian untuk kondisi kesalahan tertentu ditentukan dalam dokumentasi.

Kompatibilitas Model Tersimpan, grafik, dan pos pemeriksaan

SavedModel adalah format serialisasi yang lebih disukai untuk digunakan dalam program TensorFlow. SavedModels mengandung dua bagian: Satu atau lebih grafik dikodekan sebagai GraphDefs dan Checkpoint. Grafik menggambarkan aliran data operasi yang akan dijalankan, dan pos pemeriksaan berisi nilai tensor variabel yang disimpan dalam grafik.

Banyak pengguna TensorFlow membuat SavedModels, serta memuat dan menjalankannya dengan rilis TensorFlow selanjutnya. Sesuai dengan semver , SavedModels ditulis dengan satu versi TensorFlow dapat dimuat dan dievaluasi dengan versi terbaru TensorFlow dengan rilis utama yang sama.

Kami membuat jaminan tambahan untuk SavedModels didukung. Kami sebut SavedModel yang diciptakan hanya menggunakan non-usang, non-eksperimental, API non-kompatibilitas di TensorFlow versi utama N sebuah SavedModel didukung dalam versi N . Setiap SavedModel didukung dalam TensorFlow versi utama N dapat dimuat dan dieksekusi dengan TensorFlow versi utama N+1 . Namun, fungsionalitas yang diperlukan untuk membuat atau memodifikasi model seperti itu mungkin tidak tersedia lagi, jadi jaminan ini hanya berlaku untuk SavedModel yang tidak dimodifikasi.

Kami akan berusaha untuk mempertahankan kompatibilitas mundur selama mungkin, sehingga file serial dapat digunakan dalam jangka waktu yang lama.

Kompatibilitas GraphDef

Grafik serial melalui GraphDef protokol penyangga. Untuk memfasilitasi perubahan belakang yang tidak kompatibel untuk grafik, masing-masing GraphDef memiliki nomor versi terpisah dari versi TensorFlow. Misalnya, GraphDef versi 17 usang yang inv op mendukung reciprocal . semantik tersebut adalah:

  • Setiap versi TensorFlow mendukung selang GraphDef versi. Interval ini akan konstan di seluruh rilis patch, dan hanya akan bertambah di seluruh rilis minor. Menjatuhkan dukungan untuk GraphDef versi hanya akan terjadi untuk rilis utama TensorFlow (dan hanya selaras dengan dukungan versi dijamin untuk SavedModels).

  • Baru dibuat grafik ditugaskan terbaru GraphDef nomor versi.

  • Jika versi tertentu dari TensorFlow mendukung GraphDef versi grafik, akan memuat dan mengevaluasi dengan perilaku yang sama dengan versi TensorFlow digunakan untuk menghasilkan itu (kecuali untuk floating point numerik rincian dan angka acak seperti diuraikan di atas), terlepas dari besar versi TensorFlow. Secara khusus, GraphDef yang kompatibel dengan file pos pemeriksaan dalam satu versi TensorFlow (seperti halnya dalam SavedModel) akan tetap kompatibel dengan pos pemeriksaan tersebut di versi berikutnya, selama GraphDef didukung.

    Perhatikan bahwa ini hanya berlaku untuk Grafik serial di GraphDefs (dan SavedModels): Kode yang berbunyi pos pemeriksaan mungkin tidak dapat membaca pos pemeriksaan yang dihasilkan oleh kode yang sama menjalankan versi yang berbeda dari TensorFlow.

  • Jika GraphDef atas terikat meningkat untuk X dalam (minor) rilis, akan ada setidaknya enam bulan sebelum batas bawah meningkat menjadi X. Sebagai contoh (kami menggunakan nomor versi hipotetis di sini):

    • TensorFlow 1,2 mungkin mendukung GraphDef versi 4 sampai 7.
    • TensorFlow 1.3 bisa menambahkan GraphDef versi 8 dan dukungan versi 4 sampai 8.
    • Setidaknya enam bulan kemudian, TensorFlow 2.0.0 dapat menghentikan dukungan untuk versi 4 hingga 7, hanya menyisakan versi 8.

    Perhatikan bahwa karena versi utama TensorFlow biasanya diterbitkan lebih dari 6 bulan, jaminan untuk SavedModels yang didukung yang dijelaskan di atas jauh lebih kuat daripada jaminan 6 bulan untuk GraphDefs.

Akhirnya, ketika dukungan untuk GraphDef versi dijatuhkan, kami akan berusaha untuk menyediakan alat-alat untuk secara otomatis mengkonversi grafik ke didukung lebih baru GraphDef versi.

Kompatibilitas grafik dan pos pemeriksaan saat memperluas TensorFlow

Bagian ini hanya relevan ketika membuat perubahan yang tidak kompatibel dengan GraphDef Format, seperti ketika menambahkan ops, menghapus ops, atau mengubah fungsi ops yang ada. Bagian sebelumnya sudah cukup untuk sebagian besar pengguna.

Kompatibilitas mundur dan maju sebagian

Skema pembuatan versi kami memiliki tiga persyaratan:

  • Kompatibilitas dukungan memuat grafik dan pos-pos pemeriksaan yang dibuat dengan versi TensorFlow.
  • Kompatibilitas ke depan untuk skenario dukungan mana produsen grafik atau pos pemeriksaan upgrade ke versi yang lebih baru dari TensorFlow sebelum konsumen.
  • Aktifkan TensorFlow yang berkembang dengan cara yang tidak kompatibel. Misalnya, menghapus ops, menambahkan atribut, dan menghapus atribut.

Perhatikan bahwa sementara GraphDef mekanisme versi terpisah dari versi TensorFlow, perubahan mundur kompatibel dengan GraphDef format yang masih dibatasi oleh Semantic Versi. Fungsi alat ini hanya bisa dihapus atau diubah antara MAJOR versi TensorFlow (seperti 1.7 ke 2.0 ). Selain itu, kompatibilitas ke depan diberlakukan dalam patch rilis ( 1.x.1 ke 1.x.2 misalnya).

Untuk mencapai kompatibilitas mundur dan maju dan untuk mengetahui kapan harus menerapkan perubahan dalam format, grafik dan pos pemeriksaan memiliki metadata yang menjelaskan kapan mereka diproduksi. Bagian di bawah rinci pelaksanaan TensorFlow dan pedoman untuk berkembang GraphDef versi.

Skema versi data independen

Ada versi data yang berbeda untuk grafik dan pos pemeriksaan. Kedua format data berkembang dengan kecepatan yang berbeda satu sama lain dan juga pada kecepatan yang berbeda dari TensorFlow. Kedua sistem versioning didefinisikan dalam core/public/version.h . Setiap kali versi baru ditambahkan, catatan ditambahkan ke header yang merinci apa yang berubah dan tanggalnya.

Data, produsen, dan konsumen

Kami membedakan antara jenis informasi versi data berikut:

  • produsen: binari yang menghasilkan data. Produsen memiliki versi ( producer ) dan versi konsumen minimum bahwa mereka yang kompatibel dengan ( min_consumer ).
  • konsumen: binari yang mengkonsumsi data. Konsumen memiliki versi ( consumer ) dan versi produser minimum bahwa mereka yang kompatibel dengan ( min_producer ).

Setiap potongan data berversi memiliki VersionDef versions lapangan yang mencatat producer yang membuat data, min_consumer bahwa itu adalah kompatibel dengan, dan daftar bad_consumers versi yang dianulir.

Secara default, ketika produser membuat beberapa data, data mewarisi produser producer dan min_consumer versi. bad_consumers bisa diatur jika versi konsumen tertentu diketahui mengandung bug dan harus dihindari. Seorang konsumen dapat menerima sepotong data jika semua berikut ini benar:

  • consumer > = Data ini min_consumer
  • Data ini producer > = konsumen min_producer
  • consumer tidak dalam data ini bad_consumers

Karena kedua produsen dan konsumen berasal dari basis kode TensorFlow sama, core/public/version.h berisi versi data yang utama yang diperlakukan sebagai baik producer atau consumer tergantung pada konteks dan kedua min_consumer dan min_producer (yang dibutuhkan oleh produsen dan konsumen, masing-masing) . Secara khusus,

  • Untuk GraphDef versi, kita memiliki TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER , dan TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Untuk versi pos pemeriksaan, kita memiliki TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMER , dan TF_CHECKPOINT_VERSION_MIN_PRODUCER .

Tambahkan atribut baru dengan default ke operasi yang ada

Mengikuti panduan di bawah ini memberi Anda kompatibilitas ke depan hanya jika rangkaian operasi tidak berubah:

  1. Jika kompatibilitas ke depan yang diinginkan, mengatur strip_default_attrs untuk True saat mengekspor model baik menggunakan tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables dan tf.saved_model.SavedModelBuilder.add_meta_graph metode dari SavedModelBuilder kelas, atau tf.estimator.Estimator.export_saved_model
  2. Ini menghapus atribut bernilai default pada saat memproduksi/mengekspor model. Hal ini memastikan bahwa diekspor tf.MetaGraphDef tidak mengandung op-atribut baru ketika nilai default digunakan.
  3. Memiliki kontrol ini dapat memungkinkan konsumen yang kedaluwarsa (misalnya, menyajikan biner yang tertinggal di belakang biner pelatihan) untuk terus memuat model dan mencegah interupsi dalam penyajian model.

Versi GraphDef yang berkembang

Bagian ini menjelaskan cara menggunakan mekanisme versioning ini untuk membuat berbagai jenis perubahan pada GraphDef Format.

Tambahkan op

Tambahkan op baru untuk konsumen dan produsen pada saat yang sama, dan tidak mengubah GraphDef versi. Jenis perubahan ini secara otomatis kompatibel ke belakang, dan tidak memengaruhi rencana kompatibilitas ke depan karena skrip produser yang ada tidak akan tiba-tiba menggunakan fungsionalitas baru.

Tambahkan op dan alihkan pembungkus Python yang ada untuk menggunakannya

  1. Melaksanakan fungsi konsumen baru dan kenaikan GraphDef versi.
  2. Jika memungkinkan untuk membuat pembungkus menggunakan fungsionalitas baru hanya dalam kasus yang tidak berfungsi sebelumnya, pembungkus dapat diperbarui sekarang.
  3. Ubah pembungkus Python untuk menggunakan fungsionalitas baru. Jangan kenaikan min_consumer , karena model yang tidak menggunakan op ini harus tidak melanggar.

Hapus atau batasi fungsionalitas operasi

  1. Perbaiki semua skrip produser (bukan TensorFlow itu sendiri) agar tidak menggunakan operasi atau fungsionalitas yang dilarang.
  2. Kenaikan GraphDef versi dan melaksanakan fungsi konsumen baru yang melarang op dihapus atau fungsi untuk GraphDefs di versi baru dan di atas. Jika memungkinkan, membuat TensorFlow berhenti memproduksi GraphDefs dengan fungsi dilarang. Untuk melakukannya, tambahkan REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Tunggu rilis utama untuk tujuan kompatibilitas mundur.
  4. Meningkatkan min_producer ke versi GraphDef dari (2) dan menghapus fungsi sepenuhnya.

Ubah fungsi operasi

  1. Tambahkan op sama baru bernama SomethingV2 atau serupa dan pergi melalui proses penambahan dan beralih pembungkus Python yang ada untuk menggunakannya. Untuk memastikan penggunaan kompatibilitas ke depan pemeriksaan yang disarankan dalam compat.py ketika mengubah pembungkus Python.
  2. Hapus op lama (Hanya dapat dilakukan dengan perubahan versi utama karena kompatibilitas ke belakang).
  3. Meningkatkan min_consumer untuk menyingkirkan konsumen dengan op tua, menambahkan kembali op tua sebagai alias untuk SomethingV2 , dan pergi melalui proses untuk beralih pembungkus Python yang ada untuk menggunakannya.
  4. Melalui proses untuk menghapus SomethingV2 .

Larang satu versi konsumen yang tidak aman

  1. Benjolan GraphDef versi dan menambahkan versi buruk untuk bad_consumers untuk semua GraphDefs baru. Jika memungkinkan, menambah bad_consumers hanya untuk GraphDefs yang berisi op tertentu atau serupa.
  2. Jika konsumen yang ada memiliki versi yang buruk, singkirkan mereka sesegera mungkin.