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
The **Document Layout** skill analyzes a document to extract regions of interest and their inter-relationships to produce a syntactical representation of the document in Markdown or Text format. You can use it to extract text and images. Image extraction includes location metadata that preserves image position within the document. Image proximity to related content is better for Retrieval Augmented Generation (RAG) workloads and [multimodal search](multimodal-search-overview.md).
21
+
The **Document Layout** skill analyzes a document to detect structure and characteristics, and produces a syntactical representation of the document in Markdown or Text format. You can use it to extract text and images, where image extraction includes location metadata that preserves image position within the document. Image proximity to related content adds value to Retrieval Augmented Generation (RAG) workloads and [multimodal search](multimodal-search-overview.md).
22
22
23
-
This article is the reference documentation for the Document Layout skill. For usage information, see [Structure-aware chunking and vectorization](search-how-to-semantic-chunking.md).
23
+
This article is the reference documentation for the Document Layout skill. For usage information, see [How to chunk and vectorize by document layout](search-how-to-semantic-chunking.md).
24
24
25
25
It's common to use this skill on content such as PDFs that have structure and images. The following tutorials demonstrate several scenarios:
26
26
@@ -34,15 +34,22 @@ It's common to use this skill on content such as PDFs that have structure and im
34
34
> This skill is bound to a [billable Azure AI multi-service resource](cognitive-search-attach-cognitive-services.md) for transactions that exceed 20 documents per indexer per day. Execution of built-in skills is charged at the existing [Azure AI services Standard price](https://azure.microsoft.com/pricing/details/cognitive-services/).
35
35
>
36
36
37
-
## Supported regions
37
+
## Supported models and regions
38
38
39
39
The Document Layout skill calls the [Document Intelligence Public preview version 2024-07-31-preview](/rest/api/aiservices/operation-groups?view=rest-aiservices-v4.0%20(2024-07-31-preview)&preserve-view=true).
40
40
41
-
Supported regions vary by modality:
41
+
Supported regions vary by modality and how the skill connects to the Document Intelligence layout model.
42
42
43
+
| Approach | Regions | Requirement |
44
+
|----------|---------|-------------|
45
+
|[Import and vectorize data wizard](search-import-data-portal.md)|**East US**, **West Europe**, **North Central US**| Create an Azure AI multi-service resource in one of these regions to get the portal experience. |
46
+
| Programmatic, using a [keyless connection (preview)](cognitive-search-attach-cognitive-services.md#bill-through-a-keyless-connection) to a multi-service region for billing purposes | Variable | Create Azure AI Search in one of these regions: **East US**, **West Europe**, **North Central US**, **West US 2**. Access Document Intelligence through an Azure AI multi-service resource in any region per the [Product availability by region](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/table) table.|
47
+
| Programmatic, using a [multi-service resource API key](cognitive-search-attach-cognitive-services.md#bill-through-a-keyless-connection) for billing purposes |**East US**, **West Europe**, **North Central US**, **West US 2**| Create your Azure AI Search service and AI multi-service resource in the same region. |
48
+
49
+
<!--
43
50
+ When you're using AI services keys [to attach your multi-service resource to your skillset](cognitive-search-attach-cognitive-services.md#bill-through-a-resource-key) via the REST API, both your Azure AI Search service and AI multi-service resource must be in the same region. This is only possible in the Azure regions of **East US**, **West Europe**, **North Central US**, **West US 2**. But if you're using a managed identity for [billing through a keyless connection](cognitive-search-attach-cognitive-services.md#bill-through-a-keyless-connection), your Azure AI Search service must be in one of the following regions: **East US**, **West Europe**, **North Central US**, **West US 2**. On the other hand, you can use AI Document Intelligence through an Azure AI multi-service resource in any region where this service is available. See [Product availability by region](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/table).
44
51
45
-
+ In the [Import and vectorize data wizard](search-import-data-portal.md) in the Azure portal, you can enable document layout detection in the data source connection step. Document layout detection in the portal is available in the following Azure regions: **East US**, **West Europe**, **North Central US**. Create an Azure AI multi-service resource in one of these three regions to get the portal experience.
52
+
+ In the [Import and vectorize data wizard](search-import-data-portal.md) in the Azure portal, you can enable document layout detection in the data source connection step. Document layout detection in the portal is available in the following Azure regions: **East US**, **West Europe**, **North Central US**. Create an Azure AI multi-service resource in one of these three regions to get the portal experience.-->
46
53
47
54
## Supported file formats
48
55
@@ -61,7 +68,7 @@ This skill recognizes the following file formats.
61
68
62
69
## Supported parameters
63
70
64
-
Several parameters are version-specific. The skills parameter table notes the API version in which a parameter was introduced so that you know whether a version upgrade is required. To use version-specific features such as image and location metadata extraction in [2025-05-01-preview REST API](/rest/api/searchservice/skillsets/create?view=rest-searchservice-2025-05-01-preview&preserve-view=true), you can use the Azure portal, or target a REST API version, or check an Azure SDK change log to see if it supports the feature.
71
+
Several parameters are version-specific. The skills parameter table notes the API version in which a parameter was introduced so that you know how to configure the skill. To use version-specific features such as image and location metadata extraction in [2025-05-01-preview REST API](/rest/api/searchservice/skillsets/create?view=rest-searchservice-2025-05-01-preview&preserve-view=true), you can use the Azure portal, or target 2025-05-01-preview, or check an Azure SDK change log to see if it supports the new parameters.
65
72
66
73
The Azure portal supports most preview features and can be used to create or update a skillset. For updates to the Document Layout skill, edit the skillset JSON definition to add new preview parameters.
67
74
@@ -85,7 +92,6 @@ Refer to [Azure AI Document Intelligence layout model supported languages](/azur
85
92
During the public preview, this skill has the following restrictions:
86
93
87
94
+ The skill isn't suitable for large documents requiring more than 5 minutes of processing in the AI Document Intelligence layout model. The skill times out, but charges still apply to the AI Services multi-services resource if it attaches to the skillset for billing purposes. Ensure documents are optimized to stay within processing limits to avoid unnecessary costs.
88
-
89
95
90
96
## Skill parameters
91
97
@@ -97,13 +103,13 @@ Parameters are case-sensitive.
97
103
|`markdownHeaderDepth`|[2024-11-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2024-11-01-preview&preserve-view=true)|`h1`, `h2`, `h3`, `h4`, `h5`, `h6(default)`| Only applies if `outputFormat` is set to `markdown`. This parameter describes the deepest nesting level that should be considered. For instance, if the markdownHeaderDepth is `h3`, any sections that are deeper such as `h4`, are rolled into `h3`. |
98
104
|`outputFormat`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)|`markdown(default)`, `text`|**New**. Controls the format of the output generated by the skill. |
99
105
|`extractionOptions`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)|`["images"]`, `["images", "locationMetadata"]`, `["locationMetadata"]`|**New**. Identify any extra content extracted from the document. Define an array of enums that correspond to the content to be included in the output. For instance, if the `extractionOptions` is `["images", "locationMetadata"]`, the output includes images and location metadata which provides page location information related to where the content was extracted, such as a page number or section. This parameter applies to both output formats. |
100
-
|`chunkingProperties`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)| See below |**New**. Only applies if `outputFormat` is set to `text`. Options that encapsulate how to chunk text content while recomputing other metadata. |
106
+
|`chunkingProperties`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)| See below.|**New**. Only applies if `outputFormat` is set to `text`. Options that encapsulate how to chunk text content while recomputing other metadata. |
|`unit`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)|`Characters`. currently the only allowed value. Chunk length is measured in characters, as opposed to words or tokens | Controls the cardinality of the chunk unit. |
105
-
|`maximumLength`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)| Any integer between 300-50000 | The maximum chunk length in characters as measured by String.Length. |
106
-
|`overlapLength`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)| Integer. The value needs to be less than the half of the `maximumLength`| The length of overlap provided between two text chunks. |
110
+
|`unit`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)|`Characters`. currently the only allowed value. Chunk length is measured in characters, as opposed to words or tokens |**New**. Controls the cardinality of the chunk unit. |
111
+
|`maximumLength`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)| Any integer between 300-50000 |**New**. The maximum chunk length in characters as measured by String.Length. |
112
+
|`overlapLength`|[2025-05-01-preview](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true)| Integer. The value needs to be less than the half of the `maximumLength`|**New**. The length of overlap provided between two text chunks. |
107
113
108
114
## Skill inputs
109
115
@@ -145,6 +151,7 @@ The file reference object can be generated in one of following ways:
145
151
|`normalized_images`| Only applies if `outputFormat` is set to `text` and `extractionOptions` includes `images`. A collection of images that were extracted from the document, including `locationMetadata` if applicable.|
146
152
147
153
## Sample definition for markdown output mode
154
+
148
155
```json
149
156
{
150
157
"skills": [
@@ -204,7 +211,7 @@ The value of the `markdownHeaderDepth` controls the number of keys in the "secti
204
211
205
212
This example demonstrates how to use the new parameters introduced in the **2025-05-01-preview** to output text content in fixed-sized chunks and extract images along with location metadata from the document.
206
213
207
-
## Sample definition for text output mode and image and metadata extraction
214
+
###Sample definition for text output mode and image and metadata extraction
208
215
209
216
```json
210
217
{
@@ -242,7 +249,7 @@ This example demonstrates how to use the new parameters introduced in the **2025
242
249
}
243
250
```
244
251
245
-
## Sample output for text output mode and image and metadata extraction
252
+
###Sample output for text output mode and image and metadata extraction
246
253
247
254
```json
248
255
{
@@ -292,7 +299,9 @@ This example demonstrates how to use the new parameters introduced in the **2025
292
299
]
293
300
}
294
301
```
302
+
295
303
The skill uses [Azure AI Document Intelligence](/azure/ai-services/document-intelligence/overview) to compute locationMetadata. Refer to [Document Intelligence layout model](/azure/ai-services/document-intelligence/concept-layout) for details on how pages and bounding polygon coordinates are defined.
304
+
296
305
The `imagePath` represents the relative path of a stored image. If the knowledge store file projection is configured in the skillset, this path matches the relative path of the image stored in the knowledge store.
0 commit comments