Compartir a través de

Biblioteca cliente de respuesta a preguntas de Azure Cognitive Language Service para Python: versión 1.1.0

  • Artículo

Respuesta a preguntas es un servicio de API basado en la nube que permite crear una capa de preguntas y respuestas conversacionales sobre los datos existentes. Úselo para crear un knowledge base mediante la extracción de preguntas y respuestas del contenido semiestructurado, incluidas las preguntas más frecuentes, los manuales y los documentos. Responda a las preguntas de los usuarios con las mejores respuestas de las preguntas y respuestas de los knowledge base, automáticamente. Su knowledge base también es más inteligente, ya que aprende continuamente del comportamiento de los usuarios.

Código | fuente Paquete (PyPI) | Documentación | de referencia de APIDocumentación | del producto Muestras

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure para Python 2.7 finalizaron el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Introducción

Requisitos previos

Instalar el paquete

Instale la biblioteca cliente de Azure Question Answering para Python con pip:

pip install azure-ai-language-questionanswering

Nota: esta versión de la biblioteca cliente tiene como valor predeterminado la versión 2021-10-01de la API de servicio .

Autenticar el cliente

Para interactuar con el servicio De respuesta a preguntas, deberá crear una instancia de la clase QuestionAnsweringClient o una instancia de AuthoringClient para administrar proyectos dentro del recurso. Necesitará un punto de conexión y una clave de API para crear instancias de un objeto de cliente. Para más información sobre la autenticación con Cognitive Services, consulte Autenticación de solicitudes en Azure Cognitive Services.

Obtención de una clave de API

Puede obtener el punto de conexión y una clave de API del recurso Language en Azure Portal.

Como alternativa, use el comando de la CLI de Azure que se muestra a continuación para obtener la clave de API del recurso Language.

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

Creación de QuestionAnsweringClient

Una vez que haya determinado el punto de conexión y la clave de API , puede crear una instancia de 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)

Creación de AuthoringClient

Con el punto de conexión y la clave de API, puede crear una instancia de 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)

Creación de un cliente con una credencial de Azure Active Directory

Para usar una credencial de token de Azure Active Directory (AAD), proporcione una instancia del tipo de credencial deseado obtenido de la biblioteca azure-identity . Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de AAD. Cree un nombre de subdominio personalizado para el recurso con el fin de usar este tipo de autenticación.

La autenticación con AAD requiere una configuración inicial:

Después de la instalación, puede elegir el tipo de credencial de azure.identity que se va a usar. Por ejemplo, Se puede usar DefaultAzureCredential para autenticar al cliente:

Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, , . AZURE_TENANT_IDAZURE_CLIENT_SECRET

Use la credencial de token devuelta para autenticar al cliente:

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)

Conceptos clave

QuestionAnsweringClient

QuestionAnsweringClient es la interfaz principal para formular preguntas mediante una knowledge base con su propia información o entrada de texto mediante modelos entrenados previamente. En el caso de las operaciones asincrónicas, un asincrónico QuestionAnsweringClient se encuentra en el azure.ai.language.questionanswering.aio espacio de nombres .

AuthoringClient

AuthoringClient proporciona una interfaz para administrar proyectos de respuesta a preguntas. Algunos ejemplos de las operaciones disponibles incluyen la creación e implementación de proyectos, la actualización de los orígenes de conocimiento y la actualización de pares de preguntas y respuestas. Proporciona API sincrónicas y asincrónicas.

Ejemplos

QuestionAnsweringClient

La azure-ai-language-questionanswering biblioteca cliente proporciona API sincrónicas y asincrónicas.

Hacer una pregunta

La única entrada necesaria para formular una pregunta mediante un knowledge base es solo la pregunta en sí:

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))

Puede establecer opciones de palabra clave adicionales para limitar el número de respuestas, especificar una puntuación de confianza mínima y mucho más.

Formular una pregunta de seguimiento

Si el knowledge base está configurado para charlar, las respuestas de la knowledge base pueden incluir mensajes sugeridos de preguntas de seguimiento para iniciar una conversación. Puede formular una pregunta de seguimiento proporcionando el identificador de la respuesta elegida como contexto para la conversación continua:

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))

Creación de un proyecto

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"]))

Adición de un origen de conocimiento

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"]))

Implementación del proyecto

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)

Operaciones asincrónicas

Los ejemplos anteriores también se pueden ejecutar de forma asincrónica mediante los clientes del aio espacio de nombres :

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

Configuración opcional

Los argumentos de palabra clave opcionales se pueden pasar en el nivel de cliente y por operación. En la documentación de referencia de azure-core se describen las configuraciones disponibles para reintentos, registro, protocolos de transporte, etc.

Solución de problemas

General

Los clientes de Respuesta a preguntas de Azure generan excepciones definidas en Azure Core. Al interactuar con la biblioteca cliente de respuesta a preguntas de Cognitive Language Service mediante el SDK de Python, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de la API REST .

Por ejemplo, si envía una pregunta a un knowledge base inexistente, se devuelve un 400 error que indica "Solicitud incorrecta".

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))

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel DEBUG, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el logging_enable argumento .

Consulte la documentación completa del registro del SDK con ejemplos aquí.

Pasos siguientes

Contribuir

Consulte la CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones