빠른 시작: QnA Maker 클라이언트 라이브러리
QnA Maker 클라이언트 라이브러리를 시작합니다. 이러한 단계에 따라 패키지를 설치하고 기본 작업을 위한 예제 코드를 사용해 봅니다.
참고 항목
QnA Maker 서비스가 2025년 3월 31일부로 종료됩니다. 이제 최신 버전의 질문 및 답변 기능이 Azure AI 언어의 일부로 사용할 수 있습니다. 언어 서비스 내의 질문 답변 기능은 질문 답변을 참조하세요. 2022년 10월 1일부터 새로운 QnA Maker 리소스를 만들 수 없습니다. 기존 QnA Maker 기술 자료를 질문 답변으로 마이그레이션하는 방법에 대한 정보는 마이그레이션 가이드를 참조하세요.
필수 조건
참고 항목
이 설명서는 최신 릴리스에는 적용되지 않습니다. 최신 릴리스에서 REST API를 사용하는 방법에 대한 자세한 내용은 REST API 빠른 시작에 대한 답변을 참조합니다.
현재 버전의 cURL. 빠른 시작에는 몇 가지 명령줄 스위치가 사용되며, 이러한 스위치는 cURL 설명서에 나와 있습니다.
키와 리소스 이름을 사용하려면 QnA Maker 리소스가 있어야 합니다. 리소스를 만드는 동안 리소스 이름을 입력한 다음, 키가 생성되었습니다. 리소스 이름은 엔드포인트의 하위 도메인으로 사용됩니다. 키와 리소스 이름을 검색하려면 Azure Portal에서 이 리소스에 대한 빠른 시작을 선택합니다. 리소스 이름은 엔드포인트 URL의 첫 번째 하위 도메인입니다.
https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0
주의
다음 BASH 예제에서는 \ 줄 연속 문자를 사용합니다. 콘솔 또는 터미널에서 다른 줄 연속 문자를 사용하는 경우 이 문자를 사용하세요.
기술 자료 만들기
REST API 및 cURL을 사용하여 기술 자료를 만드는 데 필요한 정보는 다음과 같습니다.
| 정보 | cURL 구성 | 목적 |
|---|---|---|
| QnA Maker 리소스 이름 | URL | URL을 생성하는 데 사용됨 |
| QnA Maker 리소스 키 | Ocp-Apim-Subscription-Key 헤더의 -h 매개 변수 |
QnA Maker 서비스에 인증 |
| 기술 자료를 설명하는 JSON | -d 매개 변수 |
JSON 예제 |
| JSON 크기(바이트 단위) | Content-Size 헤더의 -h 매개 변수 |
cURL 명령은 BASH 셸에서 실행됩니다. 사용자 고유의 리소스 이름, 리소스 키 및 JSON 값과 JSON 크기를 사용하여 이 명령을 편집합니다.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/create \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:107" \
-d '{ name: "QnA Maker FAQ",urls: [ "https://learn.microsoft.com/azure/ai-services/qnamaker/faqs"]}'
QnA Maker의 cURL 응답에는 작업 상태를 가져오는 데 필요한 operationId가 포함됩니다.
{
"operationState": "NotStarted",
"createdTimestamp": "2020-02-27T04:11:22Z",
"lastActionTimestamp": "2020-02-27T04:11:22Z",
"userId": "9596077b3e0441eb93d5080d6a15c64b",
"operationId": "95a4f700-9899-4c98-bda8-5449af9faef8"
}
작업 상태 가져오기
기술 자료를 만드는 경우 비동기 작업이므로 응답에는 상태를 확인하는 정보가 포함됩니다.
| 정보 | cURL 구성 | 목적 |
|---|---|---|
| QnA Maker 리소스 이름 | URL | URL을 생성하는 데 사용됨 |
| 작업 ID | URL 경로 | /operations/REPLACE-WITH-YOUR-OPERATION-ID |
| QnA Maker 리소스 키 | Ocp-Apim-Subscription-Key 헤더의 -h 매개 변수 |
QnA Maker 서비스에 인증 |
cURL 명령은 BASH 셸에서 실행됩니다. 사용자 고유의 리소스 이름, 리소스 키 및 작업 ID를 사용하여 이 명령을 편집합니다.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/operations/REPLACE-WITH-YOUR-OPERATION-ID \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"
cURL 응답에는 상태가 포함됩니다. 작업 상태가 성공인 경우 resourceLocation에 기술 자료 ID가 포함됩니다.
{
"operationState": "Succeeded",
"createdTimestamp": "2020-02-27T04:54:07Z",
"lastActionTimestamp": "2020-02-27T04:54:19Z",
"resourceLocation": "/knowledgebases/fe3971b7-cfaa-41fa-8d9f-6ceb673eb865",
"userId": "f596077b3e0441eb93d5080d6a15c64b",
"operationId": "f293f218-d080-48f0-a766-47993e9b26a8"
}
기술 자료 게시
기술 자료를 쿼리하기 전에 다음을 수행해야 합니다.
- 기술 자료 게시
- 런타임 엔드포인트 키 가져오기
이 작업은 기술 자료를 게시합니다. 런타임 엔드포인트 키를 가져오는 작업은 별도의 작업입니다.
| 정보 | cURL 구성 | 목적 |
|---|---|---|
| QnA Maker 리소스 이름 | URL | URL을 생성하는 데 사용됨 |
| QnA Maker 리소스 키 | Ocp-Apim-Subscription-Key 헤더의 -h 매개 변수 |
QnA Maker 서비스에 인증 |
| 기술 자료 ID | URL 경로 | /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID |
cURL 명령은 BASH 셸에서 실행됩니다. 리소스 이름, 리소스 키 및 기술 자료 ID를 사용하여 이 명령을 편집합니다.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-v \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
--data-raw ''
응답 상태는 204이며 결과가 없습니다. cURL 명령에 대한 자세한 정보 출력을 확인하려면 -v 명령줄 매개 변수를 사용합니다. 여기에는 HTTP 상태가 포함됩니다.
게시된 기술 자료의 런타임 엔드포인트 키 가져오기
기술 자료를 쿼리하기 전에 다음을 수행해야 합니다.
- 기술 자료 게시
- 런타임 엔드포인트 키 가져오기
이 작업은 런타임 엔드포인트 키를 가져옵니다. 기술 자료를 게시하는 작업은 별도의 작업입니다.
런타임 엔드포인트 키는 QnA Maker 리소스를 사용하는 모든 기술 자료의 키와 동일합니다.
| 정보 | cURL 구성 | 목적 |
|---|---|---|
| QnA Maker 리소스 이름 | URL | URL을 생성하는 데 사용됨 |
| QnA Maker 리소스 키 | Ocp-Apim-Subscription-Key 헤더의 -h 매개 변수 |
QnA Maker 서비스에 인증 |
cURL 명령은 BASH 셸에서 실행됩니다. 사용자 고유의 리소스 이름과 리소스 키를 사용하여 이 명령을 편집합니다.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/endpointkeys \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"
cURL 응답에는 런타임 엔드포인트 키가 포함됩니다. 기술 자료에서 답변을 얻으려면 쿼리할 때 키 중 하나만 사용합니다.
{
"primaryEndpointKey": "93e88a14-694a-44d5-883b-184a68aa8530",
"secondaryEndpointKey": "92c98c16-ca31-4294-8626-6c57454a5063",
"installedVersion": "4.0.5",
"lastStableVersion": "4.0.6"
}
게시된 기술 자료의 답변에 대한 쿼리
기술 자료의 답변을 얻는 것은 기술 자료를 관리하는 것과 다른 별도의 런타임에서 수행됩니다. 별도의 런타임이므로 런타임 키를 사용하여 인증해야 합니다.
| 정보 | cURL 구성 | 목적 |
|---|---|---|
| QnA Maker 리소스 이름 | URL | URL을 생성하는 데 사용됨 |
| QnA Maker 런타임 키 | Authorization 헤더의 -h 매개 변수 |
키는 Endpointkey 단어가 포함된 문자열의 일부입니다. QnA Maker 서비스에 인증 |
| 기술 자료 ID | URL 경로 | /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID |
| 쿼리를 설명하는 JSON | -d 매개 변수 |
JSON의 요청 본문 매개 변수 및 예제 |
| JSON 크기(바이트 단위) | Content-Size 헤더의 -h 매개 변수 |
cURL 명령은 BASH 셸에서 실행됩니다. 리소스 이름, 리소스 키 및 기술 자료 ID를 사용하여 이 명령을 편집합니다.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.azurewebsites.net/qnamaker/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID/generateAnswer \
-X POST \
-H "Authorization: EndpointKey REPLACE-WITH-YOUR-RUNTIME-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:159" \
-d '{"question": "How are QnA Maker and LUIS used together?","top": 6,"isTest": true, "scoreThreshold": 20, "strictFilters": [], "userId": "sd53lsY="}'
성공적인 응답에는 클라이언트 애플리케이션(예: 채팅 봇)에서 사용자에게 답변을 표시하는 데 필요한 다른 정보와 함께 상위 답변이 포함됩니다.
기술 자료 삭제
기술 자료를 사용하는 작업이 완료되면 해당 기술 자료를 삭제합니다.
| 정보 | cURL 구성 | 목적 |
|---|---|---|
| QnA Maker 리소스 이름 | URL | URL을 생성하는 데 사용됨 |
| QnA Maker 리소스 키 | Ocp-Apim-Subscription-Key 헤더의 -h 매개 변수 |
QnA Maker 서비스에 인증 |
| 기술 자료 ID | URL 경로 | /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID |
cURL 명령은 BASH 셸에서 실행됩니다. 리소스 이름, 리소스 키 및 기술 자료 ID를 사용하여 이 명령을 편집합니다.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-X DELETE \
-v \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"
응답 상태는 204이며 결과가 없습니다. cURL 명령에 대한 자세한 정보 출력을 확인하려면 -v 명령줄 매개 변수를 사용합니다. 여기에는 HTTP 상태가 포함됩니다.
추가 리소스
- 작성 참조 설명서
- 런타임 참조 설명서
- cURL을 사용하는 BASH 스크립트 샘플
.NET 용 QnA Maker 클라이언트 라이브러리를 사용하여 다음을 수행할 수 있습니다.
- 기술 자료 만들기
- 기술자료 업데이트
- 기술 자료 게시
- 예측 런타임 엔드포인트 키 가져오기
- 장기 실행 작업 대기
- 기술 자료 다운로드
- 기술 자료에서 답변 가져오기
- 기술 자료 삭제
참조 설명서 | 라이브러리 소스 코드 | 패키지(NuGet) | C# 샘플
참고 항목
2019년 7월 1일 이후에 만들어진 새 리소스는 사용자 지정 하위 도메인 이름을 사용합니다. 자세한 내용과 지역 엔드포인트의 전체 목록은 Azure AI 서비스에 대한 사용자 지정 하위 도메인 이름을 참조하세요.
필수 조건
참고 항목
이 설명서는 최신 릴리스에는 적용되지 않습니다. 최신 릴리스에서 C# API를 사용하는 방법에 대한 자세한 내용은 C# 빠른 시작에 대한 답변을 참조합니다.
- Azure 구독 - 체험 구독 만들기
- Visual Studio IDE 또는 현재 버전의 .NET Core.
- Azure 구독을 보유한 후에는 Azure Portal에서 QnA Maker 리소스를 만들어 작성 키와 리소스 이름을 가져옵니다. 배포 후 리소스로 이동을 선택합니다.
- 애플리케이션을 QnA Maker API에 연결하려면 만드는 리소스의 키와 리소스 이름이 필요합니다. 빠른 시작의 뒷부분에서 키와 리소스 이름을 아래 코드에 붙여넣습니다.
- 평가판 가격 책정 계층(
F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.
설정
CLI
콘솔 창(예: cmd, PowerShell 또는 Bash)에서 dotnet new 명령을 사용하여 qna-maker-quickstart라는 새 콘솔 앱을 만듭니다. 이 명령은 program.cs라는 단일 소스 파일을 사용하여 간단한 "Hello World" C# 프로젝트를 만듭니다.
dotnet new console -n qna-maker-quickstart
새로 만든 앱 폴더로 디렉터리를 변경합니다. 다음을 통해 애플리케이션을 빌드할 수 있습니다.
dotnet build
빌드 출력에 경고나 오류가 포함되지 않아야 합니다.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
애플리케이션 디렉터리 내에서 다음 명령을 사용하여 .NET용 QnA Maker 클라이언트 라이브러리를 설치합니다.
dotnet add package Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker --version 2.0.1
팁
한 번에 전체 빠른 시작 코드 파일을 보시겠습니까? GitHub에서 찾을 수 있으며 이 빠른 시작의 코드 예제를 포함합니다.
Using 지시문
프로젝트 디렉터리에서 program.cs 파일을 열고 using 지시문을 추가합니다.
using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker;
using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker.Models;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
구독 키 및 리소스 엔드포인트
애플리케이션의 Main 메서드에서 다음 섹션에 나와 있는 변수와 코드를 추가하여 이 빠른 시작의 일반적인 작업을 사용합니다.
구독 키와 작성 키를 서로 바꿔서 사용합니다. 작성 키에 대한 자세한 내용은 QnA Maker의 키를 참조하세요.
QNA_MAKER_ENDPOINT 값의 형식은
https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com입니다. Azure Portal로 이동하여 필수 구성 요소에서 만든 QnA Maker 리소스를 찾습니다. 리소스 관리에서 키 및 엔드포인트 페이지를 선택하여 작성(구독) 키 및 QnA Maker 엔드포인트를 찾습니다.
- QNA_MAKER_RUNTIME_ENDPOINT 값의 형식은
https://YOUR-RESOURCE-NAME.azurewebsites.net입니다. Azure Portal로 이동하여 필수 구성 요소에서 만든 QnA Maker 리소스를 찾습니다. Automation에서 템플릿 내보내기 페이지를 선택하여 런타임 엔드포인트를 찾습니다.
Important
완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure Key Vault와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은 Azure AI 서비스 보안 문서를 참조하세요.
var authoringKey = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
var authoringURL = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
var queryingURL = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";
개체 모델
QnA Maker는 다음과 같은 두 가지 개체 모델을 사용합니다.
- QnAMakerClient는 기술 자료를 만들고, 관리하고, 게시하고, 다운로드하는 개체입니다.
- QnAMakerRuntime은 GenerateAnswer API를 사용하여 기술 자료를 쿼리하고 Train API(활성 학습의 일부로)를 사용하여 새로 제안된 질문을 보내는 개체입니다.
이 예제 기술 자료 사용
이 빠른 시작의 기술 자료는 2개의 대화형 QnA 쌍으로 시작합니다. 이는 후속 프롬프트를 새로운 쌍에 연결하여 예제를 단순화하고 업데이트 메서드에 사용할 매우 예측 가능한 ID를 갖기 위해 의도적으로 수행됩니다. 이 빠른 시작에 대해 특정 순서로 계획 및 구현되었습니다.
시간이 지남에 따라 기존 QnA 쌍에 종속된 추가 작업 프롬프트를 통해 기술 자료를 개발하려는 경우 다음을 선택할 수 있습니다.
- 더 큰 기술 자료의 경우 자동화를 지원하는 텍스트 편집기나 TSV 도구에서 기술 자료를 관리한 다음, 기술 자료를 한 번에 업데이트로 완전히 대체합니다.
- 더 작은 기술 자료의 경우 QnA Maker 포털에서 후속 프롬프트를 완전히 관리합니다.
이 빠른 시작에 사용되는 QnA 쌍에 대한 세부 정보:
- QnA 쌍 유형 - 이 기술 자료에는 업데이트 후 chitchat 및 도메인별 정보의 2가지 유형의 QnA 쌍이 있습니다. 이는 기술 자료가 챗봇과 같은 대화 애플리케이션에 연결된 경우에 일반적입니다.
- 기술 자료 답변은 메타데이터로 필터링되거나 후속 프롬프트를 사용할 수 있지만, 이 빠른 시작에서는 이를 보여주지 않습니다. 여기에서 언어 제한이 없는 generateAnswer 예제를 찾아보세요.
- 대답 텍스트는 markdown이고 이미지(공개적으로 사용할 수 있는 인터넷 기반 이미지), 링크(공개적으로 사용할 수 있는 URL에 대한 링크) 및 글머리 기호 지점과 같이 다양한 markdown을 포함할 수 있습니다. 이 빠른 시작에서는 해당 다양성을 사용하지 않습니다.
QnAMakerClient 개체 모델
제작 QnA Maker 클라이언트는 키가 포함된 Microsoft.Rest.ServiceClientCredentials를 사용하여 Azure에 인증하는 QnAMakerClient 개체입니다.
클라이언트를 만든 후 기술 자료 속성을 사용하여 기술 자료를 생성, 관리 및 게시합니다.
JSON 개체를 전송하여 기술 자료를 관리합니다. 즉각적인 작업의 경우 메서드는 일반적으로 상태를 나타내는 JSON 개체를 반환합니다. 장기 실행 작업의 경우 응답은 작업 ID입니다. 요청의 상태를 확인하려면 해당 작업 ID와 함께 client.Operations.GetDetailsAsync 메서드를 호출합니다.
QnAMakerRuntimeClient 개체 모델
예측 QnA Maker 클라이언트는 Microsoft.Rest.ServiceClientCredentials를 사용하여 Azure에 인증하는 QnAMakerRuntimeClient 개체입니다. 이 개체는 기술 자료가 게시된 후에 제작 클라이언트 호출(client.EndpointKeys.GetKeys)에서 반환된 예측 런타임 키를 포함합니다.
GenerateAnswer 메서드를 사용하여 쿼리 런타임에서 답변을 가져옵니다.
코드 예제
이 코드 조각은 .NET용 QnA Maker 클라이언트 라이브러리를 사용하여 다음을 수행하는 방법을 보여줍니다.
- 작성 클라이언트 인증
- 기술 자료 만들기
- 기술 자료 업데이트
- 기술 자료 다운로드
- 기술 자료 게시
- 기술 자료 삭제
- 쿼리 런타임 키 가져오기
- 작업의 상태 가져오기
- 쿼리 런타임 클라이언트 인증
- 기술 자료에서 답변 생성
기술 자료 제작을 위한 클라이언트 인증
키를 사용하여 클라이언트 개체를 인스턴스화하고, 이를 리소스와 함께 사용하여 엔드포인트를 구성하고 엔드포인트 및 키를 사용하여 QnAMakerClient를 만듭니다. ServiceClientCredentials 개체를 만듭니다.
var client = new QnAMakerClient(new ApiKeyServiceClientCredentials(authoringKey))
{ Endpoint = authoringURL };
기술 자료 만들기
기술 자료에는 다음 세 개의 원본에서 CreateKbDTO 개체에 대한 질문 및 답변 쌍이 저장됩니다.
- 편집 콘텐츠의 경우 QnADTO 개체를 사용합니다.
- 메타데이터 및 후속 프롬프트를 사용하려면 이 데이터가 개별 QnA 쌍 수준에 추가되기 때문에 편집 컨텍스트를 사용합니다.
- 파일의 경우 FileDTO 개체를 사용합니다. FileDTO에는 파일 이름과 파일에 도달하기 위한 공개 URL이 포함됩니다.
- URL의 경우 문자열 목록을 사용하여 공개적으로 사용 가능한 URL을 나타냅니다.
생성 단계에는 기술 자료에 대한 속성도 포함되어 있습니다.
defaultAnswerUsedForExtraction- 응답을 찾을 수 없을 때 반환됩니다.enableHierarchicalExtraction- 추출된 QnA 쌍 간의 프롬프트 관계를 자동으로 만듭니다.language- 리소스의 첫 번째 기술 자료를 만들 때 Azure Search 인덱스에서 사용할 언어를 설정합니다.
CreateAsync 메서드를 호출한 다음, 반환된 작업 ID를 MonitorOperation 메서드로 전달하여 상태를 폴링합니다.
다음 코드의 마지막 줄은 MonitorOperation의 응답에서 기술 자료 ID를 반환합니다.
private static async Task<string> CreateSampleKb(IQnAMakerClient client)
{
var qna1 = new QnADTO
{
Answer = "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
Questions = new List<string> { "How do I manage my knowledgebase?" },
Metadata = new List<MetadataDTO> {
new MetadataDTO { Name = "Category", Value = "api" },
new MetadataDTO { Name = "Language", Value = "REST" }
},
};
var qna2 = new QnADTO
{
Answer = "Yes, You can use our [.NET SDK](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker) with the [.NET Reference Docs](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.knowledge.qnamaker?view=azure-dotnet) to manage your knowledge base.",
Questions = new List<string> { "Can I program with C#?" },
Metadata = new List<MetadataDTO> {
new MetadataDTO { Name = "Category", Value = "api" },
new MetadataDTO { Name = "Language", Value = ".NET" }
}
};
var file1 = new FileDTO
{
FileName = "myfile.tsv",
FileUri = "https://mydomain/myfile.tsv"
};
var createKbDto = new CreateKbDTO
{
Name = "QnA Maker .NET SDK Quickstart",
QnaList = new List<QnADTO> { qna1, qna2 },
//Files = new List<FileDTO> { file1 }
};
var createOp = await client.Knowledgebase.CreateAsync(createKbDto);
createOp = await MonitorOperation(client, createOp);
return createOp.ResourceLocation.Replace("/knowledgebases/", string.Empty);
}
기술 자료를 성공적으로 만들려면 위의 코드에서 참조되는 MonitorOperation 함수를 포함해야 합니다.
기술 자료 업데이트
기술 자료 ID와 add, update 및 delete DTO 개체를 포함하는 UpdatekbOperationDTO를 UpdateAsync 메서드로 전달하여 기술 자료를 업데이트할 수 있습니다. 성공적으로 업데이트되었는지 확인하려면 MonitorOperation 메서드를 사용합니다.
private static async Task UpdateKB(IQnAMakerClient client, string kbId)
{
var urls = new List<string> {
"https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
};
var updateOp = await client.Knowledgebase.UpdateAsync(kbId, new UpdateKbOperationDTO
{
// Create JSON of changes
Add = new UpdateKbOperationDTOAdd
{
QnaList = new List<QnADTO> {
new QnADTO {
Questions = new List<string> {
"bye",
"end",
"stop",
"quit",
"done"
},
Answer = "goodbye",
Metadata = new List<MetadataDTO> {
new MetadataDTO { Name = "Category", Value="Chitchat" },
new MetadataDTO { Name = "Chitchat", Value = "end" },
}
},
new QnADTO {
Questions = new List<string> {
"hello",
"hi",
"start"
},
Answer = "Hello, please select from the list of questions or enter a new question to continue.",
Metadata = new List<MetadataDTO> {
new MetadataDTO { Name = "Category", Value="Chitchat" },
new MetadataDTO { Name = "Chitchat", Value = "begin" }
},
Context = new QnADTOContext
{
IsContextOnly = false,
Prompts = new List<PromptDTO>
{
new PromptDTO
{
DisplayOrder =1,
DisplayText= "Use REST",
QnaId=1
},
new PromptDTO
{
DisplayOrder =2,
DisplayText= "Use .NET NuGet package",
QnaId=2
},
}
}
},
},
Urls = urls
},
Update = null,
Delete = null
}); ;
// Loop while operation is success
updateOp = await MonitorOperation(client, updateOp);
}
기술 자료를 성공적으로 업데이트하려면 위의 코드에서 참조되는 MonitorOperation 함수를 포함해야 합니다.
기술 자료 다운로드
DownloadAsync 메서드를 사용하여 QnADocumentsDTO 목록으로 데이터베이스를 다운로드할 수 있습니다. 이 메소드의 결과는 파일이 아니기 때문에 설정 페이지에서 QnA Maker 포털의 내보내기와 동일하지 않습니다.
private static async Task DownloadKb(IQnAMakerClient client, string kbId)
{
var kbData = await client.Knowledgebase.DownloadAsync(kbId, EnvironmentType.Prod);
Console.WriteLine("KB Downloaded. It has {0} QnAs.", kbData.QnaDocuments.Count);
// Do something meaningful with data
}
기술 자료 게시
PublishAsync 메서드를 사용하여 기술 자료를 게시할 수 있습니다. 현재 저장되고 학습되며 기술 자료 ID에서 참조되는 모델을 사용하며, 이를 엔드포인트에 게시합니다. 이는 기술 자료를 쿼리하기 위해 필요한 단계입니다.
private static async Task PublishKb(IQnAMakerClient client, string kbId)
{
await client.Knowledgebase.PublishAsync(kbId);
}
쿼리 런타임 키 가져오기
기술 자료가 게시된 후에는 런타임 쿼리를 위한 쿼리 런타임 키가 필요합니다. 이는 원래 클라이언트 개체를 만드는 데 사용되는 키와 동일하지 않습니다.
EndpointKeys 메서드를 사용하여 EndpointKeysDTO 클래스를 가져옵니다.
개체에서 반환된 키 속성 중 하나를 사용하여 기술 자료를 쿼리합니다.
private static async Task<String> GetQueryEndpointKey(IQnAMakerClient client)
{
var endpointKeysObject = await client.EndpointKeys.GetKeysAsync();
return endpointKeysObject.PrimaryEndpointKey;
}
기술 자료를 쿼리하려면 런타임 키가 필요합니다.
응답을 생성하기 위한 런타임 인증
기술 자료를 쿼리하는 QnAMakerRuntimeClient를 만들어 답변을 생성하거나 활성 학습으로부터 학습합니다.
var runtimeClient = new QnAMakerRuntimeClient(new EndpointKeyServiceClientCredentials(primaryQueryEndpointKey))
{ RuntimeEndpoint = queryingURL };
QnAMakerRuntimeClient를 사용하여 다음을 수행합니다.
- 기술 자료에서 답변을 가져와서
- 활성 학습에 대한 기술 자료에 새로운 제안 질문을 보냅니다.
기술 자료에서 답변 생성
RuntimeClient.GenerateAnswerAsync 메서드를 사용하여 게시된 기술 자료에서 답변을 생성합니다. 이 메서드는 기술 자료 ID 및 QueryDTO을 허용합니다. 채팅 봇에서 사용할 Top 및 Context와 같은 QueryDTO의 추가 속성에 액세스합니다.
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
}
이는 기술 자료를 쿼리하는 간단한 예제입니다. 고급 쿼리 시나리오를 이해하려면 기타 쿼리 예제를 검토하세요.
기술 자료 삭제
기술 자료 ID의 매개 변수와 함께 DeleteAsync 메서드를 사용하여 기술 자료를 삭제할 수 있습니다.
private static async Task DeleteKB(IQnAMakerClient client, string kbId)
{
await client.Knowledgebase.DeleteAsync(kbId);
}
작업의 상태 가져오기
create 및 update와 같은 일부 메서드는 프로세스가 완료될 때까지 기다리는 대신 작업이 반환되는 데 충분한 시간을 가질 수 있습니다. 원래 메서드의 상태를 확인하려면 작업에서 작업 ID를 사용하여 폴링합니다(다시 시도 논리 사용).
다음 코드 블록의 루프 및 Task.Delay는 다시 시도 논리를 시뮬레이션하는 데 사용됩니다. 아래는 사용자의 자체 다시 시도 논리로 바꾸어야 합니다.
private static async Task<Operation> MonitorOperation(IQnAMakerClient client, Operation operation)
{
// Loop while operation is success
for (int i = 0;
i < 20 && (operation.OperationState == OperationStateType.NotStarted || operation.OperationState == OperationStateType.Running);
i++)
{
Console.WriteLine("Waiting for operation: {0} to complete.", operation.OperationId);
await Task.Delay(5000);
operation = await client.Operations.GetDetailsAsync(operation.OperationId);
}
if (operation.OperationState != OperationStateType.Succeeded)
{
throw new Exception($"Operation {operation.OperationId} failed to completed.");
}
return operation;
}
애플리케이션 실행
애플리케이션 디렉터리에서 dotnet run 명령을 사용하여 애플리케이션을 실행합니다.
dotnet run
이 샘플의 소스 코드는 GitHub에서 확인할 수 있습니다.
Node.js용 QnA Maker 클라이언트 라이브러리를 사용하여 다음을 수행할 수 있습니다.
- 기술 자료 만들기
- 기술자료 업데이트
- 기술 자료 게시
- 예측 런타임 엔드포인트 키 가져오기
- 장기 실행 작업 대기
- 기술 자료 다운로드
- 기술 자료에서 답변 가져오기
- 기술 자료 삭제
참조 설명서 | 패키지(npm) | Node.js 샘플
참고 항목
2019년 7월 1일 이후에 만들어진 새 리소스는 사용자 지정 하위 도메인 이름을 사용합니다. 자세한 내용과 지역 엔드포인트의 전체 목록은 Azure AI 서비스에 대한 사용자 지정 하위 도메인 이름을 참조하세요.
필수 조건
- Azure 구독 - 체험 구독 만들기
- 현재 버전의 Node.js
- Azure 구독을 보유한 후에는 Azure Portal에서 QnA Maker 리소스를 만들어 작성 키와 리소스를 가져옵니다. 배포 후 리소스로 이동을 선택합니다.
- 애플리케이션을 QnA Maker API에 연결하려면 만드는 리소스의 키와 리소스 이름이 필요합니다. 빠른 시작의 뒷부분에서 키와 리소스 이름을 아래 코드에 붙여넣습니다.
- 평가판 가격 책정 계층(
F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.
설정
새 Node.js 애플리케이션 만들기
콘솔 창(예: cmd, PowerShell 또는 Bash)에서 앱에 대한 새 디렉터리를 만들고 이 디렉터리로 이동합니다.
mkdir qnamaker_quickstart && cd qnamaker_quickstart
package.json 파일을 사용하여 노드 애플리케이션을 만들려면 npm init -y 명령을 실행합니다.
npm init -y
클라이언트 라이브러리 설치
다음 NPM 패키지를 설치합니다.
npm install @azure/cognitiveservices-qnamaker
npm install @azure/cognitiveservices-qnamaker-runtime
npm install @azure/ms-rest-js
앱의 package.json 파일이 종속성으로 업데이트됩니다.
index.js 파일을 만들고 다음 라이브러리를 가져옵니다.
const msRest = require("@azure/ms-rest-js");
const qnamaker = require("@azure/cognitiveservices-qnamaker");
const qnamaker_runtime = require("@azure/cognitiveservices-qnamaker-runtime");
리소스의 Azure 키에 대한 변수와 리소스 이름을 만듭니다.
구독 키와 작성 키를 서로 바꿔서 사용합니다. 작성 키에 대한 자세한 내용은 QnA Maker의 키를 참조하세요.
QNA_MAKER_ENDPOINT 값의 형식은
https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com입니다. Azure Portal로 이동하여 필수 구성 요소에서 만든 QnA Maker 리소스를 찾습니다. 리소스 관리에서 키 및 엔드포인트 페이지를 선택하여 작성(구독) 키 및 QnA Maker 엔드포인트를 찾습니다.
- QNA_MAKER_RUNTIME_ENDPOINT 값의 형식은
https://YOUR-RESOURCE-NAME.azurewebsites.net입니다. Azure Portal로 이동하여 필수 구성 요소에서 만든 QnA Maker 리소스를 찾습니다. Automation에서 템플릿 내보내기 페이지를 선택하여 런타임 엔드포인트를 찾습니다.
Important
완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure Key Vault와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은 Azure AI 서비스 보안 문서를 참조하세요.
const subscription_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
const endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
const runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";
개체 모델
QnA Maker는 다음과 같은 두 가지 개체 모델을 사용합니다.
- QnAMakerClient는 기술 자료를 만들고, 관리하고, 게시하고, 다운로드하는 개체입니다.
- QnAMakerRuntime은 GenerateAnswer API를 사용하여 기술 자료를 쿼리하고 Train API(활성 학습의 일부로)를 사용하여 새로 제안된 질문을 보내는 개체입니다.
QnAMakerClient 개체 모델
작성 QnA Maker 클라이언트는 키가 포함된 자격 증명을 사용하여 Azure에 인증하는 QnAMakerClient 개체입니다.
클라이언트를 만든 후 기술 자료를 사용하여 기술 자료를 만들고 관리하고 게시합니다.
JSON 개체를 전송하여 기술 자료를 관리합니다. 즉각적인 작업의 경우 메서드는 일반적으로 상태를 나타내는 JSON 개체를 반환합니다. 장기 실행 작업의 경우 응답은 작업 ID입니다. 작업 ID와 함께 client.operations.getDetails 메서드를 호출하여 요청의 상태를 확인합니다.
QnAMakerRuntimeClient 개체 모델
예측 QnA Maker 클라이언트는 Microsoft.Rest.ServiceClientCredentials를 사용하여 Azure에 인증하는 QnAMakerRuntimeClient 개체입니다. 이 개체는 기술 자료가 게시된 후에 제작 클라이언트 호출(client.EndpointKeys.getKeys)에서 반환된 예측 런타임 키를 포함합니다.
코드 예제
이 코드 조각은 .NET용 QnA Maker 클라이언트 라이브러리를 사용하여 다음을 수행하는 방법을 보여줍니다.
- 작성 클라이언트 인증
- 기술 자료 만들기
- 기술 자료 업데이트
- 기술 자료 다운로드
- 기술 자료 게시
- 기술 자료 삭제
- 쿼리 런타임 키 가져오기
- 작업의 상태 가져오기
- 쿼리 런타임 클라이언트 인증
- 기술 자료에서 답변 생성
기술 자료 제작을 위한 클라이언트 인증
엔드포인트 및 키를 사용하여 클라이언트를 인스턴스화합니다. 키를 사용하여 ServiceClientCredentials 개체를 만들고 엔드포인트와 함께 사용하여 QnAMakerClient 개체를 만듭니다.
const creds = new msRest.ApiKeyCredentials({ inHeader: { 'Ocp-Apim-Subscription-Key': subscription_key } });
const qnaMakerClient = new qnamaker.QnAMakerClient(creds, endpoint);
const knowledgeBaseClient = new qnamaker.Knowledgebase(qnaMakerClient);
기술 자료 만들기
기술 자료에는 다음 세 개의 원본에서 CreateKbDTO 개체에 대한 질문 및 답변 쌍이 저장됩니다.
- 편집 콘텐츠의 경우 QnADTO 개체를 사용합니다.
- 메타데이터 및 후속 프롬프트를 사용하려면 이 데이터가 개별 QnA 쌍 수준에 추가되기 때문에 편집 컨텍스트를 사용합니다.
- 파일의 경우 FileDTO 개체를 사용합니다. FileDTO에는 파일 이름과 파일에 도달하기 위한 공개 URL이 포함됩니다.
- URL의 경우 문자열 목록을 사용하여 공개적으로 사용 가능한 URL을 나타냅니다.
생성 단계에는 기술 자료에 대한 속성도 포함되어 있습니다.
defaultAnswerUsedForExtraction- 응답을 찾을 수 없을 때 반환됩니다.enableHierarchicalExtraction- 추출된 QnA 쌍 간의 프롬프트 관계를 자동으로 만듭니다.language- 리소스의 첫 번째 기술 자료를 만들 때 Azure Search 인덱스에서 사용할 언어를 설정합니다.
기술 자료 정보를 통해 create 메서드를 호출합니다. 기술 자료 정보는 기본적으로 JSON 개체입니다.
create 메서드가 반환되면 반환된 작업 ID를 wait_for_operation 메서드로 전달하여 상태를 폴링합니다. wait_for_operation 메서드는 작업이 완료되면 반환됩니다. 반환된 작업의 resourceLocation 헤더 값을 구문 분석하여 새 기술 자료 ID를 가져옵니다.
const createKnowledgeBase = async (qnaClient, kbclient) => {
console.log(`Creating knowledge base...`)
const qna1 = {
answer: "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
questions: ["How do I manage my knowledgebase?"],
metadata: [
{ name: "Category", value: "api" },
{ name: "Language", value: "REST" }
]
};
const qna2 = {
answer: "Yes, You can use our JS SDK on NPM for [authoring](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker), [query runtime](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker-runtime), and [the reference docs](https://docs.microsoft.com/en-us/javascript/api/@azure/cognitiveservices-qnamaker/?view=azure-node-latest) to manage your knowledge base.",
questions: ["How do I manage my knowledgebase?"],
metadata: [
{ name: "Category", value: "api" },
{ name: "Language", value: "JavaScript" }
]
};
const create_kb_payload = {
name: 'QnA Maker JavaScript SDK Quickstart',
qnaList: [
qna1,
qna2
],
urls: [],
files: [
/*{
fileName: "myfile.md",
fileUri: "https://mydomain/myfile.md"
}*/
],
defaultAnswerUsedForExtraction: "No answer found.",
enableHierarchicalExtraction: true,
language: "English"
};
const results = await kbclient.create(create_kb_payload)
if ( ! results._response.status.toString().startsWith("2")) {
console.log(`Create request failed - HTTP status ${results._response.status}`)
return
}
const operationResult = await wait_for_operation(qnaClient, results.operationId)
if (!operationResult || !operationResult.operationState || !(operationResult.operationState = "Succeeded") || !operationResult.resourceLocation) {
console.log(`Create operation state failed - HTTP status ${operationResult._response.status}`)
return
}
// parse resourceLocation for KB ID
const kbID = operationResult.resourceLocation.replace("/knowledgebases/", "");
return kbID;
}
기술 자료를 성공적으로 만들려면 위의 코드에서 참조되는 wait_for_operation 함수를 포함해야 합니다.
기술 자료 업데이트
기술 자료 ID와 add, update 및 delete DTO 개체를 포함하는 UpdateKbOperationDTO를 update 메서드로 전달하여 기술 자료를 업데이트할 수 있습니다. DTO는 기본적으로 JSON 개체이기도 합니다. 성공적으로 업데이트되었는지 확인하려면 wait_for_operation 메서드를 사용합니다.
const updateKnowledgeBase = async (qnaClient, kbclient, kb_id) => {
console.log(`Updating knowledge base...`)
const urls = [
"https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
]
const qna3 = {
answer: "goodbye",
questions: [
"bye",
"end",
"stop",
"quit",
"done"
],
metadata: [
{ name: "Category", value: "Chitchat" },
{ name: "Chitchat", value: "end" }
]
};
const qna4 = {
answer: "Hello, please select from the list of questions or enter a new question to continue.",
questions: [
"hello",
"hi",
"start"
],
metadata: [
{ name: "Category", value: "Chitchat" },
{ name: "Chitchat", value: "begin" }
],
context: {
isContextOnly: false,
prompts: [
{
displayOrder: 1,
displayText: "Use REST",
qna: null,
qnaId: 1
},
{
displayOrder: 2,
displayText: "Use JS NPM package",
qna: null,
qnaId: 2
},
]
}
};
console.log(JSON.stringify(qna4))
// Add new Q&A lists, URLs, and files to the KB.
const kb_add_payload = {
qnaList: [
qna3,
qna4
],
urls: urls,
files: []
};
// Bundle the add, update, and delete requests.
const update_kb_payload = {
add: kb_add_payload,
update: null,
delete: null,
defaultAnswerUsedForExtraction: "No answer found. Please rephrase your question."
};
console.log(JSON.stringify(update_kb_payload))
const results = await kbclient.update(kb_id, update_kb_payload)
if ( ! results._response.status.toString().startsWith("2")) {
console.log(`Update request failed - HTTP status ${results._response.status}`)
return false
}
const operationResult = await wait_for_operation(qnaClient, results.operationId)
if (operationResult.operationState != "Succeeded") {
console.log(`Update operation state failed - HTTP status ${operationResult._response.status}`)
return false
}
console.log(`Update operation state ${operationResult._response.status} - HTTP status ${operationResult._response.status}`)
return true
}
기술 자료를 성공적으로 업데이트하려면 위의 코드에서 참조되는 wait_for_operation 함수를 포함해야 합니다.
기술 자료 다운로드
download 메서드를 사용하여 QnADocumentsDTO 목록으로 데이터베이스를 다운로드합니다. 이 메서드의 결과가 TSV 파일이 아니므로 QnA Maker 포털에 있는 설정 페이지의 내보내기와 동일하지 않습니다.
const downloadKnowledgeBase = async (KBclient, kb_id) => {
console.log(`Downloading knowledge base...`)
var kbData = await KBclient.download(kb_id, "Prod");
console.log(`Knowledge base downloaded. It has ${kbData.qnaDocuments.length} QnAs.`);
// Do something meaningful with data
}
기술 자료 게시
publish 메서드를 사용하여 기술 자료를 게시합니다. 기술 자료 ID에서 참조하는 현재 저장 및 학습된 모델을 사용하며, 이를 엔드포인트에 게시합니다. HTTP 응답 코드를 확인하여 게시가 성공했는지 확인합니다.
const publishKnowledgeBase = async (kbclient, kb_id) => {
console.log(`Publishing knowledge base...`)
const results = await kbclient.publish(kb_id)
if ( ! results._response.status.toString().startsWith("2")) {
console.log(`Publish request failed - HTTP status ${results._response.status}`)
return false
}
console.log(`Publish request succeeded - HTTP status ${results._response.status}`)
return true
}
기술 자료 쿼리
쿼리 런타임 키 가져오기
기술 자료가 게시된 후에는 런타임 쿼리를 위한 쿼리 런타임 키가 필요합니다. 이는 원래 클라이언트 개체를 만드는 데 사용되는 키와 동일하지 않습니다.
EndpointKeys.getKeys 메서드를 사용하여 EndpointKeysDTO 클래스를 가져옵니다.
개체에서 반환된 키 속성 중 하나를 사용하여 기술 자료를 쿼리합니다.
const getEndpointKeys = async (qnaClient) => {
console.log(`Getting runtime endpoint keys...`)
const runtimeKeysClient = await qnaClient.endpointKeys;
const results = await runtimeKeysClient.getKeys()
if ( ! results._response.status.toString().startsWith("2")) {
console.log(`GetEndpointKeys request failed - HTTP status ${results._response.status}`)
return null
}
console.log(`GetEndpointKeys request succeeded - HTTP status ${results._response.status} - primary key ${results.primaryEndpointKey}`)
return results.primaryEndpointKey
}
응답을 생성하기 위한 런타임 인증
기술 자료를 쿼리하는 QnAMakerRuntimeClient를 만들어 답변을 생성하거나 활성 학습으로부터 학습합니다.
const queryRuntimeCredentials = new msRest.ApiKeyCredentials({ inHeader: { 'Authorization': 'EndpointKey ' + primaryQueryRuntimeKey } });
const runtimeClient = new qnamaker_runtime.QnAMakerRuntimeClient(queryRuntimeCredentials, runtime_endpoint);
QnAMakerRuntimeClient를 사용하여 기술 자료에서 답변을 얻거나 새로 제안된 질문을 활성 학습에 대한 기술 자료에 보냅니다.
기술 자료에서 답변 생성
RuntimeClient.runtime.generateAnswer 메서드를 사용하여 게시된 기술 자료에서 답변을 생성합니다. 이 메서드는 기술 자료 ID 및 QueryDTO을 허용합니다. 채팅 봇에서 사용할 Top 및 Context와 같은 QueryDTO의 추가 속성에 액세스합니다.
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));
}
다음은 기술 자료를 쿼리하는 간단한 예제입니다. 고급 쿼리 시나리오를 이해하려면 기타 쿼리 예제를 검토하세요.
기술 자료 삭제
기술 자료 ID의 매개 변수와 함께 delete 메서드를 사용하여 기술 자료를 삭제합니다.
const deleteKnowledgeBase = async (KBclient, kb_id) => {
console.log(`Deleting knowledge base...`)
const results = await KBclient.deleteMethod(kb_id)
if ( ! results._response.status.toString().startsWith("2")) {
console.log(`Delete operation state failed - HTTP status ${results._response.status}`)
return false
}
console.log(`Delete operation state succeeded - HTTP status ${results._response.status}`)
return true
}
작업의 상태 가져오기
create 및 update와 같은 일부 메서드는 프로세스가 완료될 때까지 기다리는 대신 작업이 반환되는 데 충분한 시간을 가질 수 있습니다. 원래 메서드의 상태를 확인하려면 작업에서 작업 ID를 사용하여 폴링합니다(다시 시도 논리 사용).
다음 코드 블록의 delayTimer 호출은 다시 시도 논리를 시뮬레이션하는 데 사용됩니다. 이를 다시 시도 논리로 바꿉니다.
const wait_for_operation = async (qnaClient, operation_id) => {
let state = "NotStarted"
let operationResult = undefined
while ("Running" === state || "NotStarted" === state) {
operationResult = await qnaClient.operations.getDetails(operation_id)
state = operationResult.operationState;
console.log(`Operation state - ${state}`)
await delayTimer(1000);
}
return operationResult;
}
const delayTimer = async (timeInMs) => {
return await new Promise((resolve) => {
setTimeout(resolve, timeInMs);
});
}
애플리케이션 실행
애플리케이션 디렉터리에서 node index.js 명령을 사용하여 애플리케이션을 실행합니다.
node index.js
이 샘플의 소스 코드는 GitHub에서 확인할 수 있습니다.
Python용 QnA Maker 클라이언트 라이브러리를 사용하여 다음을 수행할 수 있습니다.
- 기술 자료 만들기
- 기술자료 업데이트
- 기술 자료 게시
- 예측 런타임 엔드포인트 키 가져오기
- 장기 실행 작업 대기
- 기술 자료 다운로드
- 기술 자료에서 답변 가져오기
- 기술 자료 삭제
참조 설명서 | 라이브러리 소스 코드 | 패키지(PyPi) | Python 샘플
참고 항목
2019년 7월 1일 이후에 만들어진 새 리소스는 사용자 지정 하위 도메인 이름을 사용합니다. 자세한 내용과 지역 엔드포인트의 전체 목록은 Azure AI 서비스에 대한 사용자 지정 하위 도메인 이름을 참조하세요.
필수 조건
참고 항목
이 설명서는 최신 릴리스에는 적용되지 않습니다. 최신 릴리스에서 Python API를 사용하는 방법에 대한 자세한 내용은 Python 빠른 시작에 대한 답변을 참조합니다.
- Azure 구독 - 체험 구독 만들기
- Python 3.x
- Azure 구독을 보유한 후에는 Azure Portal에서 QnA Maker 리소스를 만들어 제작 키와 엔드포인트를 가져옵니다. 배포 후 리소스로 이동을 선택합니다.
- 애플리케이션을 QnA Maker API에 연결하려면 만든 리소스의 키와 엔드포인트가 필요합니다. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.
- 평가판 가격 책정 계층(
F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.
설정
클라이언트 라이브러리 설치
Python을 설치한 후, 다음을 사용하여 클라이언트 라이브러리를 설치할 수 있습니다.
pip install azure-cognitiveservices-knowledge-qnamaker==0.2.0
새 Python 애플리케이션 만들기
quickstart-file.py라는 새 Python 파일을 만들고 다음 라이브러리를 가져옵니다.
import os
import time
from azure.cognitiveservices.knowledge.qnamaker.authoring import QnAMakerClient
from azure.cognitiveservices.knowledge.qnamaker.runtime import QnAMakerRuntimeClient
from azure.cognitiveservices.knowledge.qnamaker.authoring.models import QnADTO, MetadataDTO, CreateKbDTO, OperationStateType, UpdateKbOperationDTO, UpdateKbOperationDTOAdd, EndpointKeysDTO, QnADTOContext, PromptDTO
from azure.cognitiveservices.knowledge.qnamaker.runtime.models import QueryDTO
from msrest.authentication import CognitiveServicesCredentials
리소스의 Azure 엔드포인트 및 키에 대한 변수를 만듭니다.
구독 키와 작성 키를 서로 바꿔서 사용합니다. 작성 키에 대한 자세한 내용은 QnA Maker의 키를 참조하세요.
QNA_MAKER_ENDPOINT 값의 형식은
https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com입니다. Azure Portal로 이동하여 필수 구성 요소에서 만든 QnA Maker 리소스를 찾습니다. 리소스 관리에서 키 및 엔드포인트 페이지를 선택하여 작성(구독) 키 및 QnA Maker 엔드포인트를 찾습니다.
- QNA_MAKER_RUNTIME_ENDPOINT 값의 형식은
https://YOUR-RESOURCE-NAME.azurewebsites.net입니다. Azure Portal로 이동하여 필수 구성 요소에서 만든 QnA Maker 리소스를 찾습니다. Automation에서 템플릿 내보내기 페이지를 선택하여 런타임 엔드포인트를 찾습니다.
Important
완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure Key Vault와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은 Azure AI 서비스 보안 문서를 참조하세요.
subscription_key = 'PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE'
authoring_endpoint = 'PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE'
runtime_endpoint = 'PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE'
개체 모델
QnA Maker는 다음과 같은 두 가지 개체 모델을 사용합니다.
- QnAMakerClient는 기술 자료를 만들고, 관리하고, 게시하고, 다운로드하는 개체입니다.
- QnAMakerRuntime은 GenerateAnswer API를 사용하여 기술 자료를 쿼리하고 Train API(활성 학습의 일부로)를 사용하여 새로 제안된 질문을 보내는 개체입니다.
이 예제 기술 자료 사용
이 빠른 시작의 기술 자료는 2개의 대화형 QnA 쌍으로 시작합니다. 이는 후속 프롬프트를 새로운 쌍에 연결하여 예제를 단순화하고 업데이트 메서드에 사용할 매우 예측 가능한 ID를 갖기 위해 의도적으로 수행됩니다. 이 빠른 시작에 대해 특정 순서로 계획 및 구현되었습니다.
시간이 지남에 따라 기존 QnA 쌍에 종속된 추가 작업 프롬프트를 통해 기술 자료를 개발하려는 경우 다음을 선택할 수 있습니다.
- 더 큰 기술 자료의 경우 자동화를 지원하는 텍스트 편집기나 TSV 도구에서 기술 자료를 관리한 다음, 기술 자료를 한 번에 업데이트로 완전히 대체합니다.
- 더 작은 기술 자료의 경우 QnA Maker 포털에서 후속 프롬프트를 완전히 관리합니다.
이 빠른 시작에 사용되는 QnA 쌍에 대한 세부 정보:
- QnA 쌍 유형 - 이 기술 자료에는 업데이트 후 chitchat 및 도메인별 정보의 2가지 유형의 QnA 쌍이 있습니다. 이는 기술 자료가 챗봇과 같은 대화 애플리케이션에 연결된 경우에 일반적입니다.
- 기술 자료 답변은 메타데이터로 필터링되거나 후속 프롬프트를 사용할 수 있지만, 이 빠른 시작에서는 이를 보여주지 않습니다. 여기에서 언어 제한이 없는 generateAnswer 예제를 찾아보세요.
- 대답 텍스트는 markdown이고 이미지(공개적으로 사용할 수 있는 인터넷 기반 이미지), 링크(공개적으로 사용할 수 있는 URL에 대한 링크) 및 글머리 기호 지점과 같이 다양한 markdown을 포함할 수 있습니다. 이 빠른 시작에서는 해당 다양성을 사용하지 않습니다.
QnAMakerClient 개체 모델
제작 QnA Maker 클라이언트는 키가 포함된 Microsoft.Rest.ServiceClientCredentials를 사용하여 Azure에 인증하는 QnAMakerClient 개체입니다.
클라이언트를 만든 후 기술 자료 속성을 사용하여 기술 자료를 생성, 관리 및 게시합니다.
JSON 개체를 전송하여 기술 자료를 관리합니다. 즉각적인 작업의 경우 메서드는 일반적으로 상태를 나타내는 JSON 개체를 반환합니다. 장기 실행 작업의 경우 응답은 작업 ID입니다. 작업 ID로 operations.get_details 메서드를 호출하여 요청의 상태를 확인합니다.
QnAMakerRuntimeClient 개체 모델
예측 QnA Maker 클라이언트는 Microsoft.Rest.ServiceClientCredentials를 사용하여 Azure에 인증하는 QnAMakerRuntimeClient 개체입니다. 이 개체는 기술 자료가 게시된 후에 제작 클라이언트 호출(client.EndpointKeysOperations.get_keys)에서 반환된 예측 런타임 키를 포함합니다.
generate_answer 메서드를 사용하여 쿼리 런타임에서 답변을 가져옵니다.
기술 자료 제작을 위한 클라이언트 인증
엔드포인트 및 키를 사용하여 클라이언트를 인스턴스화합니다. 키를 사용하여 CognitiveServicesCredentials 개체를 만들고, 엔드포인트에서 이를 사용하여 QnAMakerClient 개체를 만듭니다.
client = QnAMakerClient(endpoint=authoring_endpoint, credentials=CognitiveServicesCredentials(subscription_key))
기술 자료 만들기
클라이언트 개체를 사용하여 기술 자료 작업 개체를 가져옵니다.
기술 자료에는 다음 세 개의 원본에서 CreateKbDTO 개체에 대한 질문 및 답변 쌍이 저장됩니다.
- 편집 콘텐츠의 경우 QnADTO 개체를 사용합니다.
- 메타데이터 및 후속 프롬프트를 사용하려면 이 데이터가 개별 QnA 쌍 수준에 추가되기 때문에 편집 컨텍스트를 사용합니다.
- 파일의 경우 FileDTO 개체를 사용합니다. FileDTO에는 파일 이름과 파일에 도달하기 위한 공개 URL이 포함됩니다.
- URL의 경우 문자열 목록을 사용하여 공개적으로 사용 가능한 URL을 나타냅니다.
create 메서드를 호출한 다음, 반환된 작업 ID를 Operations.getDetails 메서드로 전달하여 상태를 폴링합니다.
다음 코드의 마지막 줄은 MonitorOperation의 응답에서 기술 자료 ID를 반환합니다.
def create_kb(client):
print ("Creating knowledge base...")
qna1 = QnADTO(
answer="Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
questions=["How do I manage my knowledgebase?"],
metadata=[
MetadataDTO(name="Category", value="api"),
MetadataDTO(name="Language", value="REST"),
]
)
qna2 = QnADTO(
answer="Yes, You can use our [Python SDK](https://pypi.org/project/azure-cognitiveservices-knowledge-qnamaker/) with the [Python Reference Docs](https://docs.microsoft.com/python/api/azure-cognitiveservices-knowledge-qnamaker/azure.cognitiveservices.knowledge.qnamaker?view=azure-python) to manage your knowledge base.",
questions=["Can I program with Python?"],
metadata=[
MetadataDTO(name="Category", value="api"),
MetadataDTO(name="Language", value="Python"),
]
)
urls = []
files = [
FileDTO(
file_name = "structured.docx",
file_uri = "https://github.com/Azure-Samples/cognitive-services-sample-data-files/raw/master/qna-maker/data-source-formats/structured.docx"
)]
create_kb_dto = CreateKbDTO(
name="QnA Maker Python SDK Quickstart",
qna_list=[
qna1,
qna2
],
urls=urls,
files=[],
enable_hierarchical_extraction=True,
default_answer_used_for_extraction="No answer found.",
language="English"
)
create_op = client.knowledgebase.create(create_kb_payload=create_kb_dto)
create_op_monitor = _monitor_operation(client=client, operation=create_op)
# Get knowledge base ID from resourceLocation HTTP header
knowledge_base_ID = create_op_monitor.resource_location.replace("/knowledgebases/", "")
print("Created KB with ID: {}".format(knowledge_base_ID))
return knowledge_base_ID
기술 자료를 성공적으로 만들려면 위의 코드에서 참조되는 _monitor_operation 함수를 포함해야 합니다.
기술 자료 업데이트
기술 자료 ID와 add, update 및 delete DTO 개체를 포함하는 UpdateKbOperationDTO를 update 메서드로 전달하여 기술 자료를 업데이트할 수 있습니다. 성공적으로 업데이트되었는지 확인하려면 Operation.getDetail 메서드를 사용합니다.
def update_kb(client, kb_id):
print ("Updating knowledge base...")
qna3 = QnADTO(
answer="goodbye",
questions=[
"bye",
"end",
"stop",
"quit",
"done"
],
metadata=[
MetadataDTO(name="Category", value="Chitchat"),
MetadataDTO(name="Chitchat", value="end"),
]
)
qna4 = QnADTO(
answer="Hello, please select from the list of questions or enter a new question to continue.",
questions=[
"hello",
"hi",
"start"
],
metadata=[
MetadataDTO(name="Category", value="Chitchat"),
MetadataDTO(name="Chitchat", value="begin"),
],
context = QnADTOContext(
is_context_only = False,
prompts = [
PromptDTO(
display_order =1,
display_text= "Use REST",
qna_id=1
),
PromptDTO(
display_order =2,
display_text= "Use .NET NuGet package",
qna_id=2
),
]
)
)
urls = [
"https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
]
update_kb_operation_dto = UpdateKbOperationDTO(
add=UpdateKbOperationDTOAdd(
qna_list=[
qna3,
qna4
],
urls = urls,
files=[]
),
delete=None,
update=None
)
update_op = client.knowledgebase.update(kb_id=kb_id, update_kb=update_kb_operation_dto)
_monitor_operation(client=client, operation=update_op)
print("Updated knowledge base.")
기술 자료를 성공적으로 업데이트하려면 위의 코드에서 참조되는 _monitor_operation 함수를 포함해야 합니다.
기술 자료 다운로드
download 메서드를 사용하여 QnADocumentsDTO 목록으로 데이터베이스를 다운로드합니다. 이 메서드의 결과가 TSV 파일이 아니므로 QnA Maker 포털에 있는 설정 페이지의 내보내기와 동일하지 않습니다.
def download_kb(client, kb_id):
print("Downloading knowledge base...")
kb_data = client.knowledgebase.download(kb_id=kb_id, environment="Prod")
print("Downloaded knowledge base. It has {} QnAs.".format(len(kb_data.qna_documents)))
기술 자료 게시
publish 메서드를 사용하여 기술 자료를 게시합니다. 기술 자료 ID에서 참조하는 현재 저장 및 학습된 모델을 사용하며, 이를 엔드포인트에 게시합니다.
def publish_kb(client, kb_id):
print("Publishing knowledge base...")
client.knowledgebase.publish(kb_id=kb_id)
print("Published knowledge base.")
기술 자료 쿼리
쿼리 런타임 키 가져오기
기술 자료가 게시된 후에는 런타임 쿼리를 위한 쿼리 런타임 키가 필요합니다. 이는 원래 클라이언트 개체를 만드는 데 사용되는 키와 동일하지 않습니다.
EndpointKeysOperations.get_keys 메서드를 사용하여 EndpointKeysDTO 클래스를 가져옵니다.
개체에서 반환된 키 속성 중 하나를 사용하여 기술 자료를 쿼리합니다.
def getEndpointKeys_kb(client):
print("Getting runtime endpoint keys...")
keys = client.endpoint_keys.get_keys()
print("Primary runtime endpoint key: {}.".format(keys.primary_endpoint_key))
return keys.primary_endpoint_key
응답을 생성하기 위한 런타임 인증
기술 자료를 쿼리하는 QnAMakerRuntimeClient를 만들어 답변을 생성하거나 활성 학습으로부터 학습합니다.
runtimeClient = QnAMakerRuntimeClient(runtime_endpoint=runtime_endpoint, credentials=CognitiveServicesCredentials(queryRuntimeKey))
QnAMakerRuntimeClient를 사용하여 기술 자료에서 답변을 얻거나 새로 제안된 질문을 활성 학습에 대한 기술 자료에 보냅니다.
기술 자료에서 답변 생성
QnAMakerRuntimeClient.runtime.generate_answer 메서드를 사용하여 게시된 기술 자료에서 답변을 생성합니다. 이 메서드는 기술 자료 ID 및 QueryDTO을 허용합니다. 채팅 봇에서 사용할 Top 및 Context와 같은 QueryDTO의 추가 속성에 액세스합니다.
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}.")
다음은 기술 자료를 쿼리하는 간단한 예입니다. 고급 쿼리 시나리오를 이해하려면 기타 쿼리 예제를 검토하세요.
기술 자료 삭제
기술 자료 ID의 매개 변수와 함께 delete 메서드를 사용하여 기술 자료를 삭제합니다.
def delete_kb(client, kb_id):
print("Deleting knowledge base...")
client.knowledgebase.delete(kb_id=kb_id)
print("Deleted knowledge base.")
작업의 상태 가져오기
create 및 update와 같은 일부 메서드는 프로세스가 완료될 때까지 기다리는 대신 작업이 반환되는 데 충분한 시간을 가질 수 있습니다. 원래 메서드의 상태를 확인하려면 작업에서 작업 ID를 사용하여 폴링합니다(다시 시도 논리 사용).
다음 코드 블록의 setTimeout 호출은 비동기 코드를 시뮬레이션하는 데 사용됩니다. 재시도 논리로 바꿉니다.
def _monitor_operation(client, operation):
for i in range(20):
if operation.operation_state in [OperationStateType.not_started, OperationStateType.running]:
print("Waiting for operation: {} to complete.".format(operation.operation_id))
time.sleep(5)
operation = client.operations.get_details(operation_id=operation.operation_id)
else:
break
if operation.operation_state != OperationStateType.succeeded:
raise Exception("Operation {} failed to complete.".format(operation.operation_id))
return operation
애플리케이션 실행
빠른 시작 파일에서 Python 명령을 사용하여 애플리케이션을 실행합니다.
python quickstart-file.py
이 샘플의 소스 코드는 GitHub에서 확인할 수 있습니다.
Java용 QnA Maker 클라이언트 라이브러리를 사용하여 다음을 수행할 수 있습니다.
- 기술 자료 만들기
- 기술자료 업데이트
- 기술 자료 게시
- 예측 런타임 엔드포인트 키 가져오기
- 장기 실행 작업 대기
- 기술 자료 다운로드
- 기술 자료에서 답변 가져오기
- 기술 자료 삭제
라이브러리 소스 코드 | 패키지 | 샘플
참고 항목
2019년 7월 1일 이후에 만들어진 새 리소스는 사용자 지정 하위 도메인 이름을 사용합니다. 자세한 내용과 지역 엔드포인트의 전체 목록은 Azure AI 서비스에 대한 사용자 지정 하위 도메인 이름을 참조하세요.
필수 조건
- Azure 구독 - 체험 구독 만들기
- JDK
- Azure 구독을 보유한 후에는 Azure Portal에서 QnA Maker 리소스를 만들어 제작 키와 엔드포인트를 가져옵니다. 배포 후 리소스로 이동을 선택합니다.
- 애플리케이션을 QnA Maker API에 연결하려면 만든 리소스의 키와 엔드포인트가 필요합니다. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.
- 평가판 가격 책정 계층(
F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.
설정
클라이언트 라이브러리 설치
Java를 설치한 후 MVN 리포지토리에서 Maven을 사용하여 클라이언트 라이브러리를 설치할 수 있습니다.
새 Java 애플리케이션 만들기
새 파일 quickstart.java를 만들고 다음 라이브러리를 가져옵니다.
/* Download the following files.
* - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar
* - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.pom
* Move the downloaded .jar file to a folder named "lib" directly under the current folder.
* Rename the downloaded file to pom.xml.
* At the command line, run
* mvn dependency:copy-dependencies
* This will download the .jar files depended on by azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar to the folder "target/dependency" under the current folder. Move these .jar files to the "lib" folder as well.
*/
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.*;
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.models.*;
import java.io.*;
import java.lang.Object.*;
import java.time.format.DateTimeFormatter;
import java.time.LocalDateTime;
import java.util.*;
import java.net.*;
리소스의 Azure 엔드포인트 및 키에 대한 변수를 만듭니다.
구독 키와 작성 키를 서로 바꿔서 사용합니다. 작성 키에 대한 자세한 내용은 QnA Maker의 키를 참조하세요.
QNA_MAKER_ENDPOINT 값의 형식은
https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com입니다. Azure Portal로 이동하여 필수 구성 요소에서 만든 QnA Maker 리소스를 찾습니다. 리소스 관리에서 키 및 엔드포인트 페이지를 선택하여 작성(구독) 키 및 QnA Maker 엔드포인트를 찾습니다.
- QNA_MAKER_RUNTIME_ENDPOINT 값의 형식은
https://YOUR-RESOURCE-NAME.azurewebsites.net입니다. Azure Portal로 이동하여 필수 구성 요소에서 만든 QnA Maker 리소스를 찾습니다. Automation에서 템플릿 내보내기 페이지를 선택하여 런타임 엔드포인트를 찾습니다.
Important
완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure Key Vault와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은 Azure AI 서비스 보안 문서를 참조하세요.
private static String authoring_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
private static String authoring_endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
private static String runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";
개체 모델
QnA Maker는 다음과 같은 두 가지 개체 모델을 사용합니다.
- QnAMakerClient는 기술 자료를 만들고, 관리하고, 게시하고, 다운로드하는 개체입니다.
- QnAMakerRuntime은 GenerateAnswer API를 사용하여 기술 자료를 쿼리하고 Train API(활성 학습의 일부로)를 사용하여 새로 제안된 질문을 보내는 개체입니다.
이 예제 기술 자료 사용
이 빠른 시작의 기술 자료는 2개의 대화형 QnA 쌍으로 시작합니다. 이는 후속 프롬프트를 새로운 쌍에 연결하여 예제를 단순화하고 업데이트 메서드에 사용할 매우 예측 가능한 ID를 갖기 위해 의도적으로 수행됩니다. 이 빠른 시작에 대해 특정 순서로 계획 및 구현되었습니다.
시간이 지남에 따라 기존 QnA 쌍에 종속된 추가 작업 프롬프트를 통해 기술 자료를 개발하려는 경우 다음을 선택할 수 있습니다.
- 더 큰 기술 자료의 경우 자동화를 지원하는 텍스트 편집기나 TSV 도구에서 기술 자료를 관리한 다음, 기술 자료를 한 번에 업데이트로 완전히 대체합니다.
- 더 작은 기술 자료의 경우 QnA Maker 포털에서 후속 프롬프트를 완전히 관리합니다.
이 빠른 시작에 사용되는 QnA 쌍에 대한 세부 정보:
- QnA 쌍 유형 - 이 기술 자료에는 업데이트 후 chitchat 및 도메인별 정보의 2가지 유형의 QnA 쌍이 있습니다. 이는 기술 자료가 챗봇과 같은 대화 애플리케이션에 연결된 경우에 일반적입니다.
- 기술 자료 답변은 메타데이터로 필터링되거나 후속 프롬프트를 사용할 수 있지만, 이 빠른 시작에서는 이를 보여주지 않습니다. 여기에서 언어 제한이 없는 generateAnswer 예제를 찾아보세요.
- 대답 텍스트는 markdown이고 이미지(공개적으로 사용할 수 있는 인터넷 기반 이미지), 링크(공개적으로 사용할 수 있는 URL에 대한 링크) 및 글머리 기호 지점과 같이 다양한 markdown을 포함할 수 있습니다. 이 빠른 시작에서는 해당 다양성을 사용하지 않습니다.
QnAMakerClient 개체 모델
제작 QnA Maker 클라이언트는 키가 포함된 MsRest::ServiceClientCredentials를 사용하여 Azure에 인증하는 QnAMakerClient 개체입니다.
클라이언트가 생성되면 클라이언트의 Knowledgebases 속성 메서드를 사용하여 기술 자료를 생성, 관리 및 게시합니다.
즉각적인 작업의 경우 메서드는 일반적으로 결과(있는 경우)를 반환합니다. 장기 실행 작업의 경우 응답은 작업 개체입니다. operation.operationId 값과 함께 getDetails 메서드를 호출하여 요청의 상태를 확인합니다.
QnAMakerRuntimeClient 개체 모델
런타임 QnA Maker 클라이언트는 QnAMakerRuntimeClient 개체입니다.
제작 클라이언트를 사용하여 기술 자료를 게시한 후에는 런타임 클라이언트의 generateAnswer 메서드를 사용하여 기술 자료에서 답변을 가져옵니다.
QnAMakerRuntimeManager.authenticate를 호출하고 런타임 엔드포인트 키를 전달하여 런타임 클라이언트를 만듭니다. 런타임 엔드포인트를 키를 가져오려면 제작 클라이언트를 사용하여 getKeys를 호출합니다.
기술 자료 제작을 위한 클라이언트 인증
제작 엔드포인트 및 구독 키를 사용하여 클라이언트를 인스턴스화합니다.
/* Note QnAMakerManager.authenticate() does not set the baseUrl paramater value
* as the value for QnAMakerClient.endpoint, so we still need to call withEndpoint().
*/
QnAMakerClient authoring_client = QnAMakerManager.authenticate(authoring_key).withEndpoint(authoring_endpoint);
Knowledgebases kb_client = authoring_client.knowledgebases();
Operations ops_client = authoring_client.operations();
EndpointKeys keys_client = authoring_client.endpointKeys();
기술 자료 만들기
기술 자료에는 다음 세 개의 원본에서 CreateKbDTO 개체에 대한 질문 및 답변 쌍이 저장됩니다.
- 편집 콘텐츠의 경우 QnADTO 개체를 사용합니다.
- 메타데이터 및 후속 프롬프트를 사용하려면 이 데이터가 개별 QnA 쌍 수준에 추가되기 때문에 편집 컨텍스트를 사용합니다.
- 파일의 경우 FileDTO 개체를 사용합니다. FileDTO에는 파일 이름과 파일에 도달하기 위한 공개 URL이 포함됩니다.
- URL의 경우 문자열 목록을 사용하여 공개적으로 사용 가능한 URL을 나타냅니다.
create 메서드를 호출한 다음, 반환된 작업의 operationId 속성을 getDetails 메서드로 전달하여 상태를 폴링합니다.
다음 코드의 마지막 줄은 기술 자료 ID를 반환합니다.
public String create_kb () throws Exception {
System.out.println("Creating KB...");
String name = "QnA Maker FAQ from quickstart";
var metadata = new MetadataDTO()
.withName ("Category")
.withValue ("api");
List<MetadataDTO> metadata_list = Arrays.asList(new MetadataDTO[]{ metadata });
var qna = new QnADTO()
.withAnswer ("You can use our REST APIs to manage your knowledge base.")
.withQuestions ( Arrays.asList(new String[]{ "How do I manage my knowledgebase?" }))
.withMetadata (metadata_list);
List<QnADTO> qna_list = Arrays.asList(new QnADTO[]{ qna });
var urls = Arrays.asList(new String[]{ "https://docs.microsoft.com/en-in/azure/cognitive-services/qnamaker/faqs" });
var payload = new CreateKbDTO().withName(name).withQnaList(qna_list).withUrls(urls);
var result = kb_client.create(payload);
var kb_id = wait_for_operation(result);
System.out.println("Created KB with ID: " + kb_id + ".\n");
return kb_id;
}
기술 자료 업데이트
update를 호출하고 기술 자료 ID와 UpdateKbOperationDTO 개체를 전달하여 기술 자료를 업데이트할 수 있습니다. 그러면 해당 개체에 다음이 포함될 수 있습니다.
반환된 작업의 operationId 속성을 getDetails 메서드로 전달하여 상태를 폴링합니다.
public void update_kb (String kb_id) throws Exception {
System.out.println("Updating KB...");
var update = new UpdateKbOperationDTOUpdate().withName ("New KB name");
var payload = new UpdateKbOperationDTO().withUpdate((UpdateKbOperationDTOUpdate)update);
var result = kb_client.update(kb_id, payload);
wait_for_operation(result);
System.out.println("Updated KB.");
}
기술 자료 다운로드
download 메서드를 사용하여 QnADocumentsDTO 목록으로 데이터베이스를 다운로드합니다. 이 메서드의 결과가 TSV 파일이 아니므로 QnA Maker 포털에 있는 설정 페이지의 내보내기와 동일하지 않습니다.
public void download_kb(String kb_id) {
System.out.println("Downloading KB...");
var kb_data = kb_client.download(kb_id, EnvironmentType.PROD);
System.out.println("KB Downloaded. It has " + kb_data.qnaDocuments().size() + " question/answer sets.");
System.out.println("Downloaded KB.\n");
}
기술 자료 게시
publish 메서드를 사용하여 기술 자료를 게시합니다. 기술 자료 ID에서 참조하는 현재 저장 및 학습된 모델을 사용하며, 이를 엔드포인트에 게시합니다.
public void publish_kb(String kb_id) {
System.out.println("Publishing KB...");
kb_client.publish(kb_id);
System.out.println("KB published.\n");
}
기술 자료에서 답변 생성
기술 자료가 게시된 후에는 기술 자료를 쿼리하기 위한 런타임 엔드포인트 키가 필요합니다. 이는 제작 클라이언트를 만드는 데 사용되는 구독 키와 다릅니다.
getKeys 메서드를 사용하여 EndpointKeysDTO 개체를 가져옵니다.
QnAMakerRuntimeManager.authenticate를 호출하고 EndpointKeysDTO 개체에서 런타임 엔드포인트 키를 전달하여 런타임 클라이언트를 만듭니다.
generateAnswer 메서드를 사용하여 게시된 기술 자료에서 답변을 생성합니다. 이 메서드는 기술 자료 ID 및 QueryDTO 개체를 허용합니다.
public void query_kb(String kb_id) {
System.out.println("Sending query to KB...");
var runtime_key = keys_client.getKeys().primaryEndpointKey();
QnAMakerRuntimeClient runtime_client = QnAMakerRuntimeManager.authenticate(runtime_key).withRuntimeEndpoint(runtime_endpoint);
var query = (new QueryDTO()).withQuestion("How do I manage my knowledgebase?");
var result = runtime_client.runtimes().generateAnswer(kb_id, query);
System.out.println("Answers:");
for (var answer : result.answers()) {
System.out.println(answer.answer().toString());
};
System.out.println();
}
이는 기술 자료를 쿼리하는 간단한 예제입니다. 고급 쿼리 시나리오를 이해하려면 기타 쿼리 예제를 검토하세요.
기술 자료 삭제
기술 자료 ID의 매개 변수와 함께 delete 메서드를 사용하여 기술 자료를 삭제합니다.
public void delete_kb(String kb_id) {
System.out.println("Deleting KB...");
kb_client.delete(kb_id);
System.out.println("KB deleted.\n");
}
작업의 상태 가져오기
create 및 update와 같은 일부 메서드는 프로세스가 완료될 때까지 기다리는 대신 작업이 반환되는 데 충분한 시간을 가질 수 있습니다. 원래 메서드의 상태를 확인하려면 작업에서 작업 ID를 사용하여 폴링합니다(다시 시도 논리 사용).
public String wait_for_operation(Operation op) throws Exception {
System.out.println ("Waiting for operation to finish...");
Boolean waiting = true;
String result = "";
while (true == waiting) {
var op_ = ops_client.getDetails(op.operationId());
var state = op_.operationState();
if (OperationStateType.FAILED == state) {
throw new Exception("Operation failed.");
}
if (OperationStateType.SUCCEEDED == state) {
waiting = false;
// Remove "/knowledgebases/" from the resource location.
result = op_.resourceLocation().replace("/knowledgebases/", "");
}
if (true == waiting) {
System.out.println("Waiting 10 seconds for operation to complete...");
Thread.sleep(10000);
}
}
return result;
}
애플리케이션 실행
애플리케이션의 주요 방법은 다음과 같습니다.
public static void main(String[] args) {
try {
Quickstart quickstart = new Quickstart();
String kb_id = quickstart.create_kb();
// quickstart.list_kbs();
quickstart.update_kb(kb_id);
quickstart.publish_kb(kb_id);
quickstart.download_kb(kb_id);
quickstart.query_kb(kb_id);
quickstart.delete_kb(kb_id);
} catch (Exception e) {
System.out.println(e.getMessage());
e.printStackTrace();
}
}
다음과 같이 애플리케이션을 실행합니다. 이는 클래스 이름이 Quickstart이고 종속성이 현재 폴더 아래의 lib라는 하위 폴더에 있는 것으로 가정합니다.
javac Quickstart.java -cp .;lib\*
java -cp .;lib\* Quickstart
이 샘플의 소스 코드는 GitHub에서 확인할 수 있습니다.
리소스 정리
Azure AI 서비스 구독을 정리하고 제거하려면 리소스 또는 리소스 그룹을 삭제할 수 있습니다. 리소스 그룹을 삭제하면 해당 리소스 그룹에 연결된 다른 모든 리소스가 함께 삭제됩니다.