Condividi tramite

Guida introduttiva: risposte alle domande personalizzate (CQA)

Questa guida introduttiva illustra i passaggi essenziali necessari per creare, testare e distribuire un progetto personalizzato di risposte alle domande (CQA) in Microsoft Foundry. Indipendentemente dal fatto che si stia eseguendo la transizione da Language Studio o si stia partendo da zero, questa guida introduttiva è adatta all'utente. Fornisce istruzioni chiare e attuabili per ottenere una distribuzione rapida e corretta del progetto CQA.

Note

  • Se si ha già una lingua di Azure in Foundry Tools o una risorsa multiservizio, sia usata autonomamente che tramite Language Studio, è possibile continuare a usare tali risorse di linguaggio esistenti all'interno del portale Foundry. Per altre informazioni, vedere Come usare gli strumenti Foundry nel portale foundry.
  • Consigliamo vivamente di utilizzare una risorsa Foundry all'interno di Foundry; tuttavia, è anche possibile seguire queste istruzioni usando una risorsa di lingua.

Prerequisiti

Prima di iniziare, sono necessarie le risorse e le autorizzazioni seguenti:

Get started

  1. Passare a Fonderia.

  2. Se non è già stato eseguito l'accesso, il portale richiede di farlo con le credenziali di Azure.

  3. Dopo l'accesso, è possibile creare o accedere ai progetti esistenti all'interno di Foundry.

  4. Se non si è già nel progetto per questa attività, selezionarlo.

Creare l'attività di ottimizzazione CQA

In Foundry un'attività di ottimizzazione viene usata come area di lavoro per le soluzioni CQA. In precedenza, un'attività di ottimizzazione era definita come progetto CQA. È possibile che entrambi i termini vengano usati in modo intercambiabile nella documentazione precedente di CQA.

  1. Dopo aver selezionato il progetto Foundry da usare per questa guida introduttiva, selezionare regolazione dettagliata dal menu di navigazione a sinistra.

    Screenshot della selezione del menu di ottimizzazione in Fonderia.

  2. Nella finestra principale selezionare la scheda Ottimizzazione del servizio di intelligenza artificiale e successivamente il pulsante + Ottimizza.

    Screenshot del pulsante di ottimizzazione in Fonderia.

  3. Nella finestra Crea servizio di ottimizzazione scegliere la scheda Risposte alle domande personalizzate, quindi selezionare Avanti.

    Screenshot della scheda personalizzata di risposte alle domande in Foundry.

  4. Selezionare la risorsa di Azure AI Search connessa nella finestra Crea attività di ottimizzazione CQA. Per altre informazioni, vedereConfigurare le connessioni alle risorse di Azure.

  5. Completare quindi i campi Nome e Lingua. Per questo progetto, è possibile lasciare la Risposta predefinita quando non viene restituita alcuna risposta così com'è (Nessuna risposta trovata).

  6. Selezionare il pulsante Crea.

Aggiungere un'origine della knowledge base CQA

Una knowledge base CQA è un set strutturato di coppie di domande e risposte ottimizzate per l'intelligenza artificiale conversazionale. La knowledge base usa l'elaborazione del linguaggio naturale per interpretare le query utente e restituire risposte accurate e consapevoli del contesto da un set di dati specifico.

  1. Nel menu Attività iniziali selezionare Gestisci origini.

    Screenshot della selezione di gestione delle fonti nella Foundry.

  2. Nella finestra principale selezionare il menu a discesa + Aggiungi origine.

  3. Nel menu a discesa è possibile selezionare Aggiungi chiacchiere, Aggiungi URL o Aggiungi file.

    Screenshot del menu a discesa Aggiungi fonte in Fonderia.

  4. Per questo progetto, scegliamo Aggiungi chiacchiere.

  5. Nella finestra Aggiungi nuova origine scegliere Semplice da usare.

    Screenshot della selezione dell'origine e del pulsante Aggiungi in Fonderia.

  6. Infine, selezionare Aggiungi. La creazione dell'origine potrebbe richiedere alcuni minuti.

  7. Dopo la creazione, l'origine viene elencata nella finestra Gestisci origini.

    Screenshot della gestione dell'elenco delle fonti in Fonderia.

Testare la Knowledge Base

  1. Selezionare Testa knowledge base nel menu Attività iniziali.

  2. Digitare quanto segue nel campo Digitare la domanda, quindi selezionare Esegui.

      Hello! How are you doing today?

  3. Nell'interfaccia di ispezione è possibile esaminare il livello di attendibilità della risposta e scegliere la risposta più adatta.

    Screenshot dell'interfaccia di ispezione in Foundry.

Distribuire la knowledge base

Distribuire una knowledge base CQA significa pubblicare il contenuto curato di domande e risposte come endpoint live e ricercabile. Questo processo sposta il progetto da una fase di test a un ambiente di produzione che consente alle applicazioni client di usarlo per vari progetti e soluzioni, tra cui chatbot.

  1. Al termine dell'ispezione, scegliere la sezione Distribuisci knowledge base nel menu Attività iniziali.

  2. Selezionare prima il pulsante Distribuisci nella finestra principale Distribuisci knowledge base e quindi nella finestra popup Distribuisci questo progetto. La distribuzione richiede alcuni minuti.

  3. Al termine della distribuzione, il progetto distribuito è elencato nella finestra Distribuisci knowledge base.

Ecco fatto! La knowledge base Risposte alle domande personalizzate (CQA) fornisce un'interfaccia del linguaggio naturale ai dati, consentendo agli utenti di interagire con le informazioni in modo conversazionale. Distribuendo questa soluzione, è possibile creare chatbot avanzati e agenti interattivi che comprendono le domande degli utenti, forniscono risposte precise e si adattano alla modifica dei requisiti informativi.

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. Sono necessari la chiave e l'endpoint dalla risorsa creata per connettersi all'API. Incollare la chiave e l'endpoint nel codice più avanti nell'argomento di avvio rapido.
  • Creare una risorsa Language con Azure CLI e specificare le proprietà seguenti:
  • 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 inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio si scriveranno 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

Si consiglia di eseguire l'autenticazione di Microsoft Entra ID con le identità gestite per le risorse di Azure al fine di evitare di archiviare le credenziali con le applicazioni eseguite nel cloud.

Usare le chiavi API con cautela. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente. Se si usano chiavi API, archiviarle in modo sicuro in Azure Key Vault, cambiarle regolarmente e limitare l’accesso ad Azure Key Vault usando il controllo degli accessi in base al ruolo e le restrizioni di accesso alla rete. Per altre informazioni sull’uso sicuro delle chiavi API nelle app, vedere Chiavi API con Azure Key Vault.

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

Note

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.

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 alle domande>Distribuisci il progetto>Ottieni URL di previsione. Un endpoint di esempio è: https://southcentralus.cognitiveservices.azure.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 alle domande>Distribuisci il 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. productiondipende dall'utente che distribuisce 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.cognitiveservices.azure.com/language/:query-knowledgebases?projectName={YOUR_PROJECT_NAME}&api-version=2021-10-01&deploymentName={DEPLOYMENT_NAME}'

Quando si esegue il codice, se si usa l'origine dati dai prerequisiti, si ottiene 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. Considerare il punteggio di attendibilità come percentuale moltiplicandolo per 100. Ad esempio, un punteggio di attendibilità pari a 0,9185 indica che il sistema di risposta alle domande personalizzato è 91,85% sicuro che la risposta sia corretta in base alle informazioni sul 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.cognitiveservices.azure.com//language/:query-knowledgebases?projectName=Sample-project&api-version=2021-10-01&deploymentName={DEPLOYMENT_NAME}'

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.

{
  "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.cognitiveservices.azure.com/language/:query-text?&api-version=2021-10-01'

Questo esempio restituisce 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 | 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. Sono necessari la chiave e l'endpoint dalla risorsa creata per connettersi all'API. Incollare la chiave e l'endpoint nel codice più avanti nell'argomento di avvio rapido.
  • Creare una risorsa Language con Azure CLI e specificare le proprietà seguenti:
  • Un progetto esistente su cui eseguire una query. Se non si ha un progetto, è possibile seguire le istruzioni nella guida introduttiva 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 inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio si scriveranno 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

Si consiglia di eseguire l'autenticazione di Microsoft Entra ID con le identità gestite per le risorse di Azure al fine di evitare di archiviare le credenziali con le applicazioni eseguite nel cloud.

Usare le chiavi API con cautela. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente. Se si usano chiavi API, archiviarle in modo sicuro in Azure Key Vault, cambiarle regolarmente e limitare l’accesso ad Azure Key Vault usando il controllo degli accessi in base al ruolo e le restrizioni di accesso alla rete. Per altre informazioni sull’uso sicuro delle chiavi API nelle app, vedere Chiavi API con Azure Key Vault.

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

Note

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.

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 consente di eseguire query su un progetto usando GetAnswers per ottenere una risposta alla domanda.

È necessario aggiornare il codice 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 alle domande>Distribuisci il progetto>Ottieni URL di previsione. Un endpoint di esempio è: https://southcentralus.cognitiveservices.azure.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 alle domande>Distribuisci il 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 la produzione, usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per ulteriori informazioni, vedere Sicurezza degli strumenti di fonderia.

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, Azure Key Vault fornisce un'archiviazione sicura per le chiavi.

Dopo aver aggiornato Program.cs e sostituito i valori corretti delle variabili. Eseguire l'applicazione con il comando dotnet run dalla directory dell'applicazione.

dotnet run

La 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 sui punteggi di attendibilità, aggiungere l'istruzione print seguente sotto le istruzioni print esistenti:

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

Se si esegue dotnet run di nuovo, si riceve 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)

Considerare il punteggio di attendibilità come percentuale moltiplicandolo per 100. Ad esempio, un punteggio di attendibilità pari a 0,9185 indica che il sistema di risposta alle domande personalizzato è 91,85% sicuro che la risposta sia corretta in base alle informazioni sul 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é è 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
(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}.cognitiveservices.azure.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, sostituire Program.cs con il contenuto del blocco di script e modificare le endpoint variabili e credential in modo che corrispondano alla risorsa del linguaggio 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.

Pacchetto (PyPI) | Esempi | 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 più avanti nell'argomento di avvio rapido.
  • Creare una risorsa Language con Azure CLI e specificare le proprietà seguenti:
  • Un progetto esistente su cui eseguire una query. Se non si ha un progetto, è possibile seguire le istruzioni nella guida introduttiva 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 consente 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 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 alle domande>Distribuisci il progetto>Ottieni URL di previsione. Un endpoint di esempio è: https://southcentralus.cognitiveservices.azure.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 alle domande>Distribuisci il 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.

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per ulteriori informazioni, consultare l'articolo sulla sicurezza di Foundry Tools.

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

endpoint = "https://{YOUR-ENDPOINT}.cognitiveservices.azure.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()

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, Azure Key Vault fornisce un'archiviazione sicura per le chiavi.

Quando si esegue il codice, 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 sui punteggi attendibili, aggiungere le istruzioni di stampa seguenti:

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

Si riceve 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

Considerare il punteggio di attendibilità come percentuale moltiplicandolo per 100. Ad esempio, un punteggio di attendibilità pari a 0,9185 indica che il sistema di risposta alle domande personalizzato è 91,85% sicuro che la risposta sia corretta in base alle informazioni sul progetto.

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 confidence_threshold parametro .

        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 risposte personalizzate alle domande 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}.cognitiveservices.azure.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, vedere i parametri AnswersFromTextOptions.

Pulire le risorse

Per pulire e rimuovere una risorsa di Intelligenza artificiale di Azure, è possibile eliminare la singola risorsa o l'intero gruppo di risorse. Se si elimina il gruppo di risorse, vengono eliminate anche tutte le risorse contenute all'interno.

Esplorare l'API REST

Passaggi successivi

  • Last updated on