Terima kasih telah mendengarkan Google I/O. Lihat semua sesi sesuai permintaan Tonton sesuai permintaan

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 memodifikasi TensorFlow sambil mempertahankan kompatibilitas.

Versi semantik 2.0

TensorFlow mengikuti Semantic Versioning 2.0 ( semver ) untuk API publiknya. 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 pada setiap angka memiliki arti sebagai berikut:

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

  • MINOR : Fitur yang kompatibel dengan versi sebelumnya, peningkatan kecepatan, dll. Kode dan data yang berfungsi dengan rilis minor sebelumnya dan yang hanya bergantung pada API publik non-eksperimental akan terus berfungsi tidak berubah. Untuk detail tentang API publik dan bukan, lihat Apa yang dicakup .

  • PATCH : Perbaikan bug yang kompatibel ke belakang.

Misalnya, rilis 1.0.0 memperkenalkan perubahan yang tidak kompatibel mundur 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 mundur di seluruh versi minor dan patch. API publik terdiri dari

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

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

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

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

  • API kompatibilitas (dengan Python, modul tf.compat ). Pada versi utama, kami dapat merilis utilitas dan titik akhir tambahan untuk membantu pengguna melakukan transisi ke versi utama yang baru. Simbol API ini sudah 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.

  • API C.

  • File penyangga protokol berikut:

Apa yang tidak tercakup

Beberapa bagian TensorFlow dapat berubah dengan cara yang tidak kompatibel ke belakang kapan saja. Ini termasuk:

  • API Eksperimental : Untuk memfasilitasi pengembangan, kami mengecualikan beberapa simbol API yang secara jelas ditandai sebagai eksperimental dari jaminan kompatibilitas. Secara khusus, berikut ini tidak dicakup 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 mencakup modul atau kelas yang merupakan eksperimen itu sendiri. Ini termasuk bidang dan subpesan dari buffer protokol apa pun yang disebut experimental .

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

  • Detail operasi gabungan: Banyak fungsi publik di Python memperluas ke beberapa operasi primitif dalam grafik, dan detail ini akan menjadi bagian dari grafik apa pun yang disimpan ke disk sebagai GraphDef s. Detail ini dapat berubah untuk rilis minor. Secara khusus, uji regresi yang memeriksa pencocokan tepat antara grafik kemungkinan besar akan menembus rilis minor, meskipun perilaku grafik seharusnya tidak berubah dan pos pemeriksaan yang ada akan tetap berfungsi.

  • Detail numerik floating point: Nilai floating point spesifik yang dihitung oleh ops dapat berubah sewaktu-waktu. Pengguna sebaiknya hanya mengandalkan akurasi perkiraan dan stabilitas numerik, bukan pada bit spesifik yang dihitung. Perubahan pada rumus numerik dalam rilis minor dan tambalan harus menghasilkan akurasi yang sebanding atau ditingkatkan, dengan peringatan bahwa peningkatan akurasi pada pembelajaran mesin dari formula tertentu dapat mengakibatkan penurunan akurasi untuk keseluruhan sistem.

  • Angka acak: Angka acak spesifik yang dihitung dapat berubah sewaktu-waktu. 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 berbeda dari TensorFlow dalam satu kluster tidak didukung. Tidak ada jaminan tentang kompatibilitas ke belakang dari wire protocol.

  • Bug: Kami berhak untuk mengubah perilaku yang tidak kompatibel ke belakang (meskipun bukan API) jika implementasi saat ini jelas-jelas rusak, yaitu, jika 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 terkenal tetapi tidak cocok dengan algoritme tersebut karena bug, maka kami akan memperbaiki pengoptimal tersebut. Perbaikan kami dapat merusak kode dengan mengandalkan perilaku yang salah untuk konvergensi. Kami akan mencatat perubahan tersebut di catatan rilis.

  • API yang tidak digunakan: Kami berhak membuat perubahan yang tidak kompatibel ke belakang pada API yang tidak kami temukan penggunaannya yang terdokumentasi (dengan melakukan audit penggunaan TensorFlow melalui pencarian GitHub). Sebelum melakukan perubahan tersebut, kami akan mengumumkan niat kami untuk melakukan perubahan di milis pengumuman@ , memberikan instruksi tentang cara mengatasi kerusakan (jika ada), dan menunggu selama dua minggu untuk memberikan kesempatan kepada komunitas kami untuk membagikan umpan balik mereka .

  • Perilaku kesalahan: Kami dapat mengganti kesalahan dengan perilaku non-kesalahan. Misalnya, kami dapat mengubah fungsi untuk menghitung hasil alih-alih 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 pilihan untuk digunakan dalam program TensorFlow. SavedModels berisi dua bagian: Satu atau lebih grafik yang dikodekan sebagai GraphDefs dan Checkpoint. Grafik menjelaskan 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 menjalankannya dengan rilis TensorFlow yang lebih baru. 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 memanggil SavedModel yang dibuat hanya menggunakan API non-deprecated, non-experimental, non-compatibility di TensorFlow major version N a SavedModel 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 tersebut 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 diserialisasi melalui buffer protokol GraphDef . Untuk memfasilitasi perubahan yang tidak kompatibel mundur ke grafik, setiap GraphDef memiliki nomor versi yang terpisah dari versi TensorFlow. Misalnya, GraphDef versi 17 tidak lagi menggunakan inv op dan mendukung reciprocal . semantik adalah:

  • Setiap versi TensorFlow mendukung interval versi GraphDef . Interval ini akan konstan di seluruh rilis tambalan, dan hanya akan bertambah di seluruh rilis minor. Menghentikan 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 sebuah grafik, itu akan dimuat dan dievaluasi dengan perilaku yang sama seperti versi TensorFlow yang digunakan untuk membuatnya (kecuali untuk detail numerik floating point dan angka acak seperti diuraikan di atas), terlepas dari mayor versi TensorFlow. Secara khusus, GraphDef yang kompatibel dengan file checkpoint di satu versi TensorFlow (seperti yang terjadi 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 pos pemeriksaan mungkin tidak dapat membaca pos pemeriksaan yang dihasilkan oleh kode yang sama yang menjalankan versi berbeda dari TensorFlow.

  • Jika batas 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 hingga 7, hanya menyisakan versi 8.

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

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

Kompatibilitas grafik dan pos pemeriksaan saat memperluas TensorFlow

Bagian ini hanya relevan saat membuat perubahan yang tidak kompatibel pada 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 sebagian maju

Skema pembuatan versi kami memiliki tiga persyaratan:

  • Kompatibilitas mundur untuk mendukung grafik pemuatan dan pos pemeriksaan yang dibuat dengan TensorFlow versi lama.
  • Meneruskan kompatibilitas untuk mendukung skenario di mana pembuat grafik atau pos pemeriksaan ditingkatkan ke versi TensorFlow yang lebih baru sebelum konsumen.
  • Aktifkan TensorFlow yang berkembang dengan cara yang tidak kompatibel. Misalnya menghapus ops, menambahkan atribut, dan menghapus atribut.

Perhatikan bahwa meskipun mekanisme versi GraphDef terpisah dari versi TensorFlow, perubahan yang tidak kompatibel mundur ke format GraphDef masih dibatasi oleh Semantic Versioning. Ini berarti fungsionalitas hanya dapat dihapus atau diubah antara versi MAJOR dari TensorFlow (seperti 1.7 hingga 2.0 ). Selain itu, kompatibilitas ke depan diberlakukan dalam rilis Patch ( 1.x.1 hingga 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 diproduksi. Bagian di bawah menjelaskan implementasi dan pedoman TensorFlow untuk mengembangkan versi GraphDef .

Skema versi data independen

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

Data, produsen, dan konsumen

Kami membedakan antara jenis informasi versi data berikut:

  • produsen : biner yang menghasilkan data. Produser 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 dengan mereka ( min_producer ).

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

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

  • consumer >= min_consumer data
  • producer data >= min_producer konsumen
  • consumer tidak ada 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 pos pemeriksaan, kami memiliki TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMER , dan TF_CHECKPOINT_VERSION_MIN_PRODUCER .

Tambahkan atribut baru dengan default ke op yang ada

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

  1. Jika kompatibilitas maju 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 tf.MetaGraphDef yang diekspor tidak berisi atribut op baru saat nilai default digunakan.
  3. Memiliki kontrol ini dapat memungkinkan konsumen yang sudah usang (misalnya, melayani binari yang tertinggal dari binari pelatihan) untuk terus memuat model dan mencegah gangguan dalam penyajian model.

Versi GraphDef yang berkembang

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

Tambahkan op

Tambahkan op baru untuk 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 produser yang sudah ada tidak akan tiba-tiba menggunakan fungsionalitas baru.

Tambahkan op dan alihkan pembungkus Python yang ada untuk menggunakannya

  1. Terapkan fungsionalitas konsumen baru dan tingkatkan versi GraphDef .
  2. Jika memungkinkan untuk membuat pembungkus menggunakan fungsionalitas baru hanya dalam kasus yang sebelumnya tidak berfungsi, pembungkus dapat diperbarui sekarang.
  3. Ubah pembungkus Python untuk menggunakan fungsionalitas baru. Jangan menaikkan min_consumer , karena model yang tidak menggunakan operasi ini tidak boleh rusak.

Hapus atau batasi fungsionalitas operasi

  1. Perbaiki semua skrip produsen (bukan TensorFlow itu sendiri) agar tidak menggunakan op atau fungsionalitas yang dilarang.
  2. Tingkatkan versi GraphDef dan implementasikan fungsionalitas konsumen baru yang melarang op yang dihapus atau fungsionalitas untuk GraphDefs di 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 seluruh fungsionalitasnya.

Mengubah fungsionalitas operasi

  1. Tambahkan op serupa baru bernama SomethingV2 atau serupa dan lakukan proses penambahannya dan alihkan pembungkus Python yang ada untuk menggunakannya. Untuk memastikan kompatibilitas ke depan, gunakan pemeriksaan yang disarankan di compat.py saat mengubah pembungkus Python.
  2. Hapus op lama (Hanya dapat dilakukan dengan perubahan versi besar karena kompatibilitas ke belakang).
  3. Tingkatkan min_consumer untuk mengesampingkan konsumen dengan op lama, tambahkan kembali op lama sebagai alias untuk SomethingV2 , dan lakukan proses untuk mengganti pembungkus Python yang ada untuk menggunakannya.
  4. Ikuti proses untuk menghapus SomethingV2 .

Larang 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 op tertentu atau serupa.
  2. Jika konsumen yang ada memiliki versi yang buruk, keluarkan mereka sesegera mungkin.