在 Azure 入口網站中偵錯 Azure AI 搜尋的技能

發行項
10/16/2024

啟動入口網站型的偵錯工作階段，以便識別並解決錯誤、驗證變更，並將變更推送至 Azure AI 搜尋服務中現有的技能。

偵錯工作階段屬於快取的索引子和技能執行，範圍設定為單一文件，您可以透過互動方式將其用於編輯和測試技能變更。完成偵錯時，您還能將變更儲存至技能。

如需偵錯工作階段運作方式的背景，請參閱在 Azure AI 搜尋中進行偵錯工作階段。若要使用樣本文件練習偵錯工作流程，請參閱教學課程：偵錯工作階段。

必要條件

一項 Azure AI 搜尋服務。建議您使用系統指派的受控識別和角色指派，讓 Azure AI 搜尋服務能夠寫入 Azure 儲存體，並呼叫技能集中使用的 Azure AI 資源。
用來儲存工作階段狀態的 Azure 儲存體帳戶。
現有的擴充管線，包括：資料來源、技能集、索引子和索引。
針對角色指派，搜尋服務身分識別必須具有:
- 技能集所使用的 Azure AI 多服務帳戶上認知服務使用者權限。
- Azure 儲存體上儲存體 Blob 資料參與者權限。否則，請規劃針對對 Azure 儲存體的偵錯工作階段連線使用完整存取連接字串。
如果 Azure 儲存體帳戶位於防火牆後方，請將其設定為 [允許搜尋服務存取]。

限制

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

SharePoint Online 索引子。
Azure Cosmos DB for MongoDB 索引子。
針對 Azure Cosmos DB for NoSQL，如果資料列在索引期間失敗，而且沒有對應的中繼資料，偵錯工作階段可能無法挑選正確的資料列。
針對 Azure Cosmos DB 的 SQL API，如果分割的集合先前未分割，偵錯工作階段就無法找到文件。
針對自訂技能，對 Azure 儲存體的偵錯工作階段連線不支援使用者指派的受控識別。如必要條件所述，您可以使用系統受控識別，或指定包含金鑰的完整存取連接字串。如需詳細資訊，請參閱使用受控識別將搜尋服務連線至其他 Azure 資源。
目前，無法選取要偵錯的檔。這項限制不是永久的，很快就會解除。此時，偵錯會話會選取源數據容器或資料夾中的第一份檔。

建立偵錯工作階段

登入 Azure 入口網站，然後尋找您的搜尋服務。
在左側功能表中，選取 [搜尋管理]>[偵錯工作階段]。
在頂端的動作列中，選取 [新增偵錯工作階段]。
在 [偵錯工作階段名稱] 中，提供一個名稱，以方便記住此偵錯工作階段是關於哪一個技能、索引子和資料來源。
在 [索引子範本] 中，選取用於驅動所要偵錯之技能的索引子。索引子和技能的複本均會用來初始化工作階段。
在儲存體帳戶中，尋找用於快取偵錯工作階段的一般用途的儲存體帳戶。
如果您先前將儲存體 Blob 資料參與者權限指派給搜尋服務系統受控識別，請選取 [使用受控識別驗證]。
選取 [儲存]。
- Azure AI 搜尋服務會在名為 ms-az-cognitive-search-debugsession 的 Azure 儲存體上建立 blob 容器。
- 在該容器內，它會使用您為工作階段名稱提供的名稱來建立資料夾。
- 這會啟動您的偵錯工作階段。
偵錯工作階段會開啟至 [設定] 頁面。您可以修改初始設定，並覆寫任何預設值。
在儲存體連接字串中，您可以指定連接字串或變更儲存體帳戶。
或者，在 [索引子設定] 中，指定用來建立工作階段的任何索引子執行設定。這些設定應該會模擬實際索引子所使用的設定。您在偵錯工作階段中指定的任何索引子選項，都不會影響索引子本身。
如果您進行變更，請選取 [儲存工作階段]，然後選取 [執行]。

偵錯工作階段一開始會在選取的文件上執行索引子和技能集。可以在工作階段中看到並使用文件的內容和中繼資料。

使用 [取消] 按鈕即可在執行偵錯工作階段時將其取消。如果您按下 [取消] 按鈕，應該就能分析部分結果。

偵錯工作階段的執行時間應該比索引子長，因為它會經過額外的處理。

從錯誤和警告開始

入口網站中的索引子執行記錄會提供所有文件的完整錯誤和警告清單。在偵錯工作階段中，錯誤和警告會限制在一份文件內。您可完成這份清單、進行變更，然後返回清單以確認問題是否已解決。

請記住，偵錯工作階段是以整個索引中的一份文件基礎。如果輸入或輸出看起來錯誤，可能是該文件特有的問題。您可以選擇不同的文件，以確認錯誤和警告是普遍的，還是單一文件特有的。

針對問題清單，選取 [錯誤] 或 [警告]。

最佳做法是先解決輸入的問題，再繼續輸出。

若要證明修改是否可解決錯誤，請遵循下列步驟：

選取 [技能詳細資料] 窗格中的 [儲存] 以保留您的變更。
在工作階段視窗中選取 [執行]，即可使用已修改的定義叫用技能集執行。
返回 [錯誤] 或 [警告] 以查看計數是否減少。

檢視擴充或產生的內容

AI 擴充管線會從來源文件擷取或推斷資訊與結構，並在流程中建立已擴充的文件。系統會先在文件萃取期間建立已擴充文件，並填入根節點 (/document)，以及直接從資料來源提取之任何內容的節點，例如中繼資料和文件金鑰。在技能執行期間，技能會建立更多節點，每次技能輸出都會將新節點新增至擴充樹狀結構。

技能集所建立或使用的所有內容都會出現在運算式評估工具中。您可以將滑鼠停留在連結上方，以檢視擴充文件樹狀結構中每個輸入或輸出的值。若要檢視每個技能的輸入或輸出，請遵循下列步驟:

在偵錯工作階段中，展開藍色箭號以檢視上下文相關的詳細資料。根據預設，詳細資料是擴充文件資料結構。不過，如果您選取技能或對應，則詳細資料會與該物件有關。
選取技能。
請遵循連結進一步鑽研技能處理。例如，下列螢幕擷取畫面顯示文字分割技能第一次反覆運算的輸出。

檢查索引對應

如果技能會產生輸出，但搜尋索引是空的，請檢查欄位對應。欄位對應會指定內容移出管線及移入搜尋索引的方式。

選取其中一個對應選項，並展開詳細資料檢視以檢閱來源和目標定義。

投影對應可在提供整合向量化的技能集中找到，例如匯入和向量化資料精靈所建立的技能。這些對應會決定父子系 (區塊) 欄位對應，以及是否只針對區塊化內容建立次要索引
輸出欄位對應 可在索引子中找到，並在技能集叫用內建或自訂技能時使用。這些對應可用來將擴充樹狀目錄中節點的資料路徑設定為搜尋索引中的欄位。如需路徑的詳細資訊，請參閱擴充節點路徑語法。
可在索引子定義中找到欄位對應，而且它們會從資料來源中的原始內容和索引子中的欄位建立資料路徑。您也可以使用欄位對應來新增編碼及解碼步驟。

此範例會顯示投影對應的詳細資料。您可以編輯 JSON 以修正任何對應問題。

編輯技能定義

如果欄位對應正確，請檢查個別技能的設定和內容。如果技能無法產生輸出，代表它可能遺漏屬性或參數，您可以透過錯誤和驗證訊息來判斷。

不正確內容或輸入運算式等其他問題可能較難解決，因為錯誤訊息只會告訴您出錯的地方，而不是如何修正。如需內容和輸入語法的說明，請參閱 Azure AI 搜尋技能中的參考擴充。如需個別訊息的說明，請參閱針對常見的索引子錯誤和警告進行疑難排解。

下列步驟說明如何取得技能的相關資訊。

選取工作介面上的技能。 [技能詳細資料] 窗格會在右側開啟。
使用 [技能設定] 編輯技能定義。您可以直接編輯 JSON。
檢查擴充樹狀結構中的 [參考節點的路徑語法]。以下是一些最常見的輸入路徑：
- /document/content 表示文字區塊。此節點會從 Blob 的內容屬性填入。
- /document/merged_content 表示包含 [文字合併] 技能之技能集中的文字區塊。
- /document/normalized_images/* 表示透過影像辨識或推斷的文字。

在本機對自訂技能進行偵錯

對自訂技能進行偵錯可能更具挑戰性，由於程式碼是在外部執行，因此無法用偵錯工作階段進行偵錯。本節說明如何在本機對自訂 Web API 技能、偵錯工作階段、Visual Studio Code 和 ngrok 或 Tunnelmole 進行偵錯。這項技術適用於在 Azure Functions 中執行的自訂技能，或其他在本機執行的 Web Framework (如 FastAPI)。

取得公用 URL

本章節會說明兩種方法來取得自訂技能的公用 URL。

使用 Tunnelmole

Tunnelmole 是開放原始碼通道工具，可建立公用 URL，透過通道將要求轉送至本機電腦。

安裝 Tunnelmole：
- npm：npm install -g tunnelmole
- Linux：curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
- Mac：curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
- Windows：使用 npm 進行安裝。或者，如果您沒有安裝 NodeJS，請下載適用於 Windows 先行編譯的 .exe 檔案，並將其放在您的 PATH 中。
執行此命令以建立新通道：
```
tmole 7071
```
您應該會看到如下所示的回應：
```
http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
```
在上述範例中，https://m5hdpb-ip-49-183-170-144.tunnelmole.net 轉送至本機電腦上的 7071 連接埠，這是公開 Azure 函式的預設連接埠。

使用 ngrok

ngrok 是一款常見、封閉來源的跨平台應用程式，可建立通道或轉送 URL，方便網際網路要求觸達本機電腦。使用 ngrok 將搜尋服務中擴充管線的要求轉送至您的機器，以允許本機偵錯。

安裝 ngrok。
開啟終端並透過 ngrok 可執行檔移至資料夾。
使用下列命令執行 ngrok 來建立新通道：
```
ngrok http 7071 
```
注意

根據預設，Azure 函式會在 7071 上公開。其他工具和設定可能會要求您提供不同的連接埠。
ngrok 啟動時，請複製並儲存下個步驟的公用轉送 URL。轉送 URL 會隨機產生。

在 Azure 入口網站中設定

一旦您有自訂技能的公用 URL，修改您的自訂 Web API 技能 URI 即可呼叫 Tunnelmole 或 ngrok 轉送 URL。使用 Azure Function 執行技能集程式碼時，請務必附加「/api/FunctionName」。

您可以在 [技能詳細資料] 窗格的 [技能設定] 區段中編輯技能定義。

測試您的程式碼

此時，偵錯工作階段的新要求現在應該會傳送至本機 Azure 函式。您可以在 Visual Studio 程式碼中使用中斷點來對程式碼進行偵錯或逐步執行。

下一步

既然您已了解偵錯工作階段視覺效果編輯器的配置和功能，請試著觀看教學課程以親手實作。

教學課程：探索偵錯工作階段

共用方式為