Créer votre propre API Task

La bibliothèque de tâches TensorFlow Lite fournit des modèles API C++, Android et iOS sur la même infrastructure qui extrait TensorFlow. Vous pouvez étendre l'infrastructure de l'API Task pour créer des API personnalisées. si votre modèle n'est pas compatible avec les bibliothèques de tâches existantes.

Présentation

L'infrastructure de l'API Task a une structure à deux couches: la couche C++ inférieure encapsuler l'environnement d'exécution TFLite et la couche Java/ObjC supérieure communique avec la couche C++ via JNI ou wrapper.

Implémenter toute la logique TensorFlow uniquement en C++ permet de réduire les coûts, les performances d'inférence et simplifie le workflow global sur les plates-formes.

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

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

prebuilt_task_apis
Figure 1. API Tasks prédéfinies

Créer votre propre API avec l'infrastructure de l'API Task

API C++

Tous les détails de TFLite sont implémentés dans l'API C++. Créer un objet API à l'aide de l'une des fonctions de fabrique et obtenir les résultats du modèle en appelant des fonctions définies dans l'interface.

Exemple d'utilisation

Voici un exemple d'utilisation de la syntaxe C++ BertQuestionAnswerer 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

Créer l'API

native_task_api
Figure 2. API Native Task

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 présenter des entrées/sorties similaires. sur différentes plates-formes. Ex. : BertQuestionAnswerer accepte deux chaînes (std::string& context, std::string& question) en entrée et en sort une vecteur de réponse possible et de probabilités sous la forme std::vector<QaAnswer>. Ce est effectuée en spécifiant les types correspondants dans le bloc BaseTaskApi paramètre de modèle. Avec les paramètres de modèle spécifiés, BaseTaskApi::Infer aura les bons types d'entrées/sorties. Cette fonction peut être appelé directement par les clients API, mais il est recommandé de l'encapsuler 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 de l'API et le Tensor d'entrée/sortie du model : 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. Ces deux fonctions fournissent entrée et résultats depuis le FlatBuffer TFLite. La sous-classe est chargée d’attribuer des valeurs des Tensors d'E/S de l'API aux Tensors d'E/S. Voir l'implémentation complète exemple 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 de fabrique de l'API : un fichier de modèle et un OpResolver nécessaires pour initialiser 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. Ex. : BertQuestionAnswerer peut également avoir un fichier supplémentaire pour ses fonctions de tokenisation. vocabulaire.

    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éer des API Android en définissant une interface Java/Kotlin et en déléguant la logique à la couche C++ via JNI. L'API Android nécessite d'abord de créer une API native.

Exemple d'utilisation

Voici un exemple avec 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

Créer l'API

android_task_api
Figure 3. API Android Task

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

  • Déterminez les E/S de l'API : cette méthode met généralement en miroir les interfaces natives. Ex. : BertQuestionAnswerer utilise (String context, String question) en entrée et génère List<QaAnswer>. L'implémentation appelle une couche native privée avec une signature similaire, sauf qu'elle comporte 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 de fabrique de l'API : met également en miroir la fabrique native. fonctions, sauf que les fonctions d'usine Android doivent également prendre Context pour accéder aux fichiers. L'implémentation appelle l'un des utilitaires TaskJniUtils pour créer l'objet d'API C++ correspondant et transmettre son pointeur à 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émenter le module JNI pour les fonctions natives : toutes les méthodes natives Java sont implémentés en appelant une fonction native correspondante à partir du JNI de ce module. Les fonctions de fabrique créent un objet API natif et renvoient son pointeur en tant que type long vers Java. Dans les prochains appels à l'API Java, le long le pointeur de type est renvoyé à JNI et casté vers l'objet d'API natif. Les résultats de l'API native sont ensuite reconvertis en résultats Java.

    Par exemple, voici comment bert_question_answerer_jni est implémentée.

      // 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. La l'objet API créé peut être utilisé dans ObjC ou Swift. L'API iOS nécessite une API native à créer en premier.

Exemple d'utilisation

Voici un exemple d'utilisation d'ObjC : TFLBertQuestionAnswerer pour MobileBert en 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

Créer l'API

ios_task_api
Figure 4. API iOS Task

L'API iOS est un wrapper ObjC simple qui s'ajoute à l'API native. Créer l'API en procédant comme suit:

  • Définir le wrapper ObjC : définissez une classe ObjC et déléguez le à l'objet d'API natif correspondant. Notez que les dépendances ne peuvent apparaître que dans un fichier .mm en raison de l'incapacité de Swift à et l'interopérabilité 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];
      }
    }