Biblioteca cliente de respuesta a preguntas de Azure Cognitive Language Services para .NET: versión 1.1.0

  • Artículo

El servicio de respuesta a preguntas es un servicio de API basado en la nube que le permite crear una capa de preguntas y respuestas conversacionales sobre los datos existentes. Úsela para crear un knowledge base extrayendo preguntas y respuestas del contenido semiestructurado, incluidas las preguntas más frecuentes, los manuales y los documentos. Responda automáticamente a las preguntas de los usuarios con las mejores respuestas de las QnAs de su knowledge base. El knowledge base también es más inteligente, ya que aprende continuamente del comportamiento del usuario.

Código | fuente Paquete (NuGet) | Documentación | de referencia de API | Documentación del productoMuestras | Guía de migración

Introducción

Instalar el paquete

Instale la biblioteca cliente de respuesta a preguntas de Azure Cognitive Language Services para .NET con NuGet:

dotnet add package Azure.AI.Language.QuestionAnswering

Requisitos previos

Aunque puede usar este SDK para crear e importar proyectos de conversación, Language Studio es el método preferido para crear proyectos.

Autenticar el cliente

Para interactuar con el servicio de respuesta a preguntas, deberá crear una instancia de la QuestionAnsweringClient clase para consultar proyectos existentes o una instancia de QuestionAnsweringAuthoringClient para administrar proyectos dentro del recurso. Necesitará un punto de conexión y una clave de API para crear una instancia 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 de Cognitive Services o del recurso de respuesta a preguntas 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 De respuesta a preguntas.

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

Creación de un elemento QuestionAnsweringClient

Para usar QuestionAnsweringClient, asegúrese de usar los espacios de nombres adecuados:

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

Con el punto de conexión y la clave de API, puede crear una instancia de :QuestionAnsweringClient

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

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

Creación de un elemento QuestionAnsweringAuthoringClient

Para usar QuestionAnsweringAuthoringClient, use el siguiente espacio de nombres además de los anteriores, si es necesario.

using Azure.AI.Language.QuestionAnswering.Authoring;

Con el punto de conexión y la clave de API, puede crear una instancia de :QuestionAnsweringAuthoringClient

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

QuestionAnsweringAuthoringClient client = new QuestionAnsweringAuthoringClient(endpoint, credential);

Creación de un cliente mediante la autenticación de Azure Active Directory

También puede crear o QuestionAnsweringClientQuestionAnsweringAuthoringClient mediante la autenticación de Azure Active Directory (AAD). El usuario o la entidad de servicio deben tener asignado el rol "Lector de lenguaje de Cognitive Services". Con DefaultAzureCredential , puede autenticar un servicio mediante identidad administrada o una entidad de servicio, autenticarse como desarrollador que trabaja en una aplicación y mucho más sin cambiar el código.

Para poder usar , DefaultAzureCredentialo cualquier tipo de credencial de Azure.Identity, primero deberá instalar el paquete Azure.Identity.

Para usar DefaultAzureCredential con un identificador de cliente y un secreto, deberá establecer las AZURE_TENANT_IDvariables de entorno , AZURE_CLIENT_IDy AZURE_CLIENT_SECRET ; como alternativa, puede pasar esos valores a ClientSecretCredential también en Azure.Identity.

Asegúrese de usar el espacio de nombres adecuado para DefaultAzureCredential en la parte superior del archivo de origen:

using Azure.Identity;

A continuación, puede crear una instancia de DefaultAzureCredential y pasarla a una nueva instancia del cliente:

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

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de AAD. En su lugar, cree un nombre de dominio personalizado para que el recurso use la autenticación de AAD.

Conceptos clave

QuestionAnsweringClient

QuestionAnsweringClient es la interfaz principal para formular preguntas mediante un knowledge base con su propia información, o la entrada de texto mediante modelos entrenados previamente. Proporciona API sincrónicas y asincrónicas para formular preguntas.

QuestionAnsweringAuthoringClient

QuestionAnsweringAuthoringClient 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.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de cliente Acceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

QuestionAnsweringClient

La biblioteca cliente Azure.AI.Language.QuestionAnswering proporciona API sincrónicas y asincrónicas.

En los ejemplos siguientes se muestran escenarios comunes con el clientcreado anteriormente.

Hacer una pregunta

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

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();
}

Puede establecer propiedades adicionales en QuestionAnsweringClientOptions 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, puede formular una pregunta de seguimiento proporcionada por el identificador de respuesta a preguntas anterior y, opcionalmente, la pregunta exacta que el usuario hizo:

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

En los ejemplos siguientes se muestran escenarios comunes mediante la QuestionAnsweringAuthoringClient instancia creada en esta sección.

Creación de un proyecto

Para crear un proyecto, debe especificar el nombre del proyecto y crear una RequestContent instancia con los parámetros necesarios para configurar el proyecto.

// 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);
}

Implementación del proyecto

Los proyectos se pueden implementar mediante o DeployProjectAsync la sincrónica DeployProject. Todo lo que debe especificar es el nombre del proyecto y el nombre de implementación que desea usar. Tenga en cuenta que el servicio no le permitirá implementar proyectos vacíos.

// 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);
}

Adición de un origen de conocimiento

Una manera de agregar contenido al proyecto es agregar un origen de conocimiento. En el ejemplo siguiente se muestra cómo puede configurar una RequestContent instancia para agregar un nuevo origen de conocimiento del tipo "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);
}

Solución de problemas

General

Al interactuar con la biblioteca cliente de respuesta a preguntas de Cognitive Language Services mediante el SDK de .NET, 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 no existente, se devuelve un 400 error que indica "Solicitud incorrecta".

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());
}

Observará que se registra información adicional, como el identificador de solicitud de cliente de la operación.

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

Configuración del registro de la consola

La manera más sencilla de ver los registros es habilitar el registro de la consola. Para crear un agente de escucha de registro del SDK de Azure que genere mensajes en la consola, use el AzureEventSourceListener.CreateConsoleLogger método .

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

Para más información sobre otros mecanismos de registro, consulte 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