Question Answering - Get Answers

リファレンス

Service:: Cognitive Services - Language

API Version:: 2023-04-01

サポート情報を使用して、指定した質問に回答します。

POST {Endpoint}/language/:query-knowledgebases?projectName={projectName}&deploymentName={deploymentName}&api-version=2023-04-01

URI パラメーター

名前	/	必須	型	説明
Endpoint	path	True	string	サポートされている Cognitive Services エンドポイント (例: https://.api.cognitiveservices.azure.com).
api-version	query	True	string	クライアント API バージョン。
deploymentName	query	True	string	使用するプロジェクトの特定の配置の名前。
projectName	query	True	string	使用するプロジェクトの名前。

要求本文

名前	型	説明
answerSpanRequest	ShortAnswerOptions	応答スパン予測機能を構成するには。
confidenceScoreThreshold	number	回答の最小しきい値スコア。値の範囲は 0 から 1 です。
context	KnowledgeBaseAnswerContext	前の QnA の情報を持つコンテキストオブジェクト。
filters	QueryFilters	特定のメタデータリストとサポート情報ソースに基づいて QnA をフィルター処理します。
includeUnstructuredSources	boolean	(省略可能)非構造化ソースに対するクエリを有効にするフラグ。
qnaId	integer	サポート情報からフェッチする正確な QnA ID。このフィールドは質問よりも優先されます。
question	string	サポート情報に対してクエリを実行するユーザーの質問。
rankerType	RankerKind	使用するランカーの種類。
top	integer	質問に返される回答の最大数。
userId	string	ユーザーの一意識別子。

応答

名前	型	説明
200 OK	AnswersResult	サポート情報から回答を取得するための成功した応答。
Other Status Codes	ErrorResponse	エラー応答。

セキュリティ

AADToken

これらは Azure Active Directory OAuth2 フローです。 Azure ロールベースのアクセス制御と組み合わせて使用すると、Azure Maps REST API へのアクセスを制御できます。 Azure ロールベースのアクセス制御は、1 つ以上のAzure Mapsリソースアカウントまたはサブリソースへのアクセスを指定するために使用されます。 REST API に対する 1 つ以上のアクセス許可で構成される組み込みロールまたはカスタムロールを使用して、任意のユーザー、グループ、またはサービスプリンシパルにアクセス権 Azure Mapsを付与できます。

シナリオを実装するには、認証の概念を表示することをお勧めします。要約すると、このセキュリティ定義は、特定の API とスコープに対するアクセス制御が可能なオブジェクトを使用してアプリケーションをモデル化するためのソリューションを提供します。

メモ

このセキュリティ定義では、ヘッダーを使用して、x-ms-client-idアプリケーションがアクセスを要求しているリソースAzure Maps示す必要があります。これは、 Maps 管理 API から取得できます。

Authorization URLは、Azure パブリッククラウドインスタンスに固有です。ソブリンクラウドには、一意の承認 URL と Azure Active Directory 構成があります。 * Azure ロールベースのアクセス制御は、Azure portal、PowerShell、CLI、Azure SDK、または REST API を介して Azure 管理プレーンから構成されます。 * Azure Maps Web SDK を使用すると、複数のユースケースに対してアプリケーションを構成ベースで設定できます。

現在、Azure Active Directory v1.0 または v2.0 は職場、学校、ゲストをサポートしていますが、個人用アカウントはサポートしていません。

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

名前	説明
https://cognitiveservices.azure.com/.default	https://cognitiveservices.azure.com/.default

Ocp-Apim-Subscription-Key

言語サービスリソースのサブスクリプションキー。

Type: apiKey
In: header

例

Successful query

Sample Request

HTTP

POST {Endpoint}/language/:query-knowledgebases?projectName=proj1&deploymentName=production&api-version=2023-04-01

{
  "question": "how long it takes to charge surface?",
  "top": 3,
  "userId": "sd53lsY=",
  "confidenceScoreThreshold": 0.2,
  "context": {
    "previousQnaId": 9,
    "previousUserQuery": "Where are QnA Maker quickstarts?"
  },
  "rankerType": "Default",
  "filters": {
    "metadataFilter": {
      "metadata": [
        {
          "key": "category",
          "value": "api"
        },
        {
          "key": "editorial",
          "value": "chitchat"
        }
      ],
      "logicalOperation": "AND"
    },
    "sourceFilter": [
      "filename1.pdf",
      "https://www.wikipedia.org/microsoft"
    ],
    "logicalOperation": "AND"
  },
  "answerSpanRequest": {
    "enable": true,
    "confidenceScoreThreshold": 0.2,
    "topAnswersWithSpan": 1
  },
  "includeUnstructuredSources": true
}

Sample Response

Status code:: 200

{
  "answers": [
    {
      "questions": [
        "Power and charging"
      ],
      "answer": "Power and charging**\n\nIt 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.\n\nYou 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.65,
      "id": 20,
      "source": "surface-pro-4-user-guide-EN.pdf",
      "metadata": {
        "category": "api",
        "editorial": "chitchat"
      },
      "dialog": {
        "isContextOnly": false,
        "prompts": [
          {
            "displayOrder": 1,
            "qnaId": 23,
            "displayText": "prompt1"
          },
          {
            "displayOrder": 2,
            "qnaId": 36,
            "displayText": "prompt2"
          }
        ]
      },
      "answerSpan": {
        "text": "two to four hours",
        "confidenceScore": 0.3,
        "offset": 33,
        "length": 50
      }
    },
    {
      "questions": [
        "Charge your Surface Pro 4"
      ],
      "answer": "**Charge your Surface Pro 4**\n\n1.  Connect the two parts of the power cord.\n\n2.  Connect the power cord securely to the charging port.\n\n3.  Plug the power supply into an electrical outlet.",
      "confidenceScore": 0.32,
      "id": 13,
      "source": "surface-pro-4-user-guide-EN.pdf"
    }
  ]
}

定義

名前	説明
AnswersOptions	サポート情報に対してクエリを実行するパラメーター。
AnswerSpan	QnA の応答スパンオブジェクト。
AnswersResult	質問の回答の一覧を表します。
enable	応答スパン予測を有効または無効にします。
Error	error オブジェクト。
ErrorCode	人間が判読できるエラーコード。
ErrorResponse	エラー応答。
InnerErrorCode	人間が判読できるエラーコード。
InnerErrorModel	エラーに関するより具体的な情報を含むオブジェクト。 Microsoft One API のガイドラインに従って - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses。
KnowledgeBaseAnswer	回答サポート情報表します。
KnowledgeBaseAnswerContext	前の QnA の情報を持つコンテキストオブジェクト。
KnowledgeBaseAnswerDialog	回答に関連付けられているダイアログ。
KnowledgeBaseAnswerPrompt	回答を求めます。
LogicalOperationKind	対応する論理操作を使用するには、'OR' または 'AND' に設定します。
MetadataFilter	指定されたメタデータの一覧に関連付けられている QnA を検索します。
MetadataRecord	各メタデータのキー値ペアを提供するオブジェクト。
QueryFilters	サポート情報をフィルター処理します。
RankerKind	使用するランカーの種類。
ShortAnswerOptions	応答スパン予測機能を構成するには。

AnswersOptions

サポート情報に対してクエリを実行するパラメーター。

名前	型	説明
answerSpanRequest	ShortAnswerOptions	応答スパン予測機能を構成するには。
confidenceScoreThreshold	number	回答の最小しきい値スコア。値の範囲は 0 から 1 です。
context	KnowledgeBaseAnswerContext	前の QnA の情報を持つコンテキストオブジェクト。
filters	QueryFilters	特定のメタデータリストとサポート情報ソースに基づいて QnA をフィルター処理します。
includeUnstructuredSources	boolean	(省略可能)非構造化ソースに対するクエリを有効にするフラグ。
qnaId	integer	サポート情報からフェッチする正確な QnA ID。このフィールドは質問よりも優先されます。
question	string	サポート情報に対してクエリを実行するユーザーの質問。
rankerType	RankerKind	使用するランカーの種類。
top	integer	質問に返される回答の最大数。
userId	string	ユーザーの一意識別子。

AnswerSpan

QnA の応答スパンオブジェクト。

名前	型	説明
confidenceScore	number	回答スパンの予測スコア。値の範囲は 0 から 1 です。
length	integer	回答スパンの長さ。
offset	integer	回答範囲は、回答の先頭からオフセットされます。
text	string	回答スパンの予測テキスト。

AnswersResult

質問の回答の一覧を表します。

名前	型	説明
answers	KnowledgeBaseAnswer[]	回答の結果の一覧を表します。

enable

応答スパン予測を有効または無効にします。

名前	型	説明
True	Boolean

Error

error オブジェクト。

名前	型	説明
code	ErrorCode	サーバー定義のエラーコードのセットの 1 つ。
details	Error[]	この報告されたエラーの原因となった特定のエラーに関する詳細の配列。
innererror	InnerErrorModel	エラーに関する現在のオブジェクトよりも具体的な情報を含むオブジェクト。
message	string	エラーの人間が判読できる表現。
target	string	エラーのターゲット。

ErrorCode

人間が判読できるエラーコード。

名前	型	説明
AzureCognitiveSearchIndexLimitReached	string
AzureCognitiveSearchIndexNotFound	string
AzureCognitiveSearchNotFound	string
AzureCognitiveSearchThrottling	string
Conflict	string
Forbidden	string
InternalServerError	string
InvalidArgument	string
InvalidRequest	string
NotFound	string
OperationNotFound	string
ProjectNotFound	string
QuotaExceeded	string
ServiceUnavailable	string
Timeout	string
TooManyRequests	string
Unauthorized	string
Warning	string

ErrorResponse

エラー応答。

名前	型	説明
error	Error	error オブジェクト。

InnerErrorCode

人間が判読できるエラーコード。

名前	型	説明
AzureCognitiveSearchNotFound	string
AzureCognitiveSearchThrottling	string
EmptyRequest	string
ExtractionFailure	string
InvalidCountryHint	string
InvalidDocument	string
InvalidDocumentBatch	string
InvalidParameterValue	string
InvalidRequest	string
InvalidRequestBodyFormat	string
KnowledgeBaseNotFound	string
MissingInputDocuments	string
ModelVersionIncorrect	string
UnsupportedLanguageCode	string

InnerErrorModel

エラーに関するより具体的な情報を含むオブジェクト。 Microsoft One API のガイドラインに従って - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses。

名前	型	説明
code	InnerErrorCode	サーバー定義のエラーコードのセットの 1 つ。
details	object	エラーの詳細。
innererror	InnerErrorModel	エラーに関する現在のオブジェクトよりも具体的な情報を含むオブジェクト。
message	string	エラーメッセージ。
target	string	エラーターゲット。

KnowledgeBaseAnswer

回答サポート情報表します。

名前	型	説明
answer	string	回答テキスト。
answerSpan	AnswerSpan	ユーザーの質問に関する QnA の回答スパンオブジェクト。
confidenceScore	number	回答信頼度スコア。値の範囲は 0 から 1 です。
dialog	KnowledgeBaseAnswerDialog	回答に関連付けられているダイアログ。
id	integer	QnA 結果の ID。
metadata	object	回答に関連付けられたメタデータ。質問の回答を分類またはフィルター処理するのに役立ちます。
questions	string[]	回答に関連付けられている質問の一覧。
source	string	QnA 結果のソース。

KnowledgeBaseAnswerContext

前の QnA の情報を持つコンテキストオブジェクト。

名前	型	説明
previousQnaId	integer	前のターントップ回答の結果 QnA ID。
previousUserQuery	string	以前のユーザークエリ。

KnowledgeBaseAnswerDialog

回答に関連付けられているダイアログ。

名前	型	説明
isContextOnly	boolean	プロンプトが前の質問にのみ関連するかどうかをマークする。 true の場合、コンテキストのないクエリの検索結果としてこの QnA を含めないでください。それ以外の場合、false の場合はコンテキストが無視され、この QnA が検索結果に含まれます。
prompts	KnowledgeBaseAnswerPrompt[]	回答に関連付けられているプロンプトの一覧。

KnowledgeBaseAnswerPrompt

回答を求めます。

名前	型	説明
displayOrder	integer	プロンプトのインデックス - プロンプトの順序で使用されます。
displayText	string	フォローアップの質問プロンプトを表すテキストが表示されます。
qnaId	integer	プロンプトに対応する QnA ID。

LogicalOperationKind

対応する論理操作を使用するには、'OR' または 'AND' に設定します。

名前	型	説明
AND	string
OR	string

MetadataFilter

指定されたメタデータの一覧に関連付けられている QnA を検索します。

名前	型	既定値	説明
logicalOperation	LogicalOperationKind	AND	メタデータフィルターを結合するために使用される操作。
metadata	MetadataRecord[]		各メタデータのキー値ペアを提供するオブジェクト。

MetadataRecord

各メタデータのキー値ペアを提供するオブジェクト。

名前	型	説明
key	string	QnA で使用されるメタデータディクショナリのメタデータキー。
value	string	QnA で使用されるメタデータディクショナリからのメタデータ値。

QueryFilters

サポート情報をフィルター処理します。

名前	型	既定値	説明
logicalOperation	LogicalOperationKind	AND	メタデータフィルターとソースフィルターを結合するために使用される論理操作。
metadataFilter	MetadataFilter		指定されたメタデータの一覧に関連付けられている QnA を検索します。
sourceFilter	string[]		サポート情報で、指定されたソースの一覧のいずれかに関連付けられている QnA を見つけます。

RankerKind

使用するランカーの種類。

名前	型	説明
Default	string	既定のランカー。
QuestionOnly	string	質問専用ランカー。

ShortAnswerOptions

応答スパン予測機能を構成するには。

名前	型	説明
confidenceScoreThreshold	number	回答スパンを含めるために必要な最小しきい値スコア。値の範囲は 0 から 1 です。
enable	enable	応答スパン予測を有効または無効にします。
topAnswersWithSpan	integer	スパン予測で考慮する上位の回答の数 (1 から 10)。

次の方法で共有