Kompatibilitas versi TensorFlow

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

Versi semantik 2.0

TensorFlow mengikuti Semantic Versioning 2.0 ( semver ) untuk API publiknya. Setiap versi rilis TensorFlow memiliki format MAJOR.MINOR.PATCH . Misalnya, TensorFlow versi 1.2.3 memiliki MAJOR versi 1, MINOR versi 2, dan PATCH versi 3. Perubahan pada setiap nomor memiliki arti sebagai berikut:

  • UTAMA : Kemungkinan perubahan yang tidak kompatibel ke belakang. Kode dan data yang berfungsi dengan rilis utama sebelumnya tidak akan selalu berfungsi dengan rilis baru. Namun, dalam beberapa kasus, grafik dan checkpoint TensorFlow yang ada dapat dimigrasikan ke rilis yang lebih baru; lihat Kompatibilitas grafik dan pos pemeriksaan untuk detail tentang kompatibilitas data.

  • MINOR : Fitur yang kompatibel dengan mundur, peningkatan kecepatan, dll. Kode dan data yang bekerja dengan rilis minor sebelumnya dan yang hanya bergantung pada API publik non-eksperimental akan terus berfungsi tanpa perubahan. Untuk detail tentang apa itu API publik dan bukan, lihat Apa yang tercakup .

  • PATCH : Perbaikan bug yang kompatibel dengan versi sebelumnya.

Misalnya, rilis 1.0.0 memperkenalkan perubahan yang tidak kompatibel dengan versi sebelumnya dari rilis 0.12.1. Namun, rilis 1.1.1 kompatibel dengan rilis 1.0.0.

Apa yang tercakup

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

  • Semua fungsi dan kelas Python yang didokumentasikan dalam modul tensorflow dan submodulnya, kecuali untuk

    • Simbol pribadi: fungsi, kelas, dll., Yang namanya dimulai dengan _
    • Simbol eksperimental dan tf.contrib , lihat detailnya di bawah .

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

    Jika simbol tersedia melalui modul tensorflow Python atau submodulnya, tetapi tidak didokumentasikan, simbol tersebut tidak dianggap sebagai bagian dari API publik.

  • API kompatibilitas (dalam Python, modul tf.compat ). Pada versi mayor, kami mungkin merilis utilitas dan titik akhir tambahan untuk membantu pengguna dalam transisi ke versi mayor baru. Simbol API ini sudah usang dan tidak didukung (yaitu, kami tidak akan menambahkan fitur apa pun, dan kami tidak akan memperbaiki bug selain untuk memperbaiki kerentanan), tetapi mereka termasuk dalam jaminan kompatibilitas kami.

  • C API .

  • File buffer protokol berikut:

Apa yang tidak tercakup

Beberapa bagian TensorFlow dapat berubah dengan cara yang tidak kompatibel dengan versi lama. Ini termasuk:

  • API Eksperimental : Untuk memfasilitasi pengembangan, kami mengecualikan beberapa simbol API yang dengan jelas ditandai eksperimental dari jaminan kompatibilitas. Secara khusus, berikut ini tidak tercakup oleh jaminan kompatibilitas apa pun:

    • simbol apa pun dalam modul tf.contrib atau submodulnya;
    • simbol apa pun (modul, fungsi, argumen, properti, kelas, atau konstanta) yang namanya mengandung experimental atau Experimental ; atau

    • simbol apa pun yang namanya memenuhi syarat lengkap termasuk modul atau kelas yang juga merupakan eksperimen. Ini termasuk bidang dan pesan dari setiap penyangga protokol yang disebut experimental .

  • Bahasa lain : TensorFlow API dalam bahasa selain Python dan C, seperti:

  • Detail operasi gabungan: Banyak fungsi publik di Python berkembang menjadi beberapa operasi primitif dalam grafik, dan detail ini akan menjadi bagian dari grafik apa pun yang disimpan ke disk sebagai GraphDef . Detail ini dapat berubah untuk rilis kecil. Secara khusus, pengujian regresi yang memeriksa kecocokan tepat antara grafik kemungkinan besar akan merusak rilis minor, meskipun perilaku grafik tidak boleh berubah dan checkpoint yang ada akan tetap berfungsi.

  • Detail numerik floating point: Nilai floating point spesifik yang dihitung oleh operasi dapat berubah kapan saja. Pengguna harus mengandalkan hanya pada perkiraan akurasi 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 pembelajaran mesin, akurasi formula tertentu yang ditingkatkan dapat mengakibatkan penurunan akurasi untuk keseluruhan sistem.

  • Nomor acak: Nomor acak tertentu yang dihitung dapat berubah setiap saat. Pengguna harus mengandalkan hanya pada distribusi yang kira-kira benar dan kekuatan statistik, bukan bit spesifik yang dihitung. Lihat panduan pembuatan nomor acak untuk detailnya.

  • Versi miring dalam Tensorflow terdistribusi: Menjalankan dua versi TensorFlow yang berbeda dalam satu cluster tidak didukung. Tidak ada jaminan tentang kompatibilitas mundur dari protokol kabel.

  • Bug: Kami berhak untuk membuat perubahan perilaku yang tidak kompatibel (meskipun bukan API) jika implementasi saat ini jelas-jelas rusak, yaitu, jika itu bertentangan dengan dokumentasi atau jika perilaku yang dimaksudkan dengan baik dan terdefinisi dengan baik tidak diterapkan dengan benar karena ke bug. Misalnya, jika pengoptimal mengklaim menerapkan algoritme pengoptimalan yang terkenal tetapi tidak cocok dengan algoritme tersebut karena ada bug, kami akan memperbaiki pengoptimal tersebut. Perbaikan kami dapat merusak kode yang bergantung pada perilaku yang salah untuk konvergensi. Kami akan mencatat perubahan tersebut dalam catatan rilis.

  • API yang tidak digunakan: Kami berhak untuk membuat perubahan yang tidak kompatibel ke API yang tidak kami temukan penggunaan yang terdokumentasi (dengan melakukan audit penggunaan TensorFlow melalui penelusuran GitHub). Sebelum melakukan perubahan apa pun, kami akan mengumumkan niat kami untuk melakukan perubahan tersebut di announce @ mailing list , memberikan petunjuk tentang cara mengatasi kerusakan apa pun (jika ada), dan menunggu selama dua minggu untuk memberikan kesempatan kepada komunitas kami untuk membagikan tanggapan mereka. .

  • Perilaku kesalahan: Kami dapat mengganti kesalahan dengan perilaku non-kesalahan. Misalnya, kita dapat mengubah fungsi untuk menghitung hasil daripada memunculkan 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 SavedModels, grafik, dan pos pemeriksaan

SavedModel adalah format serialisasi yang lebih disukai untuk digunakan dalam program TensorFlow. SavedModels berisi dua bagian: Satu atau lebih grafik yang 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, dan memuat serta mengeksekusinya dengan rilis TensorFlow nanti. Sesuai dengan semver , SavedModels yang ditulis dengan satu versi TensorFlow dapat dimuat dan dievaluasi dengan versi TensorFlow yang lebih baru dengan rilis utama yang sama.

Kami memberikan jaminan tambahan untuk SavedModels yang didukung . Kami menyebut SavedModel yang dibuat hanya menggunakan API non-deprecated, non-eksperimental, non-kompatibilitas di TensorFlow versi utama N sebagai SavedModel yang didukung di versi N Semua SavedModel yang didukung di TensorFlow versi utama N dapat dimuat dan dijalankan 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 menjaga kompatibilitas mundur selama mungkin, sehingga file serial dapat digunakan dalam jangka waktu yang lama.

Kompatibilitas GraphDef

Grafik diserialkan melalui buffer protokol GraphDef . Untuk memfasilitasi perubahan mundur yang tidak kompatibel pada grafik, setiap GraphDef memiliki nomor versi yang terpisah dari versi TensorFlow. Misalnya, GraphDef versi 17 tidak lagi menggunakan operasi inv untuk mendukung reciprocal . Semantiknya adalah:

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

  • Grafik yang baru dibuat diberi nomor versi GraphDef terbaru.

  • Jika versi TensorFlow tertentu mendukung versi GraphDef dari suatu grafik, versi tersebut akan memuat dan mengevaluasi dengan perilaku yang sama seperti versi TensorFlow yang digunakan untuk membuatnya (kecuali untuk detail numerik floating point dan angka acak seperti yang diuraikan di atas), apa pun jurusannya versi TensorFlow. Secara khusus, GraphDef yang kompatibel dengan file checkpoint dalam satu versi TensorFlow (seperti kasus di SavedModel) akan tetap kompatibel dengan checkpoint tersebut di versi berikutnya, selama GraphDef didukung.

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

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

    • TensorFlow 1.2 mungkin mendukung GraphDef versi 4 hingga 7.
    • TensorFlow 1.3 dapat menambahkan GraphDef versi 8 dan mendukung versi 4 hingga 8.
    • Setidaknya enam bulan kemudian, TensorFlow 2.0.0 dapat menghentikan dukungan untuk versi 4 menjadi 7, meninggalkan versi 8 saja.

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

Terakhir, saat dukungan untuk versi GraphDef dihentikan, kami akan mencoba menyediakan alat untuk secara otomatis mengonversi grafik ke versi GraphDef didukung lebih baru.

Kompatibilitas grafik dan checkpoint saat memperluas TensorFlow

Bagian ini hanya relevan saat membuat perubahan yang tidak kompatibel ke format GraphDef , seperti saat menambahkan operasi, menghapus operasi, atau mengubah fungsionalitas operasi yang ada. Bagian sebelumnya sudah cukup untuk sebagian besar pengguna.

Kompatibilitas mundur dan maju parsial

Skema pembuatan versi kami memiliki tiga persyaratan:

  • Kompatibilitas mundur untuk mendukung pemuatan grafik dan checkpoint yang dibuat dengan versi TensorFlow yang lebih lama.
  • Teruskan kompatibilitas untuk mendukung skenario ketika produsen grafik atau checkpoint diupgrade ke versi TensorFlow yang lebih baru sebelum konsumen.
  • Aktifkan TensorFlow yang berkembang dengan cara yang tidak kompatibel. Misalnya, menghapus operasi, menambahkan atribut, dan menghapus atribut.

Perhatikan bahwa meskipun mekanisme versi GraphDef terpisah dari versi TensorFlow, perubahan yang tidak kompatibel dengan versi GraphDef format GraphDef masih dibatasi oleh Versi Semantik. Artinya, fungsionalitas hanya dapat dihapus atau diubah antara versi MAJOR TensorFlow (seperti 1.7 hingga 2.0 ). Selain itu, kompatibilitas 1.x.1 diberlakukan dalam rilis Patch ( 1.x.1 hingga 1.x.2 ).

Untuk mencapai kompatibilitas mundur dan maju dan untuk mengetahui kapan harus memberlakukan perubahan dalam format, grafik dan pos pemeriksaan memiliki metadata yang menjelaskan kapan mereka diproduksi. Bagian di bawah ini menjelaskan implementasi TensorFlow dan panduan untuk mengembangkan versi GraphDef .

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 pembuatan versi didefinisikan dalam core/public/version.h . Setiap kali versi baru ditambahkan, catatan ditambahkan ke tajuk yang merinci apa yang berubah dan tanggal.

Data, produsen, dan konsumen

Kami membedakan antara jenis informasi versi data berikut:

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

Setiap bagian dari data berversi memiliki bidang VersionDef versions yang mencatat producer yang membuat data, min_consumer yang kompatibel dengannya, dan daftar versi bad_consumers yang tidak diizinkan.

Secara default, saat produsen membuat beberapa data, data tersebut mewarisi versi producer dan min_consumer dari producer . bad_consumers dapat disetel jika versi konsumen tertentu diketahui mengandung bug dan harus dihindari. Seorang konsumen dapat menerima sebagian data jika semua berikut ini benar:

  • consumer > = min_consumer data
  • data's producer > = min_producer konsumen
  • consumer bukan dalam bad_consumers data

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

  • Untuk versi GraphDef , kami memiliki TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER , dan TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Untuk versi checkpoint, kami 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 diinginkan, setel strip_default_attrs ke True saat mengekspor model menggunakan metode tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables dan tf.saved_model.SavedModelBuilder.add_meta_graph dari kelas SavedModelBuilder , atau tf.estimator.Estimator.export_saved_model
  2. Ini menghapus atribut nilai default pada saat memproduksi / mengekspor model. Ini memastikan bahwa tf.MetaGraphDef diekspor tidak berisi atribut op baru saat nilai default digunakan.
  3. Memiliki kontrol ini dapat memungkinkan konsumen lama (misalnya, menyajikan biner yang tertinggal dari biner pelatihan) untuk terus memuat model dan mencegah gangguan dalam penyajian model.

Mengembangkan versi GraphDef

Bagian ini menjelaskan cara menggunakan mekanisme pembuatan versi ini untuk membuat berbagai jenis perubahan pada format GraphDef .

Tambahkan op

Tambahkan operasi baru ke konsumen dan produsen secara bersamaan, dan jangan ubah versi GraphDef apa pun. Jenis perubahan ini secara otomatis kompatibel ke belakang, dan tidak memengaruhi rencana kompatibilitas ke depan karena skrip produsen yang ada tidak akan tiba-tiba menggunakan fungsionalitas baru.

Tambahkan op dan ganti pembungkus Python yang ada untuk menggunakannya

  1. Terapkan fungsionalitas konsumen baru dan GraphDef versi GraphDef .
  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 menambah min_consumer , karena model yang tidak menggunakan min_consumer ini tidak boleh rusak.

Hapus atau batasi fungsionalitas operasi

  1. Perbaiki semua skrip produsen (bukan TensorFlow itu sendiri) agar tidak menggunakan operasi atau fungsi yang dilarang.
  2. GraphDef versi GraphDef dan terapkan fungsionalitas konsumen baru yang melarang operasi atau fungsionalitas yang dihapus untuk GraphDefs pada versi baru dan yang lebih baru. Jika memungkinkan, buat TensorFlow berhenti memproduksi GraphDefs dengan fungsi yang dilarang. Untuk melakukannya, tambahkan REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Tunggu rilis utama untuk tujuan kompatibilitas mundur.
  4. Tingkatkan min_producer ke versi GraphDef dari (2) dan hapus fungsionalitas seluruhnya.

Ubah fungsionalitas operasi

  1. Tambahkan operasi serupa baru bernama SomethingV2 atau serupa dan ikuti proses menambahkannya dan mengganti pembungkus Python yang ada untuk menggunakannya. Untuk memastikan kompatibilitas ke depan, gunakan pemeriksaan yang disarankan di compat.py saat mengubah pembungkus Python.
  2. Hapus operasi lama (Hanya dapat dilakukan dengan perubahan versi utama karena kompatibilitas ke belakang).
  3. Tingkatkan min_consumer untuk menyingkirkan konsumen dengan operasi lama, tambahkan kembali operasi lama sebagai alias untuk SomethingV2 , dan ikuti proses untuk mengganti pembungkus Python yang ada untuk menggunakannya.
  4. Pergi melalui proses untuk menghapus SomethingV2 .

Cekal satu versi konsumen yang tidak aman

  1. Bump versi GraphDef dan tambahkan versi buruk ke bad_consumers untuk semua GraphDefs baru. Jika memungkinkan, tambahkan ke bad_consumers hanya untuk GraphDefs yang berisi operasi tertentu atau serupa.
  2. Jika konsumen yang sudah ada memiliki versi yang buruk, keluarkan mereka secepat mungkin.