TensorFlow Lite 모델에 메타데이터 추가

TensorFlow Lite 메타데이터는 모델 설명에 대한 표준을 제공합니다. 메타데이터는 모델이 수행하는 작업과 입력/출력 정보에 대한 중요한 지식 소스입니다. 메타데이터는 두 가지로 구성됩니다.

• 모델을 사용할 때 모범 사례를 전달하는 사람이 읽을 수 있는 부분
• TensorFlow Lite Android 코드 생성기 및 Android Studio ML 바인딩 기능 과 같은 코드 생성기가 활용할 수 있는 기계 판독 가능한 부분입니다.

TensorFlow Hub 에 게시된 모든 이미지 모델은 메타데이터로 채워져 있습니다.

메타데이터 형식의 모델

모델 메타데이터는 FlatBuffer 파일인 Metadata_schema.fbs 에 정의되어 있습니다. 그림 1에 표시된 것처럼 TFLite 모델 스키마 의 메타데이터 필드에 "TFLITE_METADATA" 라는 이름으로 저장됩니다. 일부 모델에는 분류 라벨 파일 과 같은 관련 파일이 함께 제공될 수 있습니다. 이러한 파일은 ZipFile "추가" 모드 ( 'a' 모드)를 사용하여 원본 모델 파일의 끝에 ZIP으로 연결됩니다. TFLite Interpreter는 이전과 동일한 방식으로 새 파일 형식을 사용할 수 있습니다. 자세한 내용은 관련 파일 압축을 참조하세요.

메타데이터를 채우고, 시각화하고, 읽는 방법은 아래 지침을 참조하세요.

메타데이터 도구 설정

모델에 메타데이터를 추가하기 전에 TensorFlow를 실행하기 위한 Python 프로그래밍 환경을 설정해야 합니다. 여기에서 이를 설정하는 방법에 대한 자세한 가이드가 있습니다.

Python 프로그래밍 환경을 설정한 후에는 추가 도구를 설치해야 합니다.

pip install tflite-support

TensorFlow Lite 메타데이터 도구는 Python 3을 지원합니다.

Flatbuffers Python API를 사용하여 메타데이터 추가

스키마 의 모델 메타데이터에는 세 부분이 있습니다.

1. 모델 정보 - 모델에 대한 전반적인 설명과 라이센스 조건 등의 항목입니다. 모델메타데이터를 참조하세요.
2. 입력 정보 - 정규화 등 필요한 입력 및 전처리에 대한 설명입니다. SubGraphMetadata.input_tensor_metadata 를 참조하세요.
3. 출력 정보 - 라벨 매핑 등 필요한 출력 및 사후 처리에 대한 설명입니다. SubGraphMetadata.output_tensor_metadata 를 참조하세요.

TensorFlow Lite는 현재 단일 하위 그래프만 지원하므로 TensorFlow Lite 코드 생성기 와 Android Studio ML 바인딩 기능은 메타데이터를 표시하고 코드를 생성할 때 SubGraphMetadata.name 및 SubGraphMetadata.description 대신 ModelMetadata.name 및 ModelMetadata.description 사용합니다.

지원되는 입력/출력 유형

입력 및 출력을 위한 TensorFlow Lite 메타데이터는 특정 모델 유형을 염두에 두고 설계되지 않고 오히려 입력 및 출력 유형을 염두에 두고 설계되었습니다. 입력 및 출력 유형이 다음 또는 다음의 조합으로 구성되어 있는 한 모델이 기능적으로 수행하는 작업은 중요하지 않으며 TensorFlow Lite 메타데이터에서 지원됩니다.

• 특징 - 부호 없는 정수 또는 float32인 숫자.
• 이미지 - 메타데이터는 현재 RGB 및 회색조 이미지를 지원합니다.
• 경계 상자 - 직사각형 모양의 경계 상자입니다. 스키마는 다양한 번호 매기기 체계를 지원합니다.

관련 파일을 압축합니다.

TensorFlow Lite 모델은 다양한 관련 파일과 함께 제공될 수 있습니다. 예를 들어 자연어 모델에는 일반적으로 단어 조각을 단어 ID에 매핑하는 어휘 파일이 있습니다. 분류 모델에는 객체 범주를 나타내는 레이블 파일이 있을 수 있습니다. 관련 파일이 없으면(있는 경우) 모델이 제대로 작동하지 않습니다.

이제 메타데이터 Python 라이브러리를 통해 관련 파일을 모델과 함께 번들로 묶을 수 있습니다. 새로운 TensorFlow Lite 모델은 모델과 관련 파일을 모두 포함하는 zip 파일이 됩니다. 일반적인 zip 도구를 사용하여 압축을 풀 수 있습니다. 이 새로운 모델 형식은 동일한 파일 확장자 .tflite 계속 사용합니다. 기존 TFLite 프레임워크 및 인터프리터와 호환됩니다. 자세한 내용은 메타데이터 및 관련 파일을 모델에 압축을 참조하세요.

관련 파일 정보는 메타데이터에 기록될 수 있습니다. 파일 유형과 파일이 첨부된 위치(예: ModelMetadata , SubGraphMetadata 및 TensorMetadata )에 따라 TensorFlow Lite Android 코드 생성기는 해당 사전/사후 처리를 객체에 자동으로 적용할 수 있습니다. 자세한 내용은 스키마에 있는 각 연관 파일 유형의 <Codegen 사용법> 섹션을 참조하세요.

정규화 및 양자화 매개변수

정규화는 기계 학습의 일반적인 데이터 전처리 기술입니다. 정규화의 목표는 값 범위의 차이를 왜곡하지 않고 값을 공통 척도로 변경하는 것입니다.

모델 양자화는 가중치의 정밀도 표현을 감소시키고 선택적으로 저장 및 계산 모두에 대한 활성화를 허용하는 기술입니다.

전처리와 후처리 측면에서 정규화와 양자화는 두 개의 독립적인 단계입니다. 자세한 내용은 다음과 같습니다.

[1] TensorFlow Lite Java API 및 TensorFlow Lite C++ API .
[2] 메타데이터 추출기 라이브러리

uint8 모델의 이미지 데이터를 처리할 때 정규화 및 양자화를 건너뛰는 경우가 있습니다. 픽셀 값이 [0, 255] 범위에 있을 때 그렇게 하는 것이 좋습니다. 그러나 일반적으로 해당되는 경우 정규화 및 양자화 매개변수에 따라 항상 데이터를 처리해야 합니다.

메타데이터에서 NormalizationOptions 설정하면 TensorFlow Lite 작업 라이브러리가 정규화를 처리할 수 있습니다. 양자화 및 역양자화 처리는 항상 캡슐화됩니다.

예

여기에서 다양한 유형의 모델에 대해 메타데이터를 채워야 하는 방법에 대한 예를 찾을 수 있습니다.

이미지 분류

mobilenet_v1_0.75_160_퀀티드.tflite 에 메타데이터를 채우는 스크립트를 여기에서 다운로드하세요. 다음과 같이 스크립트를 실행하세요.

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

다른 이미지 분류 모델에 대한 메타데이터를 채우려면 이와 같은 모델 사양을 스크립트에 추가하세요. 이 가이드의 나머지 부분에서는 핵심 요소를 설명하기 위해 이미지 분류 예제의 일부 핵심 섹션을 강조합니다.

이미지 분류 예시 자세히 알아보기

모델 정보

메타데이터는 새 모델 정보를 생성하는 것부터 시작됩니다.

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.")

입출력 정보

이 섹션에서는 모델의 입력 및 출력 서명을 설명하는 방법을 보여줍니다. 이 메타데이터는 자동 코드 생성기에서 사전 및 사후 처리 코드를 생성하는 데 사용될 수 있습니다. 텐서에 대한 입력 또는 출력 정보를 생성하려면 다음을 수행하십시오.

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

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

이미지 입력

이미지는 기계 학습의 일반적인 입력 유형입니다. TensorFlow Lite 메타데이터는 색상 공간과 같은 정보와 정규화와 같은 사전 처리 정보를 지원합니다. 이미지의 차원은 입력 텐서의 형태에 의해 이미 제공되고 자동으로 추론될 수 있으므로 수동으로 지정할 필요가 없습니다.

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

라벨 출력

TENSOR_AXIS_LABELS 사용하여 관련 파일을 통해 라벨을 출력 텐서에 매핑할 수 있습니다.

# 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]

메타데이터 플랫버퍼 생성

다음 코드는 모델 정보를 입력 및 출력 정보와 결합합니다.

# 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()

메타데이터 및 관련 파일을 모델에 포함

메타데이터 Flatbuffers가 생성되면 메타데이터와 레이블 파일은 populate 메소드를 통해 TFLite 파일에 기록됩니다.

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 통해 모델에 원하는 만큼 많은 관련 파일을 압축할 수 있습니다. 그러나 최소한 메타데이터에 문서화된 파일을 압축해야 합니다. 이 예에서는 레이블 파일을 압축하는 것이 필수입니다.

메타데이터 시각화

Netron을 사용하여 메타데이터를 시각화하거나 MetadataDisplayer 사용하여 TensorFlow Lite 모델의 메타데이터를 json 형식으로 읽을 수 있습니다.

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 바인딩 기능을 통해 메타데이터 표시도 지원합니다.

메타데이터 버전 관리

메타데이터 스키마는 스키마 파일의 변경 사항을 추적하는 Semantic 버전 번호와 실제 버전 호환성을 나타내는 Flatbuffers 파일 식별에 따라 버전이 지정됩니다.

시맨틱 버전 번호

메타데이터 스키마의 버전은 MAJOR.MINOR.PATCH와 같은 의미론적 버전 번호 로 지정됩니다. 여기에 있는 규칙에 따라 스키마 변경 사항을 추적합니다. 버전 1.0.0 이후에 추가된 필드의 기록을 확인하세요.

Flatbuffers 파일 식별

의미론적 버전 관리는 규칙을 따르면 호환성을 보장하지만 이것이 실제 비호환성을 의미하지는 않습니다. MAJOR 숫자가 올라간다고 해서 반드시 이전 버전과의 호환성이 깨졌다는 의미는 아닙니다. 따라서 메타데이터 스키마의 실제 호환성을 나타내기 위해 Flatbuffers 파일 ID 인 file_identifier를 사용합니다. 파일 식별자의 길이는 정확히 4자입니다. 이는 특정 메타데이터 스키마로 고정되어 있으며 사용자가 변경할 수 없습니다. 어떤 이유로든 메타데이터 스키마의 이전 버전과의 호환성이 중단되어야 하는 경우 file_identifier는 예를 들어 "M001"에서 "M002"로 올라갑니다. File_identifier는 Metadata_version보다 훨씬 덜 자주 변경될 것으로 예상됩니다.

필요한 최소 메타데이터 파서 버전

필요한 최소 메타데이터 파서 버전은 Flatbuffers 메타데이터 전체를 읽을 수 있는 메타데이터 파서(Flatbuffers 생성 코드)의 최소 버전입니다. 버전은 실제로 채워진 모든 필드의 버전 중에서 가장 큰 버전 번호이자 파일 식별자로 표시된 가장 작은 호환 버전입니다. 필요한 최소 메타데이터 파서 버전은 메타데이터가 TFLite 모델에 채워질 때 MetadataPopulator 에 의해 자동으로 채워집니다. 필요한 최소 메타데이터 파서 버전이 사용되는 방법에 대한 자세한 내용은 메타데이터 추출기를 참조하세요.

모델에서 메타데이터 읽기

Metadata Extractor 라이브러리는 다양한 플랫폼의 모델에서 메타데이터 및 관련 파일을 읽는 데 편리한 도구입니다( Java 버전 및 C++ 버전 참조). Flatbuffers 라이브러리를 사용하여 다른 언어로 자신만의 메타데이터 추출 도구를 구축할 수 있습니다.

Java에서 메타데이터 읽기

Android 앱에서 Metadata Extractor 라이브러리를 사용하려면 MavenCentral에서 호스팅되는 TensorFlow Lite Metadata AAR을 사용하는 것이 좋습니다. 여기에는 MetadataExtractor 클래스와 메타데이터 스키마 및 모델 스키마 에 대한 FlatBuffers Java 바인딩이 포함되어 있습니다.

다음과 같이 build.gradle 종속성에서 이를 지정할 수 있습니다.

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

야간 스냅샷을 사용하려면 Sonatype 스냅샷 저장소를 추가했는지 확인하세요.

모델을 가리키는 ByteBuffer 사용하여 MetadataExtractor 객체를 초기화할 수 있습니다.

public MetadataExtractor(ByteBuffer buffer);

ByteBuffer MetadataExtractor 객체의 전체 수명 동안 변경되지 않은 상태로 유지되어야 합니다. 모델 메타데이터의 Flatbuffers 파일 식별자가 메타데이터 파서의 식별자와 일치하지 않으면 초기화가 실패할 수 있습니다. 자세한 내용은 메타데이터 버전 관리를 참조하세요.

일치하는 파일 식별자를 사용하면 메타데이터 추출기는 Flatbuffers의 상위 및 하위 호환성 메커니즘으로 인해 모든 과거 및 미래 스키마에서 생성된 메타데이터를 성공적으로 읽습니다. 그러나 향후 스키마의 필드는 이전 메타데이터 추출기로 추출할 수 없습니다. 메타데이터의 최소 필요 파서 버전은 플랫버퍼 메타데이터 전체를 읽을 수 있는 메타데이터 파서의 최소 버전을 나타냅니다. 다음 방법을 사용하여 필요한 최소 파서 버전 조건이 충족되는지 확인할 수 있습니다.

public final boolean isMinimumParserVersionSatisfied();

메타데이터 없이 모델을 전달하는 것이 허용됩니다. 그러나 메타데이터에서 읽는 메서드를 호출하면 런타임 오류가 발생합니다. hasMetadata 메소드를 호출하여 모델에 메타데이터가 있는지 확인할 수 있습니다.

public boolean hasMetadata();

MetadataExtractor 입력/출력 텐서의 메타데이터를 가져올 수 있는 편리한 기능을 제공합니다. 예를 들어,

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 모델 스키마는 여러 하위 그래프를 지원하지만 TFLite Interpreter는 현재 단일 하위 그래프만 지원합니다. 따라서 MetadataExtractor 해당 메서드의 입력 인수로 하위 그래프 인덱스를 생략합니다.

모델에서 관련 파일 읽기

메타데이터 및 관련 파일이 포함된 TensorFlow Lite 모델은 본질적으로 관련 파일을 얻기 위해 일반적인 zip 도구로 압축을 풀 수 있는 zip 파일입니다. 예를 들어 다음과 같이 mobilenet_v1_0.75_160_Quantized의 압축을 풀고 모델에서 레이블 파일을 추출할 수 있습니다.

$ 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

Metadata Extractor 라이브러리를 통해 관련 파일을 읽을 수도 있습니다.

Java에서는 파일 이름을 MetadataExtractor.getAssociatedFile 메소드에 전달합니다.

public InputStream getAssociatedFile(String fileName);

마찬가지로 C++에서는 ModelMetadataExtractor::GetAssociatedFile 메서드를 사용하여 이 작업을 수행할 수 있습니다.

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