Guida introduttiva: Risposta alla domanda personalizzata

Articolo
10/16/2024

Nota

Si sta cercando di eseguire la migrazione dei carichi di lavoro da QnA Maker? Per informazioni sui confronti delle funzionalità e sui passaggi della migrazione, vedere la guida alla migrazione.

Introduzione alla libreria client di risposta alle domande personalizzata. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

È possibile creare un progetto di risposta alla domanda personalizzata a partire da contenuto personalizzato, ad esempio domande frequenti o manuali del prodotto. Questo articolo fornisce un esempio su come creare un progetto di risposta alla domanda personalizzata da un manuale di un prodotto per rispondere alle domande.

Prerequisiti

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
Una risorsa della lingua con la funzionalità di risposta alle domande personalizzata abilitata. Prendere nota dell’istanza di Microsoft Entra ID, della sottoscrizione e del nome della risorsa linguistica selezionati al momento della creazione della risorsa.

Creare il primo progetto di risposta alla domanda personalizzata

Accedere a Language Studio con le credenziali di Azure.
Scorrere verso il basso fino alla sezione Domande delle risposte e selezionare Apri risposte alle domande personalizzate.
Se la risorsa non è ancora connessa a Ricerca di Azure, selezionare Connetti a Ricerca di Azure. Verrà aperta una nuova scheda del browser nel riquadro Funzionalità della risorsa nel portale di Azure.
Selezionare Abilita risposte alle domande personalizzate, scegliere la risorsa di Ricerca di Azure a cui collegarsi e quindi selezionare Applica.
Tornare alla scheda Language Studio. Potrebbe essere necessario aggiornare questa pagina per registrare la modifica nella risorsa. Selezionare Crea nuovo progetto.
Scegliere l'opzione Voglio impostare la lingua per tutti i progetti creati in questa risorsa>, selezionare Inglese> Selezionare Avanti.
Immettere un nome del progetto di esempio, una descrizione de il mio progetto di risposta alle domande e lasciare la risposta predefinita con l'impostazione Nessuna risposta trovata.
Esaminare le scelte effettuate e selezionare Crea progetto
Dalla pagina Gestisci risorse, selezionare Aggiungi risorsa>URL.
Selezionare Aggiungi URL e immettere i valori seguenti, quindi selezionare Aggiungi tutto:

Nome URL Valore URL

Guida per l'utente di Surface Book https://download.microsoft.com/download/7/B/1/7B10C82E-F520-4080-8516-5CF0D803EEE0/surface-book-user-guide-EN.pdf

Il processo di estrazione impiega alcuni minuti per leggere il documento e identificare le domande e risposte.

Dopo aver aggiunto correttamente l'origine, è possibile modificare il contenuto di origine per aggiungere altri set di risposte alle domande personalizzate.

Nome URL	Valore URL
Guida per l'utente di Surface Book	https://download.microsoft.com/download/7/B/1/7B10C82E-F520-4080-8516-5CF0D803EEE0/surface-book-user-guide-EN.pdf

Testare il progetto

Selezionare il collegamento all'origine. Verrà aperta la pagina di modifica del progetto.
Selezionare Testa dalla barra dei menu > Immettere la domanda Come faccio a configurare il mio surface book?. Verrà generata una risposta in base alle coppie di risposte alle domande identificate ed estratte automaticamente dall'URL di origine:

Se si seleziona la casella per includere una risposta breve, verrà visualizzata anche una risposta precisa, se disponibile, insieme al passaggio della risposta nel riquadro di test quando si pone una domanda.
Selezionare Ispeziona per esaminare la risposta in modo più dettagliato. La finestra di test viene usata per testare le modifiche apportate al progetto prima ella distribuzione.

Dall'interfaccia Ispeziona, è possibile visualizzare il livello di attendibilità con cui questa risposta risponderà alla domanda e modificare direttamente una determinata coppia di domande e risposte.

Distribuire il progetto

Selezionare l'icona Distribuisci progetto per accedere al menu Distribuisci progetto.

Quando si distribuisce un progetto, il contenuto del progetto passa dall'indice test a un indice prod in Ricerca di Azure.
Selezionare Distribuisci> e, quando richiesto, selezionare nuovamente Distribuisci.

Il progetto è stato distribuito correttamente. È possibile usare l'endpoint per rispondere alle domande nella propria applicazione personalizzata per rispondere o in un bot.

Prerequisiti

La versione corrente di cURL. Negli argomenti di avvio rapido vengono usate diverse opzioni della riga di comando, indicate nella documentazione di cURL.
Sottoscrizione di Azure: creare un account gratuito
La funzionalità di risposta alla domanda personalizzata richiede una risorsa linguistica con tale funzionalità abilitata per generare una chiave API e un endpoint.
- Dopo la distribuzione della risorsa Lingua, fare clic su Vai alla risorsa. Saranno necessari la chiave e l'endpoint dalla risorsa creata per connettersi all'API. Incollare la chiave e l'endpoint nel codice riportato di seguito in avvio rapido.
Per creare una risorsa linguistica con l’interfaccia della riga di comando di Azure, specificare le proprietà aggiuntive seguenti: --api-properties qnaAzureSearchEndpointId=/subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Search/searchServices/<azure-search-service-name> qnaAzureSearchEndpointKey=<azure-search-service-auth-key>
Un progetto esistente su cui eseguire una query. Se non è stato configurato un progetto, è possibile seguire le istruzioni nella Guida di avvio rapido di Language Studio. In alternativa, aggiungere un progetto che usa questo URL della Guida utente di Surface come origine dati.

Configurazione

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

Per impostare la variabile di ambiente per la chiave di risorsa Lingua, aprire una finestra della console e seguire le istruzioni per il sistema operativo e l'ambiente di sviluppo.

Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

Se è sufficiente accedere alla variabile di ambiente nella console in esecuzione corrente, è possibile impostare la variabile di ambiente con set anziché setx.

Dopo aver aggiunto le variabili di ambiente, potrebbe essere necessario riavviare tutti i programmi in esecuzione che dovranno leggerle, inclusa la finestra della console. Se ad esempio si usa Visual Studio come editor, riavviare Visual Studio prima di eseguire l'esempio.

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

Dopo avere aggiunto le variabili di ambiente, eseguire source ~/.bashrc dalla finestra della console per rendere effettive le modifiche.

Bash

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

Dopo avere aggiunto le variabili di ambiente, eseguire source ~/.bash_profile dalla finestra della console per rendere effettive le modifiche.

Xcode

Per lo sviluppo in iOS e macOS impostare le variabili di ambiente in Xcode. Ad esempio, seguire questi passaggi per impostare la variabile di ambiente in Xcode 13.4.1.

Selezionare Prodotto>Schema>Modifica schema
Selezionare Argomenti nella pagina Esegui (Esecuzione debug)
In Variabili di ambiente selezionare il segno più (+) per aggiungere una nuova variabile di ambiente.
Immettere LANGUAGE_KEY nel campo Nome e la chiave della risorsa Lingua nel campo Valore.
Eseguire questi passaggi per l'endpoint della risorsa. Assegnare alla nuova variabile di ambiente il nome LANGUAGE_ENDPOINT.

Per altre opzioni di configurazione, vedere la documentazione di Xcode.

Eseguire una query su un progetto

Generare una risposta da un progetto

Per eseguire una query su un progetto di risposta alla domanda personalizzata con le API REST e cURL, sono necessarie le informazioni seguenti:

Nome variabile	Valore
`Endpoint`	Questo valore è disponibile nella sezione Chiavi &ed endpoint durante l'esame della risorsa dalla portale di Azure. In alternativa, è possibile trovare il valore in Language Studio>risposta alla domanda>Distribuisci progetto>Ottieni URL di previsione. Un endpoint di esempio è: `https://southcentralus.api.cognitive.microsoft.com/`
`API-Key`	Questo valore è disponibile nella sezione Chiavi &ed endpoint durante l'esame della risorsa dalla portale di Azure. È possibile usare Key1 o Key2. Disporre sempre di due chiavi valide per una rotazione sicura delle chiavi senza tempi di inattività. In alternativa, è possibile trovare il valore in Language Studio>risposta alla domanda>Distribuisci progetto>Ottieni URL di previsione. Il valore della chiave fa parte della richiesta di esempio.
`Project`	Il nome del progetto di risposta alla domanda personalizzata.
`Deployment`	Esistono due valori possibili: `test` e `production`. `production` dipende dall'utente che ha distribuito il progetto da Language Studio>risposta alla domanda>Distribuisci progetto.

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 -X POST -H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" -H "Content-Type: application/json" -d '{
  "question": "How much battery life do I have left?"
  }'  '$LANGUAGE_ENDPOINT.api.cognitive.microsoft.com/language/:query-knowledgebases?projectName={YOUR_PROJECT_NAME}&api-version=2021-10-01&deploymentName={DEPLOYMENT_NAME}'

Quando si esegue il codice precedente, se si usa l'origine dati dai prerequisiti, si otterrà una risposta simile alla seguente:

{
"answers": [
    {
      "questions": [
        "Check battery level"
      ],
      "answer": "If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.",
      "confidenceScore": 0.9185,
      "id": 101,
      "source": "https://support.microsoft.com/en-us/surface/how-to-use-your-surface-pen-8a403519-cd1f-15b2-c9df-faa5aa924e98",
      "metadata": {},
      "dialog": {
        "isContextOnly": false,
        "prompts": []
      }
    }
  ]
}

confidenceScore restituisce un valore compreso tra 0 e 1. Questo valore è equiparabile a una percentuale, moltiplicata per 100. Di conseguenza, un punteggio di attendibilità pari a 0,9185 significa che la funzionalità di risposta alla domanda personalizzata è sicura al 91,85% che questa sia la risposta corretta alla domanda relativa al progetto.

Se si desidera escludere risposte in cui il punteggio di attendibilità scende al di sotto di una determinata soglia, è possibile aggiungere il parametro confidenceScoreThreshold.

curl -X POST -H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" -H "Content-Type: application/json" -d '{
  "question": "How much battery life do I have left?",
  "confidenceScoreThreshold": "0.95",
  }'  '$LANGUAGE_ENDPOINT.api.cognitive.microsoft.com//language/:query-knowledgebases?projectName=Sample-project&api-version=2021-10-01&deploymentName={DEPLOYMENT_NAME}'

Poiché si sa dall'esecuzione precedente del codice che il punteggio di attendibilità è: .9185, l'impostazione della soglia su .95 comporterà la restituzione della risposta predefinita.

{
  "answers": [
    {
      "questions": [],
      "answer": "No good match found in KB",
      "confidenceScore": 0.0,
      "id": -1,
      "metadata": {}
    }
  ]
}

Eseguire query sul testo senza un progetto

È anche possibile usare la funzionalità di risposta alla domanda personalizzata senza un progetto con l'API REST predefinita per tale funzionalità, che viene chiamata tramite query-text. In questo caso, è possibile fornire risposte alle domande con una domanda e con i record di testo associati che si desiderano cercare per una risposta al momento dell'invio della richiesta.

Per questo esempio, è sufficiente modificare le variabili per API KEY e ENDPOINT.

curl -X POST -H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" -H "Content-Type: application/json" -d '{
"question":"How long does it takes to charge a surface?",
"records":[
{"id":"doc1","text":"Power and charging.It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you\u0027re using your Surface for power-intensive activities like gaming or video streaming while you\u0027re charging it"},
{"id":"doc2","text":"You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface."}],
"language":"en",
"stringIndexType":"Utf16CodeUnit"
}'  '$LANGUAGE_ENDPOINT.api.cognitive.microsoft.com/language/:query-text?&api-version=2021-10-01'

Questo esempio restituirà un risultato di:

{  
"answers": [
    {
      "answer": "Power and charging.It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it",
      "confidenceScore": 0.9118788838386536,
      "id": "doc1",
      "answerSpan": {
        "text": "two to four hours",
        "confidenceScore": 0.9850527,
        "offset": 27,
        "length": 18
      },
      "offset": 0,
      "length": 243
    },
    {
      "answer": "It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it",
      "confidenceScore": 0.052793052047491074,
      "id": "doc1",
      "answerSpan": {
        "text": "longer",
        "confidenceScore": 0.6694634,
        "offset": 11,
        "length": 7
      },
      "offset": 109,
      "length": 134
    },
    {
      "answer": "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface.",
      "confidenceScore": 0.017600709572434425,
      "id": "doc2",
      "answerSpan": {
        "text": "USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging",
        "confidenceScore": 0.1544854,
        "offset": 15,
        "length": 165
      },
      "offset": 0,
      "length": 280
    }
  ]
}

Usare questa guida introduttiva per la libreria client della funzionalità di risposta alla domanda personalizzata per .NET per:

Ottenere una risposta da un progetto.
Ottenere una risposta da un corpo di testo inviato insieme alla domanda.
Ottenere il punteggio di attendibilità per la risposta alla domanda.

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

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
IDE di Visual Studio o la versione corrente di .NET Core.
La funzionalità di risposta alla domanda personalizzata richiede una risorsa linguistica con tale funzionalità abilitata per generare una chiave API e un endpoint.
- Dopo la distribuzione della risorsa Lingua, fare clic su Vai alla risorsa. Saranno necessari la chiave e l'endpoint dalla risorsa creata per connettersi all'API. Incollare la chiave e l'endpoint nel codice riportato di seguito in avvio rapido.
Per creare una risorsa linguistica con l’interfaccia della riga di comando di Azure, specificare le proprietà aggiuntive seguenti: --api-properties qnaAzureSearchEndpointId=/subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Search/searchServices/<azure-search-service-name> qnaAzureSearchEndpointKey=<azure-search-service-auth-key>
Un progetto esistente su cui eseguire una query. Se non è stato configurato un progetto, è possibile seguire le istruzioni nella Guida di avvio rapido di Language Studio. In alternativa, aggiungere un progetto che usa questo URL della Guida utente di Surface come origine dati.

Configurazione

Creare variabili di ambiente

Per impostare la variabile di ambiente per la chiave di risorsa Lingua, aprire una finestra della console e seguire le istruzioni per il sistema operativo e l'ambiente di sviluppo.

Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

Se è sufficiente accedere alla variabile di ambiente nella console in esecuzione corrente, è possibile impostare la variabile di ambiente con set anziché setx.

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

Dopo avere aggiunto le variabili di ambiente, eseguire source ~/.bashrc dalla finestra della console per rendere effettive le modifiche.

Bash

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

Dopo avere aggiunto le variabili di ambiente, eseguire source ~/.bash_profile dalla finestra della console per rendere effettive le modifiche.

Xcode

Per lo sviluppo in iOS e macOS impostare le variabili di ambiente in Xcode. Ad esempio, seguire questi passaggi per impostare la variabile di ambiente in Xcode 13.4.1.

Selezionare Prodotto>Schema>Modifica schema
Selezionare Argomenti nella pagina Esegui (Esecuzione debug)
In Variabili di ambiente selezionare il segno più (+) per aggiungere una nuova variabile di ambiente.
Immettere LANGUAGE_KEY nel campo Nome e la chiave della risorsa Lingua nel campo Valore.
Eseguire questi passaggi per l'endpoint della risorsa. Assegnare alla nuova variabile di ambiente il nome LANGUAGE_ENDPOINT.

Per altre opzioni di configurazione, vedere la documentazione di Xcode.

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 question-answering-quickstart. Questo comando crea un semplice progetto C# "Hello World" con un unico file di origine: program.cs.

dotnet new console -n question-answering-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 risposta alla domanda personalizzata per .NET con il comando seguente:

dotnet add package Azure.AI.Language.QuestionAnswering

Eseguire una query su un progetto

Generare una risposta da un progetto

L'esempio seguente consentirà di eseguire query su un progetto usando GetAnswers per ottenere una risposta alla domanda.

Sarà necessario aggiornare il codice seguente e specificare i propri valori per le variabili seguenti.

Nome variabile	Valore
`endpoint`	Questo valore è disponibile nella sezione Chiavi &ed endpoint durante l'esame della risorsa dalla portale di Azure. In alternativa, è possibile trovare il valore in Language Studio>risposta alla domanda>Distribuisci progetto>Ottieni URL di previsione. Un endpoint di esempio è: `https://southcentralus.api.cognitive.microsoft.com/`
`credential`	Questo valore è disponibile nella sezione Chiavi &ed endpoint durante l'esame della risorsa dalla portale di Azure. È possibile usare Key1 o Key2. Disporre sempre di due chiavi valide per una rotazione sicura delle chiavi senza tempi di inattività. In alternativa, è possibile trovare il valore in Language Studio>risposta alla domanda>Distribuisci progetto>Ottieni URL di previsione. Il valore della chiave fa parte della richiesta di esempio.
`projectName`	Il nome del progetto di risposta alla domanda personalizzata.
`deploymentName`	Esistono due valori possibili: `test` e `production`. `production` dipende dall'utente che ha distribuito il progetto da Language Studio>risposta alla domanda>Distribuisci progetto.

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per un ambiente di produzione usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedere l'articolo sulla sicurezza del Servizi di Azure AI.

Dalla directory del progetto aprire il file program.cs e sostituirlo con il codice seguente:

using Azure;
using Azure.AI.Language.QuestionAnswering;
using System;

namespace question_answering
{
    class Program
    {
        static void Main(string[] args)
        {

            // This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
            Uri endpoint = new Uri("LANGUAGE_ENDPOINT");
            AzureKeyCredential credential = new AzureKeyCredential("LANGUAGE_KEY");
            string projectName = "{YOUR-PROJECT-NAME}";
            string deploymentName = "production";

            string question = "How long should my Surface battery last?";

            QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);
            QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);

            Response<AnswersResult> response = client.GetAnswers(question, project);

            foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
            {
                Console.WriteLine($"Q:{question}");
                Console.WriteLine($"A:{answer.Answer}");
            }
        }
    }
}

Mentre si codificano in modo rigido le variabili per l'esempio. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali, Ad esempio, l'insieme di credenziali delle chiavi di Azure fornisce un'archiviazione delle chiavi sicura.

Dopo l'aggiornamento di Program.cs con il codice precedente e la sostituzione dei valori delle variabili corretti. Eseguire l'applicazione con il comando dotnet run dalla directory dell'applicazione.

dotnet run

La risposta sarà simile alla seguente:

Q: How much battery life do I have left?
A: If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.

Per informazioni su quanto la funzionalità risposta alla domanda personalizzata consideri attendibile la risposta corretta, aggiungere un'istruzione di stampa aggiuntiva sotto le istruzioni di stampa esistenti:

Console.WriteLine($"Q:{question}");
Console.WriteLine($"A:{answer.Answer}");
Console.WriteLine($"({answer.Confidence})"); // add this line

Se si esegue nuovamente dotnet run, si riceverà ora un risultato con un punteggio di attendibilità:

Q:How much battery life do I have left?
A:If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.
(0.9185)

Il punteggio di attendibilità restituisce un valore compreso tra 0 e 1. Questo valore è equiparabile a una percentuale, moltiplicata per 100. Di conseguenza, un punteggio di attendibilità pari a 0,9185 significa che la funzionalità di risposta alla domanda personalizzata è sicura al 91,85% che questa sia la risposta corretta alla domanda relativa al progetto.

Se si desidera escludere risposte in cui il punteggio di attendibilità scende al di sotto di una determinata soglia, è possibile usare AnswerOptions per aggiungere la proprietà ConfidenceScoreThreshold.

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
AnswersOptions options = new AnswersOptions(); //Add this line
options.ConfidenceThreshold = 0.95; //Add this line

Response<AnswersResult> response = client.GetAnswers(question, project, options); //Add the additional options parameter

Poiché si sa dall'esecuzione precedente del codice che il punteggio di attendibilità è: .9185, l'impostazione della soglia su .95 comporterà la restituzione della risposta predefinita.

Q:How much battery life do I have left?
A:No good match found in KB
(0)

Eseguire query sul testo senza un progetto

È anche possibile usare la funzionalità di risposta alla domanda personalizzata senza un progetto con GetAnswersFromText. In questo caso, è possibile fornire alla funzionalità di risposta personalizzata sia una domanda che i record di testo associati in cui si vorrebbe che fosse ricercata la risposta al momento dell'invio della richiesta.

Per questo esempio, è sufficiente modificare le variabili per endpoint e credential.

using Azure;
using Azure.AI.Language.QuestionAnswering;
using System;
using System.Collections.Generic;


namespace questionansweringcsharp
{
    class Program
    {
        static void Main(string[] args)
        {

            Uri endpoint = new Uri("https://{YOUR-ENDPOINT}.api.cognitive.microsoft.com/");
            AzureKeyCredential credential = new AzureKeyCredential("YOUR-LANGUAGE-RESOURCE-KEY");
            QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

            IEnumerable<TextDocument> records = new[]
            {
                new TextDocument("doc1", "Power and charging.It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. " +
                         "It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it"),
                new TextDocument("doc2", "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. " +
                         "The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface."),
            };

            AnswersFromTextOptions options = new AnswersFromTextOptions("How long does it takes to charge a surface?", records);
            Response<AnswersFromTextResult> response = client.GetAnswersFromText(options);

           foreach (TextAnswer answer in response.Value.Answers)
            {
                if (answer.Confidence > .9)
                {
                    string BestAnswer = response.Value.Answers[0].Answer;

                    Console.WriteLine($"Q:{options.Question}");
                    Console.WriteLine($"A:{BestAnswer}");
                    Console.WriteLine($"Confidence Score: ({response.Value.Answers[0].Confidence:P2})"); //:P2 converts the result to a percentage with 2 decimals of accuracy. 
                    break;
                }
                else
                {
                    Console.WriteLine($"Q:{options.Question}");
                    Console.WriteLine("No answers met the requested confidence score.");
                    break;
                }
            }

        }
    }
}

Per eseguire il codice precedente, sostituire Program.cs con il contenuto del blocco di script precedente e modificare le variabili endpoint e credential in modo che corrispondano alla risorsa di lingua creata come parte dei prerequisiti.

In questo caso, viene eseguita l'iterazione di tutte le risposte e viene restituita solo la risposta con il punteggio di attendibilità più alto maggiore di 0,9. Altre informazioni sulle opzioni disponibili con GetAnswersFromText.

Usare questa guida introduttiva per la libreria client della funzionalità di risposta alla domanda personalizzata per Python per:

Ottenere una risposta da un progetto.
Ottenere una risposta da un corpo di testo inviato insieme alla domanda.
Ottenere il punteggio di attendibilità per la risposta alla domanda.

Documentazione di riferimento | Pacchetto (PyPI) | Esempi aggiuntivi | Codice sorgente della libreria

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
Python 3.x
La funzionalità di risposta alla domanda personalizzata richiede una risorsa linguistica con tale funzionalità abilitata per generare una chiave API e un endpoint.
- Dopo la distribuzione della risorsa Lingua, fare clic su Vai alla risorsa. Sono necessari la chiave e l'endpoint dalla risorsa creata per connettersi all'API. Incollare la chiave e l'endpoint nel codice riportato di seguito in avvio rapido.
Per creare una risorsa linguistica con l'interfaccia della riga di comando di Azure, specificare le altre proprietà seguenti: --api-properties qnaAzureSearchEndpointId=/subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Search/searchServices/<azure-search-service-name> qnaAzureSearchEndpointKey=<azure-search-service-auth-key>
Un progetto esistente su cui eseguire una query. Se non è stato configurato un progetto, è possibile seguire le istruzioni nella Guida di avvio rapido di Language Studio. In alternativa, aggiungere un progetto che usa questo URL della Guida utente di Surface come origine dati.

Configurazione

Installare la libreria client

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

pip install azure-ai-language-questionanswering

Eseguire una query su un progetto

Generare una risposta da un progetto

L'esempio seguente consentirà di eseguire query su un progetto usando get_answers per ottenere una risposta alla domanda. È possibile copiare questo codice in un file .py dedicato o in una cella in Jupyter Notebook/Lab.

È necessario aggiornare il codice seguente e specificare i propri valori per le variabili seguenti.

Nome variabile	Valore
`endpoint`	Questo valore è disponibile nella sezione Chiavi &ed endpoint durante l'esame della risorsa dalla portale di Azure. In alternativa, è possibile trovare il valore in Language Studio>risposta alla domanda>Distribuisci progetto>Ottieni URL di previsione. Un endpoint di esempio è: `https://southcentralus.api.cognitive.microsoft.com/`
`credential`	Questo valore è disponibile nella sezione Chiavi &ed endpoint durante l'esame della risorsa dalla portale di Azure. È possibile usare Key1 o Key2. Disporre sempre di due chiavi valide per una rotazione sicura delle chiavi senza tempi di inattività. In alternativa, è possibile trovare il valore in Language Studio>risposta alla domanda>Distribuisci progetto>Ottieni URL di previsione. Il valore della chiave fa parte della richiesta di esempio.
`knowledge_base_project`	Nome del progetto di risposta alla domanda.
`deployment`	Esistono due valori possibili: `test` e `production`. `production` dipende dall'utente che ha distribuito il progetto da Language Studio>risposta alla domanda>Distribuisci progetto.

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedere l'articolo Sicurezza di Servizi di Azure AI.

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient

endpoint = "https://{YOUR-ENDPOINT}.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("{YOUR-LANGUAGE-RESOURCE-KEY}")
knowledge_base_project = "{YOUR-PROJECT-NAME}"
deployment = "production"

def main():
    client = QuestionAnsweringClient(endpoint, credential)
    with client:
        question="How much battery life do I have left?"
        output = client.get_answers(
            question = question,
            project_name=knowledge_base_project,
            deployment_name=deployment
        )
    print("Q: {}".format(question))
    print("A: {}".format(output.answers[0].answer))

if __name__ == '__main__':
    main()

Quando si esegue il codice precedente, se si usa l'origine dati dai prerequisiti, si ottiene una risposta simile alla seguente:

Q: How much battery life do I have left?
A: If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.

Per informazioni su come la funzionalità di risposta personalizzata considera attendibile una risposta corretta, aggiungere un'altra istruzione di stampa sotto le istruzioni di stampa esistenti:

print("Q: {}".format(question))
print("A: {}".format(output.answers[0].answer))
print("Confidence Score: {}".format(output.answers[0].confidence)) # add this line

A questo punto si riceverà un risultato con un punteggio di attendibilità:

Q: How much battery life do I have left?
A: If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.
Confidence Score: 0.9185

Se si desidera escludere risposte in cui il punteggio di attendibilità scende al di sotto di una determinata soglia, è possibile modificare AnswerOptions per aggiungere il parametro confidence_threshold.

        output = client.get_answers(
            confidence_threshold = 0.95, #add this line
            question = question,
            project_name=knowledge_base_project,
            deployment_name=deployment
        )

Poiché è certi dall'esecuzione precedente del codice che il punteggio di attendibilità è: .9185, l'impostazione della soglia su .95 comporta la restituzione della risposta predefinita.

Q: How much battery life do I have left?
A: No good match found in KB
Confidence Score: 0.0

Eseguire query sul testo senza un progetto

È anche possibile usare la funzionalità di risposta personalizzata senza un progetto con get_answers_from_text. In questo caso, è possibile fornire alla funzionalità di risposta personalizzata sia una domanda che i record di testo associati in cui si vorrebbe che fosse ricercata la risposta al momento dell'invio della richiesta.

Per questo esempio, è sufficiente modificare le variabili per endpoint e credential.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.ai.language.questionanswering import models as qna

endpoint = "https://{YOUR-ENDPOINT}.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("YOUR-LANGUAGE-RESOURCE-KEY")

def main():
    client = QuestionAnsweringClient(endpoint, credential)
    with client:
        question="How long does it takes to charge a surface?"
        input = qna.AnswersFromTextOptions(
            question=question,
            text_documents=[
                "Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. " +
                "It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it.",
                "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. " +
                "The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface.",
            ]
        )


        output = client.get_answers_from_text(input)

    best_answer = [a for a in output.answers if a.confidence > 0.9][0]
    print(u"Q: {}".format(input.question))
    print(u"A: {}".format(best_answer.answer))
    print("Confidence Score: {}".format(output.answers[0].confidence))

if __name__ == '__main__':
    main()

È possibile copiare questo codice in un file .py dedicato o in una nuova cella in Jupyter Notebook/Lab. Questo esempio restituisce un risultato di:

Q: How long does it takes to charge surface?
A: Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it.
Confidence Score: 0.9254655838012695

In questo caso, viene eseguita l'iterazione di tutte le risposte e viene restituita solo la risposta con il punteggio di attendibilità più alto maggiore di 0,9. Per altre informazioni sulle opzioni disponibili con get_answers_from_text, rivedere i parametri AnswersFromTextOptions.

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è 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.

Esplorare l'API REST

Per informazioni sull'automazione della pipeline della funzionalità di risposta alla domanda personalizzata, vedere la documentazione dell'API REST. Attualmente la funzionalità di creazione è disponibile solo tramite l'API REST:

Passaggi successivi

Esercitazione: Creare un bot di domande frequenti

Condividi tramite

Guida introduttiva: Risposta alla domanda personalizzata

Prerequisiti

Creare il primo progetto di risposta alla domanda personalizzata

Testare il progetto

Distribuire il progetto

Prerequisiti

Configurazione

Creare variabili di ambiente

Bash

Xcode

Eseguire una query su un progetto

Generare una risposta da un progetto

Eseguire query sul testo senza un progetto

Prerequisiti

Configurazione

Creare variabili di ambiente

Bash

Xcode

CLI

Eseguire una query su un progetto

Generare una risposta da un progetto

Eseguire query sul testo senza un progetto

Prerequisiti

Configurazione

Installare la libreria client

Eseguire una query su un progetto

Generare una risposta da un progetto

Eseguire query sul testo senza un progetto

Pulire le risorse

Esplorare l'API REST

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive