Guide pratique pour créer des projets dans un workflow d’orchestration

Un workflow d’orchestration vous permet de créer des projets qui connectent vos applications à :

• Compréhension du langage personnalisée
• Réponses aux questions
• LUIS

Prérequis

Avant de commencer à utiliser le workflow d’orchestration, vous avez besoin de plusieurs choses :

• Un abonnement Azure : créez-en un gratuitement.
• Ressource Azure AI Language

Créer une ressource de langue

Avant de commencer à utiliser le workflow d’orchestration, vous avez besoin d’une ressource Azure AI Language.

Remarque

• Vous devez avoir un rôle de propriétaire affecté sur le groupe de ressources pour créer une ressource de langue.
• Si vous envisagez d’utiliser les réponses aux questions, vous devez les activer lors de la création des ressources.

Créer une ressource à partir du portail Azure

1. Accédez au Portail Azure pour créer une ressource Azure AI Language.

2. Sélectionnez Continuer pour créer votre ressource

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

   Détails de l’instance	Valeur requise
   Région	Une des régions prises en charge.
   Nom	Nom de votre ressource de langue.
   Niveau tarifaire	Un des niveaux tarifaires pris en charge.

Créer une ressource de langue à partir de Language Studio

Si c’est votre première connexion, une fenêtre s’affiche dans Language Studio qui vous permet de choisir une ressource de langue existante ou d’en créer une. Vous pouvez aussi créer une ressource en cliquant sur l’icône Paramètres dans le coin supérieur droit, en sélectionnant Ressources, puis en cliquant sur Créer une ressource.

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

Détails de l’instance	Valeur requise
Abonnement Azure	votre abonnement Azure
Groupe de ressources Azure	Votre groupe de ressources Azure
Nom de la ressource Azure	Nom de votre ressource Azure
Emplacement	En savoir plus sur les régions prises en charge.
Niveau tarifaire	En savoir plus sur les niveaux tarifaires pris en charge.

Important

• Veillez à activer Identité managée quand vous créez une ressource de langue.
• Lire et accepter l’avis sur l’intelligence artificielle responsable

Connexion à Language Studio

Pour créer une nouvelle intention, sélectionnez le bouton +Ajouter, puis commencez par donner un nom à votre intention. Vous allez avoir deux possibilités : vous connecter à un projet ou non. Vous pouvez vous connecter à des projets (LUIS, réponses aux questions ou compréhension du langage courant) ou choisir l’option non.

Création d’un projet de flux de travail d’orchestration

Une fois que vous avez créé une ressource Language, créez un projet de workflow d’orchestration.

Language Studio

1. Dans Language Studio, recherchez la section intitulée Comprendre les questions et le langage courant, puis sélectionnez Flux de travail d’orchestration.

   

2. Cela vous conduit à la page Projet de flux de travail d’orchestration. Sélectionnez Create new project. Pour créer un projet, vous devez fournir les informations suivantes :

Valeur	Description
Nom	Nom de votre projet
Description	Description facultative du projet.
Langue principale des énoncés	Langue principale de votre projet. Vos données de formation doivent être principalement dans cette langue.

Une fois terminé, sélectionnez Suivant et passez en revue les détails. Sélectionnez Create project (Créer un projet) pour finaliser le processus. Vous devez maintenant voir l’écran Build Schema (Générer le schéma) dans votre projet.

API REST

Envoyez une requête PATCH en utilisant l’URL, les en-têtes et le corps JSON suivants pour créer un 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-conversations/projects/{PROJECT-NAME}?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.	2023-04-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.

body

Utilisez l’exemple JSON suivant comme corps.

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "Orchestration",
  "description": "Project description"
 }

Clé	Espace réservé	Valeur	Exemple
projectName	{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	EmailApp
language	{LANGUAGE-CODE}	Chaîne spécifiant le code de langue des énoncés utilisés dans votre projet. Si votre projet est multilingue, choisissez le code de langue de la majorité des énoncés.	en-us

Importer un projet de workflow d’orchestration

Language Studio

Vous pouvez à tout moment exporter un projet de workflow d’orchestration sous forme de fichier JSON en accédant à la page des projets de workflow d’orchestration, en sélectionnant un projet dans le menu supérieur, puis en cliquant sur Exporter.

Ce projet peut être réimporté comme nouveau projet. Si vous importez un projet portant exactement le même nom, les données du projet sont remplacées par les données du nouveau projet importé.

Pour importer un projet, sélectionnez le bouton fléché à côté de Créer un projet, puis sélectionnez Importer, puis ensuite le fichier JSON.

API REST

Vous pouvez importer un fichier JSON de workflow d’orchestration dans le service

Envoyez une requête POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour importer 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-conversations/projects/{PROJECT-NAME}/:import?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.	2023-04-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.

body

Notes

Chaque intention doit être d’un type uniquement (CLU, LUIS ou qna)

Utilisez l’exemple JSON suivant comme corps.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Orchestration",
    "settings": {
      "confidenceThreshold": 0
    },
    "projectName": "{PROJECT-NAME}",
    "description": "Project description",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Orchestration",
    "intents": [
      {
        "category": "string",
        "orchestration": {
          "kind": "luis",
          "luisOrchestration": {
            "appId": "00000000-0000-0000-0000-000000000000",
            "appVersion": "string",
            "slotName": "string"
          },
          "cluOrchestration": {
            "projectName": "string",
            "deploymentName": "string"
          },
          "qnaOrchestration": {
            "projectName": "string"
          }
        }
      }
    ],
    "utterances": [
      {
        "text": "Trying orchestration",
        "language": "{LANGUAGE-CODE}",
        "intent": "string"
      }
    ]
  }
}

Clé	Espace réservé	Valeur	Exemple
api-version	{API-VERSION}	Version de l’API que vous appelez. La version utilisée ici doit être la même version d’API dans l’URL.	2022-03-01-preview
projectName	{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	EmailApp
language	{LANGUAGE-CODE}	Chaîne spécifiant le code de langue des énoncés utilisés dans votre projet. Si votre projet est multilingue, choisissez le code de langue de la majorité des énoncés.	en-us

Exporter un projet

Language Studio

Vous pouvez à tout moment exporter un projet de workflow d’orchestration sous forme de fichier JSON en accédant à la page des projets de workflow d’orchestration, en sélectionnant un projet, puis en appuyant sur Exporter.

API REST

Vous pouvez à tout moment exporter un projet de workflow d’orchestration sous forme de fichier JSON.

Créez une demande POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour exporter 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-conversations/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&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.	EmailApp
{API-VERSION}	Version de l’API que vous appelez.	2023-04-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 demande d’API, vous recevez une réponse 202 indiquant la réussite. Dans les en-têtes de réponse, extrayez la valeur operation-location. Elle est au format suivant :

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

JOB-ID est utilisé pour identifier votre demande, car cette opération est asynchrone. Utilisez cette URL pour obtenir le JSON du projet exporté à l’aide de la même méthode d’authentification.

Obtenir les détails d’un projet d’orchestration

Language Studio

1. Accédez à la page des paramètres de votre projet dans Langage Studio.

2. Vous pouvez voir les détails du projet.

3. Dans cette page, vous pouvez mettre à jour la description du projet.

4. Vous pouvez également récupérer votre clé primaire de ressource à partir de cette page.

   

API REST

Pour obtenir les détails d’un projet de workflow d’orchestration, envoyez une requête GET en utilisant l’URL et les en-têtes suivants. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?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.	2023-04-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 obtenez la réponse suivante.

{
  "createdDateTime": "2022-04-18T13:53:03Z",
  "lastModifiedDateTime": "2022-04-18T13:53:03Z",
  "lastTrainedDateTime": "2022-04-18T14:14:28Z",
  "lastDeployedDateTime": "2022-04-18T14:49:01Z",
  "projectKind": "Orchestration",
  "projectName": "{PROJECT-NAME}",
  "description": "This is a sample orchestration project.",
  "language": "{LANGUAGE-CODE}"
}

Une fois que vous avez envoyé votre demande d’API, vous recevrez une réponse 200 confirmant la réussite et un corps de réponse JSON avec les détails de votre projet.

Supprimer le projet

Language Studio

Une fois que vous n’avez plus besoin de votre projet, vous pouvez le supprimer à l’aide de Language Studio. Sélectionnez Projets dans le menu de navigation de gauche, sélectionnez le projet que vous voulez supprimer, puis cliquez sur Supprimer dans le menu du haut.

API REST

Une fois que vous n’avez plus besoin de votre projet, vous pouvez le supprimer à l’aide des API.

Créez une requête DELETE en utilisant l’URL, les en-têtes et le corps JSON suivants pour supprimer un projet de compréhension du langage courant.

URL de la demande

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?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.	2023-04-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 recevez une réponse 202 indiquant la réussite, ce qui signifie que votre projet a été supprimé.

Étapes suivantes

Générer le schéma