插件开发者文档

千帆平台作为国内首屈一指的大模型开发平台， 我们具备文心一言、开源大模型内置能力，同时具备基于Base LLM 快速开发行业应用的能力，通过对接千帆，将更方便通过大模型的能力赋能自身应用。

插件是千帆平台面向开发者、业务应用提供的一个快速与LLM链接的机制， 通过插件， 将实现千帆内大模型与外部应用接入的能力，通过LLM+插件组合，将实现如：

• Office等办公软件快速对接，如：文档助手
• 设计制作，如：AIGC设计，宣传画作设计
• 检索知识库信息，如：公司文件，政策文件、个人知识库等
• 代表用户执行，如：支持文件下发、商务订票等

千帆插件系统的工作机制

使用流程

1. 请创建一个插件文件：ai-plugin.json
   a. 文件包含插件的元数据（名称、版本、标志等）、身份验证相关信息（类型、OAuth URL等）以及需要公开API接口的OpenAPI的规范。
   b. 可为不同字段分别进行描述。
   c. 建议开始时仅开放1-2个接口，并使用最小数量的参数来最小化文本的长度， 插件的描述、API请求和API的响应都会被插入到大模型的连接上。
2. 在千帆平台的插件编排注册使用插件
   a. 在插件编排中创建使用插件， 并进行进行插件相关内容配置。
   b. 对于需要身份认证的，请提供相应的认证方式，如API 密钥。
3. 业务应用使用插件编排服务
   a. 应用开发者在插件编排中组合LLM+插件能力， 并可将组合发布为编排API。
   b. 应用开发者可将编排API集成到业务应用中， 在业务应用使用LLM+插件组合能力。
4. 业务应用用户
   a. 业务应用用户对插件无感知。
   b. 业务应用用户只需操作业务应用，如聊天、搜索等即可触发后续LLM+插件的使用组合， 并将插件结果进行合并输出。

创建插件

创建插件需要 3 个步骤：

1. 构建插件API
2. 编写插件描述文件ai-plugin.json，定义插件必须的元数据
3. 编写插件API定义文件 openapi.yaml, 文件需要符合OPENAPI规范

1.插件文件

创建插件时需要先创建一个插件文件： ai-plugin.json，该文件需要托管到API的域中。
所需文件的最小定义ai-plugin.json如下所示：

{
    "schema_version": "v1",   
    "name_for_human": "长文本理解工具",
    "name_for_model": "LongtextSummary",
    "description": "基于PDF/Doc格式文档（不支持扫描件），可检索知识点、对文档进行摘要等，支持10MB以内文件",
    "auth": {
        "type": "none"
    },
    "api": {
        "type": "openapi",
        "url": "https://example.com/openapi.yaml"
    },
    "logo_url": "https://example.com/example-icon.png",
    "contact_email": "example@baidu.com",
    "legal_info_url": "https://example.com/legal"
}

字段	类型	描述
schema_version	String	插件的版本
name_for_human	String	插件展示给用户的名称，中英文均可
name_for_model	String	插件展示给模型的名称，仅支持英文字符格式
auth	ManifestAuth	身份验证
logo_url	String	用于获取插件徽标的 URL
api	Object	OpenAPI规范
contact_email	String	用于安全/审核联系、支持和停用的电子邮件联系人
legal_info_url	String	重定向 URL 供用户查看插件信息
prompt	Object	请求大模型时使用的模版， 使用工具，请使用以下格式, 模版中必须包含工具的介绍，使用工具时按照思考/操作/输入/输出的格式，未使用工具时按照思考/AI的格式 ，请注意每个操作后包含一个空格

2.OpenAPI规范说明

OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好，那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。通用规范可参考：https://openapi.apifox.cn/

为了方便开发者接入插件市场，我们在openapi规范之上还有一些额外的限制：

• path下每个operation都必有对应的operationId，每个operationId至少有一个summary/description，描述/摘要字段最多 200 个字符；
• 每个operation输入schema的property都必须要有description，描述字段最多 200 个字符，property的格式建议使用简单格式，如string、integer等
• 每个operation输入格式目前仅支持application/json
• 每个operation输出的格式目前仅支持application/json、text/plain等纯文本格式；
• servers中需明确唯一的url地址

此外，我们建议开发者在描述插件时优先使用中文描述。

基本的插件规范如下所示：

openapi: 3.0.1
info:
  title: 插件名称
  description: 插件描述，需要在何时使用这个插件
  version: 'v1'
servers:
  - url: <http://www.example.com>
paths:
  /run:
    post:
      operationId: exampleOperation
      summary: 接口描述
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/exampleRequest'
      responses:
        "200":
          description: OK
          content:
              application/json:
                schema:
                  $ref: '#/components/schemas/exampleResponse'
        "503": 
          description: "one or more services are unavailable"
components:
  schemas:
    exampleRequest:
      type: object
      required:
      - example_param
      properties:
        example_param:
          type: string
          required: true
    exampleResponse:
      type: string
      

字段	含义
openapi	用于指定使用的OpenAPI版本
info	用于提供插件的基本信息，包括标题、描述和版本号等。
title	插件名称
description	插件描述信息
version	插件版本
servers	指定插件的服务器信息，其中每个元素都包含一个URL，用于指定API的基本URL路径。
paths	用于定义插件的各个接口以及对应的HTTP请求方式和请求参数等信息。 插件对用户仅开放run接口
/run
post	接口HTTP请求方法 支持post
operationId	接口操作id，同一个接口不同请求方法id不同，用于唯一标识该操作
summary	接口描述
responses	HTTP响应的定义，这里指定了200和503状态码，并定义了响应数据的结构
“200”	返回状态码
description	返回状态码含义
content	返回文本
application/json:	返回格式
schema	返回格式schema
$ref:	返回格式定义类，需要yaml的components写出完整定义
requestBody	请求体的定义，这里指定了请求体为JSON格式，并定义了请求数据的结构。
required	body对于当前请求体是否必须
content	请求文本
application/json:	请求格式
schema	请求格式schema
$ref:	请求格式定义类，需要yaml的components写出完整定义
components	包含接口中使用的各种组件（如数据模型、参数、响应定义等）的定义。
schemas	包含数据格式的定义
exampleRequest	待办事项列表的响应数据格式
type	exampleRequest的数据类型
properties	定义exampleRequest的一些对象属性、值以及值的类型和描述
example_param	getTodosResponse的一个属性， · type为属性类型，目前仅支持string类型 · description是对当前属性的描述,可选

3. 插件API开发示例

以开发一个代金券助手为例，必须实现的接口如下：

• POST/ run

import json

import quart
import quart_cors
from quart import request

app = quart_cors.cors(quart.Quart(__name__), allow_origin="*")


@app.post("/run")
async def (username):
    request = await quart.request.get_json(force=True)
    if "example_param" not in request:
        return quart.Response(response='缺少example_param', status=503)
    return quart.Response(response='OK', status=200)

@app.get("/ai-plugin.json")
async def plugin_manifest()
    host = request.headers['Host']
    with open("ai-plugin.json") as f:
        text = f.read()
        return quart.Response(text, mimetype "text/json"）

@app.get("/openapi.yaml")
async def openapi_spec()
    host = request.headers['Host']
    with open("openapi .yaml") as f:
        text = f.read()
        return quart.Response(text, mimetype "text/yaml"）

def main():
    app.run(debug=True, host="0.0.0.0", port=80)

if __name__ == "__main__":
    main()

4. 文件样例

【ai-plugin.json】

{
  "schema_version": "v1",
  "name_for_human": "待办事项",
  "name_for_model": "ToDoList",
  "description": "给自己记录记录待办事项时使用，对待办事项的处理支持插入、删除、查询",
  "auth": {
    "type": "none"
  },
  "api": {
    "type": "openapi",
    "url": "http://www.example.com/openapi.yaml",
    "is_user_authenticated": false
  },
  "contact_email": "support@example.com",
  "legal_info_url": "http://www.example.com/legal",
}

【openapi.yaml】

openapi: 3.0.1
info:
  title: 待办事项
  description: 给自己记录记录待办事项时使用，对待办事项的处理支持插入、删除、查询
  version: 'v1'
servers:
  - url: http://www.example.com
paths:
  /run:
    post:
      operationId: todo
      summary: 对待办事项进行处理
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/todoRequest'
      responses:
        "200":
          description: OK
          content:
              application/json:
                schema:
                  $ref: '#/components/schemas/todoResponse'
                               
components:
  schemas:
    todoRequest:
      type: object
      required:
        - 操作
      properties:
        操作:
          type: string
          description: 对待办事项的操作方法
          required: true
        顺序:
          type: string
          required: false
        事项:
          type: string
          required: false
   todoResponse:
       type:object
       properties:
           result:
              type: string

5. 插件运行机制

在确定完成插件OpenAPI、插件文件、OpenAPI规范后， 开发者可在千帆开放平台进行插件注册和测试。 再次之前，需要明确：

1.对于注册到平台的插件，你的插件服务需要用开放域地址。

6. 撰写说明

• 当用户使用带有插件配置应用时， 大模型会基于对插件的description进行理解， 并以此判断是否进行调用， 因此建议对插件的描述和提示进行多次测试，以便达到最优效果。
• 对于description， 我们建议尽量使用简洁并且具有描述性和客观性的语气的自然语言进行描述。
• 对于OpenAPI，我们建议尽量少的开放端口， 对于功能丰富的API， 我们建议只需要开放1-2个符合业务逻辑的接口即可。尽量为模型提供有关 API 各种细节的信息——可用的功能、参数等。

安全验证

插件提供多种身份验证模式以适应各种用例。对于需要认证插件，请在插件文件中对其验证方式进行说明。

无认证

我们支持不需要身份验证的应用程序的无身份验证流程，用户可以不受任何限制地直接向您的 API 发送请求。

"auth": {
    "type": "none"
},

插件约束

速率限制

插件的访问规模将会随着千帆平台的推广以及大模型的使用逐渐增大，请开发者可以监控请求的数量并相应地设置限制调整。

插件更新

将插件部署到生产环境后，您可能想要更改ai-plugin.json清单文件。对于新更改的清单文件， 需要再次进行插件的发布流程。
更新后每次发出请求时， 将会自动获取最新的 OpenAPI 规范。

常问问题

1. 如何使用插件数据？

插件将千帆大模型连接到外部应用程序。如果用户启用插件，千帆开放平台可能会将他们的部分信息发送到您的插件。

2. 如果对我的 API 的请求失败会怎样？

如果 API 请求失败，平台可能会重试请求多达 10 次，随后告知用户暂时无法从该插件获得响应。

插件政策

• 插件清单必须有一个明确的描述，与暴露给模型的 API 的功能相匹配。
• 不要在插件清单、OpenAPI 端点描述或插件响应消息中包含不相关、不必要或欺骗性的术语或说明。这包括避免使用其他插件的说明，或尝试控制或设置模型行为的说明。
• 不要使用插件来规避或干扰千帆的安全系统。
• 不要使用插件来自动与真人对话，无论是通过模拟类似人类的响应还是通过使用预编程的消息进行回复。
• 分发由 大模型 生成的个人通信或内容（例如电子邮件、消息或其他内容）的插件必须表明该内容是由 AI 生成的。