Bibliothèque cliente de réponses aux questions Azure Cognitive Language Services pour .NET - version 1.1.0

  • Article

Le service réponses aux questions est un service d’API basé sur le cloud qui vous permet de créer une couche de questions-réponses conversationnelles sur vos données existantes. Utilisez-le pour créer un base de connaissances en extrayant des questions et des réponses à partir de votre contenu semi-structuré, y compris les FAQ, les manuels et les documents. Répondez automatiquement aux questions des utilisateurs avec les meilleures réponses des QNA de votre base de connaissances. Votre base de connaissances devient également plus intelligent, car il apprend continuellement du comportement de l’utilisateur.

| Code sourcePackage (NuGet) | Documentation de référence sur les | API | Documentation produitÉchantillons | Guide de migration

Prise en main

Installer le package

Installez la bibliothèque cliente de réponses aux questions Azure Cognitive Language Services pour .NET avec NuGet :

dotnet add package Azure.AI.Language.QuestionAnswering

Prérequis

Bien que vous puissiez utiliser ce Kit de développement logiciel (SDK) pour créer et importer des projets de conversation, Language Studio est la méthode préférée pour créer des projets.

Authentifier le client

Pour interagir avec le service De réponse aux questions, vous devez créer un instance de la QuestionAnsweringClient classe pour interroger des projets existants ou un instance du pour la QuestionAnsweringAuthoringClient gestion des projets au sein de votre ressource. Vous aurez besoin d’un point de terminaison et d’une clé API pour instancier un objet client. Pour plus d’informations sur l’authentification auprès de Cognitive Services, consultez Authentifier les demandes auprès d’Azure Cognitive Services.

Obtenir une clé API

Vous pouvez obtenir le point de terminaison et une clé d’API à partir de la ressource Cognitive Services ou de la ressource Réponses aux questions dans le portail Azure.

Vous pouvez également utiliser la commande Azure CLI ci-dessous pour obtenir la clé API à partir de la ressource Réponses aux questions.

az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>

Créer un QuestionAnsweringClient

Pour utiliser , QuestionAnsweringClientveillez à utiliser les espaces de noms appropriés :

using Azure.Core;
using Azure.AI.Language.QuestionAnswering;

Avec votre point de terminaison et votre clé API , vous pouvez instancier un QuestionAnsweringClient:

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com/");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

Créer une questionAnsweringAuthoringClient

Pour utiliser , QuestionAnsweringAuthoringClientutilisez l’espace de noms suivant en plus de ceux ci-dessus, si nécessaire.

using Azure.AI.Language.QuestionAnswering.Authoring;

Avec votre point de terminaison et votre clé API, vous pouvez instancier un QuestionAnsweringAuthoringClient:

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com/");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");

QuestionAnsweringAuthoringClient client = new QuestionAnsweringAuthoringClient(endpoint, credential);

Créer un client à l’aide de l’authentification Azure Active Directory

Vous pouvez également créer une QuestionAnsweringClientQuestionAnsweringAuthoringClient authentification Ou à l’aide d’Azure Active Directory (AAD). Le rôle « Lecteur de langue Cognitive Services » doit être attribué à votre utilisateur ou principal de service. À l’aide de DefaultAzureCredential , vous pouvez authentifier un service à l’aide d’une identité managée ou d’un principal de service, vous authentifier en tant que développeur travaillant sur une application, et bien plus encore, sans modifier le code.

Avant de pouvoir utiliser , DefaultAzureCredentialou tout type d’informations d’identification à partir d’Azure.Identity, vous devez d’abord installer le package Azure.Identity.

Pour utiliser DefaultAzureCredential avec un ID client et un secret, vous devez définir les AZURE_TENANT_IDvariables d’environnement , AZURE_CLIENT_IDet AZURE_CLIENT_SECRET ; vous pouvez également passer ces valeurs au ClientSecretCredential également dans Azure.Identity.

Veillez à utiliser l’espace de noms approprié pour DefaultAzureCredential en haut de votre fichier source :

using Azure.Identity;

Vous pouvez ensuite créer un instance de et le DefaultAzureCredential transmettre à un nouveau instance de votre client :

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
DefaultAzureCredential credential = new DefaultAzureCredential();

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

Notez que les points de terminaison régionaux ne prennent pas en charge l’authentification AAD. Au lieu de cela, créez un nom de domaine personnalisé pour votre ressource afin d’utiliser l’authentification AAD.

Concepts clés

QuestionAnsweringClient

Le QuestionAnsweringClient est l’interface principale pour poser des questions à l’aide d’un base de connaissances avec vos propres informations ou d’une entrée de texte à l’aide de modèles préentraînés. Il fournit des API synchrones et asynchrones pour poser des questions.

QuestionAnsweringAuthoringClient

fournit QuestionAnsweringAuthoringClient une interface pour la gestion des projets de réponses aux questions. Parmi les opérations disponibles, citons la création et le déploiement de projets, la mise à jour de vos sources de connaissances et la mise à jour des paires de questions-réponses. Il fournit des API synchrones et asynchrones.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options clientes | Accès à la réponse | Opérations de longue durée | Gestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

QuestionAnsweringClient

La bibliothèque cliente Azure.AI.Language.QuestionAnswering fournit des API synchrones et asynchrones.

Les exemples suivants illustrent les scénarios courants utilisant le clientcréé ci-dessus.

Poser une question

La seule entrée requise pour poser une question à l’aide d’un base de connaissances existant est simplement la question elle-même :

string projectName = "{ProjectName}";
string deploymentName = "{DeploymentName}";
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
Response<AnswersResult> response = client.GetAnswers("How long should my Surface battery last?", project);

foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
    Console.WriteLine($"({answer.Confidence:P2}) {answer.Answer}");
    Console.WriteLine($"Source: {answer.Source}");
    Console.WriteLine();
}

Vous pouvez définir des propriétés supplémentaires sur QuestionAnsweringClientOptions pour limiter le nombre de réponses, spécifier un score de confiance minimal, etc.

Poser une question de suivi

Si votre base de connaissances est configuré pour la conversation, vous pouvez poser une question de suivi à condition de l’ID de réponse aux questions précédent et, éventuellement, de la question exacte que l’utilisateur a posée :

string projectName = "{ProjectName}";
string deploymentName = "{DeploymentName}";
// Answers are ordered by their ConfidenceScore so assume the user choose the first answer below:
KnowledgeBaseAnswer previousAnswer = answers.Answers.First();
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
AnswersOptions options = new AnswersOptions
{
    AnswerContext = new KnowledgeBaseAnswerContext(previousAnswer.QnaId.Value)
};

Response<AnswersResult> response = client.GetAnswers("How long should charging take?", project, options);

foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
    Console.WriteLine($"({answer.Confidence:P2}) {answer.Answer}");
    Console.WriteLine($"Source: {answer.Source}");
    Console.WriteLine();
}

QuestionAnsweringAuthoringClient

Les exemples suivants illustrent les scénarios courants utilisant le QuestionAnsweringAuthoringClient instance créé dans cette section.

Créer un projet

Pour créer un projet, vous devez spécifier le nom du projet et créer un RequestContent instance avec les paramètres nécessaires à la configuration du projet.

// Set project name and request content parameters
string newProjectName = "{ProjectName}";
RequestContent creationRequestContent = RequestContent.Create(
    new {
        description = "This is the description for a test project",
        language = "en",
        multilingualResource = false,
        settings = new {
            defaultAnswer = "No answer found for your question."
            }
        }
    );

Response creationResponse = client.CreateProject(newProjectName, creationRequestContent);

// Projects can be retrieved as follows
Pageable<BinaryData> projects = client.GetProjects();

Console.WriteLine("Projects: ");
foreach (BinaryData project in projects)
{
    Console.WriteLine(project);
}

Déployez votre projet

Vos projets peuvent être déployés à l’aide du DeployProjectAsync ou du synchrone DeployProject. Tout ce que vous devez spécifier est le nom du projet et le nom de déploiement que vous souhaitez utiliser. Notez que le service ne vous permettra pas de déployer des projets vides.

// Set deployment name and start operation
string newDeploymentName = "{DeploymentName}";

Operation<BinaryData> deploymentOperation = client.DeployProject(WaitUntil.Completed, newProjectName, newDeploymentName);

// Deployments can be retrieved as follows
Pageable<BinaryData> deployments = client.GetDeployments(newProjectName);
Console.WriteLine("Deployments: ");
foreach (BinaryData deployment in deployments)
{
    Console.WriteLine(deployment);
}

Ajouter une source de connaissances

Une façon d’ajouter du contenu à votre projet consiste à ajouter une source de connaissances. L’exemple suivant montre comment configurer un RequestContent instance pour ajouter une nouvelle source de connaissances du type « url ».

// Set request content parameters for updating our new project's sources
string sourceUri = "{KnowledgeSourceUri}";
RequestContent updateSourcesRequestContent = RequestContent.Create(
    new[] {
        new {
                op = "add",
                value = new
                {
                    displayName = "MicrosoftFAQ",
                    source = sourceUri,
                    sourceUri = sourceUri,
                    sourceKind = "url",
                    contentStructureKind = "unstructured",
                    refresh = false
                }
            }
    });

Operation<Pageable<BinaryData>> updateSourcesOperation = client.UpdateSources(WaitUntil.Completed, newProjectName, updateSourcesRequestContent);

// Knowledge Sources can be retrieved as follows
Pageable<BinaryData> sources = updateSourcesOperation.Value;

Console.WriteLine("Sources: ");
foreach (BinaryData source in sources)
{
    Console.WriteLine(source);
}

Dépannage

Général

Lorsque vous interagissez avec la bibliothèque cliente de réponses aux questions Cognitive Language Services à l’aide du KIT de développement logiciel (SDK) .NET, les erreurs retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les demandes d’API REST.

Par exemple, si vous envoyez une question à un base de connaissances non existant, une 400 erreur est retournée indiquant « Requête incorrecte ».

try
{
    QuestionAnsweringProject project = new QuestionAnsweringProject("invalid-knowledgebase", "test");
    Response<AnswersResult> response = client.GetAnswers("Does this knowledge base exist?", project);
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Vous remarquerez que des informations supplémentaires sont enregistrées, telles que l’ID de demande client de l’opération.

Azure.RequestFailedException: Please verify azure search service is up, restart the WebApp and try again
Status: 400 (Bad Request)
ErrorCode: BadArgument

Content:
{
    "error": {
    "code": "BadArgument",
    "message": "Please verify azure search service is up, restart the WebApp and try again"
    }
}

Headers:
x-envoy-upstream-service-time: 23
apim-request-id: 76a83876-22d1-4977-a0b1-559a674f3605
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
X-Content-Type-Options: nosniff
Date: Wed, 30 Jun 2021 00:32:07 GMT
Content-Length: 139
Content-Type: application/json; charset=utf-8

Configuration de la journalisation de la console

Le moyen le plus simple d’afficher les journaux consiste à activer la journalisation de console. Pour créer un écouteur de journal du KIT de développement logiciel (SDK) Azure qui génère des messages dans la console, utilisez la AzureEventSourceListener.CreateConsoleLogger méthode .

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Pour en savoir plus sur les autres mécanismes de journalisation , consultez ici.

Étapes suivantes

Contribution

Consultez la CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions