偵錯工作階段是視覺化編輯器，適用於 Azure 入口網站中現有的技能集，將會公開在工作階段期間由索引子和技能集所產生的單一擴充文件結構和內容。 由於您使用的是即時文件，所以可以與工作階段互動：您可以識別錯誤、修改和叫用技能執行，並且即時驗證結果。 如果能透過變更解決問題，則可將變更認可至已發佈的技能集，以全域套用修正程式。
本文說明支援的案例，以及編輯器的組織方式。 編輯器的索引標籤和區段會解除封裝不同的技能集層，讓您可以檢查技能集結構、流程，以及其在執行階段所產生的內容。
支援的案例
使用偵錯工作階段調查並解決以下幾方面的問題：
以下將比較前兩個案例的偵錯工作階段影像。 對於這兩種案例，介面區會顯示產生內容從將其從來源文件轉換到搜尋索引的技能有何進展。 流程中包含索引對應選項，您可以依循箭號追蹤處理軌跡。 右側的詳細資料窗格具內容相關性。 它會顯示管線所建立擴充文件的表示法，或技能或對應的詳細資料。
第一個影像顯示套用 AI 擴充的模式 (無向量)。 如果沒有相依性，技能可以循序或平行執行。 索引對應會顯示擴充或產生的內容如何從記憶體內部資料結構移至索引中的欄位。 擴充的文件會顯示技能集所建立的資料結構。
第二個影像顯示整合向量化的典型模式。 整合向量化的技能通常包括文字分割技能和內嵌技能。 文字分割技能會將文件分割成區塊。 內嵌技能會呼叫內嵌 API 來向量化這些區塊。 此特定技能集會將內容區塊化為「頁面」的陣列。 針對整合向量化，投影對應可控制區塊如何與索引中的欄位對應。
限制
偵錯工作階段適用於所有正式可用的索引子資料來源和大部分預覽資料來源，但有下列例外狀況：
SharePoint 索引子。
Azure Cosmos DB for MongoDB 索引子。
針對 Azure Cosmos DB for NoSQL，如果資料列在索引期間失敗，而且沒有對應的中繼資料，偵錯工作階段可能無法挑選正確的資料列。
針對 Azure Cosmos DB 的 SQL API，如果分割的集合先前未分割，偵錯工作階段就無法找到文件。
針對自訂技能，對 Azure 儲存體的偵錯工作階段連線不支援使用者指派的受控識別。 如必要條件所述，您可以使用系統受控識別，或指定包含金鑰的完整存取連接字串。 如需詳細資訊，請參閱使用受控識別將搜尋服務連線至其他 Azure 資源。
透過 客戶管理的金鑰 （CMK） 啟用加密的數據來源。
目前，無法選取要偵錯的文件。 此限制不是永久性的，應該很快就會取消。 此時，偵錯工作階段會選取來源資料容器或資料夾中的第一份文件。
偵錯工作階段的運作方式
當您啟動工作階段時，搜尋服務會建立一組技能、索引子和包含單份文件的資料來源，用來測試技能。 所有工作階段狀態都會儲存到新 Blob 容器，該容器即是以您提供的 Azure 儲存體帳戶中的 Azure AI 搜尋服務所建立。 所產生容器的名稱具有 ms-az-cognitive-search-debugsession 的前置詞。 需要前置詞，因為它可降低意外將工作階段資料匯出至帳戶中另一個容器的機會。
會將擴充文件與技能集的快取複本載入視覺化編輯器，讓您可以檢視擴充文件的內容和中繼資料，也能確定每個文件節點並編輯技能集定義的任何層面。 工作階段內所做的任何變更都會快取處理。 除非您認可這些變更，否則這些變更不會影響已發佈的技能集。 認可變更將會覆寫生產技能。
如果擴充管線沒有任何錯誤，就可以使用偵錯工作階段，以累加方式擴充文件、測試及驗證每個變更，然後再認可變更。
偵錯工作階段透過分析資料、技能輸入和輸出以及欄位對應來協助識別錯誤或警告的根本原因。 如果索引子遇到設定問題，例如網路設定不正確、許可權相關存取錯誤或類似問題，請檢閱特定錯誤訊息以及提供的連結檔。 如需疑難排解指引，請參閱 常見的索引子錯誤和警告。
偵錯使用私人連線的工作階段
如果您的 AI 擴充管線使用共用私人連結來存取 Azure 資源，則需要額外的設定，以確保索引子和偵錯工作階段正常運作。 這包括權限、可信任存取和網路設定。
- 如果您使用受控識別，請將必要的角色指派給搜尋服務的身分識別，包括
Storage Blob Data Contributor，使得偵錯工作階段可以將工作階段資料寫入至您的儲存體帳戶。 - 請確定搜尋服務可以存取 技能組定義中參考的所有資源，包括偵錯工作階段中使用的任何資源。
- 在您的儲存體帳戶中， 啟用受信任的服務 ，以允許從 Azure AI 搜尋服務存取。
- 設定
"executionEnvironment" = "private"屬性來確保 索引器在私人內容中執行。 - 為搜尋服務存取的每個資源建立 共用私人連結 ，包括：您的資料來源 （如果設定為索引器 AI 擴充快取和知識存放區），以及技能組中設定的任何其他資源。
- 如需其他疑難排解指引，請參閱 常見的索引子錯誤和警告。
偵錯工作階段配置
視覺化編輯器會組織成顯示作業進度的介面區，首先是文件萃取，接著是技能、對應和索引。
選取任何技能或對應，即會開啟一個窗格，顯示相關資訊。
請遵循連結進一步鑽研技能處理。 例如，下列螢幕擷取畫面顯示文字分割技能第一次反覆運算的輸出。
技能詳細資料窗格
[技能詳細資料] 窗格有下列區段：
- 反覆運算：顯示技能的執行次數。 您可以檢查每一次的輸入和輸出。
- 技能設定：檢視或編輯 JSON 技能集定義。
- 錯誤和警告：顯示此技能特有的錯誤或警告。
擴充資料結構窗格
當您選取藍色的顯示或隱藏箭頭符號時，[擴充資料結構] 窗格會滑到側邊。 這是擴充文件所含內容的人類可讀表示法。 本文中先前的螢幕擷取畫面顯示擴充資料結構的範例。
後續步驟
現在已了解偵錯工作階段的各項元素，請在現有的技能集上啟動您的第一個偵錯工作階段。