Kompatibilitas versi TensorFlow

Dokumen ini ditujukan untuk pengguna yang memerlukan kompatibilitas mundur di berbagai versi TensorFlow (baik untuk kode atau data), dan untuk developer yang ingin memodifikasi TensorFlow sambil menjaga 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 mempunyai arti sebagai berikut:

  • UTAMA : Berpotensi membalikkan perubahan yang tidak kompatibel. Kode dan data yang berfungsi pada rilis besar sebelumnya belum tentu berfungsi pada rilis baru. Namun, dalam beberapa kasus, grafik dan pos pemeriksaan 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 pada rilis minor sebelumnya dan yang hanya bergantung pada API publik non-eksperimental akan terus berfungsi tanpa perubahan. Untuk detail tentang apa yang termasuk dan bukan API publik, lihat Apa yang dicakup .

  • PATCH : Perbaikan bug yang kompatibel dengan versi sebelumnya.

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

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

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

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

    Jika suatu simbol tersedia melalui modul tensorflow 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 mungkin merilis utilitas dan titik akhir tambahan untuk membantu pengguna dalam transisi ke versi utama baru. Simbol API ini tidak digunakan lagi dan tidak didukung (misalnya, kami tidak akan menambahkan fitur apa pun, dan kami tidak akan memperbaiki bug selain memperbaiki kerentanan), namun simbol tersebut termasuk dalam jaminan kompatibilitas kami.

  • API TensorFlow C:

  • File buffer protokol berikut:

Nomor versi terpisah untuk TensorFlow Lite

Saat ini TensorFlow Lite didistribusikan sebagai bagian dari TensorFlow. Namun, kami berhak untuk melakukan perubahan pada rilis mendatang pada TensorFlow Lite API dengan jadwal yang berbeda dibandingkan TensorFlow API lainnya, atau bahkan memindahkan TensorFlow Lite ke distribusi sumber terpisah dan/atau repositori sumber terpisah dari TensorFlow.

Oleh karena itu, kami menggunakan nomor versi yang berbeda untuk TensorFlow Lite ( TFLITE_VERSION_STRING di tensorflow/lite/version.h , dan TfLiteVersion() di tensorflow/lite/c/c_api.h ) dibandingkan untuk TensorFlow ( TF_VERSION_STRING di tensorflow/core/public/version.h , dan TF_Version() di tensorflow/c/c_api.h ). Saat ini, kedua nomor versi ini memiliki nilai yang sama. Namun di masa depan, keduanya mungkin berbeda; misalnya, kami dapat menambah nomor versi utama TensorFlow Lite tanpa menambah nomor versi utama TensorFlow, atau sebaliknya.

Permukaan API yang dicakup oleh nomor versi TensorFlow Lite terdiri dari API publik berikut:

Simbol eksperimental tidak tercakup; lihat di bawah untuk detailnya.

Nomor versi terpisah untuk TensorFlow Lite Extension API

TensorFlow Lite menyediakan API C untuk memperluas penafsir TensorFlow Lite dengan "operasi khusus", yang menyediakan operasi yang ditentukan pengguna dalam sebuah grafik, atau "delegasi", yang memungkinkan pendelegasian komputasi untuk sebuah grafik (atau untuk subset grafik) ke backend khusus. API ini, yang secara kolektif kami sebut sebagai "API Ekstensi TensorFlow Lite", memerlukan ketergantungan yang lebih mendalam pada beberapa detail implementasi TensorFlow Lite.

Kami berhak untuk merilis perubahan pada API ini di masa mendatang, yang mungkin mencakup perubahan yang tidak kompatibel dengan versi sebelumnya, dengan jadwal yang berbeda dibandingkan TensorFlow Lite API lainnya. Jadi kami menggunakan nomor versi yang berbeda untuk TensorFlow Lite Extension API dengan nomor versi untuk TensorFlow Lite atau TensorFlow (yang telah dijelaskan di bagian sebelumnya). Kami memperkenalkan beberapa API baru di TensorFlow Lite versi 2.15 untuk mendapatkan versi API Ekstensi TensorFlow Lite ( TFLITE_EXTENSION_APIS_VERSION_STRING di tensorflow/lite/version.h , dan TfLiteExtensionApisVersion() di tensorflow/lite/c/c_api.h ). Nomor versi TensorFlow Lite Extension API saat ini sama dengan nomor versi TensorFlow dan TensorFlow Lite. Namun di masa depan, keduanya mungkin berbeda; misalnya, kami dapat menambah nomor versi utama untuk TensorFlow Lite Extension API tanpa menambah nomor versi utama untuk TensorFlow Lite, atau sebaliknya.

Permukaan API yang dicakup oleh nomor versi API Ekstensi TensorFlow Lite terdiri dari API publik berikut:

Sekali lagi, simbol eksperimental tidak tercakup; lihat di bawah untuk detailnya.

Apa yang tidak tercakup

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

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

    • simbol apa pun di modul tf.contrib atau submodulnya;
    • simbol apa pun (modul, fungsi, argumen, properti, kelas, konstanta, tipe, paket, dll.) yang namanya mengandung experimental atau Experimental ; atau
    • simbol apa pun yang namanya sepenuhnya memenuhi syarat mencakup modul atau kelas atau paket yang bersifat eksperimental. Ini mencakup bidang dan subpesan dari buffer protokol apa pun yang disebut experimental .

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

    dan TensorFlow Lite API dalam bahasa selain Java/Kotlin, C, Objective-C, dan Swift, khususnya

  • Detail operasi gabungan: Banyak fungsi publik di Python diperluas 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 mungkin berubah untuk rilis kecil. Secara khusus, uji regresi yang memeriksa pencocokan tepat antar grafik kemungkinan besar tidak akan terjadi pada rilis kecil, meskipun perilaku grafik tidak akan berubah dan pos pemeriksaan yang ada akan tetap berfungsi.

  • Detail numerik floating point: Nilai floating point spesifik yang dihitung oleh operasi dapat berubah kapan saja. Pengguna sebaiknya hanya mengandalkan akurasi perkiraan dan stabilitas numerik, bukan pada bit spesifik yang dihitung. Perubahan pada rumus numerik dalam rilis minor dan patch harus menghasilkan akurasi yang sebanding atau lebih baik, dengan peringatan bahwa dalam pembelajaran mesin, peningkatan akurasi rumus tertentu dapat mengakibatkan penurunan akurasi untuk sistem secara keseluruhan.

  • Nomor acak: Nomor acak spesifik yang dihitung dapat berubah sewaktu-waktu. Pengguna hanya boleh mengandalkan distribusi yang kira-kira benar dan kekuatan statistik, bukan bit spesifik yang dihitung. Lihat panduan pembuatan nomor acak untuk detailnya.

  • Kemiringan versi pada Tensorflow terdistribusi: Menjalankan dua versi TensorFlow yang berbeda dalam satu kluster tidak didukung. Tidak ada jaminan mengenai kompatibilitas mundur protokol kabel.

  • Bug: Kami berhak membuat perubahan perilaku yang tidak kompatibel (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 untuk bug. Misalnya, jika pengoptimal mengklaim menerapkan algoritme pengoptimalan terkenal tetapi tidak cocok dengan algoritme tersebut karena ada bug, maka kami akan memperbaiki pengoptimal tersebut. Perbaikan kami mungkin memecahkan kode dengan mengandalkan perilaku konvergensi yang salah. Kami akan mencatat perubahan tersebut di catatan rilis.

  • API yang Tidak Digunakan: Kami berhak membuat perubahan yang tidak kompatibel pada API yang menurut kami tidak ada kegunaannya yang terdokumentasi (dengan melakukan audit penggunaan TensorFlow melalui penelusuran GitHub). Sebelum melakukan perubahan apa pun, kami akan mengumumkan niat kami untuk melakukan perubahan di milis pengumuman@ , memberikan instruksi tentang cara mengatasi kerusakan apa pun (jika ada), dan menunggu selama dua minggu untuk memberikan kesempatan kepada komunitas kami untuk menyampaikan masukan mereka. .

  • Perilaku kesalahan: Kami dapat mengganti kesalahan dengan perilaku non-kesalahan. Misalnya, kita dapat mengubah fungsi untuk menghitung hasil alih-alih memunculkan kesalahan, meskipun kesalahan tersebut 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 menggambarkan aliran data operasi yang akan dijalankan, dan pos pemeriksaan berisi nilai tensor variabel yang disimpan dalam grafik.

Banyak pengguna TensorFlow membuat SavedModels, lalu memuat dan mengeksekusinya 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 yang tidak digunakan lagi, non-eksperimental, dan non-kompatibilitas di TensorFlow versi utama N dan SavedModel yang didukung di versi N . SavedModel apa pun yang didukung di TensorFlow versi utama N dapat dimuat dan dieksekusi dengan TensorFlow versi utama N+1 . Namun, fungsionalitas yang diperlukan untuk membangun atau memodifikasi model tersebut mungkin tidak tersedia lagi, jadi jaminan ini hanya berlaku untuk SavedModel yang tidak dimodifikasi.

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

Kompatibilitas GraphDef

Grafik diserialkan melalui buffer protokol GraphDef . Untuk memfasilitasi perubahan yang tidak kompatibel pada grafik, setiap GraphDef memiliki nomor versi yang terpisah dari versi TensorFlow. Misalnya, GraphDef versi 17 tidak lagi menggunakan operasi inv dan 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. Penghentian dukungan untuk versi GraphDef hanya akan terjadi pada 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 grafik versi GraphDef , versi tersebut akan memuat dan mengevaluasi dengan perilaku yang sama seperti versi TensorFlow yang digunakan untuk menghasilkannya (kecuali untuk detail numerik floating point dan angka acak seperti diuraikan di atas), apa pun jurusannya. versi TensorFlow. Secara khusus, GraphDef yang kompatibel dengan file checkpoint di salah satu versi TensorFlow (seperti halnya di SavedModel) akan tetap kompatibel dengan checkpoint tersebut di versi berikutnya, selama GraphDef didukung.

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

  • Jika batas atas GraphDef ditingkatkan menjadi X dalam rilis (kecil), akan ada setidaknya enam bulan sebelum batas bawah ditingkatkan 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, sehingga hanya menyisakan versi 8 saja.

    Perlu diperhatikan bahwa karena versi utama TensorFlow biasanya dipublikasikan dengan selang waktu lebih dari 6 bulan, jaminan untuk SavedModels yang didukung yang dijelaskan di atas jauh lebih kuat daripada jaminan 6 bulan untuk GraphDefs.

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

Kompatibilitas grafik dan pos pemeriksaan saat memperluas TensorFlow

Bagian ini hanya relevan ketika membuat perubahan yang tidak kompatibel pada format GraphDef , seperti saat menambahkan operasi, menghapus operasi, atau mengubah fungsi operasi yang ada. Bagian sebelumnya sudah cukup bagi sebagian besar pengguna.

Kompatibilitas mundur dan maju sebagian

Skema pembuatan versi kami memiliki tiga persyaratan:

  • Kompatibilitas mundur untuk mendukung pemuatan grafik dan pos pemeriksaan yang dibuat dengan TensorFlow versi lama.
  • Meneruskan kompatibilitas untuk mendukung skenario ketika pembuat grafik atau titik pemeriksaan diupgrade ke versi TensorFlow yang lebih baru sebelum konsumen.
  • Aktifkan TensorFlow yang berkembang dengan cara yang tidak kompatibel. Misalnya menghapus operasi, menambah atribut, dan menghapus atribut.

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

Untuk mencapai kompatibilitas mundur dan maju serta mengetahui kapan harus menerapkan perubahan format, grafik dan pos pemeriksaan memiliki metadata yang menjelaskan kapan perubahan tersebut dibuat. Bagian di bawah merinci implementasi TensorFlow dan pedoman untuk mengembangkan versi GraphDef .

Skema versi data independen

Ada versi data yang berbeda untuk grafik dan pos pemeriksaan. Kedua format data tersebut berkembang dengan kecepatan yang berbeda satu sama lain dan juga dengan kecepatan yang 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 jenis informasi versi data berikut ini:

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

Setiap bagian 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, ketika produsen membuat beberapa data, data tersebut mewarisi versi producer dan min_consumer dari produsen tersebut. bad_consumers dapat disetel jika versi konsumen tertentu diketahui mengandung bug dan harus dihindari. Konsumen dapat menerima suatu 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 operasi yang ada

Mengikuti panduan di bawah ini 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 bernilai default pada saat memproduksi/mengekspor model. Hal ini memastikan bahwa tf.MetaGraphDef yang diekspor tidak berisi atribut op baru ketika nilai default digunakan.
  3. Memiliki kontrol ini dapat memungkinkan konsumen yang sudah ketinggalan zaman (misalnya, melayani biner yang tertinggal dari biner 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 operasi

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 berdampak pada rencana kompatibilitas ke depan karena skrip produser yang ada tidak akan tiba-tiba menggunakan fungsi baru tersebut.

Tambahkan operasi dan ganti pembungkus Python yang ada untuk menggunakannya

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

Hapus atau batasi fungsi operasi

  1. Perbaiki semua skrip produser (bukan TensorFlow itu sendiri) agar tidak menggunakan operasi atau fungsi yang dilarang.
  2. Tingkatkan 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 besar untuk tujuan kompatibilitas ke belakang.
  4. Tingkatkan min_producer ke versi GraphDef dari (2) dan hapus seluruh fungsinya.

Mengubah fungsionalitas operasi

  1. Tambahkan operasi baru yang serupa bernama SomethingV2 atau serupa dan lakukan 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 besar karena kompatibilitas ke belakang).
  3. Tingkatkan min_consumer untuk mengecualikan konsumen dengan operasi lama, tambahkan kembali operasi lama sebagai alias untuk SomethingV2 , dan lakukan proses untuk mengganti pembungkus Python yang ada untuk menggunakannya.
  4. Jalani proses untuk menghapus SomethingV2 .

Larang satu versi konsumen yang tidak aman

  1. Ganti 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 lama mempunyai versi yang buruk, singkirkan mereka sesegera mungkin.