微软Copilot插件开发系列（一）

懂AI PC的人要先拥抱新世界了。继联想、荣耀之后，微软的首款AI PC马上也要来了。去年9月，Colpilot正式进入Windows 11，成为电脑系统的AI助手。

可以在各种场景下完成各种任务，例如发邮件、控制电脑亮度等

但是，Copilot 无法获取第三方服务的实时信息，例如最新的新闻、天气、股票等。这时，我们就可以使用 OpenAI schema 开发Copilot 插件，来扩展Copilot 的功能，让它能够与我们自己的 API 交互。本文作为该系列的第一篇，将带你初步了解下copilot的基本概念和开发示例。

什么是Copilot 插件？

通俗说就是使用 OpenAI schema 来为Copilot 添加自定义功能的方式，以此来将我们自己的应用连接到Copilot。插件可以让 Copilot获取外部信息或执行某个任务。例如，一个获取最新的新闻和天气信息的插件，或者让用户在一个待办事项列表中添加或删除项目。

那么构成插件由哪些要素呢？

运行在我们自己服务器上的 API服务，用来执行具体的任务。遵循OpenAPI schema 的对API做了详细说明的 YAML 或 JSON 文件，例如 openapi.yaml 名为ai-plugin.json 的 JSON 文件，用来告诉Copilot 何时以及如何使用我们的插件

插件三要素

那么具体起来应该怎么操作呢？下面举一个具体的栗子

一个 Copilot 插件的示例

假设我们想要开发一个插件，可以根据用户的搜索条件，例如城市、卧室数、浴室数、设施等，来找到房地产列表。我们用 contoso.com 作为我们API 服务。

那么第一步我么就来定义Openapi 格式的YAML文件

下面定义一个 /get-listings 的路径，以搜索条件作为参数，返回一个 JSON 格式的房地产列表。

yaml 复制代码

openapi: 3.0.0
info:
  title: Contoso Real Estate API
  version: 1.0.0
paths:
  /get-listings:
    get:
      summary: 根据搜索条件获取房地产列表
      parameters:
        - name: city
          in: query
          description: 要搜索的城市
          required: true
          schema:
            type: string
        - name: bedrooms
          in: query
          description: 卧室数量
          required: false
          schema:
            type: integer
        - name: bathrooms
          in: query
          description: 浴室数量
          required: false
          schema:
            type: integer
        - name: amenities
          in: query
          description: 需要包含的设施
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: 房地产列表
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: 房地产的唯一标识符
                    address:
                      type: string
                      description: 房地产的地址
                    price:
                      type: number
                      description: 房地产的价格
                    image_url:
                      type: string
                      description: 房地产图片的 URL
                    description:
                      type: string
                      description: 房地产的描述

第二步来定义ai-plugin.json，用来告诉Copilot 何时以及如何使用我们的插件，如下所示：

css 复制代码

{
  "schema_version": "v1",[^1^][1]
  "name_for_model": "contosorealestate",[^2^][2]
  "description_for_model": "根据搜索条件在市场上找到待售的房地产的插件",
  "name_for_human": "Contoso 房地产",[^3^][3]
  "description_for_human": "在市场上找到最新和详细的待售房地产",
  "api": {[^4^][4]
    "type": "openapi",[^5^][5]
    "url": "https://contoso.com/openapi.yaml",[^6^][6]
    "is_user_authenticated": false[^8^][8]
  },
  "auth": {[^9^][9]
    "type": "none"[^10^][10]
  },
  "logo_url": "https://contoso.com/logo.png",[^11^][11]
  "contact_email": "contact@contoso.com",[^13^][13]
  "legal_info_url": "https://contoso.com/legal/",[^12^][12]
  "privacy_url": "https://contoso.com/privacy-policy"[^7^][7]
}

以上都准备妥当之后，下一步是啥呢？那就要走软件开发标准流程-测试了。

测试我们开发的插件

第一个要解决的问题是让插件联网，Copilot要能够访问到你的插件才能测试吧。上面案例中API服务我们直接用了别人家的，如果是自己的API服务，那就要将它开放给互联网了。其实也很简单vs code有一个forward port功能，这里不在赘述了。

API YAML文件和插件清单怎么让Copilot知道呢？这个就像上传文件那么简单。看到下面这个扳手按钮了吗？

首先告诉它API的访问地址是啥

然后点击Find manifest file按钮来上传两个插件说明书，一个是YAML文件另一个是ai-plugin.json文件

如果检验通过，可以在对话列表中选中这个插件聊天了

比方说，如果我们问：

我想在纽约找一个有两个卧室和两个浴室的房子。
在伦敦有什么带游泳池的房子吗？
我可以在巴黎花 50 万欧元买到什么样的房子？

Copilot 会根据我们的插件清单中的描述，判断插件是否可以用来回答用户的问题。如果是，Copilot 会根据API说明文件中的请求使用说明，构造并发送请求，并根据返回的结果，生成如下类似回复：这是我为你找到的一些在纽约有两个卧室和两个浴室的房子的列表：

ID: 123456

地址：123 Main Street
价格：$500,000
图片：链接
描述：这是一个位于市中心的现代公寓，有两个宽敞的卧室和两个带浴缸的浴室，还有一个阳台和一个停车位。
ID: 234567
地址：456 Park Avenue
价格：$800,000
图片：链接
描述：这是一个位于高档社区的豪华别墅，有两个豪华的卧室和两个带按摩浴缸的浴室，还有一个私人花园和一个游泳池。

测试一个插件是不是很简单？是很简单，其实难的还是如何搭建自己的API服务。

读到这里，想必有些人对原理感兴趣，我不把原理放到前面，是怕有些人看到原理，看到框架就觉得这是个很复杂的事情，就会绕道走。可是原理也很简单的。

Copilot插件运行原理

假如你在Copilot聊天界面里提问，说："找纽约有4个卧室的房子。"

Copilot看到用户的问题后，会决定是否使用一个插件来帮助回答问题。它先去看下这个插件的描述是："用于在特定城市找到市场上待售的房产，可以指定卧室、浴室数量以及设施。" 插件的API说明文档里有一个叫做"get-listings"的路径，用来"获取符合指定条件的房产列表"。

Copilot觉得可以调用插件的API，通过插件的OpenAPI说明生成正确的请求。然后发送一个请求到网址contoso.com/get-listing...

API服务收到请求后，会返回一个响应。这个响应包含一些房源信息，比如[{"title": "城市中心的明亮公寓", "城市": "纽约", "卧室": 4, "描述": "..."}]。

Copilot根据插件的OpenAPI规范从响应中提取信息。

Copilot会结合API的响应信息来回答用户的问题。告诉用户找到了符合条件的房子，然后提供相关信息，如房子的标题、城市、卧室数量等。

看到这里，想必你一定觉得开发Copilot插件不是很难。这就跟正常的软件开发流程一样，有产品定义文档，有开发测试，最后是发布。哦对了，怎么发布插件到应用市场上，这个咱们下期在介绍了。