文档中心

云搜索服务

插件使用指导

Remote Inference 插件使用说明

本文介绍 Remote Inference 插件相关的使用信息。

背景信息

opensearch-remote-inference 是云搜索服务团队开发的向量增强插件，提供了稠密向量（remote_embedding）、稀疏向量（sparse_encoding）、重排（remote_rerank）和多模态（remote_multimodal_embedding）4 个算子。您在执行读写数据时，可借助该插件中的对应算子将文本、图像等数据类型自动转换成稠密向量、稀疏向量等多种向量类型。opensearch-remote-inference 插件开箱即用，您无需了解数据底层的复杂算法和向量化流程，即可直接使用该插件所提供的智能化语义读写能力，极大地降低了相关功能的接入成本和复杂度。

前提条件

实例需为 OpenSearch 2.9.0 版本。创建实例的具体方法，请参见创建实例。
已安装 opensearch-remote-inference 插件。安装插件的具体方法，请参见管理系统内置插件。
说明
opensearch-remote-inference 插件持续更新中，插件中部分参数配置有版本限制，如需使用，请将插件更新至最新版本。查看插件版本的具体方法，请参见查看系统内置插件。
已在 ContextSearch 服务中查看模型服务的调用示例，并获取 url 和 model 字段的值。具体操作，请参见查看推理服务。

使用方法

多模态（remote_multimodal_embedding）

稠密向量（remote_embedding）

稀疏向量（sparse_encoding）

重排（remote_rerank）

使用场景

在执行数据读写操作时，您可以通过 remote_multimodal_embedding 算子将指定的文本和图像字段，自动转换为多模态向量数据，并依据操作需求执行多模态向量的写入或查询任务。

使用示例

执行如下代码创建 ingest pipeline。

说明

下述代码中各参数说明如下：

description：设置 ingest pipeline 的描述信息。
processors：指定 remote_multimodal_embedding 算子的配置参数。关于 remote_multimodal_embedding 算子中各参数的详细说明，请参见写入 ingest pipeline 配置参数。

PUT _ingest/pipeline/multimodal_embedding
{
  "description": "A text/image embedding pipeline",
  "processors": [
    {
      "remote_multimodal_embedding": {
        "remote_config": {
          "method": "POST",
            "url": "https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal",
            "params": {},
            "headers": {
              "Content-Type": "application/json",
              "Authorization": "Bearer {API KEY}"    // API KEY从方舟平台上获取
            },
            "advance_request_body": {
              "model": "doubao-embedding-vision-241215"
            }
        },
        "field_map": {
          "text": "title",
          "image": "summary_image",
          "embedding": "abstract_knn"
        }
      }
    }
  ]
}

执行如下代码创建索引。

说明

火山引擎云搜索服务已将 DiskANN 算法引入到 OpenSearch 中，实现更大数据规模下更低成本的向量存储和检索能力。推荐您在创建索引时使用 DiskANN 向量引擎，具体使用方法，请参见使用 DiskANN 向量引擎。

PUT multimodel_index 
{
    "mappings": {
      "properties": {
        "title": {
          "type": "text"
        },
        "summary_image": {
          "type": "keyword"
        },
        "abstract_knn": {
          "type": "knn_vector",
          "dimension": 2048,
          "method": {
            "name": "diskann",
            "space_type": "cosinesimil",
            "engine": "diskann",
            "parameters": {
              "R": 32,
              "L": 32
            }
          }
        }
      }
    },
    "settings": {
      "index": {
        "refresh_interval": "10s",
        "number_of_shards": "1",
        "knn": "true",
        "number_of_replicas": "1"
      }
    }
}

执行如下命令写入示例数据。

PUT multimodel_index/_doc/1?pipeline=multimodal_embedding
{
  "title": "天很蓝，海很深",
  "summary_image": "https://ark-project.tos-cn-beijing.volces.com/images/view.jpeg"
}

POST multimodel_index/_doc/2?pipeline=multimodal_embedding
{
  "summary_image": "https://ark-project.tos-cn-beijing.volces.com/images/view.jpeg"
}

POST multimodel_index/_doc/3?pipeline=multimodal_embedding
{
  "title": "test_text"
}

执行如下代码创建 search pipeline。

说明

下述代码中各参数说明如下：

description：设置 search pipeline 的描述信息。
request_processors：指定 remote_multimodal_embedding 算子的配置参数。关于 remote_multimodal_embedding 算子中各参数的详细说明，请参见查询 search pipeline 配置参数。

PUT _search/pipeline/multimodel_search_embedding
{
  "description": "text embedding pipeline for remote inference",
  "request_processors": [
    {
      "remote_multimodal_embedding": {
        "remote_config": {
          "method": "POST",
          "url": "https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal",
          "params": {},
          "headers": {
            "Content-Type": "application/json",
            "Authorization": "Bearer {API KEY}"    // API KEY从方舟平台获取
          },
          "advance_request_body": {
            "model": "doubao-embedding-vision-241215"
          }
        }
      }
    }
  ]
}

执行如下命令查询数据。

GET multimodel_index/_search?search_pipeline=multimodel_search_embedding
{
  "size": 10, 
  "_source": {
    "includes": ["title", "summary_image"]
  },
  "query": {
    "remote_multimodal_neural": {
      "abstract_knn": {                  
        "query_text": "blue",    
        "query_image": "https://ark-project.tos-cn-beijing.volces.com/images/view.jpeg",
        "k": 10
      }
    }
  }
}

使用场景

在执行数据读写操作时，您只要输入文本内容，实例会通过 remote_embedding 算子自动将该文本转化为稠密向量数据，并依据操作需求执行稠密向量的写入或查询任务。

使用示例

执行如下代码创建 ingest pipeline。

说明

下述代码中各参数说明如下：

description：设置 ingest pipeline 的描述信息。
processors：指定 remote_embedding 算子的配置参数。关于 remote_embedding 算子中各参数的详细说明，请参见写入 ingest pipeline 配置参数。

PUT _ingest/pipeline/remote_embedding
{
  "description": "bge embedding 1024 dim",
  "processors": [
    {
      "remote_embedding": {
        "remote_config": {
          "method": "POST",
          "url": "xxx",
          "params": {},
          "headers": {
            "Content-Type": "application/json"
          },
          "advance_request_body": {
            "model": "zzz"
          }
        },
        "field_map": {
          "content": "content_knn"
        }
      }
    }
  ]
}

执行如下代码创建索引。

说明

PUT remote_sementic
{
  "settings": {
    "index": {
      "knn": true
    }
  },
  "mappings": {
    "properties": {
      "content_knn": {
        "type": "knn_vector",
        "dimension": 1024,
        "method": {            
            "name": "diskann",
            "engine": "diskann",
            "space_type": "cosinesimil",
            "parameters": {
              "R": 32,
              "L": 32
            }
        }
      },
      "content": {
        "type": "text"
      }
    }
  }
}

执行如下命令写入示例数据。

POST /_bulk?pipeline=remote_embedding&refresh
{ "index": { "_index": "remote_sementic", "_id": 1 } }
{ "content": "Carson City is the capital city of the American state of Nevada."}
{ "index": { "_index": "remote_sementic", "_id": 2  } }
{ "content": "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan."}
{ "index": { "_index": "remote_sementic", "_id": 3  } }
{ "content": "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district."}
{ "index": { "_index": "remote_sementic", "_id": 4  } }
{ "content": "Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."}
{ "index": { "_index": "remote_sementic", "_id": 5  } }
{ "content": "Hello world."}

执行如下代码创建 search pipeline。

说明

下述代码中各参数说明如下：

description：设置 search pipeline 的描述信息。
processors：指定 remote_embedding 算子的配置参数。关于 remote_embedding 算子中各参数的详细说明，请参见查询 search pipeline 配置参数。

PUT _search/pipeline/remote_embedding
{
  "description": "Pipeline for embedding query AND reranking with a cross-encoder",
  "request_processors": [
    {
      "remote_embedding": {
        "remote_config": {
          "method": "POST",
          "url": "xxx",
          "params": {},
          "headers": {
            "Content-Type": "application/json"
          },
          "advance_request_body": {
            "model": "zzz"
          }
        }
      }
    }
  ]
}

执行如下命令查询数据。

GET remote_sementic/_search?search_pipeline=remote_embedding
{
  "_source": "content", 
  "query": {
    "remote_neural": {
      "content_knn": {
        "query_text": "What is the capital of the United States?",
        "k": 10
      }
    }
  }
}

使用场景

在执行数据读写操作时，您只要输入文本内容，实例会通过 sparse_encoding 算子自动将该文本转化为稀疏向量数据，并依据操作需求执行稀疏向量的写入或查询任务。

使用示例

执行如下代码创建 ingest pipeline。

说明

下述代码中各参数说明如下：

description：设置 ingest pipeline 的描述信息。
processors：指定 sparse_encoding 算子的配置参数。关于 sparse_encoding 算子中各参数的详细说明，请参见写入 ingest pipeline 配置参数。

PUT _ingest/pipeline/sparse_encoding
{
  "description": "sparse_encoding_demo"
  "processors": [
    {
      "sparse_encoding": {
        "remote_config": {
          "method": "POST",
          "url": "xxx",
          "params": {},
          "headers": {
            "Content-Type": "application/json"
          },
          "advance_request_body": {
            "model": "zzz"
          }
        },
        "field_map": {
          "content": "content_sparse"
        }
      }
    }
  ]
}

执行如下代码创建索引。

说明

PUT remote_sementic
{
  "settings": {
    "index": {
      "knn": true
    }
  },
  "mappings": {
    "properties": {
      "content_knn": {
        "type": "knn_vector",
        "dimension": 1024,
        "method": {            
            "name": "diskann",
            "engine": "diskann",
            "space_type": "cosinesimil",
            "parameters": {
              "R": 32,
              "L": 32
            }
        }
      },
      "content_sparse": {
        "type": "rank_features"
      }
    }
  }
}

执行如下命令写入示例数据。

POST /_bulk?pipeline=sparse_encoding&refresh
{ "index": { "_index": "remote_sementic", "_id": 1 } }
{ "content": "Carson City is the capital city of the American state of Nevada."}
{ "index": { "_index": "remote_sementic", "_id": 2  } }
{ "content": "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan."}
{ "index": { "_index": "remote_sementic", "_id": 3  } }
{ "content": "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district."}
{ "index": { "_index": "remote_sementic", "_id": 4  } }
{ "content": "Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."}
{ "index": { "_index": "remote_sementic", "_id": 5  } }
{ "content": "Hello world."}

执行如下代码创建 search pipeline。

说明

下述代码中各参数说明如下：

description：设置 search pipeline 的描述信息。
processors：指定 sparse_encoding 算子的配置参数。关于 sparse_encoding 算子中各参数的详细说明，请参见查询 search pipeline 配置参数。

PUT _search/pipeline/sparse_encoding
{
  "description": "Pipeline for embedding query AND reranking with a cross-encoder",
  "request_processors": [
    {
      "sparse_encoding": {
        "remote_config": {
          "method": "POST",
          "url": "xxx",
          "params": {},
          "headers": {
            "Content-Type": "application/json"
          },
          "advance_request_body": {
            "model": "zzz"
          }
        }
      }
    }
  ]
}

执行如下命令查询数据。

GET remote_sementic/_search?search_pipeline=sparse_encoding
{
  "_source": "content", 
  "query": {
    "remote_neural_sparse": {
      "content_sparse": {
        "query_text": "What is the capital of the United States?"
      }
    }
  }
}

使用场景

当您在进行查询并输入文本数据时，实例会通过 remote_rerank 算子将初步排序的数据，传入指定模型中进行重排序后再返回，从而得到更符合需求的查询结果。

使用示例

执行如下代码创建索引。

PUT rerank-test
{
  "mappings": {
    "properties": {
      "text_representation": {
        "type": "text"
      },
      "text_representation2": {
        "type": "text"
      }
    }
  }
}

执行如下命令写入示例数据。

POST rerank-test/_doc/1
{
  "text_representation": "Jacques loves fish. Fish make Jacques happy",
  "text_representation2": "He also loves noodle."
}

POST rerank-test/_doc/2
{
  "text_representation": "Fish like to eat plankton",
  "text_representation2": "Bob loves fish very much."
}

执行如下代码创建 search pipeline。

说明

下述代码中各参数说明如下：

description：设置 search pipeline 的描述信息。
response_processors：指定 search pipeline 中 remote_rerank 算子的配置参数。关于 remote_rerank 算子中各参数的详细说明，请参见查询 search pipeline 配置参数。

PUT _search/pipeline/rerank-mlos-pipeline
{
  "description": "Pipeline for reranking with a cross encoder",
  "response_processors": [
    {
      "remote_rerank": {
        "ml_opensearch": {
          "remote_config": {
            "method": "POST",
            "url": "xxx",
            "params": {
              "token": "token"
            },
            "headers": {
              "content_type": "application/json",
              "Authorization": "yyy"
            },
            "advance_request_body": {
              "model": "zzz"
            }
          }
        },
        "context": {
          "document_fields": [
            "text_representation2", 
            "text_representation",
            "_score"
          ]
        }
      }
    }
  ]
}

执行如下命令查询数据。

说明

下述代码中各参数说明如下：

query：用户输入的查询问句。
ext：指定查询语句中 remote_rerank 算子的配置参数。关于查询语句中 remote_rerank 算子中各参数的详细说明，请参见查询语句配置参数。

GET rerank-test/_search?search_pipeline=rerank-mlos-pipeline
{
  "query": {
    "match_all": {}
  },
  "ext": {
    "remote_rerank": {
      "query_context": {
        "query_text": "Who loves fish?"
      },
      "appending_contexts": [
        "I like fish.",
        "He likes fish too."
      ],
      "rerank_prompt": " {{text_representation}} \n {{text_representation2}} \n  {{_score}} Ending."
    }
  }
}

配置参数

稠密向量（`remote_embedding`）

写入 ingest pipeline 配置参数

说明

当您在创建写入 ingest pipeline 中使用稠密向量（remote_embedding）算子时，可以根据业务需要在算子的 processors.remote_embedding 字段中配置下表中的参数。

参数	类型	是否必填	参数说明	支持的插件版本
remote_config	Object	是	远端服务的配置信息。	请参见各参数支持的插件版本。
field_map	JSONMap	是	指定输入的文本字段，与经模型转化后生成的向量字段间的映射关系。例如，您可以通过如下代码在文本字段和向量字段间建立映射关系。 `{ // title字段映射到title_knn字段 "title": "title_knn", // chunks为nested字段 // chunks中的text字段映射到text_knn字段 "chunks": { "text": "text_knn" } }`	所有版本。
batch_size	Integer	否	请求远端服务的单次请求中携带的数据条数，默认为 1。	2.9.0.0-24.10.31 及以上版本。
sliced_norm_dim	Integer	否	指定压缩后的维度。	2.9.0.0-25.1.0 及以上版本。
max_tokens	Integer	否	指定最大 token，超过将自动截断，对截断后的结果进行向量化。	2.9.0.0-25.7.0 及以上版本。

查询 search pipeline 配置参数

说明

当您在查询 search pipeline 中使用稠密向量（remote_embedding）算子时，可以根据业务需要在算子的 processors.remote_embedding 字段中配置下表中的参数。

参数	类型	是否必填	参数说明	支持的插件版本
remote_config	Object	是	远端服务的配置信息。	请参见各参数支持的插件版本。
sliced_norm_dim	Integer	否	指定压缩后的维度。	2.9.0.0-25.1.0 及以上版本。
support_fields	List	否	指定支持的字段，可用通配符，示例： `{ "support_fields": ["field1", "field2*"] }`	2.9.0.0-25.7.0 及以上版本。

稀疏向量（`sparse_encoding`）

写入 ingest pipeline 配置参数

说明

当您在创建写入 ingest pipeline 中使用稀疏向量（sparse_encoding）算子时，可以根据业务需要在算子的 processors.sparse_encoding 字段中配置下表中的参数。

参数	类型	是否必填	参数说明	支持的插件版本
remote_config	Object	是	远端服务的配置信息。	请参见各参数支持的插件版本。
field_map	JSONMap	是	指定输入的文本字段，与经模型转化后生成的向量字段间的映射关系。例如，您可以通过如下代码在文本字段和向量字段间建立映射关系。 `{ // title字段映射到title_sparse字段 "title": "title_sparse", // chunks为nested字段 // chunks中的text字段映射到title_sparse字段 "chunks": { "text": "title_sparse" } }`	所有版本。
batch_size	Integer	否	请求远端服务的单次请求中携带的数据条数，默认为 1。	2.9.0.0-24.10.31 及以上版本。
sliced_norm_dim	Integer	否	指定压缩后的维度。	2.9.0.0-25.1.0 及以上版本。

查询 search pipeline 配置参数

说明

您可以在查询 search pipeline 中使用稀疏向量（sparse_encoding）算子时，根据业务需要在算子的 processors.sparse_encoding 字段中配置下表中的参数。

参数	类型	是否必填	参数说明	支持的插件版本
remote_config	Object	是	远端服务的配置信息。	请参见各参数支持的插件版本。
sliced_norm_dim	Integer	否	指定压缩后的维度。	2.9.0.0-25.1.0 及以上版本。
support_fields	List	否	指定支持的字段，可用通配符，示例： `{ "support_fields": ["field1", "field2*"] }`	2.9.0.0-25.7.0 及以上版本。

多模态（`remote_multimodal_embedding`）

写入 ingest pipeline 配置参数

说明

当您在创建写入 ingest pipeline 中使用多模态（remote_multimodal_embedding）算子时，可以根据业务需要在算子的 processors.remote_multimodal_embedding 字段中配置下表中的参数。

参数	类型	是否必填	参数说明	支持的插件版本
remote_config	Object	是	远端服务的配置信息。	请参见各参数支持的插件版本。
field_map	JSONMap	是	指定输入的文本字段，与经模型转化后生成的向量字段间的映射关系。例如，您可以通过如下代码，将文本字段（ `title`）和图片字段（`summary_image`）转换后的向量数据存储到向量字段（`abstract_knn`）中。 `{ "text": "title", "image": "summary_image", "embedding": "abstract_knn" }`	2.9.0.0-25.3.0 及以上版本。

查询 search pipeline 配置参数

说明

当您在查询 search pipeline 中使用多模态（remote_multimodal_embedding）算子时，可以根据业务需要在算子的 request_processors.remote_multimodal_embedding 字段中配置下表中的参数。

参数	类型	是否必填	参数说明	支持的插件版本
remote_config	Object	是	远端服务的配置信息。	请参见各参数支持的插件版本。

重排（`remote_rerank`）

查询 search pipeline 配置参数

说明

当您在创建查询 search pipeline 中使用重排（remote_rerank）算子时，可以根据业务需要在算子的 response_processors.remote_rerank 字段中配置下表中的参数。

参数	类型	是否必填	参数说明	支持的插件版本
ml_opensearch.remote_config	Object	是	远端服务的配置信息。	请参见各参数支持的插件版本。
context	Object	否	索引信息。	请参见各参数支持的插件版本。

查询语句配置参数

说明

当您在查询语句中使用重排（remote_rerank）算子时，可以根据业务需要在算子的 ext.remote_rerank 字段中配置下表中的参数。

参数	类型	是否必填	参数说明	支持的插件版本
query_context	Object	是	远端服务的配置信息。	请参见各参数支持的插件版本。
appending_contexts	String[]	否	从指定的字段中获取数据，并将这些数据和 OpenSearch 中查询的结果一起发送给远端服务进行重排序，以得出更符合需求的最终结果。例如，您可以在 `appending_contexts` 中传入 `["I like fish.", "He likes fish too."]`信息，这两个文本内容会和 OpenSearch 查询结果一同用于重排序。	2.9.0.0-24.10.31 及以上版本。
rerank_prompt	String	否	从查询结果的指定字段中先获取相关数据并进行格式化调整，再将格式化后的结果发送到远程的服务端进行重排序。例如，您可以在 `rerank_prompt` 中传入 `This is {{text1}} \n That is {{text2}} Ending.` 信息，实例会从先查询结果指定的字段中获取相应的值来替换 `text1` 和 `text2`，并将格式化后的结果进行重排序。	2.9.0.0-25.1.0 及以上版本。
keep_previous_score	Boolean	否	是否保留在重排之前的分数，返回示例： `{ "_score": "0.7439", "fields": { "previous_score": [ 1.0 ] } }`	2.9.0.0-25.7.0 及以上版本。
min_score	String	否	指定重排返回的分数阈值，只有大于该分数，才会返回。	2.9.0.0-25.7.0 及以上版本。

云搜索服务

背景信息 #

前提条件 #

使用方法 #

使用场景 #

使用示例 #

配置参数 #

稠密向量（remote_embedding） #

写入 ingest pipeline 配置参数

查询 search pipeline 配置参数

稀疏向量（sparse_encoding） #

写入 ingest pipeline 配置参数

查询 search pipeline 配置参数

多模态（remote_multimodal_embedding） #

写入 ingest pipeline 配置参数

查询 search pipeline 配置参数

重排（remote_rerank） #

查询 search pipeline 配置参数

查询语句配置参数

更多案例 #

背景信息

前提条件

使用方法

使用场景

使用示例

配置参数

稠密向量（`remote_embedding`）

稀疏向量（`sparse_encoding`）

多模态（`remote_multimodal_embedding`）

重排（`remote_rerank`）

更多案例