快速入門：QnA Maker 用戶端連結庫

注意

Azure Open AI On Your Data 會利用大型語言模型 （LLM） 來產生與 QnA Maker 類似的結果。 如果您想要將 QnA Maker 專案移轉至 Azure Open AI On Your Data，請參閱我們的 指南。

開始使用 QnA Maker 用戶端連結庫。 請遵循下列步驟來安裝套件，並試用基本工作的範例程序代碼。

注意

QnA Maker 服務即將於 2025 年 3 月 31 日淘汰。 較新版的問題和解答功能現在隨附於 Azure AI 語言。 如需瞭解語言服務內的問題解答功能，請參閱問題解答。 從 2022 年 10 月 1 日開始，您將無法建立新的 QnA Maker 資源。 如需將現有 QnA Maker 知識庫移轉至問題解答的相關資訊，請參閱移轉指南。

必要條件

注意

本文件不適用於最新版本。 若要瞭解如何搭配最新版本使用 REST API，請參閱 回答 REST API 的問題快速入門

• 最新版的 cURL。 在快速入門中會使用數個命令行參數，如 cURL 檔中所述。

• 您必須有 QnA Maker 資源，才能使用金鑰和資源名稱。 您在資源建立期間輸入資源 名稱 ，然後為您建立金鑰。 資源名稱會作為端點的子域。 若要擷取金鑰和資源名稱，請在 Azure 入口網站 中選取資源的快速入門。 資源名稱是端點 URL 的第一個子域：

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

警告

下列BASH範例使用 \ 行接續字元。 如果您控制台或終端機使用不同的行接續字元，請使用此字元。

建立知識庫

若要使用 REST API 和 cURL 建立 知識庫，您需要具備下列資訊：

資訊	cURL 組態	目的
QnA Maker 資源名稱	URL	用來建構 URL
QnA Maker 資源金鑰	-h 標頭的 Ocp-Apim-Subscription-Key param	向 QnA Maker 服務進行驗證
描述 知識庫的 JSON	-d 參數	JSON 範例
以位元組為單位的 JSON 大小	-h 標頭的 Content-Size param

cURL 命令是從BASH殼層執行。 使用您自己的資源名稱、資源索引鍵和 JSON 值和 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"]}'

來自 QnA Maker 的 cURL 回應包含 operationId ，這是取得作業狀態所需的 。

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

取得作業狀態

當您建立 知識庫 時，因為作業是異步的，因此回應會包含決定狀態的資訊。

資訊	cURL 組態	目的
QnA Maker 資源名稱	URL	用來建構 URL
作業標識碼	URL 路由	/operations/REPLACE-WITH-YOUR-OPERATION-ID
QnA Maker 資源金鑰	-h 標頭的 Ocp-Apim-Subscription-Key param	向 QnA Maker 服務進行驗證

cURL 命令是從BASH殼層執行。 使用您自己的資源名稱、資源金鑰和作業識別碼編輯此命令。

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"

cURL 回應包含狀態。 如果作業狀態成功，則 resourceLocation 包含 知識庫標識碼。

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

發佈 知識庫

查詢 知識庫 之前，您需要：

• 發佈 知識庫
• 取得運行時間端點金鑰

此工作會發佈 知識庫。 取得運行時間端點金鑰是個別 的工作。

資訊	cURL 組態	目的
QnA Maker 資源名稱	URL	用來建構 URL
QnA Maker 資源金鑰	-h 標頭的 Ocp-Apim-Subscription-Key param	向 QnA Maker 服務進行驗證
知識庫標識碼	URL 路由	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

cURL 命令是從BASH殼層執行。 使用您自己的資源名稱、資源金鑰和 知識庫 識別碼編輯此命令。

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

回應狀態為 204，沒有結果。 -v使用命令行參數來查看 cURL 命令的詳細信息輸出。 這將會包含 HTTP 狀態。

取得發佈 知識庫 的運行時間端點金鑰

在查詢 知識庫 之前，您需要：

• 發佈 知識庫
• 取得運行時間端點金鑰

此工作會取得運行時間端點金鑰。 發佈 知識庫 是個別的工作。

運行時間端點金鑰是使用 QnA Maker 資源的所有 知識庫 相同的金鑰。

資訊	cURL 組態	目的
QnA Maker 資源名稱	URL	用來建構 URL
QnA Maker 資源金鑰	-h 標頭的 Ocp-Apim-Subscription-Key param	向 QnA Maker 服務進行驗證

cURL 命令是從BASH殼層執行。 使用您自己的資源名稱、資源金鑰編輯此命令。

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"

cURL 回應包含運行時間端點金鑰。 查詢時，只要使用其中一個索引鍵，即可從 知識庫 取得答案。

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

從已發佈的 知識庫 查詢答案

從知識中取得答案是從不同的運行時間完成，而不是管理 知識庫。 因為它是個別的運行時間，因此您必須使用運行時間金鑰進行驗證。

資訊	cURL 組態	目的
QnA Maker 資源名稱	URL	用來建構 URL
QnA Maker 執行時間金鑰	-h 標頭的 Authorization param	索引鍵是字串的一部分，其中包含 這個字 Endpointkey 。 向 QnA Maker 服務進行驗證
知識庫標識碼	URL 路由	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
描述查詢的 JSON	-d 參數	要求本文參數和 JSON 的範例
以位元組為單位的 JSON 大小	-h 標頭的 Content-Size param

cURL 命令是從BASH殼層執行。 使用您自己的資源名稱、資源金鑰和 知識庫 識別碼編輯此命令。

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

成功的回應包含頂端答案，以及用戶端應用程式，例如聊天機器人等資訊，必須向用戶顯示答案。

刪除 知識庫

當您完成 知識庫 時，請將其刪除。

資訊	cURL 組態	目的
QnA Maker 資源名稱	URL	用來建構 URL
QnA Maker 資源金鑰	-h 標頭的 Ocp-Apim-Subscription-Key param	向 QnA Maker 服務進行驗證
知識庫標識碼	URL 路由	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

cURL 命令是從BASH殼層執行。 使用您自己的資源名稱、資源金鑰和 知識庫 識別碼編輯此命令。

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"

回應狀態為 204，沒有結果。 -v使用命令行參數來查看 cURL 命令的詳細信息輸出。 這將會包含 HTTP 狀態。

其他資源

• 撰寫參考檔
• 運行時間 參考檔
• 使用 cURL 的範例 BASH 腳本

使用適用於 .NET 的 QnA Maker 用戶端連結庫來：

• 建立知識庫
• 更新知識庫
• 發佈知識庫
• 取得預測運行時間端點金鑰
• 等候長時間執行的工作
• 下載知識庫
• 從知識庫取得答案
• 刪除知識庫

參考文件 | 連結庫原始程式碼 | 套件 （NuGet） | C# 範例

注意

2019 年 7 月 1 日之後建立的新資源會使用自訂的子網域名稱。 如需詳細資訊和完整的區域端點清單，請參閱 Azure AI 服務的自訂子網域名稱。

必要條件

注意

本文件不適用於最新版本。 若要瞭解如何搭配最新版本使用 C# API，請參閱 回答 C# 的問題快速入門。

• Azure 訂用帳戶 - 建立免費帳戶
• Visual Studio IDE 或目前版本的 .NET Core。
• 擁有 Azure 訂用帳戶之後，請在 Azure 入口網站 中建立 QnA Maker 資源，以取得您的撰寫密鑰和資源名稱。 在其部署後，選取 [前往資源]。
  • 您需要從您建立的資源取得密鑰和資源名稱，才能將應用程式連線到 QnA Maker API。 將金鑰和資源名稱貼到快速入門稍後的程式代碼中。
  • 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

設定

CLI

在主控台視窗中 (例如 cmd、PowerShell 或 Bash)，使用 dotnet new 命令建立名為 qna-maker-quickstart 的新主控台應用程式。 此命令會建立簡單的 "Hello World" C# 專案，內含單一原始程式檔：program.cs。

dotnet new console -n qna-maker-quickstart

將目錄變更為新建立的應用程式資料夾。 您可以使用下列命令來建置應用程式：

dotnet build

建置輸出應該不會有警告或錯誤。

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

在應用程式目錄中，使用下列命令安裝適用於 .NET 的 QnA Maker 用戶端連結庫：

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

提示

想要一次檢視整個快速入門程式代碼檔案嗎？ 您可以在 GitHub 上找到它，其中包含本快速入門中的程式碼範例。

using 指示詞

從項目目錄中，開啟 program.cs 檔案，並新增下列 using 指示詞：

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

訂用帳戶金鑰和資源端點

在應用程式的方法中 Main ，新增下一節所示的變數和程序代碼，以使用本快速入門中的一般工作。

• 我們會使用訂用帳戶密鑰並交換撰寫金鑰。 如需撰寫密鑰的詳細資訊，請遵循 QnA Maker 中的金鑰。

• QNA_MAKER_ENDPOINT 的值的格式 https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com為 。 移至 Azure 入口網站，並尋找您在必要條件中建立的 QnA Maker 資源。 選取 [金鑰和端點] 頁面，在 [資源管理] 下找出 [撰寫][訂用帳戶] 密鑰和 QnA Maker 端點。

• QNA_MAKER_RUNTIME_ENDPOINT 的值的格式為 https://YOUR-RESOURCE-NAME.azurewebsites.net。 移至 Azure 入口網站，並尋找您在必要條件中建立的 QnA Maker 資源。 選取 [導出範本] 頁面，在 [自動化] 底下找出 [運行時間端點]。

重要

完成時，請記得從程式碼中移除金鑰，且不要公開張貼金鑰。 在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。 如需詳細資訊，請參閱 Azure AI 服務安全性一文。

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

物件模型

QnA Maker 使用兩個不同的物件模型：

• QnAMakerClient 是用來建立、管理、發佈及下載知識庫的物件。
• QnAMakerRuntime 是使用 GenerateAnswer API 查詢 知識庫 的物件，並使用訓練 API 傳送新的建議問題（作為使用中學習的一部分）。

使用此範例 知識庫

本快速入門中的 知識庫 會以 2 對交談式 QnA 配對開始，這是為了簡化範例，並在 Update 方法中使用高度可預測的標識符，將後續提示與新配對的問題產生關聯。 本快速入門已依特定順序規劃及實作此快速入門。

如果您打算隨著時間開發您的 知識庫，以及相依於現有 QnA 配對的後續提示，您可以選擇：

• 對於較大的知識庫，請在支援自動化的文本編輯器或 TSV 工具中管理 知識庫，然後使用更新一次完全取代 知識庫。
• 對於較小的知識庫，請在 QnA Maker 入口網站中完全管理後續提示。

本快速入門中使用的 QnA 配對詳細數據：

• QnA 配對的類型 - 更新之後，此 知識庫 中有 2 種類型的 QnA 組：chitchat 和網域特定資訊。 如果您的知識庫系結至交談應用程式，例如聊天機器人，則這是典型的。
• 雖然知識庫答案可以依元數據篩選或使用後續提示，但本快速入門不會顯示。 在這裡尋找那些與語言無關的generateAnswer範例。
• 回應文字是 Markdown，而且可以包含 各種不同的 Markdown ，例如影像（公開可用的因特網影像）、連結（公開可用的 URL），以及專案符號點，本快速入門不會使用該品種。

QnAMakerClient 物件模型

撰寫 QnA Maker 用戶端是 QnAMakerClient 物件，可使用包含密鑰的 Microsoft.Rest.ServiceClientCredentials 向 Azure 進行驗證。

建立客戶端之後，請使用知識庫屬性來建立、管理及發佈您的 知識庫。

傳送 JSON 物件來管理您的 知識庫。 針對立即作業，方法通常會傳回指出狀態的 JSON 物件。 對於長時間執行的作業，回應是作業標識符。 呼叫用戶端。Operations.GetDetailsAsync 方法與作業標識符，以判斷要求的狀態。

QnAMakerRuntimeClient 物件模型

預測 QnA Maker 用戶端是 QnAMakerRuntimeClient 物件，會使用 Microsoft.Rest.ServiceClientCredentials 向 Azure 進行驗證，其中包含您的預測運行時間密鑰， client.EndpointKeys.GetKeys 在發布知識庫之後，從撰寫用戶端呼叫傳回。

使用 GenerateAnswer 方法從查詢運行時間取得答案。

程式碼範例

這些代碼段示範如何使用適用於 .NET 的 QnA Maker 用戶端連結庫執行下列動作：

• 驗證撰寫用戶端
• 建立知識庫
• 更新 知識庫
• 下載 知識庫
• 發佈知識庫
• 刪除 知識庫
• 取得查詢運行時間金鑰
• 取得作業的狀態
• 驗證查詢運行時間用戶端
• 從 知識庫 產生答案

驗證用戶端以撰寫 知識庫

使用密鑰具現化客戶端物件，並將其與您的資源搭配使用，以建構端點來建立具有端點和密鑰的 QnAMakerClient 。 建立 ServiceClientCredentials 物件。

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

建立知識庫

知識庫 會儲存三個來源中 CreateKbDTO 物件的問答組：

• 針對 編輯內容，請使用 QnADTO 物件。
  • 若要使用元數據和後續提示，請使用編輯內容，因為此數據會新增至個別 QnA 配對層級。
• 針對 檔案，請使用 FileDTO 物件。 FileDTO 包含要連線到檔案的檔名和公用 URL。
• 針對 URL，請使用字串清單來代表公開可用的 URL。

建立步驟也包含知識庫的屬性：

• defaultAnswerUsedForExtraction - 找不到答案時傳回的內容
• enableHierarchicalExtraction - 自動建立所擷取 QnA 配對之間的提示關聯性
• language - 建立資源的第一個知識庫時，將語言設定為在 Azure 搜尋服務索引中使用。

呼叫 CreateAsync 方法，然後將傳回的作業標識碼傳遞至 MonitorOperation 方法，以輪詢狀態。

下列程式代碼的最後一行會從 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);
}

請務必包含MonitorOperation上述程式代碼中參考的函式，才能成功建立 知識庫。

更新 知識庫

您可以將 知識庫 標識符和 UpdatekbOperationDTO 傳入 UpdateAsync 方法，以更新 知識庫。 使用 MonitorOperation 方法來判斷更新是否成功。

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

請務必包含MonitorOperation上述程式代碼中參考的函式，才能成功更新 知識庫。

下載 知識庫

使用 DownloadAsync 方法將資料庫下載為 QnADocumentsDTO 清單。 這不等於 QnA Maker 入口網站從 設定 頁面匯出，因為此方法的結果不是檔案。

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
}

發佈知識庫

使用 PublishAsync 方法來發佈 知識庫。 這會採用目前儲存和定型的模型，由 知識庫標識元參考，並在您的端點發佈該模型。 這是查詢知識庫的必要步驟。

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

取得查詢運行時間金鑰

發佈知識庫之後，您需要查詢運行時間金鑰來查詢運行時間。 這與用來建立原始客戶端物件的密鑰不同。

使用 EndpointKeys 方法來取得 EndpointKeysDTO 類別。

使用物件中傳回的其中一個索引鍵屬性來查詢知識庫。

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

    return endpointKeysObject.PrimaryEndpointKey;
}

需要運行時間金鑰才能查詢知識庫。

驗證運行時間以產生答案

建立 QnAMakerRuntimeClient 以查詢 知識庫，以從主動式學習產生答案或定型。

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

使用 QnAMakerRuntimeClient 來：

• 從知識庫取得答案
• 以將新的建議問題傳送至 知識庫，以供使用中學習。

從 知識庫 產生答案

使用 RuntimeClient 從已發佈的知識庫產生答案。GenerateAnswerAsync 方法。 此方法接受 知識庫標識碼和 QueryDTO。 存取 QueryDTO 的其他屬性，例如 在聊天機器人中使用的 Top 和 Context 。

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
}

這是查詢知識庫的簡單範例。 若要瞭解進階查詢案例，請檢閱 其他查詢範例。

刪除 知識庫

使用 DeleteAsync 方法搭配 知識庫 識別子的參數刪除知識庫。

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

取得作業的狀態

某些方法，例如建立和更新，可能需要足夠的時間，而不是等待進程完成， 而是傳回作業 。 使用作業中的作業標識碼來輪詢 （重試邏輯），以判斷原始方法的狀態。

迴圈和 Task.Delay 下列程式代碼區塊會用來模擬重試邏輯。 這些應該取代為您自己的重試邏輯。

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

執行應用程式

使用來自應用程式目錄的 dotnet run 命令執行應用程式。

dotnet run

您可以在 GitHub 上找到此範例的原始程式碼。

使用 QnA Maker 用戶端連結庫進行下列Node.js：

• 建立知識庫
• 更新知識庫
• 發佈知識庫
• 取得預測運行時間端點金鑰
• 等候長時間執行的工作
• 下載知識庫
• 從知識庫取得答案
• 刪除 知識庫

參考文件 | 套件 (npm) | Node.js 範例

注意

2019 年 7 月 1 日之後建立的新資源會使用自訂的子網域名稱。 如需詳細資訊和完整的區域端點清單，請參閱 Azure AI 服務的自訂子網域名稱。

必要條件

• Azure 訂用帳戶 - 建立免費帳戶
• 目前版本的 Node.js。
• 擁有 Azure 訂用帳戶之後，請在 Azure 入口網站 中建立 QnA Maker 資源，以取得您的撰寫密鑰和資源。 在其部署後，選取 [前往資源]。
  • 您需要從您建立的資源取得密鑰和資源名稱，才能將應用程式連線到 QnA Maker API。 將金鑰和資源名稱貼到快速入門稍後的程式代碼中。
  • 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

設定

建立新的 Node.js 應用程式

在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中，為您的應用程式建立新的目錄，並瀏覽至該目錄。

mkdir qnamaker_quickstart && cd qnamaker_quickstart

執行命令 npm init -y，以使用 package.json 檔案建立節點應用程式。

npm init -y

安裝用戶端程式庫

安裝下列 NPM 套件：

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

您的應用程式檔案 package.json 會隨著相依性更新。

建立名為 index.js 的檔案，並匯入下列連結庫：

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

為資源的 Azure 金鑰和資源名稱建立變數。

• 我們會使用訂用帳戶密鑰並交換撰寫金鑰。 如需撰寫密鑰的詳細資訊，請遵循 QnA Maker 中的金鑰。

• QNA_MAKER_ENDPOINT 的值的格式 https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com為 。 移至 Azure 入口網站，並尋找您在必要條件中建立的 QnA Maker 資源。 選取 [金鑰和端點] 頁面，在 [資源管理] 下找出 [撰寫][訂用帳戶] 密鑰和 QnA Maker 端點。

• QNA_MAKER_RUNTIME_ENDPOINT 的值的格式為 https://YOUR-RESOURCE-NAME.azurewebsites.net。 移至 Azure 入口網站，並尋找您在必要條件中建立的 QnA Maker 資源。 選取 [導出範本] 頁面，在 [自動化] 底下找出 [運行時間端點]。

重要

完成時，請記得從程式碼中移除金鑰，且不要公開張貼金鑰。 在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。 如需詳細資訊，請參閱 Azure AI 服務安全性一文。

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

物件模型

QnA Maker 使用兩個不同的物件模型：

• QnAMakerClient 是用來建立、管理、發佈及下載知識庫的物件。
• QnAMakerRuntime 是使用 GenerateAnswer API 查詢 知識庫 的物件，並使用訓練 API 傳送新的建議問題（作為使用中學習的一部分）。

QnAMakerClient 物件模型

撰寫 QnA Maker 用戶端是 QnAMakerClient 物件，會使用包含密鑰的認證向 Azure 進行驗證。

建立客戶端之後，請使用知識庫來建立、管理及發佈您的 知識庫。

傳送 JSON 物件來管理您的 知識庫。 針對立即作業，方法通常會傳回指出狀態的 JSON 物件。 對於長時間執行的作業，回應是作業標識符。 使用作業標識符呼叫 client.operations.getDetails 方法，以判斷要求的狀態。

QnAMakerRuntimeClient 物件模型

預測 QnA Maker 用戶端是 QnAMakerRuntimeClient 物件，會使用 Microsoft.Rest.ServiceClientCredentials 向 Azure 進行驗證，其中包含從撰寫用戶端呼叫 用戶端用戶端傳回的預測運行時間密鑰。發佈知識庫之後的 EndpointKeys.getKeys 。

程式碼範例

這些代碼段示範如何使用適用於 .NET 的 QnA Maker 用戶端連結庫執行下列動作：

• 驗證撰寫用戶端
• 建立知識庫
• 更新 知識庫
• 下載 知識庫
• 發佈知識庫
• 刪除 知識庫
• 取得查詢運行時間金鑰
• 取得作業的狀態
• 驗證查詢運行時間用戶端
• 從 知識庫 產生答案

驗證用戶端以撰寫 知識庫

使用您的端點和金鑰具現化用戶端。 使用您的密鑰建立 ServiceClientCredentials 物件，並將其與您的端點搭配使用，以建立 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);

建立知識庫

知識庫 會從三個來源儲存 CreateKbDTO 物件的問答組：

• 針對 編輯內容，請使用 QnADTO 物件。
  • 若要使用元數據和後續提示，請使用編輯內容，因為此數據會新增至個別 QnA 配對層級。
• 針對 檔案，請使用 FileDTO 物件。 FileDTO 包含要連線到檔案的檔名和公用 URL。
• 針對 URL，請使用字串清單來代表公開可用的 URL。

建立步驟也包含知識庫的屬性：

• defaultAnswerUsedForExtraction - 找不到答案時傳回的內容
• enableHierarchicalExtraction - 自動建立所擷取 QnA 配對之間的提示關聯性
• language - 建立資源的第一個知識庫時，將語言設定為在 Azure 搜尋服務索引中使用。

使用 知識庫 資訊呼叫 create 方法。 知識庫 資訊基本上是 JSON 物件。

當 create 方法傳回時，將傳回的作業標識碼傳遞至 wait_for_operation 方法來輪詢狀態。 當作業完成時，wait_for_operation方法會傳回。 resourceLocation剖析傳回作業的標頭值，以取得新的 知識庫 標識符。

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

請務必包含wait_for_operation上述程式代碼中參考的函式，才能成功建立 知識庫。

更新 知識庫

您可以將 知識庫 標識符和 UpdateKbOperationDTO 傳入更新方法，以更新 知識庫。 DTO 基本上也是 JSON 物件。 使用 wait_for_operation 方法來判斷更新是否成功。

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
}

請確定包含wait_for_operation上述程式代碼中所參考的函式，以便成功更新 知識庫。

下載 知識庫

使用下載方法將資料庫下載為 QnADocumentsDTO 的清單。 這不等於 QnA Maker 入口網站從 設定 頁面匯出，因為此方法的結果不是 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
}

發佈知識庫

使用 publish 方法發佈 知識庫。 這會採用目前儲存和定型的模型，由 知識庫 標識元參考，並在端點發佈該模型。 檢查 HTTP 回應碼，以驗證發行是否成功。

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
}

查詢 知識庫

取得查詢運行時間金鑰

發佈知識庫之後，您需要查詢運行時間金鑰來查詢運行時間。 這與用來建立原始客戶端物件的密鑰不同。

使用 EndpointKeys.getKeys 方法來取得 EndpointKeysDTO 類別。

使用物件中傳回的其中一個索引鍵屬性來查詢知識庫。

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
}

驗證運行時間以產生答案

建立 QnAMakerRuntimeClient 以查詢 知識庫，以從主動式學習產生答案或定型。

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

使用 QnAMakerRuntimeClient 從知識中取得答案，或將新的建議問題傳送至 知識庫 以供使用中學習。

從 知識庫 產生答案

使用 RuntimeClient.runtime.generateAnswer 方法，從已發佈的 知識庫 產生答案。 此方法接受 知識庫標識碼和 QueryDTO。 存取 QueryDTO 的其他屬性，例如在聊天機器人中使用的 Top 和 Context。

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

}

這是查詢 知識庫的簡單範例。 若要瞭解進階查詢案例，請檢閱 其他查詢範例。

刪除 知識庫

使用 delete 方法搭配 知識庫 識別子的參數，刪除 知識庫。

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
}

取得作業的狀態

某些方法，例如建立和更新，可能需要足夠的時間，而不是等待進程完成， 而是傳回作業 。 使用作業中的作業標識碼來輪詢 （重試邏輯），以判斷原始方法的狀態。

下列程式 代碼區塊中的 delayTimer 呼叫是用來模擬重試邏輯。 將此值取代為您自己的重試邏輯。

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

執行應用程式

使用 node index.js 來自應用程式目錄的命令執行應用程式。

node index.js

您可以在 GitHub 上找到此範例的原始程式碼。

使用適用於 Python 的 QnA Maker 用戶端連結庫來：

• 建立知識庫
• 更新知識庫
• 發佈知識庫
• 取得預測運行時間端點金鑰
• 等候長時間執行的工作
• 下載知識庫
• 從知識庫取得答案
• 刪除 知識庫

參考文件 | 連結庫原始程式碼 | 套件 （PyPi） | Python 範例

注意

2019 年 7 月 1 日之後建立的新資源會使用自訂的子網域名稱。 如需詳細資訊和完整的區域端點清單，請參閱 Azure AI 服務的自訂子網域名稱。

必要條件

注意

本文件不適用於最新版本。 若要瞭解如何搭配最新版本使用 Python API，請參閱 回答 Python 快速入門的問題。

• Azure 訂用帳戶 - 建立免費帳戶
• Python 3.x
• 擁有 Azure 訂用帳戶之後，請在 Azure 入口網站 中建立 QnA Maker 資源，以取得您的撰寫密鑰和端點。 在其部署後，選取 [前往資源]。
  • 您需要從您建立的資源取得密鑰和端點，才能將應用程式連線到 QnA Maker API。 您稍後會在快速入門中將金鑰和端點貼到下列程式代碼中。
  • 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

設定

安裝用戶端程式庫

安裝 Python 之後，您可以使用下列項目來安裝用戶端連結庫：

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

建立新的 Python 應用程式

建立名為 quickstart-file.py 的新 Python 檔案，並匯入下列連結庫。

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

為資源的 Azure 端點和金鑰建立變數。

• 我們會使用訂用帳戶密鑰並交換撰寫金鑰。 如需撰寫密鑰的詳細資訊，請遵循 QnA Maker 中的金鑰。

• QNA_MAKER_ENDPOINT 的值的格式 https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com為 。 移至 Azure 入口網站，並尋找您在必要條件中建立的 QnA Maker 資源。 選取 [金鑰和端點] 頁面，在 [資源管理] 下找出 [撰寫][訂用帳戶] 密鑰和 QnA Maker 端點。

• QNA_MAKER_RUNTIME_ENDPOINT 的值的格式為 https://YOUR-RESOURCE-NAME.azurewebsites.net。 移至 Azure 入口網站，並尋找您在必要條件中建立的 QnA Maker 資源。 選取 [導出範本] 頁面，在 [自動化] 底下找出 [運行時間端點]。

重要

完成時，請記得從程式碼中移除金鑰，且不要公開張貼金鑰。 在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。 如需詳細資訊，請參閱 Azure AI 服務安全性一文。

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'

物件模型

QnA Maker 使用兩個不同的物件模型：

• QnAMakerClient 是用來建立、管理、發佈及下載知識庫的物件。
• QnAMakerRuntime 是使用 GenerateAnswer API 查詢 知識庫 的物件，並使用訓練 API 傳送新的建議問題（作為使用中學習的一部分）。

使用此範例 知識庫

本快速入門中的 知識庫 是從 2 對交談式 QnA 配對開始，這是為了簡化範例，並在 Update 方法中使用高度可預測的標識碼，將後續提示與問題與新配對產生關聯。 本快速入門已依特定順序規劃及實作此快速入門。

如果您打算隨著時間開發您的 知識庫，以及相依於現有 QnA 配對的後續提示，您可以選擇：

• 對於較大的知識庫，請在支援自動化的文本編輯器或 TSV 工具中管理 知識庫，然後使用更新一次完全取代 知識庫。
• 對於較小的知識庫，請在 QnA Maker 入口網站中完全管理後續提示。

本快速入門中使用的 QnA 配對詳細數據：

• QnA 配對的類型 - 更新之後，此 知識庫 中有 2 種類型的 QnA 組：chitchat 和網域特定資訊。 如果您的知識庫系結至交談應用程式，例如聊天機器人，則這是典型的。
• 雖然知識庫答案可以依元數據篩選或使用後續提示，但本快速入門不會顯示。 在這裡尋找那些與語言無關的generateAnswer範例。
• 回應文字是 Markdown，而且可以包含 各種不同的 Markdown ，例如影像（公開可用的因特網影像）、連結（公開可用的 URL），以及專案符號點，本快速入門不會使用該品種。

QnAMakerClient 物件模型

撰寫 QnA Maker 用戶端是 QnAMakerClient 物件，可使用包含密鑰的 Microsoft.Rest.ServiceClientCredentials 向 Azure 進行驗證。

建立客戶端之後，請使用知識庫屬性來建立、管理及發佈您的 知識庫。

傳送 JSON 物件來管理您的 知識庫。 針對立即作業，方法通常會傳回指出狀態的 JSON 物件。 對於長時間執行的作業，回應是作業標識符。 使用作業標識符呼叫 operations.get_details 方法，以判斷要求的狀態。

QnAMakerRuntimeClient 物件模型

預測 QnA Maker 用戶端是使用 QnAMakerRuntimeClient Microsoft.Rest.ServiceClientCredentials 向 Azure 進行驗證的物件，其中包含您從撰寫用戶端呼叫用戶端呼叫 用戶端傳回的預測運行時間密鑰。發佈知識庫之後EndpointKeysOperations.get_keys 。

generate_answer使用 方法從查詢運行時間取得答案。

驗證用戶端以撰寫 知識庫

使用您的端點和金鑰具現化用戶端。 使用您的密鑰建立 CognitiveServicesCredentials 物件，並將其與您的端點搭配使用，以建立 QnAMakerClient 物件。

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

建立知識庫

使用客戶端物件來取得 知識庫 作業物件。

知識庫 會從三個來源儲存 CreateKbDTO 物件的問答組：

• 針對 編輯內容，請使用 QnADTO 物件。
  • 若要使用元數據和後續提示，請使用編輯內容，因為此數據會新增至個別 QnA 配對層級。
• 針對 檔案，請使用 FileDTO 物件。 FileDTO 包含要連線到檔案的檔名和公用 URL。
• 針對 URL，請使用字串清單來代表公開可用的 URL。

呼叫 create 方法，然後將傳回的作業標識符傳遞至 Operations.getDetails 方法，以輪詢狀態。

下列程式代碼的最後一行會從 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

請確定包含_monitor_operation上述程式代碼中參考的函式，以便成功建立 知識庫。

更新 知識庫

您可以將包含 add、update 和 delete DTO 物件的updateKbOperationDTO 傳入 知識庫 標識符和 UpdateKbOperationDTO，以更新 知識庫。 使用 Operation.getDetail 方法來判斷更新是否成功。

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

請確定包含_monitor_operation上述程式代碼中參考的函式，以便成功更新 知識庫。

下載 知識庫

使用下載方法將資料庫下載為 QnADocumentsDTO 的清單。 這不等於 QnA Maker 入口網站從 設定 頁面匯出，因為此方法的結果不是 TSV 檔案。

def download_kb(client, kb_id):
    print("Downloading knowledge base...")
    kb_data = client.knowledgebase.download(kb_id=kb_id, environment="Prod")
    print("Downloaded knowledge base. It has {} QnAs.".format(len(kb_data.qna_documents)))

發佈知識庫

使用 publish 方法發佈 知識庫。 這會採用目前儲存和定型的模型，由 知識庫 標識元參考，並在端點發佈該模型。

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

查詢 知識庫

取得查詢運行時間金鑰

發佈知識庫之後，您需要查詢運行時間金鑰來查詢運行時間。 這與用來建立原始客戶端物件的密鑰不同。

使用 EndpointKeysOperations.get_keys 方法來取得 EndpointKeysDTO 類別。

使用物件中傳回的其中一個索引鍵屬性來查詢知識庫。

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

驗證運行時間以產生答案

建立 QnAMakerRuntimeClient 以查詢 知識庫，以從主動式學習產生答案或定型。

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

使用 QnAMakerRuntimeClient 從知識中取得答案，或將新的建議問題傳送至 知識庫 以供主動學習。

從 知識庫 產生答案

使用 QnAMakerRuntimeClient.runtime.generate_answer 方法，從已發佈的 知識庫 產生答案。 此方法接受 知識庫標識碼和 QueryDTO。 存取 QueryDTO 的其他屬性，例如在聊天機器人中使用的 Top 和 Context。

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

這是查詢 知識庫的簡單範例。 若要瞭解進階查詢案例，請檢閱 其他查詢範例。

刪除 知識庫

使用 delete 方法搭配 知識庫 識別子的參數，刪除 知識庫。

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

取得作業的狀態

某些方法，例如建立和更新，可能需要足夠的時間，而不是等待進程完成， 而是傳回作業 。 使用作業中的作業標識碼來輪詢 （重試邏輯），以判斷原始方法的狀態。

下列程式 代碼區塊中的 setTimeout 呼叫是用來模擬異步程序代碼。 將此值取代為重試邏輯。

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

執行應用程式

在快速入門檔案上使用 Python 命令執行應用程式。

python quickstart-file.py

您可以在 GitHub 上找到此範例的原始程式碼。

使用適用於 Java 的 QnA Maker 用戶端連結庫來：

• 建立知識庫
• 更新知識庫
• 發佈知識庫
• 取得預測運行時間端點金鑰
• 等候長時間執行的工作
• 下載知識庫
• 從知識庫取得答案
• 刪除 知識庫

連結庫原始程式碼 | 套件 | 範例

注意

2019 年 7 月 1 日之後建立的新資源會使用自訂的子網域名稱。 如需詳細資訊和完整的區域端點清單，請參閱 Azure AI 服務的自訂子網域名稱。

必要條件

• Azure 訂用帳戶 - 建立免費帳戶
• Jdk
• 擁有 Azure 訂用帳戶之後，請在 Azure 入口網站 中建立 QnA Maker 資源，以取得您的撰寫密鑰和端點。 在其部署後，選取 [前往資源]。
  • 您需要從您建立的資源取得密鑰和端點，才能將應用程式連線到 QnA Maker API。 將金鑰和端點貼到快速入門稍後的程式代碼中。
  • 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

設定

安裝用戶端程式庫

安裝 Java 之後，您可以使用 MVN 存放庫中的 Maven 來安裝用戶端連結庫。

建立新的 Java 應用程式

建立名為 quickstart.java 的新檔案，並匯入下列連結庫。

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

為資源的 Azure 端點和金鑰建立變數。

• 我們會使用訂用帳戶密鑰並交換撰寫金鑰。 如需撰寫密鑰的詳細資訊，請遵循 QnA Maker 中的金鑰。

• QNA_MAKER_ENDPOINT 的值的格式 https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com為 。 移至 Azure 入口網站，並尋找您在必要條件中建立的 QnA Maker 資源。 選取 [金鑰和端點] 頁面，在 [資源管理] 下找出 [撰寫][訂用帳戶] 密鑰和 QnA Maker 端點。

• QNA_MAKER_RUNTIME_ENDPOINT 的值的格式為 https://YOUR-RESOURCE-NAME.azurewebsites.net。 移至 Azure 入口網站，並尋找您在必要條件中建立的 QnA Maker 資源。 選取 [導出範本] 頁面，在 [自動化] 底下找出 [運行時間端點]。

重要

完成時，請記得從程式碼中移除金鑰，且不要公開張貼金鑰。 在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。 如需詳細資訊，請參閱 Azure AI 服務安全性一文。

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

物件模型

QnA Maker 使用兩個不同的物件模型：

• QnAMakerClient 是用來建立、管理、發佈及下載知識庫的物件。
• QnAMakerRuntime 是使用 GenerateAnswer API 查詢 知識庫 的物件，並使用訓練 API 傳送新的建議問題（作為使用中學習的一部分）。

使用此範例 知識庫

本快速入門中的 知識庫 從 2 對交談式 QnA 配對開始，這是為了簡化範例，並在 Update 方法中使用高度可預測的標識碼，將後續提示與新配對的問題產生關聯。 本快速入門已依特定順序規劃及實作此快速入門。

如果您打算隨著時間開發您的 知識庫，以及相依於現有 QnA 配對的後續提示，您可以選擇：

• 對於較大的知識庫，請在支援自動化的文本編輯器或 TSV 工具中管理 知識庫，然後使用更新一次完全取代 知識庫。
• 對於較小的知識庫，請在 QnA Maker 入口網站中完全管理後續提示。

本快速入門中使用的 QnA 配對詳細數據：

• QnA 配對的類型 - 更新之後，此 知識庫 中有 2 種類型的 QnA 組：chitchat 和網域特定資訊。 如果您的知識庫系結至交談應用程式，例如聊天機器人，則這是典型的。
• 雖然知識庫答案可以依元數據篩選或使用後續提示，但本快速入門不會顯示。 在這裡尋找那些與語言無關的generateAnswer範例。
• 回應文字是 Markdown，而且可以包含 各種不同的 Markdown ，例如影像（公開可用的因特網影像）、連結（公開可用的 URL），以及專案符號點，本快速入門不會使用該品種。

QnAMakerClient 物件模型

撰寫 QnA Maker 用戶端是 QnAMakerClient 物件，可使用 MsRest：：ServiceClientCredentials 向 Azure 進行驗證，其中包含您的密鑰。

建立客戶端之後，請使用用戶端 Knowledgebases 屬性的方法來建立、管理及發佈您的 知識庫。

如果是立即作業，方法通常會傳回結果，如果有的話。 對於長時間執行的作業，回應是 Operation 物件。 使用 operation.operationId 值呼叫 getDetails 方法，以判斷要求的狀態。

QnAMakerRuntimeClient 物件模型

運行時間 QnA Maker 用戶端是 QnAMakerRuntimeClient 物件。

使用撰寫用戶端發佈 知識庫 之後，請使用運行時間用戶端的 generateAnswer 方法來從 知識庫 取得答案。

您可以呼叫 QnAMakerRuntimeManager.authenticate 並傳遞運行時間端點密鑰，以建立運行時間用戶端。 若要取得運行時間端點密鑰，請使用撰寫用戶端來呼叫 getKeys。

驗證用戶端以撰寫 知識庫

使用您的撰寫端點和訂用帳戶密鑰具現化用戶端。

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

建立知識庫

知識庫 會儲存三個來源中 CreateKbDTO 物件的問答組：

• 針對 編輯內容，請使用 QnADTO 物件。
  • 若要使用元數據和後續提示，請使用編輯內容，因為此數據會新增至個別 QnA 配對層級。
• 針對 檔案，請使用 FileDTO 物件。 FileDTO 包含要連線到檔案的檔名和公用 URL。
• 針對 URL，請使用字串清單來代表公開可用的 URL。

呼叫 create 方法，然後將傳回作業的 屬性傳遞operationId至 getDetails 方法，以輪詢狀態。

下列程式代碼的最後一行會傳回 知識庫 標識符。

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

更新 知識庫

您可以藉由呼叫 update 並傳入 知識庫 標識碼和 UpdateKbOperationDTO 物件來更新 知識庫。 該物件接著可以包含：

• add
• update
• delete

將 operationId 傳回作業的 屬性傳遞至 getDetails 方法，以輪詢狀態。

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

下載 知識庫

使用下載方法將資料庫下載為 QnADocumentsDTO 的清單。 這不等於 QnA Maker 入口網站從 設定 頁面匯出，因為此方法的結果不是 TSV 檔案。

public void download_kb(String kb_id) {
    System.out.println("Downloading KB...");

    var kb_data = kb_client.download(kb_id, EnvironmentType.PROD);
    System.out.println("KB Downloaded. It has " + kb_data.qnaDocuments().size() + " question/answer sets.");

    System.out.println("Downloaded KB.\n");
}

發佈知識庫

使用 publish 方法發佈 知識庫。 這會採用目前儲存和定型的模型，由 知識庫 標識元參考，並在端點發佈該模型。

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

從 知識庫 產生答案

發佈 知識庫 之後，您需要運行時間端點金鑰來查詢 知識庫。 這與用來建立撰寫用戶端的訂用帳戶密鑰不同。

使用 getKeys 方法來取得 EndpointKeysDTO 物件。

呼叫 QnAMakerRuntimeManager.authenticate ，並從 EndpointKeysDTO 對象傳遞運行時間端點密鑰，以建立運行時間用戶端。

使用 generateAnswer 方法，從已發佈 知識庫 產生答案。 此方法接受 知識庫標識碼和 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();
}

這是查詢 知識庫的簡單範例。 若要瞭解進階查詢案例，請檢閱 其他查詢範例。

刪除 知識庫

使用 delete 方法搭配 知識庫 識別子的參數，刪除 知識庫。

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

取得作業的狀態

某些方法，例如建立和更新，可能需要足夠的時間，而不是等待進程完成， 而是傳回作業 。 使用作業中的作業標識碼來輪詢 （重試邏輯），以判斷原始方法的狀態。

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

執行應用程式

以下是應用程式的主要方法。

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

執行應用程式，如下所示。 這會假設您的類別名稱是 Quickstart ，而且您的相依性位於目前資料夾下方名為 lib 的子資料夾中。

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

您可以在 GitHub 上找到此範例的原始程式碼。

清除資源

如果您想要清除和移除 Azure AI 服務訂用帳戶，則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

• 入口網站
• Azure CLI

下一步

教學課程：使用批處理文件測試您的 知識庫

• 什麼是 QnA Maker API？
• 編輯 知識庫
• 取得使用量分析