Question Answering - Get Answers

參考

服務:: Azure AI Services

API 版本:: 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 (double) minimum: 0 maximum: 1	答案的最小閾值分數，值範圍從 0 到 1。
context	KnowledgeBaseAnswerContext	具有先前 QnA 資訊的內容物件。
filters	QueryFilters	根據指定的元數據清單和知識庫來源篩選 QnA。
includeUnstructuredSources	boolean	（選擇性）旗標以啟用非結構化來源的查詢。
qnaId	integer (int32)	要從知識庫擷取的確切 QnA 標識元，此字段優先於問題。
question	string	要查詢知識庫的用戶問題。
rankerType	RankerKind	要使用的排名器類型。
top	integer (int32)	要針對問題傳回的答案數目上限。
userId	string	使用者的唯一標識碼。

回應

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

安全性

Ocp-Apim-Subscription-Key

類型: apiKey
位於: header

範例

Successful query

範例要求

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
}

範例回覆

狀態碼:: 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 的 span 物件。
AnswersResult	代表問題解答清單。
enable	啟用或停用回應範圍預測。
Error	error 物件。
ErrorCode	人類可讀取的錯誤碼。
ErrorResponse	錯誤回應。
InnerErrorCode	人類可讀取的錯誤碼。
InnerErrorModel	物件，包含有關錯誤的更特定資訊。根據Microsoft一個 API 指導方針 - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses。
KnowledgeBaseAnswer	表示知識庫答案。
KnowledgeBaseAnswerContext	具有先前 QnA 資訊的內容物件。
KnowledgeBaseAnswerDialog	與 Answer 相關聯的對話方塊。
KnowledgeBaseAnswerPrompt	提示輸入答案。
LogicalOperationKind	設定為『OR』或『AND』以使用對應的邏輯作業。
MetadataFilter	尋找與指定元數據清單相關聯的 QnAs。
MetadataRecord	物件，以提供每個元數據的索引鍵值組。
QueryFilters	篩選知識庫。
RankerKind	要使用的排名器類型。
ShortAnswerOptions	若要設定回應範圍預測功能。

AnswersOptions

Object

查詢知識庫的參數。

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

AnswerSpan

Object

回答 QnA 的 span 物件。

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

AnswersResult

Object

代表問題解答清單。

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

enable

列舉型別

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

值	Description
True

Error

Object

error 物件。

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

ErrorCode

列舉型別

人類可讀取的錯誤碼。

值	Description
AzureCognitiveSearchIndexLimitReached
AzureCognitiveSearchIndexNotFound
AzureCognitiveSearchNotFound
AzureCognitiveSearchThrottling
Forbidden
InternalServerError
InvalidArgument
InvalidRequest
NotFound
OperationNotFound
ProjectNotFound
ServiceUnavailable
TooManyRequests
Unauthorized

ErrorResponse

Object

錯誤回應。

名稱	類型	Description
error	Error	error 物件。

InnerErrorCode

列舉型別

人類可讀取的錯誤碼。

值	Description
AzureCognitiveSearchNotFound
AzureCognitiveSearchThrottling
ExtractionFailure
InvalidParameterValue
InvalidRequest
KnowledgeBaseNotFound

InnerErrorModel

Object

物件，包含有關錯誤的更特定資訊。根據Microsoft一個 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

Object

表示知識庫答案。

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

KnowledgeBaseAnswerContext

Object

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

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

KnowledgeBaseAnswerDialog

Object

與 Answer 相關聯的對話方塊。

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

KnowledgeBaseAnswerPrompt

Object

提示輸入答案。

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

LogicalOperationKind

列舉型別

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

值	Description
AND
OR

MetadataFilter

Object

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

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

MetadataRecord

Object

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

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

QueryFilters

Object

篩選知識庫。

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

RankerKind

列舉型別

要使用的排名器類型。

值	Description
Default	預設排名器。
QuestionOnly	問題只有排名器。

ShortAnswerOptions

Object

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

名稱	類型	Description
confidenceScoreThreshold	number (double) minimum: 0 maximum: 1	包含答案範圍所需的最小閾值分數，值範圍從 0 到 1。
enable	enable	啟用或停用回應範圍預測。
topAnswersWithSpan	integer (int32) minimum: 1 maximum: 10	要考慮範圍預測從 1 到 10 的最上層答案數目。

共用方式為

Question Answering - Get Answers

URI 參數

要求標頭

要求本文

回應

安全性

Ocp-Apim-Subscription-Key

範例

Successful query

範例要求

範例回覆

定義

AnswersOptions

AnswerSpan

AnswersResult

enable

Error

ErrorCode

ErrorResponse

InnerErrorCode

InnerErrorModel

KnowledgeBaseAnswer

KnowledgeBaseAnswerContext

KnowledgeBaseAnswerDialog

KnowledgeBaseAnswerPrompt

LogicalOperationKind

MetadataFilter

MetadataRecord

QueryFilters

RankerKind

ShortAnswerOptions

其他資源