You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Use Debug Sessions to investigate and resolve problems with:
25
25
26
-
+ Built-in skills for [integrated vectorization](vector-search-integrated-vectorization.md), with data chunking through Text Split, and vectorization through an embedding skill
26
+
+ Built-in skills used for [AI enrichment](cognitive-search-concept-intro.md) (OCR, image analysis, Entity Recognition, Sentiment Analysis, Keyword Extraction).
27
+
28
+
+ Built-in skills used for [integrated vectorization](vector-search-integrated-vectorization.md), with data chunking through Text Split, and vectorization through an embedding skill.
27
29
28
30
+ Custom skills used to integrate external processing that you provide.
29
31
30
-
Compare the following images for the first two scenarios. Skills for applied AI enrichment 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.
32
+
Compare the following images for the first two scenarios. The surface area shows the progression of skills that generate or transform content en route from source to index, with a list of mapping options and arrows indicating 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.
33
+
34
+
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.
31
35
32
36
:::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":::
33
37
34
-
Skills for integrated vectorization typically include Text Split and embeddings. A Text Split skills chunks a document into pages. Projection mappings control parent-chunk indexing. This skillset skips the parent index and creates an index with just chunked content, using metadata to identify the source of the chunk.
38
+
Skills for integrated vectorization typically include Text Split and an embedding skill. A Text Split skills chunks a document into pages. Projection mappings control parent-chunk indexing. This skillset skips the parent index and creates an index with just chunked content, using metadata to identify the source of the chunk.
35
39
36
40
:::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":::
37
41
38
42
## Limitations
39
43
40
-
Debug sessions work with all generally available [indexer data sources](search-data-sources-gallery.md) and most preview data sources, with the following exceptions:
44
+
Debug Sessions work with all generally available [indexer data sources](search-data-sources-gallery.md) and most preview data sources, with the following exceptions:
Copy file name to clipboardExpand all lines: articles/search/cognitive-search-how-to-debug-skillset.md
+14-10Lines changed: 14 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,15 +23,17 @@ For background on how a debug session works, see [Debug sessions in Azure AI Sea
23
23
24
24
## Prerequisites
25
25
26
-
+A search service with roles enabled and a system-assigned managed identity that you can use in role assignments.
26
+
+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.
27
27
28
28
+ An Azure Storage account, used to save session state.
29
29
30
30
+ An existing enrichment pipeline, including a data source, a skillset, an indexer, and an index.
31
31
32
-
+The search service identity must have**Cognitive Services User** permissions on the Azure AI multiservice account used by the skillset.
32
+
+For role assignments, the search service identity must have:
33
33
34
-
+ The search service identity must have a **Storage Blob Data Contributor** role assignment in Azure Storage. Otherwise, plan on using a full access connection string for the debug session connection to Azure Storage.
34
+
+**Cognitive Services User** permissions on the Azure AI multiservice account used by the skillset.
35
+
36
+
+**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.
35
37
36
38
+ If the Azure Storage account is behind a firewall, configure it to [allow search service access](search-indexer-howto-access-ip-restricted.md).
37
39
@@ -70,10 +72,12 @@ Debug sessions work with all generally available [indexer data sources](search-d
70
72
1. Select **Save**.
71
73
72
74
+ Azure AI Search creates a blob container on Azure Storage named *ms-az-cognitive-search-debugsession*.
73
-
+It creates a folder using the name you provided for the session name.
75
+
+Within that container, it creates a folder using the name you provided for the session name.
74
76
+ It starts your debug session.
75
77
76
-
1. The debug session opens to the definition page.
78
+
1. The debug session opens to the definition page. The page looks similar the following screenshot.
79
+
80
+
:::image type="content" source="media/cognitive-search-debug/debug-session-new.png" lightbox="media/cognitive-search-debug/debug-session-new.png" alt-text="Screenshot of a debug session page." border="true":::
77
81
78
82
1. In **Storage connection string**, you can specify or change the storage account. If you already have role assignments, you can skip this step.
79
83
@@ -85,9 +89,7 @@ Debug sessions work with all generally available [indexer data sources](search-d
85
89
86
90
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.
87
91
88
-
1. Your configuration should look similar to this screenshot. If you made changes, select **Save session**.
89
-
90
-
:::image type="content" source="media/cognitive-search-debug/debug-session-new.png" lightbox="media/cognitive-search-debug/debug-session-new.png" alt-text="Screenshot of a debug session page." border="true":::
92
+
1. If you made changes, select **Save session**, followed by **Run**.
91
93
92
94
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.
93
95
@@ -119,7 +121,7 @@ To prove whether a modification resolves an error, follow these steps:
119
121
120
122
AI enrichment pipelines extract or infer information and structure from source documents, creating an enriched document in the process. An enriched document is first created during document cracking and populated with a root node (`/document`), plus nodes for any content that is lifted directly from the data source, such as metadata and the document key. More nodes are created by skills during skill execution, where each skill output adds a new node to the enrichment tree.
121
123
122
-
Enriched documents are internal, but a debug session gives you access to the content produced during skill execution. To view the content or output of each skill, follow these steps:
124
+
All content created or used by a skillset appears in the Expression Evaluator. You can hover over the links to view each input or output value in the enriched document tree. To view the input or output of each skill, follow these steps:
123
125
124
126
1. In a debug session, expand the blue arrow to view context-sensitive details. By default, the detail is the enriched document data structure. However, if you select a skill or a mapping, the detail is about that object.
125
127
@@ -133,10 +135,12 @@ Enriched documents are internal, but a debug session gives you access to the con
133
135
134
136
:::image type="content" source="media/cognitive-search-debug/debug-session-skills-detail-expression-evaluator.png" lightbox="media/cognitive-search-debug/debug-session-skills-detail-expression-evaluator.png" alt-text="Screenshot showing a skill details pane with Expression Evaluator for a given output.":::
135
137
136
-
## Check mappings
138
+
## Check index mappings
137
139
138
140
If skills produce output but the search index is empty, check the field mappings. Field mappings specify how content moves out of the pipeline and into a search index.
139
141
142
+
:::image type="content" source="media/cognitive-search-debug/debug-session-index-mapping.png" alt-text="Screenshot of the index mappings area of the workflow.":::
143
+
140
144
Select one of the mapping options and expand the details view to review source and target definitions.
141
145
142
146
+[**Projection Mappings**](index-projections-concept-intro.md) are found in skillsets that provide integrated vectorization, such as the skills created by the [Import and vectorize data wizard](search-get-started-portal-import-vectors.md). These mappings determine parent-child (chunk) field mappings and whether a secondary index is created for just the chunked content
Copy file name to clipboardExpand all lines: articles/search/cognitive-search-tutorial-debug-sessions.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,11 +15,11 @@ ms.date: 08/20/2024
15
15
16
16
# Tutorial: Fix a skillset using Debug Sessions
17
17
18
-
A skillset coordinates the actions of skills that analyze, transform, or create searchable content. Frequently, 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.
18
+
In Azure AI Search, a skillset coordinates the actions of skills that analyze, transform, or create searchable content. Frequently, 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.
19
19
20
-
**Debug sessions** is an Azure portal tool that 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.
20
+
**Debug Sessions** is an Azure portal tool that provides a holistic visualization of a skillset that executes on Azure AI Search. Using this tool, you can drill down to specific steps to easily see where an action might be falling down.
21
21
22
-
In this article, use **Debug sessions** to find and fix missing inputs and outputs. The tutorial is all-inclusive. It provides sample data, a REST file that creates objects, and instructions for debugging problems in the skillset.
22
+
In this article, use **Debug Sessions** to find and fix missing inputs and outputs. The tutorial is all-inclusive. It provides sample data, a REST file that creates objects, and instructions for debugging problems in the skillset.
23
23
24
24
If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
25
25
@@ -44,7 +44,7 @@ This section creates the sample data set in Azure Blob Storage so that the index
44
44
45
45
1.[Download sample data (clinical-trials-pdf-19)](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/_ARCHIVE/clinical-trials/clinical-trials-pdf-19), consisting of 19 files.
46
46
47
-
1.[Create an Azure storage account](../storage/common/storage-account-create.md?tabs=azure-portal) or [find an existing account](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Storage%2storageAccounts/).
47
+
1.[Create an Azure Storage account](../storage/common/storage-account-create.md?tabs=azure-portal) or [find an existing account](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Storage%2storageAccounts/).
48
48
49
49
+ Choose the same region as Azure AI Search to avoid bandwidth charges.
50
50
@@ -126,7 +126,7 @@ Another way to investigate errors and warnings is through the Azure portal.
126
126
127
127
1. **Save** the session. Saving the session kicks off the enrichment pipeline as defined by the skillset for the selected document.
128
128
129
-
1. Accept the default document choice for the first document in the collection. A debug session only works with a single document. You can choose which document to debug, or just use the first one.
129
+
1. Accept the default document choice for the first document in the collection. A debug session only works with a single document. You can [choose which document to debug](cognitive-search-how-to-debug-skillset.md#create-a-debug-session), or just use the first one.
130
130
131
131
1. When the debug session has finished initializing, you should see a skills workflow with mappings and a search index. The enriched document data structure appears in a details pane on the side.
|[**Debug session improvements**](cognitive-search-debug-session.md)| feature |Debug session has an improved user experience with a horizontal layout for skills processing, improved navigation, support for integrated vectorization and data chunking scenarios, and more information on the page. |
26
+
|[**Debug session improvements**](cognitive-search-debug-session.md)| feature |There are two important improvements. First, you can now debug integrated vectorization and data chunking workloads. Second, debug sessions has been modified to use a simpler, horizontal layout for skills processing. You can select an object in the flow, and view it's details off to the side. The previous tabbed layout is fully replaced with more context sensitive information on the page. |
27
27
|[**2024-07-01**](/rest/api/searchservice/search-service-api-versions?view=rest-searchservice-2024-07-01&preserve-view=true)| API | Stable release of REST APIs for generally available vector data types, vector compression, and integrated vectorization during indexing and queries. |
28
28
|[**Integrated vectorization**](vector-search-integrated-vectorization.md)| Feature | Announcing general availability. Skills-driven data chunking and embedding during indexing. |
29
29
|[**Vectorizers**](vector-search-how-to-configure-vectorizer.md)| Feature | Announcing general availability. Text-to-vector conversion during query execution. Both [Azure OpenAI vectorizer](vector-search-vectorizer-azure-open-ai.md) and [custom Web API vectorizer](vector-search-vectorizer-custom-web-api.md) are generally available. |
0 commit comments