在 Azure 入口網站中對 Azure AI 搜尋技能集進行偵錯

發行項
01/19/2024

啟動以入口網站為基礎的偵錯會話，以識別並解決錯誤、驗證變更，以及將變更推送至 Azure AI 搜尋服務中已發佈的技能集。

偵錯會話是快取的索引器和技能集執行，範圍設定為單一檔，您可以用來以互動方式編輯和測試變更。完成偵錯時，您可以將變更儲存至技能集。

如需偵錯會話運作方式的背景，請參閱在 Azure AI 搜尋中偵錯會話。若要使用範例文件練習偵錯工作流程，請參閱教學課程：偵錯會話。

必要條件

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

限制

偵錯會話適用於所有通用的索引器數據源和大部分預覽數據源。下列清單會指出例外狀況：

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

入口網站不支持客戶管理的密鑰加密（CMK），這表示入口網站體驗，例如偵錯會話無法有 CMK 加密連接字串或其他加密元數據。如果您的搜尋服務已針對 CMK 強制設定，偵錯會話將無法運作。

建立偵錯會話

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

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

偵錯會話會從在選取的檔上執行索引器和技能集開始。建立的文件內容和元數據將在會話中可見且可供使用。

使用 [取消] 按鈕執行偵錯會話時，可以取消偵錯會話。如果您按下 [ 取消] 按鈕，您應該能夠分析部分結果。

偵錯會話的執行時間應該比索引器更長，因為它經過額外的處理。

從錯誤和警告開始

入口網站中的索引器執行歷程記錄提供所有檔的完整錯誤和警告清單。在偵錯會話中，錯誤和警告會限製為一份檔。您將完成此清單、進行變更，然後返回清單以確認問題是否已解決。

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

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

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

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

檢視擴充節點的內容

AI 擴充管線會從源檔擷取或推斷資訊與結構，並在程式中建立擴充的檔。擴充檔會先在檔破解期間建立，並填入根節點（/document），再加上任何直接從數據源提升的內容節點，例如元數據和檔索引鍵。在技能執行期間，技能會建立更多節點，其中每個技能輸出都會將新的節點新增至擴充樹狀結構。

擴充的檔是內部檔，但偵錯會話可讓您存取技能執行期間所產生的內容。若要檢視每個技能的內容或輸出，請遵循下列步驟：

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

編輯技能定義

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

其他問題，例如無效的內容或輸入表達式，可能更難解決，因為錯誤會告訴您錯誤，但無法修正錯誤。如需內容和輸入語法的說明，請參閱 Azure AI 搜尋技能集中的參考擴充。如需個別訊息的說明，請參閱針對常見的索引器錯誤和警告進行疑難解答。

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

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

檢查欄位對應

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

從預設檢視開始： AI 擴充 > Skill Graph，圖形類型設定為 Dependency Graph。
選取 靠近頂端的 [字段對應 ]。您應該至少找到可唯一識別和關聯搜尋索引中每個搜尋檔的檔案索引鍵，以及數據源中的源文檔。

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

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

在本機偵錯自定義技能

因為程式代碼是在外部執行，所以偵錯會話無法用來偵錯，所以自定義技能可能會更具挑戰性。本節說明如何在本機偵錯自定義 Web API 技能、偵錯會話、Visual Studio Code 和 ngrok 或 Tunnelmole。這項技術適用於在 Azure Functions 中執行的自定義技能，或任何其他在本機執行的 Web 架構（例如 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 Code 中使用斷點來偵錯程式代碼或逐步執行。

下一步

既然您已了解偵錯會話可視化編輯器的配置和功能，請嘗試教學課程以取得實際操作體驗。

教學課程：探索偵錯會話

在 Azure 入口網站 中對 Azure AI 搜尋技能集進行偵錯