Inicio rápido: Biblioteca cliente de QnA Maker

  • Artículo

Nota:

Azure Open AI en los datos utiliza modelos de lenguaje grande (LLM) para generar resultados similares para respuesta a QnA Maker. Si desea migrar el proyecto de QnA Maker a Azure Open AI en los datos, consulte nuestra guía.

Introducción a la biblioteca cliente de QnA Maker. Siga estos pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.

Nota

El servicio QnA Maker se retirará del mercado el 31 de marzo de 2025. Ya hay disponible una versión más reciente de la funcionalidad de preguntas y respuestas como parte de Lenguaje de Azure AI. Para más información sobre las funcionalidades de respuesta a preguntas en el servicio de lenguaje, consulte Respuesta a preguntas. A partir del 1 de octubre de 2022 no podrá crear nuevos recursos de QnA Maker. Para obtener información sobre la migración de knowledge bases existentes de QnA Maker a respuesta a preguntas, consulte la guía de migración.

Requisitos previos

Nota:

Esta documentación no se aplica a la versión más reciente. Para obtener información sobre el uso de la API REST en la versión más reciente, consulte el inicio rápido de la REST API de respuesta a preguntas.

  • La versión actual de cURL. En las guías de inicio rápido se usan varios modificadores de línea de comandos, que se indican en la documentación de cURL.

  • Para usar la clave y el nombre del recurso, debe tener un recurso de QnA Maker. Ha especificado el nombre del recurso durante su creación; la clave se creó automáticamente. El nombre del recurso se usa como subdominio personalizado para el punto de conexión. Para recuperar la clave y el nombre del recurso, seleccione Inicio rápido para el recurso en Azure Portal. El nombre del recurso es el primer subdominio de la dirección URL del punto de conexión:

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

Precaución

En los siguientes ejemplos de BASH se usa el carácter de continuación de línea \. Si la consola o el terminal usan un carácter de continuación de línea diferente, use este carácter.

Creación de una base de conocimientos

Para crear una base de conocimiento con las API REST y cURL, debe tener la siguiente información:

Information Configuración de cURL Propósito
Nombre del recurso de QnA Maker URL Se usa para construir la dirección URL
Clave del recurso de QnA Maker Parámetro -h para el encabezado Ocp-Apim-Subscription-Key Autenticación en el servicio QnA Maker
JSON que describe la base de conocimiento Parámetro -d Ejemplos de JSON
Tamaño del archivo JSON en bytes Parámetro -h para el encabezado Content-Size

El comando de cURL se ejecuta desde un shell de BASH. Edite este comando con su propio nombre de recurso, clave de recurso y valores y tamaño 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 respuesta de cURL desde QnA Maker incluye el operationId, que es necesario para obtener el estado de la operación.

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

Obtención del estado de la operación

Al crear una base de conocimiento, dado que la operación es asincrónica, la respuesta incluye información para determinar el estado.

Information Configuración de cURL Propósito
Nombre del recurso de QnA Maker URL Se usa para construir la dirección URL
Identificador de la operación Ruta de dirección URL /operations/REPLACE-WITH-YOUR-OPERATION-ID
Clave del recurso de QnA Maker Parámetro -h para el encabezado Ocp-Apim-Subscription-Key Autenticación en el servicio QnA Maker

El comando de cURL se ejecuta desde un shell de BASH. Edite este comando con su propio nombre de recurso, clave de recurso e identificador de operación.

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 respuesta de cURL incluye el estado. Si el estado de la operación es correcto, resourceLocation incluye el identificador de la base de conocimiento.

{
   "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"
}

Publicación de una base de conocimiento

Antes de consultar la base de conocimiento, debe hacer lo siguiente:

  • Publicación de una base de conocimiento
  • Obtención de la clave de punto de conexión en tiempo de ejecución

Esta tarea publica la base de conocimiento. La obtención de la clave de punto de conexión en tiempo de ejecución es una tarea independiente.

Information Configuración de cURL Propósito
Nombre del recurso de QnA Maker URL Se usa para construir la dirección URL
Clave del recurso de QnA Maker Parámetro -h para el encabezado Ocp-Apim-Subscription-Key Autenticación en el servicio QnA Maker
Identificador de base de conocimiento Ruta de dirección URL /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

El comando de cURL se ejecuta desde un shell de BASH. Edite este comando con su propio nombre de recurso, clave de recurso e identificador de base de conocimiento.

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

El estado de la respuesta es 204 sin resultados. Use el parámetro de línea de comandos -v para ver resultados detallados del comando de cURL. Esto incluirá el estado de HTTP.

Obtención de la clave de punto de conexión en tiempo de ejecución de la base de conocimiento publicada

Antes de consultar la base de conocimiento, debe hacer lo siguiente:

  • Publicación de una base de conocimiento
  • Obtención de la clave de punto de conexión en tiempo de ejecución

Esta tarea obtiene la clave de punto de conexión en tiempo de ejecución. La publicación de la base de conocimiento es una tarea independiente.

La clave de punto de conexión en tiempo de ejecución es la misma clave para todas las bases de conocimiento que utilizan el recurso de QnA Maker.

Information Configuración de cURL Propósito
Nombre del recurso de QnA Maker URL Se usa para construir la dirección URL
Clave del recurso de QnA Maker Parámetro -h para el encabezado Ocp-Apim-Subscription-Key Autenticación en el servicio QnA Maker

El comando de cURL se ejecuta desde un shell de BASH. Edite este comando con su propio nombre de recurso y clave de recurso.

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 respuesta de cURL incluye las claves de punto de conexión en tiempo de ejecución. Use solo una de las claves al consultar para obtener una respuesta de la base de conocimiento.

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

Consulta para obtener respuesta de la base de conocimiento publicada

La obtención de una respuesta de la base de conocimiento se realiza desde un tiempo de ejecución independiente de la administración de la base de conocimiento. Dado que se trata de un entorno de ejecución independiente, debe autenticarse con una clave de tiempo de ejecución.

Information Configuración de cURL Propósito
Nombre del recurso de QnA Maker URL Se usa para construir la dirección URL
Clave de tiempo de ejecución de QnA Maker Parámetro -h para el encabezado Authorization La clave forma parte de una cadena que incluye la palabra Endpointkey . Autenticación en el servicio QnA Maker
Identificador de base de conocimiento Ruta de dirección URL /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
JSON que describe la consulta Parámetro -d Parámetros del cuerpo de la solicitud y ejemplos de JSON
Tamaño del archivo JSON en bytes Parámetro -h para el encabezado Content-Size

El comando de cURL se ejecuta desde un shell de BASH. Edite este comando con su propio nombre de recurso, clave de recurso e identificador de base de conocimiento.

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="}'

Una respuesta correcta incluye la respuesta principal junto con otra información que una aplicación cliente, como un bot de chat, necesita para mostrar una respuesta al usuario.

Eliminación de una base de conocimiento

Cuando haya terminado de usar la base de conocimiento, elimínela.

Information Configuración de cURL Propósito
Nombre del recurso de QnA Maker URL Se usa para construir la dirección URL
Clave del recurso de QnA Maker Parámetro -h para el encabezado Ocp-Apim-Subscription-Key Autenticación en el servicio QnA Maker
Identificador de base de conocimiento Ruta de dirección URL /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

El comando de cURL se ejecuta desde un shell de BASH. Edite este comando con su propio nombre de recurso, clave de recurso e identificador de base de conocimiento.

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"

El estado de la respuesta es 204 sin resultados. Use el parámetro de línea de comandos -v para ver resultados detallados del comando de cURL. Esto incluirá el estado de HTTP.

Recursos adicionales

Use la biblioteca cliente de QnA Maker para .NET para:

  • Crear una base de conocimiento
  • Actualizar una base de conocimiento
  • Publicar una base de conocimiento
  • Obtener la clave del punto de conexión de tiempo de ejecución de predicción
  • Espera de una tarea de ejecución prolongada
  • Descargar una base de conocimiento
  • Obtener una respuesta de una base de conocimiento
  • Eliminar una base de conocimiento

Documentación de referencia | Código fuente de la biblioteca | Paquete (NuGet) | Ejemplos de C#

Nota

Los nuevos recursos creados después del 1 de julio de 2019 usarán nombres de subdominio personalizados. Para obtener más información y una lista completa de puntos finales regionales, consulte Nombres de subdominios personalizados para los servicios de Azure AI.

Requisitos previos

Nota:

Esta documentación no se aplica a la versión más reciente. Para obtener información sobre el uso de la API de C# en la versión más reciente, consulte el inicio rápido de C# de respuesta a preguntas.

  • Una suscripción a Azure: cree una cuenta gratuita
  • El IDE de Visual Studio o la versión actual de .NET Core.
  • Cuando tenga la suscripción a Azure, cree un recurso de QnA Maker en Azure Portal para obtener la clave de creación y el nombre del recurso. Tras su implementación, seleccione Ir al recurso.
    • Necesitará la clave y el nombre del recurso que cree para conectar la aplicación a QnA Maker API. En una sección posterior de este mismo inicio rápido pegue la clave y el nombre del recurso en el código siguiente.
    • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.

Instalación

CLI

En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use el comando dotnet new para crear una nueva aplicación de consola con el nombre qna-maker-quickstart. Este comando crea un sencillo proyecto de C#, "Hola mundo", con un solo archivo de origen: program.cs.

dotnet new console -n qna-maker-quickstart

Cambie el directorio a la carpeta de aplicaciones recién creada. Para compilar la aplicación:

dotnet build

La salida de la compilación no debe contener advertencias ni errores.

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

Dentro del directorio de aplicaciones, instale la biblioteca cliente de QnA Maker para .NET con el siguiente comando:

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

Sugerencia

¿Desea ver todo el archivo de código de inicio rápido de una vez? Puede encontrarlo en GitHub, que contiene los ejemplos de código de este inicio rápido.

Directivas Using

En el directorio del proyecto, abra el archivo program.cs y agregue lo siguiente mediante directivas using:

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

Clave de suscripción y puntos de conexión de recursos

En el método Main de la aplicación, agregue las variables y código que se muestran en la siguiente sección, para usar las tareas comunes de este inicio rápido.

  • Se puede usar la clave de suscripción y la clave de creación indistintamente. Para más información sobre la clave de creación, siga las indicaciones de Claves de QnA Maker.

  • El valor de QNA_MAKER_ENDPOINT tiene el formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Vaya a Azure Portal y busque el recurso de QnA Maker que creó en los requisitos previos. Seleccione la página Keys and Endpoint (Claves y punto de conexión), en Administración de recursos para buscar la clave de creación (suscripción) y el punto de conexión de QnA Maker.

Punto de conexión de creación de QnA Maker

  • El valor de QNA_MAKER_RUNTIME_ENDPOINT tiene el formato https://YOUR-RESOURCE-NAME.azurewebsites.net. Vaya a Azure Portal y busque el recurso de QnA Maker que creó en los requisitos previos. Seleccione la página Exportar plantilla, en Automatización, para buscar el punto de conexión en tiempo de ejecución.

Punto de conexión en tiempo de ejecución de QnA Maker

Importante

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública. En el caso de producción, use una forma segura de almacenar sus credenciales y acceder a ellas, como Azure Key Vault. Consulte el artículo Seguridad de servicios de Azure AI para más información.

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

Modelos de objetos

QnA Maker usa dos modelos de objetos diferentes:

  • QnAMakerClient , el objeto para crear, administrar, publicar y descargar la base de conocimiento.
  • QnAMakerRuntime , el objeto para consultar la base de conocimiento con GenerateAnswer API y enviar nuevas preguntas sugeridas mediante Train API (como parte del aprendizaje activo).

Uso de esta base de conocimiento de ejemplo

La base de conocimiento de este inicio rápido comienza con 2 pares conversacionales de QnA cuyo objetivo de simplificar el ejemplo y tener identificadores muy predecibles para usar en el método de actualización, de forma que se asocien los avisos de seguimiento con las preguntas a nuevos pares. Esta actividad se planificó e implementó en un orden específico para este inicio rápido.

Si planea desarrollar la base de conocimiento a lo largo del tiempo con avisos de seguimiento que dependen de los pares de QnA existentes, puede elegir:

  • En el caso de bases de conocimiento más grandes, administrar la base de conocimiento en un editor de texto o en una herramienta TSV que admita automatización y, luego, reemplazar por completo la base de conocimiento inmediatamente con una actualización.
  • En el caso de bases de conocimiento más pequeñas, administrar los avisos de seguimiento por completo en el portal de QnA Maker.

Detalles sobre los pares de QnA usados en este inicio rápido:

  • Tipos de pares de QnA: hay 2 tipos de pares de QnA en esta base de conocimiento, después de la actualización: chitchat e información específica del dominio. Esto es habitual si la base de conocimiento está asociada a una aplicación de conversación, como un bot de chat.
  • Aunque las respuestas de la base de conocimiento se pueden filtrar por metadatos o mediante el uso de mensajes de seguimiento, en este inicio rápido no se muestra eso. Busque esos ejemplos de generateAnswer independientes del lenguaje aquí.
  • Aunque el texto de respuesta tiene el formato Markdown y puede contener una gran variedad de contenido de Markdown, como imágenes (imágenes disponibles públicamente basadas en Internet), vínculos (a direcciones URL disponibles públicamente) y viñetas, este inicio rápido no usa esa variedad.

Modelo de objetos QnAMakerClient

El cliente de QnA Maker de creación es un objeto QnAMakerClient que se autentica en Azure mediante Microsoft.Rest.ServiceClientCredentials, que contiene la clave.

Una vez creado el cliente, utilice la propiedad Knowledge base para crear, administrar y publicar la base de conocimiento.

Administre la base de conocimiento mediante el envío de un objeto JSON. En el caso de operaciones inmediatas, un método suele devolver un objeto JSON que indica el estado. En el caso de operaciones de ejecución prolongada, la respuesta es el identificador de la operación. Llame al método client.Operations.GetDetailsAsync con el identificador de la operación para determinar el estado de la solicitud.

Modelo de objetos QnAMakerRuntimeClient

El cliente de QnA Maker de predicción es un objeto QnAMakerRuntimeClient que se autentica en Azure mediante Microsoft.Rest.ServiceClientCredentials, que contiene la clave de tiempo de ejecución de predicción, devuelta por la llamada del cliente de creación, client.EndpointKeys.GetKeys una vez publicada la base de conocimiento.

Use el método GenerateAnswer para obtener una respuesta del tiempo de ejecución de la consulta.

Ejemplos de código

Estos fragmentos de código muestran cómo realizar las siguientes acciones con la biblioteca cliente de QnA Maker para .NET:

Autenticación del cliente para la creación de la base de conocimiento

Cree una instancia de un objeto de cliente con la clave y úsela con el recurso para construir el punto de conexión para crear un QnAMakerClient con el punto de conexión y la clave. Cree un objeto ServiceClientCredentials.

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

Creación de una base de conocimientos

Una base de conocimiento almacena pares de preguntas y respuestas para el objeto CreateKbDTO procedentes de tres orígenes:

  • Para contenido editorial, use el objeto QnADTO.
    • Para usar metadatos y avisos de seguimiento, utilice el contexto editorial, ya que estos datos se agregan en el nivel de un par de QnA individual.
  • Para archivos, use el objeto FileDTO. El objeto FileDTO incluye el nombre de archivo así como la dirección URL pública para llegar al archivo.
  • En el caso de las direcciones URL, use una lista de cadenas para representar las direcciones URL disponibles públicamente.

El paso de creación también incluye las propiedades de la base de conocimiento:

  • defaultAnswerUsedForExtraction: lo que se devuelve cuando no se encuentra ninguna respuesta.
  • enableHierarchicalExtraction: crea automáticamente relaciones de mensajes entre los pares de QnA extraídos.
  • language: al crear la primera base de conocimiento de un recurso, establezca el lenguaje que se va a usar en el índice de Azure Search.

Llame al método CreateAsync y, a continuación, pase el identificador de operación devuelto al método MonitorOperation para sondear el estado.

La última línea del código siguiente devuelve el identificador de la base de conocimiento de la respuesta 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);
}

Asegúrese de incluir la función MonitorOperation, a la que se hace referencia en el código anterior, con el fin de crear correctamente una base de conocimiento.

Actualización de una base de conocimientos

Puede actualizar una base de conocimiento pasando el identificador de la base de conocimiento y un UpdatekbOperationDTO que contiene los objetos de DTO add, update y delete al método UpdateAsync. Use el método MonitorOperation para determinar si la actualización se realizó correctamente.

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

Asegúrese de incluir la función MonitorOperation, a la que se hace referencia en el código anterior, con el fin de actualizar correctamente una knowledge base.

Descarga de una base de conocimiento

Use el método DownloadAsync para descargar la base de datos como una lista de QnADocumentsDTO. Esto no equivale a las exportaciones del portal de QnA Maker desde la página Configuración ya que el resultado de este método no es un archivo.

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
}

Publicación de una base de conocimientos

Publique la base de conocimiento mediante el método PublishAsync. Este método toma el modelo actual guardado y entrenado, al que hace referencia el identificador de la base de conocimiento, y lo publica en el punto de conexión. Este es un paso necesario para consultar la base de conocimiento.

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

Obtención de la clave de tiempo de ejecución de consulta

Una vez publicada una base de conocimiento, necesita la clave de tiempo de ejecución de consulta para consultar el tiempo de ejecución. Esta clave no es la misma que la que se usa para crear el objeto de cliente original.

Use el método EndpointKeys para obtener la clase EndpointKeysDTO.

Use cualquiera de las propiedades de clave devueltas en el objeto para consultar la base de conocimiento.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

Se necesita una clave de tiempo de ejecución para consultar la base de conocimiento.

Autenticación del tiempo de ejecución para generar una respuesta

Cree un QnAMakerRuntimeClient para consultar la base de conocimiento con el fin de generar una respuesta o entrenar el aprendizaje activo.

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

Use QnAMakerRuntimeClient para:

  • Obtener una respuesta de la base de conocimiento
  • Enviar nuevas preguntas sugeridas a la base de conocimiento para el aprendizaje activo.

Generación de una respuesta de la base de conocimiento

Genere una respuesta a partir de una base de conocimiento publicada mediante el método RuntimeClient.GenerateAnswerAsync. Este método acepta el identificador de la base de conocimiento y QueryDTO. Obtenga acceso a las propiedades adicionales de QueryDTO, como Top y Context que se usarán en el bot de chat.

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
}

Este es un ejemplo sencillo de consulta de la base de conocimiento. Para comprender los escenarios de consulta avanzados, revise otros ejemplos de consulta.

Eliminación de una base de conocimiento

Elimine la base de conocimiento mediante el método DeleteAsync con un parámetro del identificador de la base de conocimiento.

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

Obtención del estado de una operación

Algunos métodos, como Create y Update, pueden tardar bastante tiempo en que en lugar de esperar a que finalice el proceso, se devuelva una operación. Use el identificador de la operación para realizar un sondeo (con lógica de reintento) para determinar el estado del método original.

El bucle y Task.Delay del siguiente bloque de código se utilizan para simular una lógica de reintentos. Estos deben reemplazarse por su propia lógica de reintentos.

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

Ejecución de la aplicación

Ejecute la aplicación con el comando dotnet run desde el directorio de la aplicación.

dotnet run

El código fuente de este ejemplo está disponible en GitHub.

Use la biblioteca cliente de QnA Maker para Node.js con los siguientes fines:

  • Crear una base de conocimiento
  • Actualizar una base de conocimiento
  • Publicar una base de conocimiento
  • Obtener la clave del punto de conexión de tiempo de ejecución de predicción
  • Espera de una tarea de ejecución prolongada
  • Descargar una base de conocimiento
  • Obtener una respuesta de una base de conocimiento
  • Eliminación de una base de conocimiento

Documentación de referencia | Paquete (npm) | Ejemplos de Node.js

Nota:

Los nuevos recursos creados después del 1 de julio de 2019 usarán nombres de subdominio personalizados. Para obtener más información y una lista completa de puntos finales regionales, consulte Nombres de subdominios personalizados para los servicios de Azure AI.

Requisitos previos

  • Una suscripción a Azure: cree una cuenta gratuita
  • La versión actual de Node.js.
  • Cuando tenga la suscripción a Azure, cree un recurso de QnA Maker en Azure Portal para obtener la clave de creación y el recurso. Tras su implementación, seleccione Ir al recurso.
    • Necesitará la clave y el nombre del recurso que cree para conectar la aplicación a QnA Maker API. En una sección posterior de este mismo inicio rápido pegue la clave y el nombre del recurso en el código siguiente.
    • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.

Instalación

Creación de una aplicación Node.js

En una ventana de la consola (como cmd, PowerShell o Bash), cree un directorio para la aplicación y vaya a él.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Ejecute el comando npm init -y para crear una aplicación de nodo con un archivo package.json.

npm init -y

Instalación de la biblioteca cliente

Instale los siguientes paquetes NPM:

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

El archivo package.json de la aplicación se actualiza con las dependencias.

Cree un archivo llamado index.js e importe las bibliotecas siguientes:

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

Cree una variable para la clave de Azure y el nombre del recurso.

  • Se puede usar la clave de suscripción y la clave de creación indistintamente. Para más información sobre la clave de creación, siga las indicaciones de Claves de QnA Maker.

  • El valor de QNA_MAKER_ENDPOINT tiene el formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Vaya a Azure Portal y busque el recurso de QnA Maker que creó en los requisitos previos. Seleccione la página Keys and Endpoint (Claves y punto de conexión), en Administración de recursos para buscar la clave de creación (suscripción) y el punto de conexión de QnA Maker.

Punto de conexión de creación de QnA Maker

  • El valor de QNA_MAKER_RUNTIME_ENDPOINT tiene el formato https://YOUR-RESOURCE-NAME.azurewebsites.net. Vaya a Azure Portal y busque el recurso de QnA Maker que creó en los requisitos previos. Seleccione la página Exportar plantilla, en Automatización, para buscar el punto de conexión en tiempo de ejecución.

Punto de conexión en tiempo de ejecución de QnA Maker

Importante

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública. En el caso de producción, use una forma segura de almacenar sus credenciales y acceder a ellas, como Azure Key Vault. Consulte el artículo Seguridad de servicios de Azure AI para más información.

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

Modelos de objetos

QnA Maker usa dos modelos de objetos diferentes:

  • QnAMakerClient , el objeto para crear, administrar, publicar y descargar la base de conocimiento.
  • QnAMakerRuntime , el objeto para consultar la base de conocimiento con GenerateAnswer API y enviar nuevas preguntas sugeridas mediante Train API (como parte del aprendizaje activo).

Modelo de objetos QnAMakerClient

El cliente de QnA Maker es un objeto QnAMakerClient que se autentica en Azure mediante sus credenciales y que contiene la clave.

Una vez creado el cliente, utilice la propiedad knowledgebase para crear, administrar y publicar la base de conocimiento.

Administre la base de conocimiento mediante el envío de un objeto JSON. En el caso de operaciones inmediatas, un método suele devolver un objeto JSON que indica el estado. En el caso de operaciones de ejecución prolongada, la respuesta es el identificador de la operación. Llame al método client.operations.getDetails con el identificador de la operación para determinar el estado de la solicitud.

Modelo de objetos QnAMakerRuntimeClient

El cliente de QnA Maker de predicción es un objeto QnAMakerRuntimeClient que se autentica en Azure mediante Microsoft.Rest.ServiceClientCredentials, que contiene la clave de tiempo de ejecución de predicción que devuelve la llamada del cliente de creación, client.EndpointKeys.getKeys, una vez publicada la base de conocimiento.

Ejemplos de código

Estos fragmentos de código muestran cómo realizar las siguientes acciones con la biblioteca cliente de QnA Maker para .NET:

Autenticación del cliente para la creación de la base de conocimiento

Cree una instancia de un cliente con la clave y el punto de conexión. Cree un objeto ServiceClientCredentials con la clave y úselo con el punto de conexión para crear un objeto 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);

Creación de una base de conocimientos

Una base de conocimiento almacena pares de preguntas y respuestas para el objeto CreateKbDTO procedentes de tres orígenes:

  • Para contenido editorial, use el objeto QnADTO.
    • Para usar metadatos y avisos de seguimiento, utilice el contexto editorial, ya que estos datos se agregan en el nivel de un par de QnA individual.
  • Para archivos, use el objeto FileDTO. El objeto FileDTO incluye el nombre de archivo así como la dirección URL pública para llegar al archivo.
  • En el caso de las direcciones URL, use una lista de cadenas para representar las direcciones URL disponibles públicamente.

El paso de creación también incluye las propiedades de la base de conocimiento:

  • defaultAnswerUsedForExtraction: lo que se devuelve cuando no se encuentra ninguna respuesta.
  • enableHierarchicalExtraction: crea automáticamente relaciones de mensajes entre los pares de QnA extraídos.
  • language: al crear la primera base de conocimiento de un recurso, establezca el lenguaje que se va a usar en el índice de Azure Search.

Llame al método create con la información de la base de conocimiento. La información de la base de conocimiento es básicamente un objeto JSON.

Cuando el método create realice una devolución, pase el identificador de la operación devuelta al método wait_for_operation para sondear el estado. El método wait_for_operation devuelve una salida cuando finaliza la operación. Analice el valor del encabezado resourceLocation de la operación devuelta para obtener el nuevo identificador de la base de conocimiento.

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

Asegúrese de incluir la función wait_for_operation, a la que se hace referencia en el código anterior, con el fin de crear correctamente una base de conocimiento.

Actualización de una base de conocimientos

Para actualizar una base de conocimiento, pase el identificador de la base de conocimiento y un objeto UpdateKbOperationDTO que contenga los objetos de DTO add, update y delete al método update. Los DTO son también básicamente objetos JSON. Use el método wait_for_operation para determinar si la actualización se realizó correctamente.

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
}

Asegúrese de incluir la función wait_for_operation, a la que se hace referencia en el código anterior, con el fin de actualizar correctamente una base de conocimiento.

Descarga de una base de conocimiento

Use el método download para descargar la base de datos como una lista de QnADocumentsDTO. Esto no equivale a las exportaciones del portal de QnA Maker desde la página Configuración ya que el resultado de este método no es un archivo 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
}

Publicación de una base de conocimientos

Publique la base de conocimiento mediante el método publish. Esto toma el modelo actual guardado y entrenado, al que hace referencia el identificador de la base de conocimiento, y lo publica en un punto de conexión. Compruebe el código de respuesta HTTP para validar que la publicación se haya realizado correctamente.

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
}

Consulta de una base de conocimiento

Obtención de la clave de tiempo de ejecución de consulta

Una vez publicada una base de conocimiento, necesita la clave de tiempo de ejecución de consulta para consultar el tiempo de ejecución. Esta clave no es la misma que la que se usa para crear el objeto de cliente original.

Use el método EndpointKeys.getKeys para obtener la clase EndpointKeysDTO.

Use cualquiera de las propiedades de clave devueltas en el objeto para consultar la base de conocimiento.

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
}

Autenticación del tiempo de ejecución para generar una respuesta

Cree un QnAMakerRuntimeClient para consultar la base de conocimiento con el fin de generar una respuesta o entrenar el aprendizaje activo.

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

Use QnAMakerRuntimeClient para obtener una respuesta de la base de conocimiento o enviar a esta nuevas preguntas sugeridas para el aprendizaje activo.

Generación de una respuesta de la base de conocimiento

Genere una respuesta a partir de una base de conocimiento publicada mediante el método RuntimeClient.runtime.generateAnswer. Este método acepta el identificador de la base de conocimiento y QueryDTO. Acceda a las propiedades adicionales de QueryDTO, como Top y Context, que se usarán en el bot de chat.

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

}

Este es un ejemplo sencillo de consulta de la base de conocimiento. Para comprender los escenarios de consulta avanzados, revise otros ejemplos de consulta.

Eliminación de una base de conocimiento

Elimine la base de conocimiento con el método delete y el parámetro del identificador de la base de conocimiento.

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
}

Obtención del estado de una operación

Algunos métodos, como Create y Update, pueden tardar bastante tiempo en que en lugar de esperar a que finalice el proceso, se devuelva una operación. Use el identificador de la operación para realizar un sondeo (con lógica de reintento) para determinar el estado del método original.

La llamada delayTimer del siguiente bloque de código se usa para simular la lógica de reintentos. Reemplácela por su propia lógica de reintentos.

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

Ejecución de la aplicación

Ejecute la aplicación con el comando node index.js desde el directorio de la aplicación.

node index.js

El código fuente de este ejemplo está disponible en GitHub.

Use la biblioteca cliente de QnA Maker para Python para:

  • Crear una base de conocimiento
  • Actualizar una base de conocimiento
  • Publicar una base de conocimiento
  • Obtener la clave del punto de conexión de tiempo de ejecución de predicción
  • Espera de una tarea de ejecución prolongada
  • Descargar una base de conocimiento
  • Obtener una respuesta de una base de conocimiento
  • Eliminación de una base de conocimiento

Documentación de referencia | Código fuente de la biblioteca | Paquete (PyPi) | Ejemplos de Python

Nota

Los nuevos recursos creados después del 1 de julio de 2019 usarán nombres de subdominio personalizados. Para obtener más información y una lista completa de puntos finales regionales, consulte Nombres de subdominios personalizados para los servicios de Azure AI.

Requisitos previos

Nota:

Esta documentación no se aplica a la versión más reciente. Para obtener información sobre el uso de la API de Python en la versión más reciente, consulte el inicio rápido de Python de respuesta a preguntas.

  • Una suscripción a Azure: cree una cuenta gratuita
  • Python 3.x
  • Cuando tenga la suscripción a Azure, cree un recurso de QnA Maker en Azure Portal para obtener la clave de creación y el punto de conexión. Tras su implementación, seleccione Ir al recurso.
    • Necesitará la clave y el punto de conexión del recurso que cree para conectar la aplicación a QnA Maker API. En una sección posterior de este mismo inicio rápido pegará la clave y el punto de conexión en el código siguiente.
    • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.

Instalación

Instalación de la biblioteca cliente

Después de instalar Python, puede instalar la biblioteca cliente con:

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

Creación de una nueva aplicación de Python

Cree un archivo de Python denominado quickstart-file.py e importe las bibliotecas siguientes.

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

Cree variables para el punto de conexión y la clave de Azure del recurso.

  • Se puede usar la clave de suscripción y la clave de creación indistintamente. Para más información sobre la clave de creación, siga las indicaciones de Claves de QnA Maker.

  • El valor de QNA_MAKER_ENDPOINT tiene el formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Vaya a Azure Portal y busque el recurso de QnA Maker que creó en los requisitos previos. Seleccione la página Keys and Endpoint (Claves y punto de conexión), en Administración de recursos para buscar la clave de creación (suscripción) y el punto de conexión de QnA Maker.

Punto de conexión de creación de QnA Maker

  • El valor de QNA_MAKER_RUNTIME_ENDPOINT tiene el formato https://YOUR-RESOURCE-NAME.azurewebsites.net. Vaya a Azure Portal y busque el recurso de QnA Maker que creó en los requisitos previos. Seleccione la página Exportar plantilla, en Automatización, para buscar el punto de conexión en tiempo de ejecución.

Punto de conexión en tiempo de ejecución de QnA Maker

Importante

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública. En el caso de producción, use una forma segura de almacenar sus credenciales y acceder a ellas, como Azure Key Vault. Consulte el artículo Seguridad de servicios de Azure AI para más información.

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'

Modelos de objetos

QnA Maker usa dos modelos de objetos diferentes:

  • QnAMakerClient , el objeto para crear, administrar, publicar y descargar la base de conocimiento.
  • QnAMakerRuntime , el objeto para consultar la base de conocimiento con GenerateAnswer API y enviar nuevas preguntas sugeridas mediante Train API (como parte del aprendizaje activo).

Uso de esta base de conocimiento de ejemplo

La base de conocimiento de este inicio rápido comienza con 2 pares conversacionales de QnA cuyo objetivo de simplificar el ejemplo y tener identificadores muy predecibles para usar en el método de actualización, de forma que se asocien los avisos de seguimiento con las preguntas a nuevos pares. Esta actividad se planificó e implementó en un orden específico para este inicio rápido.

Si planea desarrollar la base de conocimiento a lo largo del tiempo con avisos de seguimiento que dependen de los pares de QnA existentes, puede elegir:

  • En el caso de bases de conocimiento más grandes, administrar la base de conocimiento en un editor de texto o en una herramienta TSV que admita automatización y, luego, reemplazar por completo la base de conocimiento inmediatamente con una actualización.
  • En el caso de bases de conocimiento más pequeñas, administrar los avisos de seguimiento por completo en el portal de QnA Maker.

Detalles sobre los pares de QnA usados en este inicio rápido:

  • Tipos de pares de QnA: hay 2 tipos de pares de QnA en esta base de conocimiento, después de la actualización: chitchat e información específica del dominio. Esto es habitual si la base de conocimiento está asociada a una aplicación de conversación, como un bot de chat.
  • Aunque las respuestas de la base de conocimiento se pueden filtrar por metadatos o mediante el uso de mensajes de seguimiento, en este inicio rápido no se muestra eso. Busque esos ejemplos de generateAnswer independientes del lenguaje aquí.
  • Aunque el texto de respuesta tiene el formato Markdown y puede contener una gran variedad de contenido de Markdown, como imágenes (imágenes disponibles públicamente basadas en Internet), vínculos (a direcciones URL disponibles públicamente) y viñetas, este inicio rápido no usa esa variedad.

Modelo de objetos QnAMakerClient

El cliente de QnA Maker de creación es un objeto QnAMakerClient que se autentica en Azure mediante Microsoft.Rest.ServiceClientCredentials, que contiene la clave.

Una vez creado el cliente, utilice la propiedad Knowledge base para crear, administrar y publicar la base de conocimiento.

Administre la base de conocimiento mediante el envío de un objeto JSON. En el caso de operaciones inmediatas, un método suele devolver un objeto JSON que indica el estado. En el caso de operaciones de ejecución prolongada, la respuesta es el identificador de la operación. Llame al método operations.get_details con el identificador de la operación para determinar el estado de la solicitud.

Modelo de objetos QnAMakerRuntimeClient

El cliente de QnA Maker de predicción es un objeto QnAMakerRuntimeClient que se autentica en Azure mediante Microsoft.Rest.ServiceClientCredentials, que contiene la clave de tiempo de ejecución de predicción que devuelve la llamada del cliente de creación, client.EndpointKeysOperations.get_keys, una vez publicada la base de conocimiento.

Use el método generate_answer para obtener una respuesta del tiempo de ejecución de la consulta.

Autenticación del cliente para la creación de la base de conocimiento

Cree una instancia de un cliente con la clave y el punto de conexión. Cree un objeto CognitiveServicesCredentials con la clave y úselo con el punto de conexión para crear un objeto QnAMakerClient.

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

Creación de una base de conocimientos

Use el objeto de cliente para obtener un objeto de operaciones de base de conocimiento.

Una base de conocimiento almacena pares de preguntas y respuestas para el objeto CreateKbDTO procedentes de tres orígenes:

  • Para contenido editorial, use el objeto QnADTO.
    • Para usar metadatos y avisos de seguimiento, utilice el contexto editorial, ya que estos datos se agregan en el nivel de un par de QnA individual.
  • Para archivos, use el objeto FileDTO. El objeto FileDTO incluye el nombre de archivo así como la dirección URL pública para llegar al archivo.
  • En el caso de las direcciones URL, use una lista de cadenas para representar las direcciones URL disponibles públicamente.

Llame al método create y, luego, pase el identificador de operación devuelto al método Operations.getDetails para sondear el estado.

La última línea del código siguiente devuelve el identificador de la base de conocimiento de la respuesta 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

Asegúrese de incluir la función _monitor_operation, a la que se hace referencia en el código anterior, con el fin de crear correctamente una base de conocimiento.

Actualización de una base de conocimientos

Para actualizar una base de conocimiento, pase el identificador de la base de conocimiento y un objeto UpdateKbOperationDTO que contenga los objetos de DTO add, update y delete al método update. Use el método Operation.getDetail para determinar si la actualización se realizó correctamente.

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

Asegúrese de incluir la función _monitor_operation, a la que se hace referencia en el código anterior, con el fin de actualizar correctamente una base de conocimiento.

Descarga de una base de conocimiento

Use el método download para descargar la base de datos como una lista de QnADocumentsDTO. Esto no equivale a las exportaciones del portal de QnA Maker desde la página Configuración ya que el resultado de este método no es un archivo 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)))

Publicación de una base de conocimientos

Publique la base de conocimiento mediante el método publish. Esto toma el modelo actual guardado y entrenado, al que hace referencia el identificador de la base de conocimiento, y lo publica en un punto de conexión.

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

Consulta de una base de conocimiento

Obtención de la clave de tiempo de ejecución de consulta

Una vez publicada una base de conocimiento, necesita la clave de tiempo de ejecución de consulta para consultar el tiempo de ejecución. Esta clave no es la misma que la que se usa para crear el objeto de cliente original.

Use el método EndpointKeysOperations.get_keys para obtener la clase EndpointKeysDTO.

Use cualquiera de las propiedades de clave devueltas en el objeto para consultar la base de conocimiento.

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

Autenticación del tiempo de ejecución para generar una respuesta

Cree un QnAMakerRuntimeClient para consultar la base de conocimiento con el fin de generar una respuesta o entrenar el aprendizaje activo.

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

Use QnAMakerRuntimeClient para obtener una respuesta de la base de conocimiento o enviar a esta nuevas preguntas sugeridas para el aprendizaje activo.

Generación de una respuesta de la base de conocimiento

Genere una respuesta a partir de una base de conocimiento publicada mediante el método QnAMakerRuntimeClient.runtime.generate_answer. Este método acepta el identificador de la base de conocimiento y QueryDTO. Acceda a las propiedades adicionales de QueryDTO, como Top y Context, que se usarán en el bot de chat.

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

Este es un ejemplo sencillo de consulta de la base de conocimiento. Para comprender los escenarios de consulta avanzados, revise otros ejemplos de consulta.

Eliminación de una base de conocimiento

Elimine la base de conocimiento con el método delete y el parámetro del identificador de la base de conocimiento.

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

Obtención del estado de una operación

Algunos métodos, como Create y Update, pueden tardar bastante tiempo en que en lugar de esperar a que finalice el proceso, se devuelva una operación. Use el identificador de la operación para realizar un sondeo (con lógica de reintento) para determinar el estado del método original.

La llamada setTimeout del siguiente bloque de código se usa para simular código asincrónico. Reemplácela por la lógica de reintento.

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

Ejecución de la aplicación

Ejecute la aplicación con el comando de python en el archivo de inicio rápido.

python quickstart-file.py

El código fuente de este ejemplo está disponible en GitHub.

Use la biblioteca cliente de QnA Maker para Java para:

  • Crear una base de conocimiento
  • Actualizar una base de conocimiento
  • Publicar una base de conocimiento
  • Obtener la clave del punto de conexión de tiempo de ejecución de predicción
  • Espera de una tarea de ejecución prolongada
  • Descargar una base de conocimiento
  • Obtener una respuesta de una base de conocimiento
  • Eliminación de una base de conocimiento

Código fuente de la biblioteca | Paquete | Ejemplos

Nota

Los nuevos recursos creados después del 1 de julio de 2019 usarán nombres de subdominio personalizados. Para obtener más información y una lista completa de puntos finales regionales, consulte Nombres de subdominios personalizados para los servicios de Azure AI.

Requisitos previos

  • Una suscripción a Azure: cree una cuenta gratuita
  • JDK
  • Cuando tenga la suscripción a Azure, cree un recurso de QnA Maker en Azure Portal para obtener la clave de creación y el punto de conexión. Tras su implementación, seleccione Ir al recurso.
    • Necesitará la clave y el punto de conexión del recurso que cree para conectar la aplicación a QnA Maker API. Más adelante en este inicio rápido, debe pegar la clave y el punto de conexión en el código que se incluye a continuación.
    • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.

Instalación

Instalación de las bibliotecas cliente

Después de instalar Java, puede instalar las bibliotecas cliente mediante Maven desde el repositorio de Maven.

Creación de una aplicación Java

Cree un archivo llamado quickstart.java e importe las bibliotecas siguientes.

/* 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.*;

Cree variables para el punto de conexión y la clave de Azure del recurso.

  • Se puede usar la clave de suscripción y la clave de creación indistintamente. Para más información sobre la clave de creación, siga las indicaciones de Claves de QnA Maker.

  • El valor de QNA_MAKER_ENDPOINT tiene el formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Vaya a Azure Portal y busque el recurso de QnA Maker que creó en los requisitos previos. Seleccione la página Keys and Endpoint (Claves y punto de conexión), en Administración de recursos para buscar la clave de creación (suscripción) y el punto de conexión de QnA Maker.

Punto de conexión de creación de QnA Maker

  • El valor de QNA_MAKER_RUNTIME_ENDPOINT tiene el formato https://YOUR-RESOURCE-NAME.azurewebsites.net. Vaya a Azure Portal y busque el recurso de QnA Maker que creó en los requisitos previos. Seleccione la página Exportar plantilla, en Automatización, para buscar el punto de conexión en tiempo de ejecución.

Punto de conexión en tiempo de ejecución de QnA Maker

Importante

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública. En el caso de producción, use una forma segura de almacenar sus credenciales y acceder a ellas, como Azure Key Vault. Consulte el artículo Seguridad de servicios de Azure AI para más información.

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

Modelos de objetos

QnA Maker usa dos modelos de objetos diferentes:

  • QnAMakerClient , el objeto para crear, administrar, publicar y descargar la base de conocimiento.
  • QnAMakerRuntime , el objeto para consultar la base de conocimiento con GenerateAnswer API y enviar nuevas preguntas sugeridas mediante Train API (como parte del aprendizaje activo).

Uso de esta base de conocimiento de ejemplo

La base de conocimiento de este inicio rápido comienza con 2 pares conversacionales de QnA cuyo objetivo de simplificar el ejemplo y tener identificadores muy predecibles para usar en el método de actualización, de forma que se asocien los avisos de seguimiento con las preguntas a nuevos pares. Esta actividad se planificó e implementó en un orden específico para este inicio rápido.

Si planea desarrollar la base de conocimiento a lo largo del tiempo con avisos de seguimiento que dependen de los pares de QnA existentes, puede elegir:

  • En el caso de bases de conocimiento más grandes, administrar la base de conocimiento en un editor de texto o en una herramienta TSV que admita automatización y, luego, reemplazar por completo la base de conocimiento inmediatamente con una actualización.
  • En el caso de bases de conocimiento más pequeñas, administrar los avisos de seguimiento por completo en el portal de QnA Maker.

Detalles sobre los pares de QnA usados en este inicio rápido:

  • Tipos de pares de QnA: hay 2 tipos de pares de QnA en esta base de conocimiento, después de la actualización: chitchat e información específica del dominio. Esto es habitual si la base de conocimiento está asociada a una aplicación de conversación, como un bot de chat.
  • Aunque las respuestas de la base de conocimiento se pueden filtrar por metadatos o mediante el uso de mensajes de seguimiento, en este inicio rápido no se muestra eso. Busque esos ejemplos de generateAnswer independientes del lenguaje aquí.
  • Aunque el texto de respuesta tiene el formato Markdown y puede contener una gran variedad de contenido de Markdown, como imágenes (imágenes disponibles públicamente basadas en Internet), vínculos (a direcciones URL disponibles públicamente) y viñetas, este inicio rápido no usa esa variedad.

Modelo de objetos QnAMakerClient

El cliente de QnA Maker de creación es un objeto QnAMakerClient que se autentica en Azure mediante MsRest::ServiceClientCredentials, que contiene la clave.

Una vez creado el cliente, use los métodos de la propiedad Knowledgebases del cliente para crear, administrar y publicar la base de conocimiento.

En el caso de las operaciones inmediatas, un método suele devolver el resultado, si lo hay. En el caso de operaciones de ejecución prolongada, la respuesta es un objeto Operation. Llame al método getDetails con el valor operation.operationId para determinar el estado de la solicitud.

Modelo de objetos QnAMakerRuntimeClient

El cliente de QnA Maker en tiempo de ejecución es un objeto QnAMakerRuntimeClient.

Después de publicar la base de conocimiento mediante el cliente de creación, use el método generateAnswer del cliente en tiempo de ejecución para obtener una respuesta de la base de conocimiento.

Puede crear un cliente en tiempo de ejecución mediante una llamada a QnAMakerRuntimeManager.authenticate y pasar una clave de punto de conexión en tiempo de ejecución. Para obtener la clave de punto de conexión en tiempo de ejecución, use el cliente de creación para llamar a getKeys.

Autenticación del cliente para la creación de la base de conocimiento

Cree una instancia de un cliente con el punto de conexión de creación y la clave de suscripción.

/* 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();

Creación de una base de conocimientos

Una base de conocimiento almacena pares de preguntas y respuestas para el objeto CreateKbDTO procedentes de tres orígenes:

  • Para contenido editorial, use el objeto QnADTO.
    • Para usar metadatos y avisos de seguimiento, utilice el contexto editorial, ya que estos datos se agregan en el nivel de un par de QnA individual.
  • Para archivos, use el objeto FileDTO. El objeto FileDTO incluye el nombre de archivo así como la dirección URL pública para llegar al archivo.
  • En el caso de las direcciones URL, use una lista de cadenas para representar las direcciones URL disponibles públicamente.

Llame al método create y, luego, pase la propiedad operationId de la operación devuelta al método getDetails para sondear el estado.

La última línea del código siguiente devuelve el identificador de la base de conocimiento.

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

Actualización de una base de conocimientos

Para actualizar una base de conocimiento, llame a update y pase el identificador de la base de conocimiento y un objeto UpdateKbOperationDTO. Ese objeto a su vez puede contener:

Pase la propiedad operationId de la operación devuelta al método getDetails para sondear el estado.

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.");
}

Descarga de una base de conocimiento

Use el método download para descargar la base de datos como una lista de QnADocumentsDTO. Esto no equivale a las exportaciones del portal de QnA Maker desde la página Configuración ya que el resultado de este método no es un archivo 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");
}

Publicación de una base de conocimientos

Publique la base de conocimiento mediante el método publish. Esto toma el modelo actual guardado y entrenado, al que hace referencia el identificador de la base de conocimiento, y lo publica en un punto de conexión.

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

Generación de una respuesta de la base de conocimiento

Una vez publicada una base de conocimiento, necesita la clave de punto de conexión en tiempo de ejecución para consultar la base de conocimiento. Esta no es la misma que la clave de suscripción que se usa para crear el cliente de creación.

Use el método getKeys para obtener un objeto EndpointKeysDTO.

Cree un cliente en tiempo de ejecución mediante una llamada a QnAMakerRuntimeManager.authenticate y pase una clave de punto de conexión en tiempo de ejecución del objeto EndpointKeysDTO.

Genere una respuesta a partir de una base de conocimiento publicada mediante el método generateAnswer. Este método acepta el identificador de la base de conocimiento y un objeto 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();
}

Este es un ejemplo sencillo de consulta de una base de conocimiento. Para comprender los escenarios de consulta avanzados, revise otros ejemplos de consulta.

Eliminación de una base de conocimiento

Elimine la base de conocimiento con el método delete y el parámetro del identificador de la base de conocimiento.

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

Obtención del estado de una operación

Algunos métodos, como Create y Update, pueden tardar bastante tiempo en que en lugar de esperar a que finalice el proceso, se devuelva una operación. Use el identificador de la operación para realizar un sondeo (con lógica de reintento) para determinar el estado del método original.

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

Ejecución de la aplicación

Este es el método principal de la aplicación.

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

Ejecute la aplicación de la siguiente manera. Esto supone que el nombre de clase es Quickstart y que las dependencias se encuentran en una subcarpeta llamada lib debajo de la carpeta actual.

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

El código fuente de este ejemplo está disponible en GitHub.

Limpieza de recursos

Si quiere limpiar y eliminar una suscripción de servicios de Azure AI, puede eliminar el recurso o el grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

Pasos siguientes

Tutorial: Prueba de la base de conocimiento con un archivo por lotes