Question Answering - Get Answers

Service:: Azure AI Services

API Version:: 2023-04-01

Answers the specified question using your knowledge base.

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

URI Parameters

Name	In	Required	Type	Description
Endpoint	path	True	string (uri)	Supported Cognitive Services endpoint (e.g., https://<resource-name>.api.cognitiveservices.azure.com).
api-version	query	True	string minLength: 1	The API version to use for this operation.
deploymentName	query	True	string	The name of the specific deployment of the project to use.
projectName	query	True	string maxLength: 100 pattern: ^(?=[a-zA-Z0-9])[a-zA-Z0-9-]{0,98}[a-zA-Z0-9]$	The name of the project to use.

Request Body

Name	Type	Description
answerSpanRequest	ShortAnswerOptions	To configure Answer span prediction feature.
confidenceScoreThreshold	number (double) minimum: 0 maximum: 1	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 (int32)	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 (int32)	Max number of answers to be returned for the question.
userId	string	Unique identifier for the user.

Responses

Name	Type	Description
200 OK	AnswersResult	The request has succeeded.
Other Status Codes	ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

AnswersResult

The request has succeeded.

Other Status Codes

ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
https://cognitiveservices.azure.com/.default

Examples

Successful query

Sample request

HTTP

POST {Endpoint}/language/:query-knowledgebases?api-version=2023-04-01&projectName=proj1&deploymentName=production

{
  "answerSpanRequest": {
    "confidenceScoreThreshold": 0.2,
    "enable": true,
    "topAnswersWithSpan": 1
  },
  "confidenceScoreThreshold": 0.2,
  "context": {
    "previousQnaId": 9,
    "previousUserQuery": "Where are QnA Maker quickstarts?"
  },
  "filters": {
    "logicalOperation": "AND",
    "metadataFilter": {
      "logicalOperation": "AND",
      "metadata": [
        {
          "key": "category",
          "value": "api"
        },
        {
          "key": "editorial",
          "value": "chitchat"
        }
      ]
    },
    "sourceFilter": [
      "filename1.pdf",
      "https://www.wikipedia.org/microsoft"
    ]
  },
  "includeUnstructuredSources": true,
  "question": "how long it takes to charge surface?",
  "rankerType": "Default",
  "top": 3,
  "userId": "sd53lsY="
}

Sample response

Status code:: 200

{
  "answers": [
    {
      "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.",
      "answerSpan": {
        "confidenceScore": 0.3,
        "length": 50,
        "offset": 33,
        "text": "two to four hours"
      },
      "confidenceScore": 0.65,
      "dialog": {
        "isContextOnly": false,
        "prompts": [
          {
            "displayOrder": 1,
            "displayText": "prompt1",
            "qnaId": 23
          },
          {
            "displayOrder": 2,
            "displayText": "prompt2",
            "qnaId": 36
          }
        ]
      },
      "id": 20,
      "metadata": {
        "category": "api",
        "editorial": "chitchat"
      },
      "questions": [
        "Power and charging"
      ],
      "source": "surface-pro-4-user-guide-EN.pdf"
    },
    {
      "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,
      "questions": [
        "Charge your Surface Pro 4"
      ],
      "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.
Error	The error response object returned when the service encounters some errors during processing the request.
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

Object

Parameters to query a knowledge base.

Name	Type	Description
answerSpanRequest	ShortAnswerOptions	To configure Answer span prediction feature.
confidenceScoreThreshold	number (double) minimum: 0 maximum: 1	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 (int32)	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 (int32)	Max number of answers to be returned for the question.
userId	string	Unique identifier for the user.

AnswerSpan

Object

Answer span object of QnA.

Name	Type	Description
confidenceScore	number (double) minimum: 0 maximum: 1	Predicted score of answer span, value ranges from 0 to 1.
length	integer (int32)	The length of the answer span.
offset	integer (int32)	The answer span offset from the start of answer.
text	string	Predicted text of answer span.

AnswersResult

Object

Represents List of Question Answers.

Name	Type	Description
answers	KnowledgeBaseAnswer[]	Represents Answer Result list.

Error

Object

The error response object returned when the service encounters some errors during processing the request.

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

Enumeration

Human-readable error code.

Value	Description
InvalidRequest	Invalid request error
InvalidArgument	Invalid argument error
Unauthorized	Unauthorized access error
Forbidden	Forbidden access error
NotFound	Not found error
ProjectNotFound	Project not found error
OperationNotFound	Operation not found error
AzureCognitiveSearchNotFound	Azure Cognitive Search not found error
AzureCognitiveSearchIndexNotFound	Azure Cognitive Search index not found error
TooManyRequests	Too many requests error
AzureCognitiveSearchThrottling	Azure Cognitive Search throttling error
AzureCognitiveSearchIndexLimitReached	Azure Cognitive Search index limit reached error
InternalServerError	Internal server error
ServiceUnavailable	Service unavailable error
Timeout	Timeout error
QuotaExceeded	Quota exceeded error
Conflict	Conflict error
Warning	Warning error

ErrorResponse

Object

Error response.

Name	Type	Description
error	Error	The error object.

InnerErrorCode

Enumeration

Human-readable error code.

Value	Description
InvalidRequest	Invalid request error
InvalidParameterValue	Invalid parameter value error
KnowledgeBaseNotFound	Knowledge base not found error
AzureCognitiveSearchNotFound	Azure Cognitive Search not found error
AzureCognitiveSearchThrottling	Azure Cognitive Search throttling error
ExtractionFailure	Extraction failure error
InvalidRequestBodyFormat	Invalid request body format error
EmptyRequest	Empty request error
MissingInputDocuments	Missing input documents error
InvalidDocument	Invalid document error
ModelVersionIncorrect	Model version incorrect error
InvalidDocumentBatch	Invalid document batch error
UnsupportedLanguageCode	Unsupported language code error
InvalidCountryHint	Invalid country hint error

InnerErrorModel

Object

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

Object

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 (double) minimum: 0 maximum: 1	Answer confidence score, value ranges from 0 to 1.
dialog	KnowledgeBaseAnswerDialog	Dialog associated with Answer.
id	integer (int32)	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

Object

Context object with previous QnA's information.

Name	Type	Description
previousQnaId	integer (int32)	Previous turn top answer result QnA ID.
previousUserQuery	string	Previous user query.

KnowledgeBaseAnswerDialog

Object

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

Object

Prompt for an answer.

Name	Type	Description
displayOrder	integer (int32)	Index of the prompt - used in ordering of the prompts.
displayText	string maxLength: 200	Text displayed to represent a follow up question prompt.
qnaId	integer (int32)	QnA ID corresponding to the prompt.

LogicalOperationKind

Enumeration

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

Value	Description
AND	'AND' for using corresponding logical operation.
OR	Set 'OR' for using corresponding logical operation.

MetadataFilter

Object

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

Name	Type	Description
logicalOperation	LogicalOperationKind	Operation used to join metadata filters.
metadata	MetadataRecord[]	Dictionary of string

MetadataRecord

Object

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

Object

filters over knowledge base.

Name	Type	Description
logicalOperation	LogicalOperationKind	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

Enumeration

Type of ranker to be used.

Value	Description
QuestionOnly	Question only ranker.
Default	Default ranker.

ShortAnswerOptions

Object

To configure Answer span prediction feature.

Name	Type	Description
confidenceScoreThreshold	number (double) minimum: 0 maximum: 1	Minimum threshold score required to include an answer span, value ranges from 0 to 1.
enable	boolean	Enable or disable Answer Span prediction.
topAnswersWithSpan	integer (int32) minimum: 1 maximum: 10	Number of Top answers to be considered for span prediction from 1 to 10.

Share via

Question Answering - Get Answers

URI Parameters

Request Body

Responses

Security

Ocp-Apim-Subscription-Key

OAuth2Auth

Scopes

Examples

Successful query

Sample request

Sample response

Definitions

AnswersOptions

AnswerSpan

AnswersResult

Error

ErrorCode

ErrorResponse

InnerErrorCode

InnerErrorModel

KnowledgeBaseAnswer

KnowledgeBaseAnswerContext

KnowledgeBaseAnswerDialog

KnowledgeBaseAnswerPrompt

LogicalOperationKind

MetadataFilter

MetadataRecord

QueryFilters

RankerKind

ShortAnswerOptions