適用于 Python 的 Azure 認知語言服務問題回答用戶端程式庫 - 1.1.0 版

發行項
04/05/2023

問題回答是雲端式 API 服務，可讓您在現有資料上建立交談式問答層。透過從半結構化內容擷取問題和解答，包括常見問題、手動和檔，即可使用它來建置知識庫。使用您知識庫中 QnA 的最佳解答來回答使用者的問題，這會自動回答。您的知識庫也會變得更聰明，因為它會持續從使用者的行為中學習。

| 原始程式碼套件 (PyPI) | API 參考檔 | 產品檔 | 樣品

免責聲明

Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。如需詳細資訊和問題，請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691

開始使用

Prerequisites

需要 Python 3.7 或更新版本才能使用此套件。
Azure 訂用帳戶
語言服務資源

安裝套件

使用 pip安裝適用于 Python 的 Azure 問題解答用戶端程式庫：

pip install azure-ai-language-questionanswering

注意：此版本的用戶端程式庫預設為服務 API 版本 2021-10-01 。

驗證用戶端

若要與問題解答服務互動，您必須建立 QuestionAnsweringClient 類別的實例，或 AuthoringClient 的實例來管理資源內的專案。您需要端點和 API 金鑰 ，才能具現化用戶端物件。如需使用認知服務進行驗證的詳細資訊，請參閱驗證對 Azure 認知服務的要求。

取得 API 金鑰

您可以從Azure入口網站中的語言資源取得端點和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 認證建立用戶端

若要使用 Azure Active Directory (AAD) 權杖認證，請提供從 azure-identity 程式庫取得所需認證類型的實例。請注意，區域端點不支援 AAD 驗證。為您的資源建立自訂子域名稱，以使用此類型的驗證。

使用 AAD 進行驗證需要一些初始設定：

安裝 azure-identity
註冊新的 AAD 應用程式
將「認知服務語言讀取者」角色指派給您的服務主體，以授與語言服務的存取權。

設定之後，您可以從 azure.identity 選擇要使用的認證類型。例如， DefaultAzureCredential 可用來驗證用戶端：

將 AAD 應用程式的用戶端識別碼、租使用者識別碼和用戶端密碼的值設定為環境變數： 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。

範例

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

您可以設定其他關鍵字選項來限制答案數目、指定最小信賴分數等等。

詢問後續問題

如果您的知識庫已針對閒聊進行設定，則來自知識庫的答案可能包含建議的後續問題提示，以起始交談。您可以提供所選答案的識別碼作為繼續交談的內容，以詢問後續問題：

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 核心參考檔說明重試、記錄、傳輸通訊協定等可用的組態。

疑難排解

一般

Azure 問題解答用戶端會引發 Azure Core中定義的例外狀況。當您使用 Python SDK 與認知語言服務問題回答用戶端程式庫互動時，服務傳回的錯誤會對應至針對 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 層級。

您可以在具有引數的用戶端 logging_enable 上啟用詳細的 DEBUG 層級記錄，包括要求/回應主體和未處理的標頭。

如需完整的 SDK 記錄檔，請參閱這裡的範例。

下一步

檢視我們的範例。
閱讀問題解答服務的不同功能。
試用我們的服務示範。

參與

如需建置、測試和參與此程式庫的詳細資訊，請參閱 CONTRIBUTING.md 。

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資訊，請造訪 cla.microsoft.com。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

曝光數

共用方式為

適用于 Python 的 Azure 認知語言服務問題回答用戶端程式庫 - 1.1.0 版

免責聲明

開始使用

Prerequisites

安裝套件

驗證用戶端

取得 API 金鑰

建立 QuestionAnsweringClient

建立 AuthoringClient

使用 Azure Active Directory 認證建立用戶端

重要概念

QuestionAnsweringClient

AuthoringClient

範例

QuestionAnsweringClient

詢問問題

詢問後續問題

建立新專案

新增知識來源

部署您的專案

非同步作業

選用組態

疑難排解

一般

記錄

下一步

參與

其他資源