Merge pull request #1801 from HeidiSteen/heidist-uuf

[azure search] UUF fixes, debug sessions

Author: prmerger-automator[bot]

articles/search/cognitive-search-debug-session.md

@@ -10,7 +10,7 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 10/01/2024
+ms.date: 12/03/2024
 ---
 
 # Debug Sessions in Azure AI Search
@@ -29,13 +29,13 @@ Use Debug Sessions to investigate and resolve problems with:
 
 + Custom skills used to integrate external processing that you provide.
 
-Compare the following debug session images for the first two scenarios. For both scenarios, the surface area shows the progression of skills that generate or transform content en route from the source document to the search index. The flow includes index mapping options, and you can trace the arrows to follow the processing trail. The details pane to the right is context-sensitive. It shows a representation of the enriched document, or the details of a skill or mapping.
+Compare the following debug session images for the first two scenarios. For both scenarios, the surface area shows the progression of skills that generate or transform content en route from the source document to the search index. The flow includes index mapping options, and you can trace the arrows to follow the processing trail. The details pane to the right is context-sensitive. It shows a representation of the enriched document that's created by the pipeline, or the details of a skill or mapping.
 
-The first image shows a pattern for applied AI enrichment. Skills can run sequentially or in parallel if there are no dependencies. Output field mappings send enriched or generated content from in-memory data structures to fields in an index. 
+The first image shows a pattern for applied AI enrichment (no vectors). Skills can run sequentially or in parallel if there are no dependencies. Index mappings show how enriched or generated content travels from in-memory data structures to fields in an index. Enriched document shows the data structure that the skillset creates.
 
 :::image type="content" source="media/cognitive-search-debug/debug-session-flow-applied-ai.png" alt-text="Screenshot of a debug session for OCR and image analysis." lightbox="media/cognitive-search-debug/debug-session-flow-applied-ai.png":::
 
-The second image shows a typical pattern for integrated vectorization. Skills for integrated vectorization usually includes Text Split and an embedding skill. A Text Split skill chunks a document into pages. An embedding skills provides vectorization. Projection mappings control how chunks of content are index. This particular skillset skips the parent index and creates an index of just chunked content, using metadata to identify the source of the chunk.
+The second image shows a typical pattern for integrated vectorization. Skills for integrated vectorization usually include a Text Split skill and an embedding skill. A Text Split skill divides a document into chunks. An embedding skill calls an embedding API to vectorize those chunks. This particular skillset chunks content into an array of "pages". For integrated vectorization, projection mappings control how chunks are mapped to fields in the index.
 
 :::image type="content" source="media/cognitive-search-debug/debug-session-flow-integrated-vectorization.png" alt-text="Screenshot of a debug session for integrated vectorization." lightbox="media/cognitive-search-debug/debug-session-flow-integrated-vectorization.png":::
 
@@ -53,7 +53,7 @@ Debug Sessions work with all generally available [indexer data sources](search-d
 
 + For custom skills, a user-assigned managed identity isn't supported for a debug session connection to Azure Storage. As stated in the prerequisites, you can use a system managed identity, or specify a full access connection string that includes a key. For more information, see [Connect a search service to other Azure resources using a managed identity](search-howto-managed-identities-data-sources.md).
 
-+ Currently, the ability to select which document to debug is unavailable. This limitation is not permanent and will be lifted soon. At this time, Debug Sessions selects the first document in the source data container or folder.
++ Currently, the ability to select which document to debug is unavailable. This limitation isn't permanent and will be lifted soon. At this time, Debug Sessions selects the first document in the source data container or folder.
 
 ## How a debug session works
 

articles/search/cognitive-search-how-to-debug-skillset.md

@@ -10,7 +10,7 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 10/01/2024
+ms.date: 12/03/2024
 ---
 
 # Debug an Azure AI Search skillset in Azure portal
@@ -23,17 +23,15 @@ For background on how a debug session works, see [Debug sessions in Azure AI Sea
 
 ## Prerequisites
 
-+ An Azure AI Search service. We recommend using a system-assigned managed identity and role assignments that allow Azure AI Search to write to Azure Storage and call the Azure AI resources used in the skillset.
++ An Azure AI Search service, any region or tier.
 
 + An Azure Storage account, used to save session state.
 
 + An existing enrichment pipeline, including a data source, a skillset, an indexer, and an index. 
 
-+ For role assignments, the search service identity must have:
+## Security and permissions
 
-  + **Cognitive Services User** permissions on the Azure AI multiservice account used by the skillset.
-
-  + **Storage Blob Data Contributor** permissions on Azure Storage. Otherwise, plan on using a full access connection string for the debug session connection to Azure Storage.
++ To save a debug session to Azure storage, the search service identity must have **Storage Blob Data Contributor** permissions on Azure Storage. Otherwise, plan on choosing a full access connection string for the debug session connection to Azure Storage.
 
 + If the Azure Storage account is behind a firewall, configure it to [allow search service access](search-indexer-howto-access-ip-restricted.md).
 
@@ -51,8 +49,6 @@ Debug sessions work with all generally available [indexer data sources](search-d
 
 + For custom skills, a user-assigned managed identity isn't supported for a debug session connection to Azure Storage. As stated in the prerequisites, you can use a system managed identity, or specify a full access connection string that includes a key. For more information, see [Connect a search service to other Azure resources using a managed identity](search-howto-managed-identities-data-sources.md).
 
-+ Currently, the ability to select which document to debug is unavailable. This limitation is not permanent and will be lifted soon. At this time, Debug Sessions selects the first document in the source data container or folder.
-
 ## Create a debug session
 
 1. Sign in to the [Azure portal](https://portal.azure.com) and [find your search service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices).
@@ -67,33 +63,25 @@ Debug sessions work with all generally available [indexer data sources](search-d
 
 1. In **Indexer template**, select the indexer that drives the skillset you want to debug. Copies of both the indexer and skillset are used to initialize the session.
 
-1. In **Storage account**, find a general-purpose storage account for caching the debug session.
+1. In **Document to debug**, choose the first document in the index or select a specific document. If you select a specific document, depending on the data source, you're asked for a URI or a row ID.
+
+   If your specific document is a blob, provide the blob URI. You can find the URI in the blob property page in the portal.
 
-1. Select **Authenticate using managed identity** if you previously assigned **Storage Blob Data Contributor** permissions to the search service system-managed identity.
+   :::image type="content" source="media/cognitive-search-debug/copy-blob-url.png" lightbox="media/cognitive-search-debug/copy-blob-url.png" alt-text="Screenshot of the URI property in blob storage." border="true":::
+
+1. In **Storage account**, choose a general-purpose storage account for caching the debug session.
+
+1. Select **Authenticate using managed identity** if you previously assigned **Storage Blob Data Contributor** permissions to the search service system-managed identity. If you don't check this box, the search service connects using a full access connection string.
 
 1. Select **Save**.
 
    + Azure AI Search creates a blob container on Azure Storage named *ms-az-cognitive-search-debugsession*.
    + Within that container, it creates a folder using the name you provided for the session name.
    + It starts your debug session.
 
-1. A debug session opens to the settings page. You can make modifications to the initial configuration and override any defaults.
-
-1. In **Storage connection string**, you can specify the connection string or change the storage account. 
-
-   <!-- 1. In **Document to debug**, choose the first document in the index or select a specific document. If you select a specific document, depending on the data source, you're asked for a URI or a row ID.
-
-   If your specific document is a blob, provide the blob URI. You can find the URI in the blob property page in the portal.
-
-   :::image type="content" source="media/cognitive-search-debug/copy-blob-url.png" lightbox="media/cognitive-search-debug/copy-blob-url.png" alt-text="Screenshot of the URI property in blob storage." border="true"::: -->
-
-1. Optionally, in **Indexer settings**, specify any [indexer execution settings](search-howto-indexing-azure-blob-storage.md) used to create the session. The settings should mirror the settings used by the actual indexer. Any indexer options that you specify in a debug session have no effect on the indexer itself.
-
-1. If you made changes, select **Save session**, followed by **Run**.
-
 The debug session begins by executing the indexer and skillset on the selected document. The document's content and metadata are visible and available in the session.
 
-A debug session can be canceled while it's executing using the **Cancel** button. If you hit the **Cancel** button you should be able to analyze partial results.
+A debug session can be canceled while it's executing. If you hit the **Cancel** button you should be able to analyze partial results.
 
 It's expected for a debug session to take longer to execute than the indexer since it goes through extra processing. 
 

articles/search/cognitive-search-tutorial-debug-sessions.md

@@ -10,7 +10,7 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: tutorial
-ms.date: 08/20/2024
+ms.date: 12/03/2024
 ---
 
 # Tutorial: Fix a skillset using Debug Sessions