TensorFlow Lite modellerine meta veri ekleme

TensorFlow Lite meta verileri, model açıklamaları için bir standart sağlar. Meta veri, modelin ne yaptığı ve giriş / çıkış bilgileri hakkında önemli bir bilgi kaynağıdır. Meta veri hem

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

Meta veri biçimine sahip model

model_with_metadata
Şekil 1. Meta veriler ve ilişkili dosyalar içeren TFLite modeli.

Model meta verileri, bir FlatBuffer dosyası olan metadata_schema.fbs içinde tanımlanır. Şekil 1'de gösterildiği gibi TFLite model şemasının meta veri alanında, "TFLITE_METADATA" adı altında depolanır. Bazı modellerde sınıflandırma etiketi dosyaları gibi ilişkilendirilmiş dosyalar olabilir. Bu dosyalar, ZipFile "ekleme" modu ('a' modu) kullanılarak, orijinal model dosyasının sonunda bir ZIP dosyası olarak birleştirilir. TFLite Çevirmeni, yeni dosya biçimini önceden olduğu gibi kullanabilir. Daha fazla bilgi için İlişkili dosyaları paketleme bölümüne bakın.

Meta verileri doldurma, görselleştirme ve okumayla ilgili aşağıdaki talimatı inceleyin.

Meta veri araçlarını ayarlama

Modelinize meta veri eklemeden önce TensorFlow'u çalıştırmak için bir Python programlama ortamı kurulumuna ihtiyacınız vardır. Bunun nasıl ayarlanacağıyla ilgili ayrıntılı kılavuzu burada bulabilirsiniz.

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

pip install tflite-support

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

Flatbuffers Python API kullanarak meta veri ekleme

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

  1. Model bilgileri - Modelin genel açıklaması ve lisans şartları gibi öğeler. ModelMetadata konusuna bakın.
  2. Giriş bilgileri: Normalleştirme gibi gerekli girişlerin ve ön işlemlerin açıklaması. SubGraphMetadata.input_tensor_metadata bölümüne bakın.
  3. Çıkış bilgileri: Çıkışın açıklaması ve etiketlerle eşleme gibi son işleme süreci. SubGraphMetadata.output_tensor_metadata bölümüne bakın.

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

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

Giriş ve çıkış için TensorFlow Lite meta verileri, belirli model türleri göz önünde bulundurularak değil, giriş ve çıkış türleri göz önünde bulundurularak tasarlanmıştır. Giriş ve çıkış türleri, aşağıdakilerden veya bunların bir birleşiminden oluştuğu sürece modelin işlevsel olarak ne yaptığı önemli değildir ve TensorFlow Lite meta verileri tarafından desteklenir:

  • Özellik: İmzalanmamış tamsayı veya float32 olan sayılar.
  • Resim - Meta veri ş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 şemalarını destekler.

İlişkili dosyaları paketle

TensorFlow Lite modelleri farklı ilişkilendirilmiş dosyalara sahip olabilir. Örneğin, doğal dil modelleri genellikle kelime parçalarını kelime kimlikleriyle eşleştiren kelime dağarcığı dosyalarına sahiptir. Sınıflandırma modellerinde ise nesne kategorilerini belirten etiket dosyaları bulunabilir. İlişkili dosyalar olmadan (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ı haline gelir. Yaygın olarak kullanılan zip araçlarıyla çıkarılabilir. Bu yeni model biçimi, aynı dosya uzantısını (.tflite) kullanmaya devam eder. Mevcut TFLite çerçevesi ve çevirmen ile uyumludur. Daha fazla ayrıntı için Meta verileri ve ilişkili dosyaları modele paketleme bölümüne bakın.

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

Normalleştirme ve nicelleştirme parametreleri

Normalleştirme, makine öğreniminde yaygın 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 nicelendirme, ağırlıkların daha düşük hassasiyetli temsillerine ve isteğe bağlı olarak hem depolama hem de hesaplama için aktivasyonlara olanak tanıyan bir tekniktir.

Ön işleme ve son işleme açısından normalleştirme ve nicelik iki bağımsız adımdır. Sorunla ilgili ayrıntılar aşağıda belirtilmiştir.

Normalleştirme Nicelleştirme

Sırasıyla kayma ve nicel modeller için MobileNet'teki giriş görüntüsünün parametre değerlerinin örneği.		 Kayan model:
- ortalama: 127,5
- std: 127,5
Nicel modeli:
- ortalama: 127,5
- std: 127,5 		Kayan öğe modeli:









Ne zaman çağrılmalı?

Girişler: Eğitimde giriş verileri normalleştirilirse çıkarım giriş verilerinin buna göre normalleştirilmesi gerekir.
Çıkışlar: Çıkış verileri genel olarak normalleştirilmez. 		Kayan modeller nicelenmez.
Nicelasyona tabi model için ön/son işlemede niceliklendirme yapılması gerekebilir veya gerekmeyebilir. Bu, giriş/çıkış tensörlerinin veri türüne bağlıdır.
- kayan tensörler: Ön/son işlemde nicelikselleştirme gerekmez. Quant işlemi ve dequant op, model grafiğine eklenir.
- int8/uint8 tensörleri: Önce/sonra işleme sırasında nicelik yapılması gerekir.


Formül

normalleştirilmiş_giriş = (giriş - ortalama) / std 		Girişlerde nicelik belirleme:
q = f / ölçek + sıfırNokta
Çıkışlar için niceliği sil:
f = (q - sıfırNokta) * ölçek

Parametreler nerede 		Model oluşturucu tarafından doldurulur ve model meta verilerinde saklanır: NormalizationOptions TFLite dönüştürücü tarafından otomatik olarak doldurulur ve tflite model dosyasında depolanır.
Parametreler nasıl alınır? MetadataExtractor API aracılığıyla [2] TFLiteTensor API [1] veya MetadataExtractor API üzerinden [2]
Kayan ve nicel modeller aynı değeri mi paylaşır? Evet, float ve quant modelleri aynı Normalleştirme parametrelerine Hayır, kayma modelinin ölçülmesi gerekmez.
TFLite Kodu oluşturucu veya Android Studio ML bağlaması, veri işlemede kodu otomatik olarak oluşturuyor mu?
Evet
Evet

[1] TensorFlow Lite Java API ve TensorFlow Lite C++ API.
[2] Meta veri ayıklayıcı kitaplığı

uint8 modelleri için görüntü verileri işlenirken normalleştirme ve niceleme bazen atlanır. Piksel değerleri [0, 255] aralığında olduğunda da sorun olmaz. Ancak genel olarak, uygun durumlarda verileri her zaman normalleştirme ve nicelleştirme parametrelerine göre işlemeniz gerekir.

Örnekler

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

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

Meta verileri mobilenet_v1_0.75_160_quantized.tflite olarak dolduracak olan komut dosyasını 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 modellerinin meta verilerini doldurmak için model özelliklerini (bu gibi) komut dosyasına ekleyin. Bu kılavuzun geri kalanında, önemli öğeleri göstermek için görüntü sınıflandırma örneğindeki önemli bölümlerden bazıları vurgulanacaktır.

Görüntü sınıflandırma örneğinin ayrıntılı incelemesi

Model bilgileri

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ümde, modelinizin giriş ve çıkış imzasını nasıl açıklayacağınız gösterilmektedir. Bu meta veriler, otomatik kod oluşturucular tarafından işleme öncesi ve sonrası kodu oluşturmak için kullanılabilir. Bir tensör hakkında giriş veya çıkış bilgileri oluşturmak için:

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

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

Resim girişi

Resim, 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. Resmin boyutu, giriş tensörünün şekli tarafından zaten sağlandığı ve otomatik olarak tahmin edilebildiği için manuel özellik 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 çı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 Flatbuffers oluşturma

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 paketle

Meta veri Flatbuffers oluşturulduktan sonra, meta veri ve etiket dosyası populate yöntemi kullanılarak 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 dosya paketleyebilirsiniz. Bununla birlikte, meta verilerde belgelenen en azından bu dosyaları paketlemeniz gerekir. Bu örnekte, etiket dosyasının paketlenmesi zorunludur.

Meta verileri görselleştirme

Meta verilerinizi görselleştirmek için Netron'u kullanabilir veya MetadataDisplayer kodunu kullanarak bir TensorFlow Lite modelindeki meta verileri json biçiminde 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, Android Studio ML Bağlama özelliği aracılığıyla meta verilerin gösterilmesini de destekler.

Meta veri sürümü oluşturma

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

Anlamsal sürüm numarası

Meta veri şeması, MAJOR.MINOR.PATCH gibi anlamsal sürüm oluşturma numarasına göre sürüme geçirilir. Şema değişikliklerini buradaki kurallara göre izler. 1.0.0 sürümünden sonra eklenen alanların geçmişine bakın.

Flatbuffers dosya kimliği

Anlamsal sürüm oluşturma, kurallara uyulması durumunda uyumluluğu garanti eder, ancak gerçek uyumsuzluğu ima etmez. MAJOR sayısının yükseltilmesi, geriye dönük uyumluluğun mutlaka bozulduğu anlamına gelmez. Bu nedenle, meta veri şemasının gerçek uyumluluğunu belirtmek için Flatbuffers dosya kimliği olan file_identifier parametresini kullanırız. Dosya tanımlayıcısı tam olarak 4 karakter uzunluğundadır. Belirli bir meta veri şemasına sabitlenir 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 file_identifier yükselir (örneğin, "M001"den "M002"ye). Dosya_tanımlayıcının, metaveri_sürümünden çok daha az sıklıkta değiştirilmesi beklenir.

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

Gerekli minimum meta veri ayrıştırıcı sürümü, meta veri ayrıştırıcının (Flatbuffers tarafından oluşturulan kod) meta veri Flatbuffers'ı tam olarak okuyabilen minimum sürümüdür. Sürüm, sonuç olarak, doldurulan tüm alanlardaki sürümler arasındaki en büyük sürüm numarası ve dosya tanımlayıcısı tarafından belirtilen uyumlu en küçük sürümdür. Meta veriler bir TFLite modeline girildiğinde, gerekli minimum meta veri ayrıştırıcı sürümü, 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 ayıklayıcı'ya bakın.

Modellerden meta verileri okuma

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

Meta verileri Java'da okuma

Android uygulamanızda Meta Veri Ayıklayıcı kitaplığını kullanmak için MavenCentral'da barındırılan TensorFlow Lite Metadata AAR'yi 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, modeli 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ınınkiyle eşleşmiyorsa başlatma işlemi başarısız olabilir. Daha fazla bilgi için meta veri sürümü oluşturma bölümüne bakın.

Eşleşen dosya tanımlayıcılarına sahip meta veri ayıklayıcı, Flatbuffers'ın ileriye ve geriye dönük uyumluluk mekanizması nedeniyle geçmiş ve gelecekteki tüm şemalardan oluşturulan meta verileri başarıyla okur. Ancak gelecekteki şemalarda bulunan alanlar, eski meta veri ayıklayıcıları tarafından ayıklanamaz. Meta verilerin gerekli minimum ayrıştırıcı sürümü, meta veri Flatbuffers'ı tam olarak okuyabilen minimum meta veri ayrıştırıcı sürümünü gösterir. 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();

Bir modelin meta verileri olmadan girilmesine izin verilir. Bununla birlikte, meta verilerden okuma yapan yöntemlerin çağrılması çalışma zamanı hatalarına neden olur. hasMetadata yöntemini çağırarak bir modelin meta veri içerip içermediğini 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 giriş bağımsız değişkeni olarak alt grafik dizinini dikkate almaz.

Modellerden ilişkili dosyaları okuma

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

$ 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

İlişkili dosyaları Meta Veri Ayıklayıcı kitaplığı üzerinden de okuyabilirsiniz.

Java'da dosya adını MetadataExtractor.getAssociatedFile yöntemine geçirin:

public InputStream getAssociatedFile(String fileName);

Benzer bir şekilde, C++'ta bu ModelMetadataExtractor::GetAssociatedFile şu yöntemle yapılabilir:

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