Merge pull request #252633 from HeidiSteen/heidist-freshness

[azure search] searchFields for early preview APIs is covered in reference docs

Author: denrea

articles/search/semantic-answers.md

@@ -8,7 +8,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: cognitive-search
 ms.topic: conceptual
-ms.date: 08/14/2023
+ms.date: 09/22/2023
 ---
 
 # Return a semantic answer in Azure Cognitive Search
@@ -18,7 +18,9 @@ ms.date: 08/14/2023
 
 When invoking [semantic ranking and captions](semantic-how-to-query-request.md), you can optionally extract content from the top-matching documents that "answers" the query directly. One or more answers can be included in the response, which you can then render on a search page to improve the user experience of your app.
 
-In this article, learn how to request a semantic answer, unpack the response, and what content characteristics are most conducive to producing high-quality answers.
+A semantic answer is verbatim content in your search index that a reading comprehension model has recognized as an answer to the query posed in the request. It's not a generated answer. For guidance on a chat-style user interaction model that uses generative AI to compose answers from your content, see [Retrieval Augmented Generation (RAG)](retrieval-augmented-generation-overview.md).
+
+In this article, learn how to request a semantic answer, unpack the response, and find out what content characteristics are most conducive to producing high-quality answers.
 
 ## Prerequisites
 
@@ -28,27 +30,25 @@ All prerequisites that apply to [semantic queries](semantic-how-to-query-request
 
 + Query strings entered by the user must be recognizable as a question (what, where, when, how).
 
-+ Search documents in the index must contain text having the characteristics of an answer, and that text must exist in one of the fields listed in the [semantic configuration](semantic-how-to-query-request.md#2---create-a-semantic-configuration). For example, given a query "what is a hash table", if none of the fields in the semantic configuration contain passages that include "A hash table is ...", then it's unlikely an answer will be returned.
++ Search documents in the index must contain text having the characteristics of an answer, and that text must exist in one of the fields listed in the [semantic configuration](semantic-how-to-query-request.md#2---create-a-semantic-configuration). For example, given a query "what is a hash table", if none of the fields in the semantic configuration contain passages that include "A hash table is ...", then it's unlikely an answer is returned.
+
+> [!NOTE]
+> Starting in 2021-04-30-Preview, in [Create or Update Index (Preview)](/rest/api/searchservice/preview-api/create-or-update-index) requests, a `"semanticConfiguration"` is required for specifying input fields for semantic ranking.
 
 ## What is a semantic answer?
 
 A semantic answer is a substructure of a [semantic query response](semantic-how-to-query-request.md). It consists of one or more verbatim passages from a search document, formulated as an answer to a query that looks like a question. To return an answer, phrases or sentences must exist in a search document that have the language characteristics of an answer, and the query itself must be posed as a question.
 
-Cognitive Search uses a machine reading comprehension model to pick the best answer. The model produces a set of potential answers from the available content, and when it reaches a high enough confidence level, it will propose one as an answer.
+Cognitive Search uses a machine reading comprehension model to recognize and pick the best answer. The model produces a set of potential answers from the available content, and when it reaches a high enough confidence level, it proposes one as an answer.
 
 Answers are returned as an independent, top-level object in the query response payload that you can choose to render on  search pages, along side search results. Structurally, it's an array element within the response consisting of text, a document key, and a confidence score.
 
 <a name="query-params"></a>
 
 ## Formulate a REST query for "answers"
 
-The approach for listing fields in priority order has changed, with "semanticConfiguration" replacing "searchFields". If you're currently using "searchFields", update your code to the 2021-04-30-Preview API version and use "semanticConfiguration" instead.
-
-### [**Semantic Configuration (recommended)**](#tab/semanticConfiguration)
-
-To return a semantic answer, the query must have the semantic "queryType", "queryLanguage", "semanticConfiguration", and the "answers" parameters. Specifying these parameters doesn't guarantee an answer, but the request must include them for answer processing to occur.
+To return a semantic answer, the query must have the semantic `"queryType"`, `"queryLanguage"`, `"semanticConfiguration"`, and the `"answers"` parameters. Specifying these parameters doesn't guarantee an answer, but the request must include them for answer processing to occur.
 
-The "semanticConfiguration" parameter is required. It's defined in a search index, and then referenced in a query, as shown below. 
 
 ```json
 {
@@ -64,52 +64,23 @@ The "semanticConfiguration" parameter is required. It's defined in a search inde
 
 + A query string must not be null and should be formulated as question.
 
-+ "queryType" must be set to "semantic.
-
-+ "queryLanguage" must be one of the values from the [supported languages list (REST API)](/rest/api/searchservice/preview-api/search-documents#queryLanguage).
-
-+ A "semanticConfiguration" determines which string fields provide tokens to the extraction model. The same fields that produce captions also produce answers. See [Create a semantic configuration](semantic-how-to-query-request.md#2---create-a-semantic-configuration) for details.
-
-+ For "answers", parameter construction is `"answers": "extractive"`, where the default number of answers returned is one. You can increase the number of answers by adding a `count` as shown in the above example, up to a maximum of 10.  Whether you need more than one answer depends on the user experience of your app, and how you want to render results.
++ `"queryType"` must be set to "semantic.
 
-### [**searchFields**](#tab/searchFields)
++ `"queryLanguage"` must be one of the values from the [supported languages list (REST API)](/rest/api/searchservice/preview-api/search-documents#queryLanguage).
 
-To return a semantic answer, the query must have the semantic "queryType", "queryLanguage", "searchFields", and the "answers" parameter. Specifying the "answers" parameter doesn't guarantee that you'll get an answer, but the request must include this parameter if answer processing is to be invoked at all.
++ A `"semanticConfiguration"` determines which string fields provide tokens to the extraction model. The same fields that produce captions also produce answers. See [Create a semantic configuration](semantic-how-to-query-request.md#2---create-a-semantic-configuration) for details.
 
-The "searchFields" parameter is crucial to returning a high-quality answer, both in terms of content and order (see below). 
-
-```json
-{
-    "search": "how do clouds form",
-    "queryType": "semantic",
-    "queryLanguage": "en-us",
-    "searchFields": "title,locations,content",
-    "answers": "extractive|count-3",
-    "count": "true"
-}
-```
-
-+ A query string must not be null and should be formulated as question.
-
-+ "queryType" must be set to "semantic.
-
-+ "queryLanguage" must be one of the values from the [supported languages list (REST API)](/rest/api/searchservice/preview-api/search-documents#queryLanguage).
-
-+ "searchFields" determines which string fields provide tokens to the extraction model. The same fields that produce captions also produce answers. See [Set searchFields](semantic-how-to-query-request.md#2b---use-searchfields-for-field-prioritization) for details. 
-
-+ For "answers", parameter construction is `"answers": "extractive"`, where the default number of answers returned is one. You can increase the number of answers by adding a `count` as shown in the above example, up to a maximum of 10.  Whether you need more than one answer depends on the user experience of your app, and how you want to render results.
-
----
++ For `"answers"`, parameter construction is `"answers": "extractive"`, where the default number of answers returned is one. You can increase the number of answers by adding a `count` as shown in the above example, up to a maximum of 10.  Whether you need more than one answer depends on the user experience of your app, and how you want to render results.
 
 ## Unpack an "answer" from the response
 
-Answers are provided in the `"@search.answers"` array, which appears first in the query response. Each answer in the array will include:
+Answers are provided in the `"@search.answers"` array, which appears first in the query response. Each answer in the array includes:
 
 + Document key
 + Text or content of the answer, in plain text or with formatting
 + Confidence score
 
-If an answer is indeterminate, the response will show up as `"@search.answers": []`. The answers array is followed by the value array, which is the standard response in a semantic query.
+If an answer is indeterminate, the response shows up as `"@search.answers": []`. The answers array is followed by the value array, which is the standard response in a semantic query.
 
 Given the query "how do clouds form", the following example illustrates an answer:
 
@@ -146,7 +117,7 @@ Given the query "how do clouds form", the following example illustrates an answe
 
 ```
 
-When designing a search results page that includes answers, be sure to handle cases where answers are not found.
+When designing a search results page that includes answers, be sure to handle cases where answers aren't found.
 
 Within @search.answers:
 
@@ -156,7 +127,7 @@ Within @search.answers:
 
   By default, highlights are styled as `<em>`, which you can override using the existing highlightPreTag and highlightPostTag parameters. As noted elsewhere, the substance of an answer is verbatim content from a search document. The extraction model looks for characteristics of an answer to find the appropriate content, but doesn't compose new language in the response.
 
-+ **"score"** is a confidence score that reflects the strength of the answer. If there are multiple answers in the response, this score is used to determine the order. Top answers and top captions can be derived from different search documents, where the top answer originates from one document, and the top caption from another, but in general you will see the same documents in the top positions within each array.
++ **"score"** is a confidence score that reflects the strength of the answer. If there are multiple answers in the response, this score is used to determine the order. Top answers and top captions can be derived from different search documents, where the top answer originates from one document, and the top caption from another, but in general the same documents appear in the top positions within each array.
 
 Answers are followed by the **"value"** array, which always includes scores, captions, and any fields that are retrievable by default. If you specified the select parameter, the "value" array is limited to the fields that you specified. See [Configure semantic ranking](semantic-how-to-query-request.md) for details.