创建自定义列表
重要
本文中的某些信息与预发行的产品有关,该产品在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。
提示
如果需要有关非 Microsoft 插件的帮助,请参阅其文档和技术支持。
根据管理员配置安全 Copilot 的操作方式,可以通过执行以下步骤来创建新插件:
从支持的插件列表生成插件。
创建 YAML 或 JSON 插件清单文件,该文件描述有关插件的元数据以及如何调用它。
将插件清单发布到安全 Copilot。
每个安全 Copilot 插件都需要一个 YAML 或 JSON 格式的清单文件(例如: plugin.yaml
或 plugin.json
),用于描述有关技能集的元数据以及如何调用技能。
清单必需由两个高级别的密钥组成,即 Descriptor
和 SkillGroups
,每个密钥都具有子键或值对,以及必需/可选字段,具体取决于技能格式。
有关 OpenAI 插件的信息,请参阅 入门。
字段 | 类型 | 说明 | 必需 |
---|---|---|---|
Name |
string | 插件的内部名称。 不允许 / \ ? # @ 。 |
是 |
DisplayName |
string | 插件的用户可读名称。 | 建议 |
Description |
string | 插件的用户可读说明。 | 是 |
DescriptionDisplay |
string | 如果未指定说明,则替代插件的用户可读说明。 | 否 |
Category |
string | 注意:此值当前在自定义插件上传过程中强制执行 Plugin 。 |
否 |
Prerequisites |
string | 否 | |
Icon |
string | 用于提取 Skillset 主图标的 URL。 | 建议 |
由技能组的列表组成,包括 Format
、Settings
和 Skills
。
字段 | 类型 | 说明 | 必需 |
---|---|---|---|
Format |
string | 有关可用选项,请参阅“格式”部分。 | 是 |
Settings |
object | 请参阅对象结构的“设置”部分。 | 是,适用于格式: API 、DOTNET 、CONTAINER |
Skills |
object | 请参阅对象结构的“技能”部分。 | 是,适用于格式: GPT 、DOTNET 、KQL 、LogicApp |
字段 Format
的选项:
API
GPT
KQL
字段 Settings
的对象结构。
字段 | 类型 | 说明 | 必需 |
---|---|---|---|
OpenApiSpecUrl |
string | 公共 OpenAPI 规范的 URL。 | 是 |
EndpointUrl |
string | 公共终结点的 URL。 | 否 |
字段 Skills
的对象结构。
字段 | 类型 | 说明 | 必需 |
---|---|---|---|
Description |
string | 此技能的用户可读说明。 | 建议 |
DescriptionForModel |
string | 用于技能选择的技能详细说明 | 否 |
Inputs |
object | 用于用户输入技能的对象列表 Name 、Description 、Required 和 DefaultValue (可选)。 |
|
Settings |
object | 基于技能 格式 的自定义设置。 |
遵循 ChatGPT 插件文档 生成的 OpenAI 插件通常使用与 Microsoft 安全 Copilot 不同的清单格式。 安全 Copilot 支持两种格式。
上传时,OpenAI 插件 清单 将转换为安全 Copilot 清单。
备注
映射详细信息(尤其是笔记中的限制)可能会在将来发生更改。 目前,平台仅支持 OpenAPI 版本 3.0 或 3.0.1 中的插件。
插件字段 | 类型 | 描述符字段 | 必需 | 注意 |
---|---|---|---|---|
schema_version |
string | 否 | 它是 OpenAI 清单架构版本,例如“v1”。 目前尚未使用。 | |
name_for_model |
string | 名称 | 是 | 限制为长度为 100 个字符。 技能集的内部名称。 不允许 / \ ? # 。 |
name_for_human |
string | DisplayName | 是 | 插件的用户可读名称。 限制长度为 40 个字符。 |
description_for_model |
string | 说明 | 是 | 限制长度为 16,000 个字符。 与 LLM 一起使用的内部说明。 |
description_for_human |
string | DescriptionDisplay | 是 | 插件的用户可读说明。 限制长度为 200 个字符。 |
logo_url |
string | 图标 | 建议 | 用于提取插件的主图标的 URL。 |
contact_email |
string | 否 | 插件的电子邮件联系人。 目前尚未使用。 | |
legal_info_url |
string | 否 | 插件信息链接。 目前尚未使用。 | |
api |
object | 请参阅对象结构的 插件 API 部分 | 是 | |
auth |
object | 是 |
authorization_type 限制为 bearer 。 有关支持不同身份验证 type (例如 none、oauth、api_key、aad、aad_delegated) 的详细信息。 |
字段 api
的对象结构
字段 | 类型 | 说明 | 必需 |
---|---|---|---|
type |
string | 当前唯一支持的类型是 openapi 。 |
是 |
url |
string | 链接到 API 的 OpenAPI 规范 文档。 | 是 |
有关插件创作的许多注意事项。 本文档旨在记录编写 Microsoft 安全 Copilot 插件的一些准则和最佳做法。
备注
当 Microsoft 安全 Copilot 无法准确区分两种不同的技能时,会发生“技能冲突”。
并非拥有多个返回相同类型响应的技能,只是根据输入的不同而有所区别;定义技能,让技能采用多个输入,然后在内部确定获取数据的方法。
- 例如,具有单个技能
GetDevices
,该技能采用设备 ID、用户 ID 或用户名,而不是单独的GetDeviceById
、GetDeviceByUserId
和GetDeviceByUserName
- 例如,具有单个技能
安全 Copilot 支持
Description
和DescriptionForModel
字段。Description
在 UX 中使用(如果DescriptionForModel
未设置,则用于技能选择),并且DescriptionForModel
仅用于技能选择。- 例如,假设我们有一个技能 GetSslCertsByHostname,其中包含“返回与主机名关联的 SSL 证书”的说明。 详细描述 ForModel 可以是“检索 DNS 主机名或域名的 SSL 证书(也称为 TLS 证书)。 返回 SSL 证书列表以及证书详细信息,例如颁发者、使用者、序列号、sha1 和日期”。
技能说明应言简意赅,措辞应适合有一定知识但可能不是问题领域专家的人。 它不仅应该描述技能的作用,还应描述为什么有人想要使用它。
- 例如,好的描述应是“获取 IP 地址的信誉信息。 使用户能够确定 IP 地址是否存在风险”。