使用 Azure 內容理解技能進行內容分塊與向量化

Note

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

Important

這些功能支援與其他 Microsoft 服務 及第三方服務的連結。 使用這些服務須遵守其各自的條款,可能導致資料處理或儲存超出 Azure 合規邊界,以及資料流入 Azure 合規邊界。

你有責任管理資料是否會超出組織的合規與地理邊界及相關影響,並確保適當的權限、邊界與核准被提供。

你有責任仔細審查並測試你在特定使用情境中所建置的應用程式,並做出所有適當的決策與客製化。 這包括實施你自己負責任的 AI 緩解措施,例如元提示、內容過濾器或其他安全系統,並確保你的應用程式符合適當的品質、可靠性、安全性與可信度標準。 欲了解更多資訊,請參閱 Foundry IQ(Azure AI 搜尋服務)透明度說明。

在本文中,請運用 Azure 內容理解技能建立索引管線,以:

  • 從文件中擷取文字與圖片
  • 產出語意連貫且遵循段落與章節邊界的區塊
  • 可選擇性地生成圖表、圖表及其他內嵌圖片的 AI 描述
  • 將每個區塊嵌入向量搜尋,並投影到 Foundry IQ 索引中

Azure 內容理解技能會在每份文件中回傳一個或多個區塊。 每個區塊包含 Markdown 格式的內容、位置元資料(頁碼與邊界多邊形),以及可選的擷取影像參考。 當你設 chunkingProperties.method 為 semantic時,區塊會跟隨段落和標題的邊界,而不是固定字元範圍。 當您設定 modelName 和 modelDeployment 時,技能會呼叫 Azure OpenAI 對話補全部署,以產生內嵌影像的描述。 技能接著會將這些描述合併到區塊內容中。

語意分塊與影像描述通常可在本導覽全程使用的 Search REST API 2026-10-01中使用。 這項可用性與 技能所呼叫的內容理解 API 是分開的。

本文在 Blob 儲存體 中使用範例健康計畫 PDF。 關於 SharePoint 文件,請參閱在 Foundry IQ 中擷取並豐富 SharePoint 文件。 請勿將本教學中可選的影像儲存步驟套用於受權限保護的內容。 欲了解更多,請參閱 SharePoint ACL 限制。

先決條件

  • 在任何 支援區域內提供 Foundry IQ 服務。 Foundry IQ 服務本身在此案例中不受區域限制。

  • 位於支援區域且附加到技能組的 Microsoft Foundry 資源。

  • (選用)位於同一個 Foundry 資源中的 Azure OpenAI 聊天完成部署,使用 Content Understanding 支援的模型。 語意分塊與映像擷取不需要這種部署。

  • Foundry 資源中的支援的 Azure OpenAI 嵌入模型部署。 這些範例使用 1,536 個維度;選擇支援此值的模型,或同時變更索引與技能維度。

  • 一個Azure Blob 儲存體容器,裡面放你想索引的檔案。 本文使用 Blob 資料來源搭配 allowSkillsetToReadFileData 索引子設定 (用於將檔案內容傳遞至 Content Understanding 技能)。

  • 建立並執行搜尋物件並查詢索引的權限。 使用基於角色的搜尋存取與搜尋管理式識別。 將附加技能集所需的 Foundry 資源角色 和 Cognitive Services OpenAI 使用者 角色授予該身分,範圍為承載嵌入部署的 Foundry 資源。

對於每個 HTTP 要求,請將 https://<search-service>.search.windows.net 替換為 {endpoint},並將 <access-token> 替換為 Foundry IQ 服務的權杖。 請以您自己的值取代 Foundry 資源與模型部署占位符。 <MODEL_NAME> 是可選的描述模型; <EMBEDDING_MODEL_NAME> 是嵌入模型,而非其部署名稱。

在嵌入技能與查詢時向量器中使用相同的嵌入資源端點、部署與模型。 範例使用 Foundry 資源端點(https://<resource>.services.ai.azure.com),而非專案 URL。

Overview

本文建構了一個一對多的索引管線。 每個來源文件會產生多個搜尋文件(每個區塊一個):

  1. 索引器會從 Azure Blob 儲存體 讀取每個檔案,並透過 /document/file_data 將二進位內容傳給技能組。

  2. Azure 內容理解技能使用語意分區來產生 text_sections。 當你同時設定 modelName 和 modelDeployment時,技能也會產生嵌入圖片描述,並將其內嵌到區塊的 Markdown 中。

  3. Azure OpenAI 嵌入技能 每個區塊執行一次,並產生區塊內容的向量。

  4. 索引投影會將每個區塊各寫入一份搜尋文件到目標索引中,並將內容、頁面中繼資料、影像參照及向量對應到各欄位。

  5. (可選)knowledge store 會將 normalized_images 投影至 Azure Blob 儲存體,讓用戶端應用程式可透過 URL 擷取這些已擷取的影像。

準備數據檔

Azure 內容理解技能會處理每份文件的二進位內容,因此原始檔案必須是該技能支援的格式。 關於目前的清單,請參閱 內容理解服務限制。 常見支援格式包括 PDF、DOCX、XLSX、PPTX 以及許多影像格式。

將您的檔案上傳至 Blob 儲存體 容器。 你可以使用 Azure 入口網站、REST API 或 Azure SDK 來建立資料來源。

以下最小請求會建立整個流程中所使用的資料來源。

POST {endpoint}/datasources?api-version=2026-10-01
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "my_blob_datasource",
  "type": "azureblob",
  "credentials": {
    "connectionString": "<your-blob-connection-string>"
  },
  "container": {
    "name": "my-container"
  }
}

建立一對多編製索引的索引

每份搜尋文件對應內容理解技能產生的一個區塊。 該指數需要:

  • 一個關鍵欄位(chunk_id)。
  • 一個父欄位,用來標示該區塊parent_id來自哪個來源文件()。
  • 儲存區塊內容、頁面元資料和圖片參考的欄位。
  • 一個用於區塊嵌入的向量場。

以下的索引定義與你在下一節所建立的技能組相符。

PUT {endpoint}/indexes/my_content_understanding_index?api-version=2026-10-01
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "my_content_understanding_index",
  "fields": [
    {
      "name": "chunk_id",
      "type": "Edm.String",
      "key": true,
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false,
      "analyzer": "keyword"
    },
    {
      "name": "parent_id",
      "type": "Edm.String",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "title",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "chunk",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "page_number_from",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "page_number_to",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "image_path",
      "type": "Edm.String",
      "searchable": false,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "text_vector",
      "type": "Collection(Edm.Single)",
      "searchable": true,
      "retrievable": false,
      "stored": false,
      "dimensions": 1536,
      "vectorSearchProfile": "profile"
    }
  ],
  "semantic": {
    "defaultConfiguration": "semantic-config",
    "configurations": [
      {
        "name": "semantic-config",
        "prioritizedFields": {
          "titleField": {"fieldName": "title"},
          "prioritizedContentFields": [{"fieldName": "chunk"}]
        }
      }
    ]
  },
  "vectorSearch": {
    "profiles": [
      {
        "name": "profile",
        "algorithm": "algorithm",
        "vectorizer": "query-vectorizer"
      }
    ],
    "algorithms": [
      {
        "name": "algorithm",
        "kind": "hnsw"
      }
    ],
    "vectorizers": [
      {
        "name": "query-vectorizer",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://<embedding-resource>.services.ai.azure.com",
          "deploymentId": "<embedding-deployment>",
          "modelName": "<EMBEDDING_MODEL_NAME>"
        }
      }
    ]
  }
}

定義語意分塊與向量化的技能組

目標索引就緒後,定義產生區塊、向量和投影對應並將其饋送至索引的技能集。

這個技能組合包含兩項技能:

  • Azure 內容理解技能 會將每份文件切分成區塊。 將 chunkingProperties.method 設為 semantic 會遵循段落與標題的界線。 獨立設定兩個模型屬性,可在向量化前啟用影像描述。 有關支援的數值,請參閱 技能參數。

  • Azure OpenAI 嵌入技能會為每個區塊的內容產生向量。

這個技能組用 indexProjections 來將每個區塊對應到獨立的搜尋文件。 如需詳細資訊,請參閱 定義索引投影。

此請求使用 Foundry IQ 服務為 Foundry 和嵌入存取而指派的系統受控識別。 Blob connection-string 範例是獨立的;對於無金鑰來源連線,請為 資料來源使用管理識別。

以下範例包含圖片描述。 如果您略過選用的影像描述部署,請使用 計費和影像描述控制項 移除相關設定,再提交技能組。 在啟動管線前,請先檢視該處適用的收費。

POST {endpoint}/skillsets?api-version=2026-10-01
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "my_content_understanding_skillset",
  "description": "Semantic chunking, image descriptions, and vectorization with the Azure Content Understanding skill",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
      "name": "my_content_understanding_skill",
      "context": "/document",
      "modelName": "<MODEL_NAME>",
      "modelDeployment": "<chat-deployment>",
      "chunkingProperties": {
        "method": "semantic",
        "unit": "tokens",
        "maximumLength": 500
      },
      "extractionOptions": ["images", "locationMetadata"],
      "inputs": [
        {
          "name": "file_data",
          "source": "/document/file_data"
        }
      ],
      "outputs": [
        {
          "name": "text_sections",
          "targetName": "text_sections"
        },
        {
          "name": "normalized_images",
          "targetName": "normalized_images"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "my_azure_openai_embedding_skill",
      "context": "/document/text_sections/*",
      "inputs": [
        {
          "name": "text",
          "source": "/document/text_sections/*/content"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "text_vector"
        }
      ],
      "resourceUri": "https://<embedding-resource>.services.ai.azure.com",
      "deploymentId": "<embedding-deployment>",
      "modelName": "<EMBEDDING_MODEL_NAME>",
      "dimensions": 1536
    }
  ],
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
    "subdomainUrl": "https://<foundry-resource>.services.ai.azure.com",
    "identity": null
  },
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "my_content_understanding_index",
        "parentKeyFieldName": "parent_id",
        "sourceContext": "/document/text_sections/*",
        "mappings": [
          {
            "name": "chunk",
            "source": "/document/text_sections/*/content"
          },
          {
            "name": "text_vector",
            "source": "/document/text_sections/*/text_vector"
          },
          {
            "name": "page_number_from",
            "source": "/document/text_sections/*/locationMetadata/pageNumberFrom"
          },
          {
            "name": "page_number_to",
            "source": "/document/text_sections/*/locationMetadata/pageNumberTo"
          },
          {
            "name": "image_path",
            "source": "/document/text_sections/*/imagePath"
          },
          {
            "name": "title",
            "source": "/document/metadata_storage_name"
          }
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

關於內容理解技能的完整參數參考、支援值及驗證規則,請參見 Azure內容理解技能。

選擇區塊與描述選項

分塊、影像擷取和影像描述是彼此獨立的選項。 關於描述設定,請使用 標準描述控制項。

對於固定大小的區塊,請將內容理解技能的 chunkingProperties 替換為 {"method": "fixedSize", "unit": "characters", "maximumLength": 1325, "overlapLength": 0}。 關於允許的範圍與重疊規則,請參見 chunkingProperties。

設定和執行索引子

建立並執行一個索引器,從你的資料來源讀取,呼叫技能集,並將區塊投影到索引中。 設定 allowSkillsetToReadFileData 為 true 內容理解技能接收檔案內容,並設 parsingMode 為 default。

在這種情況下你不需要 outputFieldMappings 。 技能組中的 indexProjections 區塊已將每個分塊對應至目標索引欄位。

POST {endpoint}/indexers?api-version=2026-10-01
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "my_content_understanding_indexer",
  "dataSourceName": "my_blob_datasource",
  "targetIndexName": "my_content_understanding_index",
  "skillsetName": "my_content_understanding_skillset",
  "parameters": {
    "batchSize": 1,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "default",
      "allowSkillsetToReadFileData": true
    }
  },
  "fieldMappings": [],
  "outputFieldMappings": []
}

當索引器執行時,內容理解技能會將檔案分割,並可選擇性地產生描述。 索引投影每個區塊寫入一份搜尋文件。 如果您更新現有索引器,需要將此管線套用至先前已編入索引的檔案,請重設並執行索引器。 在未重置的情況下執行時,只會處理新檔案或已變更的檔案。

檢查索引器狀態

在查詢前,請確認索引器的執行完成:

GET {endpoint}/indexers/my_content_understanding_indexer/status?api-version=2026-10-01
Authorization: Bearer <access-token>

檢視 lastResult.status、 itemsProcessed、 itemsFailed、 errors及 warnings。 即使已處理數量非零,也檢查代表性區塊並調查遺失文件。 欲了解更多資訊,請參閱 「監控索引器狀態」。

驗證結果

查詢索引以確認區塊是否包含預期內容,且向量搜尋是否如預期運作。 使用 搜尋檔案總管 或任何能發送 HTTP 請求的工具。

以下請求執行一個混合查詢:在 chunk 上進行關鍵字搜尋,並對 text_vector 進行向量查詢。 查詢時向量化器會使用已設定的嵌入部署來嵌入查詢文字。

POST {endpoint}/indexes/my_content_understanding_index/docs/search?api-version=2026-10-01
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "search": "copay for in-network providers",
  "searchFields": "chunk",
  "count": true,
  "searchMode": "all",
  "vectorQueries": [
    {
      "kind": "text",
      "text": "copay for in-network providers",
      "fields": "text_vector"
    }
  ],
  "select": "chunk, title, page_number_from, page_number_to, image_path"
}

回應包含帶有所選欄位的 value 個項目。 檢查區塊內容與頁面關聯。 若要獨立檢查向量檢索,請在不包含 search、searchFields 和 searchMode 的情況下重複該請求,並保留 vectorQueries。 僅靠混合結果無法證明向量檢索成功。

以下回應結構僅為範例,並非即時執行時擷取的輸出;區塊邊界、文字、計數與分數會有所不同:

{
  "@odata.count": 2,
  "value": [
    {
      "@search.score": 0.0317,
      "chunk": "## Cost sharing\n\nFor in-network providers, the copay is $20 per visit...\n\n![Chart: Copay comparison across plans](figures/3)",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 4,
      "page_number_to": 4,
      "image_path": "figures/3"
    },
    {
      "@search.score": 0.0289,
      "chunk": "### Out-of-network providers\n\nWhen you visit a provider that isn't in the Northwind network, the copay is $40 per visit...",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 5,
      "page_number_to": 6,
      "image_path": null
    }
  ]
}

回應包括:

  • chunk: 每個區塊的 Markdown 內容。 當您在「內容理解」技能中設定這兩個模型屬性時,產生的圖片描述會針對適用的圖形以內嵌方式顯示。
  • page_number_from 以及 page_number_to:產生該區塊的頁數範圍。
  • image_path:使用區塊擷取的影像路徑,或當區塊跨越多個影像時,則為分號分隔的路徑清單。 具體形狀取決於是否設定了知識儲存檔案投影。 若無檔案投影,路徑即為範例所示的簡短形式(figures/3)。 在檔案投影中,路徑是知識庫中影像的相對路徑。 若要讓這些影像提供給用戶端應用程式,請參見 (Optional) Project 影像以供檢索。

(可選)用於檢索的專案影像

image_path索引中儲存的值並非可直接存取的 URL。 若要擷取影像,請使用知識儲存庫將 normalized_images 投影至 Azure Blob 儲存體。 您的用戶端應用程式接著可以從儲存的影像路徑中建構 blob URL。

這個步驟是選擇性的。 只有當你的客戶端應用程式需要顯示或下載擷取後的圖片時才加入。

將以下設定片段中的 knowledgeStore 屬性新增至技能集負載中。 使用 PUT {endpoint}/skillsets/my_content_understanding_skillset?api-version=2026-10-01 更新現有技能集。 此選用的 Blob 情境不支援受權限保護的 SharePoint 內容。

{
  "knowledgeStore": {
    "storageConnectionString": "<your-azure-storage-connection-string>",
    "projections": [
      {
        "files": [
          {
            "storageContainer": "extracted-images",
            "source": "/document/normalized_images/*"
          }
        ],
        "tables": [],
        "objects": []
      }
    ]
  }
}

若要為已編入索引的文件填入新檔案投影,請 重設並執行索引器。 這會以更新的技能集重新處理來源檔案。

索引器執行後,容器中的 extracted-images 每個 blob 對應一個 normalized_images 元素。 blob URL 的格式為 https://<storage-account>.blob.core.windows.net/<container>/<imagePath>。 當一個區塊 image_path 包含多個分號分隔的路徑時,請使用每個獨立儲存的影像路徑。 您的應用程式也需要授權存取 Blob 儲存體;檔案投影不會讓影像公開或啟用知識庫影像服務。

如需完整結構描述,包括其他投影類型(tables 和 objects)及驗證選項,請參閱 Foundry IQ 中的知識庫「投影」。

控制產生的影像文字描述

有關直接與產生的管線設定,包括退出驗證與資產儲存限制,請參閱 計費與圖片描述控制。

清理資源

當不再需要擷取時,停止或刪除索引器及其排程。 當你不再需要資料來源、技能組和索引時,請刪除它們。 搜尋容量、Blob 檔案與擷取影像、Foundry 資源與模型部署具有獨立的生命週期;刪除搜尋物件不會刪除那些外部資源,也不會撤銷已產生的費用。

對於產生的知識來源,請使用其已記錄的刪除程序並 檢視其產生的物件。 不要刪除其他管線使用的共用資源。

Troubleshooting

如果索引器失敗或回傳意外結果,請檢查以下常見原因。

技能組驗證在 400 級時失敗

當參數組合不一致時,技能會回傳 400 Skill validation failed 錯誤。 常見原因:

  • 已設定 modelName 但未設定 modelDeployment,或反之亦然。 兩者必須同時設置。
  • 你將 semantic 設為 overlapLength,並將 method 設為大於 0 的值。 設定 overlapLength 為 0 或省略。
  • method 與 unit 不是受支援的配對。 將 fixedSize 與 characters 搭配使用,或將 semantic 與 tokens 搭配使用。

對 Foundry 資源授權失敗

如果技能呼叫 Foundry 資源時回傳 401 或 403,請確認:

text_sections 是空的

如果索引文件沒有區塊,請確認:

  • 支援此檔案格式。 關於清單,請參見 支援的檔案格式。
  • Foundry 資源位於受支援的區域。
  • 受密碼保護的 PDF 在索引前會先解鎖。

缺少圖片說明

如果區塊不包含內嵌影像描述,請檢查 描述設定、附加 Foundry 資源中的部署情況,以及其可用的 TPM 或 RPM 配額。

內容理解分析疑難排解

預設的文件分析輪詢視窗為 八分鐘。 當此視窗到期時,程序會回傳技能逾時錯誤,並不會產生該文件的內容理解輸出。 這個過期不一定會讓整個索引器執行失敗。

利用執行細節來區分原因:

症狀或證據 支票
分析輪詢後技能逾時 具代表性的文件複雜度、可選工作、資源位置,以及權威的 大型文件指引。 批次大小不會改變此視窗。
分析器建立後未變為就緒 這是一個獨立的作業,就緒輪詢逾時時間為五分鐘,而非八分鐘的文件分析時段。
終端內容理解失敗或格式錯誤的輸出 已回報的服務錯誤及支援的檔案/輸入格式。 不要把每一個缺失的區塊都診斷為輪詢逾時。
HTTP 逾時、429 或服務不可用 請求與網路失敗、節流限制,以及已設定的模型與服務容量。 重試延遲可能會占用輪詢時間。
401 或 403 身分、角色指派、資源端點和網路存取。
檔案與頁面配額或索引器執行時間耗盡 Content Understanding 服務限制與搜尋索引器限制,分別。

記錄索引器名稱、執行時間、受影響的來源識別碼、技能名稱、錯誤詳細資料,以及支援可用的請求與關聯 ID。 不要包含存取權杖、金鑰或受保護的文件內容。 請參閱 索引器疑難排解 及 常見錯誤與警告。

在重新執行或重置之前,請考量重複進行擷取、描述與嵌入所需的成本。 不要假設會有快取分析、恢復輪詢、取消先前的內容理解操作,或不會被收取重複處理費用。