빠른 시작: 사용자 지정 질문 답변

참고 항목

QnA Maker에서 워크로드를 마이그레이션하시겠습니까? 기능 비교 및 마이그레이션 단계에 대한 정보는 마이그레이션 가이드를 참조하세요.

사용자 지정형 질문 답변 클라이언트 라이브러리를 시작합니다. 이러한 단계에 따라 패키지를 설치하고 기본 작업을 위한 예제 코드를 사용해 봅니다.

FAQ, 제품 매뉴얼 등 고유의 콘텐츠를 활용해 사용자 지정 질문 답변 프로젝트를 만들 수 있습니다. 이 문서에는 질문에 답하기 위해 제품 매뉴얼에서 사용자 지정 질문 답변 프로젝트를 만드는 예가 포함되어 있습니다.

필수 조건

• Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다.
• 사용자 지정 질문 답변 기능이 사용하도록 설정된 언어 리소스. 리소스를 만들 때 선택한 Microsoft Entra ID, 구독, 언어 리소스 이름을 기억하세요.

첫 번째 사용자 지정 질문 답변 프로젝트 만들기

1. Azure 자격 증명으로 Language Studio에 로그인합니다.

2. 질문 답변 섹션까지 아래로 스크롤하고 사용자 지정 질문 답변 열기를 선택합니다.

   

3. 리소스가 아직 Azure Search에 연결되지 않은 경우 Azure Search에 연결을 선택합니다. 그러면 Azure Portal에서 리소스의 기능 창에 대한 새 브라우저 탭이 열립니다.

   

4. 사용자 지정 질문 답변 사용을 선택하고 연결할 Azure Search 리소스를 선택한 다음 적용을 선택합니다.

   

5. 언어 스튜디오 탭으로 돌아갑니다. 변경 사항을 리소스에 등록하려면 이 페이지를 새로 고쳐야 할 수 있습니다. 새 프로젝트 만들기를 선택합니다.

6. 이 리소스에서 만든 모든 프로젝트의 언어를 설정하려고 합니다> 옵션을 선택합니다. 영어>를 선택한 후 다음을 선택합니다.

7. Sample-project라는 프로젝트 이름, 나의 첫 질문 답변 프로젝트의 설명을 입력하고 기본 답변은 답변을 찾을 수 없음 설정으로 둡니다.

8. 선택 사항을 검토하고 프로젝트 만들기를 선택합니다.

9. 원본 관리 페이지에서 원본 추가>URL을 선택합니다.

10. URL 추가를 선택하고 다음 값을 입력한 다음 모두 추가를 선택합니다.

    URL 이름	URL 값
    Surface Book 사용자 가이드	https://download.microsoft.com/download/7/B/1/7B10C82E-F520-4080-8516-5CF0D803EEE0/surface-book-user-guide-EN.pdf

    추출 프로세스는 문서를 읽고 질문과 답변을 확인하는 데 몇 분 정도가 걸립니다.

    원본을 성공적으로 추가한 후 원본 내용을 편집하여 더 많은 사용자 지정 질문 답변 세트를 추가할 수 있습니다.

프로젝트 테스트

1. 원본에 대한 링크를 선택하면 프로젝트 편집 페이지가 열립니다.

2. 메뉴 모음에서 테스트를 선택하고 Surface Book을 어떻게 설정하나요? 질문을 입력합니다. 원본 URL에서 자동으로 식별되고 추출된 질문 답변 쌍을 기반으로 답변이 생성됩니다.

   

   단답형 답변 포함 확인란을 선택하면 질문을 할 때 테스트 창에 답변 구절과 함께 정확한 답변(가능한 경우)도 표시됩니다.

3. 검사를 선택하여 응답을 더 자세히 살펴봅니다. 테스트 창은 프로젝트를 배포하기 전에 프로젝트에 대한 변경 사항을 테스트하는 데 사용됩니다.

   

   검사 인터페이스에서 이 응답이 질문에 답하고 주어진 질문 및 답변 응답 쌍을 직접 편집할 것이라는 신뢰도 수준을 확인할 수 있습니다.

프로젝트 배포

1. 프로젝트 배포 아이콘을 선택하여 프로젝트 배포 메뉴로 들어갑니다.

   

   프로젝트를 배포하면 프로젝트 콘텐츠가 Azure Search의 test 인덱스에서 prod 인덱스로 이동합니다.

2. 배포>를 선택한 다음, 메시지가 표시되면 배포를 다시 선택합니다.

   

   이제 프로젝트가 성공적으로 배포되었습니다. 엔드포인트를 사용하여 답변할 사용자 지정 애플리케이션 또는 봇에서 질문에 답변할 수 있습니다.

필수 조건

• 현재 버전의 cURL. 빠른 시작에는 몇 가지 명령줄 스위치가 사용되며, 이러한 스위치는 cURL 설명서에 나와 있습니다.
• Azure 구독 - 체험 구독 만들기
• 사용자 지정 질문 답변에는 API 키 및 엔드포인트를 생성하기 위해 사용 설정된 사용자 지정 질문 답변 기능이 있는 언어 리소스가 필요합니다.
  • 언어 리소스가 배포된 후 리소스로 이동을 선택합니다. API에 연결하려면 만든 리소스의 키와 엔드포인트가 필요합니다. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.
• Azure CLI를 사용하여 언어 리소스를 만들려면 다음 추가 속성을 제공하세요. --api-properties qnaAzureSearchEndpointId=/subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Search/searchServices/<azure-search-service-name> qnaAzureSearchEndpointKey=<azure-search-service-auth-key>
• 쿼리할 기존 프로젝트입니다. 프로젝트가 설치되지 않은 경우 Language Studio 빠른 시작의 지침을 따를 수 있습니다. 또는 이 Surface 사용자 가이드 URL을 데이터 원본으로 사용하는 프로젝트를 추가합니다.

설정

환경 변수 만들기

API 요청을 보내려면 애플리케이션을 인증해야 합니다. 프로덕션의 경우 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 이 예제에서는 애플리케이션을 실행하는 로컬 컴퓨터의 환경 변수에 자격 증명을 작성합니다.

Language 리소스 키에 대한 환경 변수를 설정하려면 콘솔 창을 열고 운영 체제 및 개발 환경에 대한 지침을 따릅니다.

• LANGUAGE_KEY 환경 변수를 설정하려면 your-key를 리소스에 대한 키 중 하나로 바꿉니다.
• LANGUAGE_ENDPOINT 환경 변수를 설정하려면 your-endpoint를 리소스에 대한 엔드포인트로 바꿉니다.

Important

API 키를 사용하는 경우 Azure Key Vault와 같은 다른 위치에 안전하게 저장합니다. API 키를 코드에 직접 포함하지 말고, 공개적으로 게시하지 마세요.

AI 서비스 보안에 대한 자세한 내용은 Azure AI 서비스에 대한 요청 인증을 참조하세요.

Windows

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

참고 항목

현재 실행 중인 콘솔에서만 환경 변수에 액세스해야 하는 경우 환경 변수를 setx 대신 set으로 설정할 수 있습니다.

환경 변수가 추가되면 콘솔 창을 포함하여 환경 변수를 읽어야 하는 실행 중인 프로그램을 다시 시작해야 할 수 있습니다. 예를 들어 편집기로 Visual Studio를 사용하는 경우 Visual Studio를 다시 시작한 후 예제를 실행합니다.

Linux

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

환경 변수를 추가한 후 콘솔 창에서 source ~/.bashrc 명령을 실행하여 변경 내용을 적용합니다.

macOS

Bash

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

환경 변수를 추가한 후 콘솔 창에서 source ~/.bash_profile 명령을 실행하여 변경 내용을 적용합니다.

Xcode

iOS 및 macOS 개발의 경우 Xcode에서 환경 변수를 설정합니다. 예를 들어, 다음 단계에 따라 Xcode 13.4.1에서 환경 변수를 설정합니다.

1. 제품>구성표>구성표 편집을 선택합니다.
2. 실행(디버그 실행) 페이지에서 인수를 선택합니다.
3. 환경 변수 아래에서 더하기(+) 기호를 선택하여 새 환경 변수를 추가합니다.
4. 이름에 대해 LANGUAGE_KEY를 입력하고, 값에 대해 Language 리소스 키를 입력합니다.
5. 리소스 엔드포인트에 대해 다음 단계를 수행합니다. 새 환경 변수의 이름을 LANGUAGE_ENDPOINT로 지정합니다.

추가 구성 옵션은 Xcode 설명서를 참조하세요.

프로젝트 쿼리

프로젝트에서 답변 생성

REST API 및 cURL을 사용하여 사용자 지정 질문 답변 프로젝트를 쿼리하려면 다음 정보가 필요합니다.

변수 이름	값
Endpoint	이 값은 Azure Portal에서 리소스를 검사할 때 키 및 엔드포인트 섹션에서 찾을 수 있습니다. 또는 Language Studio>질문 답변>프로젝트 배포>예측 URL 가져오기에서 값을 찾을 수 있습니다. 엔드포인트 예제는 https://southcentralus.api.cognitive.microsoft.com/입니다.
API-Key	이 값은 Azure Portal에서 리소스를 검사할 때 키 및 엔드포인트 섹션에서 찾을 수 있습니다. Key1 또는 Key2를 사용할 수 있습니다. 가동 중지 시간이 0인 안전한 키 회전을 위해 항상 두 개의 유효한 키가 있어야 합니다. 또는 Language Studio>질문 답변>프로젝트 배포>예측 URL 가져오기에서 값을 찾을 수 있습니다. 키 값은 샘플 요청의 일부입니다.
Project	사용자 지정 질문 답변 프로젝트의 이름.
Deployment	두 개의 가능한 값은 test 및 production입니다. production은 Language Studio>질문 답변>프로젝트 배포에서 프로젝트를 배포했는지 여부에 따라 달라집니다.

cURL 명령은 BASH 셸에서 실행됩니다. 사용자 고유의 리소스 이름, 리소스 키 및 JSON 값과 JSON 크기를 사용하여 이 명령을 편집합니다.

curl -X POST -H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" -H "Content-Type: application/json" -d '{
  "question": "How much battery life do I have left?"
  }'  '$LANGUAGE_ENDPOINT.api.cognitive.microsoft.com/language/:query-knowledgebases?projectName={YOUR_PROJECT_NAME}&api-version=2021-10-01&deploymentName={DEPLOYMENT_NAME}'

위의 코드를 실행할 때 필수 구성 요소의 데이터 원본을 사용하는 경우 다음과 같은 답변이 표시됩니다.

{
"answers": [
    {
      "questions": [
        "Check battery level"
      ],
      "answer": "If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.",
      "confidenceScore": 0.9185,
      "id": 101,
      "source": "https://support.microsoft.com/en-us/surface/how-to-use-your-surface-pen-8a403519-cd1f-15b2-c9df-faa5aa924e98",
      "metadata": {},
      "dialog": {
        "isContextOnly": false,
        "prompts": []
      }
    }
  ]
}

confidenceScore는 0과 1 사이의 값을 반환합니다. 이를 백분율로 생각하여 100을 곱합니다. 이 경우 0.9185의 신뢰도 점수는 사용자 지정 질문 답변에서 프로젝트를 기반으로 한 질문에 대한 올바른 답변이라고 91.85% 확신한다는 것을 의미합니다.

신뢰도 점수가 특정 임계값 미만인 답변을 제외하려면 confidenceScoreThreshold 매개 변수를 추가하면 됩니다.

curl -X POST -H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" -H "Content-Type: application/json" -d '{
  "question": "How much battery life do I have left?",
  "confidenceScoreThreshold": "0.95",
  }'  '$LANGUAGE_ENDPOINT.api.cognitive.microsoft.com//language/:query-knowledgebases?projectName=Sample-project&api-version=2021-10-01&deploymentName={DEPLOYMENT_NAME}'

이전 코드 실행에서 신뢰도 점수가 .9185임을 알고 있으므로 임계값을 .95로 설정하면 기본 답변이 반환됩니다.

{
  "answers": [
    {
      "questions": [],
      "answer": "No good match found in KB",
      "confidenceScore": 0.0,
      "id": -1,
      "metadata": {}
    }
  ]
}

프로젝트 없이 텍스트 쿼리

query-text를 통해 호출되는 미리 빌드된 사용자 지정 질문 답변 REST API를 사용하여 프로젝트 없이 사용자 지정 질문 답변을 사용할 수도 있습니다. 이 경우 요청이 보내지면 답변을 검색하려는 질문 및 관련 텍스트 레코드 모두를 질문 답변에 제공합니다.

다음 예제에서는 API KEY 및 ENDPOINT에 대한 변수만 수정하면 됩니다.

curl -X POST -H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" -H "Content-Type: application/json" -d '{
"question":"How long does it takes to charge a surface?",
"records":[
{"id":"doc1","text":"Power and charging.It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you\u0027re using your Surface for power-intensive activities like gaming or video streaming while you\u0027re charging it"},
{"id":"doc2","text":"You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface."}],
"language":"en",
"stringIndexType":"Utf16CodeUnit"
}'  '$LANGUAGE_ENDPOINT.api.cognitive.microsoft.com/language/:query-text?&api-version=2021-10-01'

이 예제에서 반환하는 결과는 다음과 같습니다.

{  
"answers": [
    {
      "answer": "Power and charging.It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it",
      "confidenceScore": 0.9118788838386536,
      "id": "doc1",
      "answerSpan": {
        "text": "two to four hours",
        "confidenceScore": 0.9850527,
        "offset": 27,
        "length": 18
      },
      "offset": 0,
      "length": 243
    },
    {
      "answer": "It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it",
      "confidenceScore": 0.052793052047491074,
      "id": "doc1",
      "answerSpan": {
        "text": "longer",
        "confidenceScore": 0.6694634,
        "offset": 11,
        "length": 7
      },
      "offset": 109,
      "length": 134
    },
    {
      "answer": "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface.",
      "confidenceScore": 0.017600709572434425,
      "id": "doc2",
      "answerSpan": {
        "text": "USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging",
        "confidenceScore": 0.1544854,
        "offset": 15,
        "length": 165
      },
      "offset": 0,
      "length": 280
    }
  ]
}

.NET용 사용자 지정 질문 답변 클라이언트 라이브러리에 대해 이 빠른 시작을 사용하여 다음을 수행합니다.

• 프로젝트에서 답변을 가져옵니다.
• 질문과 함께 보내는 텍스트 본문에서 답변을 얻습니다.
• 질문에 대한 답변의 신뢰도 점수를 얻습니다.

참조 설명서 | 패키지(NuGet) | 추가 샘플 | 라이브러리 소스 코드

필수 조건

• Azure 구독 - 체험 구독 만들기
• Visual Studio IDE 또는 현재 버전의 .NET Core.
• 사용자 지정 질문 답변에는 API 키 및 엔드포인트를 생성하기 위해 사용 설정된 사용자 지정 질문 답변 기능이 있는 언어 리소스가 필요합니다.
  • 언어 리소스가 배포된 후 리소스로 이동을 선택합니다. API에 연결하려면 만든 리소스의 키와 엔드포인트가 필요합니다. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.
• Azure CLI를 사용하여 언어 리소스를 만들려면 다음 추가 속성을 제공하세요. --api-properties qnaAzureSearchEndpointId=/subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Search/searchServices/<azure-search-service-name> qnaAzureSearchEndpointKey=<azure-search-service-auth-key>
• 쿼리할 기존 프로젝트입니다. 프로젝트가 설치되지 않은 경우 Language Studio 빠른 시작의 지침을 따를 수 있습니다. 또는 이 Surface 사용자 가이드 URL을 데이터 원본으로 사용하는 프로젝트를 추가합니다.

설정

환경 변수 만들기

API 요청을 보내려면 애플리케이션을 인증해야 합니다. 프로덕션의 경우 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 이 예제에서는 애플리케이션을 실행하는 로컬 컴퓨터의 환경 변수에 자격 증명을 작성합니다.

Language 리소스 키에 대한 환경 변수를 설정하려면 콘솔 창을 열고 운영 체제 및 개발 환경에 대한 지침을 따릅니다.

• LANGUAGE_KEY 환경 변수를 설정하려면 your-key를 리소스에 대한 키 중 하나로 바꿉니다.
• LANGUAGE_ENDPOINT 환경 변수를 설정하려면 your-endpoint를 리소스에 대한 엔드포인트로 바꿉니다.

Important

API 키를 사용하는 경우 Azure Key Vault와 같은 다른 위치에 안전하게 저장합니다. API 키를 코드에 직접 포함하지 말고, 공개적으로 게시하지 마세요.

AI 서비스 보안에 대한 자세한 내용은 Azure AI 서비스에 대한 요청 인증을 참조하세요.

Windows

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

참고 항목

현재 실행 중인 콘솔에서만 환경 변수에 액세스해야 하는 경우 환경 변수를 setx 대신 set으로 설정할 수 있습니다.

환경 변수가 추가되면 콘솔 창을 포함하여 환경 변수를 읽어야 하는 실행 중인 프로그램을 다시 시작해야 할 수 있습니다. 예를 들어 편집기로 Visual Studio를 사용하는 경우 Visual Studio를 다시 시작한 후 예제를 실행합니다.

Linux

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

환경 변수를 추가한 후 콘솔 창에서 source ~/.bashrc 명령을 실행하여 변경 내용을 적용합니다.

macOS

Bash

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

환경 변수를 추가한 후 콘솔 창에서 source ~/.bash_profile 명령을 실행하여 변경 내용을 적용합니다.

Xcode

iOS 및 macOS 개발의 경우 Xcode에서 환경 변수를 설정합니다. 예를 들어, 다음 단계에 따라 Xcode 13.4.1에서 환경 변수를 설정합니다.

1. 제품>구성표>구성표 편집을 선택합니다.
2. 실행(디버그 실행) 페이지에서 인수를 선택합니다.
3. 환경 변수 아래에서 더하기(+) 기호를 선택하여 새 환경 변수를 추가합니다.
4. 이름에 대해 LANGUAGE_KEY를 입력하고, 값에 대해 Language 리소스 키를 입력합니다.
5. 리소스 엔드포인트에 대해 다음 단계를 수행합니다. 새 환경 변수의 이름을 LANGUAGE_ENDPOINT로 지정합니다.

추가 구성 옵션은 Xcode 설명서를 참조하세요.

CLI

콘솔 창(예: cmd, PowerShell 또는 Bash)에서 dotnet new 명령을 사용하여 question-answering-quickstart라는 새 콘솔 앱을 만듭니다. 이 명령은 program.cs라는 단일 소스 파일을 사용하여 간단한 "Hello World" C# 프로젝트를 만듭니다.

dotnet new console -n question-answering-quickstart

새로 만든 앱 폴더로 디렉터리를 변경합니다. 다음을 통해 애플리케이션을 빌드할 수 있습니다.

dotnet build

빌드 출력에 경고나 오류가 포함되지 않아야 합니다.

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

애플리케이션 디렉터리 내에서 다음 명령을 사용하여 .NET용 사용자 지정 질문 답변 클라이언트 라이브러리를 설치합니다.

dotnet add package Azure.AI.Language.QuestionAnswering

프로젝트 쿼리

프로젝트에서 답변 생성

아래 예제에서는 질문에 대한 답변을 얻기 위해 GetAnswers를 사용하여 프로젝트를 쿼리할 수 있습니다.

아래 코드를 업데이트하고, 다음 변수에 대한 고유한 값을 제공해야 합니다.

변수 이름	값
endpoint	이 값은 Azure Portal에서 리소스를 검사할 때 키 및 엔드포인트 섹션에서 찾을 수 있습니다. 또는 Language Studio>질문 답변>프로젝트 배포>예측 URL 가져오기에서 값을 찾을 수 있습니다. 엔드포인트 예제는 https://southcentralus.api.cognitive.microsoft.com/입니다.
credential	이 값은 Azure Portal에서 리소스를 검사할 때 키 및 엔드포인트 섹션에서 찾을 수 있습니다. Key1 또는 Key2를 사용할 수 있습니다. 가동 중지 시간이 0인 안전한 키 회전을 위해 항상 두 개의 유효한 키가 있어야 합니다. 또는 Language Studio>질문 답변>프로젝트 배포>예측 URL 가져오기에서 값을 찾을 수 있습니다. 키 값은 샘플 요청의 일부입니다.
projectName	사용자 지정 질문 답변 프로젝트의 이름.
deploymentName	두 개의 가능한 값은 test 및 production입니다. production은 Language Studio>질문 답변>프로젝트 배포에서 프로젝트를 배포했는지 여부에 따라 달라집니다.

Important

완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure Key Vault와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은 Azure AI 서비스 보안 문서를 참조하세요.

프로젝트 디렉터리에서 program.cs 파일을 열고, 다음 코드로 바꿉니다.

using Azure;
using Azure.AI.Language.QuestionAnswering;
using System;

namespace question_answering
{
    class Program
    {
        static void Main(string[] args)
        {

            // This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
            Uri endpoint = new Uri("LANGUAGE_ENDPOINT");
            AzureKeyCredential credential = new AzureKeyCredential("LANGUAGE_KEY");
            string projectName = "{YOUR-PROJECT-NAME}";
            string deploymentName = "production";

            string question = "How long should my Surface battery last?";

            QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);
            QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);

            Response<AnswersResult> response = client.GetAnswers(question, project);

            foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
            {
                Console.WriteLine($"Q:{question}");
                Console.WriteLine($"A:{answer.Answer}");
            }
        }
    }
}

이 예제의 변수는 하드 코딩되어 있습니다. 프로덕션의 경우 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용하는 것이 좋습니다. 예를 들어 Azure Key Vault는 보안 키 스토리지를 제공합니다.

먼저 Program.cs를 위의 코드로 업데이트하고 올바른 변수 값으로 바꿉니다. 애플리케이션 디렉터리에서 dotnet run 명령을 사용하여 애플리케이션을 실행합니다.

dotnet run

응답은 다음과 같습니다.

Q: How much battery life do I have left?
A: If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.

사용자 지정 질문 답변에서 이 답변이 올바른 응답이라고 확신하는 정도에 대한 정보를 확인하려면 추가 출력 문을 기존 출력 문 아래에 추가합니다.

Console.WriteLine($"Q:{question}");
Console.WriteLine($"A:{answer.Answer}");
Console.WriteLine($"({answer.Confidence})"); // add this line

dotnet run을 다시 실행하면 이제 신뢰도 점수가 포함된 결과가 표시됩니다.

Q:How much battery life do I have left?
A:If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.
(0.9185)

신뢰도 점수는 0과 1 사이의 값을 반환합니다. 이를 백분율로 생각하여 100을 곱합니다. 이 경우 0.9185의 신뢰도 점수는 사용자 지정 질문 답변에서 프로젝트를 기반으로 한 질문에 대한 올바른 답변이라고 91.85% 확신한다는 것을 의미합니다.

신뢰도 점수가 특정 임계값 미만인 답변을 제외하려면 AnswerOptions를 사용하여 ConfidenceScoreThreshold 속성을 추가합니다.

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
AnswersOptions options = new AnswersOptions(); //Add this line
options.ConfidenceThreshold = 0.95; //Add this line

Response<AnswersResult> response = client.GetAnswers(question, project, options); //Add the additional options parameter

이전 코드 실행에서 신뢰도 점수가 .9185임을 알고 있으므로 임계값을 .95로 설정하면 기본 답변이 반환됩니다.

Q:How much battery life do I have left?
A:No good match found in KB
(0)

프로젝트 없이 텍스트 쿼리

GetAnswersFromText를 사용하면 프로젝트 없이 사용자 지정 질문 답변을 사용할 수도 있습니다. 이 경우 요청이 보내지면 답변을 검색하려는 질문 및 관련 텍스트 레코드 모두를 사용자 지정 질문 답변에 제공합니다.

다음 예제에서는 endpoint 및 credential에 대한 변수만 수정하면 됩니다.

using Azure;
using Azure.AI.Language.QuestionAnswering;
using System;
using System.Collections.Generic;


namespace questionansweringcsharp
{
    class Program
    {
        static void Main(string[] args)
        {

            Uri endpoint = new Uri("https://{YOUR-ENDPOINT}.api.cognitive.microsoft.com/");
            AzureKeyCredential credential = new AzureKeyCredential("YOUR-LANGUAGE-RESOURCE-KEY");
            QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

            IEnumerable<TextDocument> records = new[]
            {
                new TextDocument("doc1", "Power and charging.It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. " +
                         "It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it"),
                new TextDocument("doc2", "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. " +
                         "The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface."),
            };

            AnswersFromTextOptions options = new AnswersFromTextOptions("How long does it takes to charge a surface?", records);
            Response<AnswersFromTextResult> response = client.GetAnswersFromText(options);

           foreach (TextAnswer answer in response.Value.Answers)
            {
                if (answer.Confidence > .9)
                {
                    string BestAnswer = response.Value.Answers[0].Answer;

                    Console.WriteLine($"Q:{options.Question}");
                    Console.WriteLine($"A:{BestAnswer}");
                    Console.WriteLine($"Confidence Score: ({response.Value.Answers[0].Confidence:P2})"); //:P2 converts the result to a percentage with 2 decimals of accuracy. 
                    break;
                }
                else
                {
                    Console.WriteLine($"Q:{options.Question}");
                    Console.WriteLine("No answers met the requested confidence score.");
                    break;
                }
            }

        }
    }
}

위의 코드를 실행하려면 Program.cs를 위의 스크립트 블록 내용으로 바꾸고, 필수 구성 요소의 일부로 만든 언어 리소스에 해당하도록 endpoint 및 credential 변수를 수정합니다.

이 경우 모든 답변을 반복하고 0.9보다 큰 가장 높은 신뢰도 점수를 가진 답변만 반환합니다. GetAnswersFromText에서 사용할 수 있는 옵션에 대해 자세히 알아보세요.

Python용 사용자 지정 질문 답변 클라이언트 라이브러리에 대해 이 빠른 시작을 사용하여 다음을 수행합니다.

• 프로젝트에서 답변을 가져옵니다.
• 질문과 함께 보내는 텍스트 본문에서 답변을 얻습니다.
• 질문에 대한 답변의 신뢰도 점수를 얻습니다.

참조 설명서 | 패키지(PyPI) | 추가 샘플 | 라이브러리 소스 코드

필수 조건

• Azure 구독 - 체험 구독 만들기
• Python 3.x
• 사용자 지정 질문 답변에는 API 키 및 엔드포인트를 생성하기 위해 사용 설정된 사용자 지정 질문 답변 기능이 있는 언어 리소스가 필요합니다.
  • 언어 리소스가 배포된 후 리소스로 이동을 선택합니다. API에 연결하려면 생성한 리소스의 키와 엔드포인트가 필요합니다. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.
• Azure CLI를 사용하여 언어 리소스를 만들려면 다음과 같은 다른 속성을 제공하세요. --api-properties qnaAzureSearchEndpointId=/subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Search/searchServices/<azure-search-service-name> qnaAzureSearchEndpointKey=<azure-search-service-auth-key>
• 쿼리할 기존 프로젝트입니다. 프로젝트가 설치되지 않은 경우 Language Studio 빠른 시작의 지침을 따를 수 있습니다. 또는 이 Surface 사용자 가이드 URL을 데이터 원본으로 사용하는 프로젝트를 추가합니다.

설정

클라이언트 라이브러리 설치

Python을 설치한 후, 다음을 사용하여 클라이언트 라이브러리를 설치할 수 있습니다.

pip install azure-ai-language-questionanswering

프로젝트 쿼리

프로젝트에서 답변 생성

아래 예제에서는 질문에 대한 답변을 얻기 위해 get_answers를 사용하여 프로젝트를 쿼리할 수 있습니다. 이 코드는 전용 .py 파일 또는 Jupyter Notebook/Lab의 셀에 복사할 수 있습니다.

아래 코드를 업데이트하고 다음 변수에 대한 고유한 값을 제공해야 합니다.

변수 이름	값
endpoint	이 값은 Azure Portal에서 리소스를 검사할 때 키 및 엔드포인트 섹션에서 찾을 수 있습니다. 또는 Language Studio>질문 답변>프로젝트 배포>예측 URL 가져오기에서 값을 찾을 수 있습니다. 엔드포인트 예제는 https://southcentralus.api.cognitive.microsoft.com/입니다.
credential	이 값은 Azure Portal에서 리소스를 검사할 때 키 및 엔드포인트 섹션에서 찾을 수 있습니다. Key1 또는 Key2를 사용할 수 있습니다. 가동 중지 시간이 0인 안전한 키 회전을 위해 항상 두 개의 유효한 키가 있어야 합니다. 또는 Language Studio>질문 답변>프로젝트 배포>예측 URL 가져오기에서 값을 찾을 수 있습니다. 키 값은 샘플 요청의 일부입니다.
knowledge_base_project	질문 답변 프로젝트의 이름입니다.
deployment	두 개의 가능한 값은 test 및 production입니다. production은 Language Studio>질문 답변>프로젝트 배포에서 프로젝트를 배포했는지 여부에 따라 달라집니다.

Important

완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure Key Vault와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은 Azure AI 서비스 보안 문서를 참조하세요.

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient

endpoint = "https://{YOUR-ENDPOINT}.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("{YOUR-LANGUAGE-RESOURCE-KEY}")
knowledge_base_project = "{YOUR-PROJECT-NAME}"
deployment = "production"

def main():
    client = QuestionAnsweringClient(endpoint, credential)
    with client:
        question="How much battery life do I have left?"
        output = client.get_answers(
            question = question,
            project_name=knowledge_base_project,
            deployment_name=deployment
        )
    print("Q: {}".format(question))
    print("A: {}".format(output.answers[0].answer))

if __name__ == '__main__':
    main()

예제의 변수를 하드 코딩하는 동안. 프로덕션의 경우 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용하는 것이 좋습니다. 예를 들어 Azure Key Vault는 보안 키 스토리지를 제공합니다.

위의 코드를 실행할 때 필수 조건의 데이터 원본을 사용하는 경우 다음과 같은 응답을 얻게 됩니다.

Q: How much battery life do I have left?
A: If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.

이것이 올바른 응답이라는 확신 있는 사용자 지정 질문 답변에 대한 정보를 보려면 기존 print 문 아래에 또 다른 print 문을 추가하세요.

print("Q: {}".format(question))
print("A: {}".format(output.answers[0].answer))
print("Confidence Score: {}".format(output.answers[0].confidence)) # add this line 

이제 신뢰도 점수가 포함된 결과를 받게 됩니다.

Q: How much battery life do I have left?
A: If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.
Confidence Score: 0.9185

신뢰도 점수는 0과 1 사이의 값을 반환합니다. 이를 백분율로 생각하여 100을 곱합니다. 이 경우 0.9185의 신뢰도 점수는 사용자 지정 질문 답변에서 프로젝트를 기반으로 한 질문에 대한 올바른 답변이라고 91.85% 확신한다는 것을 의미합니다.

신뢰도 점수가 특정 임계값 미만인 답변을 제외하려면 confidence_threshold 매개 변수를 추가하도록 AnswerOptions를 수정할 수 있습니다.

        output = client.get_answers(
            confidence_threshold = 0.95, #add this line
            question = question,
            project_name=knowledge_base_project,
            deployment_name=deployment
        )

이전 코드 실행을 통해 신뢰도 점수는 다음과 같습니다. .9185 임계값을 .95(으)로 설정하면 기본 답변이 반환됩니다.

Q: How much battery life do I have left?
A: No good match found in KB
Confidence Score: 0.0

프로젝트 없이 텍스트 쿼리

get_answers_from_text를 사용하면 프로젝트 없이 사용자 지정 질문 답변을 사용할 수도 있습니다. 이 경우 요청이 보내지면 답변을 검색하려는 질문 및 관련 텍스트 레코드 모두를 사용자 지정 질문 답변에 제공합니다.

다음 예제에서는 endpoint 및 credential에 대한 변수만 수정하면 됩니다.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.ai.language.questionanswering import models as qna

endpoint = "https://{YOUR-ENDPOINT}.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("YOUR-LANGUAGE-RESOURCE-KEY")

def main():
    client = QuestionAnsweringClient(endpoint, credential)
    with client:
        question="How long does it takes to charge a surface?"
        input = qna.AnswersFromTextOptions(
            question=question,
            text_documents=[
                "Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. " +
                "It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it.",
                "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. " +
                "The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface.",
            ]
        )


        output = client.get_answers_from_text(input)

    best_answer = [a for a in output.answers if a.confidence > 0.9][0]
    print(u"Q: {}".format(input.question))
    print(u"A: {}".format(best_answer.answer))
    print("Confidence Score: {}".format(output.answers[0].confidence))

if __name__ == '__main__':
    main()

이 코드는 전용 .py 파일 또는 Jupyter Notebook/Lab의 새 셀에 복사할 수 있습니다. 이 예에서는 다음 결과를 반환합니다.

Q: How long does it takes to charge surface?
A: Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it.
Confidence Score: 0.9254655838012695

이 경우 모든 답변을 반복하고 0.9보다 큰 가장 높은 신뢰도 점수를 가진 답변만 반환합니다. get_answers_from_text에서 사용할 수 있는 옵션에 대해 자세히 알아보려면 AnswersFromTextOptions 매개 변수를 검토하세요.

리소스 정리

Azure AI 서비스 구독을 정리하고 제거하려면 리소스 또는 리소스 그룹을 삭제할 수 있습니다. 리소스 그룹을 삭제하면 해당 리소스 그룹에 연결된 다른 모든 리소스가 함께 삭제됩니다.

• Azure Portal
• Azure CLI

REST API 탐색

사용자 지정 질문 답변 파이프라인 자동화에 대해 알아보려면 REST API 설명서를 참조하세요. 현재 작성 기능은 REST API를 통해서만 사용할 수 있습니다.

• 작성 API 참조
• 작성 API cURL 예제
• 런타임 API 참조

다음 단계

• 자습서: FAQ 봇 만들기