Question Answering - Get Answers

Reference

Service:: Cognitive Services

API Version:: 2021-10-01

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

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

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.