搜索请求文本向量化
View as Markdown

搜索请求文本向量化 #

Easysearch 使用搜索管道的 semantic_query_enricher 处理器，协助 semantic query，将文本转为向量。

相关指南（先读这些） #

先决条件 #

  1. 服务兼容性 需满足以下任一条件：

    • 支持与 OpenAI API 兼容的 embedding 接口
    • 支持 Ollama embedding 接口

  2. 插件要求 必须安装 Easysearch 的以下插件：

    knn
ai

  3. 数据准备 需预先完成：

创建或更新 semantic_query_enricher 处理器 #

PUT /_search/pipeline/default_model_pipeline
{
  "rewrite_processors": [
    {
      "semantic_query_enricher" : {
        "tag": "tag1",
        "description": "Sets the default embedding model",
        "url": "https://api.openai.com/v1/embeddings",
        "vendor": "openai",
        "api_key": "<api_key>",
        "default_model_id": "text-embedding-3-small",
        "vector_field_model_id": {
           "text_vector": "text-embedding-3-small"
        }
      }
    }
  ]
}

请求体字段： #

下表列出了用于创建或更新管道的请求体字段。

参数是否必填类型说明
rewrite_processors必填数组处理器列表，按顺序执行。示例中为 semantic_query_enricher。
tag可选字符串处理器标签，用于调试或日志（如 "tag1"）。
description可选字符串管道描述，用于说明用途（如 “Sets the default model ID at index and field levels”）。
url必填字符串Embedding API 的完整 URL（如 https://poloai.top/v1/embeddings）。
vendor必填字符串服务提供商标识，如 "openai"。
api_key必填字符串API 密钥，需替换为实际值（如 "sk-xxx"）。
default_model_id可选字符串全局默认模型 ID，当字段未在 vector_field_model_id 中配置时使用（如 text-embedding-3-small）。
vector_field_model_id可选对象字段级模型映射，如 { "text_vector": "text-embedding-3-small" }，优先级高于 default_model_id。

查看搜索管道 #

要查看刚创建的所有搜索管道，请使用以下请求：

GET _search/pipeline/default_model_pipeline

响应包含您在上一节中设置的管道：

{
  "default_model_pipeline": {
    "rewrite_processors": [
      {
        "semantic_query_enricher": {
          "api_key": "*************************************************vE",
          "vendor": "openai",
          "description": "Sets the default embedding model",
          "tag": "tag1",
          "vector_field_model_id": {
            "text_vector": "text-embedding-3-small"
          },
          "default_model_id": "text-embedding-3-small",
          "url": "https://api.openai.com/v1/embeddings"
        }
      }
    ]
  }
}

api_key 返回带版本前缀的加密值。GET 返回的实际配置可以原样回 PUT；上方星号仅表示省略，不可作为有效密钥回写。

使用 api_key 前，在所有安装 AI 插件的节点的 Easysearch keystore 中设置相同的 search.pipeline.encryption_key。值为32个随机字节的 Base64 编码，通过 bin/easysearch-keystore add search.pipeline.encryption_key 交互输入。该设置不能写入 easysearch.yml，修改后需要重启节点，密钥丢失将无法读取已保存的凭据。未使用 api_key 的 Ollama 配置不需要此设置。

REST、Transport 和 NodeClient 写入使用同一保护入口。滚动升级期间仍可读取旧版明文或旧密文配置，并记录迁移提示；这些历史存储在迁移前仍有原保护缺陷。待全部相关节点升级并配置相同部署密钥后，将 GET 返回的旧配置原样 PUT 即可重新加密，也可以提交新的实际 api_key。带凭据的配置更新要求全部目标节点为3.0.0或更高版本，新格式不能由旧版节点解密。GET 返回的密文应按敏感配置管理。

设置默认搜索管道 #

可以将 default_model_pipeline 设置为索引默认的搜索管道，避免每次请求提供搜索管道参数。

PUT /my-index/_settings
{
  "index.search.default_pipeline" : "default_model_pipeline"
}

使用 semantic query 进行搜索 #

GET /my-index/_search
{
  "_source": "input_text",
  "query": {
    "semantic": {
      "text_vector": {
        "query_text": "这是另一个示例文本，这次使用 POST。",
        "candidates": 100,
        "query_strategy": "HNSW"
      }
    }
  }
}

Semantic Query 参数说明 #

参数类型必填默认值说明
semanticstring是-查询类型标识，表示这是一个将文本自动转成向量的查询。
text_vectorstring是-目标向量字段名（需在 mapping 中定义为 dense_vector 类型）
query_textstring是-需要编码为向量的文本内容
candidatesinteger否100正整数。原生 HNSW 同时映射为 k 和 num_candidates，最大10000；最终命中数仍受搜索窗口限制
query_strategyenum否AUTO按字段类型选择后端。原生、已索引的 float dense_vector 使用 HNSW；显式 LSH 策略不能用于该字段
- AUTO：自动选择；HNSW：显式选择原生向量查询
- LSH_COSINE：局部敏感哈希 + 余弦相似度（model: lsh, similarity: cosine）
- LSH_L2：局部敏感哈希 + L2距离（model: lsh, similarity: l2）
- PERMUTATION_LSH：排列局部敏感哈希（model: permutation_lsh）

LSH 策略仅用于已有 knn_dense_float_vector 字段，其模型必须与策略相容。新向量索引建议使用原生 HNSW。相同默认搜索管道可通过索引别名、通配符和 data stream 选择；多个目标索引的默认管道不同（包括部分未配置）时，必须显式指定 search_pipeline。显式 _none 会跳过默认管道，Semantic 查询仍须获得模型配置。

查询结果 #

{
  "took": 3297,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4,
      "relation": "eq"
    },
    "max_score": 2,
    "hits": [
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "dewmA5gB0ulPrMzo2K-_",
        "_score": 2,
        "_source": {
          "input_text": "这是另一个示例文本，这次使用 POST。"
        }
      },
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "dt2DAZgB6WXmvHRNYksX",
        "_score": 1.540483,
        "_source": {
          "input_text": "这是另一示例文本。"
        }
      },
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "bulk_doc_2",
        "_score": 1.513369,
        "_source": {
          "input_text": "第二个批量处理的文本，指定了ID。"
        }
      },
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "dd2DAZgB6WXmvHRNYksX",
        "_score": 1.4987004,
        "_source": {
          "input_text": "第一个批量处理的文本。"
        }
      }
    ]
  }
}
©INFINI.LTD, All Rights Reserved.