共用方式為


Question Answering - Get Answers

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

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

範例要求

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
}

範例回覆

{
  "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

查詢知識庫的參數。

名稱 類型 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

回答 QnA 的 span 物件。

名稱 類型 Description
confidenceScore

number (double)

minimum: 0
maximum: 1

答案範圍的預測分數,值範圍從 0 到 1。

length

integer (int32)

答案範圍的長度。

offset

integer (int32)

答案範圍與答案開頭的位移。

text

string

答案範圍的預測文字。

AnswersResult

代表問題解答清單。

名稱 類型 Description
answers

KnowledgeBaseAnswer[]

代表答案結果清單。

enable

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

Description
True

Error

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

錯誤回應。

名稱 類型 Description
error

Error

error 物件。

InnerErrorCode

人類可讀取的錯誤碼。

Description
AzureCognitiveSearchNotFound
AzureCognitiveSearchThrottling
ExtractionFailure
InvalidParameterValue
InvalidRequest
KnowledgeBaseNotFound

InnerErrorModel

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

表示知識庫答案。

名稱 類型 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

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

名稱 類型 Description
previousQnaId

integer (int32)

上一個回合最上層答案結果 QnA 識別碼。

previousUserQuery

string

先前的用戶查詢。

KnowledgeBaseAnswerDialog

與 Answer 相關聯的對話方塊。

名稱 類型 Description
isContextOnly

boolean

若要標記提示是否只與先前的問題相關。 如果為 true,請勿將此 QnA 包含為沒有內容之查詢的搜尋結果;否則,如果為 false,則會忽略內容,並在搜尋結果中包含此 QnA。

prompts

KnowledgeBaseAnswerPrompt[]

與答案相關聯的提示清單。

KnowledgeBaseAnswerPrompt

提示輸入答案。

名稱 類型 Description
displayOrder

integer (int32)

提示的索引 - 用於提示的順序。

displayText

string

maxLength: 200

顯示來代表後續問題提示的文字。

qnaId

integer (int32)

對應至提示的 QnA 識別碼。

LogicalOperationKind

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

Description
AND
OR

MetadataFilter

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

名稱 類型 預設值 Description
logicalOperation

LogicalOperationKind

AND

用來聯結元數據篩選的作業。

metadata

MetadataRecord[]

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

MetadataRecord

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

名稱 類型 Description
key

string

QnA 中使用的元數據字典中的元數據索引鍵。

value

string

QnA 中使用的元數據字典中的元數據值。

QueryFilters

篩選知識庫。

名稱 類型 預設值 Description
logicalOperation

LogicalOperationKind

AND

用來將元數據篩選與來源篩選聯結的邏輯作業。

metadataFilter

MetadataFilter

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

sourceFilter

string[]

尋找與知識庫中任何指定來源清單相關聯的 QnA。

RankerKind

要使用的排名器類型。

Description
Default

預設排名器。

QuestionOnly

問題只有排名器。

ShortAnswerOptions

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

名稱 類型 Description
confidenceScoreThreshold

number (double)

minimum: 0
maximum: 1

包含答案範圍所需的最小閾值分數,值範圍從 0 到 1。

enable

enable

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

topAnswersWithSpan

integer (int32)

minimum: 1
maximum: 10

要考慮範圍預測從 1 到 10 的最上層答案數目。