Démarrage rapide : Bibliothèque de client QnA Maker

Remarque

Azure Open AI On Your Data utilise des modèles de langage étendus (LLM) pour produire des résultats similaires à ceux de QnA Maker. Si vous souhaitez migrer votre projet QnA Maker vers Azure Open AI sur vos données, veuillez consulter notre guide.

Démarrez avec la bibliothèque de client QnA Maker. Suivez les étapes suivantes pour installer le package et essayer l’exemple de code pour les tâches de base.

Notes

Le service QnA Maker sera mis hors service le 31 mars 2025. Une version plus récente de la fonctionnalité de questions et réponses est désormais disponible dans le cadre d’Azure AI Language. Pour obtenir des réponses aux questions au sein du service de langage, consultez Réponses aux questions. À partir du 1er octobre 2022 vous ne pourrez plus créer de nouvelles ressources QnA Maker. Pour plus d’informations sur la migration de bases de connaissances QnA Maker existantes vers Réponses aux questions, consultez le Guide de migration.

Prérequis

Notes

Cette documentation ne s’applique pas à la dernière version. Pour en savoir plus sur l’utilisation de l’API REST avec la dernière version, consultez le démarrage rapide de l’API REST de réponse aux questions

• Version actuelle de cURL. Plusieurs commutateurs de ligne de commande sont utilisés dans les guides de démarrage rapide, qui sont indiqués dans la documentation cURL.

• Pour utiliser la clé et le nom de la ressource, vous devez disposer d’une ressource QnA Maker. Vous avez entré le Nom de la ressource lors de la création de la ressource, puis la clé a été créée pour vous. Le nom de la ressource est utilisé en tant que sous-domaine pour votre point de terminaison. Pour récupérer votre clé et le nom de votre ressource, sélectionnez Démarrage rapide pour votre ressource dans le portail Azure. Le nom de la ressource constitue le premier sous-domaine de l’URL du point de terminaison :

  https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0

Attention

Les exemples BASH suivants utilisent le caractère de continuation de ligne \. Si votre console ou terminal utilise un caractère de continuation de ligne différent, utilisez ce caractère.

Créer une base de connaissances

Pour créer une base de connaissances avec les API REST et cURL, vous devez disposer des informations suivantes :

Information	Configuration cURL	Objectif
Nom de la ressource QnA Maker	URL	Utilisé pour construire l’URL
Clé de la ressource QnA Maker	Param -h pour l’en-tête Ocp-Apim-Subscription-Key	S’authentifier auprès du service QnA Maker
JSON décrivant la base de connaissances	Param -d	Exemples de JSON
Taille du JSON en octets	Param -h pour l’en-tête Content-Size

La commande cURL est exécutée à partir d’un interpréteur de commandes BASH. Modifiez cette commande avec vos propres informations relatives au nom de ressource, à la clé de ressource ainsi qu’aux valeurs JSON et à la taille de JSON.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/create \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:107" \
-d '{ name: "QnA Maker FAQ",urls: [ "https://learn.microsoft.com/azure/ai-services/qnamaker/faqs"]}'

La réponse cURL de QnA Maker comprend operationId, qui est requis pour obtenir l’état de l’opération.

{
  "operationState": "NotStarted",
  "createdTimestamp": "2020-02-27T04:11:22Z",
  "lastActionTimestamp": "2020-02-27T04:11:22Z",
  "userId": "9596077b3e0441eb93d5080d6a15c64b",
  "operationId": "95a4f700-9899-4c98-bda8-5449af9faef8"
}

Obtenir l’état de l’opération

Quand vous créez une base de connaissances, comme l’opération est asynchrone, la réponse contient des informations pour déterminer l’état.

Information	Configuration cURL	Objectif
Nom de la ressource QnA Maker	URL	Utilisé pour construire l’URL
ID d’opération	Itinéraire d’URL	/operations/REPLACE-WITH-YOUR-OPERATION-ID
Clé de la ressource QnA Maker	Param -h pour l’en-tête Ocp-Apim-Subscription-Key	S’authentifier auprès du service QnA Maker

La commande cURL est exécutée à partir d’un interpréteur de commandes BASH. Modifiez cette commande avec vos propres informations relatives au nom de ressource, à la clé de ressource et à l’ID d’opération.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/operations/REPLACE-WITH-YOUR-OPERATION-ID \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

La réponse cURL comprend l’état. Si l’état de l’opération est Réussi, resourceLocation contient l’ID de la base de connaissances.

{
   "operationState": "Succeeded",
   "createdTimestamp": "2020-02-27T04:54:07Z",
   "lastActionTimestamp": "2020-02-27T04:54:19Z",
   "resourceLocation": "/knowledgebases/fe3971b7-cfaa-41fa-8d9f-6ceb673eb865",
   "userId": "f596077b3e0441eb93d5080d6a15c64b",
   "operationId": "f293f218-d080-48f0-a766-47993e9b26a8"
}

Publier une base de connaissances

Avant d’interroger la base de connaissances, vous devez :

• Publier une base de connaissances
• Obtenir la clé de point de terminaison du runtime

Cette tâche permet de publier la base de connaissances. L’obtention de la clé de point de terminaison du runtime est une tâche distincte.

Information	Configuration cURL	Objectif
Nom de la ressource QnA Maker	URL	Utilisé pour construire l’URL
Clé de la ressource QnA Maker	Param -h pour l’en-tête Ocp-Apim-Subscription-Key	S’authentifier auprès du service QnA Maker
ID de la base de connaissances	Itinéraire d’URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

La commande cURL est exécutée à partir d’un interpréteur de commandes BASH. Modifiez cette commande avec vos propres informations relatives au nom de ressource, à la clé de ressource et à l’ID de la base de connaissances.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-v \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
--data-raw ''

L’état de la réponse est 204 sans résultats. Utilisez le paramètre de ligne de commande -v pour afficher la sortie détaillée de la commande cURL. Cela inclut l’état HTTP.

Obtenir la clé de point de terminaison du runtime de la base de connaissances publiée

Avant d’interroger la base de connaissances, vous devez :

• Publier une base de connaissances
• Obtenir la clé de point de terminaison du runtime

Cette tâche permet d’obtenir la clé de point de terminaison du runtime. La publication de la base de connaissances est une tâche distincte.

La clé de point de terminaison du runtime est la même clé pour toutes les bases de connaissances utilisant la ressource QnA Maker.

Information	Configuration cURL	Objectif
Nom de la ressource QnA Maker	URL	Utilisé pour construire l’URL
Clé de la ressource QnA Maker	Param -h pour l’en-tête Ocp-Apim-Subscription-Key	S’authentifier auprès du service QnA Maker

La commande cURL est exécutée à partir d’un interpréteur de commandes BASH. Modifiez cette commande avec vos propres informations relatives au nom de ressource et à la clé de ressource.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/endpointkeys \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

La réponse cURL comprend les clés de point de terminaison du runtime. Utilisez une seule des clés lors de l’interrogation pour obtenir une réponse de la base de connaissances.

{
  "primaryEndpointKey": "93e88a14-694a-44d5-883b-184a68aa8530",
  "secondaryEndpointKey": "92c98c16-ca31-4294-8626-6c57454a5063",
  "installedVersion": "4.0.5",
  "lastStableVersion": "4.0.6"
}

Requête relative à une réponse de la base de connaissances publiée

L’obtention d’une réponse de la base de connaissances se déroule à partir d’un runtime distinct de la gestion de la base de connaissances. Étant donné qu’il s’agit d’un runtime distinct, vous devez vous authentifier à l’aide d’une clé de runtime.

Information	Configuration cURL	Objectif
Nom de la ressource QnA Maker	URL	Utilisé pour construire l’URL
Clé de runtime QnA Maker	Param -h pour l’en-tête Authorization	La clé fait partie d’une chaîne qui comprend le mot Endpointkey . S’authentifier auprès du service QnA Maker
ID de la base de connaissances	Itinéraire d’URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
JSON décrivant la requête	Param -d	Paramètres du corps de la demande et exemples de JSON
Taille du JSON en octets	Param -h pour l’en-tête Content-Size

La commande cURL est exécutée à partir d’un interpréteur de commandes BASH. Modifiez cette commande avec vos propres informations relatives au nom de ressource, à la clé de ressource et à l’ID de la base de connaissances.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.azurewebsites.net/qnamaker/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID/generateAnswer \
-X POST \
-H "Authorization: EndpointKey REPLACE-WITH-YOUR-RUNTIME-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:159" \
-d '{"question": "How are QnA Maker and LUIS used together?","top": 6,"isTest": true,  "scoreThreshold": 20, "strictFilters": [], "userId": "sd53lsY="}'

Une réponse correcte comprend la meilleure réponse avec d’autres informations dont une application cliente, telle qu’un chatbot, a besoin afin d’afficher une réponse pour l’utilisateur.

Supprimer une base de connaissances

Quand vous avez fini d’utiliser la base de connaissances, supprimez-la.

Information	Configuration cURL	Objectif
Nom de la ressource QnA Maker	URL	Utilisé pour construire l’URL
Clé de la ressource QnA Maker	Param -h pour l’en-tête Ocp-Apim-Subscription-Key	S’authentifier auprès du service QnA Maker
ID de la base de connaissances	Itinéraire d’URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

La commande cURL est exécutée à partir d’un interpréteur de commandes BASH. Modifiez cette commande avec vos propres informations relatives au nom de ressource, à la clé de ressource et à l’ID de la base de connaissances.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-X DELETE \
-v \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

L’état de la réponse est 204 sans résultats. Utilisez le paramètre de ligne de commande -v pour afficher la sortie détaillée de la commande cURL. Cela inclut l’état HTTP.

Ressources supplémentaires

• Documentation de référence sur la création
• Documentation de référence sur le runtime
• Exemples de scripts BASH utilisant cURL

Utilisez la bibliothèque de client QnA Maker pour .NET afin de :

• Créer une base de connaissances
• Mettre à jour une base de connaissances
• Publier une base de connaissances
• Obtenir la clé de point de terminaison du runtime de prédiction
• Attendre l’exécution d’une tâche de longue durée
• Télécharger une base de connaissances
• Obtenir une réponse d’une base de connaissances
• Supprimer une base de connaissances

Documentation de référence | Code source de la bibliothèque | Package (NuGet) | Exemples C#

Notes

Les nouvelles ressources créées après le 1er juillet 2019 utilisent des noms de sous-domaines personnalisés. Pour plus d’informations et afin d’obtenir une liste complète des points de terminaison régionaux, consultez Noms personnalisés de sous-domaine pour Azure AI services.

Prérequis

Notes

Cette documentation ne s’applique pas à la dernière version. Pour en savoir plus sur l’utilisation de l’API C# avec la dernière version, consultez le Guide de démarrage rapide en C#.

• Abonnement Azure - En créer un gratuitement
• L’IDE Visual Studio ou la version actuelle de .NET Core.
• Une fois en possession de votre abonnement Azure, créez une ressource QnA Maker sur le portail Azure pour obtenir votre clé de création et votre nom de ressource associé. À la fin du déploiement, sélectionnez Accéder à la ressource.
  • Vous aurez besoin de la clé et du nom de la ressource que vous créez pour connecter votre application à l’API QnA Maker. Vous collerez la clé et le nom de la ressource dans le code ci-dessous plus tard dans le guide de démarrage rapide.
  • Vous pouvez utiliser le niveau tarifaire Gratuit (F0) pour tester le service, puis passer par la suite à un niveau payant pour la production.

Configuration

Interface de ligne de commande

Dans une fenêtre de console (par exemple cmd, PowerShell ou Bash), utilisez la commande dotnet new pour créer une application console avec le nom qna-maker-quickstart. Cette commande crée un projet C# simple nommé « Hello World » avec un seul fichier source : program.cs.

dotnet new console -n qna-maker-quickstart

Déplacez vos répertoires vers le dossier d’application nouvellement créé. Vous pouvez générer l’application avec :

dotnet build

La sortie de génération ne doit contenir aucun avertissement ni erreur.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Dans le répertoire de l’application, installez la bibliothèque de client QnA Maker pour .NET avec la commande suivante :

dotnet add package Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker --version 2.0.1

Conseil

Vous voulez voir l’intégralité du fichier de code de démarrage rapide à la fois ? Vous le trouverez sur GitHub, qui contient les exemples de code utilisés dans ce guide de démarrage rapide.

using, directives

À partir du répertoire du projet, ouvrez le fichier program.cs et ajoutez ce qui suit en utilisant les directives using suivantes :

using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker;
using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker.Models;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

Clé d’abonnement et points de terminaison de ressource

Dans la méthode Main de l’application, ajoutez des variables et du code, comme indiqué dans la section ci-dessous, pour utiliser les tâches courantes dans ce guide de démarrage rapide.

• Nous utilisons une clé d’abonnement et une clé de création de manière interchangeable. Pour plus d’informations sur la clé de création, consultez Clés dans QnA Maker.

• Le format de la valeur de QNA_MAKER_ENDPOINT est https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Accédez au portail Azure, puis recherchez la ressource QnA Maker que vous avez créée à l’étape des prérequis. Sélectionnez la page Clés et point de terminaison sous Gestion des ressources pour localiser la clé de création (abonnement) et le point de terminaison QnA Maker.

• Le format de la valeur de QNA_MAKER_RUNTIME_ENDPOINT est https://YOUR-RESOURCE-NAME.azurewebsites.net. Accédez au portail Azure, puis recherchez la ressource QnA Maker que vous avez créée à l’étape des prérequis. Sélectionnez la page Exporter le modèle sous Automation pour localiser le point de terminaison du runtime.

Important

N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, utilisez un moyen sécurisé de stocker et d’accéder à vos informations d’identification comme Azure Key Vault. Pour plus d’informations, consultez l’article sur la sécurité d’Azure AI services.

var authoringKey = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
var authoringURL = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
var queryingURL = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

Modèles objet

QnA Maker utilise deux modèles objet différents :

• QnAMakerClient est l’objet utilisé pour créer, gérer, publier et télécharger la base de connaissances.
• QnAMakerRuntime est l’objet utilisé pour interroger la base de connaissances avec l’API GenerateAnswer et envoyer de nouvelles questions suggérées avec l’API Train (dans le cadre de l’apprentissage actif).

Utilisation de cet exemple de base de connaissances

Dans ce guide de démarrage rapide, la base de connaissances commence par deux paires de questions et réponses conversationnelles, le but étant de simplifier l’exemple et d’obtenir des ID hautement prévisibles à utiliser dans la méthode de mise à jour, en associant les invites de suivi des questions avec de nouvelles paires. Tout cela a été planifié et implémenté dans un ordre spécifique pour les besoins de ce guide de démarrage rapide.

Si vous prévoyez de développer votre base de connaissances au fil du temps avec des invites de suivi qui dépendent de paires de questions et réponses existantes, vous pouvez choisir les méthodes suivantes :

• Pour des bases de connaissances volumineuses, gérez la base de connaissances dans un éditeur de texte ou un outil TSV qui prend en charge l’automatisation, puis remplacez entièrement la base de connaissances en une seule fois par le biais d’une mise à jour.
• Pour des bases de connaissances de petite taille, gérez intégralement les invites de suivi dans le portail QnA Maker.

Informations sur les paires de questions/réponses utilisées dans ce guide de démarrage rapide :

• Types de paires de questions/réponses : il existe deux types de paires de questions/réponses dans cette base de connaissances après la mise à jour : les informations d’échange (chitchat) et celles propres au domaine. C’est généralement le cas si votre base de connaissances est liée à une application de conversation telle qu’un chatbot.
• Les réponses de la base de connaissances peuvent être filtrées par métadonnées ou utiliser des invites de suivi, mais ce guide de démarrage rapide ne le montre pas. Consultez ces exemples generateAnswer indépendants du langage ici.
• Le texte de réponse est au format Markdown. Il peut contenir une grande variété de contenu Markdown comme des images (images disponibles publiquement sur Internet), des liens (vers des URL accessibles publiquement) et des éléments à puce, mais ce guide de démarrage rapide ne reflète pas cette variété.

Modèle objet QnAMakerClient

Le client QnA Maker de création est un objet QnAMakerClient qui s’authentifie auprès d’Azure à l’aide de Microsoft.Rest.ServiceClientCredentials, qui contient votre clé.

Une fois le client créé, utilisez la propriété Knowledge base pour créer, gérer et publier votre base de connaissances.

Gérez votre base de connaissances en envoyant un objet JSON. Pour les opérations immédiates, une méthode retourne généralement un objet JSON indiquant l’état. Pour les opérations de longue durée, la réponse est l’ID d’opération. Appelez la méthode client.Operations.GetDetailsAsync avec l’ID d’opération pour déterminer l’état de la requête.

Modèle objet QnAMakerRuntimeClient

Le client QnA Maker de prédiction est un objet QnAMakerRuntimeClient qui s’authentifie auprès d’Azure à l’aide de Microsoft.Rest.ServiceClientCredentials, qui contient la clé du runtime de prédiction retournée par l’appel du client de création, client.EndpointKeys.GetKeys après la publication de la base de connaissances.

Utilisez la méthode GenerateAnswer pour obtenir une réponse du runtime de requête.

Exemples de code

Ces extraits de code montrent comment effectuer les opérations suivantes avec la bibliothèque de client QnA Maker pour .NET :

• Authentifier le client de création
• Créer une base de connaissances
• Mettre à jour une base de connaissances
• Télécharger une base de connaissances
• Publier une base de connaissances
• Supprimer une base de connaissances
• Obtenir la clé du runtime de requête
• Obtenir l’état d’une opération
• Authentifier le client du runtime de requête
• Générer une réponse à partir de la base de connaissances

Authentifier le client pour la création de la base de connaissances

Instanciez un objet client avec votre clé, puis utilisez-le avec votre ressource pour construire le point de terminaison et créer un QnAMakerClient avec votre point de terminaison et votre clé. Créez un objet ServiceClientCredentials.

var client = new QnAMakerClient(new ApiKeyServiceClientCredentials(authoringKey))
{ Endpoint = authoringURL };

Créer une base de connaissances

Une base de connaissances stocke des paires de questions et réponses pour l’objet CreateKbDTO à partir de trois sources :

• Pour le contenu éditorial, utilisez l'objet QnADTO.
  • Pour utiliser les métadonnées et les invites de suivi, utilisez le contexte éditorial, car cette donnée est ajoutée au niveau de chaque paire question/réponse.
• Pour les fichiers, utilisez l'objet FileDTO. FileDTO contient le nom de fichier et l’URL publique d’accès au fichier.
• Pour les URL, utilisez une liste de chaînes pour représenter les URL disponibles publiquement.

L’étape de création comprend également les propriétés de la base de connaissances :

• defaultAnswerUsedForExtraction : données retournées quand aucune réponse n’est trouvée
• enableHierarchicalExtraction : créez automatiquement des relations d’invite entre les paires question/réponse extraites
• language : quand vous créez la première base de connaissances d’une ressource, définissez le langage à utiliser dans l’index Recherche Azure.

Appelez la méthode CreateAsync, puis transmettez l’ID d’opération retourné à la méthode MonitorOperation pour interroger l’État.

La dernière ligne du code suivant retourne l’ID de la base de connaissances à partir de la réponse de MonitorOperation.

private static async Task<string> CreateSampleKb(IQnAMakerClient client)
{
    var qna1 = new QnADTO
    {
        Answer = "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        Questions = new List<string> { "How do I manage my knowledgebase?" },
        Metadata = new List<MetadataDTO> {
            new MetadataDTO { Name = "Category", Value = "api" },
            new MetadataDTO { Name = "Language", Value = "REST" }
        },

    };

    var qna2 = new QnADTO
    {
        Answer = "Yes, You can use our [.NET SDK](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker) with the [.NET Reference Docs](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.knowledge.qnamaker?view=azure-dotnet) to manage your knowledge base.",
        Questions = new List<string> { "Can I program with C#?" },
        Metadata = new List<MetadataDTO> {
            new MetadataDTO { Name = "Category", Value = "api" },
            new MetadataDTO { Name = "Language", Value = ".NET" }
        }
    };

    var file1 = new FileDTO
    {
        FileName = "myfile.tsv",
        FileUri = "https://mydomain/myfile.tsv"

    };

    var createKbDto = new CreateKbDTO
    {
        Name = "QnA Maker .NET SDK Quickstart",
        QnaList = new List<QnADTO> { qna1, qna2 },
        //Files = new List<FileDTO> { file1 }

    };

    var createOp = await client.Knowledgebase.CreateAsync(createKbDto);
    createOp = await MonitorOperation(client, createOp);

    return createOp.ResourceLocation.Replace("/knowledgebases/", string.Empty);
}

Veillez à inclure la fonction MonitorOperation, référencée dans le code ci-dessus, afin de créer une base de connaissances.

Mettre à jour une base de connaissances

Vous pouvez mettre à jour une base de connaissances en transmettant l’ID de la base de connaissances et un UpdatekbOperationDTO contenant des objets DTO add, update et delete à la méthode UpdateAsync. Utilisez la méthode MonitorOperation pour déterminer si la mise à jour a réussi.

private static async Task UpdateKB(IQnAMakerClient client, string kbId)
{

    var urls = new List<string> {
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    };

    var updateOp = await client.Knowledgebase.UpdateAsync(kbId, new UpdateKbOperationDTO
    {
        // Create JSON of changes
        Add = new UpdateKbOperationDTOAdd
        {
            QnaList = new List<QnADTO> {
                new QnADTO {
                    Questions = new List<string> {
                        "bye",
                        "end",
                        "stop",
                        "quit",
                        "done"
                    },
                    Answer = "goodbye",
                    Metadata = new List<MetadataDTO> {
                        new MetadataDTO { Name = "Category", Value="Chitchat" },
                        new MetadataDTO { Name = "Chitchat", Value = "end" },
                    }
                },
                new QnADTO {
                    Questions = new List<string> {
                        "hello",
                        "hi",
                        "start"
                    },
                    Answer = "Hello, please select from the list of questions or enter a new question to continue.",
                    Metadata = new List<MetadataDTO> {
                        new MetadataDTO { Name = "Category", Value="Chitchat" },
                        new MetadataDTO { Name = "Chitchat", Value = "begin" }
                    },
                    Context = new QnADTOContext
                    {
                        IsContextOnly = false,
                        Prompts = new List<PromptDTO>
                        {
                            new PromptDTO
                            {
                                DisplayOrder =1,
                                DisplayText= "Use REST",
                                QnaId=1

                            },
                            new PromptDTO
                            {
                                DisplayOrder =2,
                                DisplayText= "Use .NET NuGet package",
                                QnaId=2

                            },
                        }
                    }
                },
            },
            Urls = urls
        },
        Update = null,
        Delete = null
    }); ;

    // Loop while operation is success
    updateOp = await MonitorOperation(client, updateOp);
}

Veillez à inclure la fonction MonitorOperation, référencée dans le code ci-dessus, afin de mettre à jour une base de connaissances.

Télécharger une base de connaissances

Utilisez la méthode DownloadAsync pour télécharger la base de données sous la forme d’une liste de QnADocumentsDTO. Ceci n’est pas équivalent à l’exportation depuis la page Paramètres du portail QnA Maker, car le résultat de cette méthode n’est pas un fichier.

private static async Task DownloadKb(IQnAMakerClient client, string kbId)
{
    var kbData = await client.Knowledgebase.DownloadAsync(kbId, EnvironmentType.Prod);
    Console.WriteLine("KB Downloaded. It has {0} QnAs.", kbData.QnaDocuments.Count);

    // Do something meaningful with data
}

Publier une base de connaissances

Publiez la base de connaissances à l’aide de la méthode PublishAsync. Celle-ci prend le modèle actuel enregistré et entraîné, référencé par l’ID de base de connaissances, et le publie sur votre point de terminaison. Cette étape est nécessaire pour interroger votre base de connaissances.

private static async Task PublishKb(IQnAMakerClient client, string kbId)
{
    await client.Knowledgebase.PublishAsync(kbId);
}

Obtenir la clé du runtime de requête

Une fois que la base de connaissances a été publiée, vous avez besoin de la clé du runtime de requête pour interroger le runtime. Il ne s’agit pas de la même clé que celle utilisée pour créer l’objet client d’origine.

Utilisez la méthode EndpointKeys pour obtenir la classe EndpointKeysDTO.

Utilisez l’une des propriétés de clé retournées dans l’objet pour interroger la base de connaissances.

private static async Task<String> GetQueryEndpointKey(IQnAMakerClient client)
{
    var endpointKeysObject = await client.EndpointKeys.GetKeysAsync();

    return endpointKeysObject.PrimaryEndpointKey;
}

Une clé du runtime est nécessaire pour interroger votre base de connaissances.

Authentifier le runtime pour générer une réponse

Créez un QnAMakerRuntimeClient pour interroger la base de connaissances afin de générer une réponse ou d’effectuer un entraînement par le biais de l’apprentissage actif.

var runtimeClient = new QnAMakerRuntimeClient(new EndpointKeyServiceClientCredentials(primaryQueryEndpointKey))
{ RuntimeEndpoint = queryingURL };

Utilisez QnAMakerRuntimeClient pour :

• obtenir une réponse de la base de connaissances
• envoyer de nouvelles questions suggérées à la base de connaissances pour l’apprentissage actif.

Générer une réponse à partir de la base de connaissances

Générez une réponse à partir d’une base de connaissances publiée à l’aide de la méthode RuntimeClient.GenerateAnswerAsync. Cette méthode accepte l’ID de la base de connaissances et QueryDTO. Accédez à des propriétés supplémentaires de QueryDTO comme Top et Context, que vous pouvez utiliser dans votre chat bot.

private static async Task GenerateAnswer(IQnAMakerRuntimeClient runtimeClient, string kbId)
{
    var response = await runtimeClient.Runtime.GenerateAnswerAsync(kbId, new QueryDTO { Question = "How do I manage my knowledgebase?" });
    Console.WriteLine("Endpoint Response: {0}.", response.Answers[0].Answer);

    // Do something meaningful with answer
}

Il s’agit d’un exemple simple d’interrogation de la base de connaissances. Pour comprendre les scénarios d’interrogation avancés, consultez ces autres exemples de requêtes.

Supprimer une base de connaissances

Supprimez la base de connaissances à l’aide de la méthode DeleteAsync avec comme paramètre l’ID de la base de connaissances.

private static async Task DeleteKB(IQnAMakerClient client, string kbId)
{
    await client.Knowledgebase.DeleteAsync(kbId);
}

Obtenir l’état d’une opération

Certaines méthodes, telles que Create et Update, peuvent prendre tellement de temps qu’au lieu d’attendre que le processus se termine, une opération est retournée. Utilisez l'ID de l’opération pour interroger (avec une logique de nouvelle tentative) afin de déterminer l’état de la méthode d’origine.

La boucle et Task.Delay dans le bloc de code suivant sont utilisés pour simuler la logique de nouvelle tentative. Vous devez les remplacer par votre propre logique de nouvelle tentative.

private static async Task<Operation> MonitorOperation(IQnAMakerClient client, Operation operation)
{
    // Loop while operation is success
    for (int i = 0;
        i < 20 && (operation.OperationState == OperationStateType.NotStarted || operation.OperationState == OperationStateType.Running);
        i++)
    {
        Console.WriteLine("Waiting for operation: {0} to complete.", operation.OperationId);
        await Task.Delay(5000);
        operation = await client.Operations.GetDetailsAsync(operation.OperationId);
    }

    if (operation.OperationState != OperationStateType.Succeeded)
    {
        throw new Exception($"Operation {operation.OperationId} failed to completed.");
    }
    return operation;
}

Exécution de l'application

Exécutez l’application avec la commande dotnet run à partir du répertoire de votre application.

dotnet run

Le code source de cet exemple est disponible sur GitHub.

Utilisez la bibliothèque de client QnA Maker pour Node.js afin de :

• Créer une base de connaissances
• Mettre à jour une base de connaissances
• Publier une base de connaissances
• Obtenir la clé de point de terminaison du runtime de prédiction
• Attendre l’exécution d’une tâche de longue durée
• Télécharger une base de connaissances
• Obtenir une réponse d’une base de connaissances
• Supprimer une base de connaissances

Documentation de référence | Paquet (npm) | Exemples de Node.js

Remarque

Les nouvelles ressources créées après le 1er juillet 2019 utilisent des noms de sous-domaines personnalisés. Pour plus d’informations et afin d’obtenir une liste complète des points de terminaison régionaux, consultez Noms personnalisés de sous-domaine pour Azure AI services.

Prérequis

• Abonnement Azure - En créer un gratuitement
• Version actuelle de Node.js.
• Une fois en possession de votre abonnement Azure, créez une ressource QnA Maker sur le portail Azure pour obtenir vos clé et ressource de création. À la fin du déploiement, sélectionnez Accéder à la ressource.
  • Vous aurez besoin de la clé et du nom de la ressource que vous créez pour connecter votre application à l’API QnA Maker. Vous collerez la clé et le nom de la ressource dans le code ci-dessous plus tard dans le guide de démarrage rapide.
  • Vous pouvez utiliser le niveau tarifaire Gratuit (F0) pour tester le service, puis passer par la suite à un niveau payant pour la production.

Configuration

Création d’une application Node.js

Dans une fenêtre de console (telle que cmd, PowerShell ou bash), créez un répertoire pour votre application et accédez-y.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Exécutez la commande npm init -y pour créer une application de nœud avec un fichier package.json.

npm init -y

Installer la bibliothèque de client

Installez les packages NPM suivants :

npm install @azure/cognitiveservices-qnamaker
npm install @azure/cognitiveservices-qnamaker-runtime
npm install @azure/ms-rest-js

Le fichier package.json de votre application est mis à jour avec les dépendances.

Créez un fichier nommé index.js et importez les bibliothèques suivantes :

const msRest = require("@azure/ms-rest-js");
const qnamaker = require("@azure/cognitiveservices-qnamaker");
const qnamaker_runtime = require("@azure/cognitiveservices-qnamaker-runtime");

Créez une variable pour le nom de ressource et la clé Azure de votre ressource.

• Nous utilisons une clé d’abonnement et une clé de création de manière interchangeable. Pour plus d’informations sur la clé de création, consultez Clés dans QnA Maker.

• Le format de la valeur de QNA_MAKER_ENDPOINT est https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Accédez au portail Azure, puis recherchez la ressource QnA Maker que vous avez créée à l’étape des prérequis. Sélectionnez la page Clés et point de terminaison sous Gestion des ressources pour localiser la clé de création (abonnement) et le point de terminaison QnA Maker.

• Le format de la valeur de QNA_MAKER_RUNTIME_ENDPOINT est https://YOUR-RESOURCE-NAME.azurewebsites.net. Accédez au portail Azure, puis recherchez la ressource QnA Maker que vous avez créée à l’étape des prérequis. Sélectionnez la page Exporter le modèle sous Automation pour localiser le point de terminaison du runtime.

Important

N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, utilisez un moyen sécurisé de stocker et d’accéder à vos informations d’identification comme Azure Key Vault. Pour plus d’informations, consultez l’article sur la sécurité d’Azure AI services.

const subscription_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
const endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
const runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

Modèles objet

QnA Maker utilise deux modèles objet différents :

• QnAMakerClient est l’objet utilisé pour créer, gérer, publier et télécharger la base de connaissances.
• QnAMakerRuntime est l’objet utilisé pour interroger la base de connaissances avec l’API GenerateAnswer et envoyer de nouvelles questions suggérées avec l’API Train (dans le cadre de l’apprentissage actif).

Modèle objet QnAMakerClient

Le client QnA Maker de création est un objet QnAMakerClient qui s’authentifie auprès d’Azure à l’aide de vos informations d’identification, qui contiennent votre clé.

Une fois le client créé, utilisez la propriété knowledgebase pour créer, gérer et publier votre base de connaissances.

Gérez votre base de connaissances en envoyant un objet JSON. Pour les opérations immédiates, une méthode retourne généralement un objet JSON indiquant l’état. Pour les opérations de longue durée, la réponse est l’ID d’opération. Appelez la méthode client.operations.getDetails avec l’ID d’opération pour déterminer l’état de la requête.

Modèle objet QnAMakerRuntimeClient

Le client QnA Maker de prédiction est un objet QnAMakerRuntimeClient qui s’authentifie auprès d’Azure à l’aide de Microsoft.Rest.ServiceClientCredentials, qui contient la clé du runtime de prédiction retournée par l’appel du client de création, client.EndpointKeys.getKeys, après la publication de la base de connaissances.

Exemples de code

Ces extraits de code montrent comment effectuer les opérations suivantes avec la bibliothèque de client QnA Maker pour .NET :

• Authentifier le client de création
• Créer une base de connaissances
• Mettre à jour une base de connaissances
• Télécharger une base de connaissances
• Publier une base de connaissances
• Supprimer une base de connaissances
• Obtenir la clé du runtime de requête
• Obtenir l’état d’une opération
• Authentifier le client du runtime de requête
• Générer une réponse à partir de la base de connaissances

Authentifier le client pour la création de la base de connaissances

Instanciez un client avec votre point de terminaison et la clé. Créez un objet ServiceClientCredentials avec votre clé et utilisez-le avec votre point de terminaison pour créer un objet QnAMakerClient.

const creds = new msRest.ApiKeyCredentials({ inHeader: { 'Ocp-Apim-Subscription-Key': subscription_key } });
const qnaMakerClient = new qnamaker.QnAMakerClient(creds, endpoint);
const knowledgeBaseClient = new qnamaker.Knowledgebase(qnaMakerClient);

Créer une base de connaissances

Une base de connaissances stocke des paires de questions et réponses pour l’objet CreateKbDTO à partir de trois sources :

• Pour le contenu éditorial, utilisez l'objet QnADTO.
  • Pour utiliser les métadonnées et les invites de suivi, utilisez le contexte éditorial, car cette donnée est ajoutée au niveau de chaque paire question/réponse.
• Pour les fichiers, utilisez l'objet FileDTO. FileDTO contient le nom de fichier et l’URL publique d’accès au fichier.
• Pour les URL, utilisez une liste de chaînes pour représenter les URL disponibles publiquement.

L’étape de création comprend également les propriétés de la base de connaissances :

• defaultAnswerUsedForExtraction : données retournées quand aucune réponse n’est trouvée
• enableHierarchicalExtraction : créez automatiquement des relations d’invite entre les paires question/réponse extraites
• language : quand vous créez la première base de connaissances d’une ressource, définissez le langage à utiliser dans l’index Recherche Azure.

Appelez la méthode create avec les informations de la base de connaissances. Ces informations sont essentiellement un objet JSON.

Au retour de la méthode create, passez l’ID d’opération retourné à la méthode wait_for_operation pour interroger l’état. La méthode wait_for_operation est retournée à la fin de l’opération. Analysez la valeur d’en-tête resourceLocation de l’opération retournée pour obtenir le nouvel ID de la base de connaissances.

const createKnowledgeBase = async (qnaClient, kbclient) => {

    console.log(`Creating knowledge base...`)

    const qna1 = {
        answer: "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        questions: ["How do I manage my knowledgebase?"],
        metadata: [
            { name: "Category", value: "api" },
            { name: "Language", value: "REST" }
        ]
    };

    const qna2 = {
        answer: "Yes, You can use our JS SDK on NPM for [authoring](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker), [query runtime](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker-runtime), and [the reference docs](https://docs.microsoft.com/en-us/javascript/api/@azure/cognitiveservices-qnamaker/?view=azure-node-latest) to manage your knowledge base.",
        questions: ["How do I manage my knowledgebase?"],
        metadata: [
            { name: "Category", value: "api" },
            { name: "Language", value: "JavaScript" }
        ]
    };

    const create_kb_payload = {
        name: 'QnA Maker JavaScript SDK Quickstart',
        qnaList: [
            qna1,
            qna2
        ],
        urls: [],
        files: [
            /*{
                fileName: "myfile.md",
                fileUri: "https://mydomain/myfile.md"
            }*/
        ],
        defaultAnswerUsedForExtraction: "No answer found.",
        enableHierarchicalExtraction: true,
        language: "English"
    };

    const results = await kbclient.create(create_kb_payload)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Create request failed - HTTP status ${results._response.status}`)
        return
    }

    const operationResult = await wait_for_operation(qnaClient, results.operationId)

    if (!operationResult || !operationResult.operationState || !(operationResult.operationState = "Succeeded") || !operationResult.resourceLocation) {
        console.log(`Create operation state failed - HTTP status ${operationResult._response.status}`)
        return
    }

    // parse resourceLocation for KB ID
    const kbID = operationResult.resourceLocation.replace("/knowledgebases/", "");

    return kbID;
}

Veillez à inclure la fonction wait_for_operation, référencée dans le code ci-dessus, afin de créer une base de connaissances.

Mettre à jour une base de connaissances

Vous pouvez mettre à jour une base de connaissances en passant l’ID de celle-ci et un UpdateKbOperationDTO contenant des objets DTO add, update et delete à la méthode update. Les objets DTO sont également essentiellement des objets JSON. Utilisez la méthode wait_for_operation pour déterminer si la mise à jour a réussi.

const updateKnowledgeBase = async (qnaClient, kbclient, kb_id) => {

    console.log(`Updating knowledge base...`)

    const urls = [
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    ]

    const qna3 = {
        answer: "goodbye",
        questions: [
            "bye",
            "end",
            "stop",
            "quit",
            "done"
        ],
        metadata: [
            { name: "Category", value: "Chitchat" },
            { name: "Chitchat", value: "end" }
        ]
    };

    const qna4 = {
        answer: "Hello, please select from the list of questions or enter a new question to continue.",
        questions: [
            "hello",
            "hi",
            "start"
        ],
        metadata: [
            { name: "Category", value: "Chitchat" },
            { name: "Chitchat", value: "begin" }
        ],
        context: {
            isContextOnly: false,
            prompts: [
                {
                    displayOrder: 1,
                    displayText: "Use REST",
                    qna: null,
                    qnaId: 1
                },
                {
                    displayOrder: 2,
                    displayText: "Use JS NPM package",
                    qna: null,
                    qnaId: 2
                },
            ]
        }
    };

    console.log(JSON.stringify(qna4))

    // Add new Q&A lists, URLs, and files to the KB.
    const kb_add_payload = {
        qnaList: [
            qna3,
            qna4
        ],
        urls: urls,
        files: []
    };

    // Bundle the add, update, and delete requests.
    const update_kb_payload = {
        add: kb_add_payload,
        update: null,
        delete: null,
        defaultAnswerUsedForExtraction: "No answer found. Please rephrase your question."
    };

    console.log(JSON.stringify(update_kb_payload))

    const results = await kbclient.update(kb_id, update_kb_payload)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Update request failed - HTTP status ${results._response.status}`)
        return false
    }

    const operationResult = await wait_for_operation(qnaClient, results.operationId)

    if (operationResult.operationState != "Succeeded") {
        console.log(`Update operation state failed - HTTP status ${operationResult._response.status}`)
        return false
    }

    console.log(`Update operation state ${operationResult._response.status} - HTTP status ${operationResult._response.status}`)
    return true
}

Veillez à inclure la fonction wait_for_operation, référencée dans le code ci-dessus, afin de mettre à jour une base de connaissances.

Télécharger une base de connaissances

Utilisez la méthode download pour télécharger la base de données sous la forme d’une liste de QnADocumentsDTO. Ceci n'est pas équivalent à l’exportation à partir de la page Paramètres du portail QnA Maker, car le résultat de cette méthode n’est pas un fichier TSV.

const downloadKnowledgeBase = async (KBclient, kb_id) => {

    console.log(`Downloading knowledge base...`)

    var kbData = await KBclient.download(kb_id, "Prod");
    console.log(`Knowledge base downloaded. It has ${kbData.qnaDocuments.length} QnAs.`);

    // Do something meaningful with data
}

Publier une base de connaissances

Publiez la base de connaissances à l’aide de la méthode publish. Celle-ci prend le modèle actuel enregistré et entraîné, référencé par l’ID de base de connaissances, et le publie sur un point de terminaison. Examinez le code de réponse HTTP pour vérifier que la publication a abouti.

const publishKnowledgeBase = async (kbclient, kb_id) => {

    console.log(`Publishing knowledge base...`)

    const results = await kbclient.publish(kb_id)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Publish request failed - HTTP status ${results._response.status}`)
        return false
    }

    console.log(`Publish request succeeded - HTTP status ${results._response.status}`)

    return true
}

Interroger une base de connaissances

Obtenir la clé du runtime de requête

Une fois que la base de connaissances a été publiée, vous avez besoin de la clé du runtime de requête pour interroger le runtime. Il ne s’agit pas de la même clé que celle utilisée pour créer l’objet client d’origine.

Utilisez la méthode EndpointKeys.getKeys pour obtenir la classe EndpointKeysDTO.

Utilisez l’une des propriétés de clé retournées dans l’objet pour interroger la base de connaissances.

const getEndpointKeys = async (qnaClient) => {

    console.log(`Getting runtime endpoint keys...`)

    const runtimeKeysClient = await qnaClient.endpointKeys;
    const results = await runtimeKeysClient.getKeys()

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`GetEndpointKeys request failed - HTTP status ${results._response.status}`)
        return null
    }

    console.log(`GetEndpointKeys request succeeded - HTTP status ${results._response.status} - primary key ${results.primaryEndpointKey}`)

    return results.primaryEndpointKey
}

Authentifier le runtime pour générer une réponse

Créez un QnAMakerRuntimeClient pour interroger la base de connaissances afin de générer une réponse ou d’effectuer un entraînement par le biais de l’apprentissage actif.

const queryRuntimeCredentials = new msRest.ApiKeyCredentials({ inHeader: { 'Authorization': 'EndpointKey ' + primaryQueryRuntimeKey } });
const runtimeClient = new qnamaker_runtime.QnAMakerRuntimeClient(queryRuntimeCredentials, runtime_endpoint);

Utilisez QnAMakerRuntimeClient pour obtenir une réponse de la base de connaissances ou pour envoyer de nouvelles questions suggérées à la base de connaissances en vue de l’apprentissage actif.

Générer une réponse à partir de la base de connaissances

Générez une réponse à partir d’une base de connaissances publiée à l’aide de la méthode RuntimeClient.runtime.generateAnswer. Cette méthode accepte l’ID de la base de connaissances et QueryDTO. Accédez à des propriétés supplémentaires de QueryDTO comme Top et Context, que vous pouvez utiliser dans votre chat bot.

const generateAnswer = async (runtimeClient, runtimeKey, kb_id) => {

    console.log(`Querying knowledge base...`)

    const requestQuery = await runtimeClient.runtime.generateAnswer(
        kb_id,
        {
            question: "How do I manage my knowledgebase?",
            top: 1,
            strictFilters: [
                { name: "Category", value: "api" }
            ]
        }
    );
    console.log(JSON.stringify(requestQuery));

}

Il s’agit d’un exemple simple d’interrogation de la base de connaissances. Pour comprendre les scénarios d’interrogation avancés, consultez ces autres exemples de requêtes.

Supprimer une base de connaissances

Supprimez la base de connaissances à l’aide de la méthode delete avec comme paramètre l’ID de la base de connaissances.

const deleteKnowledgeBase = async (KBclient, kb_id) => {

    console.log(`Deleting knowledge base...`)

    const results = await KBclient.deleteMethod(kb_id)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Delete operation state failed - HTTP status ${results._response.status}`)
        return false
    }

    console.log(`Delete operation state succeeded - HTTP status ${results._response.status}`)
    return true
}

Obtenir l’état d’une opération

Certaines méthodes, telles que Create et Update, peuvent prendre tellement de temps qu’au lieu d’attendre que le processus se termine, une opération est retournée. Utilisez l'ID de l’opération pour interroger (avec une logique de nouvelle tentative) afin de déterminer l’état de la méthode d’origine.

L’appel delayTimer dans le bloc de code suivant est utilisé pour simuler la logique de nouvelle tentative. Remplacez cette logique par votre propre logique de nouvelle tentative.

const wait_for_operation = async (qnaClient, operation_id) => {

    let state = "NotStarted"
    let operationResult = undefined

    while ("Running" === state || "NotStarted" === state) {

        operationResult = await qnaClient.operations.getDetails(operation_id)
        state = operationResult.operationState;

        console.log(`Operation state - ${state}`)

        await delayTimer(1000);
    }

    return operationResult;
}
const delayTimer = async (timeInMs) => {
    return await new Promise((resolve) => {
        setTimeout(resolve, timeInMs);
    });
}

Exécution de l'application

Exécutez l’application avec la commande node index.js à partir de votre répertoire d’application.

node index.js

Le code source de cet exemple est disponible sur GitHub.

Utilisez la bibliothèque de client QnA Maker pour Python afin de :

• Créer une base de connaissances
• Mettre à jour une base de connaissances
• Publier une base de connaissances
• Obtenir la clé de point de terminaison du runtime de prédiction
• Attendre l’exécution d’une tâche de longue durée
• Télécharger une base de connaissances
• Obtenir une réponse d’une base de connaissances
• Supprimer une base de connaissances

Documentation de référence | Code source de la bibliothèque | Package (PyPi) | Exemples Python

Notes

Les nouvelles ressources créées après le 1er juillet 2019 utilisent des noms de sous-domaines personnalisés. Pour plus d’informations et afin d’obtenir une liste complète des points de terminaison régionaux, consultez Noms personnalisés de sous-domaine pour Azure AI services.

Prérequis

Notes

Cette documentation ne s’applique pas à la dernière version. Pour en savoir plus sur l’utilisation de l’API Python avec la dernière version, consultez le Guide de démarrage rapide de Python.

• Abonnement Azure - En créer un gratuitement
• Python 3.x
• Une fois en possession de votre abonnement Azure, créez une ressource QnA Maker sur le portail Azure pour obtenir vos clé et point de terminaison de création. À la fin du déploiement, sélectionnez Accéder à la ressource.
  • Vous aurez besoin de la clé et du point de terminaison de la ressource que vous créez pour connecter votre application à l’API QnA Maker. Vous collerez votre clé et votre point de terminaison dans le code ci-dessous plus loin dans le guide de démarrage rapide.
  • Vous pouvez utiliser le niveau tarifaire Gratuit (F0) pour tester le service, puis passer par la suite à un niveau payant pour la production.

Configuration

Installer la bibliothèque de client

Après avoir installé Python, vous pouvez installer la bibliothèque de client avec :

pip install azure-cognitiveservices-knowledge-qnamaker==0.2.0

Créer une application Python

Créez un fichier Python nommé quickstart-file.py et importez les bibliothèques suivantes.

import os
import time

from azure.cognitiveservices.knowledge.qnamaker.authoring import QnAMakerClient
from azure.cognitiveservices.knowledge.qnamaker.runtime import QnAMakerRuntimeClient
from azure.cognitiveservices.knowledge.qnamaker.authoring.models import QnADTO, MetadataDTO, CreateKbDTO, OperationStateType, UpdateKbOperationDTO, UpdateKbOperationDTOAdd, EndpointKeysDTO, QnADTOContext, PromptDTO
from azure.cognitiveservices.knowledge.qnamaker.runtime.models import QueryDTO
from msrest.authentication import CognitiveServicesCredentials

Créez des variables pour le point de terminaison et la clé Azure de votre ressource.

• Nous utilisons une clé d’abonnement et une clé de création de manière interchangeable. Pour plus d’informations sur la clé de création, consultez Clés dans QnA Maker.

• Le format de la valeur de QNA_MAKER_ENDPOINT est https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Accédez au portail Azure, puis recherchez la ressource QnA Maker que vous avez créée à l’étape des prérequis. Sélectionnez la page Clés et point de terminaison sous Gestion des ressources pour localiser la clé de création (abonnement) et le point de terminaison QnA Maker.

• Le format de la valeur de QNA_MAKER_RUNTIME_ENDPOINT est https://YOUR-RESOURCE-NAME.azurewebsites.net. Accédez au portail Azure, puis recherchez la ressource QnA Maker que vous avez créée à l’étape des prérequis. Sélectionnez la page Exporter le modèle sous Automation pour localiser le point de terminaison du runtime.

Important

N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, utilisez un moyen sécurisé de stocker et d’accéder à vos informations d’identification comme Azure Key Vault. Pour plus d’informations, consultez l’article sur la sécurité d’Azure AI services.

subscription_key = 'PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE'

authoring_endpoint = 'PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE'

runtime_endpoint = 'PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE'

Modèles objet

QnA Maker utilise deux modèles objet différents :

• QnAMakerClient est l’objet utilisé pour créer, gérer, publier et télécharger la base de connaissances.
• QnAMakerRuntime est l’objet utilisé pour interroger la base de connaissances avec l’API GenerateAnswer et envoyer de nouvelles questions suggérées avec l’API Train (dans le cadre de l’apprentissage actif).

Utilisation de cet exemple de base de connaissances

Dans ce guide de démarrage rapide, la base de connaissances commence par deux paires de questions et réponses conversationnelles, le but étant de simplifier l’exemple et d’obtenir des ID hautement prévisibles à utiliser dans la méthode de mise à jour, en associant les invites de suivi des questions avec de nouvelles paires. Tout cela a été planifié et implémenté dans un ordre spécifique pour les besoins de ce guide de démarrage rapide.

Si vous prévoyez de développer votre base de connaissances au fil du temps avec des invites de suivi qui dépendent de paires de questions et réponses existantes, vous pouvez choisir les méthodes suivantes :

• Pour des bases de connaissances volumineuses, gérez la base de connaissances dans un éditeur de texte ou un outil TSV qui prend en charge l’automatisation, puis remplacez entièrement la base de connaissances en une seule fois par le biais d’une mise à jour.
• Pour des bases de connaissances de petite taille, gérez intégralement les invites de suivi dans le portail QnA Maker.

Informations sur les paires de questions/réponses utilisées dans ce guide de démarrage rapide :

• Types de paires de questions/réponses : il existe deux types de paires de questions/réponses dans cette base de connaissances après la mise à jour : les informations d’échange (chitchat) et celles propres au domaine. C’est généralement le cas si votre base de connaissances est liée à une application de conversation telle qu’un chatbot.
• Les réponses de la base de connaissances peuvent être filtrées par métadonnées ou utiliser des invites de suivi, mais ce guide de démarrage rapide ne le montre pas. Consultez ces exemples generateAnswer indépendants du langage ici.
• Le texte de réponse est au format Markdown. Il peut contenir une grande variété de contenu Markdown comme des images (images disponibles publiquement sur Internet), des liens (vers des URL accessibles publiquement) et des éléments à puce, mais ce guide de démarrage rapide ne reflète pas cette variété.

Modèle objet QnAMakerClient

Le client QnA Maker de création est un objet QnAMakerClient qui s’authentifie auprès d’Azure à l’aide de Microsoft.Rest.ServiceClientCredentials, qui contient votre clé.

Une fois le client créé, utilisez la propriété Knowledge base pour créer, gérer et publier votre base de connaissances.

Gérez votre base de connaissances en envoyant un objet JSON. Pour les opérations immédiates, une méthode retourne généralement un objet JSON indiquant l’état. Pour les opérations de longue durée, la réponse est l’ID d’opération. Appelez la méthode operations.get_details avec l’ID d’opération pour déterminer l’état de la requête.

Modèle objet QnAMakerRuntimeClient

Le client QnA Maker de prédiction est un objet QnAMakerRuntimeClient qui s’authentifie auprès d’Azure à l’aide de Microsoft.Rest.ServiceClientCredentials, qui contient la clé du runtime de prédiction retournée par l’appel du client de création, client.EndpointKeysOperations.get_keys, après la publication de la base de connaissances.

Utilisez la méthode generate_answer pour obtenir une réponse du runtime de requête.

Authentifier le client pour la création de la base de connaissances

Instanciez un client avec votre point de terminaison et la clé. Créez un objet CognitiveServicesCredentials avec votre clé et utilisez-le avec votre point de terminaison pour créer un objet QnAMakerClient.

client = QnAMakerClient(endpoint=authoring_endpoint, credentials=CognitiveServicesCredentials(subscription_key))

Créer une base de connaissances

Utilisez l’objet client pour obtenir un objet knowledge base operations.

Une base de connaissances stocke des paires de questions et réponses pour l’objet CreateKbDTO à partir de trois sources :

• Pour le contenu éditorial, utilisez l'objet QnADTO.
  • Pour utiliser les métadonnées et les invites de suivi, utilisez le contexte éditorial, car cette donnée est ajoutée au niveau de chaque paire question/réponse.
• Pour les fichiers, utilisez l'objet FileDTO. FileDTO contient le nom de fichier et l’URL publique d’accès au fichier.
• Pour les URL, utilisez une liste de chaînes pour représenter les URL disponibles publiquement.

Appelez la méthode create, puis passer l’ID d’opération retourné à la méthode Operations.getDetails pour interroger l’état.

La dernière ligne du code suivant retourne l’ID de la base de connaissances à partir de la réponse de MonitorOperation.

def create_kb(client):
    print ("Creating knowledge base...")

    qna1 = QnADTO(
        answer="Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        questions=["How do I manage my knowledgebase?"],
        metadata=[
            MetadataDTO(name="Category", value="api"),
            MetadataDTO(name="Language", value="REST"),
        ]
    )

    qna2 = QnADTO(
        answer="Yes, You can use our [Python SDK](https://pypi.org/project/azure-cognitiveservices-knowledge-qnamaker/) with the [Python Reference Docs](https://docs.microsoft.com/python/api/azure-cognitiveservices-knowledge-qnamaker/azure.cognitiveservices.knowledge.qnamaker?view=azure-python) to manage your knowledge base.",
        questions=["Can I program with Python?"],
        metadata=[
            MetadataDTO(name="Category", value="api"),
            MetadataDTO(name="Language", value="Python"),
        ]
    )

    urls = []
    files = [
        FileDTO(
            file_name = "structured.docx",
            file_uri = "https://github.com/Azure-Samples/cognitive-services-sample-data-files/raw/master/qna-maker/data-source-formats/structured.docx"
        )]

    create_kb_dto = CreateKbDTO(
        name="QnA Maker Python SDK Quickstart",
        qna_list=[
            qna1,
            qna2
        ],
        urls=urls,
        files=[],
        enable_hierarchical_extraction=True,
        default_answer_used_for_extraction="No answer found.",
        language="English"
    )
    create_op = client.knowledgebase.create(create_kb_payload=create_kb_dto)

    create_op_monitor = _monitor_operation(client=client, operation=create_op)

    # Get knowledge base ID from resourceLocation HTTP header
    knowledge_base_ID = create_op_monitor.resource_location.replace("/knowledgebases/", "")
    print("Created KB with ID: {}".format(knowledge_base_ID))

    return knowledge_base_ID

Veillez à inclure la fonction _monitor_operation, référencée dans le code ci-dessus, afin de créer une base de connaissances.

Mettre à jour une base de connaissances

Vous pouvez mettre à jour une base de connaissances en passant l’ID de celle-ci et un UpdateKbOperationDTO contenant des objets DTO add, update et delete à la méthode update. Utilisez la méthode Operation.getDetail pour déterminer si la mise à jour a réussi.

def update_kb(client, kb_id):
    print ("Updating knowledge base...")

    qna3 = QnADTO(
        answer="goodbye",
        questions=[
            "bye",
            "end",
            "stop",
            "quit",
            "done"
            ],
        metadata=[
            MetadataDTO(name="Category", value="Chitchat"),
            MetadataDTO(name="Chitchat", value="end"),
        ]
    )

    qna4 = QnADTO(
        answer="Hello, please select from the list of questions or enter a new question to continue.",
        questions=[
            "hello",
            "hi",
            "start"
        ],
        metadata=[
            MetadataDTO(name="Category", value="Chitchat"),
            MetadataDTO(name="Chitchat", value="begin"),
        ],
        context = QnADTOContext(

            is_context_only = False,
            prompts = [

                PromptDTO(
                    display_order =1,
                    display_text= "Use REST",
                    qna_id=1

                ),
                PromptDTO(
                    display_order =2,
                    display_text= "Use .NET NuGet package",
                    qna_id=2
                ),
            ]
        )

    )

    urls = [
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    ]



    update_kb_operation_dto = UpdateKbOperationDTO(
        add=UpdateKbOperationDTOAdd(
            qna_list=[
                qna3,
                qna4
            ],
            urls = urls,
            files=[]
        ),
        delete=None,
        update=None
    )
    update_op = client.knowledgebase.update(kb_id=kb_id, update_kb=update_kb_operation_dto)
    _monitor_operation(client=client, operation=update_op)
    print("Updated knowledge base.")

Veillez à inclure la fonction _monitor_operation, référencée dans le code ci-dessus, afin de mettre à jour une base de connaissances.

Télécharger une base de connaissances

Utilisez la méthode download pour télécharger la base de données sous la forme d’une liste de QnADocumentsDTO. Ceci n'est pas équivalent à l’exportation à partir de la page Paramètres du portail QnA Maker, car le résultat de cette méthode n’est pas un fichier TSV.

def download_kb(client, kb_id):
    print("Downloading knowledge base...")
    kb_data = client.knowledgebase.download(kb_id=kb_id, environment="Prod")
    print("Downloaded knowledge base. It has {} QnAs.".format(len(kb_data.qna_documents)))

Publier une base de connaissances

Publiez la base de connaissances à l’aide de la méthode publish. Celle-ci prend le modèle actuel enregistré et entraîné, référencé par l’ID de base de connaissances, et le publie sur un point de terminaison.

def publish_kb(client, kb_id):
    print("Publishing knowledge base...")
    client.knowledgebase.publish(kb_id=kb_id)
    print("Published knowledge base.")

Interroger une base de connaissances

Obtenir la clé du runtime de requête

Une fois que la base de connaissances a été publiée, vous avez besoin de la clé du runtime de requête pour interroger le runtime. Il ne s’agit pas de la même clé que celle utilisée pour créer l’objet client d’origine.

Utilisez la méthode EndpointKeysOperations.get_keys pour obtenir la classe EndpointKeysDTO.

Utilisez l’une des propriétés de clé retournées dans l’objet pour interroger la base de connaissances.

def getEndpointKeys_kb(client):
    print("Getting runtime endpoint keys...")
    keys = client.endpoint_keys.get_keys()
    print("Primary runtime endpoint key: {}.".format(keys.primary_endpoint_key))

    return keys.primary_endpoint_key

Authentifier le runtime pour générer une réponse

Créez un QnAMakerRuntimeClient pour interroger la base de connaissances afin de générer une réponse ou d’effectuer un entraînement par le biais de l’apprentissage actif.

runtimeClient = QnAMakerRuntimeClient(runtime_endpoint=runtime_endpoint, credentials=CognitiveServicesCredentials(queryRuntimeKey))

Utilisez QnAMakerRuntimeClient pour obtenir une réponse de la base de connaissances ou pour envoyer de nouvelles questions suggérées à la base de connaissances en vue de l’apprentissage actif.

Générer une réponse à partir de la base de connaissances

Générez une réponse à partir d’une base de connaissances publiée à l’aide de la méthode QnAMakerRuntimeClient.runtime.generate_answer. Cette méthode accepte l’ID de la base de connaissances et QueryDTO. Accédez à des propriétés supplémentaires de QueryDTO comme Top et Context, que vous pouvez utiliser dans votre chat bot.

def generate_answer(client, kb_id, runtimeKey):
    print ("Querying knowledge base...")

    authHeaderValue = "EndpointKey " + runtimeKey

    listSearchResults = client.runtime.generate_answer(kb_id, QueryDTO(question = "How do I manage my knowledgebase?"), dict(Authorization=authHeaderValue))

    for i in listSearchResults.answers:
        print(f"Answer ID: {i.id}.")
        print(f"Answer: {i.answer}.")
        print(f"Answer score: {i.score}.")

Il s’agit d’un exemple simple d’interrogation de la base de connaissances. Pour comprendre les scénarios d’interrogation avancés, consultez ces autres exemples de requêtes.

Supprimer une base de connaissances

Supprimez la base de connaissances à l’aide de la méthode delete avec comme paramètre l’ID de la base de connaissances.

def delete_kb(client, kb_id):
    print("Deleting knowledge base...")
    client.knowledgebase.delete(kb_id=kb_id)
    print("Deleted knowledge base.")

Obtenir l’état d’une opération

Certaines méthodes, telles que Create et Update, peuvent prendre tellement de temps qu’au lieu d’attendre que le processus se termine, une opération est retournée. Utilisez l’ID de l’opération pour interroger (avec une logique de nouvelle tentative) afin de déterminer l’état de la méthode d’origine.

L’appel setTimeout dans le bloc de code suivant est utilisé pour simuler le code asynchrone. Remplacez cela par la logique de nouvelle tentative.

def _monitor_operation(client, operation):

    for i in range(20):
        if operation.operation_state in [OperationStateType.not_started, OperationStateType.running]:
            print("Waiting for operation: {} to complete.".format(operation.operation_id))
            time.sleep(5)
            operation = client.operations.get_details(operation_id=operation.operation_id)
        else:
            break
    if operation.operation_state != OperationStateType.succeeded:
        raise Exception("Operation {} failed to complete.".format(operation.operation_id))

    return operation

Exécution de l'application

Exécutez l’application avec la commande Python de votre fichier de démarrage rapide.

python quickstart-file.py

Le code source de cet exemple est disponible sur GitHub.

Utilisez la bibliothèque de client QnA Maker pour Java afin de :

• Créer une base de connaissances
• Mettre à jour une base de connaissances
• Publier une base de connaissances
• Obtenir la clé de point de terminaison du runtime de prédiction
• Attendre l’exécution d’une tâche de longue durée
• Télécharger une base de connaissances
• Obtenir une réponse d’une base de connaissances
• Supprimer une base de connaissances

Code source de la bibliothèque | Package | Exemples

Notes

Les nouvelles ressources créées après le 1er juillet 2019 utilisent des noms de sous-domaines personnalisés. Pour plus d’informations et afin d’obtenir une liste complète des points de terminaison régionaux, consultez Noms personnalisés de sous-domaine pour Azure AI services.

Prérequis

• Abonnement Azure - En créer un gratuitement
• JDK
• Une fois en possession de votre abonnement Azure, créez une ressource QnA Maker sur le portail Azure pour obtenir vos clé et point de terminaison de création. À la fin du déploiement, sélectionnez Accéder à la ressource.
  • Vous aurez besoin de la clé et du point de terminaison de la ressource que vous créez pour connecter votre application à l’API QnA Maker. Collez votre clé et votre point de terminaison dans le code ci-dessous, plus loin dans le guide de démarrage rapide.
  • Vous pouvez utiliser le niveau tarifaire Gratuit (F0) pour tester le service, puis passer par la suite à un niveau payant pour la production.

Configuration

Installer les bibliothèques de client

Après avoir installé Java, vous pouvez installer les bibliothèques de client en utilisant Maven depuis le dépôt MVN.

Créer une application Java

Créez un fichier nommé quickstart.java et importez les bibliothèques suivantes.

/* Download the following files.
 * - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar
 * - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.pom
 * Move the downloaded .jar file to a folder named "lib" directly under the current folder.
 * Rename the downloaded file to pom.xml.
 * At the command line, run
 * mvn dependency:copy-dependencies
 * This will download the .jar files depended on by azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar to the folder "target/dependency" under the current folder. Move these .jar files to the "lib" folder as well.
 */
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.*;
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.models.*;

import java.io.*;
import java.lang.Object.*;
import java.time.format.DateTimeFormatter;  
import java.time.LocalDateTime; 
import java.util.*;
import java.net.*;

Créez des variables pour le point de terminaison et la clé Azure de votre ressource.

• Nous utilisons une clé d’abonnement et une clé de création de manière interchangeable. Pour plus d’informations sur la clé de création, consultez Clés dans QnA Maker.

• Le format de la valeur de QNA_MAKER_ENDPOINT est https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Accédez au portail Azure, puis recherchez la ressource QnA Maker que vous avez créée à l’étape des prérequis. Sélectionnez la page Clés et point de terminaison sous Gestion des ressources pour localiser la clé de création (abonnement) et le point de terminaison QnA Maker.

• Le format de la valeur de QNA_MAKER_RUNTIME_ENDPOINT est https://YOUR-RESOURCE-NAME.azurewebsites.net. Accédez au portail Azure, puis recherchez la ressource QnA Maker que vous avez créée à l’étape des prérequis. Sélectionnez la page Exporter le modèle sous Automation pour localiser le point de terminaison du runtime.

Important

N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, utilisez un moyen sécurisé de stocker et d’accéder à vos informations d’identification comme Azure Key Vault. Pour plus d’informations, consultez l’article sur la sécurité d’Azure AI services.

private static String authoring_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
private static String authoring_endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
private static String runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

Modèles objet

QnA Maker utilise deux modèles objet différents :

• QnAMakerClient est l’objet utilisé pour créer, gérer, publier et télécharger la base de connaissances.
• QnAMakerRuntime est l’objet utilisé pour interroger la base de connaissances avec l’API GenerateAnswer et envoyer de nouvelles questions suggérées avec l’API Train (dans le cadre de l’apprentissage actif).

Utilisation de cet exemple de base de connaissances

Dans ce guide de démarrage rapide, la base de connaissances commence par deux paires de questions et réponses conversationnelles, le but étant de simplifier l’exemple et d’obtenir des ID hautement prévisibles à utiliser dans la méthode de mise à jour, en associant les invites de suivi des questions avec de nouvelles paires. Tout cela a été planifié et implémenté dans un ordre spécifique pour les besoins de ce guide de démarrage rapide.

Si vous prévoyez de développer votre base de connaissances au fil du temps avec des invites de suivi qui dépendent de paires de questions et réponses existantes, vous pouvez choisir les méthodes suivantes :

• Pour des bases de connaissances volumineuses, gérez la base de connaissances dans un éditeur de texte ou un outil TSV qui prend en charge l’automatisation, puis remplacez entièrement la base de connaissances en une seule fois par le biais d’une mise à jour.
• Pour des bases de connaissances de petite taille, gérez intégralement les invites de suivi dans le portail QnA Maker.

Informations sur les paires de questions/réponses utilisées dans ce guide de démarrage rapide :

• Types de paires de questions/réponses : il existe deux types de paires de questions/réponses dans cette base de connaissances après la mise à jour : les informations d’échange (chitchat) et celles propres au domaine. C’est généralement le cas si votre base de connaissances est liée à une application de conversation telle qu’un chatbot.
• Les réponses de la base de connaissances peuvent être filtrées par métadonnées ou utiliser des invites de suivi, mais ce guide de démarrage rapide ne le montre pas. Consultez ces exemples generateAnswer indépendants du langage ici.
• Le texte de réponse est au format Markdown. Il peut contenir une grande variété de contenu Markdown comme des images (images disponibles publiquement sur Internet), des liens (vers des URL accessibles publiquement) et des éléments à puce, mais ce guide de démarrage rapide ne reflète pas cette variété.

Modèle objet QnAMakerClient

Le client QnA Maker de création est un objet QnAMakerClient qui s’authentifie auprès d’Azure en utilisant MsRest::ServiceClientCredentials, qui contient votre clé.

Une fois le client créé, utilisez les méthodes de la propriété Knowledgebases du client pour créer, gérer et publier votre base de connaissances.

Pour les opérations immédiates, une méthode retourne généralement le résultat, le cas échéant. Pour les opérations de longue durée, la réponse est un objet Operation. Appelez la méthode getDetails avec la valeur operation.operationId pour déterminer l’état de la requête.

Modèle objet QnAMakerRuntimeClient

Le client QnA Maker d’exécution est un objet QnAMakerRuntimeClient.

Une fois que vous avez publié votre base de connaissances en utilisant le client d’exécution, utilisez la méthode generateAnswer du client d’exécution pour recevoir une réponse de la base de connaissances.

Vous créez un client d’exécution en appelant QnAMakerRuntimeManager.authenticate et en passant une clé de point de terminaison d’exécution. Pour obtenir la clé du point de terminaison d’exécution, utilisez le client de création pour appeler getKeys.

Authentifier le client pour la création de la base de connaissances

Instanciez un client avec votre point de terminaison de création et votre clé d’abonnement.

/* Note QnAMakerManager.authenticate() does not set the baseUrl paramater value
 * as the value for QnAMakerClient.endpoint, so we still need to call withEndpoint().
 */
QnAMakerClient authoring_client = QnAMakerManager.authenticate(authoring_key).withEndpoint(authoring_endpoint);
Knowledgebases kb_client = authoring_client.knowledgebases();
Operations ops_client = authoring_client.operations();
EndpointKeys keys_client = authoring_client.endpointKeys();

Créer une base de connaissances

Une base de connaissances stocke des paires de questions et réponses pour l’objet CreateKbDTO à partir de trois sources :

• Pour le contenu éditorial, utilisez l'objet QnADTO.
  • Pour utiliser les métadonnées et les invites de suivi, utilisez le contexte éditorial, car cette donnée est ajoutée au niveau de chaque paire question/réponse.
• Pour les fichiers, utilisez l'objet FileDTO. FileDTO contient le nom de fichier et l’URL publique d’accès au fichier.
• Pour les URL, utilisez une liste de chaînes pour représenter les URL disponibles publiquement.

Appelez la méthode create, puis passez la propriété operationId de l’opération retournée à la méthode getDetails pour interroger l’état.

La dernière ligne du code suivant retourne l’ID de la base de connaissances.

public String create_kb () throws Exception {
    System.out.println("Creating KB...");

    String name = "QnA Maker FAQ from quickstart";

    var metadata = new MetadataDTO()
        .withName ("Category")
        .withValue ("api");

    List<MetadataDTO> metadata_list = Arrays.asList(new MetadataDTO[]{ metadata });

    var qna = new QnADTO()
        .withAnswer ("You can use our REST APIs to manage your knowledge base.")
        .withQuestions ( Arrays.asList(new String[]{ "How do I manage my knowledgebase?" }))
        .withMetadata (metadata_list);

    List<QnADTO> qna_list = Arrays.asList(new QnADTO[]{ qna });

    var urls = Arrays.asList(new String[]{ "https://docs.microsoft.com/en-in/azure/cognitive-services/qnamaker/faqs" });

    var payload = new CreateKbDTO().withName(name).withQnaList(qna_list).withUrls(urls);

    var result = kb_client.create(payload);
    var kb_id = wait_for_operation(result);

    System.out.println("Created KB with ID: " + kb_id + ".\n");
    return kb_id;
}

Mettre à jour une base de connaissances

Vous pouvez mettre à jour une base de connaissances en appelant update, et en passant l’ID de la base de connaissances et un objet UpdateKbOperationDTO. Cet objet peut à son tour contenir :

• add
• update
• delete

Passez la propriété operationId de l’opération retournée à la méthode getDetails pour interroger l’état.

public void update_kb (String kb_id) throws Exception {
    System.out.println("Updating KB...");

    var update = new UpdateKbOperationDTOUpdate().withName ("New KB name");

    var payload = new UpdateKbOperationDTO().withUpdate((UpdateKbOperationDTOUpdate)update);

    var result = kb_client.update(kb_id, payload);
    wait_for_operation(result);

    System.out.println("Updated KB.");
}

Télécharger une base de connaissances

Utilisez la méthode download pour télécharger la base de données sous la forme d’une liste de QnADocumentsDTO. Ceci n'est pas équivalent à l’exportation à partir de la page Paramètres du portail QnA Maker, car le résultat de cette méthode n’est pas un fichier TSV.

public void download_kb(String kb_id) {
    System.out.println("Downloading KB...");

    var kb_data = kb_client.download(kb_id, EnvironmentType.PROD);
    System.out.println("KB Downloaded. It has " + kb_data.qnaDocuments().size() + " question/answer sets.");

    System.out.println("Downloaded KB.\n");
}

Publier une base de connaissances

Publiez la base de connaissances à l’aide de la méthode publish. Celle-ci prend le modèle actuel enregistré et entraîné, référencé par l’ID de base de connaissances, et le publie sur un point de terminaison.

public void publish_kb(String kb_id) {
    System.out.println("Publishing KB...");
    kb_client.publish(kb_id);
    System.out.println("KB published.\n");
}

Générer une réponse à partir de la base de connaissances

Une fois qu’une base de connaissances a été publiée, vous avez besoin de la clé du point de terminaison d’exécution pour interroger la base de connaissances. Ce n’est pas la même clé que la clé d’abonnement utilisée pour créer le client de création.

Utilisez la méthode getKeys pour obtenir un objet EndpointKeysDTO.

Créez un client d’exécution en appelant QnAMakerRuntimeManager.authenticate et en passant une clé de point de terminaison d’exécution provenant de l’objet EndpointKeysDTO.

Générez une réponse d’une base de connaissances publiée en utilisant la méthode generateAnswer. Cette méthode accepte l’ID de la base de connaissances et un objet QueryDTO.

public void query_kb(String kb_id) {
    System.out.println("Sending query to KB...");
    
    var runtime_key = keys_client.getKeys().primaryEndpointKey();
    QnAMakerRuntimeClient runtime_client = QnAMakerRuntimeManager.authenticate(runtime_key).withRuntimeEndpoint(runtime_endpoint);
    var query = (new QueryDTO()).withQuestion("How do I manage my knowledgebase?");
    var result = runtime_client.runtimes().generateAnswer(kb_id, query);
    System.out.println("Answers:");
    for (var answer : result.answers()) {
        System.out.println(answer.answer().toString());
    };
    System.out.println();
}

Il s’agit d’un exemple simple d’interrogation d’une base de connaissances. Pour comprendre les scénarios d’interrogation avancés, consultez ces autres exemples de requêtes.

Supprimer une base de connaissances

Supprimez la base de connaissances à l’aide de la méthode delete avec comme paramètre l’ID de la base de connaissances.

public void delete_kb(String kb_id) {
    System.out.println("Deleting KB...");
    kb_client.delete(kb_id);
    System.out.println("KB deleted.\n");
}

Obtenir l’état d’une opération

Certaines méthodes, telles que Create et Update, peuvent prendre tellement de temps qu’au lieu d’attendre que le processus se termine, une opération est retournée. Utilisez l’ID de l’opération pour interroger (avec une logique de nouvelle tentative) afin de déterminer l’état de la méthode d’origine.

public String wait_for_operation(Operation op) throws Exception {
    System.out.println ("Waiting for operation to finish...");
    Boolean waiting = true;
    String result = "";
    while (true == waiting) {
        var op_ = ops_client.getDetails(op.operationId());
        var state = op_.operationState();
        if (OperationStateType.FAILED == state) {
            throw new Exception("Operation failed.");
        }
        if (OperationStateType.SUCCEEDED == state) {
            waiting = false;
            // Remove "/knowledgebases/" from the resource location.
            result = op_.resourceLocation().replace("/knowledgebases/", "");
        }
        if (true == waiting) {
            System.out.println("Waiting 10 seconds for operation to complete...");
            Thread.sleep(10000);
        }
    }
    return result;
}

Exécution de l'application

Voici la méthode principale pour l’application.

    public static void main(String[] args) {
        try {
            Quickstart quickstart = new Quickstart();
            String kb_id = quickstart.create_kb();
//			quickstart.list_kbs();
            quickstart.update_kb(kb_id);
            quickstart.publish_kb(kb_id);
            quickstart.download_kb(kb_id);
            quickstart.query_kb(kb_id);
            quickstart.delete_kb(kb_id);
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

Exécutez l’application comme suit. Ceci suppose que le nom de votre classe est Quickstart et que vos dépendances se trouvent dans un sous-dossier nommé lib sous le dossier actif.

javac Quickstart.java -cp .;lib\*
java -cp .;lib\* Quickstart

Le code source de cet exemple est disponible sur GitHub.

Nettoyer les ressources

Si vous souhaitez nettoyer et supprimer un abonnement Azure AI services, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées.

• Portail
• Azure CLI

Étapes suivantes

Tutoriel : Tester votre base de connaissances avec un fichier de commandes

• Qu’est-ce que l’API QnA Maker ?
• Modifier une base de connaissances
• Obtenir une analyse de l'utilisation