Azure 內容理解技能

Note

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

Azure 內容理解技能使用 Foundry Tools 中的 Azure 內容理解工具中的文件分析器,從文件中擷取文字、圖片及位置中繼資料。 它同時也將內容分塊用於 多模態搜尋、 代理檢索及 檢索增強生成 (RAG)。 這個分塊不需要額外加文字分割技能。

基本技能一般可在 Search REST API 2026-04-01中取得。 在 中引入 2026-05-01-preview的語意分塊與 AI 生成的影像描述,通常可在 Search REST API 2026-10-01中提供。 本文中的範例請使用 2026-10-01。 此搜尋 API 版本與 支援區域中下游的內容理解 API 版本不同。

與 文件版面配置技能相比,此技能能產生 Markdown 表格與圖表,辨識跨頁表格,並支援跨頁區塊。 以下功能是獨立的:

  • 分塊:fixedSize 按角色劃分; semantic 依照版面、段落與標題邊界使用字元長度。 語意分塊並不是語意排序。
  • 影像擷取:extractionOptions 包含 images 會產生 normalized_images。 僅靠擷取無法實現 AI 生成的描述。
  • 圖片描述:配對與modelDeployment設定允許modelName描述嵌入的圖表、圖表與圖表,並內嵌於區塊的 Markdown 中,然後再進行向量化。 僅靠語意分塊無法實現描述。
  • 嵌入與影像服務: 為向量設定獨立的嵌入技能。 擷取或描述影像本身並不會讓客戶端取得影像,或啟用檢索時影像服務。

關於基於 Blob 的程序,請參閱 使用 Content Understanding 進行區塊與向量化。

關於 SharePoint 文件,請參閱在 Foundry IQ(Azure AI 搜尋服務)中擷取並豐富 SharePoint 文件。 選擇知識來源 API 設定以簡化設定與生命週期操作,或選擇索引器與技能組設定以獲得更多控制。

局限性

  • 搜尋會在 分析輪詢視窗內等待文件分析。 大型檔案不會自動不適合,且在服務限制內的檔案也不保證能在該時間內完成。

  • 內容:了解不同文件類型的服務行為 ,適用於輸出。 例如,DOCX 與 PDF 檔案可能會產生不同的影像結果。 測試代表性檔案;當需要一致的影像處理時,請考慮 PDF 轉換。

  • 操作說明中的選用影像儲存程序不適用於匯入文件權限的管線。 在合併技能、預測與儲存空間前,先檢視 SharePoint ACL 的限制。

  • 附加於技能集的 Foundry 資源中部署的可選 modelName 並 modelDeployment 選擇聊天完成模式。

  • 支援的完成模型由 Content Understanding 的 prebuilt-document 分析器決定。 遵循 內容理解支援的生成模型。 僅有配置接受並不能證明所選模型在執行時可正常運作。

分析、民調與大型文件

對內容理解文件分析作業進行輪詢的預設最大窗口為 八分鐘。 提交非同步分析後,搜尋會輪詢操作以判斷終端狀態。 視窗衡量該投票循環中經過的時間,包括等待與重試;它不是檔案大小的門檻、單一 HTTP 請求的逾時,也不是端對端完成的保證。

如果操作在輪詢視窗內未達到終端狀態,技能會回報技能逾時豐富錯誤,且不會回傳該文件的內容理解分析輸出。 檢查索引器執行錯誤與警告。 文件或整個執行失敗取決於剩餘的管線、預測值及已設定的索引器失敗閾值。 缺少區塊輸出並不代表所有來源元資料都被阻止被索引。 停止搜尋調查並不代表後續分析被取消。

此八分鐘分析視窗與建立自訂分析器、文件版面限制、個別 HTTP/技能請求逾時、重試延遲、模型配額,以及 索引器執行時間與層級限制的五分鐘準備投票逾時區分。 這項技能不會暴露面向客戶的分析調查覆蓋。

對於大型或複雜文件:

  • 衡量具代表性的檔案,包括頁數、檔案類型、版面配置、表格、圖形、語意區塊及可選描述。 模型/服務負載、節流以及跨區域延遲都會影響所過的時間。
  • 盡可能將搜尋與 Foundry 資源置於相同支援區域。 若不需要,請停用可選描述,或評估固定大小區塊。
  • 若您分割檔案,請保留有意義的章節、跨頁表格、來源識別碼、原始頁面偏移量、圖表參考、引用,以及每個衍生文件與區塊的適用權限。
  • 若支援的其他 擷取方式 符合您的內容與安全需求,請考慮其使用。 減少索引器批次大小並不會延長每份文件的輪詢視窗。

重新執行或重設索引器可能會重複分析並產生額外費用。 不要假設重試會重用先前的分析結果或恢復其輪詢狀態。 有關診斷,請參閱「 內容理解分析疑難排解」。

支援的區域

此技能呼叫內容 理解 2025-11-01 REST API。 您的 Foundry 資源必須位於 支援的內容理解區域。

您的 Foundry IQ 服務可位於任何 支援的 Foundry IQ 區域。 跨區域網路延遲會影響索引器效能。

支援的檔案格式

此技能可辨識 PDF、JPEG、JPG、PNG、BMP、HEIF、TIFF、DOCX、XLSX、PPTX、HTML、TXT、MD、RTF 及 EML 檔案。 有關目前格式特定的限制,請參閱 《內容理解服務限制》。

支援的語言

關於印刷文字,請參閱 「內容理解語言支援」。

@odata.type

Microsoft.Skills.Util.ContentUnderstandingSkill

資料限制

技能參數

參數依大小寫區分。

參數名稱 允許的值 Description
extractionOptions ["images"]、["images", "locationMetadata"]、["locationMetadata"] 可選配額外輸出。 images 擷取影像; locationMetadata 新增頁面與位置資訊。 這兩種設定都無法啟用描述。
modelName String 嵌入圖片描述可選的聊天完成模型名稱。 與 一起指定 modelDeployment。 該模型必須由內容理解(Content Understanding)支持;請參閱 支援的生成模型。
modelDeployment String 技能組附帶的 Foundry 資源中可選的部署名稱。 與 一起指定 modelName。 省略這兩個屬性以停用內建描述。
chunkingProperties 物件 下表中描述的可選區塊化設定。

chunkingProperties

Property 允許的值 Description
method fixedSize (預設), semantic 固定大小的字元視窗或符合版面配置的語意區塊。
unit characters 其中 fixedSize; tokens 其中 semantic 若省略,則由 推斷。method 其他配對則不支援。
maximumLength 300–50,000 字元或 100–8,000 個代幣 已設定單元中的最大區塊長度。 預設值:500。
overlapLength 小於一半的非負整數 maximumLength 預設值:0。 適用於 fixedSize。 對於 semantic,省略或設為 0。

技能輸入

輸入名稱 Description
file_data 原始檔案內容,非已擷取的文字。

使用包含 和 data 的檔案物件(base64 編碼的檔案位元組)或url($type: "file"可下載的檔案 URL)。 一個選用sasToken功能驗證 Blob 儲存體 檔案 URL。

對於 Blob 和 SharePoint 索引器管線,請在索引器上設定parameters.configuration.allowSkillsetToReadFileData為 。true 這會將原始檔案暴露為 /document/file_data;不會增加原始檔案或內容理解的限制。

自訂技能也可以回傳支援自訂技能的檔案物件。 請勿使用自訂的 Web API 技能來繞過對受權限保護內容的限制。

技能產出

輸出名稱 Description
text_sections 一組區塊,可能跨越多頁。
normalized_images 擷取的影像。 僅在 extractionOptions 包含 images時才出現。

每個 text_sections 元素包含:

Field 類型 Description
id String 區塊識別碼。
content String Markdown 內容。 僅在配對模型設定啟用時,才包含產生的圖形描述,與分塊方法無關。
locationMetadata 物件 pageNumberFrom、pageNumberTo、ordinalPosition 和 source。 在請求位置元資料時顯示。
imagePath String 在適用時,重疊的圖形跨度使用分號分隔的影像參考。 不是直接可檢索的網址。

每個normalized_images元素包含 id、base64 圖像data、、imagePath,以及在要求時。 locationMetadata

locationMetadata.source 保留 內容理解元素的位置編碼。 投影區塊時保持頁面與圖形關聯。 如果設定了相容的知識庫檔案投影,則 imagePath 會識別相對儲存的影像路徑。

帳單與影像描述控制項

此技能使用您附加於技能集的 Microsoft Foundry 資源進行處理與計費。 其他內建技能提供的免費文件允許則不適用。

內容解析器需要版面解析與擷取,這些費用與 Foundry IQ 分別產生。 設定後,影像語言化會使用您的 LLM 部署資料,並產生額外的模型使用費用。 檢視內容理解價格、Foundry IQ 價格,以及您已設定的 Azure OpenAI 模型的價格。

若要停用您直接設定的技能集中內建的影像描述,請從內容理解技能中省略或移除兩者modelNamemodelDeployment。 如果你還需要擷取的影像,就繼續保留extractionOptionsimages。 語意或固定大小的區塊可以在不加說明的情況下繼續進行。 停用描述並不會消除適用的內容理解擷取/區塊、搜尋、嵌入或檢索負擔。

對於使用標準擷取方式產生的知識來源管線,請修改知識來源本身, ingestionParameters 而非編輯其生成的技能集。 以下控制項適用於一般 GA 配置,且不需進行圖形擷取:

  1. 將 disableImageVerbalization 設定為 true。
  2. 省略或移除 chatCompletionModel。 在設定旗標時保留非空模型則被拒絕。
  3. 在支援時省略或移除 assetStore。 資產儲存驗證需要具備聊天完成模式並啟用圖片口述功能。
  4. 保留嵌入模型, aiServices以及其他必要的來源設定。 依照其類型,使用程序更新知識來源。
描述配置 Result
生成:旗標 true、無聊天模式、無資產儲存 描述:選擇退出;提取與分塊工作可以繼續進行。
產生:旗標 true,聊天模式保留 無效。 移除 chatCompletionModel。
產生:無模型或帶有旗標的資產儲存 true 無效。
產生:聊天模式、旗標 false 或省略 影像的語言表達可以持續進行;所選的擷取/模型路徑決定所使用的技能。

這些說明不適用於獨立預覽圖形擷取設定,該設定可使用聊天模式進行其他工作。 它們不會改變獨立記錄的知識來源類型或影像服務的可用性。

範例

這些是完整的技能組請求主體,而不是完整的索引流程。 請以您的搜尋端點及<access-token>該服務的令牌替換{endpoint}。 依照 「附加 Foundry 資源」所述,設定搜尋管理識別及其 Foundry 權限。

範例 1:固定大小分塊,並擷取影像與元資料

此配置可擷取影像而不產生描述。

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

{
  "name": "cu-fixed",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
      "context": "/document",
      "extractionOptions": ["images", "locationMetadata"],
      "chunkingProperties": {
        "method": "fixedSize",
        "unit": "characters",
        "maximumLength": 1325,
        "overlapLength": 0
      },
      "inputs": [{"name": "file_data", "source": "/document/file_data"}],
      "outputs": [
        {"name": "text_sections", "targetName": "text_sections"},
        {"name": "normalized_images", "targetName": "normalized_images"}
      ]
    }
  ],
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
    "subdomainUrl": "https://<foundry-resource>.services.ai.azure.com",
    "identity": null
  }
}

索引完成後,預期 text_sections 會有 Markdown 內容與位置元資料,以及 normalized_images 擷取出來的影像。 圖的參考依據來源文件而定;此範例中未設定描述模型。

範例 2:帶有影像描述的語意分塊

請以支援的聊天完成模型名稱及其<chat-deployment>在附件 Foundry 資源中的部署取代<MODEL_NAME>。 如需無描述的配置,請參閱 帳單與影像描述控制項。

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

{
  "name": "cu-semantic",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
      "context": "/document",
      "modelName": "<MODEL_NAME>",
      "modelDeployment": "<chat-deployment>",
      "extractionOptions": ["images", "locationMetadata"],
      "chunkingProperties": {
        "method": "semantic",
        "unit": "tokens",
        "maximumLength": 500
      },
      "inputs": [{"name": "file_data", "source": "/document/file_data"}],
      "outputs": [
        {"name": "text_sections", "targetName": "text_sections"},
        {"name": "normalized_images", "targetName": "normalized_images"}
      ]
    }
  ],
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
    "subdomainUrl": "https://<foundry-resource>.services.ai.azure.com",
    "identity": null
  }
}

預期 在 中會用語義分塊的 Markdown text_sections。 設定好模型配對後,生成的描述會嵌入到相關圖表的內容中。 影像擷取與位置元資料仍由 extractionOptions控制。 實際的區塊與描述會依來源和模型而異。

向量化內容理解區塊

對於向量搜尋,請將以下 Azure OpenAI 嵌入技能加入同一技能組的skills陣列。 它會處理每個內容理解區塊,並完成語意區塊與圖像語言化。 輸入包含 text 區塊 Markdown 中生成的圖片描述。

設定 resourceUri 為您的 Foundry 資源端點及 deploymentId 您的部署 text-embedding-3-large。 請將 嵌入技能的權限 與內容理解資源附件分開設定。

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "context": "/document/text_sections/*",
  "resourceUri": "https://<embedding-resource>.services.ai.azure.com",
  "deploymentId": "<embedding-deployment>",
  "modelName": "text-embedding-3-large",
  "dimensions": 3072,
  "inputs": [
    {"name": "text", "source": "/document/text_sections/*/content"}
  ],
  "outputs": [
    {"name": "embedding", "targetName": "text_vector"}
  ]
}

使用 Project/document/text_sections/*/text_vector 投影到你的區塊索引的向量場中。 在此範例中,將欄位的尺寸設定為 , 3072 並使用相容的 查詢時向量器。