---
title: "创建搜索管道"
date: 2026-01-30
lastmod: 2026-01-30
description: "介绍如何在 Easysearch 中创建或更新搜索管道（Search Pipeline），用于自定义搜索请求和响应的处理流程。"
tags: ["搜索管道", "搜索", "AI"]
summary: "搜索管道（Search Pipeline）是 Easysearch 中用于自定义搜索请求和响应处理的机制。通过定义一系列处理器（processors），可以在搜索执行前修改请求、在返回结果前处理响应。
API #  PUT /_search/pipeline/{id} API 的作用 #  创建新的搜索管道或更新已存在的管道。搜索管道的主要功能包括：
 请求处理：在搜索执行前修改搜索请求（查询重写、过滤增强等） 响应处理：在返回搜索结果前处理结果（字段重命名、结果增强等） 结果重排序：对初步合并的搜索结果进行二次排序 API 密钥加密：自动加密语义查询增强器中的 API 密钥  API 的参数 #  路由参数 #     参数 类型 是否必需 描述     id string 必需 管道的唯一标识符    查询字符串参数 #     参数 类型 是否必需 默认值 描述     master_timeout time 可选 30s 等待主节点响应的超时时间   timeout time 可选 30s 操作超时时间   pretty boolean 可选 - 格式化 JSON 输出    请求体参数 #  请求体需要包含管道配置，基本结构如下："
---


搜索管道（Search Pipeline）是 Easysearch 中用于自定义搜索请求和响应处理的机制。通过定义一系列处理器（processors），可以在搜索执行前修改请求、在返回结果前处理响应。

## API

```
PUT /_search/pipeline/{id}
```

## API 的作用

创建新的搜索管道或更新已存在的管道。搜索管道的主要功能包括：

- **请求处理**：在搜索执行前修改搜索请求（查询重写、过滤增强等）
- **响应处理**：在返回搜索结果前处理结果（字段重命名、结果增强等）
- **结果重排序**：对初步合并的搜索结果进行二次排序
- **API 密钥加密**：自动加密语义查询增强器中的 API 密钥

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `id` | string | 必需 | 管道的唯一标识符 |

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `master_timeout` | time | 可选 | 30s | 等待主节点响应的超时时间 |
| `timeout` | time | 可选 | 30s | 操作超时时间 |
| `pretty` | boolean | 可选 | - | 格式化 JSON 输出 |

### 请求体参数

请求体需要包含管道配置，基本结构如下：

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `config` | object | 必需 | 管道配置对象 |
| `config.request_processors` | array | 可选 | 请求处理器列表 |
| `config.response_processors` | array | 可选 | 响应处理器列表 |

## 请求体结构

```json
{
  "config": {
    "request_processors": [
      {
        "type": "processor_type",
        "tag": "optional_tag",
        "description": "optional_description",
        "ignore_failure": false,
        "processor_specific_config": {}
      }
    ],
    "response_processors": [
      {
        "type": "processor_type",
        "tag": "optional_tag",
        "description": "optional_description",
        "ignore_failure": false,
        "processor_specific_config": {}
      }
    ]
  }
}
```

## 常用处理器类型

### 请求处理器 (request_processors)

| 处理器 | 功能 |
|--------|------|
| `filter_query` | 添加查询过滤条件 |
| `script` | 使用脚本修改搜索请求 |
| `semantic_query_enricher` | 语义查询增强（AI 功能） |

### 响应处理器 (response_processors)

| 处理器 | 功能 |
|--------|------|
| `rename_field` | 重命名字段 |
| `script` | 使用脚本处理搜索结果 |
| `rerank` | 结果重排序 |

## 请求示例

### 基础搜索管道

```json
PUT /_search/pipeline/my-pipeline
{
  "config": {
    "request_processors": [
      {
        "type": "filter_query",
        "tag": "public_filter",
        "description": "只返回公开数据",
        "query": {
          "term": {
            "visibility": "public"
          }
        }
      }
    ]
  }
}
```

### 语义查询增强管道（AI 功能）

```json
PUT /_search/pipeline/semantic-pipeline
{
  "config": {
    "request_processors": [
      {
        "type": "semantic_query_enricher",
        "tag": "semantic_enrichment",
        "description": "使用语义增强查询",
        "model_name": "text-embedding-ada-002",
        "api_key": "your-api-key-here",
        "text_field": "content",
        "embedding_field": "content_embedding"
      }
    ]
  }
}
```

**重要说明**：`api_key` 会被自动加密存储为 `ENCRYPTED_VALUE...infinilabs` 格式。

### 完整配置示例

```json
PUT /_search/pipeline/full-pipeline
{
  "config": {
    "request_processors": [
      {
        "type": "filter_query",
        "tag": "filter_deleted",
        "query": {
          "term": {
            "deleted": false
          }
        },
        "ignore_failure": true
      },
      {
        "type": "script",
        "tag": "add_timestamp",
        "script": {
          "source": "ctx._source.query.bool.must.push({range: {@timestamp: {gte: 'now-7d'}}})",
          "lang": "painless"
        }
      }
    ],
    "response_processors": [
      {
        "type": "rename_field",
        "tag": "rename_fields",
        "field_mappings": [
          {
            "old_field": "title",
            "new_field": "headline"
          },
          {
            "old_field": "body",
            "new_field": "content"
          }
        ]
      },
      {
        "type": "rerank",
        "tag": "rerank_results",
        "rerank_model": "my-rerank-model",
        "top_n": 10
      }
    ]
  }
}
```

## 响应示例

### 成功响应

```json
{
  "acknowledged": true
}
```

### 错误响应 - 管道定义无效

```json
{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "Processor type [unknown_processor] is not installed"
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "Processor type [unknown_processor] is not installed"
  },
  "status": 400
}
```

## 使用搜索管道

创建管道后，可以通过以下方式使用：

### 方式 1：搜索时指定管道

```bash
GET /my-index/_search?search_pipeline=my-pipeline
{
  "query": {
    "match": { "message": "error" }
  }
}
```

### 方式 2：在索引设置中指定默认管道

```json
PUT /my-index
{
  "settings": {
    "index.search.default_pipeline": "my-pipeline"
  }
}
```

### 方式 3：临时使用管道（覆盖默认）

```bash
GET /my-index/_search?search_pipeline=temp-pipeline
{
  "query": {
    "match_all": {}
  }
}
```

### 方式 4：禁用管道

```bash
GET /my-index/_search?search_pipeline=_none
{
  "query": {
    "match_all": {}
  }
}
```

## 处理器执行顺序

1. **请求处理器**：按照定义顺序依次执行
2. **搜索执行**：使用处理后的请求执行搜索
3. **响应处理器**：按照定义顺序依次处理搜索结果

如果某个处理器失败且设置了 `ignore_failure: true`，则跳过该处理器继续执行。

## 安全特性

### API 密钥加密

对于包含 API 密钥的处理器（如 `semantic_query_enricher`），Easysearch 会自动加密 API 密钥：

```json
{
  "type": "semantic_query_enricher",
  "api_key": "sk-1234567890abcdef"
}
```

存储后自动变为：

```json
{
  "type": "semantic_query_enricher",
  "api_key": "ENCRYPTED_VALUE:aBc123...infinilabs"
}
```

## 注意事项

1. **API 密钥加密**：包含 API 密钥的处理器会自动加密存储
2. **管道覆盖**：搜索参数中的管道会覆盖索引默认管道
3. **处理器顺序**：处理器按数组顺序执行，请合理排列
4. **测试管道**：建议先在测试环境验证管道逻辑
5. **性能影响**：复杂的处理器会影响搜索性能

## 相关文档

- [查询所有搜索管道](./get-all-search-pipelines.md)
- [查询指定搜索管道](./get-specific-search-pipeline.md)
- [删除搜索管道](./delete-search-pipeline.md)
- [搜索文档](./search-document.md)