使用 Azure Content Understanding 在 Foundry IQ (Azure AI 搜尋服務) 中擷取並擴充 SharePoint 文件內容。 本指引適用於 Microsoft 365 中的 SharePoint 索引器和 SharePoint(已建立索引)知識來源。
內建的解析功能提供文字擷取功能,並與其他 AI 強化技能搭配使用。 對於版面豐富或多模態文件,內容理解將版面感知解析、分塊和影像擷取結合於單一技能中。 它也會使用已部署的模型產生可選的影像描述。
支援的輸入包括 Microsoft Word (DOCX) 文件、Microsoft Excel (XLSX) 活頁簿,以及 Microsoft PowerPoint (PPTX) 簡報,但受格式限制。 使用知識 contentExtractionMode: "standard" 來源 API,以簡化設定與生命週期操作。 若要更精確控制技能、分區與投影,請直接設定 SharePoint 索引器與內容理解技能集。
Prerequisites
- 具備建立搜尋物件並查詢其內容權限的 Foundry IQ 服務。 對於知識來源路徑,請使用 支援代理檢索的區域。 請參閱「搜尋基於角色的存取」以了解適用的管理與資料角色。
- 完成 SharePoint 索引器先決條件及驗證設定。 關於權限擷取,請依照 ACL 先決條件操作,而非委託驗證範例。
- 位於內容理解支援區域的 Microsoft Foundry 資源。 在直接設定索引器與技能集時,請設定 Search 受控識別、所需角色及 技能集資源附加。
- 需要向量化時所需的嵌入部署。 若要使用可選的內建映像描述,需在附加的 Foundry 資源中有支援的描述模型部署。
- SharePoint 索引器與內容理解技能所支援的代表性檔案,包括您預期擷取的版面配置與圖表。
選擇萃取管線
根據您所需的處理作業及打算維護的資源選擇管線。
| 管線 | 在下列情況下使用 | 資源所有權 |
|---|---|---|
| 知識來源 API 配置 | 您希望透過單一 SharePoint(索引)知識來源設定來簡化設定。 | 搜尋會產生索引器、資料來源、技能集與索引。 利用知識來源設定與生命週期操作來維護它們。 |
| 索引器與技能組設定 | 你需要比知識來源設定所展現的更多技能、分塊或投影控制。 | 您可以直接設定並維護擷取物件及受保護索引。 如果您想在知識庫中使用索引,請新增搜尋索引知識來源。 |
這兩條路徑的結構如下。 在這兩條路徑中,模型流量都與 SharePoint 來源連線分開:
知識來源 API:SharePoint文件→產生索引器→內容理解語意區塊與圖像描述→嵌入技能→產生的安全區塊索引→ SharePoint(索引)知識來源→知識庫。
索引器與技能集 API:SharePoint文件→索引器→內容理解語意區塊與圖片描述→嵌入技能(用於向量搜尋)→安全區塊索引。 直接查詢索引,或透過搜尋索引知識來源將其連結至知識庫。
擴充連線: 內容理解技能→附加的 Foundry 資源供分析使用及可選的內建說明;嵌入技能→嵌入端點與部署。
對於索引式知識來源, minimal 擷取使用內建的解析功能。 它用於先擷取文字,或當分開的豐富化技能能提供所需的處理效果時。 選擇 standard 擷取,即可將 Content Understanding 的版面感知解析、分塊、影像擷取及可選描述整合到產生的管線中。
在直接設定索引器時,請將內容理解技能加入您的技能組合,以取得相同的整合文件處理能力。 你仍然會分別設定嵌入和任何額外的增強。
保持處理階段的區分:
- 版面擷取用來識別文件結構,包括章節、表格與圖表。 使用您支援格式的代表性檔案驗證擷取的結構。
- 分塊 準備內容範圍。 語意分塊會遵循版面配置與段落邊界;固定大小區塊使用字元視窗。 這兩種選擇單獨都無法啟用描述。
- 影像擷取 會產生影像資料與參考資料。 描述 為相關圖表新增生成的文字。
- 嵌入以向量的方式表示區塊內容。 影像服務 透過獨立支援的設定,讓影像在檢索時可用;擷取的圖片參考不是可下載的網址。
若要直接從 SharePoint 擷取資料,而非透過索引管線,請參閱 SharePoint(遠端)知識來源,其擷取與權限架構不同。
在 SharePoint(已索引)知識來源中使用標準擷取
標準擷取利用內容理解來解析支援的文件並在生成的管線中準備語意區塊。 在知識來源上設定權限及影像描述模型。 搜尋會建立底層資料來源、索引器、內容理解技能組以及受保護分塊索引。
- 請參考 建立索引化的 SharePoint 知識來源,以完成連線、來源選擇、身分識別及嵌入模型的設定。
- 在
indexedSharePointParameters.ingestionParameters中,配置以下 標準擷取設定:- 將
contentExtractionMode設定為standard。 - 將
ingestionPermissionOptions設為["userIds", "groupIds"],以保留 SharePoint 文件權限。 - 請使用您支援的 Foundry 資源端點設定
aiServices。
- 將
- 在該 Foundry 資源中的
chatCompletionModel設定支援的影像描述模型和部署。 將disableImageVerbalization保持設為false,或省略它。 檢視標準 影像描述控制項 以了解設定需求。 - 請在
resourceUri中使用您的 Foundry 資源端點設定embeddingModel.azureOpenAIParameters,加上嵌入deploymentId與modelName。 例如,端點請使用https://<embedding-resource>.services.ai.azure.com。 生成的嵌入技能會在索引前向量化內容理解的區塊內容,包括生成的圖片描述。 - 執行擷取並 檢視產生的物件,包括投影區塊的權限。
- 一旦成功匯入,知識來源即可 指派給知識庫。 您不需要為此流程另設一個獨立的搜尋索引知識來源。
Content Understanding 語意區塊與圖片描述通常可在搜尋 REST API 2026-10-01 中取得。 SharePoint 連接器與權限功能的可用性與 API 需求仍依各自文件另行說明。 下游的內容理解 API 版本另有文件說明。
將此檔案處理路徑限制為支援的文件。 以文字解析的 SharePoint list 項目與網站頁面,無法提供內容理解所需的原始檔案輸入。 不要假設文件庫檔案設定會不變更地套用於混合內容的選取。
設定 SharePoint 索引器與內容理解技能組
使用索引器與技能集 API,讓你對豐富化流程有更多掌控。 將您的 SharePoint 索引器連接到執行語意分塊與影像語言化的內容理解技能。 設定技能集與對應,以將強化區塊及其 SharePoint 權限寫入索引。
- 使用 SharePoint 索引器程序設定資料來源。 在資料來源中將
indexerPermissionOptions設為["userIds", "groupIds"],以保留來源權限。 請依照 SharePoint ACL 設定,用於索引中的驗證與權限篩選欄位。 - 在索引器上,設定
parameters.configuration.allowSkillsetToReadFileData為true。 此設定會在/document/file_data提供原始檔案,供內容理解技能的file_data輸入使用。 請使用原始檔案,而非已擷取的/document/content文字。 - 將具備語 意分塊與圖片描述的內容理解技能 加入您的技能組:
- 將
chunkingProperties.method設為semantic,並將chunkingProperties.unit設為tokens。 - 在附帶的 Foundry 資源中,將兩者
modelNamemodelDeployment設定為使用您支援的影像描述模型。 - 包含
images與locationMetadata輸入extractionOptions以進行影像擷取與定位輸出。 - 將
file_data對應至/document/file_data,並保留text_sections輸出。 每個相關區塊的 Markdown 內容中都會包含生成的描述。
- 將
- 對於向量搜尋,請在內容理解技能後新增嵌入技能:
- 設定
resourceUri為您的 Foundry 資源端點,例如https://<embedding-resource>.services.ai.azure.com,並配置deploymentId和modelName。 - 將技能的
context設定為/document/text_sections/*,並將其text輸入設定為/document/text_sections/*/content。 此架構會在包含圖片描述後,嵌入每個 Content Understanding 區塊。 - 將
embedding輸出映射到text_vector。 將向量維度與索引對齊,並設定相容的 查詢時向量器。
- 設定
- 定義 一對多的索引投影 ,設
sourceContext為/document/text_sections/*。 Project 區塊內容、/document/text_sections/*/text_vector已設定時的來源與引用欄位,以及所要求的位置中繼資料對應至區塊索引中。 - 請依照 SharePoint 權限投影的要求,在每個區塊上重複父文件的權限:
- 映射
/document/metadata_user_ids到索引的UserIds權限欄位。 - 映射
/document/metadata_group_ids到索引的GroupIds權限欄位。 - 對於 SharePoint 網站群組,也請將
/document/metadata_spo_site_url投影到SharePointSiteUrl,並設定所需的 SharePoint 群組 解析。 - 使用
projectionMode: skipIndexingParentDocuments時,請使用這些投影映射,而非僅依賴索引器欄位映射。
- 映射
- 執行索引器並檢查索引中已強化的區塊與權限。 若要在知識庫中使用索引,也請在 代理式擷取的索引準則 中設定欄位及語意設定。
內容理解在此流程中提供分塊與內建圖片描述;您不需要另外使用文字分割或 Chat Completion 技能來執行這些操作。 關於技能的輸入/輸出關係,請參閱 Content Understanding 逐步解說。 保留您的 SharePoint 來源與權限設定;不要複製教學中的 Blob 連線或可選的影像儲存步驟。
將權限元資料排除在技能與模型輸入之外。 請改由來源層級的投影對應來進行。 不要用自訂 Web API 技能來繞過受保護內容限制。
保留權限並驗證擷取
權限過濾在分塊與擷取後仍須保留。 使用使用者 ID、群組 ID 及適用的網站情境的標準 權限欄位與對應。 保留必要的來源路徑元資料以及可讀的引用資訊。 在一般查詢中保持權限欄位不可取回。
如果您直接設定索引器和技能集,就可以使用搜尋功能查詢結果索引。 若要在知識庫中使用該索引,請依照 「建立搜尋索引知識來源」,然後將其 指派到知識庫。 此交接使用現有索引;它不會匯入 SharePoint 內容或重執行內容理解。 在知識來源 API 設定中,請將 SharePoint(已索引)知識來源本身指派到知識庫中。
在正式使用任一管線之前:
- 檢查代表性區塊中的內容、設定好的向量、來源/引用關聯,以及所需的權限映射。
- 使用 查詢時間權限程序,對具有權限和遭拒絕的使用者進行直接搜尋查詢。 如果你使用知識庫,也要用這些使用者測試其擷取請求。
- 如果您的應用程式暴露了 MCP 端點,也請測試其使用者權杖傳播與存取結果。 檢查回傳的引用與來源資料欄位是否顯示遭拒絕存取的內容。
- 使用 SharePoint 同步指引測試適用的群組與站台情境,以及權限撤銷。 僅僅有索引成功並不能證明目前授權。
檢視網路與資源所有權
將應用程式對 Search 的入站存取與對外擷取分開處理。 Search 的私人端點不會建立與 SharePoint、Content Understanding 或模型部署的私人連線。
- SharePoint 來源: 使用連接器的驗證機制。 SharePoint Online 使用公開端點,並非共用私有連結目標。
- 內容理解分析: 使用附加的支援 Foundry 資源及其所需的身分識別與連線。
- 嵌入與可選聊天功能: 檢查每個已設定端點所支援的驗證、角色指派、DNS 及網路存取需求。
獨立的 GenAI 提示(聊天完成)或自訂端點不會代理內容理解分析器的呼叫。 API 管理不支援 Content Understanding。 若使用僅 ACL 的擷取,則需另行使用一個 Chat Completion 技能,且需使用允許的第一方端點,而非 APIM。 在敏感標籤匯入時,該聊天完成設定不被支援。
將 典型的受保護內容限制 套用至特定設定,包括自訂 Web API、快取、知識儲存、除錯及影像服務限制。 驗證或私有路由也不會讓封鎖的設定成為受支援的設定。
您維護您直接建立的管線物件。 對於精靈建立的物件,請使用該精靈的文件化工作流程。 對於由知識來源產生的物件,請使用知識來源設定與生命週期操作;不要將生成的物件視為無限制的自訂表面。
排除處理問題並維護管線
對於缺少內容理解輸出或處理緩慢的情況,請遵循 分析輪詢與大型文件指引的指引。 預設的分析輪詢視窗為八分鐘。 客製化分析器就緒有另外一個五分鐘的期限。 檢查 索引器狀態 ,以區分輪詢過期與驗證、節流、輸入格式或終端服務失敗。
使用 SharePoint 權限生命週期程序進行重新整理、重新同步、撤銷及支援的重建操作。 不要用內容重置來取代理解權限刷新行為。
在淘汰管線時,請停止其排程並使用其已記錄的刪除程序。 僅在不再需要客戶擁有的物件時,才將其移除。 刪除搜尋知識來源不會刪除外部 SharePoint 內容、Foundry 資源或模型部署。