Démarrage rapide : API REST de classification de texte personnalisée

Utilisez cet article pour commencer à créer un projet de classification de texte personnalisée dans lequel vous pouvez effectuer l’apprentissage de modèles personnalisés pour la classification de texte. Un modèle est un logiciel IA entraîné pour effectuer une certaine tâche. Pour ce système, les modèles classifient le texte et sont entraînés en apprenant à partir de données balisées.

La classification de texte personnalisée prend en charge deux types de projets :

• Classification avec une seule étiquette : vous pouvez attribuer une seule classe à chaque document de votre jeu de données. Par exemple, un script de film ne peut être classé que comme « Romance » ou « Comédie ».
• Classification avec plusieurs étiquettes : vous pouvez attribuer plusieurs classes à chaque document de votre jeu de données. Par exemple, un script de film peut être classé comme « Comédie » ou « Romance » et « Comédie ».

Dans ce guide de démarrage rapide, vous pouvez utiliser les exemples de jeux de données fournis pour créer une classification multi-étiquette pour classer les scripts vidéo en une ou plusieurs catégories. Vous pouvez également utiliser un jeu de données de classification d’étiquette unique pour classifier des résumés d’articles scientifiques dans l’un des domaines définis.

Prérequis

• Abonnement Azure : créez-en un gratuitement.

Créer une nouvelle langue Azure dans la ressource Foundry Tools et le compte de stockage Azure

Avant de pouvoir utiliser la classification de texte personnalisée, vous devez créer une ressource language, ce qui vous donnera les informations d’identification nécessaires pour créer un projet et commencer à entraîner un modèle. Vous aurez également besoin d’un compte de stockage Azure, où vous pouvez charger votre jeu de données utilisé pour créer votre modèle.

Créer une ressource à partir du portail Azure

1. Accédez au portail Azure pour créer une nouvelle ressource Azure Language in Foundry Tools.

2. Dans la fenêtre qui s’affiche, sélectionnez Classification de texte personnalisée et reconnaissance d’entités nommées personnalisées dans les fonctionnalités personnalisées. Sélectionnez Continuer pour créer votre ressource en bas de l’écran.

   

3. Créez une ressource de langue avec les détails suivants.

   Nom	Valeur requise
   Abonnement	Votre abonnement Azure.
   groupe de ressources	Un groupe de ressources comprenant votre ressource. Vous pouvez utiliser un groupe de resources existant ou en créer un.
   Région	Une des régions prises en charge. Par exemple, « USA Ouest 2 ».
   Nom	Nom de votre ressource.
   Niveau tarifaire	Un des niveaux tarifaires pris en charge. Vous pouvez utiliser le niveau tarifaire gratuit (F0) pour tester le service.

   Si vous recevez un message indiquant « votre compte de connexion n’est pas propriétaire du groupe de ressources du compte de stockage sélectionné », votre compte doit avoir un rôle de propriétaire affecté sur le groupe de ressources avant de pouvoir créer une ressource Language. Pour obtenir de l’aide, contactez le propriétaire de votre abonnement Azure.

   Vous pouvez déterminer le propriétaire de votre abonnement Azure en recherchant votre groupe de ressources et en suivant le lien vers l’abonnement associé. Ensuite :

   1. Sélectionnez l’onglet Contrôle d’accès (IAM).
   2. Sélectionnez Attributions de rôle.
   3. Filtrez par Rôle : Propriétaire.

4. Dans la section Classification de texte personnalisée et reconnaissance d’entités nommées personnalisées, sélectionnez un compte de stockage existant ou Nouveau compte de stockage. Notez que ces valeurs vous aident dans le cadre d’un démarrage rapide. Il ne s’agit pas des valeurs du compte de stockage à utiliser dans les environnements de production. Pour éviter la latence lors de la création de votre projet, connectez-vous à des comptes de stockage dans la même région que votre ressource de langue.

   Valeur du compte de stockage	Valeur recommandée
   Nom du compte de stockage	Nom quelconque
   Type de compte de stockage	LRS standard

5. Vérifiez que l’Avis d’IA responsable est coché. Au bas de la page, sélectionnez Examiner et créer.

Charger les exemples de données dans un conteneur d’objets blob

Après avoir créé un compte de stockage Azure et l’avoir connecté à votre ressource de langue, vous devez charger les documents à partir de l’exemple de jeu de données dans le répertoire racine de votre conteneur. Ces documents sont utilisés pour entraîner votre modèle.

Portail Azure

1. Dans le portail Azure, accédez au compte de stockage que vous avez créé, puis sélectionnez-le en sélectionnant comptes de stockage et en tapant le nom de votre compte de stockage dans Filtrer pour n’importe quel champ.

   Si votre groupe de ressources n'apparaît pas, assurez-vous que le filtre Abonnement égal à est défini sur Tous.

2. Dans votre compte de stockage, sélectionnez Conteneurs dans le menu de gauche, situé sous Stockage de données. Dans l’écran qui s’affiche, sélectionnez + Conteneur. Donnez au conteneur le nom exemple de données et laissez le Niveau d’accès public par défaut.

   

3. Une fois votre conteneur créé, sélectionnez-le. Sélectionnez ensuite le bouton Charger pour sélectionner les fichiers .txt et .json que vous avez téléchargés précédemment.

   

Récupération des clés et du point de terminaison de la ressource

• Accédez à la page de vue d’ensemble de votre ressource dans le portail Azure

• Dans le menu de gauche, sélectionnez Clés et point de terminaison. Le point de terminaison et la clé sont utilisés pour les demandes d’API.

Créer un projet de classification de texte personnalisée

Une fois votre ressource et votre conteneur de stockage configurés, créez un projet de classification de texte personnalisée. Un projet est une zone de travail qui vous permet de créer des modèles ML personnalisés en fonction de vos données. Votre projet est accessible uniquement par vous et d’autres utilisateurs qui ont accès à la ressource de langue Azure utilisée.

Déclencher un travail d’importation de projet

Soumettez une demande POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour importer votre fichier d’étiquettes. Vérifiez que votre fichier d’étiquettes respecte le format accepté.

Si un projet portant le même nom existe déjà, les données de ce projet sont remplacées.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

body

Utilisez le code JSON suivant dans votre demande. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customMultiLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customMultiLabelClassification",
    "classes": [
      {
        "category": "Class1"
      },
      {
        "category": "Class2"
      }
    ],
    "documents": [
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class1"
          },
          {
            "category": "Class2"
          }
        ]
      },
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class2"
          }
        ]
      }
    ]
  }
}

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customSingleLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customSingleLabelClassification",
        "classes": [
            {
                "category": "Class1"
            },
            {
                "category": "Class2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class2"
                }
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class1"
                }
            }
        ]
    }
}

Une fois que vous avez envoyé votre demande d’API, vous recevez une 202 réponse indiquant que le travail a été envoyé correctement. Dans les en-têtes de réponse, extrayez la valeur operation-location formatée comme suit :

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} sert à identifier votre demande, car cette opération est asynchrone. Vous utilisez cette URL pour obtenir l’état de la tâche d’importation.

Scénarios d’erreur possibles pour cette requête :

• La ressource sélectionnée n’a pas les autorisations appropriées pour le compte de stockage.
• Le storageInputContainerName spécifié n’existe pas.
• Le code de langue utilisé est non valide ou si le type de code de langue n’est pas une chaîne.
• La valeur multilingual est une chaîne et non pas une valeur booléenne.

Obtient l’état du travail d’importation

Utilisez la requête GET suivante pour obtenir l’état de votre projet d’importation. Remplacez les valeurs d’espace réservé par vos propres valeurs.

URL de la demande

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Entraîner votre modèle

En règle générale, après avoir créé un projet, vous commencez à ajouter des étiquettes aux documents qui se trouvent dans le conteneur connecté à votre projet. Pour ce guide de démarrage rapide, vous avez importé un exemple de jeu de données étiqueté et initialisé votre projet avec l’exemple de fichier de balises JSON.

Lancement de l’apprentissage du modèle

Une fois votre projet importé, vous pouvez commencer l’apprentissage de votre modèle.

Envoyez une requête POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour envoyer un travail d’apprentissage. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Corps de la demande

Utilisez le code JSON suivant dans le corps de la demande. Le modèle reçoit le {MODEL-NAME} une fois l’apprentissage effectué. Seuls les travaux d’apprentissage réussis produisent des modèles.

{
	"modelLabel": "{MODEL-NAME}",
	"trainingConfigVersion": "{CONFIG-VERSION}",
	"evaluationOptions": {
		"kind": "percentage",
		"trainingSplitPercentage": 80,
		"testingSplitPercentage": 20
	}
}

Une fois que vous avez envoyé votre demande d’API, vous recevez une 202 réponse indiquant que le travail a été envoyé correctement. Dans les en-têtes de réponse, extrayez la valeur location formatée comme suit :

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} sert à identifier votre requête, car cette opération est asynchrone. Vous pouvez utiliser cette URL pour obtenir l’état de la formation.

Obtenir l’état des travaux d’apprentissage

La formation peut prendre entre 10 et 30 minutes. Vous pouvez utiliser la requête suivante pour continuer à interroger l’état du travail d’apprentissage jusqu’à ce qu’il soit effectué avec succès.

Utilisez la requête GET suivante pour obtenir l’état de progression du processus d’apprentissage de votre modèle. Remplacez les valeurs d’espace réservé par vos propres valeurs.

URL de la demande

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Corps de la réponse

Une fois la requête envoyée, vous recevez la réponse suivante.

{
  "result": {
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2022-04-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "{JOB-ID}",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

Déployer votre modèle

En règle générale, après l’entraînement d’un modèle, vous passez en revue les détails de l’évaluation et vous apportez des améliorations si nécessaire. Dans ce guide de démarrage rapide, vous allez simplement déployer votre modèle et le rendre disponible pour pouvoir l’essayer dans Language Studio. Vous pouvez également appeler l’API de prévision.

Envoyer un travail de déploiement

Envoyez une requête PUT en utilisant l’URL, les en-têtes et le corps JSON suivants pour envoyer un travail de déploiement. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Corps de la demande

Utilisez le code JSON suivant dans le corps de la demande. Utilisez le nom du modèle que vous attribuez au déploiement.

{
  "trainedModelLabel": "{MODEL-NAME}"
}

Une fois que vous avez envoyé votre demande d’API, vous recevez une 202 réponse indiquant que le travail a été envoyé correctement. Dans les en-têtes de réponse, extrayez la valeur operation-location formatée comme suit :

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} sert à identifier votre requête, car cette opération est asynchrone. Vous pouvez utiliser cette URL pour obtenir l’état du déploiement.

Obtenir l’état du travail de déploiement

Utilisez la requête GET suivante pour interroger l’état du travail de déploiement. Vous pouvez vous servir de l’URL reçue à l’étape précédente ou remplacer les valeurs d’espace réservé par les vôtres.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Corps de la réponse

Une fois la requête envoyée, vous recevez la réponse suivante. Continuez à interroger ce point de terminaison jusqu’à ce que le paramètre status passe à « réussi ». Vous devez normalement obtenir un code 200 pour indiquer la réussite de la demande.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Classifier le texte

Une fois votre modèle déployé avec succès, vous pouvez commencer à l’utiliser pour classifier votre texte via l’API de prédiction. Dans l’exemple de jeu de données que vous avez téléchargé précédemment, vous trouverez des documents de test que vous pouvez utiliser dans cette étape.

Envoyer une tâche de classification de texte personnalisée

Utilisez cette requête POST pour démarrer une tâche de classification de texte.

{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}

headers

body

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomMultiLabelClassification",
      "taskName": "Multi Label Classification",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomSingleLabelClassification",
      "taskName": "Single Classification Label",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

response

Vous recevez une réponse 202 indiquant la réussite. Dans les en-têtes de réponse, extrayez operation-location. operation-location est au format suivant :

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

Vous pouvez utiliser cette URL pour interroger l’état d’achèvement de la tâche et obtenir les résultats une fois la tâche terminée.

Obtenir les résultats de la tâche

Utilisez la requête GET suivante pour interroger l’état/les résultats de la tâche de classification de texte.

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

headers

Corps de réponse

La réponse est un document JSON avec les paramètres suivants.

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customMultiClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "classes": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customSingleClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "class": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

Nettoyer les ressources

Quand vous n’avez plus besoin de votre projet, vous pouvez le supprimer avec la demande DELETE suivante. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Une fois que vous avez envoyé votre demande d’API, vous recevez une 202 réponse indiquant la réussite, ce qui signifie que votre projet est supprimé. Un appel réussi donne un en-tête Operation-Location utilisé pour vérifier l’état du travail.

Étapes suivantes

Après avoir créé un modèle de classification de texte personnalisé, vous pouvez :

• Utiliser l’API du runtime pour classifier le texte

Quand vous commencez à créer vos propres projets de classification de texte personnalisée, utilisez les guides pratiques pour en savoir plus sur le développement de votre modèle plus en détail :

• Sélection de données et conception de schéma
• Données de balise
• Entraîner un modèle
• Afficher l’évaluation du modèle