How to Create a Custom Plug-in - Alibaba Cloud Model Studio

If the official plug-ins cannot meet your business requirements, you can create a custom plug-in to integrate the desired API, whether it is a personal development or a third-party API.

Procedure

Step 1: Go to the Add Custom Plug-in page

Method 1: Log on to the Alibaba Cloud Model Studio console. In the left-side navigation pane, choose Application Components > Plug-in Management. Then, click Create Custom Plug-in.
Method 2: If you already have a large language model (LLM) application, go to the Configuration page of the application. Click Select Plug-in. In the Select Plug-in pane, click Create Custom Plug-in.

Step 2: Specify plug-in information

On the Add Custom Plug-in page, configure the following parameters:

Plug-in Name:
Enter a descriptive name for the plug-in in English or Chinese.
The Plug-in Name helps the LLM determine whether it needs to call the plug-in for a given task.
Plug-in ID:
Enter a descriptive name in English, such as 'search' or 'weather'. After you click Create, Model Studio will generate a unique plug-in ID for you.
Use the Plug-in ID to call your custom plug-in through Assistant API.
Plug-in Description:
Enter a description of the functionality of the plug-in in natural language and include examples if possible. For example: "This plug-in retrieves weather and temperature information for a specified time and location, such as 'Query the weather and temperature in Singapore tomorrow'".
The Plug-in Description helps the LLM determine whether it needs to call the plug-in for a given task.
Enable Authentication:
(Optional) Specifies whether authentication is needed when applications call your plug-in. You can choose from No Authentication, Service-level Authentication, and User-level Authentication based on the security policy of the API provider.
Authentication Type:
For Service-level Authentication, a token is not required for each call. Instead, you must specify a token when creating the plug-in.
For User-level Authentication, a token is required for each call.
Service-level Authentication
- Location: The authentication information can be included in either the Header or the Query.
  - Header: Include authentication details within the Authorization field of the HTTP request header to keep them concealed from the URL.
  - Query: Include authentication information within the URL, for example, https://example.com?api_key=123456.
- Parameter Name: If you select Query, specify the parameter that is required for authentication, such as api_key. If you select Header, the parameter is Authorization by default.
- Type:
  - basic: The provided token is used without any preceding content.
  - bearer: Prepend "Bearer" to the token.
  For example, if you select bearer: ("Authorization": "Bearer <YOUR_TOKEN>").
- Token: This is the authentication token, such as an API Key from the API provider.
User-level Authentication
- Location: The authentication information can be included in either the Header or the Query.
  - Header: Include authentication details within the Authorization field of the HTTP request header to keep them concealed from the URL.
  - Query: Include authentication information within the URL, for example, https://example.com?api_key=123456.
- Parameter Name: If you select Query, specify the parameter that is required for authentication, such as api_key. If you select Header, the parameter is Authorization by default.
- Type:
  - basic: The provided token is used without any preceding content.
  - bearer: Prepend "Bearer" to the token.
  For example, if you select bearer: ("Authorization": "Bearer <YOUR_TOKEN>").
If you use user-level authentication, you need to configure token on the application configuration page. For more information, see User-level authentication.
Tab 正文

Step 3: Specify interface information

In the code box, define your API interface information according to the OpenAPI v3 specification. The OpenAPI specification, formerly known as the Swagger Specification, is the world's standard for describing RESTful APIs. For more information, see OpenAPI Specification v3.0.3. Sample:

openapi: 3.0.1
info:
    title: Dormitory Convention Query Tool
    description: The dormitory convention query tool can query a specific article based on the serial number. 
    version: "v2"
servers:
    - url: https://domitorgreement-plugin-example-nblivhmlwc.ap-southeast-1.fcapp.run
paths:
    /article:
        post:
            operationId: get_article
            summary: Query an article based on the serial number, which is an integer.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [article_index]
                            properties:
                                article_index:
                                    type: integer
                                    description: The serial number of the article, which is an integer.
            responses:
                "200":
                    description: The query is successful.
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [article]
                                properties:
                                    article:
                                        type: string
                                        description: The article.

The sample contains the following key objects:

```
openapi: 3.0.1
```
OpenAPI object
This object specifies the OpenAPI version in use.
```
info:
    title: Dormitory Convention Query Tool
    description: The dormitory convention query tool can query a specific article based on the serial number. 
    version: "v2"
```
Info object
This object provides metadata about the API, useful for clients.
- title: The title of the plug-in.
- description: The description of the plug-in.
- version: The version number of the OpenAPI interface protocol.
```
servers:
    - url: https://dormitoryagreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run
```
Server object
This object defines the server's path.
- url: Specifies the base path for server access.
```
paths:
    /article:
        post:
```
Paths object
paths: Specifies the relative path to a specific endpoint, which must start with a forward slash (/). This path is combined with the base URL defined in the Servers Object to form the complete URL.
- The /article path includes a POST method to interface with the operation.
  You can use HTTP methods such as GET, POST, or DELETE to interact with the API interface according to your requirements.

operationId: get_article
summary: Query an article based on the serial number, which is an integer.
requestBody:
    required: true
    content:
        application/json:
            schema:
                type: object
                required: [article_index]
                properties:
                    article_index                            article_index:
                        type: integer
                        description: The serial number of the article, which is an integer.
responses:
    "200":
        description: The query is successful.
        content:
            application/json:
                schema:
                    type: object
                    required: [article]
                    properties:
                        article:
                            type: string
                            description: The article.

Operation object
This object details the attributes of the operation interface:
- operationId: The ID of the operation object.
- summary: The concise overview of the operation object, ideally within 5-10 words.
- requestBody: Describes the request body.
  - required: Specifies whether the item is mandatory.
  - content: Specifies the request body content. application/json denotes JSON format for request or response body data.
- responses: Describes the response body, using common HTTP status codes as keys.
  - description: Summarizes the response content briefly.
  - content: Details the content of the response body.
JSON Schema object
- type: Specifies the data type, such as string, number, object, array, etc.
- required: Specifies which parameters are mandatory.
- properties: Describes each attribute within the object, including their respective data types and descriptions.

Tips: You can use a LLM to generate interface information that complies to the OpenAPI v3 specification. Sample prompt:

Generate an interface information that complies with the OpenAPI v3 specification based on the following parameters:

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

Request Method: post

Request Parameter: Name: article_index; Description: The serial number of the dormitory convention article, which is an integer; Required: Yes.

Response Parameter: Name: article; Description: The text of the dormitory convention article.

Note

You can check whether your interface information complies with the OpenAPI specification by using tools such as Swagger Editor Online Tool to avoid syntax errors or inconsistencies.

Examples

You can choose from No Authentication, Service-level Authentication, and User-level Authentication for your plug-in.

No authentication

Enter the plug-in and interface information. Here, the Dormitory Convention Query Tool is used as an example.
- Plug-in Name: Dorm Convention
- Plug-in ID Suffix: test
- Plug-in Description: Enter 'The dormitory convention query tool can query a specific article based on the serial number.'
- Use the default values for other parameters. Then, click Create.
Go back to the application configuration page. Click Select Plug-in, in the Custom Plug-in tab, Add the plug-in you created.
After adding, you can ask: What is the second article of the dormitory convention? The LLM application returns the following sample response:

Authentication required

The Administrative Region Query API provided by the AMAP Open Platform is used as an example. For the API documentation, see Administrative Region Query. The interface must support the OpenAPI v3 protocol. Sample:

Click to view interface information

openapi: 3.0.2
info:
  title: Amap Administrative Region Query API
  version: 1.0.0
  description: API interface for querying administrative division information in China

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

paths:
  /v3/config/district:
    get:
      summary: Query administrative division information
      operationId: searchDistrict
      parameters:
        - in: query
          name: key
          schema:
            type: string
          required: true
          description: Request service permission identifier, must be applied for on the Amap website
        - in: query
          name: keywords
          schema:
            type: string
          description: Query keywords, such as administrative district name, citycode, adcode
        - in: query
          name: subdistrict
          schema:
            type: integer
            minimum: 0
            maximum: 3
          description: Set the level of sub-administrative districts to display, default is 1
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Which page of data is needed
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 20
          description: Maximum amount of data returned per page
        - in: query
          name: extensions
          schema:
            type: string
            enum: [base, all]
            default: base
          description: Control whether the returned result includes administrative district boundary coordinates
        - in: query
          name: filter
          schema:
            type: string
          description: Filter by district, fill in adcode
        - in: query
          name: callback
          schema:
            type: string
          description: JSONP callback function name
        - in: query
          name: output
          schema:
            type: string
            enum: [JSON, XML]
            default: JSON
          description: Return data format type

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: Return result status value, 0 indicates failure, 1 indicates success
                  info:
                    type: string
                    description: Return status description
                  infocode:
                    type: string
                    description: Status code
                  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: Suggested keyword list
        cities:
          type: array
          items:
            type: string
          description: Suggested city list
    District:
      type: object
      properties:
        citycode:
          type: string
          description: City code
        adcode:
          type: string
          description: Area code
        name:
          type: string
          description: Name of the administrative district
        polyline:
          type: string
          description: Boundary coordinates of the administrative district
        center:
          type: array
          items:
            type: number
            format: float
          description: Center coordinates of the district
        level:
          type: string
          enum: [country, province, city, district, street]
          description: Level of the administrative division
        districts:
          type: array
          items:
            $ref: '#/components/schemas/District'
          description: List of sub-administrative districts

Service-level authentication

Enter the plug-in information.
- Plug-in Name: AdministrativeRegion
- Plug-in ID Suffix: administrative_region
- Plug-in Description: This plug-in facilitates administrative region queries, such as "Query the administrative region of Hangzhou area."
- Enable Authentication: Enable the authentication.
- Authentication Type: Service-level Authentication.
- Location: Query
- Parameter Name: key
- Type: basic
- Token: Enter your API Key here
Enter the interface information.
Go back to the application configuration page. Click Select Plug-in, in the Custom Plug-in tab, Add the plug-in you created.

User-level authentication

Enter the plug-in information.
- Plug-in Name: AdministrativeRegion
- Plug-in ID Suffix: administrative_region
- Plug-in Description: This plug-in facilitates administrative region queries, such as "Query the administrative region of Hangzhou area."
- Enable Authentication: Enable the authentication.
- Authentication Type: User-level Authentication.
- Location: Query
- Parameter Name: key
- Type: basic
Enter the interface information.
Go back to the application configuration page. Click Select Plug-in, in the Custom Plug-in tab, Add the plug-in you created.
Click Plug-in and Process Variable Configuration, enter the authentication token, and click OK.

After adding, you can ask: Query the administrative region of Hangzhou area, and the LLM application calls the custom administrative region plug-in and return the correct result. 执行插件.png

FAQ

Does the custom plug-in feature support pass-through of business parameters?

The custom plug-in feature supports pass-through of business parameters. Take Administrative Region Query API as an example, take the following steps:

Go to Plug-in Center. On the Custom Plug-in tab, click Modify Plug-in. On the Modify Custom Plug-in page, configure the interface information. Add the pass-through identifier x-source:userto the subdistrict parameter as a pass-through parameter:
```
parameters:
  - in: query
    name: subdistrict
    schema:
      type: integer
      minimum: 0
      maximum: 3
    description: Set the level of sub-administrative districts to display, default is 1
    x-source: user
```
Go back to the application configuration page. Click Select Plug-in, in the Custom Plug-in tab, Add the plug-in you created.
Click Plug-in and Process Variable Configuration, specify the value of subdistrict and click OK.
After configuring, you can ask: Query the administrative region of Hangzhou area to test the effect.