教學課程：使用偵錯工作階段修正技能

在 Azure AI 搜尋服務中，技能會協調分析、轉換或建立可搜尋內容的技能動作。 通常，一個技能的輸出會變成另一個技能的輸入。 當輸入相依於輸出時，技能集定義和欄位關聯的錯誤可能會導致作業和資料遺失。

偵錯工作階段是 Azure 入口網站工具，可提供在 Azure AI 搜尋服務上執行之技能的整體視覺效果。 使用此工具，您可以向下切入至特定步驟，輕鬆查看動作可能失敗的位置。

在本文中，使用偵錯工作階段來尋找並修正遺漏的輸入和輸出。 本教學課程具有包容性。 它會提供範例資料、建立物件的 REST 檔案，以及技能中偵錯問題的指示。

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

必要條件

• Azure AI 搜尋服務。 在目前的訂閱下，建立服務 或 尋找現有的服務。 您可以使用本教學課程的免費服務。 免費層不提供 Azure AI 搜尋服務的受控識別支援。 您必須使用金鑰來連線到 Azure 儲存體。

• 具有 Blob 儲存體的 Azure 記憶體帳戶，用於裝載範例資料，以及用來保存偵錯工作階段期間建立的快取資料。 如果您使用免費的搜尋服務，則儲存體帳戶必須啟用共用存取金鑰，且必須允許公用網路存取。

• 具有 REST 用戶端 (英文) 的 Visual Studio Code (英文)

• 範例 PDF (臨床試驗)。

• 用來建立擴充管線的範例 debug-sessions.rest file 檔案。

注意

本教學課程也會使用 Azure AI 服務進行語言偵測、實體辨識和關鍵片語擷取。 由於工作負載很小，因此 Azure AI 服務會在幕後連線以進行免費處理，最多 20 筆交易。 這表示您可以完成此練習，而不必建立可計費的 Azure AI 服務資源。

設定範例資料

本節會在 Azure Blob 儲存體中建立範例資料集，讓索引子和技能集具有要使用的內容。

1. 下載範例資料 (clinical-trials-pdf-19)，其中包含 19 個檔案。

2. 建立 Azure 儲存體帳戶，或尋找現有帳戶。

   • 選擇與 Azure AI 搜尋服務相同的區域，以避免產生頻寬費用。

   • 選擇 StorageV2 (一般用途 V2) 帳戶類型。

3. 瀏覽至入口網站中的 Azure 記憶體服務頁面，並建立 Blob 容器。 最佳做法是指定「私人」存取層級。 將您的容器命名為 clinicaltrialdataset。

4. 在容器中選取 [上傳]，以上傳您在第一個步驟中下載並解壓縮的範例檔案。

5. 在入口網站中，複製 Azure 儲存體的連接字串。 您可以從入口網站中的 [設定]>[存取金鑰] 取得連接字串。

複製金鑰和 URL

本教學課程使用 API 金鑰進行驗證和授權。 您需要搜尋服務端點和 API 金鑰，您可以從 Azure 入口網站取得此金鑰。

1. 登入 Azure 入口網站，流覽至 [概觀] 頁面，然後複製 URL。 範例端點看起來會像是 https://mydemo.search.windows.net。

2. 在 [設定 > 金鑰] 下面，複製系統管理金鑰。 系統管理金鑰可用來新增、修改和刪除物件。 有兩個可交換的系統管理密鑰。 複製任一個。

   

有效的 API 金鑰能為每個要求在傳送要求之應用程式與處理要求的搜尋服務間建立信任。

建立資料來源、技能集、索引和索引子

在本節中，建立您可以在本教學課程中修正的「錯誤」工作流程。

1. 啟動 Visual Studio Code 並開啟 debug-sessions.rest 檔案。

2. 提供下列變數：搜尋服務 URL、搜尋服務管理員 API 金鑰、儲存體連接字串，以及儲存 PDF 的 Blob 容器名稱。

3. 接著傳送每個要求。 建立索引子需要幾分鐘的時間才能完成。

4. 關閉 檔案。

在入口網站中檢查結果

由於技能集執行期間出現的問題，範例程式碼故意建立了一個有錯誤的索引。 問題是索引遺漏資料。

1. 在 Azure 入口網站的搜尋服務 [概觀] 頁面上，選取 [索引] 索引標籤。

2. 選取 [臨床試驗]。

3. 在搜尋總管的 JSON 檢視中輸入此 JSON 查詢字串。 它會傳回特定文件的欄位 (由唯一的 metadata_storage_path 欄位識別)。

   "search": "*",
   "select": "metadata_storage_path, organizations, locations",
   "count": true
   

4. 執行查詢。 您應該會看到 organizations 和 locations 的空白值。

   這些欄位應該已透過技能集的實體辨識技能填入，用來偵測 Blob 內容中任何地方的組織與位置。 在下一個練習中，您將對技能集進行偵錯，以判斷發生的問題。

另一個調查錯誤和警告的方式是透過 Azure 入口網站。

1. 開啟 [索引子] 索引標籤，然後選取 [clinical-trials-idxr]。

   請注意，雖然索引子作業整體成功，但出現了警告。

2. 選取 [成功] 以檢視警告 (如果大部分發生錯誤，則詳細資料連結會是失敗)。 您會看到索引子發出之每個警告的完整清單。

   

啟動您的偵錯工作階段

1. 從搜尋服務左側瀏覽窗格的 [搜尋管理] 底下，選取 [偵錯工作階段]。

2. 選取 [+ 新增偵錯工作階段]。

3. 指定工作階段名稱。

4. 在索引子範本中，提供索引子名稱。 索引子具有資料來源、技能集和索引的參考。

5. 選取儲存體帳戶。

6. 儲存工作階段。

   

7. 偵錯工作階段會開啟至 [設定] 頁面。 您可以修改初始設定，並覆寫任何預設值。 偵錯工作階段僅適用於單一文件。 預設值是接受集合中的第一份文件作為偵錯工作階段的基礎。 您可以在 Azure 儲存體中提供其 URI，以選擇要偵錯的特定文件。

8. 當偵錯工作階段完成初始化時，您應該會看到具有對應和搜尋索引的技能工作流程。 擴充的文件資料結構會出現在側邊的詳細資料窗格中。 我們已將它從下列螢幕擷取畫面中排除，讓您可以看到更多工作流程。

   

尋找技能集的問題

索引子所回報的任何問題都會表示為錯誤和警告。

請注意，錯誤和警告的數目是比先前所顯示精簡得多的清單，因為此清單只會詳列單一文件的錯誤。 如同索引子所顯示的清單，您可以選取警告訊息，並查看此警告的詳細資料。

選取 [警告] 以檢閱通知。 您應該會看到四個：

• 「無法執行技能，因為一或多個技能輸入無效。 缺少必要的技能輸入。 名稱：'text'，來源：'/document/content'。」

• 「無法將輸出欄位 'locations' 對應至搜尋索引。 檢查索引子的「outputFieldMappings」屬性。 遺漏值 '/document/merged_content/locations'。」

• 「無法將輸出欄位 'organizations' 對應至搜尋索引。 檢查索引子的「outputFieldMappings」屬性。 遺漏值 '/document/merged_content/organizations'。」

• 「技能執行但可能有非預期的結果，因為一或多個技能輸入無效。 缺少選擇性的技能輸入。 名稱：'languageCode'，來源：'/document/languageCode'。 表達式語言剖析問題：遺漏值 '/document/languageCode'。」

許多技能都有「languageCode」參數。 透過檢查作業，您可以看到 EntityRecognitionSkill.#1 中缺少此語言程式碼輸入，這與「locations」和「organizations」輸出出現問題的實體辨識技能相同。

由於這四個通知都是關於此技能，您的下一個步驟是對此技能進行偵錯。 可能的話，請先解決輸入問題，再繼續進行輸出問題。

修正遺漏的技能輸入值

1. 在工作介面上，選取回報警告的技能。 在本教學課程中，它是實體辨識技能。

2. [技能詳細資料] 窗格隨即在右側開啟，其中包含反覆項目區段及其各自的輸入和輸出、技能 JSON 定義的技能設定，以及此技能所發出的任何錯誤和警告訊息。

   

3. 將滑鼠停留在每個輸入上 (或選取輸入)，以顯示運算式評估工具中的值。 請注意，此輸入的顯示結果看起來不像是文字輸入。 它看起來像是一系列新行字元 \n \n\n\n\n，而非文字。 缺少文字表示無法識別任何實體，因此此文件無法符合技能的必要條件，或有應該改用的另一個輸入。

   

4. 切換回 [擴充資料結構]，並檢閱此文件的擴充節點。 請注意，「content」的 \n \n\n\n\n 沒有原始來源，但「merged_content」的另一個值具有 OCR 輸出。 雖然沒有指示，但此 PDF 的內容似乎是 JPEG 檔案，如「merged_content」中擷取和處理過的文字所證明。

   

5. 切換回技能，然後選取 [技能設定] 以開啟 JSON 定義。

6. 將運算式從 /document/content 變更為 /document/merged_content，然後選取 [儲存]。 請注意，將不再列出警告。

   

7. 在工作階段的視窗功能表中，選取 [執行]。 如此即會使用文件再次執行技能。

8. 偵錯工作階段執行完成之後，請注意警告計數已減少一個。 警告顯示文字輸入的錯誤已消失，但其他警告仍然存在。 下一個步驟是解決遺漏或空白值 /document/languageCode 的相關警告。

   

9. 選取技能，並將滑鼠停留在 /document/languageCode 上。 此輸入的值是 null，這不是有效的輸入。

10. 如同上一個問題，請先檢閱 [擴充資料結構]，以取得其節點的辨識項。 請注意，沒有「languageCode」節點，但「language」有一個節點。 這表示技能設定中有錯字。

11. 複製運算式 /document/language。

12. 在 [技能詳細資料] 窗格中，選取 #1 技能的 [技能設定]，然後貼上新的值 /document/language。

13. 選取 [儲存]。

14. 選取執行。

15. 偵錯工作階段執行完成之後，您可以在 [技能詳細資料] 窗格中檢查結果。 當您將滑鼠停留在 /document/language 上方時，您應該會看到運算式評估工具中作為值的 en。

請注意，輸入警告已消失。 現在，組織和位置的輸出欄位僅剩下兩個警告。

修正遺漏的技能輸出值

訊息會指出要檢查索引子 'outputFieldMappings' 屬性，因此我們就從這裡開始。

1. 選取工作介面上的 [輸出欄位對應]。 請注意，輸出欄位對應遺失。

   

2. 在第一個步驟中，確認搜尋索引具有預期的欄位。 在此情況下，索引具有「locations」和「organizations」的欄位。

3. 如果索引沒有問題，下一個步驟是檢查技能輸出。 如前所述，選取 [擴充資料結構]，然後捲動節點以尋找「locations」和「organizations」。 請注意，父代是「content」，而不是「merged_content」。 內容錯誤。

4. 切換回實體辨識技能的 [技能詳細資料] 窗格。

5. 在 [技能設定] 中，將 context 變更為 document/merged_content。 此時，您應該對技能定義進行三項修改。

   

6. 選取 [儲存]。

7. 選取執行。

所有的錯誤都已解決。

認可技能集的變更

在起始偵錯工作階段時，搜尋服務建立了技能集的複本。 這樣是為了保護搜尋服務上的原始技能集。 現在您已完成技能集的偵錯，您可以認可該修正 (覆寫原始的技能集)。

或者，如果您尚未準備好認可變更，您可以儲存偵錯工作階段，並在稍後重新開啟。

1. 選取主要偵錯工作階段功能表中的 [認可變更]。

2. 按一下 [確定] 以確認您要更新技能集。

3. 關閉 [偵錯] 工作階段，然後從左側瀏覽窗格開啟 [索引子]。

4. 選取 [clinical-trials-idxr]。

5. 選取 [重設]。

6. 選取執行。

7. 選取 [重新整理] 以顯示重設和執行命令的狀態。

索引子執行完成時，應該會出現綠色的核取記號，且 [執行歷程記錄] 索引標籤中最近一次執行的時間戳記旁會出現「成功」一詞。若要確定變更已套用：

1. 在左側瀏覽窗格中，開啟 [索引]。

2. 選取 'clinical-trials' 索引，然後在 [搜尋總管] 索引標籤中，輸入此查詢字串：$select=metadata_storage_path, organizations, locations&$count=true 以傳回特定文件的欄位 (由唯一 metadata_storage_path 欄位識別)。

3. 選取搜尋。

在顯示的結果中，組織和位置現在應已填入預期的值。

清除資源

如果您是在自己的訂用帳戶中進行，建議您在專案結束時判斷自己是否仍需要先前所建立的資源。 資源若繼續執行，將需付費。 您可以個別刪除資源，或刪除資源群組以刪除整組資源。

您可以使用左導覽窗格中的 [所有資源] 或 [資源群組] 連結，在入口網站中尋找和管理資源。

免費服務僅限於三個索引、索引子和資料來源。 您可以在入口網站中刪除個別項目，以避免超出限制。

下一步

本教學課程觸及技能集定義和處理的各層面。 若要深入了解概念和工作流程，請參閱下列文章：

• 如何將技能集輸出欄位對應至搜尋索引中的欄位

• Azure AI 搜尋服務中的技能集

• 如何設定增量擴充的快取