Mulai Cepat: Pustaka klien QnA Maker

Catatan

Azure Open AI On Your Data menggunakan model bahasa besar (LLM) untuk menghasilkan hasil yang serupa dengan QnA Maker. Jika Anda ingin memigrasikan proyek QnA Maker Anda ke Azure Open AI On Your Data, silakan lihat panduan kami.

Mulai menggunakan pustaka klien QnA Maker. Ikuti langkah-langkah berikut untuk memasang paket dan mencoba contoh kode untuk tugas-tugas dasar.

Catatan

Layanan QnA Maker akan dihentikan pada 31 Maret 2025. Versi kemampuan pertanyaan dan jawaban yang lebih baru sekarang tersedia sebagai bagian dari Bahasa Azure AI. Untuk kemampuan menjawab pertanyaan dalam Language Service, lihat jawaban pertanyaan. Mulai 1 Oktober 2022, Anda tidak dapat membuat sumber daya QnA Maker baru. Untuk informasi tentang memigrasikan pangkalan pengetahuan QnA Maker yang ada ke jawaban atas pertanyaan, lihat panduan migrasi.

Prasyarat

Catatan

Dokumentasi ini tidak berlaku untuk rilis terbaru. Untuk mempelajari tentang menggunakan REST API dengan rilis terbaru, lihat mulai cepat jawaban atas pertanyaan REST API

• Versi cURL saat ini. Beberapa sakelar baris perintah digunakan dalam mulai cepat, yang tercatat dalam dokumentasi cURL.

• Anda harus memiliki sumber daya QnA Maker, untuk menggunakan nama kunci dan sumber daya. Anda memasukkan Nama sumber daya selama pembuatan sumber daya, lalu kunci dibuat untuk Anda. Nama sumber daya digunakan sebagai subdomain untuk titik akhir Anda. Untuk mengambil nama kunci dan sumber daya Anda, pilih Mulai cepat untuk sumber daya Anda di portal Microsoft Azure. Nama sumber daya adalah subdomain pertama dari URL titik akhir:

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

Perhatian

Contoh BASH berikut menggunakan \ karakter kelanjutan baris. Jika konsol atau terminal Anda menggunakan karakter kelanjutan baris yang berbeda, gunakan karakter tersebut.

Membuat basis pengetahuan

Untuk membuat pangkalan pengetahuan dengan REST API dan cURL, Anda harus memiliki informasi berikut:

Informasi	Konfigurasi cURL	Tujuan
nama sumber daya QnA Maker	URL	digunakan untuk membangun URL
kunci sumber daya QnA Maker	param -h untuk header Ocp-Apim-Subscription-Key	Autentikasi ke layanan QnA Maker
JSON menggambarkan pangkalan pengetahuan	param -d	Contoh JSON
Ukuran JSON dalam byte	param -h untuk header Content-Size

Perintah cURL dijalankan dari shell BASH. Edit perintah ini dengan nama sumber daya, kunci sumber daya, dan nilai JSON dan ukuran JSON Anda sendiri.

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

Respons cURL dari QnA Maker mencakup operationId, yang diperlukan untuk mendapatkan status operasi.

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

Mendapatkan status operasi

Ketika Anda membuat pangkalan pengetahuan, karena operasinya asinkron, respons menyertakan informasi untuk menentukan status.

Informasi	Konfigurasi cURL	Tujuan
nama sumber daya QnA Maker	URL	digunakan untuk membangun URL
ID operasi	rute URL	/operations/REPLACE-WITH-YOUR-OPERATION-ID
kunci sumber daya QnA Maker	param -h untuk header Ocp-Apim-Subscription-Key	Autentikasi ke layanan QnA Maker

Perintah cURL dijalankan dari shell BASH. Edit perintah ini dengan nama sumber daya, kunci sumber daya, dan ID operasi Anda sendiri.

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"

Respons cURL mencakup status. Jika status operasi berhasil, maka resourceLocation termasuk ID pangkalan pengetahuan.

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

Terbitkan pangkalan pengetahuan

Sebelum Anda menanyakan pangkalan pengetahuan, Anda perlu:

• Terbitkan pangkalan pengetahuan
• Dapatkan tombol titik akhir runtime

Tugas ini menerbitkan pangkalan pengetahuan. Mendapatkan kunci titik akhir runtime adalah tugas terpisah.

Informasi	Konfigurasi cURL	Tujuan
nama sumber daya QnA Maker	URL	digunakan untuk membangun URL
kunci sumber daya QnA Maker	param -h untuk header Ocp-Apim-Subscription-Key	Autentikasi ke layanan QnA Maker
ID pangkalan pengetahuan	rute URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

Perintah cURL dijalankan dari shell BASH. Edit perintah ini dengan nama sumber daya, kunci sumber daya, dan ID pangkalan pengetahuan Anda sendiri.

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

Status respons adalah 204 tanpa hasil. Gunakan parameter baris perintah -v untuk melihat output verbose untuk perintah cURL. Ini akan mencakup status HTTP.

Dapatkan kunci titik akhir runtime pangkalan pengetahuan yang diterbitkan

Sebelum Anda menanyakan pangkalan pengetahuan, Anda perlu:

• Terbitkan pangkalan pengetahuan
• Dapatkan tombol titik akhir runtime

Tugas ini mendapatkan kunci titik akhir runtime. Menerbitkan pangkalan pengetahuan adalah tugas terpisah.

Kunci titik akhir runtime adalah kunci yang sama untuk semua pangkalan pengetahuan menggunakan sumber daya QnA Maker.

Informasi	Konfigurasi cURL	Tujuan
nama sumber daya QnA Maker	URL	digunakan untuk membangun URL
kunci sumber daya QnA Maker	param -h untuk header Ocp-Apim-Subscription-Key	Autentikasi ke layanan QnA Maker

Perintah cURL dijalankan dari shell BASH. Edit perintah ini dengan nama sumber daya, kunci sumber daya Anda sendiri.

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"

Respons cURL mencakup tombol titik akhir runtime. Gunakan hanya salah satu kunci saat meminta untuk mendapatkan jawaban dari pangkalan pengetahuan.

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

Kueri untuk jawaban dari pangkalan pengetahuan yang diterbitkan

Mendapatkan jawaban dari pengetahuan dilakukan dari runtime terpisah daripada mengelola pangkalan pengetahuan. Karena ini adalah runtime terpisah, Anda perlu mengautentikasi dengan tombol runtime.

Informasi	Konfigurasi cURL	Tujuan
nama sumber daya QnA Maker	URL	digunakan untuk membangun URL
Kunci runtime QnA Maker	param -h untuk header Authorization	Kuncinya adalah bagian dari string yang menyertakan kata Endpointkey . Autentikasi ke layanan QnA Maker
ID pangkalan pengetahuan	rute URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
JSON menjelaskan kueri	param -d	Meminta parameter tubuh dan contoh JSON
Ukuran JSON dalam byte	param -h untuk header Content-Size

Perintah cURL dijalankan dari shell BASH. Edit perintah ini dengan nama sumber daya, kunci sumber daya, dan ID pangkalan pengetahuan Anda sendiri.

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

Respons yang berhasil mencakup jawaban teratas bersama dengan informasi lain aplikasi klien, seperti bot obrolan, perlu menampilkan jawaban kepada pengguna.

Hapus pangkalan pengetahuan

Ketika Anda selesai dengan pangkalan pengetahuan, hapus.

Informasi	Konfigurasi cURL	Tujuan
nama sumber daya QnA Maker	URL	digunakan untuk membangun URL
kunci sumber daya QnA Maker	param -h untuk header Ocp-Apim-Subscription-Key	Autentikasi ke layanan QnA Maker
ID pangkalan pengetahuan	rute URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

Perintah cURL dijalankan dari shell BASH. Edit perintah ini dengan nama sumber daya, kunci sumber daya, dan ID pangkalan pengetahuan Anda sendiri.

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"

Status respons adalah 204 tanpa hasil. Gunakan parameter baris perintah -v untuk melihat output verbose untuk perintah cURL. Ini akan mencakup status HTTP.

Sumber Daya Tambahan:

• Penulisan Dokumentasi referensi
• Runtime Dokumentasi referensi
• Sampel skrip BASH menggunakan cURL

Gunakan pustaka klien QnA Maker untuk .NET untuk:

• Membuat pangkalan pengetahuan
• Memperbarui pangkalan pengetahuan
• Menerbitkan pangkalan pengetahuan
• Mendapatkan kunci titik akhir runtime prediksi
• Menunggu tugas yang sudah berjalan lama
• Mengunduh pangkalan pengetahuan
• Mendapatkan jawaban dari pangkalan pengetahuan
• Menghapus pangkalan pengetahuan

Dokumentasi referensi | Kode sumber pustaka | Paket (NuGet) | Sampel C#

Catatan

Sumber daya baru yang dibuat setelah 1 Juli 2019, akan menggunakan nama subdomain kustom. Untuk informasi selengkapnya dan daftar lengkap titik akhir regional, lihat Nama subdomain kustom untuk layanan Azure AI.

Prasyarat

Catatan

Dokumentasi ini tidak berlaku untuk rilis terbaru. Untuk mempelajari tentang menggunakan C# API dengan rilis terbaru, lihat mulai cepat jawaban atas pertanyaan C#

• Langganan Azure - Buat langganan secara gratis
• IDE Visual Studio atau versi .NET Core saat ini.
• Setelah Anda memiliki langganan Azure Anda, buat sumber daya QnA Maker di portal Microsoft Azure untuk mendapatkan nama sumber daya dan kunci penulisan. Setelah menyebar, pilih Buka sumber daya.
  • Anda akan memerlukan nama sumber daya dan kunci dari sumber daya yang Anda buat untuk menyambungkan aplikasi ke QnA Maker API. Tempelkan kunci dan nama sumber daya pada kode di bawah ini di mulai cepat.
  • Anda dapat menggunakan tingkat harga gratis (F0) untuk percobaan, lalu meningkatkannya ke tingkat berbayar untuk produksi.

Menyiapkan

CLI

Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan perintah dotnet new untuk membuat aplikasi konsol baru dengan nama qna-maker-quickstart. Perintah ini membuat proyek C# "Halo Dunia" sederhana dengan satu file sumber: program.cs.

dotnet new console -n qna-maker-quickstart

Ubah direktori Anda ke folder aplikasi yang baru dibuat. Anda dapat membangun aplikasi dengan:

dotnet build

Output build tidak boleh berisi peringatan atau kesalahan.

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

Dalam direktori aplikasi, instal pustaka klien QnA Maker untuk .NET dengan perintah berikut:

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

Tip

Ingin menampilkan seluruh file kode mulai cepat sekaligus? Anda dapat menemukannya di GitHub, yang berisi contoh kode dalam mulai cepat ini.

Menggunakan direktif

Dari direktori proyek, buka file program.cs dan tambahkan instruksi using berikut:

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

Titik akhir sumber daya dan kunci langganan

Dalam metode Main aplikasi, tambahkan variabel dan kode, yang ditampilkan di bagian berikut, untuk menggunakan tugas umum dalam mulai cepat ini.

• Kami menggunakan kunci langganan dan kunci penulisan secara bergantian. Untuk detail selengkapnya tentang kunci penulisan, ikuti Kunci di QnA Maker.

• Nilai QNA_MAKER_ENDPOINT memiliki format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Buka portal Microsoft Azure, lalu temukan sumber daya QnA Maker yang Anda buat di prasyarat. Klik halaman Kunci dan Titik Akhir pada bagian manajemen sumber daya untuk menemukan kunci Penulisan (Langganan) dan Titik Akhir QnA Maker.

• Nilai QNA_MAKER_RUNTIME_ENDPOINT memiliki format https://YOUR-RESOURCE-NAME.azurewebsites.net. Buka portal Microsoft Azure, lalu temukan sumber daya QnA Maker yang Anda buat di prasyarat. Klik halaman Ekspor Template di bagian Otomatisasi untuk menemukan Titik Akhir Runtime.

Penting

Jangan lupa menghapus kunci dari kode setelah Anda selesai, dan jangan pernah mempostingnya secara publik. Untuk produksi, gunakan cara yang aman untuk menyimpan dan mengakses kredensial Anda seperti Azure Key Vault. Lihat artikel keamanan layanan Azure AI untuk informasi selengkapnya.

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

Model objek

QnA Maker menggunakan dua model objek yang berbeda:

• QnAMakerClient adalah objek untuk membuat, mengelola, menerbitkan, dan mengunduh pangkalan pengetahuan.
• QnAMakerRuntime adalah objek untuk meminta pangkalan pengetahuan dengan API GenerateAnswer dan mengirim saran pertanyaan baru menggunakan API Train (sebagai bagian dari pembelajaran aktif).

Menggunakan basis pengetahuan contoh ini

Basis pengetahuan dalam mulai cepat ini dimulai dengan 2 pasangan tanya jawab percakapan, ini dilakukan dengan sengaja untuk menyederhanakan contoh dan memiliki Id yang sangat dapat diprediksi untuk digunakan dalam metode Pembaruan, mengaitkan permintaan tindak lanjut dengan pertanyaan kepada pasangan baru. Ini direncanakan dan diimplementasikan dalam urutan tertentu untuk mulai cepat ini.

Jika Anda berencana untuk mengembangkan basis pengetahuan Anda dari waktu ke waktu dengan perintah tindak lanjut yang bergantung pada pasangan tanya jawab yang ada, Anda dapat memilih:

• Untuk basis pengetahuan yang lebih besar, kelola basis pengetahuan di editor teks atau alat TSV yang mendukung otomatisasi, lalu ganti sepenuhnya basis pengetahuan sekaligus dengan pembaruan.
• Untuk basis pengetahuan yang lebih kecil, kelola perintah tindak lanjut sepenuhnya di portal QnA Maker.

Detail tentang pasangan tanya jawab yang digunakan dalam mulai cepat ini:

• Jenis pasangan tanya jawab - ada 2 jenis pasangan tanya jawab di basis pengetahuan ini, setelah pembaruan: chitchat dan informasi khusus domain. Ini khas jika basis pengetahuan Anda terikat dengan aplikasi percakapan seperti chatbot.
• Meskipun jawaban basis pengetahuan dapat difilter oleh metadata atau menggunakan perintah tindak lanjut, mulai cepat ini tidak menunjukkannya. Carilah contoh-contoh bahasa-agnostik generateAnswer di sini.
• Teks jawaban adalah markdown dan dapat berisi berbagai markdown seperti gambar (gambar berbasis internet yang tersedia untuk umum), tautan (ke URL yang tersedia untuk umum), dan titik poin, mulai cepat ini tidak menggunakan variasi itu.

Model objek QnAMakerClient

Klien QnA Maker penulisan adalah objek QnAMakerClient yang mengautentikasi ke Azure menggunakan Microsoft.Rest.ServiceClientCredentials, yang berisi kunci Anda.

Setelah klien dibuat, gunakan properti Pangkalan pengetahuan untuk membuat, mengelola, dan menerbitkan pangkalan pengetahuan Anda.

Kelola pangkalan pengetahuan Anda dengan mengirim objek JSON. Untuk operasi segera, metode biasanya menampilkan objek JSON yang menunjukkan status. Untuk operasi jangka panjang, responsnya adalah ID operasi. Panggil metode client.Operations.GetDetailsAsync dengan ID operasi untuk menentukan status permintaan.

Model objek QnAMakerRuntimeClient

Klien QnA Maker prediksi adalah objek QnAMakerRuntimeClient yang mengautentikasi ke Azure menggunakan Microsoft.Rest.ServiceClientCredentials, yang berisi kunci runtime prediksi Anda, yang dikembalikan dari panggilan klien penulisan, client.EndpointKeys.GetKeys setelah pangkalan pengetahuan diterbitkan.

Gunakan metode GenerateAnswer untuk mendapatkan jawaban dari runtime kueri.

Contoh kode

Cuplikan kode berikut menunjukkan kepada Anda cara melakukan hal berikut dengan pustaka klien QnA Maker untuk .NET:

• Mengautentikasi klien penulisan
• Membuat pangkalan pengetahuan
• Memperbarui pangkalan pengetahuan
• Mengunduh pangkalan pengetahuan
• Menerbitkan basis pengetahuan
• Menghapus pangkalan pengetahuan
• Mendapatkan kunci runtime kueri
• Mendapatkan status operasi
• Mengautentikasi klien runtime kueri
• Menghasilkan jawaban dari pangkalan pengetahuan

Mengautentikasi klien untuk menulis basis pengetahuan

Buat objek klien dengan kunci Anda, dan gunakan dengan sumber daya Anda untuk membangun titik akhir guna membuat QnAMakerClient dengan titik akhir dan kunci Anda. Buat objek ServiceClientCredentials.

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

Membuat basis pengetahuan

Pangkalan pengetahuan menyimpan pasangan pertanyaan dan jawaban untuk objek CreateKbDTO dari tiga sumber:

• Untuk konten editorial, gunakan objek QnADTO.
  • Untuk menggunakan metadata dan petunjuk tindak lanjut, gunakan konteks editorial, karena data ini ditambahkan pada tingkat pasangan QnA individual.
• Untuk file, gunakan objek FileDTO. FileDTO menyertakan nama file dan URL publik untuk mencapai file.
• Untuk URL, gunakan daftar string untuk mewakili URL yang tersedia untuk umum.

Langkah pembuatan juga mencakup properti untuk pangkalan pengetahuan:

• defaultAnswerUsedForExtraction - apa yang ditampilkan ketika tidak ada jawaban yang ditemukan
• enableHierarchicalExtraction - secara otomatis membuat hubungan permintaan antara pasangan QnA yang diekstrak
• language - ketika membuat pangkalan pengetahuan pertama untuk sumber daya, atur bahasa yang akan digunakan dalam indeks Azure Search.

Panggil metode CreateAsync kemudian berikan ID operasi yang dikembalikan ke metode MonitorOperation ke polling untuk status.

Baris akhir dari kode berikut menampilkan ID pangkalan pengetahuan dari respons 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);
}

Pastikan untuk menyertakan fungsi MonitorOperation, yang direferensikan dalam kode di atas, agar berhasil membuat pangkalan pengetahuan.

Memperbarui pangkalan pengetahuan

Anda dapat memperbarui pangkalan pengetahuan dengan meneruskan ID pangkalan pengetahuan dan UpdatekbOperationDTO yang berisi menambahkan, memperbarui, dan menghapus objek DTO ke metode UpdateAsync. Gunakan metode MonitorOperation untuk menentukan apakah pembaruan berhasil.

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

Pastikan untuk menyertakan fungsi MonitorOperation, yang direferensikan dalam kode di atas, agar berhasil memperbarui basis pengetahuan.

Mengunduh basis pengetahuan

Gunakan metode DownloadAsync untuk mengunduh database sebagai daftar QnADocumentsDTO. Metode ini tidak sama dengan ekspor melalui portal QnA Maker dari halaman Pengaturan karena metode ini tidak menghasilkan file.

private static async Task DownloadKb(IQnAMakerClient client, string kbId)
{
    var kbData = await client.Knowledgebase.DownloadAsync(kbId, EnvironmentType.Prod);
    Console.WriteLine("KB Downloaded. It has {0} QnAs.", kbData.QnaDocuments.Count);

    // Do something meaningful with data
}

Terbitkan pangkalan pengetahuan

Terbitkan pangkalan pengetahuan menggunakan metode PublishAsync. Tindakan ini mengambil model saat ini yang disimpan dan dilatih, yang direferensikan oleh ID pangkalan pengetahuan, dan menerbitkannya di titik akhir Anda. Ini adalah langkah yang diperlukan untuk mengkueri pangkalan pengetahuan Anda.

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

Mendapatkan kunci runtime kueri

Setelah pangkalan pengetahuan diterbitkan, Anda memerlukan kunci runtime kueri untuk mengkueri runtime. Ini tidak sama dengan kunci yang digunakan untuk membuat objek klien asli.

Gunakan metode EndpointKeys untuk mendapatkan kelas EndpointKeysDTO.

Gunakan salah satu properti kunci yang dikembalikan dalam objek untuk meminta pangkalan pengetahuan.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

Kunci runtime diperlukan untuk mengkueri pangkalan pengetahuan Anda.

Mengautentikasi runtime untuk menghasilkan jawaban

Buat QnAMakerRuntimeClient mengkueri pangkalan pengetahuan untuk menghasilkan jawaban atau melatih dari pembelajaran aktif.

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

Gunakan QnAMakerRuntimeClient untuk:

• mendapatkan jawaban dari pangkalan pengetahuan
• mengirimkan pertanyaan baru yang disarankan ke pangkalan pengetahuan untuk pembelajaran aktif.

Menghasilkan jawaban dari pangkalan pengetahuan

Ambil jawaban dari pangkalan pengetahuan yang dipublikasikan menggunakan metode RuntimeClient.GenerateAnswerAsync. Metode ini menerima ID Pangkalan Pengetahuan dan QueryDTO. Akses properti tambahan dari QueryDTO, seperti Atas dan Konteks untuk digunakan dalam bot obrolan Anda.

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
}

Ini adalah contoh sederhana dalam mengkueri pangkalan pengetahuan. Untuk memahami skenario kueri tingkat lanjut, tinjau contoh kueri lainnya.

Menghapus pangkalan pengetahuan

Hapus pangkalan pengetahuan menggunakan metode DeleteAsync dengan parameter ID pangkalan pengetahuan.

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

Mendapatkan status operasi

Beberapa metode, seperti buat dan perbarui, memerlukan waktu yang lama sehingga daripada menunggu proses selesai, operasi dikembalikan. Gunakan ID operasi dari operasi ke polling (dengan logika coba lagi) untuk menentukan status metode asli.

Loop dan Task.Delay di blok kode berikut digunakan untuk mensimulasikan logika mencoba kembali. Ini harus diganti dengan logika coba lagi Anda sendiri.

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

Jalankan aplikasi

Menjalankan aplikasi dengan perintah dotnet run dari direktori aplikasi Anda.

dotnet run

Kode sumber untuk sampel ini dapat ditemukan di GitHub.

Gunakan pustaka klien QnA Maker untuk Node.js untuk:

• Membuat pangkalan pengetahuan
• Memperbarui pangkalan pengetahuan
• Menerbitkan pangkalan pengetahuan
• Mendapatkan kunci titik akhir runtime prediksi
• Menunggu tugas yang sudah berjalan lama
• Mengunduh pangkalan pengetahuan
• Mendapatkan jawaban dari pangkalan pengetahuan
• Hapus pangkalan pengetahuan

Paket dokumentasi | referensi (npm) | sampel Node.js

Catatan

Sumber daya baru yang dibuat setelah 1 Juli 2019, akan menggunakan nama subdomain kustom. Untuk informasi selengkapnya dan daftar lengkap titik akhir regional, lihat Nama subdomain kustom untuk layanan Azure AI.

Prasyarat

• Langganan Azure - Buat langganan secara gratis
• Versi terbaru Node.js.
• Setelah Anda memiliki langganan Azure, buat sumber daya QnA Maker di portal Microsoft Azure untuk mendapatkan kunci dan sumber daya penulisan Anda. Setelah menyebar, pilih Buka sumber daya.
  • Anda akan memerlukan nama sumber daya dan kunci dari sumber daya yang Anda buat untuk menyambungkan aplikasi ke QnA Maker API. Tempelkan kunci dan nama sumber daya pada kode di bawah ini di mulai cepat.
  • Anda dapat menggunakan tingkat harga gratis (F0) untuk percobaan, lalu meningkatkannya ke tingkat berbayar untuk produksi.

Menyiapkan

Membuat aplikasi Node.js baru

Di jendela konsol (seperti cmd, PowerShell, atau Bash), buat direktori baru untuk aplikasi Anda, dan buka direktori tersebut.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Jalankan perintah npm init -y untuk membuat aplikasi node dengan file package.json.

npm init -y

Memasang pustaka klien

Instal paket NPM berikut:

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

File aplikasi package.json Anda diperbarui dengan dependensi.

Buat file bernama index.js dan impor pustaka berikut ini:

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

Buat variabel untuk nama kunci dan sumber daya Azure sumber daya Anda.

• Kami menggunakan kunci langganan dan kunci penulisan secara bergantian. Untuk detail selengkapnya tentang kunci penulisan, ikuti Kunci di QnA Maker.

• Nilai QNA_MAKER_ENDPOINT memiliki format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Buka portal Microsoft Azure, lalu temukan sumber daya QnA Maker yang Anda buat di prasyarat. Klik halaman Kunci dan Titik Akhir pada bagian manajemen sumber daya untuk menemukan kunci Penulisan (Langganan) dan Titik Akhir QnA Maker.

• Nilai QNA_MAKER_RUNTIME_ENDPOINT memiliki format https://YOUR-RESOURCE-NAME.azurewebsites.net. Buka portal Microsoft Azure, lalu temukan sumber daya QnA Maker yang Anda buat di prasyarat. Klik halaman Ekspor Template di bagian Otomatisasi untuk menemukan Titik Akhir Runtime.

Penting

Jangan lupa menghapus kunci dari kode setelah Anda selesai, dan jangan pernah mempostingnya secara publik. Untuk produksi, gunakan cara yang aman untuk menyimpan dan mengakses kredensial Anda seperti Azure Key Vault. Lihat artikel keamanan layanan Azure AI untuk informasi selengkapnya.

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

Model objek

QnA Maker menggunakan dua model objek yang berbeda:

• QnAMakerClient adalah objek untuk membuat, mengelola, menerbitkan, dan mengunduh pangkalan pengetahuan.
• QnAMakerRuntime adalah objek untuk meminta pangkalan pengetahuan dengan API GenerateAnswer dan mengirim saran pertanyaan baru menggunakan API Train (sebagai bagian dari pembelajaran aktif).

Model objek QnAMakerClient

Klien penulisan QnA Maker adalah objek QnAMakerClient yang mengautentikasi ke Microsoft Azure menggunakan kredensial Anda, yang berisi kunci Anda.

Setelah klien dibuat, gunakan pangkalan pengetahuan untuk membuat, mengelola, dan menerbitkan pangkalan pengetahuan Anda.

Kelola pangkalan pengetahuan Anda dengan mengirim objek JSON. Untuk operasi segera, metode biasanya menampilkan objek JSON yang menunjukkan status. Untuk operasi jangka panjang, responsnya adalah ID operasi. Hubungi metode client.operations.getDetails dengan ID operasi untuk menentukan status permintaan.

Model objek QnAMakerRuntimeClient

Prediksi klien QnA Maker adalah objek QnAMakerRuntimeClient yang mengautentikasi ke Azure menggunakan Microsoft.Rest.ServiceClientCredentials, yang berisi kunci runtime prediksi Anda, dikembalikan dari panggilan klien penulisan, clien.EndpointKeys.getKeys setelah pangkalan pengetahuan diterbitkan.

Contoh kode

Cuplikan kode berikut menunjukkan kepada Anda cara melakukan hal berikut dengan pustaka klien QnA Maker untuk .NET:

• Mengautentikasi klien penulisan
• Membuat pangkalan pengetahuan
• Memperbarui pangkalan pengetahuan
• Mengunduh pangkalan pengetahuan
• Menerbitkan basis pengetahuan
• Menghapus pangkalan pengetahuan
• Mendapatkan kunci runtime kueri
• Mendapatkan status operasi
• Mengautentikasi klien runtime kueri
• Menghasilkan jawaban dari pangkalan pengetahuan

Mengautentikasi klien untuk menulis basis pengetahuan

Membuat instans klien dengan titik akhir dan kunci Anda. Membuat objek ServiceClientCredentials dengan kunci Anda, dan gunakan objek tersebut menggunakan titik akhir Anda untuk membuat objek 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);

Membuat basis pengetahuan

Pangkalan pengetahuan menyimpan pasangan pertanyaan dan jawaban untuk objek CreateKbDTO dari tiga sumber:

• Untuk konten editorial, gunakan objek QnADTO.
  • Untuk menggunakan metadata dan petunjuk tindak lanjut, gunakan konteks editorial, karena data ini ditambahkan pada tingkat pasangan QnA individual.
• Untuk file, gunakan objek FileDTO. FileDTO menyertakan nama file dan URL publik untuk mencapai file.
• Untuk URL, gunakan daftar string untuk mewakili URL yang tersedia untuk umum.

Langkah pembuatan juga mencakup properti untuk pangkalan pengetahuan:

• defaultAnswerUsedForExtraction - apa yang ditampilkan ketika tidak ada jawaban yang ditemukan
• enableHierarchicalExtraction - secara otomatis membuat hubungan permintaan antara pasangan QnA yang diekstrak
• language - ketika membuat pangkalan pengetahuan pertama untuk sumber daya, atur bahasa yang akan digunakan dalam indeks Azure Search.

Hubungi metode buat dengan informasi pangkalan pengetahuan. Informasi pangkalan pengetahuan pada dasarnya adalah objek JSON.

Ketika metode buat kembali, berikan ID operasi yang dikembalikan ke metode wait_for_operation ke polling untuk status. Metode wait_for_operation ini akan kembali ketika operasi selesai. Urai nilai header resourceLocation dari operasi yang dikembalikan untuk mendapatkan ID pangkalan pengetahuan baru.

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

Pastikan untuk menyertakan fungsi wait_for_operation, yang direferensikan dalam kode di atas, agar berhasil membuat pangkalan pengetahuan.

Memperbarui pangkalan pengetahuan

Anda dapat memperbarui pangkalan pengetahuan dengan meneruskan ID pangkalan pengetahuan dan UpdateKbOperationDTO yang berisi menambahkan,memperbarui, dan menghapus objek DTO ke metode pembaruan. DNO juga pada dasarnya adalah objek JSON. Gunakan wait_for_operation untuk menentukan apakah pembaruan berhasil.

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
}

Pastikan untuk menyertakan fungsi wait_for_operation, yang direferensikan dalam kode di atas, agar berhasil memperbarui pangkalan pengetahuan.

Mengunduh basis pengetahuan

Gunakan metode unduh untuk mengunduh database sebagai daftar QnADocumentsDTO. Ini tidak setara dengan ekspor portal QnA Maker dari halaman Pengaturan karena hasil dari metode ini bukan file TSV.

const downloadKnowledgeBase = async (KBclient, kb_id) => {

    console.log(`Downloading knowledge base...`)

    var kbData = await KBclient.download(kb_id, "Prod");
    console.log(`Knowledge base downloaded. It has ${kbData.qnaDocuments.length} QnAs.`);

    // Do something meaningful with data
}

Terbitkan pangkalan pengetahuan

Terbitkan pangkalan pengetahuan menggunakan metode terbitkan. Hal ini mengambil model yang disimpan dan dilatih saat ini, dirujuk oleh ID pangkalan Pengetahuan, dan menerbitkannya pada titik akhir. Periksa kode respons HTTP untuk memvalidasi bahwa publikasi berhasil.

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
}

Meminta pangkalan pengetahuan

Mendapatkan kunci runtime kueri

Setelah pangkalan pengetahuan diterbitkan, Anda memerlukan kunci runtime kueri untuk mengkueri runtime. Ini tidak sama dengan kunci yang digunakan untuk membuat objek klien asli.

Gunakan metode EndpointKeys.getKeys untuk mendapatkan kelas EndpointKeysDTO.

Gunakan salah satu properti kunci yang dikembalikan dalam objek untuk meminta pangkalan pengetahuan.

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
}

Mengautentikasi runtime untuk menghasilkan jawaban

Buat QnAMakerRuntimeClient mengkueri pangkalan pengetahuan untuk menghasilkan jawaban atau melatih dari pembelajaran aktif.

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

Gunakan QnAMakerRuntimeClient untuk mendapatkan jawaban dari pengetahuan atau untuk mengirim pertanyaan baru yang disarankan ke pangkalan pengetahuan untuk pembelajaran aktif.

Menghasilkan jawaban dari pangkalan pengetahuan

Hasilkan jawaban dari pangkalan pengetahuan yang dipublikasikan menggunakan metode RuntimeClient.runtime.generateAnswer. Metode ini menerima ID Pangkalan Pengetahuan dan QueryDTO. Akses properti tambahan dari QueryDTO, seperti Atas dan Konteks untuk digunakan dalam bot obrolan Anda.

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

}

Ini adalah contoh sederhana yang meminta pangkalan pengetahuan. Untuk memahami skenario kueri tingkat lanjut, tinjau contoh kueri lainnya.

Menghapus pangkalan pengetahuan

Hapus pangkalan pengetahuan menggunakan metode hapus dengan parameter ID pangkalan pengetahuan.

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
}

Mendapatkan status operasi

Beberapa metode, seperti buat dan perbarui, memerlukan waktu yang lama sehingga daripada menunggu proses selesai, operasi dikembalikan. Gunakan ID operasi dari operasi ke polling (dengan logika coba lagi) untuk menentukan status metode asli.

Panggilan DelayTimer di blok kode berikut digunakan untuk mensimulasikan logika coba lagi. Ganti ini dengan logika coba lagi Anda sendiri.

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

Jalankan aplikasi

Jalankan aplikasi dengan node index.js perintah dari direktori aplikasi Anda.

node index.js

Kode sumber untuk sampel ini dapat ditemukan di GitHub.

Gunakan pustaka klien QnA Maker untuk Python guna:

• Membuat pangkalan pengetahuan
• Memperbarui pangkalan pengetahuan
• Menerbitkan pangkalan pengetahuan
• Mendapatkan kunci titik akhir runtime prediksi
• Menunggu tugas yang sudah berjalan lama
• Mengunduh pangkalan pengetahuan
• Mendapatkan jawaban dari pangkalan pengetahuan
• Hapus pangkalan pengetahuan

Dokumentasi referensi | Kode sumber pustaka | Paket (PyPi) | Sampel Python

Catatan

Sumber daya baru yang dibuat setelah 1 Juli 2019, akan menggunakan nama subdomain kustom. Untuk informasi selengkapnya dan daftar lengkap titik akhir regional, lihat Nama subdomain kustom untuk layanan Azure AI.

Prasyarat

Catatan

Dokumentasi ini tidak berlaku untuk rilis terbaru. Untuk mempelajari tentang menggunakan Python API dengan rilis terbaru, lihat mulai cepat jawaban atas pertanyaan Python.

• Langganan Azure - Buat langganan secara gratis
• Python 3.x
• Setelah Anda berlangganan Azure, buat sumber daya QnA Maker di portal Azure untuk mendapatkan kunci penulisan dan titik akhir. Setelah menyebar, pilih Buka sumber daya.
  • Anda akan memerlukan kunci dan titik akhir dari sumber daya yang Anda buat untuk menyambungkan aplikasi ke QnA Maker API. Anda akan menempelkan kunci dan titik akhir ke dalam kode di bawah ini di mulai cepat.
  • Anda dapat menggunakan tingkat harga gratis (F0) untuk percobaan, lalu meningkatkannya ke tingkat berbayar untuk produksi.

Menyiapkan

Memasang pustaka klien

Setelah memasang Python, Anda dapat memasang pustaka klien dengan:

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

Membuat aplikasi Python baru

Buat file Python baru bernama quickstart-file.py dan impor pustaka berikut.

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

Buat variabel untuk titik akhir dan kunci Azure dari sumber daya Anda.

• Kami menggunakan kunci langganan dan kunci penulisan secara bergantian. Untuk detail selengkapnya tentang kunci penulisan, ikuti Kunci di QnA Maker.

• Nilai QNA_MAKER_ENDPOINT memiliki format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Buka portal Microsoft Azure, lalu temukan sumber daya QnA Maker yang Anda buat di prasyarat. Klik halaman Kunci dan Titik Akhir pada bagian manajemen sumber daya untuk menemukan kunci Penulisan (Langganan) dan Titik Akhir QnA Maker.

• Nilai QNA_MAKER_RUNTIME_ENDPOINT memiliki format https://YOUR-RESOURCE-NAME.azurewebsites.net. Buka portal Microsoft Azure, lalu temukan sumber daya QnA Maker yang Anda buat di prasyarat. Klik halaman Ekspor Template di bagian Otomatisasi untuk menemukan Titik Akhir Runtime.

Penting

Jangan lupa menghapus kunci dari kode setelah Anda selesai, dan jangan pernah mempostingnya secara publik. Untuk produksi, gunakan cara yang aman untuk menyimpan dan mengakses kredensial Anda seperti Azure Key Vault. Lihat artikel keamanan layanan Azure AI untuk informasi selengkapnya.

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'

Model objek

QnA Maker menggunakan dua model objek yang berbeda:

• QnAMakerClient adalah objek untuk membuat, mengelola, menerbitkan, dan mengunduh pangkalan pengetahuan.
• QnAMakerRuntime adalah objek untuk meminta pangkalan pengetahuan dengan API GenerateAnswer dan mengirim saran pertanyaan baru menggunakan API Train (sebagai bagian dari pembelajaran aktif).

Menggunakan basis pengetahuan contoh ini

Basis pengetahuan dalam mulai cepat ini dimulai dengan 2 pasangan tanya jawab percakapan, ini dilakukan dengan sengaja untuk menyederhanakan contoh dan memiliki Id yang sangat dapat diprediksi untuk digunakan dalam metode Pembaruan, mengaitkan permintaan tindak lanjut dengan pertanyaan kepada pasangan baru. Ini direncanakan dan diimplementasikan dalam urutan tertentu untuk mulai cepat ini.

Jika Anda berencana untuk mengembangkan basis pengetahuan Anda dari waktu ke waktu dengan perintah tindak lanjut yang bergantung pada pasangan tanya jawab yang ada, Anda dapat memilih:

• Untuk basis pengetahuan yang lebih besar, kelola basis pengetahuan di editor teks atau alat TSV yang mendukung otomatisasi, lalu ganti sepenuhnya basis pengetahuan sekaligus dengan pembaruan.
• Untuk basis pengetahuan yang lebih kecil, kelola perintah tindak lanjut sepenuhnya di portal QnA Maker.

Detail tentang pasangan tanya jawab yang digunakan dalam mulai cepat ini:

• Jenis pasangan tanya jawab - ada 2 jenis pasangan tanya jawab di basis pengetahuan ini, setelah pembaruan: chitchat dan informasi khusus domain. Ini khas jika basis pengetahuan Anda terikat dengan aplikasi percakapan seperti chatbot.
• Meskipun jawaban basis pengetahuan dapat difilter oleh metadata atau menggunakan perintah tindak lanjut, mulai cepat ini tidak menunjukkannya. Carilah contoh-contoh bahasa-agnostik generateAnswer di sini.
• Teks jawaban adalah markdown dan dapat berisi berbagai markdown seperti gambar (gambar berbasis internet yang tersedia untuk umum), tautan (ke URL yang tersedia untuk umum), dan titik poin, mulai cepat ini tidak menggunakan variasi itu.

Model objek QnAMakerClient

Klien QnA Maker penulisan adalah objek QnAMakerClient yang mengautentikasi ke Azure menggunakan Microsoft.Rest.ServiceClientCredentials, yang berisi kunci Anda.

Setelah klien dibuat, gunakan properti Pangkalan pengetahuan untuk membuat, mengelola, dan menerbitkan pangkalan pengetahuan Anda.

Kelola pangkalan pengetahuan Anda dengan mengirim objek JSON. Untuk operasi segera, metode biasanya menampilkan objek JSON yang menunjukkan status. Untuk operasi jangka panjang, responsnya adalah ID operasi. Hubungi operations.get_details dengan ID operasi untuk menentukan status permintaan.

Model objek QnAMakerRuntimeClient

Klien QnA Maker prediksi adalah objek QnAMakerRuntimeClient yang mengautentikasi ke Azure menggunakan Microsoft.Rest.ServiceClientCredentials, yang berisi kunci runtime prediksi Anda, yang dikembalikan dari panggilan klien penulisan, client.EndpointKeysOperations.get_keys setelah pangkalan pengetahuan diterbitkan.

Gunakan metode generate_answer untuk mendapatkan jawaban dari runtime kueri.

Mengautentikasi klien untuk menulis basis pengetahuan

Membuat instans klien dengan titik akhir dan kunci Anda. Buat objek CognitiveServicesCredentials dengan kunci Anda, dan gunakan dengan titik akhir Anda untuk membuat objek QnAMakerClient.

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

Membuat basis pengetahuan

Gunakan objek klien untuk mendapatkan objek operasi pangkalan pengetahuan.

Pangkalan pengetahuan menyimpan pasangan pertanyaan dan jawaban untuk objek CreateKbDTO dari tiga sumber:

• Untuk konten editorial, gunakan objek QnADTO.
  • Untuk menggunakan metadata dan petunjuk tindak lanjut, gunakan konteks editorial, karena data ini ditambahkan pada tingkat pasangan QnA individual.
• Untuk file, gunakan objek FileDTO. FileDTO menyertakan nama file dan URL publik untuk mencapai file.
• Untuk URL, gunakan daftar string untuk mewakili URL yang tersedia untuk umum.

Panggil metode create kemudian berikan ID operasi yang dikembalikan ke metode Operations.getDetails ke polling untuk status.

Baris akhir dari kode berikut menampilkan ID pangkalan pengetahuan dari respons 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

Pastikan untuk menyertakan fungsi _monitor_operation, yang direferensikan dalam kode di atas, agar berhasil membuat pangkalan pengetahuan.

Memperbarui pangkalan pengetahuan

Anda dapat memperbarui pangkalan pengetahuan dengan meneruskan ID pangkalan pengetahuan dan UpdateKbOperationDTO yang berisi menambahkan,memperbarui, dan menghapus objek DTO ke metode pembaruan. Gunakan metode Operation.getDetail untuk menentukan apakah pembaruan berhasil.

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

Pastikan untuk menyertakan fungsi _monitor_operation, yang direferensikan dalam kode di atas, agar berhasil memperbarui pangkalan pengetahuan.

Mengunduh basis pengetahuan

Gunakan metode unduh untuk mengunduh database sebagai daftar QnADocumentsDTO. Ini tidak setara dengan ekspor portal QnA Maker dari halaman Pengaturan karena hasil dari metode ini bukan file 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)))

Terbitkan pangkalan pengetahuan

Terbitkan pangkalan pengetahuan menggunakan metode terbitkan. Hal ini mengambil model yang disimpan dan dilatih saat ini, dirujuk oleh ID pangkalan Pengetahuan, dan menerbitkannya pada titik akhir.

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

Meminta pangkalan pengetahuan

Mendapatkan kunci runtime kueri

Setelah pangkalan pengetahuan diterbitkan, Anda memerlukan kunci runtime kueri untuk mengkueri runtime. Ini tidak sama dengan kunci yang digunakan untuk membuat objek klien asli.

Gunakan metode EndpointKeysOperations.get_keys untuk mendapatkan class EndpointKeysDTO.

Gunakan salah satu properti kunci yang dikembalikan dalam objek untuk meminta pangkalan pengetahuan.

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

Mengautentikasi runtime untuk menghasilkan jawaban

Buat QnAMakerRuntimeClient mengkueri pangkalan pengetahuan untuk menghasilkan jawaban atau melatih dari pembelajaran aktif.

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

Gunakan QnAMakerRuntimeClient untuk mendapatkan jawaban dari pengetahuan atau untuk mengirim pertanyaan baru yang disarankan ke pangkalan pengetahuan untuk pembelajaran aktif.

Menghasilkan jawaban dari pangkalan pengetahuan

Hasilkan jawaban dari pangkalan pengetahuan yang dipublikasikan menggunakan metode QnAMakerRuntimeClient.runtime.generate_answer. Metode ini menerima ID Pangkalan Pengetahuan dan QueryDTO. Akses properti tambahan dari QueryDTO, seperti Atas dan Konteks untuk digunakan dalam bot obrolan Anda.

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

Ini adalah contoh sederhana untuk mengirim kueri ke pangkalan pengetahuan. Untuk memahami skenario kueri tingkat lanjut, tinjau contoh kueri lainnya.

Menghapus pangkalan pengetahuan

Hapus pangkalan pengetahuan menggunakan metode hapus dengan parameter ID pangkalan pengetahuan.

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

Mendapatkan status operasi

Beberapa metode, seperti buat dan perbarui, memerlukan waktu yang lama sehingga daripada menunggu proses selesai, operasi dikembalikan. Gunakan ID operasi dari operasi ke polling (dengan logika coba lagi) untuk menentukan status metode asli.

Panggilan setTimeout di blok kode berikut digunakan untuk mensimulasikan kode asinkron. Ganti ini dengan logika coba lagi.

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

Jalankan aplikasi

Jalankan aplikasi dengan perintah Python pada file mulai cepat Anda.

python quickstart-file.py

Kode sumber untuk sampel ini dapat ditemukan di GitHub.

Menggunakan pustaka klien QnA Maker untuk Java untuk:

• Membuat pangkalan pengetahuan
• Memperbarui pangkalan pengetahuan
• Menerbitkan pangkalan pengetahuan
• Mendapatkan kunci titik akhir runtime prediksi
• Menunggu tugas yang sudah berjalan lama
• Mengunduh pangkalan pengetahuan
• Mendapatkan jawaban dari pangkalan pengetahuan
• Hapus pangkalan pengetahuan

Kode sumber pustaka | Paket | Sampel

Catatan

Sumber daya baru yang dibuat setelah 1 Juli 2019, akan menggunakan nama subdomain kustom. Untuk informasi selengkapnya dan daftar lengkap titik akhir regional, lihat Nama subdomain kustom untuk layanan Azure AI.

Prasyarat

• Langganan Azure - Buat langganan secara gratis
• JDK
• Setelah Anda berlangganan Azure, buat sumber daya QnA Maker di portal Azure untuk mendapatkan kunci penulisan dan titik akhir. Setelah menyebar, pilih Buka sumber daya.
  • Anda akan memerlukan kunci dan titik akhir dari sumber daya yang Anda buat untuk menyambungkan aplikasi ke QnA Maker API. Tempelkan kunci dan titik akhir ke dalam kode di bawah ini nanti di mulai cepat.
  • Anda dapat menggunakan tingkat harga gratis (F0) untuk percobaan, lalu meningkatkannya ke tingkat berbayar untuk produksi.

Menyiapkan

Menginstal pustaka klien

Setelah menginstal Java, Anda dapat menginstal pustaka klien menggunakan Maven dari Repositori MVN.

Membuat aplikasi Java baru

Buat file bernama quickstart.java dan impor pustaka berikut.

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

Buat variabel untuk titik akhir dan kunci Azure dari sumber daya Anda.

• Kami menggunakan kunci langganan dan kunci penulisan secara bergantian. Untuk detail selengkapnya tentang kunci penulisan, ikuti Kunci di QnA Maker.

• Nilai QNA_MAKER_ENDPOINT memiliki format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Buka portal Microsoft Azure, lalu temukan sumber daya QnA Maker yang Anda buat di prasyarat. Klik halaman Kunci dan Titik Akhir pada bagian manajemen sumber daya untuk menemukan kunci Penulisan (Langganan) dan Titik Akhir QnA Maker.

• Nilai QNA_MAKER_RUNTIME_ENDPOINT memiliki format https://YOUR-RESOURCE-NAME.azurewebsites.net. Buka portal Microsoft Azure, lalu temukan sumber daya QnA Maker yang Anda buat di prasyarat. Klik halaman Ekspor Template di bagian Otomatisasi untuk menemukan Titik Akhir Runtime.

Penting

Jangan lupa menghapus kunci dari kode setelah Anda selesai, dan jangan pernah mempostingnya secara publik. Untuk produksi, gunakan cara yang aman untuk menyimpan dan mengakses kredensial Anda seperti Azure Key Vault. Lihat artikel keamanan layanan Azure AI untuk informasi selengkapnya.

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

Model objek

QnA Maker menggunakan dua model objek yang berbeda:

• QnAMakerClient adalah objek untuk membuat, mengelola, menerbitkan, dan mengunduh pangkalan pengetahuan.
• QnAMakerRuntime adalah objek untuk meminta pangkalan pengetahuan dengan API GenerateAnswer dan mengirim saran pertanyaan baru menggunakan API Train (sebagai bagian dari pembelajaran aktif).

Menggunakan basis pengetahuan contoh ini

Basis pengetahuan dalam mulai cepat ini dimulai dengan 2 pasangan tanya jawab percakapan, ini dilakukan dengan sengaja untuk menyederhanakan contoh dan memiliki Id yang sangat dapat diprediksi untuk digunakan dalam metode Pembaruan, mengaitkan permintaan tindak lanjut dengan pertanyaan kepada pasangan baru. Ini direncanakan dan diimplementasikan dalam urutan tertentu untuk mulai cepat ini.

Jika Anda berencana untuk mengembangkan basis pengetahuan Anda dari waktu ke waktu dengan perintah tindak lanjut yang bergantung pada pasangan tanya jawab yang ada, Anda dapat memilih:

• Untuk basis pengetahuan yang lebih besar, kelola basis pengetahuan di editor teks atau alat TSV yang mendukung otomatisasi, lalu ganti sepenuhnya basis pengetahuan sekaligus dengan pembaruan.
• Untuk basis pengetahuan yang lebih kecil, kelola perintah tindak lanjut sepenuhnya di portal QnA Maker.

Detail tentang pasangan tanya jawab yang digunakan dalam mulai cepat ini:

• Jenis pasangan tanya jawab - ada 2 jenis pasangan tanya jawab di basis pengetahuan ini, setelah pembaruan: chitchat dan informasi khusus domain. Ini khas jika basis pengetahuan Anda terikat dengan aplikasi percakapan seperti chatbot.
• Meskipun jawaban basis pengetahuan dapat difilter oleh metadata atau menggunakan perintah tindak lanjut, mulai cepat ini tidak menunjukkannya. Carilah contoh-contoh bahasa-agnostik generateAnswer di sini.
• Teks jawaban adalah markdown dan dapat berisi berbagai markdown seperti gambar (gambar berbasis internet yang tersedia untuk umum), tautan (ke URL yang tersedia untuk umum), dan titik poin, mulai cepat ini tidak menggunakan variasi itu.

Model objek QnAMakerClient

Klien QnA Maker penulisan adalah objek QnAMakerClient yang mengautentikasi ke Azure menggunakan MsRest::ServiceClientCredentials, yang berisi kunci Anda.

Setelah klien dibuat, gunakan metode properti Basis Pengetahuan klien untuk membuat mengelola, dan menerbitkan basis pengetahuan.

Untuk operasi segera, metode biasanya mengembalikan hasilnya, jika ada. Untuk operasi jangka panjang, responsnya adalah objek Operasi. Panggil metode getDetails dengan nilai operation.operationId untuk menentukan status permintaan.

Model objek QnAMakerRuntimeClient

Klien QnA Maker runtime adalah objek QnAMakerRuntimeClient.

Setelah Anda memublikasikan basis pengetahuan Anda menggunakan klien penulis, gunakan metode generateAnswer klien runtime untuk mendapatkan jawaban dari basis pengetahuan.

Anda membuat klien runtime dengan memanggil QnAMakerRuntimeManager.authenticate dan melewati kunci titik akhir runtime. Untuk mendapatkan kunci titik akhir runtime, gunakan klien penulis untuk memanggil getKeys.

Mengautentikasi klien untuk menulis basis pengetahuan

Buat objek klien dengan titik akhir penulisan dan kunci langganan.

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

Membuat basis pengetahuan

Pangkalan pengetahuan menyimpan pasangan pertanyaan dan jawaban untuk objek CreateKbDTO dari tiga sumber:

• Untuk konten editorial, gunakan objek QnADTO.
  • Untuk menggunakan metadata dan petunjuk tindak lanjut, gunakan konteks editorial, karena data ini ditambahkan pada tingkat pasangan QnA individual.
• Untuk file, gunakan objek FileDTO. FileDTO menyertakan nama file dan URL publik untuk mencapai file.
• Untuk URL, gunakan daftar string untuk mewakili URL yang tersedia untuk umum.

Panggil metode buat lalu berikan properti operationId dari operasi yang dikembalikan ke metode getDetails untuk jajak pendapat status.

Baris akhir dari kode berikut mengembalikan ID basis pengetahuan.

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

Memperbarui pangkalan pengetahuan

Anda dapat memperbarui pangkalan pengetahuan dengan memanggil perbarui, dan memberikan ID pangkalan pengetahuan dan objek UpdateKbOperationDTO. Objek tersebut pada gilirannya dapat berisi:

• penambahan
• memperbarui
• hapus

Berikan operationId properti operasi yang dikembalikan ke metode getDetails untuk jajak pendapat status.

public void update_kb (String kb_id) throws Exception {
    System.out.println("Updating KB...");

    var update = new UpdateKbOperationDTOUpdate().withName ("New KB name");

    var payload = new UpdateKbOperationDTO().withUpdate((UpdateKbOperationDTOUpdate)update);

    var result = kb_client.update(kb_id, payload);
    wait_for_operation(result);

    System.out.println("Updated KB.");
}

Mengunduh basis pengetahuan

Gunakan metode unduh untuk mengunduh database sebagai daftar QnADocumentsDTO. Ini tidak setara dengan ekspor portal QnA Maker dari halaman Pengaturan karena hasil dari metode ini bukan file 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");
}

Terbitkan pangkalan pengetahuan

Terbitkan pangkalan pengetahuan menggunakan metode terbitkan. Hal ini mengambil model yang disimpan dan dilatih saat ini, dirujuk oleh ID pangkalan Pengetahuan, dan menerbitkannya pada titik akhir.

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

Menghasilkan jawaban dari pangkalan pengetahuan

Setelah basis pengetahuan diterbitkan, Anda memerlukan kunci titik akhir runtime untuk meminta basis pengetahuan. Ini tidak sama dengan kunci langganan yang digunakan untuk membuat klien penulisan.

Gunakan metode getKeys untuk mendapatkan objek EndpointKeysDTO.

Buat klien runtime dengan memanggil QnAMakerRuntimeManager.authenticate dan memberikan kunci titik akhir runtime dari objek EndpointKeysDTO.

Buat jawaban dari basis pengetahuan yang diterbitkan menggunakan metode generate_answer ini. Metode ini menerima ID basis pengetahuan dan objek 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();
}

Ini merupakan contoh sederhana dari meminta pangkalan pengetahuan. Untuk memahami skenario kueri tingkat lanjut, tinjau contoh kueri lainnya.

Menghapus pangkalan pengetahuan

Hapus pangkalan pengetahuan menggunakan metode hapus dengan parameter ID pangkalan pengetahuan.

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

Mendapatkan status operasi

Beberapa metode, seperti buat dan perbarui, memerlukan waktu yang lama sehingga daripada menunggu proses selesai, operasi dikembalikan. Gunakan ID operasi dari operasi ke polling (dengan logika coba lagi) untuk menentukan status metode asli.

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

Jalankan aplikasi

Berikut metode utama untuk aplikasi.

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

Jalankan aplikasi sebagai berikut. Ini menganggap nama kelas Quickstart dan dependensi Anda berada dalam subfolder bernama lib di bawah folder saat ini.

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

Kode sumber untuk sampel ini dapat ditemukan di GitHub.

Membersihkan sumber daya

Jika Anda ingin membersihkan dan menghapus langganan layanan Azure AI, Anda dapat menghapus sumber daya atau grup sumber daya. Menghapus grup sumber daya juga menghapus sumber daya apa pun yang terkait dengannya.

• Portal
• Azure CLI

Langkah berikutnya

Tutorial: Menguji basis pengetahuan Anda dengan file batch

• Apa itu QnA Maker API?
• Mengedit pangkalan pengetahuan
• Mendapatkan analitik penggunaan