Bibliothèque cliente de réponses aux questions du service de langage cognitif Azure pour Python - version 1.1.0

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 des utilisateurs.

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

Clause d’exclusion de responsabilité

La prise en charge des packages Python du KIT de développement logiciel (SDK) Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

Prérequis

• Python 3.7 ou version ultérieure est requis pour utiliser ce package.
• Un abonnement Azure
• Une ressource Language Service

Installer le package

Installez la bibliothèque cliente de réponses aux questions Azure pour Python avec pip :

pip install azure-ai-language-questionanswering

Remarque : cette version de la bibliothèque cliente utilise par défaut la version 2021-10-01de l’API de service .

Authentifier le client

Pour interagir avec le service Réponses aux questions, vous devez créer une instance de la classe QuestionAnsweringClient ou une instance de AuthoringClient pour la 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 Language dans le portail Azure.

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

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

Créer questionAnsweringClient

Une fois que vous avez déterminé votre point de terminaison et votre clé API , vous pouvez instancier un QuestionAnsweringClient :

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = QuestionAnsweringClient(endpoint, credential)

Créer authoringClient

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

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = AuthoringClient(endpoint, credential)

Créer un client avec des informations d’identification Azure Active Directory

Pour utiliser des informations d’identification de jeton Azure Active Directory (AAD), fournissez une instance du type d’informations d’identification souhaité obtenue à partir de la bibliothèque azure-identity . Notez que les points de terminaison régionaux ne prennent pas en charge l’authentification AAD. Créez un nom de sous-domaine personnalisé pour votre ressource afin d’utiliser ce type d’authentification.

L’authentification avec AAD nécessite une configuration initiale :

• Installer azure-identity
• Inscrire une nouvelle application AAD
• Accordez l’accès au service Language en affectant le rôle « Lecteur de langue Cognitive Services » à votre principal de service.

Après l’installation, vous pouvez choisir le type d’informations d’identification d’azure.identity à utiliser. Par exemple, DefaultAzureCredential peut être utilisé pour authentifier le client :

Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Utilisez les informations d’identification de jeton retournées pour authentifier le client :

from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = QuestionAnsweringClient(endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/", credential=credential)

Concepts clés

QuestionAnsweringClient

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. Pour les opérations asynchrones, une async QuestionAnsweringClient se trouve dans l’espace de azure.ai.language.questionanswering.aio noms.

AuthoringClient

AuthoringClient fournit 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.

Exemples

QuestionAnsweringClient

La azure-ai-language-questionanswering bibliothèque cliente fournit des API synchrones et asynchrones.

• Poser une question
• Poser une question de suivi
• Créer un projet
• Ajouter une source de connaissances
• Déployer votre projet
• Opérations asynchrones

Poser une question

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

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="test"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

Vous pouvez définir des options de mots clés supplémentaires 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, les réponses du base de connaissances peuvent inclure des invites suggérées pour des questions de suivi pour lancer une conversation. Vous pouvez poser une question de suivi en fournissant l’ID de la réponse choisie comme contexte pour la poursuite de la conversation :

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.ai.language.questionanswering import models

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should charging take?",
    answer_context=models.KnowledgeBaseAnswerContext(
        previous_qna_id=previous_answer.qna_id
    ),
    project_name="FAQ",
    deployment_name="live"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

Créer un projet

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))
with client:

    # create project
    project_name = "IssacNewton"
    project = client.create_project(
        project_name=project_name,
        options={
            "description": "biography of Sir Issac Newton",
            "language": "en",
            "multilingualResource": True,
            "settings": {
                "defaultAnswer": "no answer"
            }
        })

    print("view created project info:")
    print("\tname: {}".format(project["projectName"]))
    print("\tlanguage: {}".format(project["language"]))
    print("\tdescription: {}".format(project["description"]))

Ajouter une source de connaissances

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"
update_sources_poller = client.begin_update_sources(
    project_name=project_name,
    sources=[
        {
            "op": "add",
            "value": {
                "displayName": "Issac Newton Bio",
                "sourceUri": "https://wikipedia.org/wiki/Isaac_Newton",
                "sourceKind": "url"
            }
        }
    ]
)
update_sources_poller.result()

# list sources
print("list project sources")
sources = client.list_sources(
    project_name=project_name
)
for source in sources:
    print("project: {}".format(source["displayName"]))
    print("\tsource: {}".format(source["source"]))
    print("\tsource Uri: {}".format(source["sourceUri"]))
    print("\tsource kind: {}".format(source["sourceKind"]))

Déployez votre projet

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"

# deploy project
deployment_poller = client.begin_deploy_project(
    project_name=project_name,
    deployment_name="production"
)
deployment_poller.result()

# list all deployments
deployments = client.list_deployments(
    project_name=project_name
)

print("view project deployments")
for d in deployments:
    print(d)

Opérations asynchrones

Les exemples ci-dessus peuvent également être exécutés de manière asynchrone à l’aide des clients de l’espace de aio noms :

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.aio import QuestionAnsweringClient

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = await client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="production"
)

Configuration facultative

Les arguments de mot clé facultatifs peuvent être transmis au niveau du client et par opération. La documentation de référence azure-core décrit les configurations disponibles pour les nouvelles tentatives, la journalisation, les protocoles de transport, etc.

Dépannage

Général

Les clients De réponses aux questions Azure posent des exceptions définies dans Azure Core. Lorsque vous interagissez avec la bibliothèque cliente de réponses aux questions du service de langage cognitif à l’aide du Kit de développement logiciel (SDK) Python, les erreurs retournées par le service correspondent aux mêmes codes d’état HTTP retournés pour les demandes d’API REST .

Par exemple, si vous envoyez une question à un base de connaissances inexistant, une 400 erreur est retournée indiquant « Demande incorrecte ».

from azure.core.exceptions import HttpResponseError

try:
    client.get_answers(
        question="Why?",
        project_name="invalid-knowledge-base",
        deployment_name="test"
    )
except HttpResponseError as error:
    print("Query failed: {}".format(error.message))

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument logging_enable .

Consultez la documentation complète sur la journalisation du KIT de développement logiciel (SDK) avec des exemples ici.

Étapes suivantes

• Consultez nos exemples.
• Découvrez les différentes fonctionnalités du service Réponses aux questions.
• Essayez nos démonstrations de service.

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.