Exemple : Créer une compétence personnalisée Form Recognizer (archivé)

Article
02/01/2023

Cet exemple est archivé et n’est pas pris en charge. Il explique comment créer une compétence personnalisée Form Recognizer à l’aide de C# et de Visual Studio.

Prérequis

Visual Studio (n’importe quelle édition).
Au moins cinq formulaires du même type. Vous pouvez utiliser les exemples de données fournis avec ce guide.

Créer une ressource Form Recognizer

Consultez Créer une ressource Form Recognizer

Entraîner votre modèle

Vous devez entraîner un modèle Form Recognizer avec vos formulaires d’entrée avant d’utiliser cette compétence. Utiliser Form Recognizer modèles explique comment entraîner un modèle. Vous pouvez utiliser des exemples de données ou fournir les vôtres.

Une fois le modèle entraîné, copiez sa valeur d’ID dans un emplacement sécurisé.

Configurer la compétence personnalisée

Ce tutoriel utilise le projet AnalyzeForm dans le dépôt GitHub Super compétences de la Recherche Azure. Clonez ce dépôt sur votre ordinateur local, puis naviguez vers Vision/AnalyzeForm/ pour accéder au projet. Ouvrez ensuite AnalyzeForm.csproj dans Visual Studio. Ce projet crée une ressource Azure Function qui satisfait l’interface de compétence personnalisée et qui peut être utilisée pour l’enrichissement de la Recherche cognitive Azure. Il prend des documents de formulaire comme entrées et génère (sous forme de texte) les paires clé/valeur que vous spécifiez.

Tout d’abord, ajoutez des variables d’environnement au niveau du projet. Localisez le projet AnalyzeForm dans le volet gauche, cliquez dessus avec le bouton droit, puis sélectionnez Propriétés. Dans la fenêtre Propriétés , sélectionnez l’onglet Déboguer , puis recherchez le champ Variables d’environnement . Sélectionnez Ajouter pour ajouter les variables suivantes :

FORMS_RECOGNIZER_ENDPOINT_URL avec la valeur définie sur l’URL de votre point de terminaison.
FORMS_RECOGNIZER_API_KEY avec la valeur définie sur votre clé d’abonnement.
FORMS_RECOGNIZER_MODEL_ID avec la valeur définie sur l’ID du modèle que vous avez entraîné.
FORMS_RECOGNIZER_RETRY_DELAY avec la valeur définie sur 1000. Cette valeur est le temps, en millisecondes, pendant lequel le programme attend avant de retenter la requête.
FORMS_RECOGNIZER_MAX_ATTEMPTS avec la valeur définie sur 100. Cette valeur est le nombre de fois où le programme interroge le service en tentant d’obtenir une réponse correcte.

Ensuite, ouvrez AnalyzeForm.cs, puis recherchez la variable fieldMappings, qui fait référence au fichier field-mappings.json. Ce fichier (et la variable qui y fait référence) définissent la liste des clés que vous voulez extraire de vos formulaires et une étiquette personnalisée pour chaque clé. Par exemple, la valeur { "Address:", "address" }, { "Invoice For:", "recipient" } signifie que le script enregistre uniquement les valeurs définies pour les champs Address: et Invoice For: détectés, et qu’il étiquette ces valeurs avec "address" et "recipient", respectivement.

Enfin, notez la variable contentType. Ce script exécute le modèle Form Recognizer donné sur des documents distants qui sont référencés par URL, de sorte que le type de contenu est application/json. Si vous voulez analyser des fichiers locaux en incluant leurs flux d’octets dans les requêtes HTTP, vous devez remplacer le contentType par le type MIME approprié pour votre fichier.

Tester la fonction à partir de Visual Studio

Une fois que vous avez modifié votre projet, enregistrez-le et définissez le projet AnalyzeForm comme projet de démarrage dans Visual Studio (s’il n’est pas déjà défini). Appuyez ensuite sur F5 pour exécuter la fonction dans votre environnement local. Utilisez un service REST comme Postman pour appeler la fonction.

Demande HTTP

Vous allez effectuer la requête suivante pour appeler la fonction.

POST http://localhost:7071/api/analyze-form

Corps de la demande

Commencez par le modèle de corps de la demande

{
    "values": [
        {
            "recordId": "record1",
            "data": { 
                "formUrl": "<your-form-url>",
                "formSasToken": "<your-sas-token>"
            }
        }
    ]
}

Ici, vous devez fournir l’URL d’un formulaire qui a le même type que les formulaires avec lesquels vous avez effectué l’entraînement. À des fins de test, vous pouvez utiliser l’un de vos formulaires d’entraînement. Si vous avez suivi le guide de démarrage rapide cURL, vos formulaires se trouvent dans un compte de stockage d’objets Blob Azure. Ouvrez l’Explorateur Stockage Azure, localisez un fichier de formulaire, cliquez dessus avec le bouton droit, puis sélectionnez Obtenir une signature d’accès partagé. La fenêtre de boîte de dialogue suivante fournit une URL et un jeton SAS. Entrez ces chaînes dans les champs "formUrl" et "formSasToken" du corps de votre demande, respectivement.

Si vous voulez analyser un document distant qui ne se trouve pas dans le stockage d’objets Blob Azure, collez son URL dans le champ "formUrl" et laissez le champ "formSasToken" vide.

Notes

Quand la compétence est intégrée dans un ensemble de compétences, l’URL et le jeton sont fournis par la Recherche cognitive.

response

Vous devriez voir une réponse similaire à l’exemple suivant :

{
    "values": [
        {
            "recordId": "record1",
            "data": {
                "address": "1111 8th st. Bellevue, WA 99501 ",
                "recipient": "Southridge Video 1060 Main St. Atlanta, GA 65024 "
            },
            "errors": null,
            "warnings": null
        }
    ]
}

Publier la fonction sur Azure

Lorsque vous êtes satisfait du comportement de la fonction, vous pouvez la publier.

Dans l’Explorateur de solutions dans Visual Studio, cliquez avec le bouton droit sur le projet, puis sélectionnez Publier. Choisissez Créer>Publier.
Si vous n’avez pas encore connecté Visual Studio à votre compte Azure, sélectionnez Ajouter un compte... .
Suivez les invitations qui s’affichent à l’écran. Spécifiez un nom unique pour votre service d’application, l’abonnement Azure, le groupe de ressources, le plan d’hébergement et le compte de stockage que vous voulez utiliser. Si vous n’avez pas encore de groupe de ressources, de plan d’hébergement et de compte de stockage, vous pouvez les créer. Quand vous avez terminé, sélectionnez Créer.
Une fois le déploiement terminé, notez l’URL du site. Cette URL est l’adresse de votre application de fonction dans Azure. Enregistrez-la dans un emplacement temporaire.
Dans le portail Azure, accédez au groupe de ressources, puis recherchez la fonction AnalyzeForm que vous avez publiée. Dans la section Gérer, vous devriez voir Host Keys. Copiez la clé d’hôte par défaut, puis enregistrez-la dans un emplacement temporaire.

Connexion à votre pipeline

Pour utiliser cette compétence dans un pipeline de Recherche cognitive, vous devez ajouter une définition de compétence à votre ensemble de compétences. Le bloc JSON suivant est un exemple de définition de compétence (vous devez mettre à jour les entrées et les sorties pour refléter l’environnement de votre scénario et votre ensemble de compétences spécifiques). Remplacez AzureFunctionEndpointUrl par votre URL de fonction, puis remplacez AzureFunctionDefaultHostKey par votre clé d’hôte.

{ 
  "description":"Skillset that invokes the Form Recognizer custom skill",
  "skills":[ 
    "[... your existing skills go here]",
    { 
      "@odata.type":"#Microsoft.Skills.Custom.WebApiSkill",
      "name":"formrecognizer",
      "description":"Extracts fields from a form using a pre-trained form recognition model",
      "uri":"[AzureFunctionEndpointUrl]/api/analyze-form?code=[AzureFunctionDefaultHostKey]",
      "httpMethod":"POST",
      "timeout":"PT30S",
      "context":"/document",
      "batchSize":1,
      "inputs":[ 
        { 
          "name":"formUrl",
          "source":"/document/metadata_storage_path"
        },
        { 
          "name":"formSasToken",
          "source":"/document/metadata_storage_sas_token"
        }
      ],
      "outputs":[ 
        { 
          "name":"address",
          "targetName":"address"
        },
        { 
          "name":"recipient",
          "targetName":"recipient"
        }
      ]
    }
  ]
}

Partager via