Share via

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

  • Makale

Not

Verilerinizde Azure Open AI, Soru-Cevap Oluşturma'ya benzer sonuçlar elde etmek için büyük dil modellerinden (LLM) yararlanır. Soru-Cevap Oluşturma projenizi Azure Open AI On Your Data'ya geçirmek istiyorsanız lütfen kılavuzumuzu inceleyin.

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

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 Azure AI Dili'nin 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. Mevcut Soru-Cevap Oluşturma bilgi bankası soru yanıtlamaya geçirme hakkında bilgi için geçiş kılavuzuna bakın.

Önkoş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 başvurun

  • 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ında 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 devamlılığı karakteri kullanılır \ . Konsol veya terminal farklı bir satır devamlılığı 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:

Bilgiler cURL yapılandırması Purpose
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ı yapma
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 ve JSON değerlerinizle ve JSON boyutuyla 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/ai-services/qnamaker/faqs"]}'

Soru-Cevap Oluşturma'dan gelen cURL yanıtı, operationId işlemin durumunu almak için gereken değerini 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 belirlemek için bilgi içerir.

Bilgiler cURL yapılandırması Purpose
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ı yapma

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.

Bilgiler cURL yapılandırması Purpose
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ı yapma
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 bankası için aynı anahtardır.

Bilgiler cURL yapılandırması Purpose
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ı yapma

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 sorgusu

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

Bilgiler cURL yapılandırması Purpose
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ı yapma
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.

Bilgiler cURL yapılandırması Purpose
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ı yapma
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

.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 bekleme
  • Bilgi bankası indirme
  • Bilgi bankasından yanıt alma
  • Bilgi bankalarını silme

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

Not

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

Önkoş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 olarak 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ında 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.
    • Hizmeti denemek ve daha sonra üretim için ücretli bir katmana yükseltmek için ücretsiz fiyatlandırma katmanını (F0) kullanabilirsiniz.

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 dosyayla 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 komutla .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

Tüm hızlı başlangıç kodunu aynı anda görüntülemek mi istiyorsunuz? Bunu, 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 bilgi 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ına 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.

Soru-Cevap Oluşturma Yazma Uç Noktası

  • QNA_MAKER_RUNTIME_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.azurewebsites.net. Azure portalına 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.

Soru-Cevap Oluşturma Çalışma Zamanı Uç Noktası

Ö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 Azure AI hizmetleri 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ğit API'sini kullanarak (etkin öğrenmenin bir parçası olarak) önerilen yeni sorular gönderme nesnesidir.

Bu örnek bilgi bankası kullanma

Bu hızlı başlangıçtaki bilgi bankası 2 konuşma Soru-Cevap çifti ile 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 ilgili sorularla ilişkilendirmek amacıyla gerçekleştirilir. Bu, bu hızlı başlangıç için belirli bir sırada planlandı ve uygulandı.

Mevcut Soru-Cevap çiftlerine bağımlı olan izleme istemleriyle zaman içinde 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 kerede bir güncelleştirmeyle 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: sohbet ve etki alanına özgü bilgiler. Bilgi bankanız sohbet botu gibi bir konuşma uygulamasına bağlıysa bu 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. Burada language-agnostic generateAnswer örneklerini bulabilirsiniz.
  • Yanıt metni markdown'dır ve görüntüler (genel kullanıma açık İnternet tabanlı görüntüler), 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 Microsoft.Rest.ServiceClientCredentials kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerClient nesnesidir.

İ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, 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 Microsoft.Rest.ServiceClientCredentials kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerRuntimeClient nesnesidir.

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:

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

Anahtarınızla bir istemci nesnesi örneği oluşturun ve bunu kaynağınızla birlikte kullanarak uç noktanızı 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, bu veriler tek tek Soru-Cevap çifti düzeyinde eklendiğinden editoryal bağlamı kullanın.
  • 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 göstermek için 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 bulunarak 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 bulunarak 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 bulunarak 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

Bilgi bankası yayımlandıktan sonra, çalışma zamanını sorgulamak için sorgu çalışma zamanı anahtarına ihtiyacınız vardır. 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ı 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. QueryDTO'nun sohbet botunuzda kullanmak üzere 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 için işlemden işlem kimliğini kullanarak yoklama yapın (yeniden deneme mantığıyla).

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 dizininizdeki 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 bekleme
  • Bilgi bankası indirme
  • Bilgi bankasından yanıt alma
  • bilgi bankası silme

Başvuru belgeleri | Paketi (npm) | Node.js Örnekleri

Not

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

Önkoşullar

  • Azure aboneliği - Ücretsiz olarak oluşturun
  • Node.js’nin geçerli sürümü.
  • Azure aboneliğinizi aldıktan sonra, yazma anahtarınızı ve kaynağınızı almak için Azure portalında 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.
    • Hizmeti denemek ve daha sonra üretim için ücretli bir katmana yükseltmek için ücretsiz fiyatlandırma katmanını (F0) kullanabilirsiniz.

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

Bir package.json dosyası ile bir düğüm uygulaması oluşturmak için npm init -y 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 bilgi 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ına 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.

Soru-Cevap Oluşturma Yazma Uç Noktası

  • QNA_MAKER_RUNTIME_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.azurewebsites.net. Azure portalına 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.

Soru-Cevap Oluşturma Çalışma Zamanı Uç Noktası

Ö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 Azure AI hizmetleri 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, GenerateAnswer API'siyle bilgi bankası sorgulama ve Eğit API'sini kullanarak (etkin öğrenmenin bir parçası olarak) önerilen yeni sorular gönderme nesnesidir.

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, yazma istemci çağrısı istemcisinden döndürülen tahmin çalışma zamanı anahtarınızı içeren Microsoft.Rest.ServiceClientCredentials kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerRuntimeClient nesnesidir. 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:

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, bu veriler tek tek Soru-Cevap çifti düzeyinde eklendiğinden editoryal bağlamı kullanın.
  • 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 göstermek için 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 temelde bir JSON nesnesidir.

Oluşturma yöntemi döndürdüğünde, durum yoklaması yapmak 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 bulunarak işlevini eklediğinizden wait_for_operation emin olun.

Bilgi bankası güncelleştirme

bilgi bankası Kimliğini ve güncelleştirme yöntemine DTO nesnelerini ekleme, güncelleştirme ve silme içeren bir UpdateKbOperationDTO geçirerek bir bilgi bankası 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 etme seçeneğinin belirtildiğinden 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

yayımlama yöntemini kullanarak bilgi bankası yayımlayın. Bu, bilgi bankası kimliği tarafından başvuruda bulunarak kaydedilen ve eğitilen geçerli 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

Bilgi bankası yayımlandıktan sonra, çalışma zamanını sorgulamak için sorgu çalışma zamanı anahtarına ihtiyacınız vardır. 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ğitmek 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);

Bilgiden yanıt almak veya etkin öğrenme için bilgi bankası yeni önerilen sorular göndermek için QnAMakerRuntimeClient'ı kullanın.

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. QueryDTO'nun sohbet botunuzda kullanmak üzere 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ı 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 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 için işlemden işlem kimliğini kullanarak yoklama yapın (yeniden deneme mantığıyla).

Aşağıdaki kod bloğundaki delayTimer çağrısı, yeniden deneme mantığının benzetimini yapmak için 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 bekleme
  • Bilgi bankası indirme
  • Bilgi bankasından yanıt alma
  • bilgi bankası silme

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

Not

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

Önkoş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 olarak oluşturun
  • Python 3.x
  • Azure aboneliğinizi aldıktan sonra, yazma anahtarınızı ve uç noktanızı almak için Azure portalında 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.
    • Hizmeti denemek ve daha sonra üretim için ücretli bir katmana yükseltmek için ücretsiz fiyatlandırma katmanını (F0) kullanabilirsiniz.

Ayarlama

İstemci kitaplığını yükleme

Python yükledikten sonra şunları kullanarak istemci kitaplığını 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 bilgi 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ına 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.

Soru-Cevap Oluşturma Yazma Uç Noktası

  • QNA_MAKER_RUNTIME_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.azurewebsites.net. Azure portalına 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.

Soru-Cevap Oluşturma Çalışma Zamanı Uç Noktası

Ö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 Azure AI hizmetleri 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ğit API'sini kullanarak (etkin öğrenmenin bir parçası olarak) önerilen yeni sorular gönderme nesnesidir.

Bu örnek bilgi bankası kullanma

Bu hızlı başlangıçtaki bilgi bankası 2 konuşma Soru-Cevap çifti ile 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 ilgili sorularla ilişkilendirmek amacıyla gerçekleştirilir. Bu, bu hızlı başlangıç için belirli bir sırada planlandı ve uygulandı.

Mevcut Soru-Cevap çiftlerine bağımlı olan izleme istemleriyle zaman içinde 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 kerede bir güncelleştirmeyle 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: sohbet ve etki alanına özgü bilgiler. Bilgi bankanız sohbet botu gibi bir konuşma uygulamasına bağlıysa bu 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. Burada language-agnostic generateAnswer örneklerini bulabilirsiniz.
  • Yanıt metni markdown'dır ve görüntüler (genel kullanıma açık İnternet tabanlı görüntüler), 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 Microsoft.Rest.ServiceClientCredentials kullanarak Azure'da kimlik doğrulaması yapan bir QnAMakerClient nesnesidir.

İ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.rest.ServiceClientCredentials kullanarak Azure'da kimlik doğrulaması yapan ve yazma istemci çağrısından döndürülen tahmin çalışma zamanı anahtarınızı içeren bir QnAMakerRuntimeClient nesnedir. 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, bu veriler tek tek Soru-Cevap çifti düzeyinde eklendiğinden editoryal bağlamı kullanın.
  • 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 göstermek için 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

Bir bilgi bankası başarıyla oluşturmak için yukarıdaki kodda başvuruda bulunarak işlevini dahil _monitor_operation etme seçeneğinin belirtildiğinden emin olun.

Bilgi bankası güncelleştirme

bilgi bankası Kimliğini ve güncelleştirme 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 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 etme seçeneğinin belirtildiğinden 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.

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

yayımlama yöntemini kullanarak bilgi bankası yayımlayın. Bu, bilgi bankası kimliği tarafından başvuruda bulunarak kaydedilen ve eğitilen geçerli 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

Bilgi bankası yayımlandıktan sonra, çalışma zamanını sorgulamak için sorgu çalışma zamanı anahtarına ihtiyacınız vardır. 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))

Bilgiden yanıt almak veya etkin öğrenme için bilgi bankası yeni önerilen sorular göndermek için QnAMakerRuntimeClient'ı kullanın.

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. QueryDTO'nun sohbet botunuzda kullanmak üzere 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 için işlemden işlem kimliğini kullanarak yoklama yapın (yeniden deneme mantığıyla).

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.

Java 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 bekleme
  • 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ı kullanacaktır. Daha fazla bilgi ve bölgesel uç noktaların tam listesi için bkz . Azure AI hizmetleri için özel alt etki alanı adları.

Önkoşullar

  • Azure aboneliği - Ücretsiz olarak oluşturun
  • JDK
  • Azure aboneliğinizi aldıktan sonra, yazma anahtarınızı ve uç noktanızı almak için Azure portalında 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.
    • Hizmeti denemek ve daha sonra üretim için ücretli bir katmana yükseltmek için ücretsiz fiyatlandırma katmanını (F0) kullanabilirsiniz.

Ayarlama

İstemci kitaplıklarını yükleme

Java'yı yükledikten sonra MVN Deposundan Maven 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 bilgi 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ına 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.

Soru-Cevap Oluşturma Yazma Uç Noktası

  • QNA_MAKER_RUNTIME_ENDPOINT değeri biçimindedir https://YOUR-RESOURCE-NAME.azurewebsites.net. Azure portalına 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.

Soru-Cevap Oluşturma Çalışma Zamanı Uç Noktası

Ö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 Azure AI hizmetleri 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ğit API'sini kullanarak (etkin öğrenmenin bir parçası olarak) önerilen yeni sorular gönderme nesnesidir.

Bu örnek bilgi bankası kullanma

Bu hızlı başlangıçtaki bilgi bankası 2 konuşma Soru-Cevap çifti ile 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 ilgili sorularla ilişkilendirmek amacıyla gerçekleştirilir. Bu, bu hızlı başlangıç için belirli bir sırada planlandı ve uygulandı.

Mevcut Soru-Cevap çiftlerine bağımlı olan izleme istemleriyle zaman içinde 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 kerede bir güncelleştirmeyle 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: sohbet ve etki alanına özgü bilgiler. Bilgi bankanız sohbet botu gibi bir konuşma uygulamasına bağlıysa bu 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. Burada language-agnostic generateAnswer örneklerini bulabilirsiniz.
  • Yanıt metni markdown'dır ve görüntüler (genel kullanıma açık İnternet tabanlı görüntüler), 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ı bir 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, bu veriler tek tek Soru-Cevap çifti düzeyinde eklendiğinden editoryal bağlamı kullanın.
  • 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 göstermek için bir dize listesi kullanın.

Create yöntemini çağırın ve ardından döndürülen işlemin özelliğini getDetails yöntemine geçirerek operationId durumu yoklayın.

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

Bir bilgi bankası güncelleştirmek için güncelleştirmeyi çağırabilir ve bilgi bankası Kimliğini ve UpdateKbOperationDTO nesnesini geçirebilirsiniz. Bu nesne de şu içeriği içerebilir:

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

yayımlama yöntemini kullanarak bilgi bankası yayımlayın. Bu, bilgi bankası kimliği tarafından başvuruda bulunarak kaydedilen ve eğitilen geçerli 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ç nokta 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 için işlemden işlem kimliğini kullanarak yoklama yapın (yeniden deneme mantığıyla).

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

Azure AI hizmetleri 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.

Sonraki adımlar

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