Question Answering - Get Answers

Answers the specified question using your knowledge base.

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

URI Parameters

Name In Required Type Description
Endpoint
path True

string

Supported Cognitive Services endpoint (e.g., https://.api.cognitiveservices.azure.com).

api-version
query True

string

Client API version.

deploymentName
query True

string

The name of the specific deployment of the project to use.

projectName
query True

string

The name of the project to use.

Request Header

Name Required Type Description
Ocp-Apim-Subscription-Key True

string

Request Body

Name Type Description
answerSpanRequest

ShortAnswerOptions

To configure Answer span prediction feature.

confidenceScoreThreshold

number

Minimum threshold score for answers, value ranges from 0 to 1.

context

KnowledgeBaseAnswerContext

Context object with previous QnA's information.

filters

QueryFilters

Filter QnAs based on given metadata list and knowledge base sources.

includeUnstructuredSources

boolean

(Optional) Flag to enable Query over Unstructured Sources.

qnaId

integer

Exact QnA ID to fetch from the knowledge base, this field takes priority over question.

question

string

User question to query against the knowledge base.

rankerType

RankerKind

Type of ranker to be used.

top

integer

Max number of answers to be returned for the question.

userId

string

Unique identifier for the user.

Responses

Name Type Description
200 OK

AnswersResult

A successful response to get answers from knowledge base.

Other Status Codes

ErrorResponse

Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Successful query

Sample request

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

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

Definitions

Name Description
AnswersOptions

Parameters to query a knowledge base.

AnswerSpan

Answer span object of QnA.

AnswersResult

Represents List of Question Answers.

enable

Enable or disable Answer Span prediction.

Error

The error object.

ErrorCode

Human-readable error code.

ErrorResponse

Error response.

InnerErrorCode

Human-readable error code.

InnerErrorModel

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

KnowledgeBaseAnswer

Represents knowledge base answer.

KnowledgeBaseAnswerContext

Context object with previous QnA's information.

KnowledgeBaseAnswerDialog

Dialog associated with Answer.

KnowledgeBaseAnswerPrompt

Prompt for an answer.

LogicalOperationKind

Set to 'OR' or 'AND' for using corresponding logical operation.

MetadataFilter

Find QnAs that are associated with the given list of metadata.

MetadataRecord

Object to provide the key value pair for each metadata.

QueryFilters

filters over knowledge base.

RankerKind

Type of ranker to be used.

ShortAnswerOptions

To configure Answer span prediction feature.

AnswersOptions

Parameters to query a knowledge base.

Name Type Description
answerSpanRequest

ShortAnswerOptions

To configure Answer span prediction feature.

confidenceScoreThreshold

number

Minimum threshold score for answers, value ranges from 0 to 1.

context

KnowledgeBaseAnswerContext

Context object with previous QnA's information.

filters

QueryFilters

Filter QnAs based on given metadata list and knowledge base sources.

includeUnstructuredSources

boolean

(Optional) Flag to enable Query over Unstructured Sources.

qnaId

integer

Exact QnA ID to fetch from the knowledge base, this field takes priority over question.

question

string

User question to query against the knowledge base.

rankerType

RankerKind

Type of ranker to be used.

top

integer

Max number of answers to be returned for the question.

userId

string

Unique identifier for the user.

AnswerSpan

Answer span object of QnA.

Name Type Description
confidenceScore

number

Predicted score of answer span, value ranges from 0 to 1.

length

integer

The length of the answer span.

offset

integer

The answer span offset from the start of answer.

text

string

Predicted text of answer span.

AnswersResult

Represents List of Question Answers.

Name Type Description
answers

KnowledgeBaseAnswer[]

Represents Answer Result list.

enable

Enable or disable Answer Span prediction.

Name Type Description
True

Boolean

Error

The error object.

Name Type Description
code

ErrorCode

One of a server-defined set of error codes.

details

Error[]

An array of details about specific errors that led to this reported error.

innererror

InnerErrorModel

An object containing more specific information than the current object about the error.

message

string

A human-readable representation of the error.

target

string

The target of the error.

ErrorCode

Human-readable error code.

Name Type 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

Error response.

Name Type Description
error

Error

The error object.

InnerErrorCode

Human-readable error code.

Name Type Description
AzureCognitiveSearchNotFound

string

AzureCognitiveSearchThrottling

string

ExtractionFailure

string

InvalidParameterValue

string

InvalidRequest

string

KnowledgeBaseNotFound

string

InnerErrorModel

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name Type Description
code

InnerErrorCode

One of a server-defined set of error codes.

details

object

Error details.

innererror

InnerErrorModel

An object containing more specific information than the current object about the error.

message

string

Error message.

target

string

Error target.

KnowledgeBaseAnswer

Represents knowledge base answer.

Name Type Description
answer

string

Answer text.

answerSpan

AnswerSpan

Answer span object of QnA with respect to user's question.

confidenceScore

number

Answer confidence score, value ranges from 0 to 1.

dialog

KnowledgeBaseAnswerDialog

Dialog associated with Answer.

id

integer

ID of the QnA result.

metadata

object

Metadata associated with the answer, useful to categorize or filter question answers.

questions

string[]

List of questions associated with the answer.

source

string

Source of QnA result.

KnowledgeBaseAnswerContext

Context object with previous QnA's information.

Name Type Description
previousQnaId

integer

Previous turn top answer result QnA ID.

previousUserQuery

string

Previous user query.

KnowledgeBaseAnswerDialog

Dialog associated with Answer.

Name Type Description
isContextOnly

boolean

To mark if a prompt is relevant only with a previous question or not. If true, do not include this QnA as search result for queries without context; otherwise, if false, ignores context and includes this QnA in search result.

prompts

KnowledgeBaseAnswerPrompt[]

List of prompts associated with the answer.

KnowledgeBaseAnswerPrompt

Prompt for an answer.

Name Type Description
displayOrder

integer

Index of the prompt - used in ordering of the prompts.

displayText

string

Text displayed to represent a follow up question prompt.

qnaId

integer

QnA ID corresponding to the prompt.

LogicalOperationKind

Set to 'OR' or 'AND' for using corresponding logical operation.

Name Type Description
AND

string

OR

string

MetadataFilter

Find QnAs that are associated with the given list of metadata.

Name Type Default value Description
logicalOperation

LogicalOperationKind

AND

Operation used to join metadata filters.

metadata

MetadataRecord[]

Object to provide the key value pair for each metadata.

MetadataRecord

Object to provide the key value pair for each metadata.

Name Type Description
key

string

Metadata Key from Metadata dictionary used in the QnA.

value

string

Metadata Value from Metadata dictionary used in the QnA.

QueryFilters

filters over knowledge base.

Name Type Default value Description
logicalOperation

LogicalOperationKind

AND

Logical operation used to join metadata filter with source filter.

metadataFilter

MetadataFilter

Find QnAs that are associated with the given list of metadata.

sourceFilter

string[]

Find QnAs that are associated with any of the given list of sources in knowledge base.

RankerKind

Type of ranker to be used.

Name Type Description
Default

string

Default ranker.

QuestionOnly

string

Question only ranker.

ShortAnswerOptions

To configure Answer span prediction feature.

Name Type Description
confidenceScoreThreshold

number

Minimum threshold score required to include an answer span, value ranges from 0 to 1.

enable

enable

Enable or disable Answer Span prediction.

topAnswersWithSpan

integer

Number of Top answers to be considered for span prediction from 1 to 10.