Microsoft Azure Microsoft Cognitive Language Service Question Answering uses advanced natural language processing techniques and machine learning algorithms to analyze and understand text-based questions and provide accurate responses. This service leverages deep learning models to extract key information from the input text and generate relevant answers based on the context of the query.
swagger: '2.0'
info:
title: Microsoft Azure Microsoft Cognitive Language Service - Question Answering
description: >-
The language service API is a suite of natural language processing (NLP)
skills built with best-in-class Microsoft machine learning algorithms. The
API can be used to analyze unstructured text for tasks such as sentiment
analysis, key phrase extraction, language detection and question answering.
Further documentation can be found in <a
href="https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview">https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview</a>.
version: 2023-04-15-preview
securityDefinitions:
AADToken:
type: oauth2
authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
flow: implicit
description: >-
These are the [Azure Active Directory
OAuth2](https://docs.microsoft.com/azure/active-directory/develop/v1-overview)
Flows. When paired with [Azure role-based
access](https://docs.microsoft.com/azure/role-based-access-control/overview)
control it can be used to control access to Azure Maps REST APIs. Azure
role-based access controls are used to designate access to one or more
Azure Maps resource account or sub-resources. Any user, group, or service
principal can be granted access via a built-in role or a custom role
composed of one or more permissions to Azure Maps REST APIs.
To implement scenarios, we recommend viewing [authentication
concepts](https://aka.ms/amauth). In summary, this security definition
provides a solution for modeling application(s) via objects capable of
access control on specific APIs and scopes.
#### Notes
* This security definition **requires** the use of the `x-ms-client-id`
header to indicate which Azure Maps resource the application is requesting
access to. This can be acquired from the [Maps management
API](https://aka.ms/amauthdetails).
*
The `Authorization URL` is specific to the Azure public cloud instance.
Sovereign clouds have unique Authorization URLs and Azure Active directory
configurations.
*
The Azure role-based access control is configured from the [Azure
management plane](https://aka.ms/amrbac) via Azure portal, PowerShell,
CLI, Azure SDKs, or REST APIs.
*
Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for
configuration based setup of an application for multiple use cases.
* Currently, Azure Active Directory [v1.0 or
v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison)
supports Work, School, and Guests but does not support Personal accounts.
scopes:
https://cognitiveservices.azure.com/.default: https://cognitiveservices.azure.com/.default
apim_key:
type: apiKey
description: A subscription key for a Language service resource.
name: Ocp-Apim-Subscription-Key
in: header
security:
- AADToken:
- https://cognitiveservices.azure.com/.default
- apim_key: []
x-ms-parameterized-host:
hostTemplate: '{Endpoint}/language'
useSchemePrefix: false
parameters:
- $ref: common.json#/parameters/Endpoint
paths:
/:query-knowledgebases:
post:
summary: 'Microsoft Azure Answers The Specified Question Using Your Knowledge Base'
operationId: microsoftAzureQuestionansweringGetanswers
parameters:
- $ref: '#/parameters/AnswersOptions'
- $ref: common.json#/parameters/ProjectNameQueryParameter
- $ref: common.json#/parameters/DeploymentNameQueryParameter
- $ref: common.json#/parameters/ApiVersionParameter
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: A successful response to get answers from knowledge base.
schema:
$ref: '#/definitions/AnswersResult'
default:
description: Error response.
schema:
$ref: common.json#/definitions/ErrorResponse
x-ms-examples:
Successful query:
$ref: ./examples/questionanswering/SuccessfulQueryKnowledgebases.json
description: Needs a more full description created.
tags:
- :Query Knowledgebases
/:query-text:
post:
summary: 'Microsoft Azure Answers The Specified Question Using The Provided Text In The Body'
operationId: microsoftAzureQuestionansweringGetanswersfromtext
parameters:
- $ref: '#/parameters/AnswersFromTextOptions'
- $ref: common.json#/parameters/ApiVersionParameter
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: A successful response to get answers from input text.
schema:
$ref: '#/definitions/AnswersFromTextResult'
default:
description: Error response.
schema:
$ref: common.json#/definitions/ErrorResponse
x-ms-examples:
Successful query:
$ref: ./examples/questionanswering/SuccessfulQueryText.json
description: Needs a more full description created.
tags:
- :Query Text
definitions:
AnswersOptions:
type: object
description: Parameters to query a knowledge base.
additionalProperties: false
properties:
qnaId:
type: integer
description: >-
Exact QnA ID to fetch from the knowledge base, this field takes
priority over question.
format: int32
question:
type: string
description: User question to query against the knowledge base.
top:
type: integer
description: Max number of answers to be returned for the question.
format: int32
userId:
type: string
description: Unique identifier for the user.
confidenceScoreThreshold:
type: number
format: double
x-ms-client-name: confidenceThreshold
description: Minimum threshold score for answers, value ranges from 0 to 1.
maximum: 1
minimum: 0
context:
x-ms-client-name: answerContext
description: Context object with previous QnA's information.
$ref: '#/definitions/KnowledgeBaseAnswerContext'
rankerType:
type: string
x-ms-client-name: rankerKind
description: Type of ranker to be used.
x-ms-enum:
name: RankerKind
modelAsString: true
values:
- value: QuestionOnly
description: Question only ranker.
- value: Default
description: Default ranker.
enum:
- Default
- QuestionOnly
filters:
description: Filter QnAs based on given metadata list and knowledge base sources.
$ref: '#/definitions/QueryFilters'
answerSpanRequest:
x-ms-client-name: shortAnswerOptions
description: To configure Answer span prediction feature.
$ref: '#/definitions/ShortAnswerOptions'
includeUnstructuredSources:
type: boolean
description: (Optional) Flag to enable Query over Unstructured Sources.
ShortAnswerOptions:
type: object
description: To configure Answer span prediction feature.
additionalProperties: false
required:
- enable
properties:
enable:
type: boolean
description: Enable or disable Answer Span prediction.
enum:
- true
x-ms-enum:
name: enable
modelAsString: false
confidenceScoreThreshold:
type: number
format: double
x-ms-client-name: confidenceThreshold
description: >-
Minimum threshold score required to include an answer span, value
ranges from 0 to 1.
maximum: 1
minimum: 0
topAnswersWithSpan:
type: integer
x-ms-client-name: top
description: >-
Number of Top answers to be considered for span prediction from 1 to
10.
format: int32
maximum: 10
minimum: 1
KnowledgeBaseAnswerContext:
type: object
description: Context object with previous QnA's information.
additionalProperties: false
required:
- previousQnaId
properties:
previousQnaId:
type: integer
description: Previous turn top answer result QnA ID.
format: int32
previousUserQuery:
type: string
x-ms-client-name: previousQuestion
description: Previous user query.
AnswersResult:
type: object
description: Represents List of Question Answers.
additionalProperties: false
properties:
answers:
type: array
description: Represents Answer Result list.
items:
$ref: '#/definitions/KnowledgeBaseAnswer'
KnowledgeBaseAnswer:
type: object
description: Represents knowledge base answer.
additionalProperties: false
properties:
questions:
type: array
description: List of questions associated with the answer.
items:
type: string
answer:
type: string
description: Answer text.
confidenceScore:
type: number
format: double
x-ms-client-name: confidence
description: Answer confidence score, value ranges from 0 to 1.
maximum: 1
minimum: 0
id:
type: integer
x-ms-client-name: qnaId
description: ID of the QnA result.
format: int32
source:
type: string
description: Source of QnA result.
metadata:
type: object
description: >-
Metadata associated with the answer, useful to categorize or filter
question answers.
additionalProperties:
type: string
dialog:
type: object
$ref: '#/definitions/KnowledgeBaseAnswerDialog'
answerSpan:
type: object
x-ms-client-name: shortAnswer
description: Answer span object of QnA with respect to user's question.
$ref: '#/definitions/AnswerSpan'
KnowledgeBaseAnswerDialog:
type: object
description: Dialog associated with Answer.
properties:
isContextOnly:
type: boolean
description: >-
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:
type: array
description: List of prompts associated with the answer.
maxItems: 20
items:
$ref: '#/definitions/KnowledgeBaseAnswerPrompt'
KnowledgeBaseAnswerPrompt:
type: object
description: Prompt for an answer.
properties:
displayOrder:
type: integer
description: Index of the prompt - used in ordering of the prompts.
format: int32
qnaId:
type: integer
description: QnA ID corresponding to the prompt.
format: int32
displayText:
type: string
description: Text displayed to represent a follow up question prompt.
maxLength: 200
QueryFilters:
type: object
description: filters over knowledge base.
additionalProperties: false
properties:
metadataFilter:
type: object
$ref: '#/definitions/MetadataFilter'
sourceFilter:
type: object
$ref: '#/definitions/SourceFilter'
logicalOperation:
type: string
description: Logical operation used to join metadata filter with source filter.
$ref: '#/definitions/LogicalOperationKind'
default: AND
MetadataFilter:
type: object
description: Find QnAs that are associated with the given list of metadata.
additionalProperties: false
properties:
metadata:
type: array
items:
$ref: '#/definitions/MetadataRecord'
logicalOperation:
type: string
description: Operation used to join metadata filters.
$ref: '#/definitions/LogicalOperationKind'
default: AND
MetadataRecord:
type: object
description: Object to provide the key value pair for each metadata.
additionalProperties: false
required:
- key
- value
properties:
key:
type: string
description: Metadata Key from Metadata dictionary used in the QnA.
value:
type: string
description: Metadata Value from Metadata dictionary used in the QnA.
LogicalOperationKind:
type: string
description: Set to 'OR' or 'AND' for using corresponding logical operation.
x-ms-enum:
name: LogicalOperationKind
modelAsString: true
enum:
- AND
- OR
SourceFilter:
type: array
description: >-
Find QnAs that are associated with any of the given list of sources in
knowledge base.
items:
type: string
AnswerSpan:
type: object
description: Answer span object of QnA.
additionalProperties: false
properties:
text:
type: string
description: Predicted text of answer span.
confidenceScore:
type: number
x-ms-client-name: confidence
description: Predicted score of answer span, value ranges from 0 to 1.
format: double
maximum: 1
minimum: 0
offset:
type: integer
description: The answer span offset from the start of answer.
format: int32
length:
type: integer
description: The length of the answer span.
format: int32
AnswersFromTextOptions:
type: object
description: The question and text record parameters to answer.
required:
- question
- records
additionalProperties: false
properties:
question:
type: string
description: User question to query against the given text records.
records:
type: array
x-ms-client-name: textDocuments
description: Text records to be searched for given question.
items:
$ref: '#/definitions/TextDocument'
language:
$ref: common.json#/definitions/Language
stringIndexType:
$ref: common.json#/definitions/StringIndexType
AnswersFromTextResult:
type: object
description: Represents the answer results.
additionalProperties: false
properties:
answers:
type: array
description: Represents the answer results.
items:
$ref: '#/definitions/TextAnswer'
TextAnswer:
type: object
description: Represents answer result.
additionalProperties: false
properties:
answer:
type: string
description: Answer.
confidenceScore:
type: number
x-ms-client-name: confidence
description: answer confidence score, value ranges from 0 to 1.
format: double
maximum: 1
minimum: 0
id:
type: string
description: record ID.
answerSpan:
type: object
x-ms-client-name: shortAnswer
description: Answer span object with respect to user's question.
$ref: '#/definitions/AnswerSpan'
offset:
type: integer
description: The sentence offset from the start of the document.
format: int32
length:
type: integer
description: The length of the sentence.
format: int32
TextDocument:
type: object
description: Represent input text record to be queried.
additionalProperties: false
required:
- id
- text
properties:
id:
type: string
description: Unique identifier for the text record.
text:
type: string
description: Text contents of the record.
parameters:
AnswersOptions:
name: knowledgeBaseQueryOptions
in: body
required: true
schema:
$ref: '#/definitions/AnswersOptions'
x-nullable: true
description: Post body of the request.
x-ms-parameter-location: method
AnswersFromTextOptions:
name: textQueryOptions
in: body
required: true
schema:
$ref: '#/definitions/AnswersFromTextOptions'
x-nullable: true
description: Post body of the request.
x-ms-parameter-location: method
tags:
- name: :Query Knowledgebases
- name: :Query Text