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

如果百鍊提供的官方外掛程式不能滿足業務需求，比如您想要在大模型應用中調用個人化開發的外掛程式或第三方平台的API，可以在百鍊建立自訂外掛程式來整合需要使用的API。

操作步驟

步驟一：進入外掛程式建立頁面

方式一：登入阿里雲百鍊大模型服務平台，在應用組件中選擇外掛程式管理，單擊建立自訂外掛程式。
方式二：如果您已經擁有了一個百鍊大模型應用，您可以進入應用管理介面，單擊選擇外掛程式，在自訂外掛程式欄處，單擊建立自訂外掛程式。

步驟二：填寫外掛程式資訊

參數	說明
外掛程式名稱	建議您輸入具有語義的名稱，中英文不限。外掛程式名稱能夠協助大模型判斷當前任務是否需要調用該外掛程式。
外掛程式ID	建議您輸入具有語義的英文名稱，例如：search、weather等。在您單擊建立完成後，百鍊將為您產生全域唯一的外掛程式ID。您可以在Assistant API中使用該外掛程式ID調用您的自訂外掛程式。
外掛程式描述	請使用自然語言描述外掛程式的功能，盡量給出使用樣本。例如：“此外掛程式用於擷取指定時間和指定地點的天氣和溫度。例如‘查詢杭州明天的天氣和溫度’”。外掛程式描述能夠協助大模型判斷當前任務是否需要調用該外掛程式。
是否鑒權	（可選）當百鍊應用調用您的自訂外掛程式時是否需要鑒權，支援無鑒權、服務級鑒權和使用者級鑒權三種方式。此處是否需要鑒權主要取決於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”。兩種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”。兩種type都會放在鑒權參數欄位中。例如：選擇bearer，則調用外掛程式時會變成（“Authorization”： “Bearer <YOUR_TOKEN>”）。使用者級鑒權需要在應用管理介面配置Token，具體操作請參見使用者級鑒權。

步驟三：填寫介面資訊

在代碼框中定義您的API介面資訊，請使用符合OpenAPI v3規範的格式。OpenAPI 規範（原名 Swagger 規範）是定義 RESTful 介面的全球標準，關於OpenAPI v3的詳細欄位，請參見OpenAPI v3.0.3。以下是一個樣本：

openapi: 3.0.1
info:
    title: 寢室公約查詢工具
    description: 寢室公約查詢工具，可以根據序號查詢特定條目。
    version: "v2"
servers:
    - url: https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run
paths:
    /article:
        post:
            operationId: get_article
            summary: 查詢寢室公約第幾條，用整數數字
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [article_index]
                            properties:
                                article_index:
                                    type: integer
                                    description: 寢室公約第幾條，用整數數字
            responses:
                "200":
                    description: 查詢成功
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [article]
                                properties:
                                    article:
                                        type: string
                                        description: 寢室公約條款

上述範例程式碼中各項內容的描述如下。

程式碼片段	描述
`openapi: 3.0.1`	openapi對象該對象指定使用的openapi版本。
`info: title: 寢室公約查詢工具 description: 寢室公約查詢工具，可以根據序號查詢特定條目。 version: "v2"`	info對象該對象提供了關於API的中繼資料，用戶端可以根據需要使用這些中繼資料。 `title`：外掛程式標題。 `description`：外掛程式描述。 `version`：OpenAPI介面協議版本號碼。
`servers: - url: https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run`	servers對象該對象指定服務端路徑。 `url`：訪問服務端的基礎路徑。
`paths: /article: post:`	paths對象 `paths`：一個指向單個endpoint的相對路徑。欄位名必須以正斜杠（/）開頭。此路徑將附加到servers對象中的URL上，以構建完整的URL。 `/article`中包含一個POST操作介面。您可以根據需求選擇使用GET、POST或DELETE等HTTP方法來操作API介面。
`operationId: get_article summary: 查詢寢室公約第幾條，用整數數字 requestBody: required: true content: application/json: schema: type: object required: [article_index] properties: article_index: type: integer description: 寢室公約第幾條，用整數數字 responses: "200": description: 查詢成功 content: application/json: schema: type: object required: [article] properties: article: type: string description: 寢室公約條款`	operation對象操作介面包含如下的屬性： `operationId`：操作對象的唯一ID。 `summary`：操作對象的摘要資訊，最好限制在 5-10字以內，主要作為概覽展示。 `requestBody`：請求體的描述。 `required`：是否為必填項。 `content`：請求體內容。`application/json`表示請求或響應的主體內容是以JSON格式編碼的資料。 `responses`：響應體的描述，直接使用常見的httpcode作為key值 `description`：關於響應內容的簡短描述。 `content`：響應體內容。 JSON schema對象 `type`：資料的類型，如string、number、object、array等。 `required`：指定必須存在的參數。 `properties`：對象中每個屬性的定義，包括它們的資料類型和描述。

小技巧：您可以藉助大模型產生符合OpenAPI v3規範的介面資訊，Prompt樣本如下：

請根據以下參數協助我產生符合OpenAPI v3規範的介面資訊：

URL: https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run/article

請求方式：post

請求參數：名稱：article_index；含義：寢室公約第幾條，用整數數字；是否必須：是。

返回參數：名稱：article；含義：寢室公約條款。

說明

完成介面資訊編寫後，請使用OpenAPI校正工具（如Swagger Editor線上工具）驗證您的OpenAPI規範是否符合規範要求，確保沒有語法錯誤或不一致的地方。

參考樣本

百鍊應用調用外掛程式時支援無鑒權、服務級鑒權和使用者級鑒權三種方式。

無需鑒權時

填寫外掛程式及介面資訊，本文以百鍊提供的寢室公約查詢工具作為樣本。
- 外掛程式名稱：寢室公約查詢工具
- 外掛程式ID尾碼：test
- 外掛程式描述填入：寢室公約查詢工具，可以根據序號查詢特定條目。
- 其它保持預設選項，單擊建立完成。
返回大模型應用管理介面，單擊選擇外掛程式，在自訂外掛程式欄勾選上一步建立好的外掛程式，單擊添加。
添加完成後，您可以在輸入框中輸入：寢室公約第二條是什嗎？大模型應用會返回以下結果：

需要鑒權時

本文以高德開放平台提供的行政地區查詢API為例。API文檔請參見行政地區查詢，介面需支援OpenAPI v3協議，樣本如下：

單擊下拉框可查看介面資訊

openapi: 3.0.2
info:
  title: 高德地圖行政區查詢API
  version: 1.0.0
  description: 查詢中國行政區劃資訊的API介面

servers:
  - url: https://restapi.amap.com

paths:
  /v3/config/district:
    get:
      summary: 查詢行政區劃資訊
      operationId: searchDistrict
      parameters:
        - in: query
          name: key
          schema:
            type: string
          required: true
          description: 請求服務許可權標識，需在高德地圖官網申請
        - in: query
          name: keywords
          schema:
            type: string
          description: 查詢關鍵字，如行政區名稱、citycode、adcode
        - in: query
          name: subdistrict
          schema:
            type: integer
            minimum: 0
            maximum: 3
          description: 設定顯示下級行政區級數，預設1
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: 需要第幾頁資料
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 20
          description: 每頁返回的最巨量資料量
        - in: query
          name: extensions
          schema:
            type: string
            enum: [base, all]
            default: base
          description: 控制返回結果中是否包含行政區邊界座標點
        - in: query
          name: filter
          schema:
            type: string
          description: 根據區划過濾，填入adcode
        - in: query
          name: callback
          schema:
            type: string
          description: JSONP回呼函數名
        - in: query
          name: output
          schema:
            type: string
            enum: [JSON, XML]
            default: JSON
          description: 返回資料格式類型

      responses:
        '200':
          description: 成功響應
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: 返回結果狀態值，0表示失敗，1表示成功
                  info:
                    type: string
                    description: 返回狀態說明
                  infocode:
                    type: string
                    description: 狀態代碼
                  suggestion:
                    $ref: '#/components/schemas/Suggestion'
                  districts:
                    type: array
                    items:
                      $ref: '#/components/schemas/District'

components:
  schemas:
    Suggestion:
      type: object
      properties:
        keywords:
          type: array
          items:
            type: string
          description: 建議關鍵字列表
        cities:
          type: array
          items:
            type: string
          description: 建議城市列表
    District:
      type: object
      properties:
        citycode:
          type: string
          description: 城市編碼
        adcode:
          type: string
          description: 地區編碼
        name:
          type: string
          description: 行政區名稱
        polyline:
          type: string
          description: 行政區邊界座標點
        center:
          type: array
          items:
            type: number
            format: float
          description: 地區中心點座標
        level:
          type: string
          enum: [country, province, city, district, street]
          description: 行政區劃層級
        districts:
          type: array
          items:
            $ref: '#/components/schemas/District'
          description: 下級行政區列表

服務級鑒權

填寫外掛程式資訊。
- 外掛程式名稱：行政地區查詢
- 外掛程式ID尾碼：administrative_region
- 外掛程式描述填入：該外掛程式用於行政地區查詢，例如“查詢杭州地區的行政地區”
- 是否鑒權：開啟鑒權開關
- 鑒權類型：服務級鑒權
- 位置：Query
- 參數名：key
- Type：basic
- Token：<輸入您的API-KEY>
填寫介面資訊。
返回大模型應用管理介面，單擊選擇外掛程式，在自訂外掛程式欄勾選上一步建立好的外掛程式，單擊添加。

使用者級鑒權

填寫外掛程式資訊：本文以高德開放平台提供的行政地區查詢API為例。
- 外掛程式名稱：行政地區查詢
- 外掛程式ID尾碼：administrative_region
- 外掛程式描述填入：該外掛程式用於行政地區查詢，例如“查詢杭州地區的行政地區。
- 是否鑒權：開啟鑒權開關
- 鑒權類型：使用者級鑒權
- 位置：Query
- 參數名：key
- Type：basic
填寫介面資訊。
返回大模型應用管理介面，單擊選擇外掛程式，在自訂外掛程式欄勾選上一步建立好的外掛程式，單擊添加。
單擊外掛程式及流程變數配置，填入鑒權token，最後單擊確定。

外掛程式添加完成後，您可以在輸入框中輸入：查詢杭州地區的行政地區，大模型應用成功調用自訂的行政地區查詢外掛程式，並正確返回結果。執行外掛程式.png

常見問題

自訂外掛程式功能是否支援透傳業務參數？

自訂外掛程式功能支援透傳業務參數，以行政地區查詢API為例，具體操作如下：

進入，單擊編輯外掛程式，配置介面資訊，為參數加入業務透傳標識x-source:user，此處將下級行政區級數設定為業務透傳參數：

parameters:
  - in: query
    name: subdistrict
    schema:
      type: integer
      minimum: 0
      maximum: 3
    description: 設定顯示下級行政區級數，預設1
    x-source: user

返回大模型應用管理介面，單擊選擇外掛程式，在自訂外掛程式欄勾選上一步建立好的外掛程式，單擊添加。
單擊外掛程式及流程變數配置，配置subdistrict變數值，最後單擊確定。
配置完成後，您可以在輸入框中輸入：查詢杭州地區的行政地區。