文件配置技能

文件配置技能會分析文件以偵測結構和特性，並以 Markdown 或 Text 格式產生文件的語法表示法。 您可以使用它來擷取文字和影像，其中影像擷取包含的位置中繼資料保留了文件內的影像位置。 相關內容的影像鄰近性對於擷取擴增生成 (RAG) 工作負載和多模態搜尋情境很實用。

本文是文件配置技能的參考文件。 如需使用資訊，請參閱如何根據文件配置進行區塊化和向量化。

此技能使用了 Foundry 工具的 Azure 文件智慧服務的配置模型。

這項技能與可計費的 Microsoft Foundry 資源綁定，適用於每天每個索引子超過 20 份文件的交易。 內建技能的執行會按照現有 的 Foundry 工具標準價格收費。

Limitations

此技能有下列限制：

• 這項技能不適合用在 Azure 文件智慧服務的配置模型需要處理超過 5 分鐘的大型文件。 如果已與需計費的技能連結，技能會逾時，但 Foundry 資源仍會產生費用。 請務必將文件最佳化，維持在處理上限內，以免不必要的成本。

• 由於此技能會呼叫 Azure 文件智慧服務配置模型，不同文件類型的所有文件服務行為都會按照不同檔案類型套用到其輸出。 舉例來說，Word (DOCX) 和 PDF 檔案可能會因為影像處理方式的差異而產生不同的結果。 如果 DOCX 和 PDF 需要一致的影像行為，建議將文件轉換為 PDF，或參閱多模態搜尋文件了解替代方法。

支援的區域

文件配置技能會呼叫 Azure 文件智慧服務 2024-11-30 API 版本 V4.0。

支援的區域依模態及技能與 Azure 文件智慧服務配置模型的連結方式而異。

目前實作的文件配置模型尚不支援 21 Vianet 區域。

支援的檔案格式

此技能可識別下列文件格式。

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

支援的語言

請參閱 Azure 文件智慧服務配置模型支援的語言來處理印刷文字。

@odata.type

Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill

資料限制

• 若使用 PDF 和 TIFF，最多可處理 2,000 頁 (若使用免費層訂閱，則只會處理前兩頁)。
• 雖然 Azure 文件智慧服務付費 (S0) 層級分析文件的檔案大小是 500 MB，而 Azure 文件智慧服務免費 (F0) 層級為 4 MB，索引編制仍受限於搜尋服務層級的索引子上限。
• 影像尺寸必須介於 50 像素 x 50 像素或 10,000 像素 x 10,000 像素之間。
• 如果您的 PDF 已有密碼鎖定，請在執行索引子前先移除鎖定。

技能參數

參數會區分大小寫。 REST API 的特定預覽版本已引進數個參數。 建議使用正式版本 (2025-09-01) 或最新預覽版 (2025-11-01-preview)，以完整存取所有參數。

技能輸入

「file_data」輸入必須為定義如下的物件：

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

或者，它也可以定義為：

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

檔案參照物件可以透過下列其中一種方式產生：

• 將索引子定義的 allowSkillsetToReadFileData 參數設為 true。 此設定建立的路徑 /document/file_data 是代表從 Blob 資料來源下載的原始檔案資料的物件。 此參數僅適用於 Azure Blob 儲存體的檔案。

• 具備的自訂技能所傳回的 JSON 物件定義會提供 $type、data 或 url 和 sastoken。 $type 參數必須設為 file，且 data 必須是 Base 64 編碼位元組陣列的檔案內容。 參數 url 必須是有效 URL，可存取該位置以下載檔案。

技能輸出

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" 
        }
      ]
    }
  ]
}

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,
    } 
  ] 
}

markdownHeaderDepth 的值控制了「sections」字典的索引鍵數目。 在技能定義範例中，由於 markdownHeaderDepth 是「h3」，因此「sections」字典有三個索引鍵：h1、h2、h3。

文字輸出模式和影像集中繼資料擷取的範例

此範例示範如何以固定大小的區塊輸出文字內容，並從文件擷取影像及位置中繼資料。

文字輸出模式和影像及中繼資料擷取的定義範例

{
  "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" 
        } 
      ]
    }
  ]
}

文字輸出模式和影像及中繼資料擷取的輸出範例

{
  "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}]]"
            } 
        }
    ] 
}

請注意，上述範例輸出的 “sections” 顯示為空白。 若要填入，您要新增的額外技能需將 outputFormat 設為 markdown 以確保章節正確填入。

此技能使用 Azure 文件智慧服務來計算位置中繼資料。 請參閱 Azure 文件智慧服務配置模型以了解頁面與邊界多邊形座標的定義方法。

imagePath表示已儲存影像的相對路徑。 如果在技能集設定知識存放區檔案投影，此路徑會與儲存在知識存放區的影像相對路徑相符。

另請參閱

• 什麼是 Azure 文件智慧服務配置模型
• 內建技能
• 如何定義技能集
• 建立索引子 (REST API)