Skip to content

Commit ce90c83

Browse files
GitHubber17GitHubber17
authored
Merge pull request #178534 from mrbullwinkle/mrb_11_3_2021_prebuilt_api
[Cognitive Services] Q&A query text
2 parents 75a1527 + 2d89323 commit ce90c83

File tree

2 files changed

+134
-0
lines changed

2 files changed

+134
-0
lines changed

‎articles/cognitive-services/language-service/question-answering/how-to/prebuilt.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
title: Prebuilt API - question answering
3+
titleSuffix: Azure Cognitive Services
4+
description: Use the question answering Prebuilt API to ask and receive answers to questions without having to create a project/knowledge base.
5+
ms.service: cognitive-services
6+
ms.subservice: language-service
7+
author: mrbullwinkle
8+
ms.author: mbullwin
9+
ms.topic: conceptual
10+
ms.date: 11/03/2021
11+
---
12+
13+
# Prebuilt API
14+
15+
The question answering **prebuilt API** provides you the capability to answer questions based on a passage of text without having to create projects/knowledge bases, maintain question and answer pairs, or incurring costs for underutilized infrastructure. This functionality is provided as an API and can be used to meet question and answering needs without having to learn the details about question answering.
16+
17+
Given a user query and a block of text/passage the API will return an answer and precise answer (if available).
18+
19+
## Example API usage
20+
21+
Imagine that you have one or more blocks of text from which you would like to get answers for a given question. Normally you would have had to create as many sources as the number of blocks of text. However, now with the prebuilt API you can query the blocks of text without having to define content sources in a project/knowledge base.
22+
23+
Some other scenarios where this API can be used are:
24+
25+
* You are developing an ebook reader app for end users, which allows them to highlight text, enter a question and find answers over a highlighted passage of text.
26+
* A browser extension that allows users to ask a question over the content being currently displayed on the browser page.
27+
* A health bot that takes queries from users and provides answers based on the medical content that the bot identifies as most relevant to the user query.
28+
29+
Below is an example of a sample request:
30+
31+
## Sample request
32+
33+
```
34+
POST https://{Unique-to-your-endpoint}.api.cognitive.microsoft.com/language/:query-text
35+
```
36+
37+
### Sample query over a single block of text
38+
39+
Request Body
40+
41+
```json
42+
{
43+
"parameters": {
44+
"Endpoint": "{Endpoint}",
45+
"Ocp-Apim-Subscription-Key": "{API key}",
46+
"Content-Type": "application/json",
47+
"api-version": "2021-10-01",
48+
"stringIndexType": "TextElements_v8",
49+
"textQueryOptions": {
50+
"question": "how long it takes to charge surface?",
51+
"records": [
52+
{
53+
"id": "1",
54+
"text": "Power and charging. It 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."
55+
},
56+
{
57+
"id": "2",
58+
"text": "You 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."
59+
}
60+
],
61+
"language": "en"
62+
}
63+
}
64+
}
65+
```
66+
67+
## Sample response
68+
69+
In the above request body, we query over a single block of text. A sample response received for the above query is shown below,
70+
71+
```json
72+
{
73+
"responses": {
74+
"200": {
75+
"headers": {},
76+
"body": {
77+
"answers": [
78+
{
79+
"answer": "Power and charging. It 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.",
80+
"confidenceScore": 0.93,
81+
"id": "1",
82+
"answerSpan": {
83+
"text": "two to four hours",
84+
"confidenceScore": 0,
85+
"offset": 28,
86+
"length": 45
87+
},
88+
"offset": 0,
89+
"length": 224
90+
},
91+
{
92+
"answer": "It 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.",
93+
"confidenceScore": 0.92,
94+
"id": "1",
95+
"answerSpan": {
96+
"text": "two to four hours",
97+
"confidenceScore": 0,
98+
"offset": 8,
99+
"length": 25
100+
},
101+
"offset": 20,
102+
"length": 224
103+
},
104+
{
105+
"answer": "It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it.",
106+
"confidenceScore": 0.05,
107+
"id": "1",
108+
"answerSpan": null,
109+
"offset": 110,
110+
"length": 244
111+
}
112+
]
113+
}
114+
}
115+
}
116+
```
117+
118+
We see that multiple answers are received as part of the API response. Each answer has a specific confidence score that helps understand the overall relevance of the answer. Answer span represents whether a potential short answer was also detected. Users can make use of this confidence score to determine which answers to provide in response to the query.
119+
120+
## Prebuilt API limits
121+
122+
If you need to use larger documents than the limit allows, you can break the text into smaller chunks of text before sending them to the API. In this context, a document is a defined single string of text characters.
123+
124+
These numbers represent the **per individual API call limits**:
125+
126+
* Number of documents: 5.
127+
* Maximum size of a single document: 5,120 characters.
128+
* Maximum three responses per document.
129+
130+
## Prebuilt API reference
131+
132+
Visit the [full prebuilt API samples](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/Language/stable/2021-10-01/examples/questionanswering/SuccessfulQueryText.json) documentation to understand the input and output parameters required for calling the API.

‎articles/cognitive-services/language-service/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -505,6 +505,8 @@ items:
505505
href: question-answering/how-to/manage-knowledge-base.md
506506
- name: Network isolation and private endpoints
507507
href: question-answering/how-to/network-isolation.md
508+
- name: Prebuilt API
509+
href: question-answering/how-to/prebuilt.md
508510
- name: Troubleshooting
509511
href: question-answering/how-to/troubleshooting.md
510512
- name: Concepts

0 commit comments

Comments
 (0)