TensorFlow Lite modellerine meta veri ekleme

TensorFlow Lite meta verileri, model açıklamaları için bir standart sağlar. Meta veriler, modelin ne yaptığı ve girdi/çıktı bilgileri hakkında önemli bir bilgi kaynağıdır. Meta veriler her ikisinden de oluşur

TensorFlow Hub'da yayınlanan tüm görüntü modelleri meta verilerle doldurulmuştur.

Meta veri formatına sahip model

model_with_metadata
Şekil 1. Meta veriler ve ilgili dosyalar ile TFLite modeli.

Model meta verileri, bir FlatBuffer dosyası olan metadata_schema.fbs dosyasında tanımlanır. Şekil 1'de görüldüğü gibi TFLite model şemasının metadata alanında "TFLITE_METADATA" adı altında saklanmaktadır. Bazı modeller, sınıflandırma etiketi dosyaları gibi ilişkili dosyalarla birlikte gelebilir. Bu dosyalar, ZipFile "ekleme" modunu ( 'a' modu) kullanarak orijinal model dosyasının sonuna ZIP olarak birleştirilir. TFLite Interpreter, yeni dosya formatını eskisi gibi kullanabilir. Daha fazla bilgi için İlişkili dosyaları paketleme konusuna bakın.

Meta verilerin nasıl doldurulacağı, görselleştirileceği ve okunacağı hakkında aşağıdaki talimatlara bakın.

Meta veri araçlarını kurun

Modelinize meta veri eklemeden önce TensorFlow'u çalıştırmak için bir Python programlama ortamı kurulumuna ihtiyacınız olacak. Burada bunun nasıl ayarlanacağına dair ayrıntılı bir kılavuz var.

Python programlama ortamını kurduktan sonra ek araçlar yüklemeniz gerekecektir:

pip install tflite-support

TensorFlow Lite meta veri araçları Python 3'ü destekler.

Flatbuffers Python API'sini kullanarak meta veri ekleme

Şemada model meta verilerinin üç bölümü vardır:

  1. Model bilgisi - Modelin genel açıklamasının yanı sıra lisans koşulları gibi öğeler. Bkz. ModelMetadata .
  2. Giriş bilgileri - Normalleştirme gibi gerekli girişlerin ve ön işlemlerin açıklaması. Bkz. SubGraphMetadata.input_tensor_metadata .
  3. Çıktı bilgileri - Etiketlere eşleme gibi çıktının ve gerekli son işlemlerin açıklaması. Bkz. SubGraphMetadata.output_tensor_metadata .

TensorFlow Lite bu noktada yalnızca tek alt grafiği desteklediğinden, TensorFlow Lite kod oluşturucu ve Android Studio ML Binding özelliği, meta verileri görüntülerken ve kod oluştururken ModelMetadata.name ve SubGraphMetadata.description yerine SubGraphMetadata.name ve ModelMetadata.description kullanacaktır.

Desteklenen Giriş / Çıkış türleri

Giriş ve çıkışa ilişkin TensorFlow Lite meta verileri, belirli model türleri dikkate alınarak değil, giriş ve çıkış türleri dikkate alınarak tasarlanmıştır. Giriş ve çıkış türleri aşağıdakilerden veya aşağıdakilerin bir kombinasyonundan oluştuğu sürece modelin işlevsel olarak ne yaptığı önemli değildir, TensorFlow Lite meta verileri tarafından desteklenir:

  • Özellik - İşaretsiz tamsayılar veya kayan nokta32 olan sayılar.
  • Resim - Meta veriler şu anda RGB ve gri tonlamalı resimleri desteklemektedir.
  • Sınırlayıcı kutu - Dikdörtgen şekilli sınırlayıcı kutular. Şema çeşitli numaralandırma düzenlerini destekler.

İlgili dosyaları paketleyin

TensorFlow Lite modelleri farklı ilişkili dosyalarla birlikte gelebilir. Örneğin, doğal dil modellerinde genellikle sözcük parçalarını sözcük kimlikleriyle eşleştiren sözcük dosyaları bulunur; sınıflandırma modellerinde nesne kategorilerini belirten etiket dosyaları bulunabilir. İlişkili dosyalar olmadan (eğer varsa), model iyi çalışmaz.

İlişkili dosyalar artık meta veri Python kitaplığı aracılığıyla modelle birlikte paketlenebilir. Yeni TensorFlow Lite modeli, hem modeli hem de ilişkili dosyaları içeren bir zip dosyasına dönüşür. Yaygın olarak kullanılan zip araçlarıyla açılabilir. Bu yeni model formatı aynı dosya uzantısı olan .tflite kullanmaya devam ediyor. Mevcut TFLite çerçevesi ve Yorumlayıcı ile uyumludur. Daha fazla ayrıntı için bkz. Meta verileri ve ilişkili dosyaları modele paketleme .

İlişkili dosya bilgileri meta verilere kaydedilebilir. Dosya türüne ve dosyanın eklendiği yere (örn. ModelMetadata , SubGraphMetadata ve TensorMetadata ) bağlı olarak TensorFlow Lite Android kod oluşturucu , ilgili ön/son işlemleri nesneye otomatik olarak uygulayabilir. Daha fazla ayrıntı için şemadaki her bir ilişkili dosya türünün <Kod oluşturma kullanımı> bölümüne bakın.

Normalizasyon ve nicemleme parametreleri

Normalleştirme, makine öğreniminde yaygın olarak kullanılan bir veri ön işleme tekniğidir. Normalleştirmenin amacı, değer aralıklarındaki farklılıkları bozmadan değerleri ortak bir ölçeğe değiştirmektir.

Model nicemleme, ağırlıkların azaltılmış hassasiyetteki temsillerine ve isteğe bağlı olarak hem depolama hem de hesaplama için aktivasyonlara izin veren bir tekniktir.

Ön işleme ve son işleme açısından normalizasyon ve nicemleme iki bağımsız adımdır. Detaylar burada.

Normalleştirme Niceleme

Sırasıyla kayan nokta ve nicelik modelleri için MobileNet'teki giriş görüntüsünün parametre değerlerinin bir örneği.
Şamandıra modeli :
- ortalama: 127,5
- standart: 127,5
Quant modeli :
- ortalama: 127,5
- standart: 127,5
Şamandıra modeli :
- sıfırNoktası: 0
- ölçek: 1,0
Quant modeli :
- sıfırNoktası: 128,0
- ölçek:0,0078125f




Ne zaman çağrılmalı?


Girdiler : Eğer girdi verileri eğitimde normalleştirilirse, çıkarımın girdi verilerinin de buna göre normalleştirilmesi gerekir.
Çıkışlar : çıkış verileri genel olarak normalleştirilmeyecektir.
Şamandıra modelleri kuantizasyona ihtiyaç duymaz.
Nicelenmiş model, ön/son işlemde nicelemeye ihtiyaç duyabilir veya duymayabilir. Giriş/çıkış tensörlerinin veri tipine bağlıdır.
- kayan tensörler: ön/son işlemde kuantizasyona gerek yoktur. Quant op ve dequant op, model grafiğine eklenir.
- int8/uint8 tensörleri: ön/son işlemde nicemlemeye ihtiyaç vardır.


Formül


normalized_input = (giriş - ortalama) / std
Girişler için niceleme :
q = f / ölçek + sıfırNoktası
Çıkışlar için dekuantizasyon :
f = (q - sıfırNoktası) * ölçek

Parametreler nerede
Model oluşturucu tarafından doldurulur ve model meta verilerinde NormalizationOptions olarak saklanır TFLite dönüştürücü tarafından otomatik olarak doldurulur ve tflite model dosyasında saklanır.
Parametreler nasıl alınır? MetadataExtractor API'si aracılığıyla [2] TFLite Tensor API'si [1] veya MetadataExtractor API'si [2] aracılığıyla
Float ve quant modelleri aynı değeri paylaşıyor mu? Evet, float ve quant modelleri aynı Normalleştirme parametrelerine sahiptir Hayır, kayan nokta modelinin kuantizasyona ihtiyacı yoktur.
TFLite Code oluşturucu veya Android Studio ML bağlama, bunu veri işleme sırasında otomatik olarak oluşturuyor mu?
Evet

Evet

[1] TensorFlow Lite Java API'si ve TensorFlow Lite C++ API'si .
[2] Meta veri çıkarıcı kütüphanesi

Uint8 modelleri için görüntü verileri işlenirken normalizasyon ve nicemleme bazen atlanır. Piksel değerleri [0, 255] aralığında olduğunda bunu yapmakta sakınca yoktur. Ancak genel olarak verileri her zaman uygun olduğunda normalizasyon ve nicemleme parametrelerine göre işlemelisiniz.

Meta verilerde NormalizationOptions ayarlarsanız TensorFlow Lite Görev Kitaplığı sizin için normalleştirmeyi gerçekleştirebilir. Kuantizasyon ve dekuantizasyon işlemleri her zaman kapsüllenir.

Örnekler

Farklı model türleri için meta verilerin nasıl doldurulması gerektiğine ilişkin örnekleri burada bulabilirsiniz:

Görüntü sınıflandırması

Meta verileri mobilenet_v1_0.75_160_quantized.tflite'a dolduran betiği buradan indirin. Komut dosyasını şu şekilde çalıştırın:

python ./metadata_writer_for_image_classifier.py \
    --model_file=./model_without_metadata/mobilenet_v1_0.75_160_quantized.tflite \
    --label_file=./model_without_metadata/labels.txt \
    --export_directory=model_with_metadata

Diğer görüntü sınıflandırma modellerine ilişkin meta verileri doldurmak için bunun gibi model özelliklerini komut dosyasına ekleyin. Bu kılavuzun geri kalanında, temel unsurları göstermek için görüntü sınıflandırma örneğindeki bazı önemli bölümler vurgulanacaktır.

Görüntü sınıflandırma örneğine derinlemesine bakın

Model bilgisi

Meta veriler yeni bir model bilgisi oluşturarak başlar:

from tflite_support import flatbuffers
from tflite_support import metadata as _metadata
from tflite_support import metadata_schema_py_generated as _metadata_fb

""" ... """
"""Creates the metadata for an image classifier."""

# Creates model info.
model_meta = _metadata_fb.ModelMetadataT()
model_meta.name = "MobileNetV1 image classifier"
model_meta.description = ("Identify the most prominent object in the "
                          "image from a set of 1,001 categories such as "
                          "trees, animals, food, vehicles, person etc.")
model_meta.version = "v1"
model_meta.author = "TensorFlow"
model_meta.license = ("Apache License. Version 2.0 "
                      "http://www.apache.org/licenses/LICENSE-2.0.")

Giriş / çıkış bilgileri

Bu bölüm modelinizin giriş ve çıkış imzasını nasıl tanımlayacağınızı gösterir. Bu meta veriler, otomatik kod oluşturucular tarafından işleme öncesi ve sonrası kod oluşturmak için kullanılabilir. Bir tensör hakkında giriş veya çıkış bilgisi oluşturmak için:

# Creates input info.
input_meta = _metadata_fb.TensorMetadataT()

# Creates output info.
output_meta = _metadata_fb.TensorMetadataT()

Görüntü girişi

Görüntü, makine öğrenimi için yaygın bir giriş türüdür. TensorFlow Lite meta verileri, renk alanı gibi bilgileri ve normalleştirme gibi ön işleme bilgilerini destekler. Görüntünün boyutu, giriş tensörünün şekli tarafından zaten sağlandığı ve otomatik olarak çıkarılabildiği için manuel belirleme gerektirmez.

input_meta.name = "image"
input_meta.description = (
    "Input image to be classified. The expected image is {0} x {1}, with "
    "three channels (red, blue, and green) per pixel. Each value in the "
    "tensor is a single byte between 0 and 255.".format(160, 160))
input_meta.content = _metadata_fb.ContentT()
input_meta.content.contentProperties = _metadata_fb.ImagePropertiesT()
input_meta.content.contentProperties.colorSpace = (
    _metadata_fb.ColorSpaceType.RGB)
input_meta.content.contentPropertiesType = (
    _metadata_fb.ContentProperties.ImageProperties)
input_normalization = _metadata_fb.ProcessUnitT()
input_normalization.optionsType = (
    _metadata_fb.ProcessUnitOptions.NormalizationOptions)
input_normalization.options = _metadata_fb.NormalizationOptionsT()
input_normalization.options.mean = [127.5]
input_normalization.options.std = [127.5]
input_meta.processUnits = [input_normalization]
input_stats = _metadata_fb.StatsT()
input_stats.max = [255]
input_stats.min = [0]
input_meta.stats = input_stats

Etiket çıkışı

Etiket, TENSOR_AXIS_LABELS kullanılarak ilişkili bir dosya aracılığıyla bir çıkış tensörüne eşlenebilir.

# Creates output info.
output_meta = _metadata_fb.TensorMetadataT()
output_meta.name = "probability"
output_meta.description = "Probabilities of the 1001 labels respectively."
output_meta.content = _metadata_fb.ContentT()
output_meta.content.content_properties = _metadata_fb.FeaturePropertiesT()
output_meta.content.contentPropertiesType = (
    _metadata_fb.ContentProperties.FeatureProperties)
output_stats = _metadata_fb.StatsT()
output_stats.max = [1.0]
output_stats.min = [0.0]
output_meta.stats = output_stats
label_file = _metadata_fb.AssociatedFileT()
label_file.name = os.path.basename("your_path_to_label_file")
label_file.description = "Labels for objects that the model can recognize."
label_file.type = _metadata_fb.AssociatedFileType.TENSOR_AXIS_LABELS
output_meta.associatedFiles = [label_file]

Meta veri Flatbuffer'larını oluşturun

Aşağıdaki kod, model bilgilerini giriş ve çıkış bilgileriyle birleştirir:

# Creates subgraph info.
subgraph = _metadata_fb.SubGraphMetadataT()
subgraph.inputTensorMetadata = [input_meta]
subgraph.outputTensorMetadata = [output_meta]
model_meta.subgraphMetadata = [subgraph]

b = flatbuffers.Builder(0)
b.Finish(
    model_meta.Pack(b),
    _metadata.MetadataPopulator.METADATA_FILE_IDENTIFIER)
metadata_buf = b.Output()

Meta verileri ve ilişkili dosyaları modele paketleyin

Meta veri Flatbuffer'ları oluşturulduktan sonra meta veriler ve etiket dosyası, populate yöntemi aracılığıyla TFLite dosyasına yazılır:

populator = _metadata.MetadataPopulator.with_model_file(model_file)
populator.load_metadata_buffer(metadata_buf)
populator.load_associated_files(["your_path_to_label_file"])
populator.populate()

load_associated_files aracılığıyla modele istediğiniz sayıda ilişkili dosyayı paketleyebilirsiniz. Ancak en azından meta verilerde belgelenen dosyaların paketlenmesi gerekir. Bu örnekte etiket dosyasının paketlenmesi zorunludur.

Meta verileri görselleştirin

Meta verilerinizi görselleştirmek için Netron'u kullanabilir veya MetadataDisplayer kullanarak meta verileri bir TensorFlow Lite modelinden json formatına okuyabilirsiniz:

displayer = _metadata.MetadataDisplayer.with_model_file(export_model_path)
export_json_file = os.path.join(FLAGS.export_directory,
                                os.path.splitext(model_basename)[0] + ".json")
json_file = displayer.get_metadata_json()
# Optional: write out the metadata as a json file
with open(export_json_file, "w") as f:
  f.write(json_file)

Android Studio ayrıca Android Studio ML Binding özelliği aracılığıyla meta verilerin görüntülenmesini de destekler.

Meta veri sürümü oluşturma

Meta veri şeması , hem şema dosyasındaki değişiklikleri izleyen Anlamsal sürüm numarasına hem de gerçek sürüm uyumluluğunu gösteren Flatbuffers dosya kimliğine göre sürümlendirilir.

Anlamsal sürüm numarası

Meta veri şeması, MAJOR.MINOR.PATCH gibi Anlamsal sürüm numarasına göre sürümlendirilir. Buradaki kurallara göre şema değişikliklerini takip eder. Sürüm 1.0.0 sonra eklenen alanların geçmişine bakın.

Flatbuffers dosya kimliği

Semantik sürüm oluşturma, kurallara uyulması durumunda uyumluluğu garanti eder, ancak gerçek uyumsuzluğu ima etmez. MAJOR sayısını artırmak, geriye dönük uyumluluğun bozulduğu anlamına gelmez. Bu nedenle, meta veri şemasının gerçek uyumluluğunu belirtmek için Flatbuffers dosya tanımlamasını ( file_identifier) ​​kullanırız. Dosya tanımlayıcısı tam olarak 4 karakter uzunluğundadır. Belirli bir meta veri şemasına sabitlenmiştir ve kullanıcılar tarafından değiştirilemez. Meta veri şemasının geriye dönük uyumluluğunun herhangi bir nedenle bozulması gerekiyorsa, dosya_tanımlayıcısı örneğin "M001"den "M002"ye yükselecektir. Dosya_tanımlayıcısının metadata_version'a göre çok daha az sıklıkta değiştirilmesi bekleniyor.

Gerekli minimum meta veri ayrıştırıcı sürümü

Gerekli minimum meta veri ayrıştırıcı sürümü, meta veri Flatbuffer'ları tam olarak okuyabilen minimum meta veri ayrıştırıcı sürümüdür (Flatbuffer'lar tarafından oluşturulan kod). Sürüm, doldurulan tüm alanların sürümleri arasında etkili bir şekilde en büyük sürüm numarasıdır ve dosya tanımlayıcı tarafından belirtilen en küçük uyumlu sürümdür. Gerekli minimum meta veri ayrıştırıcı sürümü, meta veriler bir TFLite modeline doldurulduğunda MetadataPopulator tarafından otomatik olarak doldurulur. Gerekli minimum meta veri ayrıştırıcı sürümünün nasıl kullanıldığı hakkında daha fazla bilgi için meta veri çıkarıcıya bakın.

Modellerden meta verileri okuyun

Meta Veri Çıkarıcı kitaplığı, farklı platformlardaki modellerden meta verileri ve ilgili dosyaları okumak için kullanışlı bir araçtır ( Java sürümüne ve C++ sürümüne bakın). Flatbuffers kütüphanesini kullanarak kendi meta veri çıkarma aracınızı diğer dillerde oluşturabilirsiniz.

Java'daki meta verileri okuyun

Meta Veri Çıkarıcı kitaplığını Android uygulamanızda kullanmak için MavenCentral'da barındırılan TensorFlow Lite Meta Veri AAR'ı kullanmanızı öneririz. MetadataExtractor sınıfının yanı sıra meta veri şeması ve model şeması için FlatBuffers Java bağlamalarını içerir.

Bunu build.gradle bağımlılıklarınızda aşağıdaki gibi belirtebilirsiniz:

dependencies {
    implementation 'org.tensorflow:tensorflow-lite-metadata:0.1.0'
}

Gecelik anlık görüntüleri kullanmak için Sonatype anlık görüntü deposunu eklediğinizden emin olun.

Bir MetadataExtractor nesnesini, modele işaret eden bir ByteBuffer ile başlatabilirsiniz:

public MetadataExtractor(ByteBuffer buffer);

ByteBuffer MetadataExtractor nesnesinin kullanım ömrü boyunca değişmeden kalmalıdır. Model meta verilerinin Flatbuffers dosya tanımlayıcısı meta veri ayrıştırıcısınınkiyle eşleşmezse başlatma başarısız olabilir. Daha fazla bilgi için meta veri sürümlendirmesine bakın.

Eşleşen dosya tanımlayıcıları ile meta veri çıkarıcı, Flatbuffer'ların ileri ve geri uyumluluk mekanizması nedeniyle tüm geçmiş ve gelecek şemalardan oluşturulan meta verileri başarıyla okuyacaktır. Ancak gelecekteki şemalardan alanlar eski meta veri çıkarıcılar tarafından çıkarılamaz. Meta verinin gerekli minimum ayrıştırıcı sürümü, meta veri Flatbuffer'ları tam olarak okuyabilen minimum meta veri ayrıştırıcı sürümünü belirtir. Gerekli minimum ayrıştırıcı sürümü koşulunun karşılanıp karşılanmadığını doğrulamak için aşağıdaki yöntemi kullanabilirsiniz:

public final boolean isMinimumParserVersionSatisfied();

Meta verileri olmayan bir modelin aktarılmasına izin verilir. Ancak meta verilerden okunan yöntemlerin çağrılması çalışma zamanı hatalarına neden olur. hasMetadata yöntemini çağırarak bir modelin meta veriye sahip olup olmadığını kontrol edebilirsiniz:

public boolean hasMetadata();

MetadataExtractor giriş/çıkış tensörlerinin meta verilerini almanız için kullanışlı işlevler sağlar. Örneğin,

public int getInputTensorCount();
public TensorMetadata getInputTensorMetadata(int inputIndex);
public QuantizationParams getInputTensorQuantizationParams(int inputIndex);
public int[] getInputTensorShape(int inputIndex);
public int getoutputTensorCount();
public TensorMetadata getoutputTensorMetadata(int inputIndex);
public QuantizationParams getoutputTensorQuantizationParams(int inputIndex);
public int[] getoutputTensorShape(int inputIndex);

TensorFlow Lite model şeması birden fazla alt grafiği desteklese de TFLite Interpreter şu anda yalnızca tek bir alt grafiği desteklemektedir. Bu nedenle MetadataExtractor yöntemlerinde girdi bağımsız değişkeni olarak alt grafik dizinini atlar.

İlgili dosyaları modellerden okuyun

Meta verileri ve ilişkili dosyaları içeren TensorFlow Lite modeli, esasen, ilişkili dosyaları almak için yaygın zip araçlarıyla paketi açılabilen bir zip dosyasıdır. Örneğin, mobilenet_v1_0.75_160_quantized dosyasının sıkıştırmasını açabilir ve modeldeki etiket dosyasını aşağıdaki gibi çıkarabilirsiniz:

$ unzip mobilenet_v1_0.75_160_quantized_1_metadata_1.tflite
Archive:  mobilenet_v1_0.75_160_quantized_1_metadata_1.tflite
 extracting: labels.txt

İlgili dosyaları Meta Veri Çıkarıcı kitaplığı aracılığıyla da okuyabilirsiniz.

Java'da dosya adını MetadataExtractor.getAssociatedFile yöntemine aktarın:

public InputStream getAssociatedFile(String fileName);

Benzer şekilde, C++'da bu, ModelMetadataExtractor::GetAssociatedFile yöntemiyle yapılabilir:

tflite::support::StatusOr<absl::string_view> GetAssociatedFile(
      const std::string& filename) const;