Python용 Azure Cognitive Language Service 질문 답변 클라이언트 라이브러리 - 버전 1.1.0

아티클
04/05/2023

질문 답변은 기존 데이터에 대해 대화형 질문 및 답변 계층을 만들 수 있는 클라우드 기반 API 서비스입니다. FAQ, 설명서 및 문서를 포함하여 반구조화된 콘텐츠에서 질문과 답변을 추출하여 기술 자료 빌드하는 데 사용합니다. 기술 자료 QnA의 최상의 답변으로 사용자의 질문에 자동으로 답변합니다. 사용자의 동작에서 지속적으로 학습하므로 기술 자료 더 스마트해집니다.

소스 코드 | 패키지(PyPI) | API 참조 설명서 | 제품 설명서 | 샘플

고지 사항

Python 2.7에 대한 Azure SDK Python 패키지 지원은 2022년 1월 1일에 종료되었습니다. 자세한 내용과 질문은 다음을 참조하세요. https://github.com/Azure/azure-sdk-for-python/issues/20691

시작

필수 조건

이 패키지를 사용하려면 Python 3.7 이상이 필요합니다.
Azure 구독
언어 서비스 리소스

패키지 설치

pip를 사용하여 Python용 Azure 질문 답변 클라이언트 라이브러리를 설치합니다.

pip install azure-ai-language-questionanswering

참고: 이 버전의 클라이언트 라이브러리는 기본적으로 서비스 API 버전 2021-10-01로 설정됩니다.

클라이언트 인증

질문 답변 서비스와 상호 작용하려면 리소스 내에서 프로젝트를 관리하기 위해 QuestionAnsweringClient 클래스의 인스턴스 또는 AuthoringClient 인스턴스를 만들어야 합니다. 클라이언트 개체를 인스턴스화하려면 엔드포인트와 API 키가 필요합니다. Cognitive Services 인증에 대한 자세한 내용은 Azure Cognitive Services에 대한 요청 인증을 참조하세요.

API 키 가져오기

Azure Portal의 언어 리소스에서 엔드포인트 및 API 키를 가져올 수 있습니다.

또는 아래에 표시된 Azure CLI 명령을 사용하여 언어 리소스에서 API 키를 가져옵니다.

az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>

QuestionAnsweringClient 만들기

엔드포인트 및 API 키를 결정했으면 QuestionAnsweringClient를 인스턴스화할 수 있습니다.

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

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = QuestionAnsweringClient(endpoint, credential)

AuthoringClient 만들기

엔드포인트 및 API 키를 사용하여 AuthoringClient를 인스턴스화할 수 있습니다.

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = AuthoringClient(endpoint, credential)

Azure Active Directory 자격 증명을 사용하여 클라이언트 만들기

AAD(Azure Active Directory) 토큰 자격 증명을 사용하려면 azure-identity 라이브러리에서 가져온 원하는 자격 증명 유형의 인스턴스를 제공합니다. 지역 엔드포인트는 AAD 인증을 지원하지 않습니다. 이 유형의 인증을 사용하기 위해 리소스에 대한 사용자 지정 하위 도메인 이름을 만듭니다.

AAD를 사용하여 인증하려면 몇 가지 초기 설정이 필요합니다.

azure-identity 설치
새 AAD 애플리케이션 등록
서비스 주체에 "Cognitive Services 언어 읽기 권한자" 역할을 할당하여 언어 서비스에 대한 액세스 권한을 부여합니다.

설치 후 azure.identity에서 사용할 자격 증명 유형을 선택할 수 있습니다. 예를 들어 DefaultAzureCredential을 사용하여 클라이언트를 인증할 수 있습니다.

AAD 애플리케이션의 클라이언트 ID, 테넌트 ID 및 클라이언트 암호 값을 환경 변수로 설정합니다. AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET

반환된 토큰 자격 증명을 사용하여 클라이언트를 인증합니다.

from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = QuestionAnsweringClient(endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/", credential=credential)

주요 개념

QuestionAnsweringClient

QuestionAnsweringClient는 사용자 고유의 정보가 포함된 기술 자료 사용하거나 미리 학습된 모델을 사용하는 텍스트 입력을 사용하여 질문을 하기 위한 기본 인터페이스입니다. 비동기 작업의 경우 비동 QuestionAnsweringClient 기는 네임스페이스에 azure.ai.language.questionanswering.aio 있습니다.

AuthoringClient

AuthoringClient는 질문 답변 프로젝트를 관리하기 위한 인터페이스를 제공합니다. 사용 가능한 작업의 예로는 프로젝트 만들기 및 배포, 지식 원본 업데이트, 질문 및 답변 쌍 업데이트 등이 있습니다. 동기 API와 비동기 API를 모두 제공합니다.

예제

QuestionAnsweringClient

클라이언트 라이브러리는 azure-ai-language-questionanswering 동기 및 비동기 API를 모두 제공합니다.

질문하기
후속 질문하기
새 프로젝트 만들기
기술 자료 추가
프로젝트 배포
비동기 작업

질문하기

기술 자료 사용하여 질문을 하는 데 필요한 유일한 입력은 질문 자체입니다.

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

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="test"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

추가 키워드 옵션을 설정하여 답변 수를 제한하고, 최소 신뢰도 점수를 지정하는 등의 작업을 수행할 수 있습니다.

후속 질문하기

기술 자료 잡담용으로 구성된 경우 기술 자료 답변에 대화를 시작하기 위한 후속 질문에 대한 제안된 프롬프트가 포함될 수 있습니다. 선택한 답변의 ID를 계속된 대화의 컨텍스트로 제공하여 후속 질문을 할 수 있습니다.

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

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should charging take?",
    answer_context=models.KnowledgeBaseAnswerContext(
        previous_qna_id=previous_answer.qna_id
    ),
    project_name="FAQ",
    deployment_name="live"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

새 프로젝트 만들기

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))
with client:

    # create project
    project_name = "IssacNewton"
    project = client.create_project(
        project_name=project_name,
        options={
            "description": "biography of Sir Issac Newton",
            "language": "en",
            "multilingualResource": True,
            "settings": {
                "defaultAnswer": "no answer"
            }
        })

    print("view created project info:")
    print("\tname: {}".format(project["projectName"]))
    print("\tlanguage: {}".format(project["language"]))
    print("\tdescription: {}".format(project["description"]))

기술 자료 추가

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"
update_sources_poller = client.begin_update_sources(
    project_name=project_name,
    sources=[
        {
            "op": "add",
            "value": {
                "displayName": "Issac Newton Bio",
                "sourceUri": "https://wikipedia.org/wiki/Isaac_Newton",
                "sourceKind": "url"
            }
        }
    ]
)
update_sources_poller.result()

# list sources
print("list project sources")
sources = client.list_sources(
    project_name=project_name
)
for source in sources:
    print("project: {}".format(source["displayName"]))
    print("\tsource: {}".format(source["source"]))
    print("\tsource Uri: {}".format(source["sourceUri"]))
    print("\tsource kind: {}".format(source["sourceKind"]))

프로젝트 배포

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"

# deploy project
deployment_poller = client.begin_deploy_project(
    project_name=project_name,
    deployment_name="production"
)
deployment_poller.result()

# list all deployments
deployments = client.list_deployments(
    project_name=project_name
)

print("view project deployments")
for d in deployments:
    print(d)

비동기 작업

위의 예제는 네임스페이스의 클라이언트를 사용하여 비동기적으로 실행할 수도 있습니다 aio .

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

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = await client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="production"
)

선택적 구성

선택적 키워드 인수는 클라이언트 및 작업별 수준에서 전달할 수 있습니다. azure-core 참조 설명서 에서는 재시도, 로깅, 전송 프로토콜 등에 사용할 수 있는 구성에 대해 설명합니다.

문제 해결

일반

Azure 질문 답변 클라이언트는 Azure Core에 정의된 예외를 발생합니다. Python SDK를 사용하여 Cognitive Language Service 질문 답변 클라이언트 라이브러리와 상호 작용하는 경우 서비스에서 반환된 오류는 REST API 요청에 대해 반환된 것과 동일한 HTTP 상태 코드에 해당합니다.

예를 들어 존재하지 않는 기술 자료 질문을 제출하면 "잘못된 요청"을 400 나타내는 오류가 반환됩니다.

from azure.core.exceptions import HttpResponseError

try:
    client.get_answers(
        question="Why?",
        project_name="invalid-knowledge-base",
        deployment_name="test"
    )
except HttpResponseError as error:
    print("Query failed: {}".format(error.message))

로깅

이 라이브러리는 로깅에 표준 로깅 라이브러리를 사용합니다. HTTP 세션(URL, 헤더 등)에 대한 기본 정보는 INFO 수준에서 기록됩니다.

요청/응답 본문 및 수정되지 않은 헤더를 포함한 자세한 DEBUG 수준 로깅은 인수가 있는 클라이언트 logging_enable 에서 사용하도록 설정할 수 있습니다.

여기에 예제가 포함된 전체 SDK 로깅 설명서를 참조 하세요.

다음 단계

샘플을 봅니 다.
질문 답변 서비스의 다양한 기능에 대해 알아봅니다.
서비스 데모를 사용해 보세요.

참여

이 라이브러리의 빌드, 테스트 및 기여에 대한 자세한 내용은 CONTRIBUTING.md 참조하세요.

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 cla.microsoft.com.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.

Impressions

Python용 Azure Cognitive Language Service 질문 답변 클라이언트 라이브러리 - 버전 1.1.0

고지 사항

시작

필수 조건

패키지 설치

클라이언트 인증

API 키 가져오기

QuestionAnsweringClient 만들기

AuthoringClient 만들기

Azure Active Directory 자격 증명을 사용하여 클라이언트 만들기

주요 개념

QuestionAnsweringClient

AuthoringClient

예제

QuestionAnsweringClient

질문하기

후속 질문하기

새 프로젝트 만들기

기술 자료 추가

프로젝트 배포

비동기 작업

선택적 구성

문제 해결

일반

로깅

다음 단계

참여

피드백

추가 리소스