文本向量化处理器 #

需要 AI 插件和 KNN 插件

text_embedding 处理器在文档写入时自动调用外部 Embedding 模型服务，将文本字段转换为向量并存储到指定的向量字段中，实现"写入即向量化"。该处理器是构建语义搜索和混合搜索的基础组件。

语法 #

{
  "text_embedding": {
    "text_field": "content",
    "vector_field": "content_vector",
    "url": "https://api.openai.com/v1/embeddings",
    "vendor": "openai",
    "model_id": "text-embedding-3-small",
    "api_key": "sk-xxxxxxxx"
  }
}

配置参数 #

参数	是否必填	描述
`text_field`	必填	包含待向量化文本的源字段
`vector_field`	必填	存储生成的向量的目标字段。该字段应映射为 `knn_vector` 类型
`url`	必填	Embedding 模型服务的 API 端点 URL
`vendor`	必填	模型提供商标识。`openai` 表示 OpenAI 兼容接口，其他值（如 `ollama`）使用 Ollama 兼容接口
`model_id`	必填	使用的 Embedding 模型 ID
`api_key`	可选	API 密钥（使用 OpenAI 兼容接口时通常必填）。存储时会自动加密
`dimensions`	可选	期望的向量维度。未指定时使用模型默认维度
`ignore_missing`	可选	为 `true` 时，源字段缺失则跳过处理。默认为 `false`
`batch_size`	可选	批量处理时每次 API 调用包含的文档数。默认为 `1`
`description`	可选	处理器的简要描述
`if`	可选	处理器运行的条件
`ignore_failure`	可选	为 `true` 时，处理器出错后忽略继续执行。默认为 `false`
`on_failure`	可选	处理器失败时运行的处理器列表
`tag`	可选	处理器的标识标签

支持的模型服务 #

接口类型	`vendor` 值	认证方式	典型服务
OpenAI 兼容	`openai`	`Authorization: Bearer <api_key>` 请求头	OpenAI、阿里云 DashScope、Azure OpenAI、DeepSeek 等
Ollama 兼容	其他任意值（如 `ollama`）	无认证	Ollama 本地部署

如何使用 #

步骤 1：创建向量索引 #

首先创建包含 KNN 向量字段的索引：

PUT /my_index
{
  "settings": {
    "index.knn": true
  },
  "mappings": {
    "properties": {
      "content": {
        "type": "text"
      },
      "content_vector": {
        "type": "knn_vector",
        "dimension": 1536
      }
    }
  }
}

步骤 2：创建管道 #

使用 OpenAI 兼容接口创建向量化管道：

PUT /_ingest/pipeline/embedding_pipeline
{
  "description": "写入时自动向量化",
  "processors": [
    {
      "text_embedding": {
        "text_field": "content",
        "vector_field": "content_vector",
        "url": "https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings",
        "vendor": "openai",
        "model_id": "text-embedding-v3",
        "api_key": "sk-xxxxxxxx"
      }
    }
  ]
}

步骤 3：写入数据 #

PUT /my_index/_doc/1?pipeline=embedding_pipeline
{
  "content": "Easysearch 是一款高性能的搜索引擎"
}

处理器会自动将 content 字段的文本发送到 Embedding 服务，并将返回的向量存储到 content_vector 字段。

步骤 4：验证结果 #

GET /my_index/_doc/1

{
  "_source": {
    "content": "Easysearch 是一款高性能的搜索引擎",
    "content_vector": [0.0123, -0.0456, 0.0789, ...]
  }
}

使用 Ollama 本地模型 #

PUT /_ingest/pipeline/ollama_embedding_pipeline
{
  "description": "使用 Ollama 本地模型向量化",
  "processors": [
    {
      "text_embedding": {
        "text_field": "content",
        "vector_field": "content_vector",
        "url": "http://localhost:11434/api/embed",
        "vendor": "ollama",
        "model_id": "nomic-embed-text"
      }
    }
  ]
}

批量写入 #

使用 batch_size 提升批量写入时的向量化效率：

PUT /_ingest/pipeline/batch_embedding_pipeline
{
  "description": "批量向量化",
  "processors": [
    {
      "text_embedding": {
        "text_field": "content",
        "vector_field": "content_vector",
        "url": "https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings",
        "vendor": "openai",
        "model_id": "text-embedding-v3",
        "api_key": "sk-xxxxxxxx",
        "batch_size": 10
      }
    }
  ]
}

注意事项 #

如果 vector_field 已存在于文档中，处理器会抛出异常（设置 ignore_failure: true 可跳过）
API 密钥在管道配置中会被自动加密存储（形如 ENCRYPTED_VALUE...infinilabs），查询管道定义时看到的是加密后的值
批量写入时，文本为空或缺失的文档会被静默跳过，不会发送到 Embedding 服务
vector_field 的维度必须与所用模型的输出维度一致
向量化依赖外部服务，写入速度会受到网络延迟和模型服务吞吐量的影响