Guida introduttiva: Libreria client di QnA Maker

Articolo
01/19/2024

Nota

Azure Open AI On Your Data usa modelli di linguaggio di grandi dimensioni per produrre risultati simili a QnA Maker. Per eseguire la migrazione del progetto QnA Maker ad Azure Open AI On Your Data, consultare la guida.

Introduzione alla libreria client di QnA Maker. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

Nota

Il servizio QnA Maker viene ritirato il 31 marzo 2025. Una versione più recente della funzionalità di domande e risposte è ora disponibile come parte del linguaggio di intelligenza artificiale di Azure. Per le funzionalità di risposta alle domande all'interno del servizio di linguaggio, vedere La risposta alle domande. A partire dal 1° ottobre 2022 non sarà possibile creare nuove risorse di QnA Maker. Per informazioni sulla migrazione delle knowledge base di QnA Maker esistenti alla risposta alle domande, vedere la guida alla migrazione.

Prerequisiti

Nota

Questa documentazione non si applica alla versione più recente. Per informazioni sull'uso dell'API REST con la versione più recente, vedere la guida introduttiva all'API REST per rispondere alle domande

La versione corrente di cURL. Negli argomenti di avvio rapido vengono usate diverse opzioni della riga di comando, indicate nella documentazione di cURL.
È necessario avere una risorsa QnA Maker, per usare la chiave e il nome della risorsa. Durante la creazione della risorsa si è immesso il nome, quindi la chiave è stata creata automaticamente. Il nome della risorsa viene usato come sottodominio per l'endpoint. Per recuperare la chiave e il nome della risorsa, selezionare Avvio rapido nel portale di Azure per la risorsa. Il nome della risorsa è il primo sottodominio dell'URL dell'endpoint:

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

Attenzione

Negli esempi BASH seguenti viene usato il carattere di continuazione riga \. Se la console o il terminale usa un carattere di continuazione riga diverso, usare questo carattere.

Creare una knowledge base

Per creare una knowledge base con le API REST e cURL, è necessario avere le informazioni seguenti:

Informazioni	Configurazione di cURL	Scopo
Nome della risorsa di QnA Maker	URL	Usato per creare l'URL
Chiave della risorsa di QnA Maker	Parametro `-h` per l'intestazione `Ocp-Apim-Subscription-Key`	Eseguire l'autenticazione per il servizio QnA Maker
JSON che descrive la knowledge base	Parametro `-d`	Esempi di JSON
Dimensioni di JSON in byte	Parametro `-h` per l'intestazione `Content-Size`

Il comando cURL viene eseguito da una shell BASH. Modificare questo comando con il nome e la chiave della risorsa e con i valori e le dimensioni di 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 risposta cURL di QnA Maker include operationId, che è necessario per ottenere lo stato dell'operazione.

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

Ottenere lo stato dell'operazione

Quando si crea una knowledge base, poiché l'operazione è asincrona, la risposta include informazioni per determinare lo stato.

Informazioni	Configurazione di cURL	Scopo
Nome della risorsa di QnA Maker	URL	Usato per creare l'URL
ID operazione	Route dell'URL	`/operations/REPLACE-WITH-YOUR-OPERATION-ID`
Chiave della risorsa di QnA Maker	Parametro `-h` per l'intestazione `Ocp-Apim-Subscription-Key`	Eseguire l'autenticazione per il servizio QnA Maker

Il comando cURL viene eseguito da una shell BASH. Modificare questo comando con il nome e la chiave della risorsa e con l'ID operazione.

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 risposta cURL include lo stato. Se lo stato indica che l'operazione è riuscita, resourceLocation include l'ID della knowledge base.

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

Pubblicare una knowledge base

Prima di eseguire una query sulla knowledge base, è necessario:

Pubblicare una knowledge base
Ottenere la chiave dell'endpoint di runtime

Questa attività pubblica la knowledge base. Il recupero della chiave dell'endpoint di runtime è un'attività separata.

Informazioni	Configurazione di cURL	Scopo
Nome della risorsa di QnA Maker	URL	Usato per creare l'URL
Chiave della risorsa di QnA Maker	Parametro `-h` per l'intestazione `Ocp-Apim-Subscription-Key`	Eseguire l'autenticazione per il servizio QnA Maker
ID knowledge base	Route dell'URL	`/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID`

Il comando cURL viene eseguito da una shell BASH. Modificare questo comando con il nome e la chiave della risorsa e con l'ID knowledge base.

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

Lo stato della risposta è 204 senza risultati. Usare il parametro della riga di comando -v per visualizzare l'output dettagliato del comando cURL, che include lo stato HTTP.

Ottenere la chiave dell'endpoint di runtime della knowledge base pubblicata

Prima di eseguire una query sulla knowledge base, è necessario:

Pubblicare una knowledge base
Ottenere la chiave dell'endpoint di runtime

Questa attività ottiene la chiave dell'endpoint di runtime. La pubblicazione della knowledge base è un'attività separata.

La chiave dell'endpoint di runtime è la stessa chiave per tutte le knowledge base che usano la risorsa di QnA Maker.

Informazioni	Configurazione di cURL	Scopo
Nome della risorsa di QnA Maker	URL	Usato per creare l'URL
Chiave della risorsa di QnA Maker	Parametro `-h` per l'intestazione `Ocp-Apim-Subscription-Key`	Eseguire l'autenticazione per il servizio QnA Maker

Il comando cURL viene eseguito da una shell BASH. Modificare questo comando con il nome e la chiave della risorsa.

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 risposta cURL include le chiavi dell'endpoint di runtime. Usare solo una delle chiavi durante l'esecuzione di una query per ottenere una risposta dalla knowledge base.

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

Eseguire un query per ottenere una risposta dalla knowledge base pubblicata

Il recupero di una risposta dalla knowledge base si esegue da un runtime separato rispetto a quello per la gestione della knowledge base. Poiché si tratta di un runtime separato, è necessario eseguire l'autenticazione con una chiave di runtime.

Informazioni	Configurazione di cURL	Scopo
Nome della risorsa di QnA Maker	URL	Usato per creare l'URL
Chiave di runtime di QnA Maker	Parametro `-h` per l'intestazione `Authorization`	La chiave fa parte di una stringa che include la parola `Endpointkey` . Eseguire l'autenticazione per il servizio QnA Maker
ID knowledge base	Route dell'URL	`/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID`
JSON che descrive la query	Parametro `-d`	Parametri del corpo della richiesta ed esempi di JSON
Dimensioni di JSON in byte	Parametro `-h` per l'intestazione `Content-Size`

Il comando cURL viene eseguito da una shell BASH. Modificare questo comando con il nome e la chiave della risorsa e con l'ID knowledge base.

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 risposta con esito positivo include la risposta migliore insieme ad altre informazioni che un'applicazione client, ad esempio un chatbot, deve visualizzare in una risposta all'utente.

Eliminare una knowledge base

Dopo aver completato le operazioni con la knowledge base, eliminarla.

Informazioni	Configurazione di cURL	Scopo
Nome della risorsa di QnA Maker	URL	Usato per creare l'URL
Chiave della risorsa di QnA Maker	Parametro `-h` per l'intestazione `Ocp-Apim-Subscription-Key`	Eseguire l'autenticazione per il servizio QnA Maker
ID knowledge base	Route dell'URL	`/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID`

Il comando cURL viene eseguito da una shell BASH. Modificare questo comando con il nome e la chiave della risorsa e con l'ID knowledge base.

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"

Lo stato della risposta è 204 senza risultati. Usare il parametro della riga di comando -v per visualizzare l'output dettagliato del comando cURL, che include lo stato HTTP.

Risorse aggiuntive

Documentazione di riferimento sulla creazione
Documentazione di riferimento sul runtime
Script BASH di esempio con cURL

Usare la libreria client di QnA Maker per .NET per:

Creare una knowledge base
Aggiornare una knowledge base
Pubblicare una knowledge base
Ottenere la chiave dell'endpoint di runtime di previsione
Attendere un'attività a esecuzione prolungata
Scaricare una knowledge base
Ottenere una risposta da una knowledge base
Eliminare una knowledge base

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (NuGet) | Esempi C#

Nota

Le nuove risorse create dopo il 1° luglio 2019 useranno nomi di sottodomini personalizzati. Per altre informazioni e un elenco completo degli endpoint a livello di area, vedere Nomi di sottodomini personalizzati per i servizi di intelligenza artificiale di Azure.

Prerequisiti

Nota

Questa documentazione non si applica alla versione più recente. Per informazioni sull'uso dell'API C# con la versione più recente, vedere la guida introduttiva alla risposta alle domande in C#.

Sottoscrizione di Azure: creare un account gratuito
IDE di Visual Studio o la versione corrente di .NET Core.
Dopo aver creato la sottoscrizione di Azure, creare una risorsa di QnA Maker nel portale di Azure per ottenere la chiave di creazione e il nome della risorsa. Al termine della distribuzione, fare clic su Vai alla risorsa.
- La chiave e il nome della risorsa creata sono necessari per connettere l'applicazione all'API QnA Maker. Incollare la chiave e il nome della risorsa nel codice seguente più avanti nella guida introduttiva.
- È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

Configurazione

CLI

In una finestra di una console, ad esempio cmd, PowerShell o Bash, usare il comando dotnet new per creare una nuova app console con il nome qna-maker-quickstart. Questo comando crea un semplice progetto C# "Hello World" con un unico file di origine: program.cs.

dotnet new console -n qna-maker-quickstart

Spostarsi nella cartella dell'app appena creata. È possibile compilare l'applicazione con il comando seguente:

dotnet build

L'output di compilazione non deve contenere alcun avviso o errore.

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

Nella directory dell'applicazione installare la libreria client di QnA Maker per .NET con il comando seguente:

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

Suggerimento

Si vuole visualizzare l'intero file di codice dell'argomento di avvio rapido? È possibile trovarlo in GitHub, che contiene gli esempi di codice di questo argomento.

Direttive using

Dalla directory del progetto aprire il file program.cs e aggiungere le direttive using seguenti:

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

Endpoint risorsa e chiave della sottoscrizione

Nel metodo Main dell'applicazione aggiungere le variabili e il codice, come illustrato nella sezione seguente, per usare le attività comuni di questo argomento di avvio rapido.

La chiave di sottoscrizione e la chiave di creazione vengono usate in modo intercambiabile. Per altre informazioni sulla chiave di creazione, seguire Chiavi in QnA Maker.
Il formato del valore di QNA_MAKER_ENDPOINT è https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Passare alla portale di Azure e trovare la risorsa QnA Maker creata nei prerequisiti. Selezionare la pagina Chiavi ed endpoint in Gestione risorse per individuare la chiave di creazione (sottoscrizione) e l'endpoint QnA Maker.

Endpoint di creazione di QnA Maker

Il formato del valore di QNA_MAKER_RUNTIME_ENDPOINT è https://YOUR-RESOURCE-NAME.azurewebsites.net. Passare alla portale di Azure e trovare la risorsa QnA Maker creata nei prerequisiti. Selezionare La pagina Esporta modello in Automazione per individuare l'endpoint di runtime.

QnA Maker Runtime Endpoint

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedere l'articolo sulla sicurezza dei servizi di intelligenza artificiale di Azure.

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

Modelli a oggetti

QnA Maker usa due modelli a oggetti diversi:

QnAMakerClient è l'oggetto per creare, gestire, pubblicare e scaricare la knowledge base.
QnAMakerRuntime è l'oggetto per eseguire una query sulla knowledge base con l'API GenerateAnswer e inviare nuove domande suggerite usando l'API Train (come parte dell'apprendimento attivo).

Utilizzo della knowledge base di esempio

La knowledge base di questo argomento di avvio rapido inizia con due coppie di domande e risposte di conversazione per semplificare l'esempio e per avere ID altamente prevedibili da usare nel metodo Update, associando le richieste di completamento a domande in nuove coppie. Questa operazione è stata pianificata e implementata in un ordine specifico per questo argomento di avvio rapido.

Se si prevede di sviluppare una knowledge base nel tempo con richieste di completamento che dipendono da coppie di domande e risposte esistenti, è possibile scegliere di:

Gestire la knowledge base in un editor di testo o in uno strumento TSV che supporti l'automazione e quindi di sostituire completamente la knowledge base con un aggiornamento (per le knowledge base di grandi dimensioni).
Gestire le richieste di completamento interamente nel portale di QnA Maker (per le knowledge base di piccole dimensioni).

Dettagli sulle coppie di domande e risposte usate in questo argomento di avvio rapido:

Tipi di coppie di domande e risposte: in questa knowledge base sono disponibili due tipi di coppie di domande e risposte, dopo l'aggiornamento, ovvero chitchat e informazioni specifiche del dominio. Questo scenario è tipico se la knowledge base è collegata a un'applicazione per conversazioni, ad esempio un chatbot.
Anche se è possibile filtrare le risposte della knowledge base in base a metadati o usare le richieste di completamento, queste operazioni non vengono illustrate in questo argomento di avvio rapido. Per questi esempi di generateAnswer indipendenti dal linguaggio, vedere qui.
Il testo della risposta può contenere un'ampia varietà di markdown, come immagini (immagini Internet disponibili pubblicamente), collegamenti (a URL disponibili pubblicamente) e punti elenco. In questo argomento di avvio rapido non viene usata questa varietà.

Modello a oggetti QnAMakerClient

Il client di creazione di QnA Maker è un oggetto QnAMakerClient che esegue l'autenticazione ad Azure con Microsoft.Rest.ServiceClientCredentials, che contiene la chiave.

Dopo la creazione del client, usare la proprietà Knowledgebase per creare, gestire e pubblicare la knowledge base.

Gestire la knowledge base inviando un oggetto JSON. Per le operazioni immediate, un metodo restituisce in genere un oggetto JSON che indica lo stato. Per le operazioni a esecuzione prolungata, la risposta è l'ID operazione. Chiamare il metodo client.Operations.GetDetailsAsync con l'ID operazione per determinare lo stato della richiesta.

Modello a oggetti QnAMakerRuntimeClient

Il client di previsione di QnA Maker è un oggetto QnAMakerRuntimeClient che esegue l'autenticazione ad Azure con Microsoft.Rest.ServiceClientCredentials, che contiene la chiave di runtime di previsione, restituita dalla chiamata del client di creazione client.EndpointKeys.GetKeys dopo la pubblicazione della knowledge base.

Usare il metodo GenerateAnswer per ottenere una risposta dal runtime di query.

Esempi di codice

Questi frammenti di codice mostrano come eseguire le operazioni seguenti con la libreria client di QnA Maker per .NET:

Autenticare il client di creazione
Creare una knowledge base
Aggiornare una knowledge base
Scaricare una knowledge base
Pubblicare una knowledge base
Eliminare una knowledge base
Ottenere una chiave di runtime di query
Ottenere lo stato di un'operazione
Autenticare il client di runtime di query
Generare una risposta dalla knowledge base

Autenticare il client per la creazione della knowledge base

Creare un'istanza di un oggetto client con la chiave e usarla con la risorsa per creare l'endpoint e quindi creare un oggetto QnAMakerClient con l'endpoint e la chiave. Creare un oggetto ServicePrincipalCredentials.

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

Creare una knowledge base

In una knowledge base vengono archiviate le coppie di domande e risposte per l'oggetto CreateKbDTO da tre origini:

Per contenuto editoriale, usare l'oggetto QnADTO.
- Per usare i metadati e le richieste di completamento, usare il contesto editoriale, perché questi dati vengono aggiunti a livello di singola coppia di domande e risposte.
Per i file, usare l' oggetto FileDTO. FileDTO include il nome file e l'URL pubblico per raggiungere il file.
Per URL, usare un elenco di stringhe per rappresentare gli URL disponibili pubblicamente.

Il passaggio di creazione include anche le proprietà della knowledge base:

defaultAnswerUsedForExtraction: il risultato restituito quando non si trova nessuna risposta
enableHierarchicalExtraction: crea automaticamente relazioni di richieste tra coppie di domande e risposte estratte
language: quando si crea la prima knowledge base di una risorsa, imposta la lingua da usare nell'indice di Ricerca di Azure.

Chiamare il metodo CreateAsync, quindi passare l'ID operazione restituito al metodo MonitorOperation per eseguire il polling dello stato.

La riga finale del codice seguente restituisce l'ID knowledge base dalla risposta di 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);
}

Per creare correttamente una knowledge base, assicurarsi di includere la funzione MonitorOperation, a cui si fa riferimento nel codice precedente.

Aggiornare una knowledge base

È possibile aggiornare una knowledge base passando l'ID knowledge base e un UpdatekbOperationDTO contenente gli oggetti DTO per l'aggiunta, l'aggiornamento e l'eliminazione al metodo UpdateAsync. Usare il metodo MonitorOperation per determinare se l'aggiornamento è riuscito.

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

Assicurarsi di includere la MonitorOperation funzione, a cui si fa riferimento nel codice precedente, per aggiornare correttamente una Knowledge Base.

Scaricare una knowledge base

Usare il metodo DownloadAsync per scaricare il database come un elenco di QnADocumentsDTO. Questa operazione non equivale all'esportazione dalla pagina Settings (Impostazioni) del portale di QnA Maker, perché il risultato di questo metodo non è un file.

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
}

Pubblicare una knowledge base

Pubblicare la knowledge base con il metodo PublishAsync. In questo modo, il modello corrente salvato e sottoposto a training a cui fa riferimento l'ID knowledge base viene pubblicato in un endpoint. Questo passaggio è necessario per eseguire query sulla knowledge base.

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

Ottenere una chiave di runtime di query

Dopo la pubblicazione di una knowledge base, è necessaria la chiave di runtime di query per eseguire una query sul runtime. Non è la stessa chiave usata per creare l'oggetto client originale.

Usare il metodo EndpointKeys per ottenere la classe EndpointKeysDTO.

Usare una delle proprietà chiave restituite nell'oggetto per eseguire una query sulla knowledge base.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

Una chiave di runtime è necessaria per eseguire query sulla knowledge base.

Autenticare il runtime per la generazione di una risposta

Creare un oggetto QnAMakerRuntimeClient per eseguire una query sulla knowledge base e generare una risposta o eseguire il training da apprendimento attivo.

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

Usare QnAMakerRuntimeClient per:

Ottenere una risposta dalla knowledge base
Inviare nuove domande suggerite alla knowledge base per l'apprendimento attivo.

Generare una risposta dalla knowledge base

Generare una risposta da una knowledge base pubblicata usando il metodo RuntimeClient.GenerateAnswerAsync. Questo metodo accetta l'ID knowledge base e QueryDTO. Accedere ad altre proprietà di QueryDTO, ad esempio Top e Context da usare nel 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
}

Si tratta di un semplice esempio di esecuzione di query sulla knowledge base. Per informazioni sugli scenari di query avanzati, vedere altri esempi di query.

Eliminare una knowledge base

Eliminare la knowledge base usando il metodo DeleteAsync con un parametro dell'ID knowledge base.

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

Ottenere lo stato di un'operazione

Alcuni metodi, ad esempio per la creazione e l'aggiornamento, possono richiedere una quantità di tempo tale che invece di attendere il completamento del processo viene restituita un'operazione. Usare il relativo ID operazione per eseguire il polling (con logica di ripetizione dei tentativi) e determinare lo stato del metodo originale.

Il ciclo e Task.Delay nel blocco di codice seguente vengono usati per simulare la logica di ripetizione dei tentativi. Dovranno essere sostituiti con la propria logica di ripetizione dei tentativi.

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

Eseguire l'applicazione

Eseguire l'applicazione con il comando dotnet run dalla directory dell'applicazione.

dotnet run

Il codice sorgente per questo esempio è disponibile su GitHub.

Usare la libreria client di QnA Maker per Node.js per eseguire queste operazioni:

Creare una knowledge base
Aggiornare una knowledge base
Pubblicare una knowledge base
Ottenere la chiave dell'endpoint di runtime di previsione
Attendere un'attività a esecuzione prolungata
Scaricare una knowledge base
Ottenere una risposta da una knowledge base
Eliminare una knowledge base

Pacchetto della documentazione di riferimento | (npm) | Node.js esempi

Nota

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
Versione corrente di Node.js.
Dopo aver creato la sottoscrizione di Azure, creare una risorsa di QnA Maker nel portale di Azure per ottenere la chiave di creazione e la risorsa. Al termine della distribuzione, fare clic su Vai alla risorsa.
- La chiave e il nome della risorsa creata sono necessari per connettere l'applicazione all'API QnA Maker. Incollare la chiave e il nome della risorsa nel codice seguente più avanti nella guida introduttiva.
- È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

Configurazione

Creare una nuova applicazione Node.js

In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Eseguire il comando npm init -y per creare un'applicazione Node con un file package.json.

npm init -y

Installare la libreria client

Installare i pacchetti NPM seguenti:

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

Il file package.json dell'app viene aggiornato con le dipendenze.

Creare un file denominato index.js, aprirlo e importare le librerie seguenti:

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

Creare una variabile per la chiave di Azure della risorsa e il nome della risorsa.

La chiave di sottoscrizione e la chiave di creazione vengono usate in modo intercambiabile. Per altre informazioni sulla chiave di creazione, seguire Chiavi in QnA Maker.
Il formato del valore di QNA_MAKER_ENDPOINT è https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Passare alla portale di Azure e trovare la risorsa QnA Maker creata nei prerequisiti. Selezionare la pagina Chiavi ed endpoint in Gestione risorse per individuare la chiave di creazione (sottoscrizione) e l'endpoint QnA Maker.

Endpoint di creazione di QnA Maker

Il formato del valore di QNA_MAKER_RUNTIME_ENDPOINT è https://YOUR-RESOURCE-NAME.azurewebsites.net. Passare alla portale di Azure e trovare la risorsa QnA Maker creata nei prerequisiti. Selezionare La pagina Esporta modello in Automazione per individuare l'endpoint di runtime.

QnA Maker Runtime Endpoint

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

Modelli a oggetti

QnA Maker usa due modelli a oggetti diversi:

QnAMakerClient è l'oggetto per creare, gestire, pubblicare e scaricare la knowledge base.
QnAMakerRuntime è l'oggetto per eseguire una query sulla knowledge base con l'API GenerateAnswer e inviare nuove domande suggerite usando l'API Train (come parte dell'apprendimento attivo).

Modello a oggetti QnAMakerClient

Il client di creazione di QnA Maker è un oggetto QnAMakerClient che esegue l'autenticazione con Azure usando le proprie credenziali, che contengono la chiave.

Dopo aver creato il client, usare knowledgebase per creare, gestire e pubblicare la knowledge base.

Gestire la knowledge base inviando un oggetto JSON. Per le operazioni immediate, un metodo restituisce in genere un oggetto JSON che indica lo stato. Per le operazioni a esecuzione prolungata, la risposta è l'ID operazione. Chiamare il metodo client.operations.getDetails con l'ID operazione per determinare lo stato della richiesta.

Modello a oggetti QnAMakerRuntimeClient

Il client di previsione di QnA Maker è un oggetto QnAMakerRuntimeClient che esegue l'autenticazione con Azure tramite Microsoft.Rest.ServiceClientCredentials, che contiene la chiave di runtime di previsione, restituita dalla chiamata del client di creazioneclient.EndpointKeys.getKeys dopo la pubblicazione della knowledge base.

Esempi di codice

Questi frammenti di codice mostrano come eseguire le operazioni seguenti con la libreria client di QnA Maker per .NET:

Autenticare il client di creazione
Creare una knowledge base
Aggiornare una knowledge base
Scaricare una knowledge base
Pubblicare una knowledge base
Eliminare una knowledge base
Ottenere una chiave di runtime di query
Ottenere lo stato di un'operazione
Autenticare il client di runtime di query
Generare una risposta dalla knowledge base

Autenticare il client per la creazione della knowledge base

Creare un'istanza di un client con l'endpoint e la chiave. Creare un oggetto ServiceClientCredentials con la chiave e usarlo con l'endpoint per creare un oggetto 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);

Creare una knowledge base

In una knowledge base vengono archiviate le coppie di domande e risposte per l'oggetto CreateKbDTO da tre origini:

Per contenuto editoriale, usare l'oggetto QnADTO.
- Per usare i metadati e le richieste di completamento, usare il contesto editoriale, perché questi dati vengono aggiunti a livello di singola coppia di domande e risposte.
Per i file, usare l' oggetto FileDTO. FileDTO include il nome file e l'URL pubblico per raggiungere il file.
Per URL, usare un elenco di stringhe per rappresentare gli URL disponibili pubblicamente.

Il passaggio di creazione include anche le proprietà della knowledge base:

defaultAnswerUsedForExtraction: il risultato restituito quando non si trova nessuna risposta
enableHierarchicalExtraction: crea automaticamente relazioni di richieste tra coppie di domande e risposte estratte
language: quando si crea la prima knowledge base di una risorsa, imposta la lingua da usare nell'indice di Ricerca di Azure.

Chiamare il metodo create con le informazioni della knowledge base. Le informazioni della knowledge base sono essenzialmente un oggetto JSON.

Quando il metodo create viene completato, passare l'ID operazione restituito al metodo wait_for_operation per eseguire il polling dello stato. Il metodo wait_for_operation viene completato al termine dell'operazione. Analizzare il valore dell'intestazione resourceLocation dell'operazione restituita per ottenere il nuovo ID della knowledge base.

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

Per creare correttamente una knowledge base, assicurarsi di includere la funzione wait_for_operation, a cui si fa riferimento nel codice precedente.

Aggiornare una knowledge base

È possibile aggiornare una knowledge base passando l'ID knowledge base e un oggetto UpdateKbOperationDTO contenente gli oggetti DTO add, update e l'delete al metodo update. Anche gli oggetti DTO sono essenzialmente oggetti JSON. Usare il metodo wait_for_operation per determinare se l'aggiornamento è riuscito.

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
}

Per aggiornare correttamente una knowledge base, assicurarsi di includere la funzione wait_for_operation, a cui si fa riferimento nel codice precedente.

Scaricare una knowledge base

Usare il metodo download per scaricare il database come elenco di QnADocumentsDTO. Questa operazione non equivale all'esportazione dalla pagina Settings (Impostazioni) del portale di QnA Maker perché il risultato di questo metodo non è un file 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
}

Pubblicare una knowledge base

Pubblicare la knowledge base tramite il metodo publish. In questo modo, il modello corrente salvato e sottoposto a training a cui fa riferimento l'ID knowledge base viene pubblicato in un endpoint. Controllare il codice di risposta HTTP per verificare che la pubblicazione sia riuscita.

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
}

Eseguire query su una knowledge base

Ottenere una chiave di runtime di query

Dopo la pubblicazione di una knowledge base, è necessaria la chiave di runtime di query per eseguire una query sul runtime. Non è la stessa chiave usata per creare l'oggetto client originale.

Usare il metodo EndpointKeys.getKeys per ottenere la classe EndpointKeysDTO.

Usare una delle proprietà chiave restituite nell'oggetto per eseguire una query sulla knowledge base.

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
}

Autenticare il runtime per la generazione di una risposta

Creare un oggetto QnAMakerRuntimeClient per eseguire una query sulla knowledge base e generare una risposta o eseguire il training da apprendimento attivo.

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

Usare QnAMakerRuntimeClient per ottenere una risposta dalla knowledge base o per inviare nuove domande suggerite alla knowledge base per l'apprendimento attivo.

Generare una risposta dalla knowledge base

Generare una risposta da una knowledge base pubblicata usando il metodo RuntimeClient.runtime.generateAnswer. Questo metodo accetta l'ID knowledge base e QueryDTO. Accedere ad altre proprietà di QueryDTO, ad esempio Top e Context da usare nel 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));

}

Si tratta di un semplice esempio di esecuzione di query sulla knowledge base. Per informazioni sugli scenari di query avanzati, vedere altri esempi di query.

Eliminare una knowledge base

Eliminare la knowledge base tramite il metodo delete con un parametro dell'ID knowledge base.

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
}

Ottenere lo stato di un'operazione

La chiamata delayTimer nel blocco di codice seguente viene usata per simulare la logica di ripetizione dei tentativi. Sostituirla con la propria logica di ripetizione dei tentativi.

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

Eseguire l'applicazione

Eseguire l'applicazione con il comando node index.js dalla directory dell'applicazione.

node index.js

Il codice sorgente per questo esempio è disponibile su GitHub.

Usare la libreria client di QnA Maker per Python per:

Creare una knowledge base
Aggiornare una knowledge base
Pubblicare una knowledge base
Ottenere la chiave dell'endpoint di runtime di previsione
Attendere un'attività a esecuzione prolungata
Scaricare una knowledge base
Ottenere una risposta da una knowledge base
Eliminare una knowledge base

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (PyPi) | Esempi Python

Nota

Prerequisiti

Nota

Questa documentazione non si applica alla versione più recente. Per informazioni sull'uso dell'API Python con la versione più recente, vedere la guida introduttiva alla risposta alle domande su Python.

Sottoscrizione di Azure: creare un account gratuito
Python 3.x
Dopo aver creato la sottoscrizione di Azure, creare una risorsa QnA Maker nel portale di Azure per ottenere la chiave di creazione e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
- La chiave e l'endpoint della risorsa creata sono necessari per connettere l'applicazione all'API QnA Maker. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
- È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

Configurazione

Installare la libreria client

Dopo l'installazione di Python, è possibile installare la libreria client con:

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

Creare una nuova applicazione Python

Creare un nuovo file Python denominato quickstart-file.py e importare le librerie seguenti.

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

Creare le variabili per l'endpoint e la chiave di Azure della risorsa.

La chiave di sottoscrizione e la chiave di creazione vengono usate in modo intercambiabile. Per altre informazioni sulla chiave di creazione, seguire Chiavi in QnA Maker.
Il formato del valore di QNA_MAKER_ENDPOINT è https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Passare alla portale di Azure e trovare la risorsa QnA Maker creata nei prerequisiti. Selezionare la pagina Chiavi ed endpoint in Gestione risorse per individuare la chiave di creazione (sottoscrizione) e l'endpoint QnA Maker.

Endpoint di creazione di QnA Maker

Il formato del valore di QNA_MAKER_RUNTIME_ENDPOINT è https://YOUR-RESOURCE-NAME.azurewebsites.net. Passare alla portale di Azure e trovare la risorsa QnA Maker creata nei prerequisiti. Selezionare La pagina Esporta modello in Automazione per individuare l'endpoint di runtime.

QnA Maker Runtime Endpoint

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'

Modelli a oggetti

QnA Maker usa due modelli a oggetti diversi:

QnAMakerClient è l'oggetto per creare, gestire, pubblicare e scaricare la knowledge base.
QnAMakerRuntime è l'oggetto per eseguire una query sulla knowledge base con l'API GenerateAnswer e inviare nuove domande suggerite usando l'API Train (come parte dell'apprendimento attivo).

Utilizzo della knowledge base di esempio

Se si prevede di sviluppare una knowledge base nel tempo con richieste di completamento che dipendono da coppie di domande e risposte esistenti, è possibile scegliere di:

Gestire la knowledge base in un editor di testo o in uno strumento TSV che supporti l'automazione e quindi di sostituire completamente la knowledge base con un aggiornamento (per le knowledge base di grandi dimensioni).
Gestire le richieste di completamento interamente nel portale di QnA Maker (per le knowledge base di piccole dimensioni).

Dettagli sulle coppie di domande e risposte usate in questo argomento di avvio rapido:

Tipi di coppie di domande e risposte: in questa knowledge base sono disponibili due tipi di coppie di domande e risposte, dopo l'aggiornamento, ovvero chitchat e informazioni specifiche del dominio. Questo scenario è tipico se la knowledge base è collegata a un'applicazione per conversazioni, ad esempio un chatbot.
Anche se è possibile filtrare le risposte della knowledge base in base a metadati o usare le richieste di completamento, queste operazioni non vengono illustrate in questo argomento di avvio rapido. Per questi esempi di generateAnswer indipendenti dal linguaggio, vedere qui.
Il testo della risposta può contenere un'ampia varietà di markdown, come immagini (immagini Internet disponibili pubblicamente), collegamenti (a URL disponibili pubblicamente) e punti elenco. In questo argomento di avvio rapido non viene usata questa varietà.

Modello a oggetti QnAMakerClient

Il client di creazione di QnA Maker è un oggetto QnAMakerClient che esegue l'autenticazione ad Azure con Microsoft.Rest.ServiceClientCredentials, che contiene la chiave.

Dopo la creazione del client, usare la proprietà Knowledgebase per creare, gestire e pubblicare la knowledge base.

Gestire la knowledge base inviando un oggetto JSON. Per le operazioni immediate, un metodo restituisce in genere un oggetto JSON che indica lo stato. Per le operazioni a esecuzione prolungata, la risposta è l'ID operazione. Chiamare il metodo operations.get_details con l'ID operazione per determinare lo stato della richiesta.

Modello a oggetti QnAMakerRuntimeClient

Il client QnA Maker di stima è un QnAMakerRuntimeClient oggetto che esegue l'autenticazione ad Azure usando Microsoft.Rest.ServiceClientCredentials, che contiene la chiave di runtime di stima, restituita dalla chiamata client di creazione, client. EndpointKeysOperations.get_keys dopo la pubblicazione della knowledge base.

Usare il generate_answer metodo per ottenere una risposta dal runtime di query.

Autenticare il client per la creazione della knowledge base

Creare un'istanza di un client con l'endpoint e la chiave. Creare un oggetto CognitiveServicesCredentials con la chiave e usarlo con l'endpoint per creare un oggetto QnAMakerClient .

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

Creare una knowledge base

Usare l'oggetto client per ottenere un oggetto KnowledgeBaseOperations.

In una knowledge base vengono archiviate le coppie di domande e risposte per l'oggetto CreateKbDTO da tre origini:

Per contenuto editoriale, usare l'oggetto QnADTO.
- Per usare i metadati e le richieste di completamento, usare il contesto editoriale, perché questi dati vengono aggiunti a livello di singola coppia di domande e risposte.
Per i file, usare l' oggetto FileDTO. FileDTO include il nome file e l'URL pubblico per raggiungere il file.
Per URL, usare un elenco di stringhe per rappresentare gli URL disponibili pubblicamente.

Chiamare il metodo create e quindi passare l'ID operazione restituito al metodo Operations.getDetails per eseguire il polling dello stato.

La riga finale del codice seguente restituisce l'ID knowledge base dalla risposta di 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

Per creare correttamente una knowledge base, assicurarsi di includere la funzione _monitor_operation, a cui si fa riferimento nel codice precedente.

Aggiornare una knowledge base

È possibile aggiornare una knowledge base passando l'ID knowledge base e un oggetto UpdateKbOperationDTO contenente gli oggetti DTO add, update e l'delete al metodo update. Usare il metodo Operation.getDetail per determinare se l'aggiornamento è riuscito.

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

Per aggiornare correttamente una knowledge base, assicurarsi di includere la funzione _monitor_operation, a cui si fa riferimento nel codice precedente.

Scaricare una knowledge base

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

Pubblicare una knowledge base

Pubblicare la knowledge base tramite il metodo publish. In questo modo, il modello corrente salvato e sottoposto a training a cui fa riferimento l'ID knowledge base viene pubblicato in un endpoint.

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

Eseguire query su una knowledge base

Ottenere una chiave di runtime di query

Dopo la pubblicazione di una knowledge base, è necessaria la chiave di runtime di query per eseguire una query sul runtime. Non è la stessa chiave usata per creare l'oggetto client originale.

Usare il metodo EndpointKeysOperations.get_keys per ottenere la classe EndpointKeysDTO.

Usare una delle proprietà chiave restituite nell'oggetto per eseguire una query sulla knowledge base.

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

Autenticare il runtime per la generazione di una risposta

Creare un oggetto QnAMakerRuntimeClient per eseguire una query sulla knowledge base e generare una risposta o eseguire il training da apprendimento attivo.

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

Usare QnAMakerRuntimeClient per ottenere una risposta dalla knowledge base o per inviare nuove domande suggerite alla knowledge base per l'apprendimento attivo.

Generare una risposta dalla knowledge base

Generare una risposta da una knowledge base pubblicata usando il metodo QnAMakerRuntimeClient.runtime.generate_answer. Questo metodo accetta l'ID knowledge base e QueryDTO. Accedere ad altre proprietà di QueryDTO, ad esempio Top e Context da usare nel 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}.")

Si tratta di un semplice esempio di esecuzione di query sulla knowledge base. Per informazioni sugli scenari di query avanzati, vedere altri esempi di query.

Eliminare una knowledge base

Eliminare la knowledge base tramite il metodo delete con un parametro dell'ID knowledge base.

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

Ottenere lo stato di un'operazione

Alcuni metodi, ad esempio per la creazione e l'aggiornamento, possono richiedere una quantità di tempo tale che invece di attendere il completamento del processo viene restituita un'operazione. Usare l'ID dell'operazione per eseguire il polling (con logica di ripetizione dei tentativi) in modo da determinare lo stato del metodo originale.

La chiamata setTimeout nel blocco di codice seguente viene usata per simulare il codice asincrono. Sostituire questo codice con logica di ripetizione dei tentativi.

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

Eseguire l'applicazione

Eseguire l'applicazione con il comando Python nel file di avvio rapido.

python quickstart-file.py

Il codice sorgente per questo esempio è disponibile su GitHub.

Usare la libreria client di QnA Maker per Java per:

Creare una knowledge base
Aggiornare una knowledge base
Pubblicare una knowledge base
Ottenere la chiave dell'endpoint di runtime di previsione
Attendere un'attività a esecuzione prolungata
Scaricare una knowledge base
Ottenere una risposta da una knowledge base
Eliminare una knowledge base

Codice sorgente della libreria | Pacchetto | Esempi

Nota

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
JDK
Dopo aver creato la sottoscrizione di Azure, creare una risorsa QnA Maker nel portale di Azure per ottenere la chiave di creazione e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
- La chiave e l'endpoint della risorsa creata sono necessari per connettere l'applicazione all'API QnA Maker. Incollare la chiave e l'endpoint nel codice seguente più avanti nella guida introduttiva.
- È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

Configurazione

Installare le librerie client

Dopo aver installato Java, è possibile installare le librerie client usando Maven da repository MVN.

Creare una nuova applicazione Java

Creare un nuovo file denominato quickstart.java e importare le librerie seguenti.

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

Creare le variabili per l'endpoint e la chiave di Azure della risorsa.

La chiave di sottoscrizione e la chiave di creazione vengono usate in modo intercambiabile. Per altre informazioni sulla chiave di creazione, seguire Chiavi in QnA Maker.
Il formato del valore di QNA_MAKER_ENDPOINT è https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Passare alla portale di Azure e trovare la risorsa QnA Maker creata nei prerequisiti. Selezionare la pagina Chiavi ed endpoint in Gestione risorse per individuare la chiave di creazione (sottoscrizione) e l'endpoint QnA Maker.

Endpoint di creazione di QnA Maker

Il formato del valore di QNA_MAKER_RUNTIME_ENDPOINT è https://YOUR-RESOURCE-NAME.azurewebsites.net. Passare alla portale di Azure e trovare la risorsa QnA Maker creata nei prerequisiti. Selezionare La pagina Esporta modello in Automazione per individuare l'endpoint di runtime.

QnA Maker Runtime Endpoint

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

Modelli a oggetti

QnA Maker usa due modelli a oggetti diversi:

QnAMakerClient è l'oggetto per creare, gestire, pubblicare e scaricare la knowledge base.
QnAMakerRuntime è l'oggetto per eseguire una query sulla knowledge base con l'API GenerateAnswer e inviare nuove domande suggerite usando l'API Train (come parte dell'apprendimento attivo).

Utilizzo della knowledge base di esempio

Se si prevede di sviluppare una knowledge base nel tempo con richieste di completamento che dipendono da coppie di domande e risposte esistenti, è possibile scegliere di:

Gestire la knowledge base in un editor di testo o in uno strumento TSV che supporti l'automazione e quindi di sostituire completamente la knowledge base con un aggiornamento (per le knowledge base di grandi dimensioni).
Gestire le richieste di completamento interamente nel portale di QnA Maker (per le knowledge base di piccole dimensioni).

Dettagli sulle coppie di domande e risposte usate in questo argomento di avvio rapido:

Tipi di coppie di domande e risposte: in questa knowledge base sono disponibili due tipi di coppie di domande e risposte, dopo l'aggiornamento, ovvero chitchat e informazioni specifiche del dominio. Questo scenario è tipico se la knowledge base è collegata a un'applicazione per conversazioni, ad esempio un chatbot.
Anche se è possibile filtrare le risposte della knowledge base in base a metadati o usare le richieste di completamento, queste operazioni non vengono illustrate in questo argomento di avvio rapido. Per questi esempi di generateAnswer indipendenti dal linguaggio, vedere qui.
Il testo della risposta può contenere un'ampia varietà di markdown, come immagini (immagini Internet disponibili pubblicamente), collegamenti (a URL disponibili pubblicamente) e punti elenco. In questo argomento di avvio rapido non viene usata questa varietà.

Modello a oggetti QnAMakerClient

Il client di creazione di QnA Maker è un oggetto QnAMakerClient che esegue l'autenticazione con Azure tramite MsRest::ServiceClientCredentials, che contiene la chiave.

Dopo la creazione del client, usare i metodi della proprietà Knowledgebases del client per creare, gestire e pubblicare la knowledge base.

Per le operazioni immediate, un metodo restituisce in genere il risultato, se disponibile. Per le operazioni a esecuzione prolungata, la risposta è un oggetto Operation. Chiamare il metodo getDetails con il valore operation.operationId per determinare lo stato della richiesta.

Modello a oggetti QnAMakerRuntimeClient

Il client di runtime di QnA Maker è un oggetto QnAMakerRuntimeClient.

Dopo aver pubblicato la knowledge base con il client di creazione, usare il metodo generateAnswer del client di runtime per ottenere una risposta dalla knowledge base.

Per creare un client di runtime, chiamare QnAMakerRuntimeManager.authenticate e passare una chiave dell'endpoint di runtime. Per ottenere la chiave dell'endpoint di runtime, usare il client di creazione per chiamare getKeys.

Autenticare il client per la creazione della knowledge base

Creare un'istanza di un client con l'endpoint di creazione e la chiave di sottoscrizione.

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

Creare una knowledge base

In una knowledge base vengono archiviate le coppie di domande e risposte per l'oggetto CreateKbDTO da tre origini:

Per contenuto editoriale, usare l'oggetto QnADTO.
- Per usare i metadati e le richieste di completamento, usare il contesto editoriale, perché questi dati vengono aggiunti a livello di singola coppia di domande e risposte.
Per i file, usare l' oggetto FileDTO. FileDTO include il nome file e l'URL pubblico per raggiungere il file.
Per URL, usare un elenco di stringhe per rappresentare gli URL disponibili pubblicamente.

Chiamare il metodo create, quindi passare la proprietà operationId dell'operazione restituita al metodo getDetails per eseguire il polling dello stato.

La riga finale del codice seguente restituisce l'ID knowledge base.

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

Aggiornare una knowledge base

Per aggiornare una knowledge base, chiamare update e passare l'ID Knowledge base e un oggetto UpdateKbOperationDTO. Tale oggetto può a sua volta contenere:

Passare la proprietà operationId dell'operazione restituita al metodo getDetails per eseguire il polling dello stato.

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

Scaricare una knowledge base

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

Pubblicare una knowledge base

Pubblicare la knowledge base tramite il metodo publish. In questo modo, il modello corrente salvato e sottoposto a training a cui fa riferimento l'ID knowledge base viene pubblicato in un endpoint.

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

Generare una risposta dalla knowledge base

Dopo aver pubblicato una knowledge base, per eseguire query è necessario avere la chiave dell'endpoint di runtime, che non corrisponde alla chiave di sottoscrizione usata per creare il client di creazione.

Usare il metodo getKeys per ottenere un oggetto EndpointKeysDTO.

Per creare un client di runtime, chiamare QnAMakerRuntimeManager.authenticate e passare una chiave dell'endpoint di runtime dell'oggetto EndpointKeysDTO.

Generare una risposta da una knowledge base pubblicata usando il metodo generateAnswer. Questo metodo accetta l'ID knowledge base e un oggetto 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();
}

Questo è un semplice esempio di esecuzione di query su una knowledge base. Per informazioni sugli scenari di query avanzati, vedere altri esempi di query.

Eliminare una knowledge base

Eliminare la knowledge base tramite il metodo delete con un parametro dell'ID knowledge base.

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

Ottenere lo stato di un'operazione

Alcuni metodi, ad esempio per la creazione e l'aggiornamento, possono richiedere una quantità di tempo tale che invece di attendere il completamento del processo viene restituita un'operazione. Usare l'ID dell'operazione per eseguire il polling (con logica di ripetizione dei tentativi) in modo da determinare lo stato del metodo originale.

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

Eseguire l'applicazione

Ecco il metodo main per l'applicazione.

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

Eseguire l'applicazione come indicato di seguito. Si presuppone che il nome della classe sia Quickstart e che le dipendenze si trovino in una sottocartella denominata lib sotto la cartella corrente.

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

Il codice sorgente per questo esempio è disponibile su GitHub.

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione dei servizi di intelligenza artificiale di Azure, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

Passaggi successivi

Esercitazione: Testare la knowledge base con un file batch