插件

• 什么是插件
• 如何使用插件
• 如何创建plugin-api端点

什么是插件（Plugins）

插件 API 允许您在索引时添加任何其他元信息。 您可以在插件页面的仪表板上创建和修改插件并连接到端点。 使用插件 API，可以对数据进行编码、处理和转换。 SOCO 目前支持使用 RESTful API 和 GRPC 的 POST 方法

GRPC

GRPC 通常作为构建索引时的插件，当 Soco-search 索引文档时，我们会调用用户通过 UI 定义的 GRPC 端点。

例如，为了使用 soco-search 构建视频搜索，有很多步骤来处理数据：

1. 从 urls 下载视频
2. 从视频中提取关键帧
3. 保存关键帧图像并保存在服务器中
4. 索引关键帧 获得播放视频的开始时间范围

我们可以构建这个复杂的流程作为插件，并 soco-search 中注册插件以备后用。请查看GRPC 插件的示例

RESTful API

RESTful API 一般用于Query的插件。例如，为了从图像中搜索图像或视频，我们需要使用图像编码器对图像进行编码。 如果我们将图像编码器注册为查询插件，我们可以使用此查询插件对图像进行编码以进行图像搜索.

或者，我们有一些新闻的文字数据，当我们索引这些新闻的时候，我们希望能够通过现有的机器学习模型来添加“情感”或者“话题”的信息。我们可以使用插件功能轻松地将这些模型添加到 soco-search-worker 中，并且这些插件具有高度的灵活性和可定制性。请查看RESTful API 插件的示例

Plugin的使用流程

为了使用插件，您需要通过以下流程进行插件的创建以及调用，您可以点击对应的链接查看详细的流程：

1. 创建Plugin API 端点
2. 在Dashboard上创建Plugin
3. 在Mapping信息中添加plugin信息
4. 在索引时使用对应的Mapping

如何创建Plugin API端点

为了给 Plugin API 构建 GRPC 或 RESTful API 端点，我们需要特定的输入和输出格式， 以下为输入格式的示例。 它应该有一个列表类型的“数据（data）”字段，且列表的每个项目都应该有“值（value）”（“配置”是可选的）

{
  "data": [
    {
      "value": "say hello", "configs":{"lang":"en"}
    },
    {
      "value": "say hi", "configs":{"lang":"en"}
    },
    .......
  ]
}

处理输入数据后，API 必须返回“resp”（response的简写，即为返回结果），它也是一个列表类型，并且列表中的每一项都必须与索引映射中定义的类型相同。 下面的返回类型示例是term_score类型：

{
  "resp": [
    {
      "positive": 1.0
    },
    {
      "negative": 0.8
    },
    .......
  ]
}

GRPC 插件的示例

请参考这里的代码,如下部分即为构建 GRPC 插件的重要文件：

    soco_grpc
    ├── model.py                   # When adding thew new plugins, change this file
    └── server.py                  # the GRPC server to make the endpoint 

在制作插件API时，首先我们需要修改'model.py'。 在model.py中，需要做的是定义ClassName并实现“plugin_method方法”（见下面第12行）

1 class ClassName(plugins_pb2_grpc.PluginsServicer):
2    def __init__(self):
3        pass
4    def plugin(self, request, context) -> plugins_pb2.Output:
5        batch = []
6        for key in request.body:
7            data = request.body[key]
8            data_list = data.list_value
9            for item in data_list.values:
10                batch.append(json.loads(item))
11        
12        resp = plugin_method(batch) # 
13        return plugins_pb2.Output(resp=json.dumps(resp))

修改model.py后，在server.py的第22行可以看到如下代码，请将ClassName修改为model.py中定义的类名

22    plugins_pb2_grpc.add_PluginsServicer_to_server(ClassName(), server)

完成后，我们可以运行 GRPC 服务器并对其进行测试。

1. 运行服务器

python soco_grpc/server.py

2. 运行 grpc_test.py

python soco_grpc/grpc_test.py

如果您可以与 grpc_test 和服务器通信，则可以使用“Dockerfile”构建 docker 镜像

RESTful API 插件的示例

请参考这里的代码。如下为构建 RESTful API 插件的重要文件。

    server
    └── app                  
        └── server                  
            ├── models                   
            └── routers                   
                └── routers                 
                    └── query_encoder.py    # define the endpoint 
                └── app.py                  # define the router
            

您需要添加路由器并定义如下函数（请查看 query_encoder.py）：

@router.post("/{end_point}", name="image_encode")
def encode(x: PluginIn = Body(...)) :
    x = jsonable_encoder(x)
    docs = [{"url":z["value"] for z in x["data"]}]
    result = enc.encode(docs, params)
    return PluginOut(resp=result)

定义端点后，您可以在以下内容中包含路由器（请查看 app.py）

app.include_router(QueryRouter, tags=["QueryManager"], prefix="/v1/query")