插件开发者文档
千帆插件系统的工作机制

使用流程
1.
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+插件的使用组合, 并将插件结果进行合并输出。
创建插件
1.
2.
3.
1.插件文件
所需文件的最小定义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: 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开发示例
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. 文件样例
{
"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: 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. 插件运行机制
6. 撰写说明
安全验证
无认证
"auth": {
"type": "none"
},
插件约束
速率限制
插件更新
更新后每次发出请求时, 将会自动获取最新的 OpenAPI 规范。
常问问题
1. 如何使用插件数据?
2. 如果对我的 API 的请求失败会怎样?
插件政策
修改于 2023-11-15 03:33:43