Alibaba Cloud Model Studio：如何建立自訂外掛程式

步驟一：建立外掛程式

1. 在外掛程式頁面，單擊新增自訂外掛程式。

   

2. 填寫外掛程式資訊。

   

   參數	說明
   外掛程式名稱	建議您輸入具有語義的名稱，中英文不限。
   外掛程式描述	請輸入外掛程式描述，協助使用者更好地理解外掛程式功能和使用情境。
   外掛程式URL	外掛程式的訪問地址。同一個HTTP請求下，不同的路徑被拆分成了不同的API（即下方建立工具中的工具路徑）。同一外掛程式下的不同工具使用相同的網域名稱，每個工具的工具路徑對應一個獨立的API。 例如：xx外掛程式下包含兩個API： 查詢：https://xxx.com/query 刪除：https://xxx.com/delete 在這個樣本中，https://xxx.com對應外掛程式URL，/query和/delete對應下方建立工具中的工具路徑。這表明該外掛程式下包含兩個工具。
   Header列表	（可選）需要鑒權時，可以通過自訂Header傳遞鑒權資訊。
   是否鑒權	（可選）當阿里雲百鍊應用調用您的自訂外掛程式時是否需要鑒權。此處是否需要鑒權主要取決於API提供方的安全性原則。 ：無鑒權。 ：開啟鑒權。
   鑒權類型	鑒權包括服務級鑒權和使用者級鑒權兩種方式。 如果選擇服務級鑒權，那麼調用外掛程式時不需要傳入Token，統一使用配置外掛程式時填寫的Token。 如果選擇使用者級鑒權，那麼每次調用外掛程式時都需要傳入Token。 服務級鑒權 位置：支援將鑒權資訊放在Header或Query中。 Header：將鑒權資訊放在HTTP要求標頭的Authorization欄位中，這些資訊在URL中不可見。 Query：將鑒權資訊放在URL中，例如https://example.com?api_key=123456。 參數名：如果將鑒權資訊放在Query中需填寫鑒權時使用的參數，如“api_key”。如果將鑒權資訊放在Header中將預設此參數為“Authorization”。 Type： basic：不會在您提供的Token前加任何內容。 bearer：會在Token前增加“Bearer”。 appcode：會在Token前增加“APPCODE”。 兩種type都會放在鑒權參數欄位中。例如：選擇bearer，則調用外掛程式時會變成（“Authorization”： “Bearer <YOUR_TOKEN>”）。 Token：從API提供方擷取的鑒權Token，如API Key。 使用者級鑒權 位置：支援將鑒權資訊放在Header或Query中。 Header：將鑒權資訊放在HTTP要求標頭的Authorization欄位中，這些資訊在URL中不可見。 Query：將鑒權資訊放在URL中，例如https://example.com?api_key=123456。 參數名：如果將鑒權資訊放在Query中需填寫鑒權時使用的參數，如“api_key”。如果將鑒權資訊放在Header中將預設此參數為“Authorization”。 Type： basic：不會在您提供的Token前加任何內容。 bearer：會在Token前增加“Bearer”。 appcode：會在Token前增加“APPCODE”。 兩種type都會放在鑒權參數欄位中。例如：選擇bearer，則調用外掛程式時會變成（“Authorization”： “Bearer <YOUR_TOKEN>”）。 使用DashScope SDK或HTTP介面調用應用時，通過參數biz_params和user_defined_tokens將外掛程式中的使用者級鑒權資訊透傳給應用，其中user_token傳遞的值為該外掛程式需要的鑒權資訊。具體請參見通過API傳遞外掛程式參數。

3. 填寫完成後單擊確認建立外掛程式 > 建立工具或單擊繼續添加工具。

步驟二：建立工具

1. 填寫工具資訊、配置輸入/輸出參數以及進階配置。

   

   參數	說明
   工具名稱	建議您輸入具有語義的名稱，中英文不限。 工具名稱能夠協助大模型判斷當前任務是否需要調用該工具。
   工具描述	工具描述能協助大模型更好的理解工具功能和使用情境。請使用自然語言進行描述，盡量給出使用樣本。例如：“此工具用於擷取指定時間和指定地點的天氣和溫度。例如‘查詢杭州明天的天氣和溫度’”。 工具描述能夠協助大模型判斷當前任務是否需要調用該工具。
   工具路徑	指向外掛程式URL的相對路徑。欄位名必須以正斜杠（/）開頭。此路徑將拼接到外掛程式URL上，以構建完整的URL。
   要求方法	您可以根據需求選擇使用GET或POST等HTTP方法來操作API介面。
   提交方式	請求或響應的編碼類別型。 application/json：表示請求或響應的主體內容是以JSON格式編碼的資料。 application/x-www-form-urlencoded：用於在 HTTP 要求中編碼錶單資料。這種編碼方式主要用於 POST 請求，將表單資料編碼為索引值對，並通過 URL 編碼傳輸。多個索引值對之間用 & 分隔，每個鍵和值之間用 = 分隔。URL 編碼會將特殊字元轉換為 % 後跟兩位十六進位數的形式。例如，空格會被編碼為 %20，& 會被編碼為 %26，= 會被編碼為 %3D，表單資料 name=John Doe&age=25 會被編碼為 name=John%20Doe&age=25。
   配置輸入參數	單擊增加入參，配置參數資訊，所有參數均為必填項。 參數名稱儘可能帶有含義，可以協助大模型理解當前需要識別的參數資訊是什麼。例如city這種有含義的詞。 參數描述是對該入參的功能描述，要簡練且準確，協助大模型進一步理解取參的方式。例如，date，描述為日期的同時，可以再進一步描述date的形式，比如yyyy-MM-dd。 類型指參數類型。如需在Object類型下新增參數，請單擊Object行末的表徵圖進行新增。 傳參方式要設定準確。 大模型識別：表示該參數的值需要大模型從使用者輸入中提取。 業務透傳：表示該參數的值從外部主動透傳，傳遞過程中不對資料進行處理或修改。使用DashScope SDK或HTTP介面調用應用時，通過參數 biz_params和user_defined_params將外掛程式中的業務透傳參數資訊透傳給應用。具體請參見通過API傳遞外掛程式參數。
   配置輸出參數	單擊增加出參，配置參數資訊，所有參數均為必填項。 大模型會根據出參的定義，再結合使用者的問題，對API返回的結果進行篩選、重新組合，作為最終的答案返回給使用者。因此，出參與入參一樣，需要儘可能精簡和準確描述，嵌套的層級也儘可能少。
   進階配置	（可選）為大模型增加調用樣本，減少漏召回和誤召回的情況。通常用於入參比較複雜，模型構造容易出錯的情境，通過提供一些範例，提升大模型調用外掛程式的準確性。 Value表示使用者輸入當前的Query時，期望大模型構造出的調用入參。

2. 配置完成後單擊儲存草稿。

3. 線上調試工具API能否調通。

   單擊測試載入器，輸入鑒權資訊（開啟鑒權時填寫）及入參的值，單擊開始運行。

   如果運行失敗，請根據運行結果中的報錯資訊對配置進行調整，並重新進行測試，直至成功運行。

   

   入參的值可以手動輸入，也可以通過代碼輸入。對於入參較為複雜的情況，建議採用代碼模式編輯。您可以在代碼編輯器中提交完整的JSON格式的入參及其相應的值。

   

4. 測試通過後單擊發布。只有發行的工具才能在應用中被調用。

步驟三：調用外掛程式

發布工具時的報錯資訊