Créez votre propre API de tâches

La bibliothèque de tâches TensorFlow Lite fournit des API natives/Android/iOS prédéfinies au-dessus de la même infrastructure qui résume TensorFlow. Vous pouvez étendre l'infrastructure de l'API de tâches pour créer des API personnalisées si votre modèle n'est pas pris en charge par les bibliothèques de tâches existantes.

Aperçu

L'infrastructure de l'API de tâches a une structure à deux couches : la couche C++ inférieure encapsulant le runtime natif TFLite et la couche Java/ObjC supérieure qui communique avec la couche C++ via JNI ou un wrapper natif.

La mise en œuvre de toute la logique TensorFlow en C++ uniquement minimise les coûts, maximise les performances d'inférence et simplifie le flux de travail global sur toutes les plates-formes.

Pour créer une classe Task, étendez BaseTaskApi pour fournir une logique de conversion entre l'interface du modèle TFLite et l'interface API Task, puis utilisez les utilitaires Java/ObjC pour créer les API correspondantes. Avec tous les détails de TensorFlow masqués, vous pouvez déployer le modèle TFLite dans vos applications sans aucune connaissance en apprentissage automatique.

TensorFlow Lite fournit des API prédéfinies pour les tâches Vision et NLP les plus courantes. Vous pouvez créer vos propres API pour d'autres tâches à l'aide de l'infrastructure de l'API de tâches.

prebuilt_task_apis
Figure 1. API de tâches prédéfinies

Créez votre propre API avec l'API de tâches ci-dessous

APIC++

Tous les détails de TFLite sont implémentés dans l'API native. Créez un objet API en utilisant l'une des fonctions d'usine et obtenez les résultats du modèle en appelant les fonctions définies dans l'interface.

Exemple d'utilisation

Voici un exemple utilisant le BertQuestionAnswerer C++ pour MobileBert .

  char kBertModelPath[] = "path/to/model.tflite";
  // Create the API from a model file
  std::unique_ptr<BertQuestionAnswerer> question_answerer =
      BertQuestionAnswerer::CreateFromFile(kBertModelPath);

  char kContext[] = ...; // context of a question to be answered
  char kQuestion[] = ...; // question to be answered
  // ask a question
  std::vector<QaAnswer> answers = question_answerer.Answer(kContext, kQuestion);
  // answers[0].text is the best answer

Construire l'API

native_task_api
Figure 2. API de tâches natives

Pour créer un objet API, vous devez fournir les informations suivantes en étendant BaseTaskApi

  • Déterminez les E/S de l'API : votre API doit exposer des entrées/sorties similaires sur différentes plates-formes. par exemple BertQuestionAnswerer prend deux chaînes (std::string& context, std::string& question) en entrée et génère un vecteur de réponses possibles et de probabilités sous la forme std::vector<QaAnswer> . Cela se fait en spécifiant les types correspondants dans le paramètre de modèle de BaseTaskApi . Avec les paramètres de modèle spécifiés, la fonction BaseTaskApi::Infer aura les types d'entrée/sortie corrects. Cette fonction peut être directement appelée par les clients API, mais c'est une bonne pratique de l'envelopper dans une fonction spécifique au modèle, dans ce cas, BertQuestionAnswerer::Answer .

    class BertQuestionAnswerer : public BaseTaskApi<
                                  std::vector<QaAnswer>, // OutputType
                                  const std::string&, const std::string& // InputTypes
                                  > {
      // Model specific function delegating calls to BaseTaskApi::Infer
      std::vector<QaAnswer> Answer(const std::string& context, const std::string& question) {
        return Infer(context, question).value();
      }
    }
    
  • Fournir une logique de conversion entre les E/S API et le tenseur d'entrée/sortie du modèle - Avec les types d'entrée et de sortie spécifiés, les sous-classes doivent également implémenter les fonctions typées BaseTaskApi::Preprocess et BaseTaskApi::Postprocess . Les deux fonctions fournissent des entrées et des sorties du TFLite FlatBuffer . La sous-classe est chargée d'attribuer les valeurs des E/S de l'API aux tenseurs d'E/S. Voir l'exemple d'implémentation complet dans BertQuestionAnswerer .

    class BertQuestionAnswerer : public BaseTaskApi<
                                  std::vector<QaAnswer>, // OutputType
                                  const std::string&, const std::string& // InputTypes
                                  > {
      // Convert API input into tensors
      absl::Status BertQuestionAnswerer::Preprocess(
        const std::vector<TfLiteTensor*>& input_tensors, // input tensors of the model
        const std::string& context, const std::string& query // InputType of the API
      ) {
        // Perform tokenization on input strings
        ...
        // Populate IDs, Masks and SegmentIDs to corresponding input tensors
        PopulateTensor(input_ids, input_tensors[0]);
        PopulateTensor(input_mask, input_tensors[1]);
        PopulateTensor(segment_ids, input_tensors[2]);
        return absl::OkStatus();
      }
    
      // Convert output tensors into API output
      StatusOr<std::vector<QaAnswer>> // OutputType
      BertQuestionAnswerer::Postprocess(
        const std::vector<const TfLiteTensor*>& output_tensors, // output tensors of the model
      ) {
        // Get start/end logits of prediction result from output tensors
        std::vector<float> end_logits;
        std::vector<float> start_logits;
        // output_tensors[0]: end_logits FLOAT[1, 384]
        PopulateVector(output_tensors[0], &end_logits);
        // output_tensors[1]: start_logits FLOAT[1, 384]
        PopulateVector(output_tensors[1], &start_logits);
        ...
        std::vector<QaAnswer::Pos> orig_results;
        // Look up the indices from vocabulary file and build results
        ...
        return orig_results;
      }
    }
    
  • Créer des fonctions d'usine de l'API - Un fichier modèle et un OpResolver sont nécessaires pour initialiser le tflite::Interpreter . TaskAPIFactory fournit des fonctions utilitaires pour créer des instances BaseTaskApi.

    Vous devez également fournir tous les fichiers associés au modèle. par exemple, BertQuestionAnswerer peut également avoir un fichier supplémentaire pour le vocabulaire de son tokenizer.

    class BertQuestionAnswerer : public BaseTaskApi<
                                  std::vector<QaAnswer>, // OutputType
                                  const std::string&, const std::string& // InputTypes
                                  > {
      // Factory function to create the API instance
      StatusOr<std::unique_ptr<QuestionAnswerer>>
      BertQuestionAnswerer::CreateBertQuestionAnswerer(
          const std::string& path_to_model, // model to passed to TaskApiFactory
          const std::string& path_to_vocab  // additional model specific files
      ) {
        // Creates an API object by calling one of the utils from TaskAPIFactory
        std::unique_ptr<BertQuestionAnswerer> api_to_init;
        ASSIGN_OR_RETURN(
            api_to_init,
            core::TaskAPIFactory::CreateFromFile<BertQuestionAnswerer>(
                path_to_model,
                absl::make_unique<tflite::ops::builtin::BuiltinOpResolver>(),
                kNumLiteThreads));
    
        // Perform additional model specific initializations
        // In this case building a vocabulary vector from the vocab file.
        api_to_init->InitializeVocab(path_to_vocab);
        return api_to_init;
      }
    }
    

API Android

Créez des API Android en définissant l'interface Java/Kotlin et en déléguant la logique à la couche C++ via JNI. L'API Android nécessite que l'API native soit d'abord créée.

Exemple d'utilisation

Voici un exemple utilisant Java BertQuestionAnswerer pour MobileBert .

  String BERT_MODEL_FILE = "path/to/model.tflite";
  String VOCAB_FILE = "path/to/vocab.txt";
  // Create the API from a model file and vocabulary file
    BertQuestionAnswerer bertQuestionAnswerer =
        BertQuestionAnswerer.createBertQuestionAnswerer(
            ApplicationProvider.getApplicationContext(), BERT_MODEL_FILE, VOCAB_FILE);

  String CONTEXT = ...; // context of a question to be answered
  String QUESTION = ...; // question to be answered
  // ask a question
  List<QaAnswer> answers = bertQuestionAnswerer.answer(CONTEXT, QUESTION);
  // answers.get(0).text is the best answer

Construire l'API

android_task_api
Figure 3. API de tâches Android

Semblable aux API natives, pour créer un objet API, le client doit fournir les informations suivantes en étendant BaseTaskApi , qui fournit des gestions JNI pour toutes les API de tâches Java.

  • Déterminer les E/S API : cela reflète généralement les interfaces natives. par exemple, BertQuestionAnswerer prend (String context, String question) comme entrée et sortie List<QaAnswer> . L'implémentation appelle une fonction native privée avec une signature similaire, sauf qu'elle possède un paramètre supplémentaire long nativeHandle , qui est le pointeur renvoyé par C++.

    class BertQuestionAnswerer extends BaseTaskApi {
      public List<QaAnswer> answer(String context, String question) {
        return answerNative(getNativeHandle(), context, question);
      }
    
      private static native List<QaAnswer> answerNative(
                                            long nativeHandle, // C++ pointer
                                            String context, String question // API I/O
                                           );
    
    }
    
  • Créer des fonctions d'usine de l'API - Cela reflète également les fonctions d'usine natives, sauf que les fonctions d'usine Android doivent également prendre en compte Context pour l'accès aux fichiers. L'implémentation appelle l'un des utilitaires de TaskJniUtils pour créer l'objet API C++ correspondant et transmettre son pointeur au constructeur BaseTaskApi .

      class BertQuestionAnswerer extends BaseTaskApi {
        private static final String BERT_QUESTION_ANSWERER_NATIVE_LIBNAME =
                                                  "bert_question_answerer_jni";
    
        // Extending super constructor by providing the
        // native handle(pointer of corresponding C++ API object)
        private BertQuestionAnswerer(long nativeHandle) {
          super(nativeHandle);
        }
    
        public static BertQuestionAnswerer createBertQuestionAnswerer(
                                            Context context, // Accessing Android files
                                            String pathToModel, String pathToVocab) {
          return new BertQuestionAnswerer(
              // The util first try loads the JNI module with name
              // BERT_QUESTION_ANSWERER_NATIVE_LIBNAME, then opens two files,
              // converts them into ByteBuffer, finally ::initJniWithBertByteBuffers
              // is called with the buffer for a C++ API object pointer
              TaskJniUtils.createHandleWithMultipleAssetFilesFromLibrary(
                  context,
                  BertQuestionAnswerer::initJniWithBertByteBuffers,
                  BERT_QUESTION_ANSWERER_NATIVE_LIBNAME,
                  pathToModel,
                  pathToVocab));
        }
    
        // modelBuffers[0] is tflite model file buffer, and modelBuffers[1] is vocab file buffer.
        // returns C++ API object pointer casted to long
        private static native long initJniWithBertByteBuffers(ByteBuffer... modelBuffers);
    
      }
    
  • Implémentez le module JNI pour les fonctions natives - Toutes les méthodes natives Java sont implémentées en appelant une fonction native correspondante à partir du module JNI. Les fonctions d'usine créeraient un objet API natif et renverraient son pointeur sous forme de type long à Java. Lors des appels ultérieurs à l'API Java, le pointeur de type long est renvoyé à JNI et renvoyé à l'objet API natif. Les résultats de l'API native sont ensuite reconvertis en résultats Java.

    Par exemple, c'est ainsi que bert_question_answerer_jni est implémenté.

      // Implements BertQuestionAnswerer::initJniWithBertByteBuffers
      extern "C" JNIEXPORT jlong JNICALL
      Java_org_tensorflow_lite_task_text_qa_BertQuestionAnswerer_initJniWithBertByteBuffers(
          JNIEnv* env, jclass thiz, jobjectArray model_buffers) {
        // Convert Java ByteBuffer object into a buffer that can be read by native factory functions
        absl::string_view model =
            GetMappedFileBuffer(env, env->GetObjectArrayElement(model_buffers, 0));
    
        // Creates the native API object
        absl::StatusOr<std::unique_ptr<QuestionAnswerer>> status =
            BertQuestionAnswerer::CreateFromBuffer(
                model.data(), model.size());
        if (status.ok()) {
          // converts the object pointer to jlong and return to Java.
          return reinterpret_cast<jlong>(status->release());
        } else {
          return kInvalidPointer;
        }
      }
    
      // Implements BertQuestionAnswerer::answerNative
      extern "C" JNIEXPORT jobject JNICALL
      Java_org_tensorflow_lite_task_text_qa_BertQuestionAnswerer_answerNative(
      JNIEnv* env, jclass thiz, jlong native_handle, jstring context, jstring question) {
      // Convert long to native API object pointer
      QuestionAnswerer* question_answerer = reinterpret_cast<QuestionAnswerer*>(native_handle);
    
      // Calls the native API
      std::vector<QaAnswer> results = question_answerer->Answer(JStringToString(env, context),
                                             JStringToString(env, question));
    
      // Converts native result(std::vector<QaAnswer>) to Java result(List<QaAnswerer>)
      jclass qa_answer_class =
        env->FindClass("org/tensorflow/lite/task/text/qa/QaAnswer");
      jmethodID qa_answer_ctor =
        env->GetMethodID(qa_answer_class, "<init>", "(Ljava/lang/String;IIF)V");
      return ConvertVectorToArrayList<QaAnswer>(
        env, results,
        [env, qa_answer_class, qa_answer_ctor](const QaAnswer& ans) {
          jstring text = env->NewStringUTF(ans.text.data());
          jobject qa_answer =
              env->NewObject(qa_answer_class, qa_answer_ctor, text, ans.pos.start,
                             ans.pos.end, ans.pos.logit);
          env->DeleteLocalRef(text);
          return qa_answer;
        });
      }
    
      // Implements BaseTaskApi::deinitJni by delete the native object
      extern "C" JNIEXPORT void JNICALL Java_task_core_BaseTaskApi_deinitJni(
          JNIEnv* env, jobject thiz, jlong native_handle) {
        delete reinterpret_cast<QuestionAnswerer*>(native_handle);
      }
    

API iOS

Créez des API iOS en encapsulant un objet API natif dans un objet API ObjC. L'objet API créé peut être utilisé dans ObjC ou Swift. L'API iOS nécessite que l'API native soit d'abord créée.

Exemple d'utilisation

Voici un exemple utilisant ObjC TFLBertQuestionAnswerer pour MobileBert dans Swift.

  static let mobileBertModelPath = "path/to/model.tflite";
  // Create the API from a model file and vocabulary file
  let mobileBertAnswerer = TFLBertQuestionAnswerer.mobilebertQuestionAnswerer(
      modelPath: mobileBertModelPath)

  static let context = ...; // context of a question to be answered
  static let question = ...; // question to be answered
  // ask a question
  let answers = mobileBertAnswerer.answer(
      context: TFLBertQuestionAnswererTest.context, question: TFLBertQuestionAnswererTest.question)
  // answers.[0].text is the best answer

Construire l'API

ios_task_api
Figure 4. API de tâches iOS

L'API iOS est un simple wrapper ObjC au-dessus de l'API native. Créez l'API en suivant les étapes ci-dessous :

  • Définir le wrapper ObjC - Définissez une classe ObjC et déléguez les implémentations à l'objet API natif correspondant. Notez que les dépendances natives ne peuvent apparaître que dans un fichier .mm en raison de l'incapacité de Swift à interopérer avec C++.

    • fichier .h
      @interface TFLBertQuestionAnswerer : NSObject
    
      // Delegate calls to the native BertQuestionAnswerer::CreateBertQuestionAnswerer
      + (instancetype)mobilebertQuestionAnswererWithModelPath:(NSString*)modelPath
                                                    vocabPath:(NSString*)vocabPath
          NS_SWIFT_NAME(mobilebertQuestionAnswerer(modelPath:vocabPath:));
    
      // Delegate calls to the native BertQuestionAnswerer::Answer
      - (NSArray<TFLQAAnswer*>*)answerWithContext:(NSString*)context
                                         question:(NSString*)question
          NS_SWIFT_NAME(answer(context:question:));
    }
    
    • fichier .mm
      using BertQuestionAnswererCPP = ::tflite::task::text::BertQuestionAnswerer;
    
      @implementation TFLBertQuestionAnswerer {
        // define an iVar for the native API object
        std::unique_ptr<QuestionAnswererCPP> _bertQuestionAnswerwer;
      }
    
      // Initialize the native API object
      + (instancetype)mobilebertQuestionAnswererWithModelPath:(NSString *)modelPath
                                              vocabPath:(NSString *)vocabPath {
        absl::StatusOr<std::unique_ptr<QuestionAnswererCPP>> cQuestionAnswerer =
            BertQuestionAnswererCPP::CreateBertQuestionAnswerer(MakeString(modelPath),
                                                                MakeString(vocabPath));
        _GTMDevAssert(cQuestionAnswerer.ok(), @"Failed to create BertQuestionAnswerer");
        return [[TFLBertQuestionAnswerer alloc]
            initWithQuestionAnswerer:std::move(cQuestionAnswerer.value())];
      }
    
      // Calls the native API and converts C++ results into ObjC results
      - (NSArray<TFLQAAnswer *> *)answerWithContext:(NSString *)context question:(NSString *)question {
        std::vector<QaAnswerCPP> results =
          _bertQuestionAnswerwer->Answer(MakeString(context), MakeString(question));
        return [self arrayFromVector:results];
      }
    }