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

發行項
07/22/2024

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

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

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

必要條件

現有的擴充管線，包括：資料來源、技能集、索引子和索引。
搜尋服務中的 [參與者] 角色指派。
用來儲存工作階段狀態的 Azure 儲存體帳戶。
如果您使用系統受控識別，Azure 儲存體中的 [儲存體 Blob 資料參與者] 角色指派。否則，請規劃針對對 Azure 儲存體的偵錯工作階段連線使用完整存取連接字串。
如果 Azure 儲存體帳戶位於防火牆後方，請將其設定為 [允許搜尋服務存取]。

限制

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

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

入口網站不支援客戶自控金鑰 (CMK)，這表示入口網站體驗，例如偵錯工作階段不能有 CMK 加密的連接字串或其他加密元中繼資料。如果您的搜尋服務設定為 CMK 強制，偵錯工作階段將無法運作。

建立偵錯工作階段

登入 Azure 入口網站，然後尋找您的搜尋服務。
在左側功能表中，選取 [搜尋管理]>[偵錯工作階段]。
在頂端的動作列中，選取 [新增偵錯工作階段]。
在 [偵錯工作階段名稱] 中，提供一個名稱，以方便記住此偵錯工作階段是關於哪一個技能、索引子和資料來源。
在 [儲存體連線],中，尋找用於快取處理偵錯工作階段的一般用途儲存體帳戶。系統會提示您在 Blob 儲存體或 Azure Data Lake Storage Gen2 中選取並選擇性地建立 Blob 容器。您可以針對建立的所有後續偵錯工作階段重複使用相同的容器。明顯的容器名稱可能是「偵錯工作階段」。
在 [受控識別驗證] 中，如果 Azure 儲存體連接不使用受控識別，請選擇 [無]。否則，請選擇您授與 [儲存體 Blob 資料參與者] 許可權的受控識別。
在 [索引子範本] 中，選取用於驅動所要偵錯之技能的索引子。索引子和技能的複本均會用來初始化工作階段。
在 [要偵錯的文件] 中，選擇索引中的第一份文件，或選擇特定文件。如果您選取特定文件，視資料來源而定，系統會要求您提供 URI 或資料列識別碼。

如果您的特定文件是 Blob，請提供 Blob URI。您可以在入口網站的 Blob 屬性頁中找到 URI。
或者，在 [索引子設定] 中，指定用來建立工作階段的任何索引子執行設定。這些設定應該會模擬實際索引子所使用的設定。您在偵錯工作階段中指定的任何索引子選項，都不會影響索引子本身。
您的設定看起來應該與此螢幕擷取畫面類似。選取 [儲存工作階段] 以開始。

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

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

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

從錯誤和警告開始

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

若要檢視訊息，請在 [AI 擴充] > [技能圖表] 中選取技能，然後在詳細資料窗格中選取 [錯誤/警告]。

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

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

選取 [技能詳細資料] 窗格中的 [儲存] 以保留您的變更。
在工作階段視窗中選取 [執行]，即可使用已修改的定義叫用技能集執行。
返回 [錯誤/警告] 以查看計數是否減少。在您開啟索引標籤之前，清單不會重新整理。

檢視擴充節點的內容

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

已擴充文件屬於內部文件，但偵錯工作階段可讓您存取技能執行期間所產生的內容。若要檢視每個技能的內容或輸出，請遵循下列步驟：

從預設檢視開始：[AI 擴充] > [技能圖表]，圖表類型設定為 [相依性關係圖]。
選取技能。
在右側的詳細資料窗格中，選取 [執行]、選取 [輸出]，然後開啟 [運算式評估工具] (</>) 來檢視運算式及其結果。
或者，開啟 [AI 擴充]>[擴充資料結構] 以向下捲動節點清單。此清單包含潛在和實際節點，內含輸出的資料行，以及另一個資料行，可指出用來產生輸出的上游物件。

編輯技能定義

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

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

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

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

檢查欄位對應

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

從預設檢視開始：[AI 擴充] > [技能圖表]，圖表類型設定為 [相依性關係圖]。
選取靠近頂端的 [欄位對應]。您至少應找到可唯一識別，並將搜尋索引中每個搜尋文件與其資料來源中的來源文件建立關聯的文件金鑰。

如果您要直接從資料來源匯入原始內容並略過擴充，您應該會在 [欄位對應] 中找到這些欄位。
選取圖表底部的 [輸出欄位對應]。在這裡，您將找到搜尋索引中從技能輸出到目標欄位的對應。除非您使用匯入資料精靈，否則輸出欄位對應為手動定義，內容可能不完整或輸入錯誤。

確認 [輸出欄位對應] 中的欄位存在於指定的搜尋索引中，並檢查拼字和擴充節點路徑語法。

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

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

取得公用 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 入口網站中設定

在偵錯工作階段中，修改您的自訂 Web API 技能 URI 即可呼叫 Tunnelmole 或 ngrok 轉送 URL。使用 Azure Function 執行技能集程式碼時，請務必附加「/api/FunctionName」。

您可以在入口網站中編輯技能定義。

測試您的程式碼

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

下一步

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

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

共用方式為