Azure AI 搜尋服務中的偵錯工作階段

偵錯工作階段是視覺化編輯器，適用於 Azure 入口網站中現有的技能集，將會公開在工作階段期間由索引子和技能集所產生的單一擴充文件結構和內容。 由於您使用的是即時文件，所以可以與工作階段互動：您可以識別錯誤、修改和叫用技能執行，並且即時驗證結果。 如果能透過變更解決問題，則可將變更認可至已發佈的技能集，以全域套用修正程式。

本文說明支援的案例，以及編輯器的組織方式。 編輯器的索引標籤和區段會解除封裝不同的技能集層，讓您可以檢查技能集結構、流程，以及其在執行階段所產生的內容。

支援的案例

使用偵錯工作階段調查並解決以下幾方面的問題：

• 用於 AI 擴充的內建技能，例如 OCR、影像分析、實體辨識和關鍵字擷取。

• 用於整合向量化的內建技能，透過文字分割進行資料區塊化，以及透過內嵌技能進行向量化。

• 用來整合您所提供的外部處理的自訂技能。

以下將比較前兩個案例的偵錯工作階段影像。 對於這兩種案例，介面區會顯示產生內容從將其從來源文件轉換到搜尋索引的技能有何進展。 流程中包含索引對應選項，您可以依循箭號追蹤處理軌跡。 右側的詳細資料窗格具內容相關性。 它會顯示管線所建立擴充文件的表示法，或技能或對應的詳細資料。

第一個影像顯示套用 AI 擴充的模式 (無向量)。 如果沒有相依性，技能可以循序或平行執行。 索引對應會顯示擴充或產生的內容如何從記憶體內部資料結構移至索引中的欄位。 擴充的文件會顯示技能集所建立的資料結構。

第二個影像顯示整合向量化的典型模式。 整合向量化的技能通常包括文字分割技能和內嵌技能。 文字分割技能會將文件分割成區塊。 內嵌技能會呼叫內嵌 API 來向量化這些區塊。 此特定技能集會將內容區塊化為「頁面」的陣列。 針對整合向量化，投影對應可控制區塊如何與索引中的欄位對應。

限制

偵錯工作階段適用於所有正式可用的索引子資料來源和大部分預覽資料來源，但有下列例外狀況：

• SharePoint 索引子。

• Azure Cosmos DB for MongoDB 索引子。

• 針對 Azure Cosmos DB for NoSQL，如果資料列在索引期間失敗，而且沒有對應的中繼資料，偵錯工作階段可能無法挑選正確的資料列。

• 針對 Azure Cosmos DB 的 SQL API，如果分割的集合先前未分割，偵錯工作階段就無法找到文件。

• 針對自訂技能，對 Azure 儲存體的偵錯工作階段連線不支援使用者指派的受控識別。 如必要條件所述，您可以使用系統受控識別，或指定包含金鑰的完整存取連接字串。 如需詳細資訊，請參閱使用受控識別將搜尋服務連線至其他 Azure 資源。

• 透過 客戶管理的金鑰 （CMK） 啟用加密的數據來源。

• 不支援共享私有連結。 如果你的搜尋服務使用私有端點連線來存取資料來源或其他資源，除錯會話就無法存取這些資源。 關於解決方法，請參見 除錯會話與私人連線。

• 目前，無法選取要偵錯的文件。 此限制不是永久性的，應該很快就會取消。 此時，偵錯工作階段會選取來源資料容器或資料夾中的第一份文件。

偵錯工作階段的運作方式

當您啟動工作階段時，搜尋服務會建立一組技能、索引子和包含單份文件的資料來源，用來測試技能。 Azure AI 搜尋服務 服務會將所有會話狀態儲存到你提供的 Azure 儲存體 帳號中建立的新 blob 容器。 產生的容器名稱前綴為 ms-az-cognitive-search-debugsession。 這個前綴降低了誤將會話資料匯出到帳號內其他容器的機率。

如果您使用 受控識別 來設定儲存體帳戶連線，請在儲存體帳戶上將 Storage Blob Data Contributor 角色指派給您的搜尋服務識別。 在您的儲存帳號中，啟用可信服務以允許從 Azure AI 搜尋服務 寫入。

會將擴充文件與技能集的快取複本載入視覺化編輯器，讓您可以檢視擴充文件的內容和中繼資料，也能確定每個文件節點並編輯技能集定義的任何層面。 工作階段內所做的任何變更都會快取處理。 除非您認可這些變更，否則這些變更不會影響已發佈的技能集。 認可變更將會覆寫生產技能。

如果擴充管線沒有任何錯誤，就可以使用偵錯工作階段，以累加方式擴充文件、測試及驗證每個變更，然後再認可變更。

除錯工作階段透過分析資料、技能輸入輸出及欄位映射，協助找出錯誤或警告的根本原因。 使用技能詳細資料面板檢查每個技能接收到的輸入和輸出。 此檢查有助於確認技能定義、表達式及場域映射是否正確形成。 若索引器遇到設定問題，如網路設定錯誤或權限相關存取錯誤，請檢視該錯誤訊息及連結的文件。 有關故障排除的指引，請參閱 常見索引器錯誤與警告。

除錯會話與私人連線

除錯會話不支援共享私有連結。 如果你的生產搜尋服務使用私有端點連線來存取資料來源或其他資源，除錯會話就無法針對該服務執行。

變通方法：使用測試搜尋服務

若要對技能集進行偵錯，請建立不受私有連線限制的獨立 Azure AI 搜尋服務 服務。 為了避免生產資料和結構細節進入非私有環境，請用合成文件來建立你的測試架構：

• 建立與生產資料欄位類型和結構相符的測試文件，但使用通用欄位名稱（例如 content、 、 titlecategory）和佔位值，而非真實資料。 技能組邏輯取決於內容類型和結構，而非特定領域名稱。
• 從您的生產服務中複製技能組 JSON。 如果技能輸入參考了生產欄位名稱，請更新這些參考，使其與你的通用測試欄位名稱相符。 在測試索引器中使用 欄位映射 ，將測試欄位名稱與技能組輸入對齊。
• 設定索引器，使其針對測試資料來源執行。

在測試服務上執行除錯工作階段，檢查技能輸入與輸出、驗證技能表達式與欄位映射，並識別錯誤。 當你的變更被驗證後，請在技能組 JSON 中還原原始的生產欄位名稱參考，並將其套用回你的生產服務。

偵錯工作階段配置

視覺化編輯器會組織成顯示作業進度的介面區，首先是文件萃取，接著是技能、對應和索引。

選取任何技能或對應，即會開啟一個窗格，顯示相關資訊。

請遵循連結進一步鑽研技能處理。 例如，下列螢幕擷取畫面顯示文字分割技能第一次反覆運算的輸出。

技能詳細資料窗格

[技能詳細資料] 窗格有下列區段：

• 反覆運算：顯示技能的執行次數。 您可以檢查每一次的輸入和輸出。
• 技能設定：檢視或編輯 JSON 技能集定義。
• 錯誤和警告：顯示此技能特有的錯誤或警告。

擴充資料結構窗格

當您選取藍色的顯示或隱藏箭頭符號時，[擴充資料結構] 窗格會滑到側邊。 這是擴充文件所含內容的人類可讀表示法。 本文中先前的螢幕擷取畫面顯示擴充資料結構的範例。

後續步驟

現在已了解偵錯工作階段的各項元素，請在現有的技能集上啟動您的第一個偵錯工作階段。