Question Answering - Get Answers

Service:

Cognitive Services

API Version:

2021-10-01

使用您的 知識庫 回答指定的問題。

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

URI 參數

名稱	位於	必要	類型	Description
Endpoint	path	True	string	支援的認知服務端點 (例如 https://.api.cognitiveservices.azure.com).
api-version	query	True	string	用戶端 API 版本。
deploymentName	query	True	string	要使用的專案特定部署名稱。
projectName	query	True	string	要使用的項目名稱。

要求標頭

名稱	必要	類型	Description
Ocp-Apim-Subscription-Key	True	string

要求本文

名稱	類型	Description
answerSpanRequest	ShortAnswerOptions	若要設定回應範圍預測功能。
confidenceScoreThreshold	number	答案的最小閾值分數，值範圍從 0 到 1。
context	KnowledgeBaseAnswerContext	具有先前 QnA 資訊的內容物件。
filters	QueryFilters	根據指定的元數據清單和 知識庫 來源篩選 QnA。
includeUnstructuredSources	boolean	(選擇性) 旗標，以啟用非結構化來源的查詢。
qnaId	integer	要從 知識庫 擷取的確切 QnA 識別元，此欄位優先於問題。
question	string	要查詢 知識庫 的用戶問題。
rankerType	RankerKind	要使用的排名器類型。
top	integer	要針對問題傳回的答案數目上限。
userId	string	使用者的唯一標識碼。

回應

名稱	類型	Description
200 OK	AnswersResult	從 知識庫 取得答案的成功回應。
Other Status Codes	ErrorResponse	錯誤回應。

安全性

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

範例

Successful query

Sample Request

HTTP

POST {Endpoint}/language/:query-knowledgebases?projectName=proj1&deploymentName=production&api-version=2021-10-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"
    }
  ]
}

定義

名稱	Description
AnswersOptions	查詢 知識庫的參數。
AnswerSpan	QnA 的回應範圍物件。
AnswersResult	代表問題解答的清單。
enable	啟用或停用回應範圍預測。
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

查詢 知識庫的參數。

名稱	類型	Description
answerSpanRequest	ShortAnswerOptions	若要設定回應範圍預測功能。
confidenceScoreThreshold	number	答案的最小閾值分數，值範圍從 0 到 1。
context	KnowledgeBaseAnswerContext	具有先前 QnA 資訊的內容物件。
filters	QueryFilters	根據指定的元數據清單和 知識庫 來源篩選 QnA。
includeUnstructuredSources	boolean	(選擇性) 旗標，以啟用非結構化來源的查詢。
qnaId	integer	要從 知識庫 擷取的確切 QnA 識別元，此欄位優先於問題。
question	string	要查詢 知識庫 的用戶問題。
rankerType	RankerKind	要使用的排名器類型。
top	integer	要針對問題傳回的答案數目上限。
userId	string	使用者的唯一標識碼。

AnswerSpan

QnA 的回應範圍物件。

名稱	類型	Description
confidenceScore	number	答案範圍的預測分數，值範圍從 0 到 1。
length	integer	答案範圍的長度。
offset	integer	答案範圍與答案開頭的位移。
text	string	答案範圍的預測文字。

AnswersResult

代表問題解答的清單。

名稱	類型	Description
answers	KnowledgeBaseAnswer[]	代表答案結果清單。

enable

啟用或停用回應範圍預測。

名稱	類型	Description
True	Boolean

Error

錯誤物件。

名稱	類型	Description
code	ErrorCode	其中一組伺服器定義的錯誤碼。
details	Error[]	導致此錯誤之特定錯誤的詳細數據陣列。
innererror	InnerErrorModel	物件，包含比目前對象有關錯誤的更特定資訊。
message	string	人類看得懂的錯誤表示法。
target	string	錯誤的目標。

ErrorCode

人類可讀取的錯誤碼。

名稱	類型	Description
AzureCognitiveSearchIndexLimitReached	string
AzureCognitiveSearchIndexNotFound	string
AzureCognitiveSearchNotFound	string
AzureCognitiveSearchThrottling	string
Forbidden	string
InternalServerError	string
InvalidArgument	string
InvalidRequest	string
NotFound	string
OperationNotFound	string
ProjectNotFound	string
ServiceUnavailable	string
TooManyRequests	string
Unauthorized	string

ErrorResponse

錯誤回應。

名稱	類型	Description
error	Error	錯誤物件。

InnerErrorCode

人類可讀取的錯誤碼。

名稱	類型	Description
AzureCognitiveSearchNotFound	string
AzureCognitiveSearchThrottling	string
ExtractionFailure	string
InvalidParameterValue	string
InvalidRequest	string
KnowledgeBaseNotFound	string

InnerErrorModel

物件，包含有關錯誤的更特定資訊。 根據 Microsoft One API 指導方針 - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses。

名稱	類型	Description
code	InnerErrorCode	其中一組伺服器定義的錯誤碼。
details	object	錯誤詳細數據。
innererror	InnerErrorModel	物件，包含比目前對象有關錯誤的更特定資訊。
message	string	錯誤訊息。
target	string	錯誤目標。

KnowledgeBaseAnswer

代表 知識庫 答案。

名稱	類型	Description
answer	string	回答文字。
answerSpan	AnswerSpan	針對用戶的問題回答 QnA 範圍物件。
confidenceScore	number	回答信賴分數，值範圍從 0 到 1。
dialog	KnowledgeBaseAnswerDialog	與答案相關聯的對話框。
id	integer	QnA 結果的標識碼。
metadata	object	與答案相關聯的元數據，適用於分類或篩選問題解答。
questions	string[]	與答案相關聯的問題清單。
source	string	QnA 結果的來源。

KnowledgeBaseAnswerContext

具有先前 QnA 資訊的內容物件。

名稱	類型	Description
previousQnaId	integer	上一個回合頂端答案結果 QnA 識別碼。
previousUserQuery	string	先前的用戶查詢。

KnowledgeBaseAnswerDialog

與答案相關聯的對話框。

名稱	類型	Description
isContextOnly	boolean	若要標示提示是否只與先前的問題相關。 如果為 true，請勿將此 QnA 納入為沒有內容之查詢的搜尋結果;否則，如果為 false，則會忽略內容，並在搜尋結果中包含此 QnA。
prompts	KnowledgeBaseAnswerPrompt[]	與答案相關聯的提示清單。

KnowledgeBaseAnswerPrompt

提示輸入答案。

名稱	類型	Description
displayOrder	integer	提示的索引 - 用於提示的順序。
displayText	string	顯示來表示後續問題提示的文字。
qnaId	integer	對應至提示的 QnA 識別碼。

LogicalOperationKind

將 設定為 『OR』 或 'AND'，以使用對應的邏輯作業。

名稱	類型	Description
AND	string
OR	string

MetadataFilter

尋找與指定元數據清單相關聯的 QnA。

名稱	類型	預設值	Description
logicalOperation	LogicalOperationKind	AND	用來聯結元數據篩選的作業。
metadata	MetadataRecord[]		物件，提供每個元數據的索引鍵值組。

MetadataRecord

物件，提供每個元數據的索引鍵值組。

名稱	類型	Description
key	string	QnA 中使用的元數據字典中的元數據金鑰。
value	string	QnA 中使用的元數據字典中的元數據值。

QueryFilters

篩選 知識庫。

名稱	類型	預設值	Description
logicalOperation	LogicalOperationKind	AND	用來聯結元數據篩選與來源篩選的邏輯作業。
metadataFilter	MetadataFilter		尋找與指定元數據清單相關聯的 QnA。
sourceFilter	string[]		尋找與 知識庫 中任何指定來源清單相關聯的 QnA。

RankerKind

要使用的排名器類型。

名稱	類型	Description
Default	string	預設排名器。
QuestionOnly	string	只有排名器的問題。

ShortAnswerOptions

若要設定回應範圍預測功能。

名稱	類型	Description
confidenceScoreThreshold	number	包含答案範圍所需的最小閾值分數，值範圍從 0 到 1。
enable	enable	啟用或停用回應範圍預測。
topAnswersWithSpan	integer	要視為範圍預測從 1 到 10 的前幾個答案數目。