Início Rápido: Biblioteca de clientes do QnA Maker

Artigo
01/19/2024

Observação

Azure Open AI on Your Data utiliza LLMs (grandes modelos de linguagem) para produzir resultados semelhantes ao QnA Maker. Se você quiser migrar seu projeto do QnA Maker para o Azure Open AI On Your Data, confira nosso guia.

Introdução à biblioteca de clientes do QnA Maker. Siga essas etapas para instalar o pacote e testar o código de exemplo para tarefas básicas.

Observação

O serviço de QnA Maker está sendo desativado no dia 31 de março de 2025. Uma versão mais recente da funcionalidade de perguntas e respostas agora está disponível como parte da Linguagem de IA do Azure. Para saber mais sobre o recurso de respostas às perguntas no Serviço de Linguagem, confira respostas às perguntas. A partir de 1º de outubro de 2022, você não poderá criar novos recursos de QnA Maker. Para obter informações sobre como migrar bases de dados de conhecimento do QnA Maker existentes para responder à pergunta, consulte o Guia de migração.

Pré-requisitos

Observação

Esta documentação não se aplica à versão mais recente. Para saber mais sobre como usar a API REST com a versão mais recente, confira o guia de início rápido sobre a API de respostas às perguntas

A versão atual do cURL. Várias opções de linha de comando são usadas nos inícios rápidos, indicadas na documentação do cURL.
Você deve ter um Recurso do QnA Maker para usar a chave e o nome do recurso. Você inseriu o Nome do recurso durante a criação dele e a chave foi criada para você. O nome do recurso é usado como o subdomínio para seu ponto de extremidade. Para recuperar a chave e o nome do recurso, selecione Início Rápido para o recurso no portal do Azure. O nome do recurso é o primeiro subdomínio da URL do ponto de extremidade:

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

Cuidado

Os exemplos de BASH a seguir usam o caractere de continuação de linha \. Se o console ou o terminal usar um caractere de continuação de linha diferente, use esse caractere.

Como criar uma base de dados de conhecimento

Para criar uma base de dados de conhecimento com as APIs REST e o cURL, você precisa ter as seguintes informações:

Informações	Configuração cURL	Finalidade
Nome de recursos do QnA Maker	URL	usado para construir a URL
Chave de recursos do QnA Maker	Parâmetro `-h` para o cabeçalho `Ocp-Apim-Subscription-Key`	Autenticar-se no serviço QnA Maker
JSON que descreve a base de dados de conhecimento	Parâmetro `-d`	Exemplos de JSON
Tamanho do JSON em bytes	Parâmetro `-h` para o cabeçalho `Content-Size`

O comando cURL é executado em um shell BASH. Edite esse comando com os valores de nome de recurso, chave de recurso e JSON e o tamanho do 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"]}'

A resposta de cURL do QnA Maker inclui o operationId, que é necessário para obter o status da operação.

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

Obter o status da operação

Quando você cria uma base de dados de conhecimento, como a operação é assíncrona, a resposta inclui informações para determinar o status.

Informações	Configuração cURL	Finalidade
Nome de recursos do QnA Maker	URL	usado para construir a URL
ID da operação	Roteamento de URL	`/operations/REPLACE-WITH-YOUR-OPERATION-ID`
Chave de recursos do QnA Maker	Parâmetro `-h` para o cabeçalho `Ocp-Apim-Subscription-Key`	Autenticar-se no serviço QnA Maker

O comando cURL é executado em um shell BASH. Edite esse comando com o próprio nome de recurso, a chave de recurso e a ID da operação.

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"

A resposta de cURL inclui o status. Se o estado da operação for bem-sucedido, o resourceLocation incluirá a ID da base de dados de conhecimento.

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

Publicar base de dados de conhecimento

Antes de consultar a base de dados de conhecimento, você precisa:

Publicar base de dados de conhecimento
Obter a chave de ponto de extremidade do runtime

Esta tarefa publica a base de dados de conhecimento. Obter a chave de ponto de extremidade do runtime é uma tarefa separada.

Informações	Configuração cURL	Finalidade
Nome de recursos do QnA Maker	URL	usado para construir a URL
Chave de recursos do QnA Maker	Parâmetro `-h` para o cabeçalho `Ocp-Apim-Subscription-Key`	Autenticar-se no serviço QnA Maker
ID da base de dados de conhecimento	Roteamento de URL	`/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID`

O comando cURL é executado em um shell BASH. Edite esse comando com o próprio nome de recurso, a chave de recurso e a ID da base de dados de conhecimento.

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

O status da resposta é 204 sem resultados. Use o parâmetro de linha de comando -v para ver a saída detalhada do comando cURL. Isso incluirá o status HTTP.

Obter a chave de ponto de extremidade do runtime da base de dados de conhecimento

Antes de consultar a base de dados de conhecimento, você precisa:

Publicar base de dados de conhecimento
Obter a chave de ponto de extremidade do runtime

Esta tarefa obtém a chave de ponto de extremidade do runtime. Publicar a base de dados de conhecimento é uma tarefa separada.

A chave de ponto de extremidade do runtime é a mesma chave para todas as bases de dados de conhecimento que usam o recurso do QnA Maker.

Informações	Configuração cURL	Finalidade
Nome de recursos do QnA Maker	URL	usado para construir a URL
Chave de recursos do QnA Maker	Parâmetro `-h` para o cabeçalho `Ocp-Apim-Subscription-Key`	Autenticar-se no serviço QnA Maker

O comando cURL é executado em um shell BASH. Edite esse comando com o próprio nome de recurso e a chave 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"

A resposta de cURL inclui as chaves de ponto de extremidade do runtime. Use apenas uma das chaves ao consultar para obter uma resposta da base de dados de conhecimento.

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

Consultar resposta da base de dados de conhecimento publicada

Obter uma resposta do conhecimento é realizado por meio de um runtime separado do gerenciamento da base de dados de conhecimento. Como é um runtime separado, você precisa autenticar-se com uma chave de runtime.

Informações	Configuração cURL	Finalidade
Nome de recursos do QnA Maker	URL	usado para construir a URL
Chave de runtime do QnA Maker	Parâmetro `-h` para o cabeçalho `Authorization`	A chave faz parte de uma cadeia de caracteres que inclui a palavra `Endpointkey` . Autenticar-se no serviço QnA Maker
ID da base de dados de conhecimento	Roteamento de URL	`/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID`
JSON que descreve a consulta	Parâmetro `-d`	Parâmetros do corpo da solicitação e exemplos de JSON
Tamanho do JSON em bytes	Parâmetro `-h` para o cabeçalho `Content-Size`

O comando cURL é executado em um shell BASH. Edite esse comando com o próprio nome de recurso, a chave de recurso e a ID da base de dados de conhecimento.

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

Uma resposta bem-sucedida inclui a resposta principal, juntamente com outras informações de que um aplicativo cliente, como um bot de chat, precisa para exibir uma resposta para o usuário.

Excluir base de dados de conhecimento

Quando você concluir a base de dados de conhecimento, exclua-a.

Informações	Configuração cURL	Finalidade
Nome de recursos do QnA Maker	URL	usado para construir a URL
Chave de recursos do QnA Maker	Parâmetro `-h` para o cabeçalho `Ocp-Apim-Subscription-Key`	Autenticar-se no serviço QnA Maker
ID da base de dados de conhecimento	Roteamento de URL	`/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID`

O comando cURL é executado em um shell BASH. Edite esse comando com o próprio nome de recurso, a chave de recurso e a ID da base de dados de conhecimento.

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"

O status da resposta é 204 sem resultados. Use o parâmetro de linha de comando -v para ver a saída detalhada do comando cURL. Isso incluirá o status HTTP.

Recursos adicionais

Documentação de referência de criação
Documentação de referência do Runtime
Scripts de BASH de exemplo que usam cURL

Use a biblioteca de clientes do QnA Maker para .NET para:

Criar uma base de dados de conhecimento
Atualizar uma base de dados de conhecimento
Publicar uma base de dados de conhecimento
Obter a chave de ponto de extremidade do runtime de previsão
Aguardar tarefa de execução longa
Baixar uma base de dados de conhecimento
Obter uma resposta de uma base de dados de conhecimento
Excluir uma base de dados de conhecimento

Documentação de referência | Código-fonte da biblioteca | Pacote (NuGet) | Exemplos de C#

Observação

Os novos recursos criados após 1º de julho de 2019 usarão nomes de subdomínio personalizados. Para obter mais informações e uma lista completa de pontos de extremidade regionais, confira Nomes de subdomínio personalizados para os serviços de IA do Azure.

Pré-requisitos

Observação

Esta documentação não se aplica à versão mais recente. Para saber mais sobre como usar a API C# com a versão mais recente, confira o guia de início rápido sobre o C# de respostas às perguntas.

Assinatura do Azure – Criar uma gratuitamente
O IDE do Visual Studio ou a versão atual do .NET Core.
Quando você tiver sua assinatura do Azure, crie um recurso do QnA Maker no portal do Azure para obter a chave de criação e o nome do recurso. Após a implantação, selecione Ir para recurso.
- Você precisará do nome do recurso e da chave do recurso que você criar para conectar o aplicativo à API do QnA Maker. Cole a chave e o nome do recurso no código abaixo mais adiante no guia de início rápido.
- Use o tipo de preço gratuito (F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

Configurando

CLI

Em uma janela de console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo do console com o nome qna-maker-quickstart. Esse comando cria um projeto simples em C# do tipo "Olá, Mundo" com um arquivo de origem único: program.cs.

dotnet new console -n qna-maker-quickstart

Altere o diretório para a pasta do aplicativo recém-criado. É possível criar o aplicativo com:

dotnet build

A saída de compilação não deve conter nenhum aviso ou erro.

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

Dentro do diretório do aplicativo, instale a biblioteca de clientes do QnA Maker para .NET com o seguinte comando:

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

Dica

Deseja exibir todo o arquivo de código do início rápido de uma vez? Você pode encontrá-lo no GitHub, que contém os exemplos de código neste início rápido.

Uso de diretivas

No diretório do projeto, abra o arquivo program.cs e adicione as seguintes diretivas using:

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

Chave de assinatura e pontos de extremidade de recurso

No método Main do aplicativo, adicione as variáveis e o código mostrados na seção a seguir para usar as tarefas comuns neste guia de início rápido.

Usamos a chave de assinatura e a chave de criação de modo intercambiável. Para obter mais detalhes sobre a chave de criação, siga Chaves no QnA Maker.
O valor de QNA_MAKER_ENDPOINT tem o formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Acesse o portal do Azure e localize o recurso do QnA Maker criado nos pré-requisitos. Selecione a página Chaves e ponto de extremidade, em Gerenciamento de recursos, para localizar a Chave de criação (Assinatura) e o Ponto de extremidade do QnA Maker.

Ponto de extremidade de criação do QnA Maker

O valor de QNA_MAKER_RUNTIME_ENDPOINT tem o formato https://YOUR-RESOURCE-NAME.azurewebsites.net. Acesse o portal do Azure e localize o recurso do QnA Maker criado nos pré-requisitos. Selecione a página Exportar modelo, em Automação, para localizar o Ponto de extremidade do Runtime.

Ponto de extremidade do runtime do QnA Maker

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Consulte o artigo sobre segurança do serviços de IA do Azure para obter mais informações.

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 objeto

O QnA Maker usa dois modelos de objeto diferentes:

QnAMakerClient é o objeto usado para criar, gerenciar, publicar e baixar a base de dados de conhecimento.
QnAMakerRuntime é o objeto usado para consultar a base de dados de conhecimento com a API GenerateAnswer e para enviar novas perguntas sugeridas usando a API de Treinamento (como parte do aprendizado ativo).

Usando esta base de dados de conhecimento de exemplo

A base de dados de conhecimento neste guia de início rápido começa com 2 pares de conversa do QnA. Isso é feito de propósito para simplificar o exemplo e ter IDs altamente previsíveis para usar no método de atualização, associando solicitações de acompanhamento com perguntas a novos pares. Isso foi planejado e implementado em uma ordem específica para este guia de início rápido.

Se você planeja desenvolver sua base de dados de conhecimento ao longo do tempo, com solicitações de acompanhamento que dependem de pares do QnA existentes, você pode optar:

Por bases de dados de conhecimento maiores, gerenciar a base de dados de conhecimento em um editor de texto ou na ferramenta TSV com suporte para automação e substituir completamente a base de dados de conhecimento de uma só vez com uma atualização.
Para bases de dados de conhecimento menores, gerenciar as solicitações de acompanhamento inteiramente no portal do QnA Maker.

Detalhes sobre os pares do QnA usados neste guia de início rápido:

Tipos de par do QnA – há dois tipos de pares do QnA nesta base de dados de conhecimento, após a atualização: informações específicas de domínio e conversas. Isso é comum se a base de dados de conhecimento estiver vinculada a um aplicativo de conversa, como um chatbot.
Embora as respostas da base de dados de conhecimento possam ser filtradas por metadados ou usar prompts de acompanhamento, este guia de início rápido não mostra isso. Procure os exemplos generateAnswer independentes de idioma aqui.
O texto de resposta é um Markdown e pode conter uma ampla variedade de Markdown como imagens (imagens baseadas na Internet publicamente disponíveis), links (para URLs disponíveis publicamente) e pontos com marcadores; este guia de início rápido não usa essa variedade.

Modelo de objeto do QnAMakerClient

O cliente de criação do QnA Maker é um objeto QnAMakerClient que é autenticado no Azure usando Microsoft.Rest.ServiceClientCredentials, que contém sua chave.

Após a criação do cliente, use a propriedade da Base de dados de conhecimento para criar, gerenciar e publicar sua base de dados de conhecimento.

Gerencie sua base de dados de conhecimento enviando um objeto JSON. Para operações imediatas, um método geralmente retorna um objeto JSON que indica o status. Para operações de longa execução, a resposta é a ID da operação. Chame o método client.Operations.GetDetailsAsync com a ID da operação para determinar o status da solicitação.

Modelo de objeto do QnAMakerRuntimeClient

O cliente de previsão do QnA Maker é um objeto QnAMakerRuntimeClient que é autenticado no Azure usando Microsoft.Rest.ServiceClientCredentials, que contém sua chave do runtime de previsão, retornada pela chamada do cliente de criação, client.EndpointKeys.GetKeys, após a publicação da base de dados de conhecimento.

Use o método GenerateAnswer para obter uma resposta do runtime da consulta.

Exemplos de código

Estes snippets de códigos mostram como fazer o seguinte com a biblioteca de clientes do QnA Maker para .NET:

Autenticar o cliente de criação
Criar uma base de dados de conhecimento
Atualizar uma base de dados de conhecimento
Baixar uma base de dados de conhecimento
Publicar uma base de dados de conhecimento
Excluir uma base de dados de conhecimento
Obter a chave do runtime de consulta
Obter o status de uma operação
Autenticar o cliente do runtime de consulta
Gerar uma resposta da base de dados de conhecimento

Autenticar o cliente para criar a base de dados de conhecimento

Crie uma instância de um objeto de cliente com sua chave e use esse objeto com seu recurso para construir o ponto de extremidade para criar um QnAMakerClient com o ponto de extremidade e a chave. Crie um objeto ServiceClientCredentials.

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

Como criar uma base de dados de conhecimento

Uma base de dados de conhecimento armazena pares de perguntas e respostas para o objeto CreateKbDTO de três fontes:

Para conteúdo editorial, use o objeto QnADTO.
- Para usar os metadados e as solicitações de acompanhamento, use o contexto editorial, pois esses dados são adicionados no nível do par individual de P e R.
Para arquivos, use o objeto FileDTO. O FileDTO inclui o nome de arquivo e a URL pública para acessar o arquivo.
Em URLs, use uma lista de cadeias de caracteres para representar URLs disponíveis publicamente.

A etapa de criação também inclui propriedades para a base de conhecimento:

defaultAnswerUsedForExtraction – o que é retornado quando nenhuma resposta é encontrada
enableHierarchicalExtraction – criar automaticamente relações de prompt entre pares extraídos do QnA
language – ao criar a primeira base de dados de conhecimento de um recurso, defina o idioma a ser usado no índice do Azure Search.

Chame o método CreateAsync e, em seguida, passe a ID da operação retornada para o método MonitorOperation para sondar o status.

A linha final do código a seguir retorna a ID da base de dados de conhecimento da resposta 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);
}

Inclua a função MonitorOperation, referenciada no código acima, para criar uma base de dados de conhecimento com êxito.

Como atualizar uma base de dados de conhecimento

É possível atualizar uma base de dados de conhecimento passando sua ID e um UpdatekbOperationDTO contendo os objetos add, update e delete DTO para o método UpdateAsync. Use o método MonitorOperation para determinar se a atualização foi bem-sucedida.

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

Certifique-se de incluir a função MonitorOperation, referenciada no código acima, para atualizar uma base de dados de conhecimento com êxito.

Baixar uma base de dados de conhecimento

Use o método DownloadAsync para baixar o banco de dados como uma lista de QnADocumentsDTO. Isso não é equivalente à exportação do portal do QnA Maker da página Configurações do portal, pois o resultado deste método não é um arquivo.

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
}

Como publicar uma base de dados de conhecimento

Publique a base de dados de conhecimento usando o método PublishAsync. Ele usa o modelo salvo e treinado atual, referenciado pela ID da base de dados de conhecimento, e o publica em seu ponto de extremidade. Essa é uma etapa necessária para consultar sua base de conhecimento.

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

Obter a chave do runtime de consulta

Após uma base de dados de conhecimento ser publicada, você precisa da chave do runtime de consulta para consultar o runtime. Ela não é a mesma chave usada para criar o objeto de cliente original.

Use o método EndpointKeys para obter a classe EndpointKeysDTO.

Use qualquer uma das propriedades da chave retornadas no objeto para consultar a base de dados de conhecimento.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

Uma chave de runtime é necessária para consultar sua base de dados de conhecimento.

Autenticar o runtime para gerar uma resposta

Crie um QnAMakerRuntimeClient para consultar a base de dados de conhecimento para gerar uma resposta ou treinar com base em um aprendizado ativo.

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

Use o QnAMakerRuntimeClient para:

obter uma resposta da base de dados de conhecimento
enviar novas perguntas sugeridas à base de dados de conhecimento para aprendizado ativo.

Gerar uma resposta da base de dados de conhecimento

Gere uma resposta de uma base de dados de conhecimento publicada usando o método RuntimeClient.GenerateAnswerAsync. Esse método aceita a ID da base de dados de conhecimento e o QueryDTO. Acesse as propriedades adicionais do QueryDTO, como Superior e Contexto para usar em seu chatbot.

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 é um exemplo simples de consulta à base de dados de conhecimento. Para entender cenários de consulta avançada, confira outros exemplos de consulta.

Excluir uma base de dados de conhecimento

Exclua a base de dados de conhecimento usando o método DeleteAsync com um parâmetro da ID da base de dados de conhecimento.

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

Obter o status de uma operação

Alguns métodos, como criar e atualizar, podem levar tempo suficiente para que, em vez de aguardar a conclusão do processo, uma operação seja retornada. Use a ID da operação para fazer uma sondagem (com lógica de repetição) para determinar o status do método original.

Os elementos loop e Task.Delay no bloco de código a seguir são usados para simular a lógica de repetição. Eles devem ser substituídos por sua própria lógica de repetição.

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

Executar o aplicativo

Execute o aplicativo com o comando dotnet run do seu próprio diretório de aplicativo.

dotnet run

O código-fonte desta amostra pode ser encontrado no GitHub.

Use a biblioteca de clientes do QnA Maker para Node.js para:

Criar uma base de dados de conhecimento
Atualizar uma base de dados de conhecimento
Publicar uma base de dados de conhecimento
Obter a chave de ponto de extremidade do runtime de previsão
Aguardar tarefa de execução longa
Baixar uma base de dados de conhecimento
Obter uma resposta de uma base de dados de conhecimento
Excluir base de dados de conhecimento

Documentação de referência | Pacote (npm) | Amostras de Node.js

Observação

Pré-requisitos

Assinatura do Azure – Criar uma gratuitamente
A versão atual do Node.js.
Quando você tiver sua assinatura do Azure, crie um recurso do QnA Maker no portal do Azure para obter a chave de criação e o recurso. Após a implantação, selecione Ir para recurso.
- Você precisará do nome do recurso e da chave do recurso que você criar para conectar o aplicativo à API do QnA Maker. Cole a chave e o nome do recurso no código abaixo mais adiante no guia de início rápido.
- Use o tipo de preço gratuito (F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

Configurando

Criar um novo aplicativo do Node.js

Em uma janela de console (como cmd, PowerShell ou Bash), crie um novo diretório para seu aplicativo e navegue até ele.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Execute o comando npm init -y para criar um aplicativo do Node com um arquivo package.json.

npm init -y

Instalar a biblioteca de clientes

Instale os seguintes pacotes NPM:

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

O arquivo package.json do seu aplicativo é atualizado com as dependências.

Crie um arquivo chamado index.js e importe as seguintes bibliotecas:

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

Crie uma variável para o nome de recurso e a chave do Azure do seu recurso.

Usamos a chave de assinatura e a chave de criação de modo intercambiável. Para obter mais detalhes sobre a chave de criação, siga Chaves no QnA Maker.
O valor de QNA_MAKER_ENDPOINT tem o formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Acesse o portal do Azure e localize o recurso do QnA Maker criado nos pré-requisitos. Selecione a página Chaves e ponto de extremidade, em Gerenciamento de recursos, para localizar a Chave de criação (Assinatura) e o Ponto de extremidade do QnA Maker.

Ponto de extremidade de criação do QnA Maker

O valor de QNA_MAKER_RUNTIME_ENDPOINT tem o formato https://YOUR-RESOURCE-NAME.azurewebsites.net. Acesse o portal do Azure e localize o recurso do QnA Maker criado nos pré-requisitos. Selecione a página Exportar modelo, em Automação, para localizar o Ponto de extremidade do Runtime.

Ponto de extremidade do runtime do QnA Maker

Importante

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 objeto

O QnA Maker usa dois modelos de objeto diferentes:

QnAMakerClient é o objeto usado para criar, gerenciar, publicar e baixar a base de dados de conhecimento.
QnAMakerRuntime é o objeto usado para consultar a base de dados de conhecimento com a API GenerateAnswer e para enviar novas perguntas sugeridas usando a API de Treinamento (como parte do aprendizado ativo).

Modelo de objeto do QnAMakerClient

O cliente de criação do QnA Maker é um objeto QnAMakerClient que se autentica no Azure usando suas credenciais, que contém sua chave.

Após o cliente ser criado, use a base de dados de conhecimento para criar, gerenciar e publicar sua base de dados de conhecimento.

Gerencie sua base de dados de conhecimento enviando um objeto JSON. Para operações imediatas, um método geralmente retorna um objeto JSON que indica o status. Para operações de longa execução, a resposta é a ID da operação. Chame o método client.operations.getDetails com a ID da operação para determinar o status da solicitação.

Modelo de objeto do QnAMakerRuntimeClient

O cliente de previsão do QnA Maker é um objeto QnAMakerRuntimeClient que é autenticado no Azure usando Microsoft.Rest.ServiceClientCredentials, que contém sua chave do runtime de previsão, retornada pela chamada do cliente de criação, client.EndpointKeys.getKeys, após a publicação da base de dados de conhecimento.

Exemplos de código

Estes snippets de códigos mostram como fazer o seguinte com a biblioteca de clientes do QnA Maker para .NET:

Autenticar o cliente de criação
Criar uma base de dados de conhecimento
Atualizar uma base de dados de conhecimento
Baixar uma base de dados de conhecimento
Publicar uma base de dados de conhecimento
Excluir uma base de dados de conhecimento
Obter a chave do runtime de consulta
Obter o status de uma operação
Autenticar o cliente do runtime de consulta
Gerar uma resposta da base de dados de conhecimento

Autenticar o cliente para criar a base de dados de conhecimento

Instancie um cliente com o ponto de extremidade e a chave. Crie um objeto ServiceClientCredentials com sua chave e use-o com seu ponto de extremidade para criar um 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);

Como criar uma base de dados de conhecimento

Uma base de dados de conhecimento armazena pares de perguntas e respostas para o objeto CreateKbDTO de três fontes:

Para conteúdo editorial, use o objeto QnADTO.
- Para usar os metadados e as solicitações de acompanhamento, use o contexto editorial, pois esses dados são adicionados no nível do par individual de P e R.
Para arquivos, use o objeto FileDTO. O FileDTO inclui o nome de arquivo e a URL pública para acessar o arquivo.
Em URLs, use uma lista de cadeias de caracteres para representar URLs disponíveis publicamente.

A etapa de criação também inclui propriedades para a base de conhecimento:

defaultAnswerUsedForExtraction – o que é retornado quando nenhuma resposta é encontrada
enableHierarchicalExtraction – criar automaticamente relações de prompt entre pares extraídos do QnA
language – ao criar a primeira base de dados de conhecimento de um recurso, defina o idioma a ser usado no índice do Azure Search.

Chame o método create com as informações da base de dados de conhecimento. As informações da base de dados de conhecimento são, basicamente um objeto JSON.

Quando o método create for retornado, passe a ID da operação retornada para o método wait_for_operation para sondar o status. O método wait_for_operation é retornado quando a operação é concluída. Analise o valor do cabeçalho de resourceLocation da operação retornada para obter a nova ID da base de dados de conhecimento.

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

Inclua a função wait_for_operation, referenciada no código acima, para criar uma base de dados de conhecimento com êxito.

Como atualizar uma base de dados de conhecimento

É possível atualizar uma base de dados de conhecimento passando sua ID e um UpdateKbOperationDTO contendo os objetos add, update e delete DTO para o método update. Os DTOs também são, basicamente, objetos JSON. Use o método wait_for_operation para determinar se a atualização foi bem-sucedida.

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
}

Inclua a função wait_for_operation, referenciada no código acima, para atualizar uma base de dados de conhecimento com êxito.

Baixar uma base de dados de conhecimento

Use o método download para baixar o banco de dados como uma lista de QnADocumentsDTO. Isso não é equivalente à exportação do portal do QnA Maker da página Configurações do portal, porque o resultado deste método não é um arquivo 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
}

Como publicar uma base de dados de conhecimento

Publique a base de dados de conhecimento usando o método publish. Ele usa o modelo salvo e treinado atual, referenciado pela ID da base de dados de conhecimento, e o publica em um ponto de extremidade. Verifique o código de resposta HTTP para validar que a publicação foi bem-sucedida.

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
}

Consultar uma base de dados de conhecimento

Obter a chave do runtime de consulta

Após uma base de dados de conhecimento ser publicada, você precisa da chave do runtime de consulta para consultar o runtime. Ela não é a mesma chave usada para criar o objeto cliente original.

Use o método EndpointKeys.getKeys para obter a classe EndpointKeysDTO.

Use qualquer uma das propriedades da chave retornadas no objeto para consultar a base de dados de conhecimento.

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
}

Autenticar o runtime para gerar uma resposta

Crie um QnAMakerRuntimeClient para consultar a base de dados de conhecimento para gerar uma resposta ou treinar com base em um aprendizado ativo.

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

Use o QnAMakerRuntimeClient para obter uma resposta de conhecimento ou para enviar novas perguntas sugeridas para a base de dados de conhecimento, para o aprendizado ativo.

Gerar uma resposta da base de dados de conhecimento

Gere uma resposta de uma base de dados de conhecimento publicada usando o método RuntimeClient.runtime.generateAnswer. Esse método aceita a ID da base de dados de conhecimento e o QueryDTO. Acesse as propriedades adicionais do QueryDTO, como Superior e Contexto, para usar em seu chatbot.

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 é um exemplo simples de consulta à base de dados de conhecimento. Para entender cenários de consulta avançada, confira outros exemplos de consulta.

Excluir uma base de dados de conhecimento

Exclua a base de dados de conhecimento usando o método delete com um parâmetro da ID da base de dados de conhecimento.

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
}

Obter o status de uma operação

A chamada delayTimer no bloco de código a seguir é usada para simular a lógica de repetição. Substitua isso por sua pela lógica de repetição.

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

Executar o aplicativo

Execute o aplicativo com o comando node index.js do seu próprio diretório de aplicativo.

node index.js

O código-fonte desta amostra pode ser encontrado no GitHub.

Use a biblioteca de clientes do QnA Maker para Python para:

Criar uma base de dados de conhecimento
Atualizar uma base de dados de conhecimento
Publicar uma base de dados de conhecimento
Obter a chave de ponto de extremidade do runtime de previsão
Aguardar tarefa de execução longa
Baixar uma base de dados de conhecimento
Obter uma resposta de uma base de dados de conhecimento
Excluir base de dados de conhecimento

Documentação de referência | Código-fonte da biblioteca | Pacote (PyPi) | Exemplos do Python

Observação

Pré-requisitos

Observação

Esta documentação não se aplica à versão mais recente. Para saber mais sobre como usar a API Python com a versão mais recente, confira o guia de início rápido sobre o Python de respostas às perguntas.

Assinatura do Azure – Criar uma gratuitamente
Python 3.x
Quando você tiver sua assinatura do Azure, crie um recurso do QnA Maker no portal do Azure para obter a chave de criação e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
- Você precisará da chave e do ponto de extremidade do recurso que você criar para conectar seu aplicativo à API do QnA Maker. Cole a chave e o ponto de extremidade no código abaixo mais adiante no guia de início rápido.
- Use o tipo de preço gratuito (F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

Configurando

Instalar a biblioteca de clientes

Depois de instalar o Python, você pode instalar a biblioteca de clientes com:

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

Criar um novo aplicativo Python

Crie um arquivo do Python chamado quickstart-file.py e importe as bibliotecas a seguir.

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

Crie variáveis para a chave e o ponto de extremidade do Azure do recurso.

Usamos a chave de assinatura e a chave de criação de modo intercambiável. Para obter mais detalhes sobre a chave de criação, siga Chaves no QnA Maker.
O valor de QNA_MAKER_ENDPOINT tem o formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Acesse o portal do Azure e localize o recurso do QnA Maker criado nos pré-requisitos. Selecione a página Chaves e ponto de extremidade, em Gerenciamento de recursos, para localizar a Chave de criação (Assinatura) e o Ponto de extremidade do QnA Maker.

Ponto de extremidade de criação do QnA Maker

O valor de QNA_MAKER_RUNTIME_ENDPOINT tem o formato https://YOUR-RESOURCE-NAME.azurewebsites.net. Acesse o portal do Azure e localize o recurso do QnA Maker criado nos pré-requisitos. Selecione a página Exportar modelo, em Automação, para localizar o Ponto de extremidade do Runtime.

Ponto de extremidade do runtime do QnA Maker

Importante

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 objeto

O QnA Maker usa dois modelos de objeto diferentes:

QnAMakerClient é o objeto usado para criar, gerenciar, publicar e baixar a base de dados de conhecimento.
QnAMakerRuntime é o objeto usado para consultar a base de dados de conhecimento com a API GenerateAnswer e para enviar novas perguntas sugeridas usando a API de Treinamento (como parte do aprendizado ativo).

Usando esta base de dados de conhecimento de exemplo

Se você planeja desenvolver sua base de dados de conhecimento ao longo do tempo, com solicitações de acompanhamento que dependem de pares do QnA existentes, você pode optar:

Por bases de dados de conhecimento maiores, gerenciar a base de dados de conhecimento em um editor de texto ou na ferramenta TSV com suporte para automação e substituir completamente a base de dados de conhecimento de uma só vez com uma atualização.
Para bases de dados de conhecimento menores, gerenciar as solicitações de acompanhamento inteiramente no portal do QnA Maker.

Detalhes sobre os pares do QnA usados neste guia de início rápido:

Tipos de par do QnA – há dois tipos de pares do QnA nesta base de dados de conhecimento, após a atualização: informações específicas de domínio e conversas. Isso é comum se a base de dados de conhecimento estiver vinculada a um aplicativo de conversa, como um chatbot.
Embora as respostas da base de dados de conhecimento possam ser filtradas por metadados ou usar prompts de acompanhamento, este guia de início rápido não mostra isso. Procure os exemplos generateAnswer independentes de idioma aqui.
O texto de resposta é um Markdown e pode conter uma ampla variedade de Markdown como imagens (imagens baseadas na Internet publicamente disponíveis), links (para URLs disponíveis publicamente) e pontos com marcadores; este guia de início rápido não usa essa variedade.

Modelo de objeto do QnAMakerClient

O cliente de criação do QnA Maker é um objeto QnAMakerClient que é autenticado no Azure usando Microsoft.Rest.ServiceClientCredentials, que contém sua chave.

Após a criação do cliente, use a propriedade da Base de dados de conhecimento para criar, gerenciar e publicar sua base de dados de conhecimento.

Gerencie sua base de dados de conhecimento enviando um objeto JSON. Para operações imediatas, um método geralmente retorna um objeto JSON que indica o status. Para operações de longa execução, a resposta é a ID da operação. Chame o método operations.get_details com a ID da operação para determinar o status da solicitação.

Modelo de objeto do QnAMakerRuntimeClient

O cliente de previsão do QnA Maker é um objeto QnAMakerRuntimeClient que é autenticado no Azure usando Microsoft.Rest.ServiceClientCredentials, que contém sua chave do runtime de previsão, retornada pela chamada do cliente de criação, client.EndpointKeysOperations.get_keys, após a publicação da base de dados de conhecimento.

Use o método generate_answer para obter uma resposta do runtime da consulta.

Autenticar o cliente para criar a base de dados de conhecimento

Instancie um cliente com o ponto de extremidade e a chave. Crie um objeto CognitiveServicesCredentials com a sua chave e use-o com o ponto de extremidade para criar um objeto QnAMakerClient.

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

Como criar uma base de dados de conhecimento

Use o objeto de cliente para obter um objeto de operações da base de dados de conhecimento.

Uma base de dados de conhecimento armazena pares de perguntas e respostas para o objeto CreateKbDTO de três fontes:

Para conteúdo editorial, use o objeto QnADTO.
- Para usar os metadados e as solicitações de acompanhamento, use o contexto editorial, pois esses dados são adicionados no nível do par individual de P e R.
Para arquivos, use o objeto FileDTO. O FileDTO inclui o nome de arquivo e a URL pública para acessar o arquivo.
Em URLs, use uma lista de cadeias de caracteres para representar URLs disponíveis publicamente.

Chame o método create e, em seguida, passe a ID da operação retornada para o método Operations.getDetails para sondar o status.

A linha final do código a seguir retorna a ID da base de dados de conhecimento da resposta 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

Inclua a função _monitor_operation, referenciada no código acima, para criar uma base de dados de conhecimento com êxito.

Como atualizar uma base de dados de conhecimento

É possível atualizar uma base de dados de conhecimento passando sua ID e um UpdateKbOperationDTO contendo os objetos add, update e delete DTO para o método update. Use o método Operation.getDetail para determinar se a atualização foi bem-sucedida.

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

Inclua a função _monitor_operation, referenciada no código acima, para atualizar uma base de dados de conhecimento com êxito.

Baixar uma base de dados de conhecimento

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

Como publicar uma base de dados de conhecimento

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

Consultar uma base de dados de conhecimento

Obter a chave do runtime de consulta

Após uma base de dados de conhecimento ser publicada, você precisa da chave do runtime de consulta para consultar o runtime. Ela não é a mesma chave usada para criar o objeto cliente original.

Use o método EndpointKeysOperations.get_keys para obter a classe EndpointKeysDTO.

Use qualquer uma das propriedades da chave retornadas no objeto para consultar a base de dados de conhecimento.

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

Autenticar o runtime para gerar uma resposta

Crie um QnAMakerRuntimeClient para consultar a base de dados de conhecimento para gerar uma resposta ou treinar com base em um aprendizado ativo.

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

Use o QnAMakerRuntimeClient para obter uma resposta de conhecimento ou para enviar novas perguntas sugeridas para a base de dados de conhecimento, para o aprendizado ativo.

Gerar uma resposta da base de dados de conhecimento

Gere uma resposta de uma base de dados de conhecimento publicada usando o método QnAMakerRuntimeClient.runtime.generate_answer. Esse método aceita a ID da base de dados de conhecimento e o QueryDTO. Acesse as propriedades adicionais do QueryDTO, como Superior e Contexto, para usar em seu chatbot.

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 é um exemplo simples de consulta à base de dados de conhecimento. Para entender cenários de consulta avançada, confira outros exemplos de consulta.

Excluir uma base de dados de conhecimento

Exclua a base de dados de conhecimento usando o método delete com um parâmetro da ID da base de dados de conhecimento.

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

Obter o status de uma operação

A chamada setTimeout no bloco de código a seguir é usada para simular código assíncrono. Substitua isso pela lógica de repetição.

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

Executar o aplicativo

Execute o aplicativo com o comando Python no arquivo de início rápido.

python quickstart-file.py

O código-fonte desta amostra pode ser encontrado no GitHub.

Use a biblioteca de clientes do QnA Maker para Java para:

Criar uma base de dados de conhecimento
Atualizar uma base de dados de conhecimento
Publicar uma base de dados de conhecimento
Obter a chave de ponto de extremidade do runtime de previsão
Aguardar tarefa de execução longa
Baixar uma base de dados de conhecimento
Obter uma resposta de uma base de dados de conhecimento
Excluir base de dados de conhecimento

Código-fonte da biblioteca | Pacote | Amostras

Observação

Pré-requisitos

Assinatura do Azure – Criar uma gratuitamente
JDK
Quando você tiver sua assinatura do Azure, crie um recurso do QnA Maker no portal do Azure para obter a chave de criação e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
- Você precisará da chave e do ponto de extremidade do recurso que você criar para conectar seu aplicativo à API do QnA Maker. Cole a chave e o ponto de extremidade no código abaixo, mais adiante no início rápido.
- Use o tipo de preço gratuito (F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

Configurando

Instalar as bibliotecas cliente

Depois de instalar o Java, você pode instalar as bibliotecas de clientes usando Maven no Repositório MVN.

Criar um aplicativo Java

Crie um arquivo chamado quickstart.java e importe as bibliotecas a seguir.

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

Crie variáveis para a chave e o ponto de extremidade do Azure do recurso.

Usamos a chave de assinatura e a chave de criação de modo intercambiável. Para obter mais detalhes sobre a chave de criação, siga Chaves no QnA Maker.
O valor de QNA_MAKER_ENDPOINT tem o formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Acesse o portal do Azure e localize o recurso do QnA Maker criado nos pré-requisitos. Selecione a página Chaves e ponto de extremidade, em Gerenciamento de recursos, para localizar a Chave de criação (Assinatura) e o Ponto de extremidade do QnA Maker.

Ponto de extremidade de criação do QnA Maker

O valor de QNA_MAKER_RUNTIME_ENDPOINT tem o formato https://YOUR-RESOURCE-NAME.azurewebsites.net. Acesse o portal do Azure e localize o recurso do QnA Maker criado nos pré-requisitos. Selecione a página Exportar modelo, em Automação, para localizar o Ponto de extremidade do Runtime.

Ponto de extremidade do runtime do QnA Maker

Importante

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 objeto

O QnA Maker usa dois modelos de objeto diferentes:

QnAMakerClient é o objeto usado para criar, gerenciar, publicar e baixar a base de dados de conhecimento.
QnAMakerRuntime é o objeto usado para consultar a base de dados de conhecimento com a API GenerateAnswer e para enviar novas perguntas sugeridas usando a API de Treinamento (como parte do aprendizado ativo).

Usando esta base de dados de conhecimento de exemplo

Se você planeja desenvolver sua base de dados de conhecimento ao longo do tempo, com solicitações de acompanhamento que dependem de pares do QnA existentes, você pode optar:

Por bases de dados de conhecimento maiores, gerenciar a base de dados de conhecimento em um editor de texto ou na ferramenta TSV com suporte para automação e substituir completamente a base de dados de conhecimento de uma só vez com uma atualização.
Para bases de dados de conhecimento menores, gerenciar as solicitações de acompanhamento inteiramente no portal do QnA Maker.

Detalhes sobre os pares do QnA usados neste guia de início rápido:

Tipos de par do QnA – há dois tipos de pares do QnA nesta base de dados de conhecimento, após a atualização: informações específicas de domínio e conversas. Isso é comum se a base de dados de conhecimento estiver vinculada a um aplicativo de conversa, como um chatbot.
Embora as respostas da base de dados de conhecimento possam ser filtradas por metadados ou usar prompts de acompanhamento, este guia de início rápido não mostra isso. Procure os exemplos generateAnswer independentes de idioma aqui.
O texto de resposta é um Markdown e pode conter uma ampla variedade de Markdown como imagens (imagens baseadas na Internet publicamente disponíveis), links (para URLs disponíveis publicamente) e pontos com marcadores; este guia de início rápido não usa essa variedade.

Modelo de objeto do QnAMakerClient

O cliente de criação do QnA Maker é um objeto QnAMakerClient que é autenticado no Azure usando MsRest::ServiceClientCredentials, que contém a sua chave.

Após a criação do cliente, use os métodos da propriedade Knowledgebases do cliente para criar, gerenciar e publicar a sua base de dados de conhecimento.

Para operações imediatas, um método geralmente retornará o resultado, se houver. Para operações de execução prolongada, a resposta é um objeto Operation. Chame o método getDetails com o valor operation.operationId para determinar o status da solicitação.

Modelo de objeto do QnAMakerRuntimeClient

O cliente de runtime do QnA Maker é um objeto QnAMakerRuntimeClient.

Depois de publicar a sua base de dados de conhecimento usando o cliente de criação, use o método generateAnswer do cliente de runtime para obter uma resposta da base de dados de conhecimento.

Você cria um cliente de runtime chamando QnAMakerRuntimeManager.authenticat e passando uma chave de ponto de extremidade de runtime. Para obter a chave de ponto de extremidade de runtime, use o cliente de criação para chamar getKeys.

Autenticar o cliente para criar a base de dados de conhecimento

Crie uma instância de um cliente com o ponto de extremidade de criação e a chave de assinatura.

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

Como criar uma base de dados de conhecimento

Uma base de dados de conhecimento armazena pares de perguntas e respostas para o objeto CreateKbDTO de três fontes:

Para conteúdo editorial, use o objeto QnADTO.
- Para usar os metadados e as solicitações de acompanhamento, use o contexto editorial, pois esses dados são adicionados no nível do par individual de P e R.
Para arquivos, use o objeto FileDTO. O FileDTO inclui o nome de arquivo e a URL pública para acessar o arquivo.
Em URLs, use uma lista de cadeias de caracteres para representar URLs disponíveis publicamente.

Chame o método create e, em seguida, passe a propriedade operationId da operação retornada para o método getDetails para sondar o status.

A linha final do código a seguir retorna a ID da base de dados de conhecimento.

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

Como atualizar uma base de dados de conhecimento

É possível atualizar uma base de dados de conhecimento chamando update e passando a ID da base de dados de conhecimento e um objeto UpdateKbOperationDTO. Esse objeto, por sua vez, pode conter:

Passe a propriedade operationId da operação retornada para o método getDetails para sondar o status.

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

Baixar uma base de dados de conhecimento

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

Como publicar uma base de dados de conhecimento

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

Gerar uma resposta da base de dados de conhecimento

Após uma base de dados de conhecimento ser publicada, você precisará da chave de ponto de extremidade de runtime para consultar a base de dados de conhecimento. Isso não é o mesmo que a chave de assinatura usada para criar o cliente de criação.

Use o método getKeys para obter um objeto EndpointKeysDTO.

Crie um cliente de runtime chamando QnAMakerRuntimeManager.authenticat e passando uma chave de ponto de extremidade de runtime do objeto EndpointKeysDTO.

Gere uma resposta de uma base de dados de conhecimento publicada usando o método generateAnswer. Esse método aceita a ID da base de dados de conhecimento e o 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();
}

Esse é um exemplo simples de consulta à base de dados de conhecimento. Para entender cenários de consulta avançada, confira outros exemplos de consulta.

Excluir uma base de dados de conhecimento

Exclua a base de dados de conhecimento usando o método delete com um parâmetro da ID da base de dados de conhecimento.

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

Obter o status de uma operação

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

Executar o aplicativo

Este é o método principal para o aplicativo.

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

Execute o aplicativo da maneira a seguir. Isso pressupõe que o nome de classe é Quickstart e as suas dependências estão em uma subpasta chamada lib abaixo da pasta atual.

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

O código-fonte desta amostra pode ser encontrado no GitHub.

Limpar os recursos

Se quiser limpar e remover uma assinatura dos Serviços de IA do Azure, você poderá excluir o recurso ou grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Próximas etapas

Tutorial: Testar sua base de dados de conhecimento com um arquivo em lotes