Hızlı Başlangıç: Soru-Cevap Oluşturma istemci kitaplığı

Soru-Cevap Oluşturma istemci kitaplığını kullanmaya başlayın. Paketi yüklemek için bu adımları izleyin ve temel görevler için örnek kodu deneyin.

Not

Soru-Cevap Oluşturma hizmeti 31 Mart 2025'te kullanımdan kaldırılıyor. Soru ve yanıtlama özelliğinin daha yeni bir sürümü artık Dil için Azure Bilişsel Hizmet'in bir parçası olarak kullanılabilir. Dil Hizmeti'nin içindeki soru yanıtlama özellikleri için bkz. soru yanıtlama. 1 Ekim 2022'den itibaren yeni Soru-Cevap Oluşturma kaynakları oluşturamayacaksınız. Soru-Cevap Oluşturma bilgi bankalarını soru yanıtlamaya geçirme hakkında bilgi için geçiş kılavuzuna bakın.

Ön koşullar

Not

Bu belgeler en son sürüm için geçerli değildir. REST API'yi en son sürümle kullanma hakkında bilgi edinmek için REST API hızlı başlangıcını yanıtlama sorusuna bakın

• cURL'nin geçerli sürümü. Hızlı başlangıçlarda , cURL belgelerinde belirtilen çeşitli komut satırı anahtarları kullanılır.

• Anahtar ve kaynak adını kullanmak için soru-cevap oluşturma kaynağınız olmalıdır. Kaynak oluşturma sırasında kaynak Adını girdiniz, ardından anahtar sizin için oluşturuldu. Kaynak adı uç noktanızın alt etki alanı olarak kullanılır. Anahtarınızı ve kaynak adınızı almak için Azure portal kaynağınız için Hızlı Başlangıç'ı seçin. Kaynak adı, uç nokta URL'sinin ilk alt etki alanıdır:

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

Dikkat

Aşağıdaki BASH örneklerinde satır devamı karakteri kullanılır \ . Konsol veya terminal farklı bir satır devamı karakteri kullanıyorsa, bu karakteri kullanın.

Bilgi bankası oluşturma

REST API'leri ve cURL ile bir bilgi bankası oluşturmak için aşağıdaki bilgilere sahip olmanız gerekir:

Bilgi	cURL yapılandırması	Amaç
Soru-Cevap Oluşturma kaynak adı	URL	URL oluşturmak için kullanılır
Soru-Cevap Oluşturma kaynak anahtarı	-h üst bilgi için Ocp-Apim-Subscription-Key param	Soru-Cevap Oluşturma hizmetinde kimlik doğrulaması
bilgi bankası açıklayan JSON	-d param	JSON örnekleri
JSON'un bayt cinsinden boyutu	-h üst bilgi için Content-Size param

cURL komutu bir BASH kabuğundan yürütülür. Bu komutu kendi kaynak adınız, kaynak anahtarınız, JSON değerleriniz ve JSON boyutunuzla düzenleyin.

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/cognitive-services/qnamaker/faqs"]}'

Soru-Cevap Oluşturma'dan gelen cURL yanıtı, operationIdişlemin durumunu almak için gereken öğesini içerir.

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

İşlemin durumunu alma

bir bilgi bankası oluşturduğunuzda, işlem zaman uyumsuz olduğundan yanıt, durumu belirlemeye yönelik bilgiler içerir.

Bilgi	cURL yapılandırması	Amaç
Soru-Cevap Oluşturma kaynak adı	URL	URL oluşturmak için kullanılır
İşlem Kimliği	URL yolu	/operations/REPLACE-WITH-YOUR-OPERATION-ID
Soru-Cevap Oluşturma kaynak anahtarı	-h üst bilgi için Ocp-Apim-Subscription-Key param	Soru-Cevap Oluşturma hizmetinde kimlik doğrulaması

cURL komutu bir BASH kabuğundan yürütülür. Bu komutu kendi kaynak adınız, kaynak anahtarınız ve işlem kimliğiniz ile düzenleyin.

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 yanıtı durumu içerir. İşlem durumu başarılı olursa, resourceLocation bilgi bankası kimliğini içerir.

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

Bilgi bankası yayımlama

bilgi bankası sorgulamadan önce şunları yapmanız gerekir:

• Bilgi bankası yayımlama
• Çalışma zamanı uç noktası anahtarını alma

Bu görev bilgi bankası yayımlar. Çalışma zamanı uç noktası anahtarını almak ayrı bir görevdir.

Bilgi	cURL yapılandırması	Amaç
Soru-Cevap Oluşturma kaynak adı	URL	URL oluşturmak için kullanılır
Soru-Cevap Oluşturma kaynak anahtarı	-h üst bilgi için Ocp-Apim-Subscription-Key param	Soru-Cevap Oluşturma hizmetinde kimlik doğrulaması
Bilgi bankası kimliği	URL yolu	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

cURL komutu bir BASH kabuğundan yürütülür. Bu komutu kendi kaynak adınız, kaynak anahtarınız ve bilgi bankası kimliğiniz ile düzenleyin.

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

Sonuç olmadan yanıt durumu 204'dür. cURL komutunun -v ayrıntılı çıktısını görmek için komut satırı parametresini kullanın. Bu, HTTP durumunu içerir.

Yayımlanan bilgi bankası çalışma zamanı uç noktası anahtarını alma

bilgi bankası sorgulamadan önce şunları yapmanız gerekir:

• Bilgi bankası yayımlama
• Çalışma zamanı uç noktası anahtarını alma

Bu görev çalışma zamanı uç noktası anahtarını alır. bilgi bankası yayımlamak ayrı bir görevdir.

Çalışma zamanı uç noktası anahtarı, Soru-Cevap Oluşturma kaynağını kullanan tüm bilgi bankaları için aynı anahtardır.

Bilgi	cURL yapılandırması	Amaç
Soru-Cevap Oluşturma kaynak adı	URL	URL oluşturmak için kullanılır
Soru-Cevap Oluşturma kaynak anahtarı	-h üst bilgi için Ocp-Apim-Subscription-Key param	Soru-Cevap Oluşturma hizmetinde kimlik doğrulaması

cURL komutu bir BASH kabuğundan yürütülür. Bu komutu kendi kaynak adınız ve kaynak anahtarınız ile düzenleyin.

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 yanıtı çalışma zamanı uç noktası anahtarlarını içerir. bilgi bankası yanıt almak için sorgularken anahtarlardan yalnızca birini kullanın.

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

Yayımlanan bilgi bankası yanıt sorgulama

Bilgilerden yanıt almak, bilgi bankası yönetmekten ayrı bir çalışma zamanından yapılır. Ayrı bir çalışma zamanı olduğundan, bir çalışma zamanı anahtarıyla kimlik doğrulaması yapmanız gerekir.

Bilgi	cURL yapılandırması	Amaç
Soru-Cevap Oluşturma kaynak adı	URL	URL oluşturmak için kullanılır
Soru-Cevap Oluşturma çalışma zamanı anahtarı	-h üst bilgi için Authorization param	anahtar, sözcüğünü Endpointkey içeren bir dizenin parçasıdır. Soru-Cevap Oluşturma hizmetinde kimlik doğrulaması
Bilgi bankası kimliği	URL yolu	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
Sorguyu açıklayan JSON	-d param	İstek gövdesi parametreleri ve JSON örnekleri
JSON'un bayt cinsinden boyutu	-h üst bilgi için Content-Size param

cURL komutu bir BASH kabuğundan yürütülür. Bu komutu kendi kaynak adınız, kaynak anahtarınız ve bilgi bankası kimliğiniz ile düzenleyin.

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

Başarılı bir yanıt, sohbet botu gibi bir istemci uygulamasının kullanıcıya yanıt görüntülemesi gereken diğer bilgilerle birlikte en iyi yanıtı içerir.

bilgi bankası silme

bilgi bankası bitirdiğinizde silin.

Bilgi	cURL yapılandırması	Amaç
Soru-Cevap Oluşturma kaynak adı	URL	URL oluşturmak için kullanılır
Soru-Cevap Oluşturma kaynak anahtarı	-h üst bilgi için Ocp-Apim-Subscription-Key param	Soru-Cevap Oluşturma hizmetinde kimlik doğrulaması
Bilgi bankası kimliği	URL yolu	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

cURL komutu bir BASH kabuğundan yürütülür. Bu komutu kendi kaynak adınız, kaynak anahtarınız ve bilgi bankası kimliğiniz ile düzenleyin.

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"

Sonuç olmadan yanıt durumu 204'dür. cURL komutunun -v ayrıntılı çıktısını görmek için komut satırı parametresini kullanın. Bu, HTTP durumunu içerir.

Ek kaynaklar

• Yazma Başvuru belgeleri
• Çalışma zamanı Başvuru belgeleri
• cURL kullanan örnek BASH betikleri

.NET için Soru-Cevap Oluşturma istemci kitaplığını kullanarak:

• Bilgi bankası oluşturma
• Bilgi bankalarını güncelleştirme
• Bilgi bankası yayımlama
• Tahmin çalışma zamanı uç noktası anahtarını alma
• Uzun süre çalışan görevi bekleyin
• Bilgi bankası indirme
• Bilgi bankasından yanıt alma
• Bilgi bankalarını silme

Başvuru belgeleri | Kitaplık kaynak kodu | Paket (NuGet) | C# Örnekleri

Not

1 Temmuz 2019'da oluşturulan yeni kaynaklar özel alt etki alanı adlarını kullanır. Daha fazla bilgi ve bölgesel uç noktaların tam listesi için bkz. Bilişsel Hizmetler için özel alt etki alanı adları.

Ön koşullar

Not

Bu belgeler en son sürüm için geçerli değildir. En son sürümle C# API'sini kullanma hakkında bilgi edinmek için C# hızlı başlangıcını yanıtlama sorusuna başvurun.

• Azure aboneliği - Ücretsiz bir abonelik oluşturun
• Visual Studio IDE veya .NET Core'un geçerli sürümü.
• Azure aboneliğinizi aldıktan sonra yazma anahtarınızı ve kaynak adınızı almak için Azure portal bir Soru-Cevap Oluşturma kaynağı oluşturun. Dağıtıldıktan sonra Kaynağa git'i seçin.
  • Uygulamanızı Soru-Cevap Oluşturma API'sine bağlamak için oluşturduğunuz kaynağın anahtarına ve kaynak adına ihtiyacınız olacaktır. Anahtarınızı ve kaynak adınızı hızlı başlangıcın ilerleyen bölümlerinde aşağıdaki koda yapıştırın.
  • Ücretsiz fiyatlandırma katmanını (F0) kullanarak hizmeti deneyebilir ve daha sonra üretim için ücretli bir katmana yükseltebilirsiniz.

Ayarlama

CLI

Bir konsol penceresinde (cmd, PowerShell veya Bash gibi), adlı qna-maker-quickstartyeni bir konsol uygulaması oluşturmak için komutunu kullanındotnet new. Bu komut, tek bir kaynak dosyası olan basit bir "Merhaba Dünya" C# projesi oluşturur: program.cs.

dotnet new console -n qna-maker-quickstart

Dizininizi yeni oluşturulan uygulama klasörüyle değiştirin. Uygulamayı şu şekilde oluşturabilirsiniz:

dotnet build

Derleme çıkışı hiçbir uyarı veya hata içermemelidir.

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

Uygulama dizininde aşağıdaki komutu kullanarak .NET için Soru-Cevap Oluşturma istemci kitaplığını yükleyin:

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

İpucu

Hızlı başlangıç kod dosyasının tamamını aynı anda görüntülemek mi istiyorsunuz? Bu hızlı başlangıçtaki kod örneklerini içeren GitHub'da bulabilirsiniz.

Yönergeleri kullanma

Proje dizininden program.cs dosyasını açın ve aşağıdaki using yönergeleri ekleyin:

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

Abonelik anahtarı ve kaynak uç noktaları

Uygulamanın Main yönteminde, bu hızlı başlangıçtaki ortak görevleri kullanmak için aşağıdaki bölümde gösterilen değişkenleri ve kodu ekleyin.

• Abonelik anahtarını ve yazma anahtarını birbirinin yerine kullanırız. Anahtar yazma hakkında daha fazla ayrıntı için Soru-Cevap Oluşturma'da Anahtarlar'ı izleyin.

• QNA_MAKER_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Azure portal gidin ve önkoşullarda oluşturduğunuz Soru-Cevap Oluşturma kaynağını bulun. Yazma (Abonelik) anahtarını ve Soru-Cevap Oluşturma Uç Noktasını bulmak için kaynak yönetimi altında Anahtarlar ve Uç Nokta sayfasını seçin.

• QNA_MAKER_RUNTIME_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.azurewebsites.net. Azure portal gidin ve önkoşullarda oluşturduğunuz Soru-Cevap Oluşturma kaynağını bulun. Çalışma Zamanı Uç Noktasını bulmak için Otomasyon'un altındaki Şablonu Dışarı Aktar sayfasını seçin.

Önemli

İşiniz bittiğinde anahtarı kodunuzdan kaldırmayı unutmayın ve asla herkese açık olarak göndermeyin. Üretim için Azure Key Vault gibi kimlik bilgilerinizi depolamanın ve bunlara erişmenin güvenli bir yolunu kullanın. Daha fazla bilgi için Bilişsel Hizmetler güvenlik makalesine bakın.

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

Nesne modelleri

Soru-Cevap Oluşturma iki farklı nesne modeli kullanır:

• QnAMakerClient , bilgi bankasını oluşturma, yönetme, yayımlama ve indirme nesnesidir.
• QnAMakerRuntime, GenerateAnswer API'siyle bilgi bankası sorgulama ve EğitME API'sini kullanarak yeni önerilen sorular gönderme nesnesidir (etkin öğrenmenin bir parçası olarak).

Bu örneği bilgi bankası kullanma

Bu hızlı başlangıçtaki bilgi bankası 2 konuşma Soru-Cevap çiftiyle başlar. Bu, örneği basitleştirmek ve Güncelleştirme yönteminde kullanılacak yüksek oranda öngörülebilir kimliklere sahip olmak ve izleme istemlerini yeni çiftlerle ilişkilendirmek amacıyla gerçekleştirilir. Bu, bu hızlı başlangıç için belirli bir sırada planlandı ve uygulandı.

Zaman içinde mevcut Soru-Cevap çiftlerine bağımlı olan izleme istemleriyle bilgi bankası geliştirmeyi planlıyorsanız şunları seçebilirsiniz:

• Daha büyük bilgi bankaları için, otomasyonu destekleyen bir metin düzenleyicisinde veya TSV aracında bilgi bankası yönetin, ardından bilgi bankası bir güncelleştirmeyle aynı anda tamamen değiştirin.
• Daha küçük bilgi bankaları için soru-cevap oluşturma portalında izleme istemlerini tamamen yönetin.

Bu hızlı başlangıçta kullanılan Soru-Cevap çiftleri hakkındaki ayrıntılar:

• Soru-Cevap çifti türleri - güncelleştirmeden sonra bu bilgi bankası 2 soru-cevap çifti türü vardır: chitchat ve etki alanına özgü bilgiler. Bilgi bankanız sohbet botu gibi bir konuşma uygulamasına bağlıysa bu durum tipik bir durumdur.
• Bilgi bankası yanıtları meta verilere göre filtrelenebilir veya izleme istemleri kullanılabilir, ancak bu hızlı başlangıçta bu gösterilmez. Bu language-agnostic generateAnswer örneklerini burada bulabilirsiniz.
• Yanıt metni markdown'dır ve görüntüler (genel kullanıma açık internet tabanlı resimler), bağlantılar (genel kullanıma açık URL'ler) ve madde işaretleri gibi çok çeşitli markdown içerebilir. Bu hızlı başlangıçta bu çeşitlilik kullanılmamaktadır.

QnAMakerClient nesne modeli

Yazma Soru-Cevap Oluşturma istemcisi, Microsoft kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerClient nesnesidir. Anahtarınızı içeren Rest.ServiceClientCredentials.

İstemci oluşturulduktan sonra bilgi bankası özelliğini kullanarak bilgi bankası oluşturun, yönetin ve yayımlayın.

JSON nesnesi göndererek bilgi bankası yönetin. Hemen işlemler için bir yöntem genellikle durumu belirten bir JSON nesnesi döndürür. Uzun süre çalışan işlemler için yanıt işlem kimliğidir. İstemciyi çağırın. İsteğin durumunu belirlemek için işlem kimliğine sahip Operations.GetDetailsAsync yöntemi.

QnAMakerRuntimeClient nesne modeli

Tahmin Soru-Cevap Oluşturma istemcisi, Microsoft kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerRuntimeClient nesnesidir. Bilgi bankası yayımlandıktan sonra yazma istemci çağrısından client.EndpointKeys.GetKeys döndürülen tahmin çalışma zamanı anahtarınızı içeren Rest.ServiceClientCredentials.

Sorgu çalışma zamanından yanıt almak için GenerateAnswer yöntemini kullanın.

Kod örnekleri

Bu kod parçacıkları, .NET için Soru-Cevap Oluşturma istemci kitaplığıyla aşağıdakileri nasıl yapacağınızı gösterir:

• Yazma istemcisinin kimliğini doğrulama
• bilgi bankası oluşturma
• Bilgi bankası yükleme
• bilgi bankası indirme
• Bilgi bankası yayımlama
• Bilgi bankasını silme
• Sorgu çalışma zamanı anahtarını alma
• İşlemin durumunu alma
• Sorgu çalışma zamanı istemcisinin kimliğini doğrulama
• bilgi bankası yanıt oluşturma

bilgi bankası yazmak için istemcinin kimliğini doğrulama

Anahtarınızla bir istemci nesnesinin örneğini oluşturun ve bunu kaynağınızla birlikte kullanarak uç noktayı oluşturarak uç noktanız ve anahtarınız ile bir QnAMakerClient oluşturun. ServiceClientCredentials nesnesi oluşturun.

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

Bilgi bankası oluşturma

bilgi bankası, üç kaynaktan CreateKbDTO nesnesi için soru ve yanıt çiftlerini depolar:

• Editoryal içerik için QnADTO nesnesini kullanın.
  • Meta verileri ve izleme istemlerini kullanmak için editoryal bağlamı kullanın çünkü bu veriler tek tek Soru-Cevap çifti düzeyinde eklenir.
• Dosyalar için FileDTO nesnesini kullanın. FileDTO dosya adını ve dosyaya ulaşmak için genel URL'yi içerir.
• URL'ler için, genel kullanıma açık URL'leri temsil eden bir dize listesi kullanın.

Oluşturma adımı, bilgi bankasının özelliklerini de içerir:

• defaultAnswerUsedForExtraction - yanıt bulunamazsa ne döndürülür?
• enableHierarchicalExtraction - ayıklanan Soru-Cevap çiftleri arasında otomatik olarak istem ilişkileri oluşturma
• language - Bir kaynağın ilk bilgi bankasını oluştururken, Azure Search dizininde kullanılacak dili ayarlayın.

CreateAsync yöntemini çağırın ve ardından durum yoklaması için döndürülen işlem kimliğini MonitorOperation yöntemine geçirin.

Aşağıdaki kodun son satırı, MonitorOperation yanıtından bilgi bankası kimliğini döndürür.

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

Bir bilgi bankası başarıyla oluşturmak için yukarıdaki kodda başvuruda bulunılan işlevini eklediğinizden MonitorOperation emin olun.

Bilgi bankası güncelleştirme

Bilgi bankası Kimliğini ve UpdateAsync yöntemine DTO nesnelerini ekleme, güncelleştirme ve silme içeren bir UpdatekbOperationDTO geçirerek bir bilgi bankası güncelleştirebilirsiniz. Güncelleştirmenin başarılı olup olmadığını belirlemek için MonitorOperation yöntemini kullanın.

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

Bir bilgi bankası başarıyla güncelleştirmek için yukarıdaki kodda başvuruda bulunılan işlevini eklediğinizden MonitorOperation emin olun.

bilgi bankası indirme

Veritabanını QnADocumentsDTO listesi olarak indirmek için DownloadAsync yöntemini kullanın. Bu yöntemin sonucu bir dosya olmadığından bu, Soru-Cevap Oluşturma portalının Ayarlar sayfasından dışarı aktarma işlemiyle eşdeğer değildir.

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
}

Bilgi bankası yayımlama

PublishAsync yöntemini kullanarak bilgi bankası yayımlayın. Bu, bilgi bankası kimliği tarafından başvuruda bulunılan geçerli kaydedilmiş ve eğitilmiş modeli alır ve bunu uç noktanızda yayımlar. Bu, bilgi bankanızı sorgulamak için gerekli bir adımdır.

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

Sorgu çalışma zamanı anahtarını alma

Bir bilgi bankası yayımlandıktan sonra, çalışma zamanını sorgulamak için sorgu çalışma zamanı anahtarına ihtiyacınız olur. Bu, özgün istemci nesnesini oluşturmak için kullanılan anahtarla aynı değildir.

EndpointKeysDTO sınıfını almak için EndpointKeys yöntemini kullanın.

Bilgi bankasını sorgulamak için nesnesinde döndürülen anahtar özelliklerden birini kullanın.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

Bilgi bankanızı sorgulamak için bir çalışma zamanı anahtarı gereklidir.

Yanıt oluşturmak için çalışma zamanının kimliğini doğrulama

Yanıt oluşturmak veya etkin öğrenmeden eğitmek için bilgi bankası sorgulamak için bir QnAMakerRuntimeClient oluşturun.

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

QnAMakerRuntimeClient kullanarak:

• bilgi bankasından yanıt alın
• etkin öğrenme için bilgi bankası yeni önerilen sorular göndermek için.

bilgi bankası yanıt oluşturma

RuntimeClient kullanarak yayımlanmış bir bilgi bankasından yanıt oluşturun. GenerateAnswerAsync yöntemi. Bu yöntem bilgi bankası Kimliğini ve QueryDTO'yu kabul eder. Sohbet botunuzda kullanmak üzere QueryDTO'nun Top ve Context gibi ek özelliklerine erişin.

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
}

Bu, bilgi bankasını sorgulamaya yönelik basit bir örnektir. Gelişmiş sorgu senaryolarını anlamak için diğer sorgu örneklerini gözden geçirin.

Bilgi bankasını silme

bilgi bankası kimliği parametresiyle DeleteAsync yöntemini kullanarak bilgi bankasını silin.

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

İşlemin durumunu alma

Oluşturma ve güncelleştirme gibi bazı yöntemler, işlemin bitmesi yerine bir işlemin döndürülmesi için yeterli zaman alabilir. Özgün yöntemin durumunu belirlemek üzere yoklama (yeniden deneme mantığıyla) için işlemden işlem kimliğini kullanın.

Döngü ve Task.Delay aşağıdaki kod bloğunda yeniden deneme mantığının benzetimini yapmak için kullanılır. Bunlar kendi yeniden deneme mantığınızla değiştirilmelidir.

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

Uygulamayı çalıştırma

Uygulamayı uygulama dizininizden komutuyla dotnet run çalıştırın.

dotnet run

Bu örneğin kaynak kodu GitHub'da bulunabilir.

Node.js için Soru-Cevap Oluşturma istemci kitaplığını kullanın:

• Bilgi bankası oluşturma
• Bilgi bankalarını güncelleştirme
• Bilgi bankası yayımlama
• Tahmin çalışma zamanı uç noktası anahtarını alma
• Uzun süre çalışan görevi bekleyin
• Bilgi bankası indirme
• Bilgi bankasından yanıt alma
• bilgi bankası silme

Başvuru belgeleri | Kitaplık kaynak kodu | Paket (npm) | Node.js Örnekleri

Not

1 Temmuz 2019'da oluşturulan yeni kaynaklar özel alt etki alanı adlarını kullanır. Daha fazla bilgi ve bölgesel uç noktaların tam listesi için bkz. Bilişsel Hizmetler için özel alt etki alanı adları.

Ön koşullar

• Azure aboneliği - Ücretsiz bir abonelik oluşturun
• Node.jsgeçerli sürümü.
• Azure aboneliğinizi aldıktan sonra yazma anahtarınızı ve kaynağınızı almak için Azure portal bir Soru-Cevap Oluşturma kaynağı oluşturun. Dağıtıldıktan sonra Kaynağa git'i seçin.
  • Uygulamanızı Soru-Cevap Oluşturma API'sine bağlamak için oluşturduğunuz kaynağın anahtarına ve kaynak adına ihtiyacınız olacaktır. Anahtarınızı ve kaynak adınızı hızlı başlangıcın ilerleyen bölümlerinde aşağıdaki koda yapıştırın.
  • Ücretsiz fiyatlandırma katmanını (F0) kullanarak hizmeti deneyebilir ve daha sonra üretim için ücretli bir katmana yükseltebilirsiniz.

Ayarlama

Yeni bir Node.js uygulaması oluşturma

Konsol penceresinde (cmd, PowerShell veya Bash gibi), uygulamanız için yeni bir dizin oluşturun ve bu dizine gidin.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Dosyasını içeren npm init -y bir düğüm uygulaması package.json oluşturmak için komutunu çalıştırın.

npm init -y

İstemci kitaplığını yükleme

Aşağıdaki NPM paketlerini yükleyin:

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

Uygulamanızın package.json dosyası bağımlılıklarla güncelleştirilir.

index.js adlı bir dosya oluşturun ve aşağıdaki kitaplıkları içeri aktarın:

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

Kaynağınızın Azure anahtarı ve kaynak adı için bir değişken oluşturun.

• Abonelik anahtarını ve yazma anahtarını birbirinin yerine kullanırız. Anahtar yazma hakkında daha fazla ayrıntı için Soru-Cevap Oluşturma'da Anahtarlar'ı izleyin.

• QNA_MAKER_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Azure portal gidin ve önkoşullarda oluşturduğunuz Soru-Cevap Oluşturma kaynağını bulun. Yazma (Abonelik) anahtarını ve Soru-Cevap Oluşturma Uç Noktasını bulmak için kaynak yönetimi altında Anahtarlar ve Uç Nokta sayfasını seçin.

• QNA_MAKER_RUNTIME_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.azurewebsites.net. Azure portal gidin ve önkoşullarda oluşturduğunuz Soru-Cevap Oluşturma kaynağını bulun. Çalışma Zamanı Uç Noktasını bulmak için Otomasyon'un altındaki Şablonu Dışarı Aktar sayfasını seçin.

Önemli

İşiniz bittiğinde anahtarı kodunuzdan kaldırmayı unutmayın ve asla herkese açık olarak göndermeyin. Üretim için Azure Key Vault gibi kimlik bilgilerinizi depolamanın ve bunlara erişmenin güvenli bir yolunu kullanın. Daha fazla bilgi için Bilişsel Hizmetler güvenlik makalesine bakın.

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

Nesne modelleri

Soru-Cevap Oluşturma iki farklı nesne modeli kullanır:

• QnAMakerClient , bilgi bankasını oluşturma, yönetme, yayımlama ve indirme nesnesidir.
• QnAMakerRuntime, Bilgi bankası GenerateAnswer API'si ile sorgulamak ve Eğitim API'sini kullanarak yeni önerilen sorular göndermek için kullanılan nesnedir (etkin öğrenmenin bir parçası olarak).

QnAMakerClient nesne modeli

Yazma Soru-Cevap Oluşturma istemcisi, anahtarınızı içeren kimlik bilgilerinizi kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerClient nesnesidir.

İstemci oluşturulduktan sonra bilgi bankasını kullanarak bilgi bankası oluşturun, yönetin ve yayımlayın.

JSON nesnesi göndererek bilgi bankası yönetin. Hemen işlemler için bir yöntem genellikle durumu belirten bir JSON nesnesi döndürür. Uzun süre çalışan işlemler için yanıt, işlem kimliğidir. İsteğin durumunu belirlemek için işlem kimliğiyle client.operations.getDetails yöntemini çağırın.

QnAMakerRuntimeClient nesne modeli

Tahmin Soru-Cevap Oluşturma istemcisi, Microsoft kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerRuntimeClient nesnesidir. Yazma istemci çağrısı istemcisinden döndürülen tahmin çalışma zamanı anahtarınızı içeren Rest.ServiceClientCredentials. Bilgi bankası yayımlandıktan sonra EndpointKeys.getKeys.

Kod örnekleri

Bu kod parçacıkları, .NET için Soru-Cevap Oluşturma istemci kitaplığıyla aşağıdakileri nasıl yapacağınızı gösterir:

• Yazma istemcisinin kimliğini doğrulama
• bilgi bankası oluşturma
• Bilgi bankası yükleme
• bilgi bankası indirme
• Bilgi bankası yayımlama
• Bilgi bankasını silme
• Sorgu çalışma zamanı anahtarını alma
• İşlemin durumunu alma
• Sorgu çalışma zamanı istemcisinin kimliğini doğrulama
• bilgi bankası yanıt oluşturma

bilgi bankası yazmak için istemcinin kimliğini doğrulama

Uç noktanız ve anahtarınız ile bir istemci örneği oluşturun. Anahtarınız ile bir ServiceClientCredentials nesnesi oluşturun ve bunu uç noktanızla birlikte kullanarak bir QnAMakerClient nesnesi oluşturun.

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

Bilgi bankası oluşturma

bilgi bankası, üç kaynaktan CreateKbDTO nesnesi için soru ve yanıt çiftlerini depolar:

• Editoryal içerik için QnADTO nesnesini kullanın.
  • Meta verileri ve izleme istemlerini kullanmak için editoryal bağlamı kullanın çünkü bu veriler tek tek Soru-Cevap çifti düzeyinde eklenir.
• Dosyalar için FileDTO nesnesini kullanın. FileDTO, dosyaya ulaşmak için dosya adını ve genel URL'yi içerir.
• URL'ler için, genel kullanıma açık URL'leri temsil eden bir dize listesi kullanın.

Oluşturma adımı, bilgi bankasının özelliklerini de içerir:

• defaultAnswerUsedForExtraction - yanıt bulunamazsa ne döndürülür?
• enableHierarchicalExtraction - ayıklanan Soru-Cevap çiftleri arasında otomatik olarak istem ilişkileri oluşturma
• language - Bir kaynağın ilk bilgi bankasını oluştururken, Azure Search dizininde kullanılacak dili ayarlayın.

bilgi bankası bilgileriyle create yöntemini çağırın. bilgi bankası bilgileri temel olarak bir JSON nesnesidir.

Oluşturma yöntemi döndürdüğünde, durum yoklaması için döndürülen işlem kimliğini wait_for_operation yöntemine geçirin. wait_for_operation yöntemi, işlem tamamlandığında döndürür. Yeni bilgi bankası kimliğini almak için döndürülen işlemin üst bilgi değerini ayrıştırınresourceLocation.

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

Bir bilgi bankası başarıyla oluşturmak için yukarıdaki kodda başvuruda bulunılan işlevini eklediğinizden wait_for_operation emin olun.

Bilgi bankası güncelleştirme

bilgi bankası güncelleştirme yöntemine ekleme,güncelleştirme ve silme nesnelerini içeren bilgi bankası Kimliği ve UpdateKbOperationDTO geçirerek güncelleştirebilirsiniz. DTO'lar da temel olarak JSON nesneleridir. Güncelleştirmenin başarılı olup olmadığını belirlemek için wait_for_operation yöntemini kullanın.

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
}

bir bilgi bankası başarıyla güncelleştirmek için yukarıdaki kodda başvuruda bulunarak işlevini dahil wait_for_operation edin öğesinin olduğundan emin olun.

bilgi bankası indirme

Veritabanını QnADocumentsDTO listesi olarak indirmek için indirme yöntemini kullanın. Bu yöntemin sonucu bir TSV dosyası olmadığından bu, Soru-Cevap Oluşturma portalının Ayarlar sayfasından dışarı aktarma işlemiyle eşdeğer değildir.

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
}

Bilgi bankası yayımlama

publish yöntemini kullanarak bilgi bankası yayımlayın. Bu, bilgi bankası kimliği tarafından başvuruda bulunarak geçerli kaydedilmiş ve eğitilmiş modeli alır ve bunu bir uç noktada yayımlar. Yayımlamanın başarılı olduğunu doğrulamak için HTTP yanıt kodunu denetleyin.

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
}

Bilgi bankasına sorgu yapma

Sorgu çalışma zamanı anahtarını alma

Bir bilgi bankası yayımlandıktan sonra, çalışma zamanını sorgulamak için sorgu çalışma zamanı anahtarına ihtiyacınız olur. Bu, özgün istemci nesnesini oluşturmak için kullanılan anahtarla aynı değildir.

EndpointKeysDTO sınıfını almak için EndpointKeys.getKeys yöntemini kullanın.

Bilgi bankasını sorgulamak için nesnesinde döndürülen anahtar özelliklerden birini kullanın.

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
}

Yanıt oluşturmak için çalışma zamanının kimliğini doğrulama

Yanıt oluşturmak veya etkin öğrenmeden eğitim almak için bilgi bankası sorgulamak için bir QnAMakerRuntimeClient oluşturun.

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

QnAMakerRuntimeClient'ı kullanarak bilgiden bir yanıt alın veya etkin öğrenme için bilgi bankası yeni önerilen sorular gönderin.

bilgi bankası yanıt oluşturma

RuntimeClient.runtime.generateAnswer yöntemini kullanarak yayımlanmış bir bilgi bankası yanıt oluşturun. Bu yöntem bilgi bankası Kimliğini ve QueryDTO'yu kabul eder. Sohbet botunuzda kullanmak üzere QueryDTO'nun Top ve Context gibi ek özelliklerine erişin.

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

}

Bu, bilgi bankası sorgulayan basit bir örnektir. Gelişmiş sorgu senaryolarını anlamak için diğer sorgu örneklerini gözden geçirin.

Bilgi bankasını silme

bilgi bankası kimliği parametresiyle delete yöntemini kullanarak bilgi bankası silin.

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
}

İşlemin durumunu alma

Oluşturma ve güncelleştirme gibi bazı yöntemler, işlemin bitmesi yerine bir işlemin döndürülmesi için yeterli zaman alabilir. Özgün yöntemin durumunu belirlemek üzere yoklama (yeniden deneme mantığıyla) için işlemden işlem kimliğini kullanın.

Yeniden deneme mantığının benzetimini yapmak için aşağıdaki kod bloğundaki delayTimer çağrısı kullanılır. Bunu kendi yeniden deneme mantığınızla değiştirin.

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

Uygulamayı çalıştırma

Uygulamayı uygulama dizininizden komutuyla node index.js çalıştırın.

node index.js

Bu örneğin kaynak kodu GitHub'da bulunabilir.

Python için Soru-Cevap Oluşturma istemci kitaplığını kullanarak:

• Bilgi bankası oluşturma
• Bilgi bankalarını güncelleştirme
• Bilgi bankası yayımlama
• Tahmin çalışma zamanı uç noktası anahtarını alma
• Uzun süre çalışan görevi bekleyin
• Bilgi bankası indirme
• Bilgi bankasından yanıt alma
• bilgi bankası silme

Başvuru belgeleri | Kitaplık kaynak kodu | Paket (PyPi) | Python örnekleri

Not

1 Temmuz 2019'da oluşturulan yeni kaynaklar özel alt etki alanı adlarını kullanır. Daha fazla bilgi ve bölgesel uç noktaların tam listesi için bkz. Bilişsel Hizmetler için özel alt etki alanı adları.

Ön koşullar

Not

Bu belgeler en son sürüm için geçerli değildir. Python API'sini en son sürümle kullanma hakkında bilgi edinmek için Python hızlı başlangıcını yanıtlama sorusuna başvurun.

• Azure aboneliği - Ücretsiz bir abonelik oluşturun
• Python 3.x
• Azure aboneliğinizi aldıktan sonra yazma anahtarınızı ve uç noktanızı almak için Azure portal bir Soru-Cevap Oluşturma kaynağı oluşturun. Dağıtıldıktan sonra Kaynağa git'i seçin.
  • Uygulamanızı Soru-Cevap Oluşturma API'sine bağlamak için oluşturduğunuz kaynaktan anahtara ve uç noktaya ihtiyacınız olacaktır. Anahtarınızı ve uç noktanızı hızlı başlangıcın ilerleyen bölümlerinde aşağıdaki koda yapıştıracaksınız.
  • Ücretsiz fiyatlandırma katmanını (F0) kullanarak hizmeti deneyebilir ve daha sonra üretim için ücretli bir katmana yükseltebilirsiniz.

Ayarlama

İstemci kitaplığını yükleme

Python'ı yükledikten sonra istemci kitaplığını şu şekilde yükleyebilirsiniz:

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

Yeni Python uygulaması oluşturma

adlı quickstart-file.py yeni bir Python dosyası oluşturun ve aşağıdaki kitaplıkları içeri aktarın.

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

Kaynağınızın Azure uç noktası ve anahtarı için değişkenler oluşturun.

• Abonelik anahtarını ve yazma anahtarını birbirinin yerine kullanırız. Anahtar yazma hakkında daha fazla ayrıntı için Soru-Cevap Oluşturma'da Anahtarlar'ı izleyin.

• QNA_MAKER_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Azure portal gidin ve önkoşullarda oluşturduğunuz Soru-Cevap Oluşturma kaynağını bulun. Yazma (Abonelik) anahtarını ve Soru-Cevap Oluşturma Uç Noktasını bulmak için kaynak yönetimi altında Anahtarlar ve Uç Nokta sayfasını seçin.

• QNA_MAKER_RUNTIME_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.azurewebsites.net. Azure portal gidin ve önkoşullarda oluşturduğunuz Soru-Cevap Oluşturma kaynağını bulun. Çalışma Zamanı Uç Noktasını bulmak için Otomasyon'un altındaki Şablonu Dışarı Aktar sayfasını seçin.

Önemli

İşiniz bittiğinde anahtarı kodunuzdan kaldırmayı unutmayın ve asla herkese açık olarak göndermeyin. Üretim için Azure Key Vault gibi kimlik bilgilerinizi depolamanın ve bunlara erişmenin güvenli bir yolunu kullanın. Daha fazla bilgi için Bilişsel Hizmetler güvenlik makalesine bakın.

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'

Nesne modelleri

Soru-Cevap Oluşturma iki farklı nesne modeli kullanır:

• QnAMakerClient , bilgi bankasını oluşturma, yönetme, yayımlama ve indirme nesnesidir.
• QnAMakerRuntime, GenerateAnswer API'siyle bilgi bankası sorgulama ve EğitME API'sini kullanarak yeni önerilen sorular gönderme nesnesidir (etkin öğrenmenin bir parçası olarak).

Bu örneği bilgi bankası kullanma

Bu hızlı başlangıçtaki bilgi bankası 2 konuşma Soru-Cevap çiftiyle başlar. Bu, örneği basitleştirmek ve Güncelleştirme yönteminde kullanılacak yüksek oranda öngörülebilir kimliklere sahip olmak ve izleme istemlerini yeni çiftlerle ilişkilendirmek amacıyla gerçekleştirilir. Bu, bu hızlı başlangıç için belirli bir sırada planlandı ve uygulandı.

Zaman içinde mevcut Soru-Cevap çiftlerine bağımlı olan izleme istemleriyle bilgi bankası geliştirmeyi planlıyorsanız şunları seçebilirsiniz:

• Daha büyük bilgi bankaları için, otomasyonu destekleyen bir metin düzenleyicisinde veya TSV aracında bilgi bankası yönetin, ardından bilgi bankası bir güncelleştirmeyle aynı anda tamamen değiştirin.
• Daha küçük bilgi bankaları için soru-cevap oluşturma portalında izleme istemlerini tamamen yönetin.

Bu hızlı başlangıçta kullanılan Soru-Cevap çiftleri hakkındaki ayrıntılar:

• Soru-Cevap çifti türleri - güncelleştirmeden sonra bu bilgi bankası 2 soru-cevap çifti türü vardır: chitchat ve etki alanına özgü bilgiler. Bilgi bankanız sohbet botu gibi bir konuşma uygulamasına bağlıysa bu durum tipik bir durumdur.
• Bilgi bankası yanıtları meta verilere göre filtrelenebilir veya izleme istemleri kullanılabilir, ancak bu hızlı başlangıçta bu gösterilmez. Bu language-agnostic generateAnswer örneklerini burada bulabilirsiniz.
• Yanıt metni markdown'dır ve görüntüler (genel kullanıma açık internet tabanlı resimler), bağlantılar (genel kullanıma açık URL'ler) ve madde işaretleri gibi çok çeşitli markdown içerebilir. Bu hızlı başlangıçta bu çeşitlilik kullanılmamaktadır.

QnAMakerClient nesne modeli

Yazma Soru-Cevap Oluşturma istemcisi, Microsoft kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerClient nesnesidir. Anahtarınızı içeren Rest.ServiceClientCredentials.

İstemci oluşturulduktan sonra bilgi bankası özelliğini kullanarak bilgi bankası oluşturun, yönetin ve yayımlayın.

JSON nesnesi göndererek bilgi bankası yönetin. Hemen işlemler için bir yöntem genellikle durumu belirten bir JSON nesnesi döndürür. Uzun süre çalışan işlemler için yanıt işlem kimliğidir. İsteğin durumunu belirlemek için işlem kimliğiyle operations.get_details yöntemini çağırın.

QnAMakerRuntimeClient nesne modeli

Tahmin Soru-Cevap Oluşturma istemcisi, Microsoft kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerRuntimeClient nesnedir. Yazma istemci çağrısından döndürülen tahmin çalışma zamanı anahtarınızı içeren Rest.ServiceClientCredentials. bilgi bankası yayımlandıktan sonra EndpointKeysOperations.get_keys.

Sorgu çalışma zamanından generate_answer yanıt almak için yöntemini kullanın.

bilgi bankası yazmak için istemcinin kimliğini doğrulama

Uç noktanız ve anahtarınız ile bir istemci örneği oluşturun. Anahtarınız ile bir CognitiveServicesCredentials nesnesi oluşturun ve bunu uç noktanızla birlikte kullanarak bir QnAMakerClient nesnesi oluşturun.

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

Bilgi bankası oluşturma

bir bilgi bankası işlemleri nesnesi almak için istemci nesnesini kullanın.

bilgi bankası, üç kaynaktan CreateKbDTO nesnesi için soru ve yanıt çiftlerini depolar:

• Editoryal içerik için QnADTO nesnesini kullanın.
  • Meta verileri ve izleme istemlerini kullanmak için editoryal bağlamı kullanın çünkü bu veriler tek tek Soru-Cevap çifti düzeyinde eklenir.
• Dosyalar için FileDTO nesnesini kullanın. FileDTO dosya adını ve dosyaya ulaşmak için genel URL'yi içerir.
• URL'ler için, genel kullanıma açık URL'leri temsil eden bir dize listesi kullanın.

Create yöntemini çağırın ve ardından durum yoklaması için döndürülen işlem kimliğini Operations.getDetails yöntemine geçirin.

Aşağıdaki kodun son satırı, MonitorOperation yanıtından bilgi bankası kimliğini döndürür.

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

Başarılı bir şekilde bir bilgi bankası oluşturmak için yukarıdaki kodda başvuruda bulunarak işlevini dahil _monitor_operation edin.

Bilgi bankası güncelleştirme

bilgi bankası güncelleştirmek için bilgi bankası kimliğini ve güncelleştirme yöntemineekleme,güncelleştirme ve silme DTO nesnelerini içeren bir UpdateKbOperationDTO geçirebilirsiniz. Güncelleştirmenin başarılı olup olmadığını belirlemek için Operation.getDetail yöntemini kullanın.

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

bir bilgi bankası başarıyla güncelleştirmek için yukarıdaki kodda başvuruda bulunarak işlevini dahil _monitor_operation edin.

bilgi bankası indirme

Veritabanını QnADocumentsDTO listesi olarak indirmek için indirme yöntemini kullanın. Bu yöntemin sonucu bir TSV dosyası olmadığından bu, Soru-Cevap Oluşturma portalının Ayarlar sayfasından dışarı aktarma işlemiyle eşdeğer değildir.

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

Bilgi bankası yayımlama

publish yöntemini kullanarak bilgi bankası yayımlayın. Bu, bilgi bankası kimliği tarafından başvuruda bulunılan geçerli kaydedilmiş ve eğitilmiş modeli alır ve bunu bir uç noktada yayımlar.

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

Bilgi bankasına sorgu yapma

Sorgu çalışma zamanı anahtarını alma

Bir bilgi bankası yayımlandıktan sonra, çalışma zamanını sorgulamak için sorgu çalışma zamanı anahtarına ihtiyacınız olur. Bu, özgün istemci nesnesini oluşturmak için kullanılan anahtarla aynı değildir.

EndpointKeysDTO sınıfını almak için EndpointKeysOperations.get_keys yöntemini kullanın.

Bilgi bankasını sorgulamak için nesnesinde döndürülen anahtar özelliklerden birini kullanın.

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

Yanıt oluşturmak için çalışma zamanının kimliğini doğrulama

Yanıt oluşturmak veya etkin öğrenmeden eğitmek için bilgi bankası sorgulamak için bir QnAMakerRuntimeClient oluşturun.

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

QnAMakerRuntimeClient'ı kullanarak bilgiden bir yanıt alın veya etkin öğrenme için bilgi bankası yeni önerilen sorular gönderin.

bilgi bankası yanıt oluşturma

QnAMakerRuntimeClient.runtime.generate_answer yöntemini kullanarak yayımlanmış bir bilgi bankası yanıt oluşturun. Bu yöntem bilgi bankası Kimliğini ve QueryDTO'yu kabul eder. Sohbet botunuzda kullanmak üzere QueryDTO'nun Top ve Context gibi ek özelliklerine erişin.

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

Bu, bilgi bankası sorgulamanın basit bir örneğidir. Gelişmiş sorgu senaryolarını anlamak için diğer sorgu örneklerini gözden geçirin.

Bilgi bankasını silme

bilgi bankası kimliği parametresiyle delete yöntemini kullanarak bilgi bankası silin.

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

İşlemin durumunu alma

Oluşturma ve güncelleştirme gibi bazı yöntemler, işlemin bitmesi yerine bir işlemin döndürülmesi için yeterli zaman alabilir. Özgün yöntemin durumunu belirlemek üzere yoklama (yeniden deneme mantığıyla) için işlemden işlem kimliğini kullanın.

Aşağıdaki kod bloğundaki setTimeout çağrısı, zaman uyumsuz kodun benzetimini yapmak için kullanılır. Bunu yeniden deneme mantığıyla değiştirin.

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

Uygulamayı çalıştırma

Hızlı başlangıç dosyanızda Python komutuyla uygulamayı çalıştırın.

python quickstart-file.py

Bu örneğin kaynak kodu GitHub'da bulunabilir.

Aşağıdakiler için Java için Soru-Cevap Oluşturma istemci kitaplığını kullanın:

• Bilgi bankası oluşturma
• Bilgi bankalarını güncelleştirme
• Bilgi bankası yayımlama
• Tahmin çalışma zamanı uç noktası anahtarını alma
• Uzun süre çalışan görevi bekleyin
• Bilgi bankası indirme
• Bilgi bankasından yanıt alma
• bilgi bankası silme

Kitaplık kaynak kodu | Paket | Örnekleri

Not

1 Temmuz 2019'da oluşturulan yeni kaynaklar özel alt etki alanı adlarını kullanır. Daha fazla bilgi ve bölgesel uç noktaların tam listesi için bkz. Bilişsel Hizmetler için özel alt etki alanı adları.

Ön koşullar

• Azure aboneliği - Ücretsiz bir abonelik oluşturun
• JDK
• Azure aboneliğinizi aldıktan sonra yazma anahtarınızı ve uç noktanızı almak için Azure portal bir Soru-Cevap Oluşturma kaynağı oluşturun. Dağıtıldıktan sonra Kaynağa git'i seçin.
  • Uygulamanızı Soru-Cevap Oluşturma API'sine bağlamak için oluşturduğunuz kaynaktan anahtara ve uç noktaya ihtiyacınız olacaktır. Anahtarınızı ve uç noktanızı hızlı başlangıcın ilerleyen bölümlerinde aşağıdaki koda yapıştırın.
  • Ücretsiz fiyatlandırma katmanını (F0) kullanarak hizmeti deneyebilir ve daha sonra üretim için ücretli bir katmana yükseltebilirsiniz.

Ayarlama

İstemci kitaplıklarını yükleme

Java'yı yükledikten sonra MVN DeposundanMaven kullanarak istemci kitaplıklarını yükleyebilirsiniz.

Yeni java uygulaması oluşturma

adlı quickstart.java yeni bir dosya oluşturun ve aşağıdaki kitaplıkları içeri aktarın.

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

Kaynağınızın Azure uç noktası ve anahtarı için değişkenler oluşturun.

• Abonelik anahtarını ve yazma anahtarını birbirinin yerine kullanırız. Anahtar yazma hakkında daha fazla ayrıntı için Soru-Cevap Oluşturma'da Anahtarlar'ı izleyin.

• QNA_MAKER_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Azure portal gidin ve önkoşullarda oluşturduğunuz Soru-Cevap Oluşturma kaynağını bulun. Yazma (Abonelik) anahtarını ve Soru-Cevap Oluşturma Uç Noktasını bulmak için kaynak yönetimi altında Anahtarlar ve Uç Nokta sayfasını seçin.

• QNA_MAKER_RUNTIME_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.azurewebsites.net. Azure portal gidin ve önkoşullarda oluşturduğunuz Soru-Cevap Oluşturma kaynağını bulun. Çalışma Zamanı Uç Noktasını bulmak için Otomasyon'un altındaki Şablonu Dışarı Aktar sayfasını seçin.

Önemli

İşiniz bittiğinde anahtarı kodunuzdan kaldırmayı unutmayın ve asla herkese açık olarak göndermeyin. Üretim için Azure Key Vault gibi kimlik bilgilerinizi depolamanın ve bunlara erişmenin güvenli bir yolunu kullanın. Daha fazla bilgi için Bilişsel Hizmetler güvenlik makalesine bakın.

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

Nesne modelleri

Soru-Cevap Oluşturma iki farklı nesne modeli kullanır:

• QnAMakerClient , bilgi bankasını oluşturma, yönetme, yayımlama ve indirme nesnesidir.
• QnAMakerRuntime, GenerateAnswer API'siyle bilgi bankası sorgulama ve EğitME API'sini kullanarak yeni önerilen sorular gönderme nesnesidir (etkin öğrenmenin bir parçası olarak).

Bu örneği bilgi bankası kullanma

Bu hızlı başlangıçtaki bilgi bankası 2 konuşma Soru-Cevap çiftiyle başlar. Bu, örneği basitleştirmek ve Güncelleştirme yönteminde kullanılacak yüksek oranda öngörülebilir kimliklere sahip olmak ve izleme istemlerini yeni çiftlerle ilişkilendirmek amacıyla gerçekleştirilir. Bu, bu hızlı başlangıç için belirli bir sırada planlandı ve uygulandı.

Zaman içinde mevcut Soru-Cevap çiftlerine bağımlı olan izleme istemleriyle bilgi bankası geliştirmeyi planlıyorsanız şunları seçebilirsiniz:

• Daha büyük bilgi bankaları için, otomasyonu destekleyen bir metin düzenleyicisinde veya TSV aracında bilgi bankası yönetin, ardından bilgi bankası bir güncelleştirmeyle aynı anda tamamen değiştirin.
• Daha küçük bilgi bankaları için soru-cevap oluşturma portalında izleme istemlerini tamamen yönetin.

Bu hızlı başlangıçta kullanılan Soru-Cevap çiftleri hakkındaki ayrıntılar:

• Soru-Cevap çifti türleri - güncelleştirmeden sonra bu bilgi bankası 2 soru-cevap çifti türü vardır: chitchat ve etki alanına özgü bilgiler. Bilgi bankanız sohbet botu gibi bir konuşma uygulamasına bağlıysa bu durum tipik bir durumdur.
• Bilgi bankası yanıtları meta verilere göre filtrelenebilir veya izleme istemleri kullanılabilir, ancak bu hızlı başlangıçta bu gösterilmez. Bu language-agnostic generateAnswer örneklerini burada bulabilirsiniz.
• Yanıt metni markdown'dır ve görüntüler (genel kullanıma açık internet tabanlı resimler), bağlantılar (genel kullanıma açık URL'ler) ve madde işaretleri gibi çok çeşitli markdown içerebilir. Bu hızlı başlangıçta bu çeşitlilik kullanılmamaktadır.

QnAMakerClient nesne modeli

Yazma Soru-Cevap Oluşturma istemcisi, anahtarınızı içeren MsRest::ServiceClientCredentials kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerClient nesnesidir.

İstemci oluşturulduktan sonra, bilgi bankası oluşturmak, yönetmek ve yayımlamak için istemcinin Knowledgebases özelliğinin yöntemlerini kullanın.

Hemen işlemler için bir yöntem genellikle varsa sonucu döndürür. Uzun süre çalışan işlemler için yanıt bir operation nesnesidir. İsteğin durumunu belirlemek için getDetails yöntemini değeriyle operation.operationId çağırın.

QnAMakerRuntimeClient nesne modeli

Çalışma zamanı Soru-Cevap Oluşturma istemcisi bir QnAMakerRuntimeClient nesnesidir.

yazma istemcisini kullanarak bilgi bankası yayımladıktan sonra, bilgi bankası yanıt almak için çalışma zamanı istemcisinin generateAnswer yöntemini kullanın.

QnAMakerRuntimeManager.authenticate çağrısı yaparak ve bir çalışma zamanı uç noktası anahtarı geçirerek bir çalışma zamanı istemcisi oluşturursunuz. Çalışma zamanı uç noktası anahtarını almak için yazma istemcisini kullanarak getKeys'i çağırın.

bilgi bankası yazmak için istemcinin kimliğini doğrulama

Yazma uç noktanız ve abonelik anahtarınız ile bir istemci örneği oluşturun.

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

Bilgi bankası oluşturma

bilgi bankası, üç kaynaktan CreateKbDTO nesnesi için soru ve yanıt çiftlerini depolar:

• Editoryal içerik için QnADTO nesnesini kullanın.
  • Meta verileri ve izleme istemlerini kullanmak için editoryal bağlamı kullanın çünkü bu veriler tek tek Soru-Cevap çifti düzeyinde eklenir.
• Dosyalar için FileDTO nesnesini kullanın. FileDTO, dosyaya ulaşmak için dosya adını ve genel URL'yi içerir.
• URL'ler için, genel kullanıma açık URL'leri temsil eden bir dize listesi kullanın.

Create yöntemini çağırın ve ardından durum yoklaması için döndürülen işlemin özelliğini getDetails yöntemine geçirinoperationId.

Aşağıdaki kodun son satırı bilgi bankası kimliğini döndürür.

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

Bilgi bankası güncelleştirme

Update'i çağırıp bilgi bankası Kimliğini ve UpdateKbOperationDTO nesnesini geçirerek bir bilgi bankası güncelleştirebilirsiniz. Bu nesne de şunları içerebilir:

• add
• update
• delete

operationId Durum yoklaması yapmak için döndürülen işlemin özelliğini getDetails yöntemine geçirin.

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

bilgi bankası indirme

Veritabanını QnADocumentsDTO listesi olarak indirmek için indirme yöntemini kullanın. Bu yöntemin sonucu bir TSV dosyası olmadığından bu, Soru-Cevap Oluşturma portalının Ayarlar sayfasından dışarı aktarma işlemiyle eşdeğer değildir.

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

Bilgi bankası yayımlama

publish yöntemini kullanarak bilgi bankası yayımlayın. Bu, bilgi bankası kimliği tarafından başvuruda bulunarak geçerli kaydedilmiş ve eğitilmiş modeli alır ve bunu bir uç noktada yayımlar.

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

bilgi bankası yanıt oluşturma

bir bilgi bankası yayımlandıktan sonra, bilgi bankası sorgulamak için çalışma zamanı uç noktası anahtarına ihtiyacınız vardır. Bu, yazma istemcisini oluşturmak için kullanılan abonelik anahtarıyla aynı değildir.

Bir EndpointKeysDTO nesnesi almak için getKeys yöntemini kullanın.

QnAMakerRuntimeManager.authenticate çağrısı yaparak ve EndpointKeysDTO nesnesinden bir çalışma zamanı uç noktası anahtarı geçirerek bir çalışma zamanı istemcisi oluşturun.

generateAnswer yöntemini kullanarak yayımlanmış bir bilgi bankası yanıt oluşturun. Bu yöntem bilgi bankası kimliğini ve QueryDTO nesnesini kabul eder.

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

Bu, bir bilgi bankası sorgulamanın basit bir örneğidir. Gelişmiş sorgu senaryolarını anlamak için diğer sorgu örneklerini gözden geçirin.

Bilgi bankasını silme

bilgi bankası kimliği parametresiyle delete yöntemini kullanarak bilgi bankası silin.

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

İşlemin durumunu alma

Oluşturma ve güncelleştirme gibi bazı yöntemler, işlemin bitmesi yerine bir işlemin döndürülmesi için yeterli zaman alabilir. özgün yöntemin durumunu belirlemek üzere yoklama (yeniden deneme mantığıyla) için işlemden işlem kimliğini kullanı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;
}

Uygulamayı çalıştırma

Uygulamanın ana yöntemi aşağıdadır.

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

Uygulamayı aşağıdaki gibi çalıştırın. Bu, sınıf adınızın olduğunu Quickstart ve bağımlılıklarınızın geçerli klasörün altında adlı lib bir alt klasörde olduğunu varsayır.

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

Bu örneğin kaynak kodu GitHub'da bulunabilir.

Kaynakları temizleme

Bilişsel Hizmetler aboneliğini temizlemek ve kaldırmak istiyorsanız, kaynağı veya kaynak grubunu silebilirsiniz. Kaynak grubunun silinmesi, kaynak grubuyla ilişkili diğer tüm kaynakları da siler.

• Portal
• Azure CLI

Sonraki adımlar

Öğretici: Bilgi bankası toplu iş dosyasıyla test edin

• Soru-Cevap Oluşturma API'si nedir?
• Bilgi bankası düzenleme
• Kullanım analizi alma