Python 用 Azure Cognitive Language Service 質問応答クライアント ライブラリ - バージョン 1.1.0

質問応答は、既存のデータに対して会話型の質問と回答レイヤーを作成できるクラウドベースの 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 Question Answering クライアント ライブラリをインストールします。

pip install azure-ai-language-questionanswering

注: このバージョンのクライアント ライブラリの既定値は、サービス API バージョン 2021-10-01です。

クライアントを認証する

質問応答サービスを操作するには、 QuestionAnsweringClient クラスのインスタンス、またはリソース内のプロジェクトを管理するための AuthoringClient の インスタンスを作成する必要があります。 クライアント オブジェクトをインスタンス化するには、 エンドポイントと API キー が必要です。 Cognitive Services を使用した認証の詳細については、「 Azure Cognitive Services への要求を認証する」を参照してください。

API キーを取得する

エンドポイントと API キーは、Azure Portal の言語リソースから取得できます。

または、次に示す 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 アプリケーションを登録する
• "Cognitive Services 言語閲覧者" ロールをサービス プリンシパルに割り当てることで、言語サービスへのアクセス権を付与します。

セットアップ後、使用する azure.identity から 資格情報 の種類を選択できます。 たとえば、 DefaultAzureCredential を使用してクライアントを認証できます。

AAD アプリケーションのクライアント ID、テナント ID、およびクライアント シークレットの値を環境変数として設定します。 AZURE_CLIENT_IDAZURE_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 と非同期 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 Question Answering クライアントでは、 Azure Core で定義されている例外が発生します。 Python SDK を使用して Cognitive Language Service 質問応答クライアント ライブラリを操作する場合、サービスによって返されるエラーは、 REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。

たとえば、存在しないサポート情報に質問を送信すると、400"Bad Request" を示すエラーが返されます。

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) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。