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 服務本身在此案例中不受區域限制。
(選用)位於同一個 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
本文建構了一個一對多的索引管線。 每個來源文件會產生多個搜尋文件(每個區塊一個):
索引器會從 Azure Blob 儲存體 讀取每個檔案,並透過
/document/file_data將二進位內容傳給技能組。Azure 內容理解技能使用語意分區來產生
text_sections。 當你同時設定modelName和modelDeployment時,技能也會產生嵌入圖片描述,並將其內嵌到區塊的 Markdown 中。Azure OpenAI 嵌入技能 每個區塊執行一次,並產生區塊內容的向量。
索引投影會將每個區塊各寫入一份搜尋文件到目標索引中,並將內容、頁面中繼資料、影像參照及向量對應到各欄位。
(可選)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",
"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,請確認:
- 技能組中的
cognitiveServices方塊指向正確的鑄造資源。 - Foundry IQ 服務所使用的身份在 Foundry 資源中具有所需的角色。 如需了解受控識別設定,請參閱 在 Foundry IQ 中將可計費資源附加至技能集。
text_sections 是空的
如果索引文件沒有區塊,請確認:
- 支援此檔案格式。 關於清單,請參見 支援的檔案格式。
- Foundry 資源位於受支援的區域。
- 受密碼保護的 PDF 在索引前會先解鎖。
缺少圖片說明
如果區塊不包含內嵌影像描述,請檢查 描述設定、附加 Foundry 資源中的部署情況,以及其可用的 TPM 或 RPM 配額。
內容理解分析疑難排解
預設的文件分析輪詢視窗為 八分鐘。 當此視窗到期時,程序會回傳技能逾時錯誤,並不會產生該文件的內容理解輸出。 這個過期不一定會讓整個索引器執行失敗。
利用執行細節來區分原因:
| 症狀或證據 | 支票 |
|---|---|
| 分析輪詢後技能逾時 | 具代表性的文件複雜度、可選工作、資源位置,以及權威的 大型文件指引。 批次大小不會改變此視窗。 |
| 分析器建立後未變為就緒 | 這是一個獨立的作業,就緒輪詢逾時時間為五分鐘,而非八分鐘的文件分析時段。 |
| 終端內容理解失敗或格式錯誤的輸出 | 已回報的服務錯誤及支援的檔案/輸入格式。 不要把每一個缺失的區塊都診斷為輪詢逾時。 |
| HTTP 逾時、429 或服務不可用 | 請求與網路失敗、節流限制,以及已設定的模型與服務容量。 重試延遲可能會占用輪詢時間。 |
| 401 或 403 | 身分、角色指派、資源端點和網路存取。 |
| 檔案與頁面配額或索引器執行時間耗盡 | Content Understanding 服務限制與搜尋索引器限制,分別。 |
記錄索引器名稱、執行時間、受影響的來源識別碼、技能名稱、錯誤詳細資料,以及支援可用的請求與關聯 ID。 不要包含存取權杖、金鑰或受保護的文件內容。 請參閱 索引器疑難排解 及 常見錯誤與警告。
在重新執行或重置之前,請考量重複進行擷取、描述與嵌入所需的成本。 不要假設會有快取分析、恢復輪詢、取消先前的內容理解操作,或不會被收取重複處理費用。