插件开发者文档
插件应用已于2024年7月31日迁移至AppBuilder,本文档为历史参考,如有需要请您于AppBulier使用或关注。
作为国内首屈一指的大模型开发平台, 我们具备文心一言、开源大模型内置能力,同时具备基于Base LLM 快速开发行业应用的能力,通过对接本平台,将更方便通过大模型的能力赋能自身应用。
插件是本平台面向开发者、业务应用提供的一个快速与LLM链接的机制, 通过插件, 将实现本平台内大模型与外部应用接入的能力,通过LLM+插件组合,将实现如:
- Office等办公软件快速对接,如:文档助手
- 设计制作,如:AIGC设计,宣传画作设计
- 检索知识库信息,如:公司文件,政策文件、个人知识库等
- 代表用户执行,如:支持文件下发、商务订票等
本平台插件系统的工作机制
使用流程
- 请创建一个插件文件:ai-plugin.json
a. 文件包含插件的元数据(名称、版本、标志等)、身份验证相关信息(类型、OAuth URL等)以及需要公开API接口的OpenAPI的规范。
b. 可为不同字段分别进行描述。
c. 建议开始时仅开放1-2个接口,并使用最小数量的参数来最小化文本的长度, 插件的描述、API请求和API的响应都会被插入到大模型的连接上。 - 在本平台的插件编排注册使用插件
a. 在插件编排中创建使用插件, 并进行进行插件相关内容配置。
b. 对于需要身份认证的,请提供相应的认证方式,如API 密钥。 - 业务应用使用插件编排服务
a. 应用开发者在插件编排中组合LLM+插件能力, 并可将组合发布为编排API。
b. 应用开发者可将编排API集成到业务应用中, 在业务应用使用LLM+插件组合能力。 - 业务应用用户
a. 业务应用用户对插件无感知。
b. 业务应用用户只需操作业务应用,如聊天、搜索等即可触发后续LLM+插件的使用组合, 并将插件结果进行合并输出。
创建插件
创建插件需要 3 个步骤:
- 构建插件API
- 编写插件描述文件ai-plugin.json,定义插件必须的元数据
- 编写插件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 供用户查看插件信息 |
description | String | 插件的描述信息,用于描述插件的功能,在意图识别阶段帮助模型决定是否调用该插件 |
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
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 run(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: 对待办事项的操作方法
顺序:
type: string
事项:
type: string
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 生成的。