火山云搜索服务插件是火山引擎云搜索服务提供的一款插件，该插件借助火山引擎的云搜索服务 ES 和 OpenSearch 引擎，和开源的 ES 以及 OpenSearch 语法相兼容，能够进行文本和向量的混合搜索，很好地将精准查询和语义查询进行结合。火山云搜索服务插件还能存储超大规模的向量（适用规模在十万到五百亿之间），支持扣子的聊天机器人使用云搜索功能。
目前火山云搜索服务插件已支持 search template 工具，通过调用 ES 或者 OpenSearch 的 search template 接口可实现向量文本召回。
本文完整介绍了在扣子中使用云搜索插件的完整流程，该流程可分为开通云搜索服务实例并构建知识库和在扣子中使用火山云搜索插件两部分。

开通云搜索服务实例并构建知识库

1. 开通火山引擎云搜索服务
   1. 注册火山引擎账号并完成实名认证。
   2. 在火山引擎控制台开通云搜索服务。
2. 创建引擎实例
   参考云搜索服务快速入门创建 ES 或者 OpenSearch 引擎。

   说明

   建议在 AI 搜索和向量相关的场景中使用 OpenSearch 2.9 版本，支持百亿级别向量。

3. 开启公网访问。为实例开启公网访问，详细信息，可参考配置实例公网访问。
4. 构建知识库
   1. 创建 Index，导入数据。AI 搜索（混合检索，例如向量和关键词混合检索）可参考基于云搜索服务的混合检索和重排序实践。
   2. 创建 search template。由于 DSL 通过单个或者多个参数配置较为复杂，建议配置 search template，将查询配置成模版。例如下文是对云搜索文档进行混合查询的模版。建议配置 from，size 和 keyword 三个参数，这三个参数分别为起始的偏移量，单次返回大小和查询关键字。

      PUT _scripts/my_search_template
      {
        "script": {
          "lang": "mustache",
          "source": {
            "_source": {
              "excludes": "*_knn"
            },
            "from": "{{#from}}{{from}}{{/from}}{{^from}}0{{/from}}",
            "size": "{{#size}}{{size}}{{/size}}{{^size}}10{{/size}}",
            "query": {
              "hybrid": {
                "queries": [
                  {
                    "remote_neural": {
                      "summary_knn": {
                        "query_text": "{{keyword}}",
                        "k": 1000
                      }
                    }
                  },
                  {
                    "match": {
                      "summary": "{{keyword}}"
                    }
                  }
                ]
              }
            }
          }
        }
      }
      

在扣子中使用火山云搜索插件

根据应用场景的不同，本文分别介绍在扣子的智能体中、在扣子的工作流中使用云搜索插件的操作流程。

在智能体插件中使用云搜索插件

1. 在扣子创建智能体。关于创建扣子智能体的更多详细信息，可参考搭建一个 AI 助手智能体。
   

2. 在新创建的扣子智能体的技能中，搜索“火山云搜索服务”插件并添加。关于为扣子智能体添加插件的详细信息，可参考为智能体添加技能——插件。
   
   

3. 编辑智能体中火山云搜索插件的以下参数并设置参数是否可见。更多关于修改插件参数的详细信息，请参见插件参数配置。

   参数名	描述	是否可见
   endpoint	OpenSearch 的公网访问地址。需为完整 URL（如 https://host:port）。	否
   username	认证用户名。	否
   secret	用户名的密码。	否
   Index	索引名称。	否
   params	查询 URL 参数，填写 pipeline 等信息。	否
   template_id	预存搜索模板的 ID。此处输入在上文中创建的 search template 的 ID。	否
   template_param_keyword	搜索关键词（对应模板中的 {{keyword}}），长度 <8000 字符。	是
   template_param_size	每页结果数量（对应模板中的 {{size}}，1 ≤ value ≤ 200。	是
   template_param_from	分页起始偏移量（对应模板中的 {{from}}。若提供则必须≥0。	是
   template_source	直接传入的搜索模板内容（JSON 格式）。	否

   说明

   设置了参数的默认值并设置不可见后，在调用插件时，智能体会默认只使用这个设定值，可减少大模型的无效判断，从而提高插件调用效率。

   
   

4. 修改智能体的人设与回复逻辑。

   每次用户输入时，先调用火山云搜索服务的search_template工具进行搜索，用户问题作为template_param_keyword参数输入。输出结果在hits中用列表显示。
   

5. 进行查询调试。

在工作流中使用云搜索插件

1. 在扣子智能体或者资源库中创建工作流。关于在扣子智能体中创建工作流的详细信息，可参考为智能体添加技能——工作流；在资源库中创建工作流的更多详细信息，可参考创建工作流。
2. 工作流中选择火山云搜索服务插件（search_template） 工具。
   
3. 配置 search_template 的输入和输出。

4. 输出结果在 source 字段中，使用 json 格式字符串。以下为解析该字符串到文本再进行具体处理的示例。

   import json
   async def main(args: Args) -> Output:
       params = args.params
       print(params)
       # 构建输出对象
       value = ""
       for item in args.params["input"]:
            for content in json.loads(item["source"])["content"]:
               value+=content["summary"]+"\n"
       ret: Output = {"content": value}
       return ret
   

5. 进行查询调试。