Habilidade Layout de Documento

A habilidade de Layout de Documento analisa um documento a fim de detectar a estrutura e as características, e gera uma representação sintática do documento no formato Markdown ou Text. Você pode usá-lo a fim de extrair texto e imagens, em que a extração de imagens inclua os metadados de localização que preservam a posição da imagem no documento. A proximidade da imagem com o conteúdo relacionado é benéfica em cargas de trabalho RAG (geração aumentada de recuperação) e cenários de pesquisa multimodal.

Este artigo constitui a documentação de referência para a habilidade Layout de Documento. Para obter informações de uso, confira Como dividir e vetorizar por layout de documento.

Essa habilidade usa o modelo de layout da Inteligência de Documentos do Azure no Foundry Tools.

Essa habilidade é associada a um recurso cobrável do Microsoft Foundry para transações que excedam 20 documentos por indexador ao dia. A execução de habilidades internas é cobrada pelo preço do Foundry Tools Standard existente.

Limitations

Essa habilidade tem as seguintes limitações:

• A habilidade não é adequada para documentos grandes que exigem mais de 5 minutos de processamento no modelo de layout da Inteligência de Documentos do Azure. A habilidade atinge o tempo limite, mas as cobranças ainda se aplicarão ao recurso do Foundry se ele estiver anexado ao conjunto de habilidades para fins de cobrança. Verifique se os documentos estão otimizados a fim de permanecer nos limites de processamento e evitar custos desnecessários.

• Como essa habilidade chama o modelo de layout da Inteligência de Documentos do Azure, todos os comportamentos de serviço documentados para tipos de documento distintos para tipos de arquivo diversos se aplicam à sua saída. Por exemplo, arquivos do Word (DOCX) e PDF podem gerar resultados distintos devido a diferenças no tratamento de imagens. Caso o comportamento de imagem consistente em arquivos DOCX e PDF seja necessário, considere converter os documentos em PDF ou examinar a documentação de pesquisa multimodal a fim de encontrar abordagens alternativas.

Regiões com suporte

A habilidade Layout de Documento chama a API de 30-11-2024 da Inteligência de Documentos do Azure versão V4.0.

As regiões compatíveis variam de acordo com a modalidade e como a habilidade se conecta ao modelo de layout da Inteligência de Documentos do Azure.

A versão implementada do modelo Layout de Documento não tem suporte para as regiões 21Vianet no momento.

Formatos de arquivo com suporte

Essa habilidade reconhece os formatos de arquivo a seguir.

• .PDF
• .JPEG
• .JPG
• .PNG
• .BMP
• .TIFF
• .DOCX
• .XLSX
• .PPTX
• .HTML

Idiomas com suporte

Consulte os idiomas compatíveis com o modelo de layout da Inteligência de Documentos do Azure para texto impresso.

@odata.type

Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill

Limites de dados

• Para arquivos PDF e TIFF, até 2.000 páginas podem ser processadas (com uma assinatura de camada gratuita, apenas as primeiras duas páginas são processadas).
• Mesmo que o tamanho do arquivo a fim de analisar documentos seja de 500 MB para a camada paga da Inteligência de Documentos do Azure (S0) e de 4 MB para a camada gratuita da Inteligência de Documentos do Azure (F0), a indexação estará sujeita aos limites do indexador da sua camada de serviço de pesquisa.
• As dimensões da imagem devem estar entre 50 pixels x 50 pixels ou 10.000 pixels x 10.000 pixels.
• Caso os arquivos PDFs estejam bloqueados por senha, remova o bloqueio antes de executar o indexador.

Parâmetros de habilidades

Os parâmetros diferenciam maiúsculas de minúsculas. Vários parâmetros foram apresentados em versões de visualização específicas da API REST. É recomendável usar a versão disponível em geral (2025-09-01) ou a versão preliminar mais recente (versão preliminar de 2025-11-01) a fim de ter acesso total a todos os parâmetros.

Entradas de habilidades

A entrada "file_data" precisa ser um objeto definido da seguinte forma:

{
  "$type": "file",
  "data": "BASE64 encoded string of the file"
}

Alternativamente, ele pode ser definido como:

{
  "$type": "file",
  "url": "URL to download file",
  "sasToken": "OPTIONAL: SAS token for authentication if the URL provided is for a file in blob storage"
}

É possível gerar o objeto de referência de arquivo de uma destas maneiras:

• Especificar o parâmetro allowSkillsetToReadFileData na definição do indexador como true. Essa configuração cria um caminho /document/file_data que é um objeto representando os dados do arquivo original baixados da fonte de dados de blob. Esse parâmetro se aplica apenas a arquivos no Armazenamento de Blobs do Azure.

• Ter uma habilidade personalizada que retorna uma definição de objeto JSON que fornece $type, data ou url e sastoken. O parâmetro $type deve ser definido como file, e o data deve ser a matriz de bytes codificados de base 64 do conteúdo do arquivo. O parâmetro url deve ser uma URL válida com acesso a fim de baixar o arquivo nesse local.

Saídas de habilidades

Definição de exemplo para o modo de saída markdown

{
  "skills": [
    {
      "description": "Analyze a document",
      "@odata.type": "#Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill",
      "context": "/document",
      "outputMode": "oneToMany", 
      "markdownHeaderDepth": "h3", 
      "inputs": [
        {
          "name": "file_data",
          "source": "/document/file_data"
        }
      ],
      "outputs": [
        {
          "name": "markdown_document", 
          "targetName": "markdown_document" 
        }
      ]
    }
  ]
}

Saída de exemplo para o modo de saída markdown

{
  "markdown_document": [
    { 
      "content": "Hi this is Jim \r\nHi this is Joe", 
      "sections": { 
        "h1": "Foo", 
        "h2": "Bar", 
        "h3": "" 
      },
      "ordinal_position": 0
    }, 
    { 
      "content": "Hi this is Lance",
      "sections": { 
         "h1": "Foo", 
         "h2": "Bar", 
         "h3": "Boo" 
      },
      "ordinal_position": 1,
    } 
  ] 
}

O valor do markdownHeaderDepth controla o número de chaves no dicionário "seções". Na definição de habilidade de exemplo, como o markdownHeaderDepth é "h3", existem três chaves no dicionário "seções": h1, h2, h3.

Exemplo de modo de saída de texto e extração de imagem e metadados

Esse exemplo demonstra como gerar conteúdo de texto em partes de tamanho fixo e extrair imagens junto com metadados de localização do documento.

Definição de exemplo para o modo de saída de texto e a extração de imagem e metadados

{
  "skills": [
    {
      "description": "Analyze a document",
      "@odata.type": "#Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill",
      "context": "/document",
      "outputMode": "oneToMany",
      "outputFormat": "text",
      "extractionOptions": ["images", "locationMetadata"],
      "chunkingProperties": {     
          "unit": "characters",
          "maximumLength": 2000, 
          "overlapLength": 200
      },
      "inputs": [
        {
          "name": "file_data",
          "source": "/document/file_data"
        }
      ],
      "outputs": [
        { 
          "name": "text_sections", 
          "targetName": "text_sections" 
        }, 
        { 
          "name": "normalized_images", 
          "targetName": "normalized_images" 
        } 
      ]
    }
  ]
}

Saída de exemplo para o modo de saída de texto e também de extração de imagem e metadados

{
  "text_sections": [
      {
        "id": "1_7e6ef1f0-d2c0-479c-b11c-5d3c0fc88f56",
        "content": "the effects of analyzers using Analyze Text (REST). For more information about analyzers, see Analyzers for text processing.During indexing, an indexer only checks field names and types. There's no validation step that ensures incoming content is correct for the corresponding search field in the index.Create an indexerWhen you're ready to create an indexer on a remote search service, you need a search client. A search client can be the Azure portal, a REST client, or code that instantiates an indexer client. We recommend the Azure portal or REST APIs for early development and proof-of-concept testing.Azure portal1. Sign in to the Azure portal 2, then find your search service.2. On the search service Overview page, choose from two options:· Import data wizard: The wizard is unique in that it creates all of the required elements. Other approaches require a predefined data source and index.All services > Azure Al services | Al Search >demo-search-svc Search serviceSearchAdd indexImport dataImport and vectorize dataOverviewActivity logEssentialsAccess control (IAM)Get startedPropertiesUsageMonitoring· Add indexer: A visual editor for specifying an indexer definition.",
        "locationMetadata": {
          "pageNumber": 1,
          "ordinalPosition": 0,
          "boundingPolygons": "[[{\"x\":1.5548,\"y\":0.4036},{\"x\":6.9691,\"y\":0.4033},{\"x\":6.9691,\"y\":0.8577},{\"x\":1.5548,\"y\":0.8581}],[{\"x\":1.181,\"y\":1.0627},{\"x\":7.1393,\"y\":1.0626},{\"x\":7.1393,\"y\":1.7363},{\"x\":1.181,\"y\":1.7365}],[{\"x\":1.1923,\"y\":2.1466},{\"x\":3.4585,\"y\":2.1496},{\"x\":3.4582,\"y\":2.4251},{\"x\":1.1919,\"y\":2.4221}],[{\"x\":1.1813,\"y\":2.6518},{\"x\":7.2464,\"y\":2.6375},{\"x\":7.2486,\"y\":3.5913},{\"x\":1.1835,\"y\":3.6056}],[{\"x\":1.3349,\"y\":3.9489},{\"x\":2.1237,\"y\":3.9508},{\"x\":2.1233,\"y\":4.1128},{\"x\":1.3346,\"y\":4.111}],[{\"x\":1.5705,\"y\":4.5322},{\"x\":5.801,\"y\":4.5326},{\"x\":5.801,\"y\":4.7311},{\"x\":1.5704,\"y\":4.7307}]]"
        },
        "sections": []
      },
      {
        "id": "2_25134f52-04c3-415a-ab3d-80729bd58e67",
        "content": "All services > Azure Al services | Al Search >demo-search-svc | Indexers Search serviceSearch0«Add indexerRefreshDelete:selected: TagsFilter by name ...:selected: Diagnose and solve problemsSearch managementStatusNameIndexesIndexers*Data sourcesRun the indexerBy default, an indexer runs immediately when you create it on the search service. You can override this behavior by setting disabled to true in the indexer definition. Indexer execution is the moment of truth where you find out if there are problems with connections, field mappings, or skillset construction.There are several ways to run an indexer:· Run on indexer creation or update (default).. Run on demand when there are no changes to the definition, or precede with reset for full indexing. For more information, see Run or reset indexers.· Schedule indexer processing to invoke execution at regular intervals.Scheduled execution is usually implemented when you have a need for incremental indexing so that you can pick up the latest changes. As such, scheduling has a dependency on change detection.Indexers are one of the few subsystems that make overt outbound calls to other Azure resources. In terms of Azure roles, indexers don't have separate identities; a connection from the search engine to another Azure resource is made using the system or user- assigned managed identity of a search service. If the indexer connects to an Azure resource on a virtual network, you should create a shared private link for that connection. For more information about secure connections, see Security in Azure Al Search.Check results",
        "locationMetadata": {
          "pageNumber": 2,
          "ordinalPosition": 1,
          "boundingPolygons": "[[{\"x\":2.2041,\"y\":0.4109},{\"x\":4.3967,\"y\":0.4131},{\"x\":4.3966,\"y\":0.5505},{\"x\":2.204,\"y\":0.5482}],[{\"x\":2.5042,\"y\":0.6422},{\"x\":4.8539,\"y\":0.6506},{\"x\":4.8527,\"y\":0.993},{\"x\":2.5029,\"y\":0.9845}],[{\"x\":2.3705,\"y\":1.1496},{\"x\":2.6859,\"y\":1.15},{\"x\":2.6858,\"y\":1.2612},{\"x\":2.3704,\"y\":1.2608}],[{\"x\":3.7418,\"y\":1.1709},{\"x\":3.8082,\"y\":1.171},{\"x\":3.8081,\"y\":1.2508},{\"x\":3.7417,\"y\":1.2507}],[{\"x\":3.9692,\"y\":1.1445},{\"x\":4.0541,\"y\":1.1445},{\"x\":4.0542,\"y\":1.2621},{\"x\":3.9692,\"y\":1.2622}],[{\"x\":4.5326,\"y\":1.2263},{\"x\":5.1065,\"y\":1.229},{\"x\":5.106,\"y\":1.346},{\"x\":4.5321,\"y\":1.3433}],[{\"x\":5.5508,\"y\":1.2267},{\"x\":5.8992,\"y\":1.2268},{\"x\":5.8991,\"y\":1.3408},{\"x\":5.5508,\"y\":1.3408}]]"
        },
        "sections": []
       }
    ],
    "normalized_images": [ 
        { 
            "id": "1_550e8400-e29b-41d4-a716-446655440000", 
            "data": "SGVsbG8sIFdvcmxkIQ==", 
            "imagePath": "aHR0cHM6Ly9henNyb2xsaW5nLmJsb2IuY29yZS53aW5kb3dzLm5ldC9tdWx0aW1vZGFsaXR5L0NyZWF0ZUluZGV4ZXJwNnA3LnBkZg2/normalized_images_0.jpg",  
            "locationMetadata": {
              "pageNumber": 1,
              "ordinalPosition": 0,
              "boundingPolygons": "[[{\"x\":2.0834,\"y\":6.2245},{\"x\":7.1818,\"y\":6.2244},{\"x\":7.1816,\"y\":7.9375},{\"x\":2.0831,\"y\":7.9377}]]"
            }
        },
        { 
            "id": "2_123e4567-e89b-12d3-a456-426614174000", 
            "data": "U29tZSBtb3JlIGV4YW1wbGUgdGV4dA==", 
            "imagePath": "aHR0cHM6Ly9henNyb2xsaW5nLmJsb2IuY29yZS53aW5kb3dzLm5ldC9tdWx0aW1vZGFsaXR5L0NyZWF0ZUluZGV4ZXJwNnA3LnBkZg2/normalized_images_1.jpg",  
            "locationMetadata": {
              "pageNumber": 2,
              "ordinalPosition": 1,
              "boundingPolygons": "[[{\"x\":2.0784,\"y\":0.3734},{\"x\":7.1837,\"y\":0.3729},{\"x\":7.183,\"y\":2.8611},{\"x\":2.0775,\"y\":2.8615}]]"
            } 
        }
    ] 
}

Observe que “sections” na saída de exemplo acima aparece em branco. Com o intuito de preenchê-los, adicione uma habilidade adicional configurada com outputFormat definida como markdowna fim de assegurar o preenchimento correto das seções.

A habilidade usa a Inteligência de Documentos do Azure a fim de calcular locationMetadata. Consulte o modelo de layout da Inteligência de Documentos do Azure a fim de obter detalhes sobre a definição de páginas e das coordenadas de polígono delimitador.

O imagePath representa o caminho relativo de uma imagem armazenada. Caso a projeção de arquivo do repositório de conhecimento esteja configurada no conjunto de habilidades, esse caminho corresponderá ao caminho relativo da imagem armazenada no repositório de conhecimento.

Consulte também

• O que é o modelo de layout da Inteligência de Documentos do Azure
• Habilidades integradas
• Como definir um conjunto de habilidades
• Criar Indexador (API REST)