Déployer un modèle et classifier du texte à l’aide de l’API de runtime

Article
12/19/2023

Dès que vous êtes satisfait des performances de votre modèle, vous pouvez le déployer et l’utiliser pour classifier du texte. Le déploiement d’un modèle le rend disponible pour une utilisation via l’API de prédiction.

Prérequis

Un projet de classification de texte personnalisée avec un compte Stockage Azure configuré
Des données texte qui ont été chargées sur votre compte de stockage
Des données étiquetées et un modèle correctement entraîné
Avoir passé en revue les détails de l’évaluation du modèle pour déterminer les performances de votre modèle

Pour plus d’informations, consultez le cycle de vie du développement de projets.

Déployer un modèle

Après avoir vérifié ses performances et conclu qu’il peut être exploité dans votre environnement, vous devez affecter votre modèle à un déploiement pour pouvoir l’interroger. L’affectation du modèle à un déploiement le rend disponible pour une utilisation via l’API de prédiction. Il est recommandé de créer un déploiement nommé production auquel vous attribuez le meilleur modèle que vous avez créé jusqu’à présent et de l’utiliser dans votre système. Vous pouvez créer un autre déploiement appelé staging auquel vous pouvez affecter le modèle sur lequel vous travaillez actuellement pour pouvoir le tester. Vous pouvez disposer d’un maximum de 10 déploiements dans votre projet.

Language Studio
API REST

Pour déployer votre modèle à partir de Language Studio :

Dans le menu de gauche, sélectionnez Déploiement d’un modèle.
Sélectionnez Ajouter un déploiement pour démarrer un nouveau travail de déploiement.
Sélectionnez Créer un déploiement pour créer un déploiement et attribuer un modèle entraîné dans la liste déroulante ci-dessous. Vous pouvez également Remplacer un déploiement existant en sélectionnant cette option et en sélectionnant le modèle entraîné que vous souhaitez attribuer dans la liste déroulante ci-dessous.

Notes

Le remplacement d’un déploiement existant ne nécessite pas de modifier votre appel de l’API de prédiction. Toutefois, les résultats obtenus sont basés sur le modèle qui vient d’être attribué.
Sélectionnez Déployer pour démarrer le travail de déploiement.
Une fois le déploiement réussi, une date d’expiration s’affiche à côté de celui-ci. L’expiration du déploiement est le moment où votre modèle déployé n’est pas disponible pour la prédiction, ce qui se produit généralement douze mois après l’expiration d’une configuration d’entraînement.

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é suivantes par vos valeurs :

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

Espace réservé	Valeur	Exemple
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	Nom de votre projet. Cette valeur respecte la casse.	`myProject`
`{DEPLOYMENT-NAME}`	Nom de votre déploiement. Cette valeur respecte la casse.	`staging`
`{API-VERSION}`	Version de l’API que vous appelez. La valeur référencée ici concerne la dernière version publiée. En savoir plus sur les autres versions d’API disponibles	`2022-05-01`

headers

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

Clé	Valeur
`Ocp-Apim-Subscription-Key`	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

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}"
}

Clé	Espace réservé	Valeur	Exemple
trainedModelLabel	`{MODEL-NAME}`	Nom du modèle qui est attribué à votre déploiement. Vous pouvez uniquement attribuer des modèles entraînés avec succès. Cette valeur respecte la casse.	`myModel`

Une fois que vous avez envoyé votre requête API, vous recevez une réponse 202 indiquant que le travail a été envoyé correctement. Dans les en-têtes de réponse, extrayez la valeur operation-location. Elle est au format suivant :

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

{JOB-ID} sert à identifier votre demande, 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 processus de déploiement de votre modèle. Vous pouvez utiliser l’URL que vous avez reçue à l’étape précédente ou remplacer les valeurs d’espace réservé ci-dessous par vos propres valeurs.

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

Espace réservé	Valeur	Exemple
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	Nom de votre projet. Cette valeur respecte la casse.	`myProject`
`{DEPLOYMENT-NAME}`	Nom de votre déploiement. Cette valeur respecte la casse.	`staging`
`{JOB-ID}`	ID de localisation de l’état d’entraînement de votre modèle. Il s’agit de la valeur d’en-tête `location` que vous avez reçue à l’étape précédente.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	Version de l’API que vous appelez. La valeur référencée ici concerne la dernière version publiée. En savoir plus sur les autres versions d’API disponibles	`2022-05-01`

headers

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

Clé	Valeur
`Ocp-Apim-Subscription-Key`	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Corps de la réponse

Une fois que vous avez envoyé la demande, 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"
}

Échanger les déploiements

Vous pouvez permuter des déploiements une fois que vous avez testé un modèle affecté à un déploiement et que vous souhaitez l’affecter à un autre. L’échange de déploiements implique de prendre le modèle affecté au premier déploiement et de l’affecter au deuxième déploiement. Ensuite, en prenant le modèle affecté au deuxième déploiement et en l’affectant au premier déploiement. Cela peut être utilisé pour permuter vos déploiements production et staging lorsque vous souhaitez prendre le modèle affecté à staging et l’affecter à production.

Language Studio
API REST

Pour permuter des déploiements à partir de Language Studio

Dans la page Déploiement d’un modèle, sélectionnez les deux déploiements que vous souhaitez échanger et sélectionnez Échanger les déploiements dans le menu supérieur.
Dans la fenêtre qui s’affiche, sélectionnez les noms des déploiements que vous souhaitez permuter.

Créez une requête POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour démarrer un travail de permutation de déploiements.

URL de la demande

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

Espace réservé	Valeur	Exemple
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	Nom de votre projet. Cette valeur respecte la casse.	`myProject`
`{API-VERSION}`	Version de l’API que vous appelez. La valeur référencée ici est la dernière version du modèle publiée.	`2022-05-01`

headers

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

Clé	Valeur
`Ocp-Apim-Subscription-Key`	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Corps de la demande

{
  "firstDeploymentName": "{FIRST-DEPLOYMENT-NAME}",
  "secondDeploymentName": "{SECOND-DEPLOYMENT-NAME}"
}

Clé	Espace réservé	Valeur	Exemple
firstDeploymentName	`{FIRST-DEPLOYMENT-NAME}`	Nom de votre premier déploiement. Cette valeur respecte la casse.	`production`
secondDeploymentName	`{SECOND-DEPLOYMENT-NAME}`	Nom de votre deuxième déploiement. Cette valeur respecte la casse.	`staging`

Une fois que vous avez envoyé votre demande d’API, vous recevez une réponse 202 indiquant la réussite.

Pour supprimer un déploiement depuis Language Studio, accédez à la page Déploiement d’un modèle. Sélectionnez le déploiement que vous souhaitez supprimer et sélectionnez Supprimer le déploiement dans le menu supérieur.

Créez une requête DELETE en utilisant l’URL, les en-têtes et le corps JSON suivants pour supprimer un déploiement.

URL de la demande

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

Espace réservé	Valeur	Exemple
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	Nom de votre projet. Cette valeur respecte la casse.	`myProject`
`{DEPLOYMENT-NAME}`	Nom de votre déploiement. Cette valeur respecte la casse.	`prod`
`{API-VERSION}`	Version de l’API que vous appelez. La valeur référencée ici concerne la dernière version publiée. En savoir plus sur les autres versions d’API disponibles	`2022-05-01`

headers

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

Clé	Valeur
`Ocp-Apim-Subscription-Key`	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

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

Affecter des ressources de déploiement

Vous pouvez déployer votre projet dans plusieurs régions en affectant différentes ressources Language qui existent dans différentes régions.

Language Studio
API REST

Pour affecter des ressources de déploiement dans d’autres régions dans Language Studio :

Veillez à vous attribuer le rôle de Propriétaire Language pour Cognitive Services dans la ressource que vous avez utilisée pour créer le projet.
Accédez à la page Déploiement d’un modèle dans Language Studio.
Sélectionnez l’onglet Régions.
Sélectionnez Ajouter une ressource de déploiement.
Sélectionnez une ressource Language dans une autre région.

Vous êtes maintenant prêt à déployer votre projet dans les régions où vous avez affecté des ressources.

L’attribution de ressources de déploiement par programme nécessite l’authentification Microsoft Entra. Microsoft Entra ID est utilisé pour confirmer que vous avez accès aux ressources que vous souhaitez attribuer à votre projet pour un déploiement multi-régional. Pour utiliser par programmation l'authentification Microsoft Entra lors des appels d'API REST, découvrez-en davantage dans la documentation des services Azure AI.

Affecter une ressource

Envoyez une requête POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour affecter les ressources de déploiement.

URL de la demande

Utilisez l’URL suivante quand vous créez votre demande d’API. Remplacez les valeurs d’espace réservé suivantes par vos valeurs :

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

Espace réservé	Valeur	Exemple
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	Nom de votre projet. Cette valeur respecte la casse.	`myProject`
`{API-VERSION}`	Version de l’API que vous appelez.	`2022-10-01-preview`

headers

Utilisez l'authentification Microsoft Entra pour authentifier cette API.

body

Utilisez l’exemple JSON suivant comme corps.

{
  "resourcesMetadata": [
    {
      "azureResourceId": "{AZURE-RESOURCE-ID}",
      "customDomain": "{CUSTOM-DOMAIN}",
      "region": "{REGION-CODE}"
    }
  ]
}

Clé	Espace réservé	Valeur	Exemple
`azureResourceId`	`{AZURE-RESOURCE-ID}`	Chemin complet de l’ID de ressource que vous souhaitez affecter. Trouvé dans le portail Azure sous l’onglet Propriétés de la ressource, dans le champ ID de ressource.	`/subscriptions/d73a1925-0000-0000-0000-0000c5fe888e/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource`
`customDomain`	`{CUSTOM-DOMAIN}`	Sous-domaine personnalisé de la ressource que vous souhaitez affecter. Trouvé dans le portail Azure sous l’onglet Clés et point de terminaison de la ressource, comme champ Point de terminaison dans l’URL `https://<your-custom-subdomain>.cognitiveservices.azure.com/`	`contosoresource`
`region`	`{REGION-CODE}`	Code de région spécifiant la région de la ressource que vous souhaitez affecter. Trouvé dans le portail Azure sous l’onglet Clés et point de terminaison de la ressource, dans le champ Localisation/région.	`eastus`

Obtenir l’état de l’affectation des ressources

Utilisez la requête GET suivante pour obtenir l’état de votre travail d’affecation de ressource de déploiement. Remplacez les valeurs d’espace réservé suivantes par vos valeurs :

URL de la demande

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

Espace réservé	Valeur	Exemple
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	Nom de votre projet. Cette valeur respecte la casse.	`myProject`
`{JOB-ID}`	ID de travail pour obtenir l’état de votre affectation de déploiement. Il se trouve dans la valeur d’en-tête `operation-location` que vous avez reçue de l’API en réponse à votre demande d’affectation de ressource de déploiement.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	Version de l’API que vous appelez.	`2022-10-01-preview`

headers

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

Clé	Valeur
`Ocp-Apim-Subscription-Key`	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Corps de la réponse

Une fois que vous avez envoyé la demande, vous recevez la réponse suivante. Continuez à interroger ce point de terminaison jusqu’à ce que le paramètre status passe à succeeded.

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

Désaffectation des ressources de déploiement

Lorsque vous désaffectez ou supprimez une ressource de déploiement d’un projet, vous supprimez également tous les déploiements déployés dans la région de cette ressource.

Language Studio
API REST

Pour désaffecter ou supprimer des ressources de déploiement dans d’autres régions en utilisant Language Studio :

Accédez à l’onglet Régions dans la page Déployer un modèle.
Sélectionnez la ressource que vous souhaitez désaffecter.
Sélectionnez le bouton Supprimer l’affectation.
Dans la fenêtre qui s’affiche, tapez le nom de la ressource que vous souhaitez supprimer.

Désaffecter la ressource

Envoyez une requête POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour désaffecter ou supprimer des ressources de déploiement de votre projet.

URL de la demande

Utilisez l’URL suivante quand vous créez votre demande d’API. Remplacez les valeurs d’espace réservé suivantes par vos valeurs :

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

Espace réservé	Valeur	Exemple
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	Nom de votre projet. Cette valeur respecte la casse.	`myProject`
`{API-VERSION}`	Version de l’API que vous appelez.	`2022-10-01-preview`

headers

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

Clé	Valeur
`Ocp-Apim-Subscription-Key`	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

body

Utilisez l’exemple JSON suivant comme corps.

{
  "assignedResourceIds": [
    "{AZURE-RESOURCE-ID}"
  ]
}

Clé	Espace réservé	Valeur	Exemple
`assignedResourceIds`	`{AZURE-RESOURCE-ID}`	Chemin complet de l’ID de ressource que vous souhaitez désaffecter. Trouvé dans le portail Azure sous l’onglet Propriétés de la ressource, dans le champ ID de ressource.	`/subscriptions/d73a1925-0000-0000-0000-0000c5fe888e/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource`

Obtenir l’état de la désaffectation des ressources

Utilisez la requête GET suivante pour obtenir l’état de votre travail de désaffecation de ressources de déploiement. Remplacez les valeurs d’espace réservé suivantes par vos valeurs :

URL de la demande

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

Espace réservé	Valeur	Exemple
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	Nom de votre projet. Cette valeur respecte la casse.	`myProject`
`{JOB-ID}`	ID de travail pour obtenir l’état de votre affectation de déploiement. Il se trouve dans la valeur d’en-tête `operation-location` que vous avez reçue de l’API en réponse à votre demande de désaffectation de ressource de déploiement.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	Version de l’API que vous appelez.	`2022-10-01-preview`

headers

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

Clé	Valeur
`Ocp-Apim-Subscription-Key`	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Corps de la réponse

Une fois que vous avez envoyé la demande, vous recevez la réponse suivante. Continuez à interroger ce point de terminaison jusqu’à ce que le paramètre status passe à « réussi ».

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

Étapes suivantes

Utiliser l’API de prédiction pour interroger votre modèle

Partager via

Déployer un modèle et classifier du texte à l’aide de l’API de runtime

Prérequis

Déployer un modèle

Envoyer un travail de déploiement

headers

Corps de la demande

Obtenir l’état du travail de déploiement

headers

Corps de la réponse

Échanger les déploiements

URL de la demande

headers

Corps de la demande

Supprimer un déploiement

URL de la demande

headers

Affecter des ressources de déploiement

Affecter une ressource

URL de la demande

headers

body

Obtenir l’état de l’affectation des ressources

URL de la demande

headers

Corps de la réponse

Désaffectation des ressources de déploiement

Désaffecter la ressource

URL de la demande

headers

body

Obtenir l’état de la désaffectation des ressources

URL de la demande

headers

Corps de la réponse

Étapes suivantes

Commentaires

Commentaires

Ressources supplémentaires