從步驟呼叫延伸

如果要從動作呼叫自訂延伸，請執行下列動作:

1. 在動作編輯器中，建立或開啟您要從中呼叫延伸的步驟。

2. 選用: 在 助理說明 欄位中，輸入在呼叫延伸之前要向客戶顯示的訊息 (例如，Please wait while I retrieve your account balance...)。

   此步驟的輸出會傳送至通道，並將廣域環境定義變數 skip_user_input 設為 true。 此變數會告知通道顯示訊息，但 不 提示客戶提供回覆。 相反地，通道會傳送空訊息，讓助理能夠繼續呼叫延伸。

   所有內建通道整合 (例如 Web 會談) 都遵循 skip_user_input 環境定義變數。 如果您使用 API 來開發自訂用戶端，您必須負責包含此變數的邏輯檢查。 如需相關資訊，請參閱 處理使用者輸入。

3. 在步驟編輯器中，按一下 ，然後按一下。

4. 按一下 使用延伸。

5. 在「延伸設定」視窗中，指定下列資訊:

   • 在 延伸 欄位中，選取您要呼叫的延伸。

   • 在 作業 欄位中，選取您要執行的作業。 ( 作業 是延伸支援的方法或函數。)

6. 指定每一個必要輸入參數的值。 參數 是傳送至作業的輸入值，例如您要擷取的客戶記錄 ID 或用於天氣預報的位置。

   若要將值指派給參數，請按一下該值的輸入欄位。 然後您可以從可用的變數清單中選取，或撰寫表示式來指定值。

   

   每一個參數都有一個資料類型 (例如 number 或 string)。 您選取的變數必須與參數的資料類型相容; 如需相關資訊，請參閱 參數的相容變數。

   您必須先指定所有必要參數的值，才能繼續進行。

7. 如果您要指定任何選用參數的值，請按一下 選用參數。 然後，您可以針對您要使用的每一個選用參數重複此處理程序。

8. 按一下套用。 (如果 套用 按鈕無法使用，請檢查以確定您已指定所有必要參數的值。)

步驟編輯器的 然後 區段現在會顯示對延伸的呼叫概觀:

如果您需要進行變更，請按一下 編輯延伸，以重新開啟「延伸設定」視窗。

存取延伸回應資料

在呼叫延伸之後，回應資料中的值會儲存在特殊動作變數中，您可以在後續步驟中存取這些變數。

您可以使用存取其他動作變數的相同方式來存取這些變數。 您可以在 助理說出 文字中參照它，將它評估為步驟條件的一部分，或將它指派給階段作業變數，以便其他動作可以存取它。 回應變數會顯示在可用變數清單中，並在延伸名稱及從中呼叫它的步驟下分類:

每次對延伸的呼叫都會建立一組個別的回應變數。 如果您的動作從不同的步驟多次呼叫相同的延伸，請確定您從正確的步驟中選取變數。

每個變數都代表回應內文中的值。 為了方便存取這些值，會從複式巢狀物件擷取資料，並對映至個別回應變數。 每個變數的名稱反映其在回應內文中的位置 (例如，body.name 或 body.customer.address.zipcode)。

例如，此動作步驟使用表示式來檢查延伸回應中的 availability 內容:

如果回應變數包含陣列，您可以撰寫表示式，以使用陣列方法來存取陣列的元素。 例如，您可以在步驟條件中使用 contains() 方法來測試陣列是否包含特定值，或使用 join() 方法將陣列中的資料格式化為您可以包含在助理回應中的字串。 如需陣列方法的相關資訊，請參閱 陣列方法。

檢查成功或失敗

您可能希望助理能夠處理呼叫自訂延伸時發生的錯誤。 您可以透過檢查 Ran successfully 回應變數來執行此動作，該回應變數與來自延伸呼叫的回應一起傳回。 此變數是布林值 (true 或 false)。

如果您定義步驟條件來檢查 Ran successfully 變數，則可以建立步驟，讓助理根據對延伸的呼叫是否成功，以不同的方式回應。 (如需步驟條件的相關資訊，請參閱 步驟條件。)

下列範例顯示的步驟條件會檢查步驟 3 中延伸的失敗。 透過使用此條件，您可以建立一個步驟來告知客戶發生錯誤，並可能提供連接至代理程式以取得更多協助。

HTTP 狀態的條件

除了 Ran successfully 變數之外，您也可能想要根據回應的 HTTP 狀態建立步驟條件。 透過這樣做，您可以建立步驟，根據失敗原因以不同方式處理狀況。 例如，如果由於超時錯誤 HTTP 狀態 408) 導致呼叫失敗，您可能想要重試呼叫。

有許多可能的 HTTP 狀態代碼，不同的方法使用不同的狀態代碼來表示各種類型的成功或失敗。 要對 HTTP 狀態設定條件，您需要知道外部服務在何種情況下會傳回哪些 HTTP 狀態代碼。 這些狀態代碼通常會在描述外部 API 的 OpenAPI 文件中指定。

若要根據 HTTP 狀態代碼建立步驟條件，請遵循下列步驟：

1. 針對您要測試的值，按一下 表示式。

2. 在表示式欄位中，輸入錢幣符號 ($) 以顯示可用變數的清單。

3. 從延伸中選取任何作為回應值的變數。 (無論您選取哪個變數，只要它是延伸回應變數)。

   表示式會自動更新，以顯示所選取變數的參照，格式為 ${step_xxx_result_y.body.variablename}。 例如，如果您選取稱為 body.id 的回應變數，則參照可能是 ${step_596_result_1.body.id}。

4. 在大括弧內 ({})，編輯此參照以移除 .body.variablename。 您應該留下類似 ${step_596_result_1} 的內容。

5. 在右大括弧 (}) 之後，新增 .status。 產生的參照會識別從對延伸的呼叫所傳回的狀態碼 (例如，${step_596_result_1}.status)。

   如需撰寫表示式的相關資訊，請參閱 撰寫表示式。

6. 透過新增運算子及比較值來完成表示式，以便表示式評估為布林值 (true/false)。 例如，以下表達式會測試 HTTP 狀態 408，這表示超時錯誤：

   ${step_549_result_1}.status==408
   

自訂擴展的調試失敗

如果對擴充功能的呼叫失敗，您可能需要透過查看有關發送到系統 API 和從系統 API 返回的內容的詳細資訊來偵錯問題。 為此，您可以使用預覽窗格中的檢查器：

1. 前往「操作」頁面或操作編輯器，然後按一下「預覽」 開啟「預覽」窗格。

   您無法從預覽頁面上的助理預覽存取檢閱器，該頁面只顯示客戶會看到的內容。 請改用「動作」頁面中的預覽特性，它可讓您存取其他資訊。

2. 像客戶一樣與您的助理互動。

3. 每次呼叫延伸時，預覽窗格都會顯示一則訊息，讓您存取詳細資訊:

   按一下 檢查，以查看延伸呼叫的詳細資料。

   您也可以點擊 圖示來顯示或隱藏檢查器。 但是，您必須按一下預覽窗格中的 「檢查」 才能顯示有關對分機的特定通話的資訊。

   檢查器的概述標籤顯示有關分機呼叫的以下資訊：

   除錯選項	說明
   延伸	延伸的名稱，如延伸設定中所指定。
   作業	所呼叫的作業。
   狀態	回應中的 HTTP 狀態碼。 此代碼可協助您判斷是否從外部服務傳回錯誤。
   要求參數	作為請求的一部分傳送到系統 API 的輸入參數。
   回應內容	系統 API 的回應中所包含的所有屬性的值。 這些是在呼叫延伸完成之後對映至動作變數的值。

   在 要求參數 和 回應內容 表格中，可能會截斷長內容名稱，只顯示 JSON 路徑的最後一部分。 若要查看完整路徑及內容名稱，請將滑鼠指標移至表格中內容名稱的上方。

4. 如果您想要查看原始要求及回應資料，請按一下延伸檢查程式中的 進階 標籤:

   • 要求會顯示為 cURL 指令，您可以在命令提示字元執行或匯入至 Postman之類的工具。 (基於安全理由，不包含任何 Authorization 標頭的內容。)
   • 回應顯示為從系統 API 傳回的完整 JSON 資料。

調試對話式搜尋或基於技能的操作的失敗

如果對話式搜尋或基於技能的操作的呼叫失敗，您可能需要透過查看有關發送到系統 API 和從系統 API 返回的內容的詳細資訊來偵錯問題。

只有在搜尋整合中啟用會話搜尋時，會話搜尋檢查器才會顯示。 如果您使用自訂服務搜尋集成，則在配置搜尋集成時必須僅使用伺服器端搜尋。 會話式搜尋檢查器不支援客戶端搜尋。

要查看分析問題的詳細信息，請使用預覽窗格中的檢查器：

1. 前往「操作」頁面，或在操作編輯器中按一下 「預覽」 以開啟「預覽」窗格。

   您無法從預覽頁面上的助理預覽存取檢閱器。 請改用「動作」頁面中的預覽特性，它可讓您存取其他資訊。

2. 像客戶一樣與您的助理互動。

3. 每次呼叫分機時，預覽窗格都會顯示一則訊息以存取詳細資訊： 您也可以按一下 圖示，以顯示或隱藏延伸檢查程式。 按一下預覽窗格中的 「檢查」 可顯示搜尋整合的特定呼叫的資訊。

4. 使用「總覽」標籤尋找通話查詢失敗的原因。

   在了解 「概述」標籤中顯示的欄位之前，請先了解搜尋擴充功能的兩個階段。

   • 檢索階段

     表示初始搜尋階段，其中呼叫外部文件搜尋引擎來檢索初始結果集。

   • 答案生成階段

     表示在檢索階段檢索資料並傳送至 LLM 以為使用者產生人類可讀答案的階段。

   檢查器的概述標籤顯示有關搜尋整合呼叫的以下資訊。

   除錯選項	說明
   延伸	延伸的名稱，如延伸設定中所指定。
   索引	搜尋使用的Elasticsearch索引的名稱，僅當搜尋擴充配置為使用Elasticsearch時才可見。
   專案 ID	IBM Watson® Discovery在搜尋檢索階段所使用的項目 ID。 只有當您將搜尋擴充功能配置為使用IBM Watson® Discovery時，此欄位才可見。
   查詢	系統用於在文件引擎（ Elasticsearch、IBM Watson® Discovery或自訂服務伺服器端）上啟動搜尋的查詢。 此欄位的值反映了系統重寫的查詢。
   原始查詢	用戶發起搜尋的查詢。 僅當啟用多輪會話搜尋時系統重寫查詢時，此欄位才可見。
   自訂結果過濾器	顯示觸發會話搜尋的自訂結果篩選條件 (如果搜尋觸發器上有提供)。 該欄位可能不會始終出現在回應中。
   法學碩士類型	在答案生成階段所調用的法學碩士。 此值為 watsonx.ai。 若要瞭解有關在 Assistant 中設定 LLM 的更多資訊，請參閱基本 LLM。
   型號	基礎法學碩士在搜尋的答案生成階段所使用的模型。
   流關閉原因	給出流結束或關閉的原因以及 UI 中的對應值。 只有當您在網路聊天中啟用串流時，此欄位才可見。
   LLM 輸入令牌計數	給出在搜尋的答案產生階段發送到 LLM 的請求中的令牌數量。
   LLM 產生的令牌數量	給出 LLM 在搜尋的答案產生階段回應的答案中的標記數量。
   IDK 回复	只有當搜尋答案解析為 IDK（我不知道）回應時，此欄位才可見。
   我不知道原因	系統將搜尋答案解析為 IDK（我不知道）回應的原因會顯示相應的值。
   IDK 觸發開頭短語	該欄位顯示偵測到的觸發 IDK（我不知道）回應的標準開頭短語，僅當 IDK 原因是由該短語引起時才可見。
   IDK 觸發短語	該欄位顯示偵測到的導致 IDK（我不知道）回應的觸發短語，僅當 IDK 原因是由該短語引起時才可見。
   返回總時間	系統完成對話式搜尋執行所花費的總時間。
   搜尋時間	在搜尋的檢索階段，系統會呼叫搜尋引擎並檢索結果所花費的時間。
   答案生成時間	系統完成搜尋的答案產生階段所花費的時間。
   置信閾值	代表搜尋信心臨界值的數值，在 Assistant 設定中也稱為「我不知道」的傾向。
   萃取性	分數反映了有多少回應是直接引用來源的。 較高的分數表示更直接的引用，較低的分數表示對來源的改寫或缺乏來源支持。
   檢索信賴度	置信度值表示系統對搜尋結果的確定程度。 如果低於臨界值，系統會回應 IDK，理由是 Retrieval confidence too low。
   響應置信度	置信度值表示系統對於產生的答案的確定性。 如果低於閾值，系統會以 IDK 和原因 Response confidence too low 進行回應。

重新配置遺漏的延伸

如果有人將延伸從 整合 頁面上的助理中移除，或者匯出動作然後匯入至未配置必要延伸的不同助理，則延伸可能變成無法使用。 如果發生這種情況，任何呼叫延伸的動作步驟都會變成無效。

若要修正問題，請遵循下列步驟：

1. 必要的話，請使用先前使用的相同 OpenAPI 規格來重建延伸。 (如需相關資訊，請參閱 建置自訂延伸。)

2. 請確定延伸已新增至助理。 (如需相關資訊，請參閱 將延伸新增至助理。)

3. 在動作編輯器中，編輯呼叫延伸的動作步驟，並檢查延伸的呼叫是否正確配置。 如果 watsonx Assistant 辨識所需的延伸，則會自動還原延伸配置。

   如果您看到訊息 Extension not fully configured，表示 watsonx Assistant 找不到必要的副檔名。 按一下 編輯延伸。

4. 在「延伸設定」視窗中，選取您要呼叫的延伸。

   如果 watsonx Assistant 辨識使用相同 OpenAPI 文件建置的可用延伸，則會出現一則訊息建議您選取此延伸。 不過，您可以選取任何可用的延伸。

5. 驗證已在 作業 和 參數 欄位中指定正確的值。

6. 按一下套用。

7. 如果您選取的延伸與用來建置動作的延伸不同，則可能需要修改存取延伸回應內容的後續步驟。 請檢查任何參照回應內容的後續步驟，並確定參照仍然有效且正確。