Merge pull request #245546 from HeidiSteen/heidist-refresh

[azure search] Refreshed 7 of 14 articles that have expired

Author: American-Dipper

articles/search/cognitive-search-common-errors-warnings.md

@@ -8,22 +8,22 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: cognitive-search
 ms.topic: conceptual
-ms.date: 07/01/2022
-ms.custom: references_regions
+ms.date: 07/19/2023
+
 ---
 # AI enrichment in Azure Cognitive Search
 
-*AI enrichment* is the application of machine learning models over content that isn't full text searchable in its raw form. Through enrichment, analysis and inference are used to create searchable content and structure where none previously existed. 
+In Cognitive Search, *AI enrichment* is the application of machine learning models over content that isn't full text searchable in its raw form. Through enrichment, analysis and inference are used to create searchable content and structure where none previously existed. 
 
 Because Azure Cognitive Search is a full text search solution, the purpose of AI enrichment is to improve the utility of your content in search-related scenarios:
 
-+ Translation and language detection for multi-lingual search
-+ Entity recognition extracts people, places, and other entities from large chunks of text
-+ Key phrase extraction identifies and then outputs important terms
-+ Optical Character Recognition (OCR) recognizes printed and handwritten text in binary files
-+ Image analysis describes image content and outputs the descriptions as searchable text fields
++ Apply translation and language detection for multi-lingual search
++ Apply entity recognition to extract people names, places, and other entities from large chunks of text
++ Apply key phrase extraction to identify and output important terms
++ Apply Optical Character Recognition (OCR) to recognize printed and handwritten text in binary files
++ Apply image analysis to describe image content, and output the descriptions as searchable text fields
 
-AI enrichment is an extension of an [**indexer pipeline**](search-indexer-overview.md). An enrichment pipeline has all of the components of an indexer pipeline (indexer, data source, index), plus a [**skillset**](cognitive-search-working-with-skillsets.md) that specifies atomic enrichment steps.
+AI enrichment is an extension of an [**indexer pipeline**](search-indexer-overview.md) that connects to Azure data sources. An enrichment pipeline has all of the components of an indexer pipeline (indexer, data source, index), plus a [**skillset**](cognitive-search-working-with-skillsets.md) that specifies atomic enrichment steps.
 
 The following diagram shows the progression of AI enrichment:
 
@@ -43,8 +43,6 @@ The following diagram shows the progression of AI enrichment:
 
 **Exploration** is the last step. Output is always a [search index](search-what-is-an-index.md) that you can query from a client app. Output can optionally be a [knowledge store](knowledge-store-concept-intro.md) consisting of blobs and tables in Azure Storage that are accessed through data exploration tools or downstream processes. If you're creating a knowledge store, [projections](knowledge-store-projection-overview.md) determine the data path for enriched content. The same enriched content can appear in both indexes and knowledge stores.
 
-<!-- ![Enrichment pipeline diagram](./media/cognitive-search-intro/cogsearch-architecture.png "enrichment pipeline") -->
-
 ## When to use AI enrichment
 
 Enrichment is useful if raw content is unstructured text, image content, or content that needs language detection and translation. Applying AI through the [**built-in skills**](cognitive-search-predefined-skills.md) can unlock this content for full text search and data science applications. 
@@ -54,7 +52,7 @@ Open-source, third-party, or first-party code can be integrated into the pipelin
 
 ### Use-cases for built-in skills
 
-Built-in skills are based on the Azure AI services APIs: [Azure AI Vision](../ai-services/computer-vision/index.yml) and [Language Service](../ai-services/language-service/overview.md). Unless your content input is small, expect to [attach a billable Azure AI services resource](cognitive-search-attach-cognitive-services.md) to run larger workloads.
+Built-in skills are based on the Azure AI services APIs: [Azure AIComputer Vision](../ai-services/computer-vision/index.yml) and [Language Service](../ai-services/language-service/overview.md). Unless your content input is small, expect to [attach a billable Azure AI services resource](cognitive-search-attach-cognitive-services.md) to run larger workloads.
 
 A [skillset](cognitive-search-defining-skillset.md) that's assembled using built-in skills is well suited for the following application scenarios:
 
@@ -66,11 +64,7 @@ A [skillset](cognitive-search-defining-skillset.md) that's assembled using built
 
 ### Use-cases for custom skills
 
-[**Custom skills**](cognitive-search-create-custom-skill-example.md) execute external code that you provide. Custom skills can support more complex scenarios, such as recognizing forms, or custom entity detection using a model that you provide and wrap in the [custom skill web interface](cognitive-search-custom-skill-interface.md). Several examples of custom skills include:
-
-+ [Document Intelligence](../ai-services/document-intelligence/overview.md)
-+ [Bing Entity Search API](./cognitive-search-create-custom-skill-example.md)
-+ [Custom entity recognition](https://github.com/Microsoft/SkillsExtractorCognitiveSearch)
+[**Custom skills**](cognitive-search-create-custom-skill-example.md) execute external code that you provide and wrap in the [custom skill web interface](cognitive-search-custom-skill-interface.md). Several examples of custom skills can be found in the [azure-search-power-skills](https://github.com/Azure-Samples/azure-search-power-skills/blob/main/README.md) GitHub repository.
 
 Custom skills aren’t always complex. For example, if you have an existing package that provides pattern matching or a document classification model, you can wrap it in a custom skill. 
 
@@ -104,11 +98,7 @@ In Azure Storage, a [knowledge store](knowledge-store-concept-intro.md) can assu
 
 ## Availability and pricing
 
-Enrichment is available in regions that have Azure AI services. You can check the availability of enrichment on the [Azure products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=search) page. Enrichment is available in all regions except:
-
-+ Australia Southeast
-+ China North 2
-+ Germany West Central
+Enrichment is available in regions that have Azure AI services. You can check the availability of enrichment on the [Azure products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=search) page. 
 
 Billing follows a pay-as-you-go pricing model. The costs of using built-in skills are passed on when a multi-region Azure AI services key is specified in the skillset. There are also costs associated with image extraction, as metered by Cognitive Search. Text extraction and utility skills, however, aren't billable. For more information, see [How you're charged for Azure Cognitive Search](search-sku-manage-costs.md#how-youre-charged-for-azure-cognitive-search).
 
@@ -141,4 +131,4 @@ To repeat any of the above steps, [reset the indexer](search-howto-reindex.md) b
 + [Skillset concepts](cognitive-search-working-with-skillsets.md)
 + [Knowledge store concepts](knowledge-store-concept-intro.md)
 + [Create a skillset](cognitive-search-defining-skillset.md)
-+ [Create a knowledge store](knowledge-store-create-rest.md)
++ [Create a knowledge store](knowledge-store-create-rest.md)

articles/search/cognitive-search-concept-intro.md

@@ -1,23 +1,23 @@
 ---
 title: 'Tutorial: Debug skillsets'
 titleSuffix: Azure Cognitive Search
-description: Debug sessions is an Azure portal tool used to find, diagnose, and repair problems in a skillset.
+description: Debug Sessions is an Azure portal tool used to find, diagnose, and repair problems in a skillset.
 author: HeidiSteen
 ms.author: heidist
 manager: nitinme
 
 ms.service: cognitive-search
 ms.topic: tutorial
-ms.date: 06/15/2022
+ms.date: 07/20/2023
 ---
 
 # Tutorial: Debug a skillset using Debug Sessions
 
 Skillsets coordinate a series of actions that analyze or transform content, where the output of one skill becomes the input of another. When inputs depend on outputs, mistakes in skillset definitions and field associations can result in missed operations and data.
 
-**Debug sessions** in the Azure portal provides a holistic visualization of a skillset. Using this tool, you can drill down to specific steps to easily see where an action might be falling down.
+**Debug sessions** is a tool in the Azure portal provides a holistic visualization of a skillset. Using this tool, you can drill down to specific steps to easily see where an action might be falling down.
 
-In this article, you'll use **Debug sessions** to find and fix missing inputs and outputs. The tutorial is all-inclusive. It provides sample data, a Postman collection that creates objects, and instructions for debugging problems in the skillset.
+In this article, use **Debug sessions** to find and fix missing inputs and outputs. The tutorial is all-inclusive. It provides sample data, a Postman collection that creates objects, and instructions for debugging problems in the skillset.
 
 ## Prerequisites
 
@@ -68,24 +68,26 @@ All requests require an api-key on every request sent to your service. Having a
 
 ## Create data source, skillset, index, and indexer
 
-In this section, Postman and a provided collection are used to create the Cognitive Search data source, skillset, index, and indexer. If you're unfamiliar with Postman, see [this quickstart](search-get-started-rest.md).
+In this section, import a Postman collection containing a "buggy" workflow that you fix in this tutorial. 
 
-You will need the [Postman collection](https://github.com/Azure-Samples/azure-search-postman-samples/tree/master/Debug-sessions) created for this tutorial to complete this task. 
+1. Start Postman and import the [DebugSessions.postman_collection.json](https://github.com/Azure-Samples/azure-search-postman-samples/tree/master/Debug-sessions) collection.  If you're unfamiliar with Postman, see [this quickstart](search-get-started-rest.md).
 
-1. Start Postman and import the "DebugSessions.postman_collection.json" collection. Under **Files** > **New**, select the collection.
+1. Under **Files** > **New**, select the collection.
 
 1. After the collection is imported, expand the actions list (...).
 
-1. Select  **Edit** to set variables used in each request, and then **Save**.
+1. Select  **Edit** to set variables used in each request.
 
    | Current value | Description |
    |---------------|-------------|
-   | searchService | The name of your search service (for example, if the endpoint is `https://mydemo.search.windows.net`, then the service name is "mydemo". |
+   | searchService | The name of your search service (for example, if the endpoint is `https://mydemo.search.windows.net`, then the service name is `mydemo`). |
    | apiKey | The primary or secondary key obtained from the **Keys** page of your search service. |
    | storageConnectionString | The connection string obtained from the **Access Keys** page of your Azure Storage account. |
    | containerName | The name of the container you created for the sample data. |
 
-1. Verify that the collection you imported contains four REST calls, used to create objects in this tutorial.
+1. **Save** your changes. The requests fail unless you save the variables.
+
+1. You should see four REST calls in the collection.
 
    + CreateDataSource adds `clinical-trials-ds`
    + CreateSkillset adds `clinical-trials-ss`
@@ -122,13 +124,15 @@ Another way to investigate errors and warnings is through the Azure portal.
 
 ## Start your debug session
 
-1. From the search service **Overview** page, click the **Debug sessions** tab.
+1. From the search service left-navigation pane, under **Search management**, select **Debug sessions**.
 
-1. Select **+ New Debug Session**.
+1. Select **+ Add Debug Session**.
 
 1. Give the session a name. 
 
-1. Connect the session to your storage account. 
+1. Connect the session to your storage account. Create a container named "debug sessions". You can use this container repeatedly to store all of your debug session data.
+
+1. If you configured a trusted connection between search and storage, select the user-managed identity or system identity for the connection. Otherwise, use the default (None).
 
 1. In Indexer template, provide the indexer name. The indexer has references to the data source, the skillset, and index.
 
@@ -152,24 +156,24 @@ Notice that the **Errors/Warnings** tab will provide a much smaller list than th
 
 Select **Errors/Warnings** to review the notifications. You should see four:
 
-+ "Could not execute skill because one or more skill input was invalid. Required skill input is missing. Name: 'text', Source: '/document/content'."
++ "Could not execute skill because one or more skill inputs were invalid. Required skill input is missing. Name: 'text', Source: '/document/content'."
 
 + "Could not map output field 'locations' to search index. Check the 'outputFieldMappings' property of your indexer.
 Missing value '/document/merged_content/locations'."
 
 + "Could not map output field 'organizations' to search index. Check the 'outputFieldMappings' property of your indexer.
 Missing value '/document/merged_content/organizations'."
 
-+ "Skill executed but may have unexpected results because one or more skill input was invalid.
++ "Skill executed but may have unexpected results because one or more skill inputs were invalid.
 Optional skill input is missing. Name: 'languageCode', Source: '/document/languageCode'. Expression language parsing issues: Missing value '/document/languageCode'."
 
-Many skills have a "languageCode" parameter. By inspecting the operation, you can see that this language code input is missing from the `EntityRecognitionSkillV3.#1`, which is the same Entity Recognition skill that is having trouble with 'locations' and 'organizations' output. 
+Many skills have a "languageCode" parameter. By inspecting the operation, you can see that this language code input is missing from the `EntityRecognitionSkill.#1`, which is the same Entity Recognition skill that is having trouble with 'locations' and 'organizations' output. 
 
 Because all four notifications are about this skill, your next step is to debug this skill. If possible, start by solving input issues first before moving on to output issues.
 
 ## Fix missing skill input values
 
-In the **Errors/Warnings** tab, there are two missing inputs for an operation labeled `EntityRecognitionSkillV3.#1`. The detail of the first error explains that a required input for 'text' is missing. The second indicates a problem with an input value "/document/languageCode".
+In the **Errors/Warnings** tab, there are two missing inputs for an operation labeled `EntityRecognitionSkill.#1`. The detail of the first error explains that a required input for 'text' is missing. The second indicates a problem with an input value "/document/languageCode".
 
 1. In **AI Enrichments** >  **Skill Graph**, select the skill labeled **#1** to display its details in the right pane.
 
@@ -191,7 +195,14 @@ In the **Errors/Warnings** tab, there are two missing inputs for an operation la
 
 1. Switch to **Skill JSON Editor**.
 
-1. Change `/document/content` to `/document/merged_content`.
+1. At line 16, under "inputs", change `/document/content` to `/document/merged_content`.
+
+   ```json
+    {
+      "name": "text",
+      "source": "/document/merged_content"
+    },
+   ```
 
 1. Select **Save** in the Skill Details pane.
 
@@ -205,7 +216,7 @@ In the **Errors/Warnings** tab, there are two missing inputs for an operation la
 
 1. Select the **Executions** tab and locate the input for "languageCode".
 
-1. Select the **</>** symbol to pop open the Expression Evaluator. Notice the confirmation that the "languageCode" property is not a valid input.
+1. Select the **</>** symbol to pop open the Expression Evaluator. Notice the confirmation that the "languageCode" property isn't a valid input.
 
    :::image type="content" source="media/cognitive-search-debug/expression-evaluator-language.png" alt-text="Screenshot of Expression Evaluator for the language input." border="true":::
 
@@ -265,19 +276,21 @@ Alternatively, if you aren't ready to commit changes, you can save the debug ses
 
 1. Select **OK** to confirm that you wish to update your skillset.
 
-1. Close Debug session and select the **Indexers** tab.
+1. Close Debug session and open **Indexers** from the left navigation pane.
 
-1. Open your 'clinical-trials-idxr'.
+1. Select 'clinical-trials-idxr'.
 
 1. Select **Reset**.
 
-1. Select **Run**. Select **OK** to confirm.
+1. Select **Run**.
+
+1. Select **Refresh** to show the status of the reset and run commands.
 
 When the indexer has finished running, there should be a green checkmark and the word Success next to the time stamp for the latest run in the **Execution history** tab. To ensure that the changes have been applied:
 
-1. In the search Overview page, select the **Index** tab.
+1. In the left navigation pane, open **Indexes**.
 
-1. Open the 'clinical-trials' index and in the Search explorer tab, enter this query string: `$select=metadata_storage_path, organizations, locations&$count=true` to return fields for specific documents (identified by the unique `metadata_storage_path` field).
+1. Select 'clinical-trials' index and in the Search explorer tab, enter this query string: `$select=metadata_storage_path, organizations, locations&$count=true` to return fields for specific documents (identified by the unique `metadata_storage_path` field).
 
 1. Select **Search**.
 
@@ -289,7 +302,7 @@ When you're working in your own subscription, it's a good idea at the end of a p
 
 You can find and manage resources in the portal, using the **All resources** or **Resource groups** link in the left-navigation pane.
 
-If you are using a free service, remember that you are limited to three indexes, indexers, and data sources. You can delete individual items in the portal to stay under the limit. 
+If you're using a free service, remember that you're limited to three indexes, indexers, and data sources. You can delete individual items in the portal to stay under the limit. 
 
 ## Next steps