Elasticsearch Service ES Inferen

本文介绍如何通过 Elasticsearch Inference API 调用智能搜索开发的原子模型服务，将原子服务直接集成到 ES 的检索与数据处理流程中。每个模型服务都有默认限频，如有更多需求，请 联系我们。
概述
Elasticsearch 提供 Inference API 用于对接外部推理服务。智能搜索开发的原子模型服务兼容 OpenAI 协议，因此可以通过 Elasticsearch 的 openai 和 custom 两种服务类型创建推理端点（Inference Endpoint），之后即可在 ES 内部像使用本地模型一样调用这些服务。
通过 ES Inference API 调用的优势：
创建一次推理端点后可反复复用，无需在业务代码中管理 API Key 和请求格式。
可与 semantic_text 字段类型、Ingest Pipeline、text_similarity_reranker 检索器等 ES 原生能力直接组合使用。
向量化、重排序等操作在 ES 内部完成，减少一次网络往返。
本文涵盖的服务如下：
服务
Inference 任务类型
服务类型
说明
﻿文本向量化﻿
text_embedding
openai
custom
将文本转换为稠密向量
﻿重排序﻿
rerank
custom
基于 Cross-Encoder 模型对候选文档重排
﻿大模型精排﻿
rerank / completion
custom
基于 LLM 对文档做 0-4 级相关性评分
﻿搜索改写﻿
completion
custom
将单个 query 改写为多个检索 query
﻿多轮改写﻿
completion
custom
结合对话历史消解指代，补全为独立语句
﻿意图识别﻿
completion
custom
判断用户意图并路由到候选项
﻿LLM 对话﻿
completion
openai
custom
大语言模型文本生成
说明：
文本向量化、重排序、精排同时支持 OpenAI 协议调用，详情请参见 OpenAI 协议调用。
搜索改写、多轮改写、意图识别、LLM 对话推荐通过 ES Inference API 调用。
搜索改写、多轮改写、意图识别三项能力合称查询分析，配合向量化、重排序和 LLM 对话，通常组合使用于 RAG 检索链路：
用户问题
  → 多轮改写（消解"它""那个"等指代词，补全为独立问句）
  → 意图识别（判断是闲聊还是检索，多知识库时决定检索哪个库）
  → 搜索改写（拆成多个检索角度，多路召回）
  → 向量/文本混合检索
  → 重排序（Cross-Encoder 粗排）
  → 精排（LLM 细粒度评分与过滤）
  → LLM 生成回答
前提条件
已开通原子服务。
已购买 ES AI 搜索增强版 9.1.3 及以上版本实例。
已获取原子服务 API Key。API Key 可在 腾讯云 ES 控制台 的 资源管理 > API Key 页面创建和管理。
通用说明
服务地址
项目
说明
原子服务 Base URL
形如 https://bj.aisearch.tencentelasticsearch.com，在 资源管理 > API Key 页面获取
ES 集群地址
在控制台实例详情页查看，形如 http://es-xxxxxxxx.vpc.tencentelasticsearch.com:9200
custom 服务配置说明
创建推理端点的请求格式为：
PUT _inference/<task_type>/<inference_id>
service 固定为 custom，service_settings 中的核心字段如下：
字段
必填
说明
url
是
原子服务的接口地址
headers
是
HTTP 请求头，用于携带认证信息和 Content-Type
request
是
请求体模板。需为 JSON 字符串，通过占位符注入运行时参数
response.json_parser
是
响应解析规则，使用 JSONPath 表达式从响应中提取结果
secret_parameters
是
密钥参数，如 api_key。配置后 ES 会加密存储，查询端点信息时不返回明文
batch_size
否
semantic_text 场景下单次请求的最大输入条数，默认 10
不同任务类型的 json_parser 字段要求不同：
task_type
json_parser 必需字段
text_embedding
text_embeddings
rerank
relevance_score（reranked_index、document_text 可选）
completion
completion_result
请求模板占位符
request、headers、url 中可使用 ${} 形式的占位符，由 ES 在调用时替换为实际值：
占位符
说明
${input}
推理请求中 input 字段的输入字符串数组
${query}
rerank 任务的查询文本
${top_n}
rerank 任务中返回前 N 条结果的数量
${return_documents}
rerank 任务中是否返回文档原文
${api_key}
引用 secret_parameters 中定义的 api_key
注意：
占位符不能被引号包裹。正确写法是 "input": ${input}，错误写法是 "input": "${input}"。若占位符在 secret_parameters 或 task_settings 中找不到对应定义，创建端点时会直接报错。
复杂参数的传递方式
ES Inference API 的 task_settings.parameters 不支持数组和对象类型，因此多轮改写的 messages、意图识别的 candidates 这类结构化参数无法通过 ES 模板变量直接传递。
﻿
原子服务针对这一限制做了适配：这些接口的 query 字段支持接收 JSON 字符串，将复杂参数打包后通过 ${input} 一次性传入。
﻿
例如多轮改写，input 传入的是这样一个 JSON 字符串：
{"query":"它的性能怎么样","messages":[{"role":"user","content":"腾讯云ES是什么"}]}
服务端会自动识别 query 字段是普通文本还是 JSON 字符串，并做相应解析。涉及此机制的接口会在对应章节中说明。
双解析模式
搜索改写、多轮改写、意图识别、精排四个接口的响应中都包含一个 completion_result 字段，其值为完整响应的 JSON 字符串。这使得每个接口都支持两种解析方式：
模式
json_parser 配置
返回内容
适用场景
核心结果
指向具体业务字段，如 $.queries
仅业务结果
在 ES 搜索管道中直接消费
完整响应
$.completion_result
完整 JSON 字符串（含 model、usage 等）
需要 token 用量、置信度等完整信息
建议按需注册不同的 inference_id，例如 aisearch-query-rewrite（核心结果）与 aisearch-query-rewrite-full（完整响应）。
文本向量化（Embedding）
文本向量化服务将文本转换为向量表示，用于语义检索、相似度计算等场景。
支持的模型
模型名称：
bge-base-zh-v1.5
bge-large-zh-v1.5
bge-m3
Conan-embedding-v1
KaLM-embedding-multilingual-mini-v1
Qwen3-Embedding-0.6B
创建推理端点
有两种方式，第一种直接 openai 协议：
Kibana Dev Tools
PUT _inference/text_embedding/tencent-embedding
{
    "service": "openai",
    "service_settings": {
    "api_key": "sk-****",
    "model_id": "bge-m3",
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/embeddings"
  }
}
采用 custom：
Kibana Dev Tools
PUT _inference/text_embedding/tencent-embedding
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/embeddings",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"bge-m3\\", \\"input\\": ${input}}",
    "response": {
      "json_parser": {
        "text_embeddings": "$.data[*].embedding[*]"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
注意：
若需切换模型，将 request 中的 model 字段替换为目标模型名称即可。建议为不同模型创建不同的 inference_id，便于区分和管理。
调用推理
单次调用：
Kibana Dev Tools
POST _inference/text_embedding/tencent-embedding
{
  "input": "你好，这是一个测试"
}
批量调用：
Kibana Dev Tools
POST _inference/text_embedding/tencent-embedding
{
  "input": ["人工智能正在改变世界", "深度学习是机器学习的一个子领域"]
}
响应示例
{
  "text_embedding": [
    {
      "embedding": [0.0123, -0.0456, ...]
    }
  ]
}
使用举例
创建推理端点后，可将其绑定到 semantic_text 字段，由 ES 在写入和查询时自动完成向量化，无需业务侧手动调用向量化接口。
PUT my-index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": "tencent-embedding"
      }
    }
  }
}
写入文档：
POST my-index/_doc
{
  "content": "Elasticsearch 是一个分布式搜索引擎"
}
语义检索：
GET my-index/_search
{
  "query": {
    "semantic": {
      "field": "content",
      "query": "分布式搜索"
    }
  }
}
重排序（Rerank）
重排序服务包含两种类型，一种是基于 Cross-Encoder 模型，一种是 LLM-Based 的精排（下文中单独说明的 PostRerank），对候选文档相对于查询的相关性进行重新排序，提升检索结果的精确度。
说明：重排序（Rerank）与精排（PostRerank）是检索链路中两个不同阶段的能力。重排序基于 Cross-Encoder 模型，速度快、成本低，适合对较多候选文档做粗排；精排基于 LLM，理解能力更强、成本更高，适合对粗排后的少量文档做细粒度评分与过滤。典型用法是两者串联：检索 → 重排序 → 精排。
支持的模型
模型名称：
bge-reranker-large
bge-reranker-v2-m3
创建推理端点
Kibana Dev Tools
PUT _inference/rerank/tencent-rerank
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/rerank",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"bge-reranker-v2-m3\\", \\"query\\": ${query}, \\"documents\\": ${input}}",
    "response": {
      "json_parser": {
        "reranked_index": "$.results[*].index",
        "relevance_score": "$.results[*].relevance_score"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
﻿
调用推理
Kibana Dev Tools
POST _inference/rerank/tencent-rerank
{
  "query": "什么是人工智能",
  "input": [
    "人工智能是计算机科学的一个分支",
    "今天天气很好",
    "机器学习是人工智能的核心技术"
  ]
}
响应示例
{
  "rerank": [
    {
      "index": 0,
      "relevance_score": 0.9856
    },
    {
      "index": 2,
      "relevance_score": 0.8234
    },
    {
      "index": 1,
      "relevance_score": 0.0123
    }
  ]
}
使用举例
通过 text_similarity_reranker 检索器，可在一次查询中完成召回与重排序：
GET my-index/_search
{
  "retriever": {
    "text_similarity_reranker": {
      "retriever": {
        "standard": {
          "query": {
            "match": {
              "content": "什么是人工智能"
            }
          }
        }
      },
      "field": "content",
      "inference_id": "tencent-rerank",
      "inference_text": "什么是人工智能",
      "rank_window_size": 20
    }
  }
}
大模型精排（Post Rerank）
精排服务基于 LLM 对 query 和文档进行细粒度的相关性评估，输出 0~4 的离散等级评分。与基于 Cross-Encoder 的重排序相比，精排的语义理解能力更强，可识别文档与问题之间更复杂的关联关系，适合在重排序之后对少量文档做最终筛选。
支持的模型
模型名称：ima-post-rerank
评分标准
分数
等级
含义
4
核心答案
文档直接、完整地回答了用户问题
3
核心论据/方法
文档提供了构建答案所需的核心方法、关键论据或关键范例
2
背景知识
文档提供了有用的背景信息或相关上下文，能丰富答案但非核心
1
提及但无价值
文档提及了问题关键词，但信息空洞或与问题无关
0
完全无关
文档内容与用户问题的领域完全不相关
实际使用时，通常设定一个分数阈值来过滤低相关文档。推荐阈值为 2.0，即保留"背景知识"及以上等级的文档。若希望送入 LLM 的上下文更精炼，可将阈值提高到 3.0。
文档格式说明
精排接口的 documents 字段支持三种格式：
格式
示例
适用场景
纯字符串
"腾讯云ES支持自动扩缩容"
无标题信息，ES rerank 任务默认形式
JSON 字符串
"{\\"content\\":\\"...\\",\\"title\\":\\"弹性伸缩\\"}"
需保留标题，ES rerank 任务下的推荐形式
对象
{"content": "...", "title": "弹性伸缩"}
直接通过 OpenAI 协议调用时使用
ES rerank 任务的 ${input} 是字符串数组，因此在 ES 中使用时对应前两种格式。文档标题往往包含重要的语义信息，建议采用 JSON 字符串格式以保留 title。单次请求最多传入 64 个文档
创建推理端点
精排支持两种注册方式，对应双解析模式。
方式一：rerank 任务类型（推荐）
由 ES 自动解析评分与索引，可直接用于 text_similarity_reranker 检索器。
Kibana Dev Tools
PUT _inference/rerank/aisearch-post-rerank
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/post-rerank",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"ima-post-rerank\\", \\"query\\": ${query}, \\"documents\\": ${input}}",
    "response": {
      "json_parser": {
        "relevance_score": "$.results[*].relevance_score",
        "reranked_index": "$.results[*].index"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
方式二：completion 任务类型（获取完整响应）
返回含 model、usage 的完整 JSON 字符串。两者代码差异不大，以 Kibana Dev Tools 为例：
Kibana Dev Tools
PUT _inference/completion/aisearch-post-rerank-full
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/post-rerank",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"ima-post-rerank\\", \\"query\\": \\"placeholder\\", \\"documents\\": [${input}]}",
    "response": {
      "json_parser": {
        "completion_result": "$.completion_result"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
说明：
"query": "placeholder" 是占位符。因为 completion 任务类型不支持 ${query} 占位符，实际 query 值需打包到 input JSON 字符串中。
调用推理
纯字符串格式（不带标题）：
Kibana Dev Tools
POST _inference/rerank/aisearch-post-rerank
{
  "query": "腾讯云ES的性能优势",
  "input": [
    "腾讯云ES支持自动扩缩容",
    "腾讯云ES基于最新内核，查询性能提升30%"
  ]
}
JSON 字符串格式（保留标题）：
Kibana Dev Tools
POST _inference/rerank/aisearch-post-rerank
{
  "query": "腾讯云ES的性能优势",
  "input": [
    "{\\"content\\":\\"腾讯云ES支持自动扩缩容\\",\\"title\\":\\"弹性伸缩\\"}",
    "{\\"content\\":\\"腾讯云ES基于最新内核，查询性能提升30%\\",\\"title\\":\\"性能优化\\"}"
  ]
}
响应示例
方式一（rerank 任务类型）：按评分从高到低排序。
{
  "rerank": [
    {
      "index": 1,
      "relevance_score": 3
    },
    {
      "index": 0,
      "relevance_score": 1
    }
  ]
}
方式二（completion 任务类型）：返回完整响应的 JSON 字符串。
{
  "completion": [
    {
      "result": "{\\"object\\":\\"post_rerank\\",\\"model\\":\\"ima-post-rerank\\",\\"results\\":[{\\"index\\":1,\\"relevance_score\\":3},{\\"index\\":0,\\"relevance_score\\":1}],\\"usage\\":{\\"prompt_tokens\\":50,\\"completion_tokens\\":10,\\"total_tokens\\":60}}"
    }
  ]
}
搜索改写（Query Rewrite）
搜索改写将用户的单个 query 改写为多个语义相近但表述不同的检索 query，用于多路召回，提升检索覆盖率。适用于用户提问较简短、单一表述难以覆盖全部相关文档的场景。
例如“如何使用腾讯云 ES”会被改写为：“腾讯云 ES 使用方法”、“腾讯云 ES 基本操作指南”、“腾讯云 ES 使用步骤详解”三个检索 query，分别召回后合并结果。
支持的模型
模型名称：ima-rewrite
创建推理端点
搜索改写只需传入单个 query 字符串，${input} 可直接使用，无需打包 JSON。
方式一：仅提取核心结果
json_parser 指向 $.queries，ES 会为每个改写后的 query 返回一个 result 元素。
Kibana Dev Tools
PUT _inference/completion/aisearch-query-rewrite
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/query/rewrite",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"ima-rewrite\\", \\"query\\": ${input}}",
    "response": {
      "json_parser": {
        "completion_result": "$.queries"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
方式二：获取完整响应
与上述代码差异不大，以 Kibana Dev Tools 为例。
Kibana Dev Tools
PUT _inference/completion/aisearch-query-rewrite-full
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/query/rewrite",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"ima-rewrite\\", \\"query\\": ${input}}",
    "response": {
      "json_parser": {
        "completion_result": "$.completion_result"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
调用推理
Kibana Dev Tools
POST _inference/completion/aisearch-query-rewrite
{
  "input": "腾讯云ES的性能优势"
}
响应示例
方式一（核心结果）：每个改写后的 query 对应一个 result 元素。
{
  "completion": [
    {
      "result": "腾讯云Elasticsearch性能优势"
    },
    {
      "result": "腾讯云ES性能怎么样"
    }
  ]
}
方式二（完整响应）：单个 result，值为完整响应的 JSON 字符串。
{
  "completion": [
    {
      "result": "{\\"object\\":\\"query.rewrite\\",\\"model\\":\\"ima-rewrite\\",\\"queries\\":[\\"腾讯云Elasticsearch性能优势\\",\\"腾讯云ES性能怎么样\\"],\\"usage\\":{\\"prompt_tokens\\":0,\\"completion_tokens\\":0,\\"total_tokens\\":0}}"
    }
  ]
}
多轮改写（Multi Round Rewrite）
多轮改写结合用户的历史对话上下文，对当前 query 进行指代消解和语义补全，使其成为一个独立完整的检索语句。
例如在“腾讯云 ES 是什么”之后追问“它的性能怎么样”，多轮改写会将其补全为“腾讯云 ES 的性能怎么样”，避免直接用“它的性能怎么样”检索导致召回失败。
支持的模型
模型名称：ima-rewrite-multiround
input 参数格式
多轮改写需要传入对话历史（messages 数组），而 ES 的模板变量不支持数组类型。因此需将 query 和 messages 打包为 JSON 字符串，通过 ${input} 一次性传入。
﻿
input JSON 字符串的内部字段：
字段
类型
必填
说明
query
string
是
当前轮用户问题
messages
object[]
否
历史对话，每个元素含 role（user / assistant）和 content
打包后的形态：
{"query":"它的性能怎么样","messages":[{"role":"user","content":"腾讯云ES是什么"},{"role":"assistant","content":"腾讯云ES是腾讯云提供的Elasticsearch服务"}]}
创建推理端点
方式一：仅提取核心结果
json_parser 指向 $.content，返回改写后的 query 文本。
Kibana Dev Tools
PUT _inference/completion/aisearch-multi-round-rewrite
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/query/multi-round-rewrite",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"ima-rewrite-multiround\\", \\"query\\": ${input}}",
    "response": {
      "json_parser": {
        "completion_result": "$.content"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
方式二：获取完整响应
PUT _inference/completion/aisearch-multi-round-rewrite-full
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/query/multi-round-rewrite",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"ima-rewrite-multiround\\", \\"query\\": ${input}}",
    "response": {
      "json_parser": {
        "completion_result": "$.completion_result"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
调用推理
Kibana Dev Tools
POST _inference/completion/aisearch-multi-round-rewrite
{
  "input": "{\\"query\\":\\"它的性能怎么样\\",\\"messages\\":[{\\"role\\":\\"user\\",\\"content\\":\\"腾讯云ES是什么\\"},{\\"role\\":\\"assistant\\",\\"content\\":\\"腾讯云ES是腾讯云提供的Elasticsearch服务\\"}]}"
}
响应示例
方式一（核心结果）：
{
  "completion": [
    {
      "result": "腾讯云ES的性能怎么样"
    }
  ]
}
方式二（完整响应）：
{
  "completion": [
    {
      "result": "{\\"object\\":\\"query.multi_round_rewrite\\",\\"model\\":\\"ima-rewrite-multiround\\",\\"content\\":\\"腾讯云ES的性能怎么样\\",\\"usage\\":{\\"prompt_tokens\\":118,\\"completion_tokens\\":25,\\"total_tokens\\":143}}"
    }
  ]
}
意图识别（Intent Recognition）
意图识别根据用户 query 和一组候选项描述，判断用户意图并路由到最匹配的候选项。典型应用场景：
闲聊与检索二分类（单知识库）：识别为闲聊时跳过知识库检索，直接由 LLM 回答，避免无意义的检索开销。
多知识库路由（多知识库）：从多个知识库候选中选出最匹配的一个，只检索该库，提升准确率并降低成本。
支持的模型
模型名称：youtu-intent
input 参数格式
意图识别需要传入候选项列表（candidates）和可选的对话历史（messages），两者都是数组类型。因此需将 query、candidates、messages 打包为 JSON 字符串，通过 ${input} 一次性传入。
input JSON 字符串的内部字段：
字段
类型
必填
说明
query
string
是
用户问题
candidates
object[]
是
候选项列表
messages
object[]
否
历史对话上下文
candidates 元素结构：
字段
类型
必填
说明
id
string
是
候选项唯一标识，如知识库 ID kb-001，或内置标识 chat
name
string
是
候选项名称，如"腾讯财报知识库""闲聊"
description
string
否
候选项描述，供模型理解该意图的含义范围。强烈建议填写，描述质量直接影响识别准确率
messages 元素结构：
字段
类型
说明
role
string
消息角色：user / assistant / intention
content
string
消息内容。role 为 intention 时，内容为该轮识别出的意图 ID
说明：
intention 是意图识别特有的角色类型，用于告知模型历史轮次的意图判断结果，有助于在多轮对话中保持意图连续性。
创建推理端点
方式一：仅提取核心结果
json_parser 指向 $.selected_candidates，返回命中的候选项信息。
Kibana Dev Tools
PUT _inference/completion/aisearch-intent-recognition
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/intent/recognition",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"youtu-intent\\", \\"query\\": ${input}}",
    "response": {
      "json_parser": {
        "completion_result": "$.selected_candidates[*].id"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
方式二：获取完整响应
包含 confidence 置信度和每个候选项的 score，便于业务侧做阈值判断。
PUT _inference/completion/aisearch-intent-recognition-full
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/intent/recognition",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"youtu-intent\\", \\"query\\": ${input}}",
    "response": {
      "json_parser": {
        "completion_result": "$.completion_result"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
说明：
注册推理端点时，ES 会自动发送一个验证请求（内容为简单字符串，不含 candidates）。服务端已做兜底处理，此时返回空结果而不报错，注册可正常完成。
调用推理
仅传入候选项：
Kibana Dev Tools
POST _inference/completion/aisearch-intent-recognition
{
  "input": "{\\"query\\":\\"帮我查一下ES集群的监控数据\\",\\"candidates\\":[{\\"id\\":\\"knowledge_search\\",\\"name\\":\\"知识搜索\\",\\"description\\":\\"用户想搜索知识库中的信息\\"},{\\"id\\":\\"task_execution\\",\\"name\\":\\"任务执行\\",\\"description\\":\\"用户想执行一个具体操作\\"},{\\"id\\":\\"chitchat\\",\\"name\\":\\"闲聊\\",\\"description\\":\\"用户想闲聊或打招呼\\"}]}"
}
带对话历史（含 intention 角色）：
Kibana Dev Tools
POST _inference/completion/aisearch-intent-recognition
{
  "input": "{\\"query\\":\\"那性能监控呢\\",\\"candidates\\":[{\\"id\\":\\"knowledge_search\\",\\"name\\":\\"知识搜索\\",\\"description\\":\\"用户想搜索知识库中的信息\\"},{\\"id\\":\\"chitchat\\",\\"name\\":\\"闲聊\\",\\"description\\":\\"用户想闲聊或打招呼\\"}],\\"messages\\":[{\\"role\\":\\"user\\",\\"content\\":\\"帮我查一下ES集群的监控数据\\"},{\\"role\\":\\"assistant\\",\\"content\\":\\"好的，我来帮你查看ES集群的监控数据\\"},{\\"role\\":\\"intention\\",\\"content\\":\\"knowledge_search\\"}]}"
}
响应示例
方式一（核心结果）：
{
  "completion": [
    {
      "result": "knowledge_search"
    }
  ]
}
方式二（完整响应）：
{
  "completion": [
    {
      "result": "{\\"object\\":\\"intent.recognition\\",\\"model\\":\\"youtu-intent\\",\\"confidence\\":1,\\"selected_candidates\\":[{\\"id\\":\\"knowledge_search\\",\\"score\\":1}],\\"usage\\":{\\"prompt_tokens\\":1180,\\"completion_tokens\\":14,\\"total_tokens\\":1194}}"
    }
  ]
}
使用建议
候选项描述要具体：description 是模型判断的主要依据。"包含腾讯 2020-2024 年季度/年度财报数据，涵盖营收、利润等财务指标"这类具体描述，效果远好于"财报相关"。
务必包含闲聊候选项：否则"你好""谢谢"这类输入会被强行归类到某个知识库，触发无意义的检索。
利用置信度兜底：置信度较低说明模型无法明确区分，此时建议回退到检索全部知识库，而非采纳一个不确定的路由结果。
多轮场景传入 intention 历史：将上一轮的意图 ID 以 intention 角色写入 messages，有助于模型在追问场景下保持意图连续。
LLM 对话（Completion）
LLM 对话服务提供大语言模型文本生成能力。
支持的模型
模型名称：
deepseek-r1
deepseek-v3
创建推理端点
LLM 也支持两种协议方式，直接用 openai 协议：
Kibana Dev Tools
{
  "service": "openai",
  "service_settings": {
    "api_key": "sk-****",
    "model_id": "deepseek-v3",
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/chat/completions"
  }
}
使用 custom：
Kibana Dev Tools
PUT _inference/completion/tencent-llm
{
  "service": "custom",
  "service_settings": {
    "url": "https://bj.aisearch.tencentelasticsearch.com/v1/chat/completions",
    "headers": {
      "Authorization": "Bearer ${api_key}",
      "Content-Type": "application/json"
    },
    "request": "{\\"model\\": \\"deepseek-v3\\", \\"stream\\": false, \\"messages\\": [{\\"role\\": \\"user\\", \\"content\\": ${input}}]}",
    "response": {
      "json_parser": {
        "completion_result": "$.choices[*].message.content"
      }
    },
    "secret_parameters": {
      "api_key": "sk-****"
    }
  }
}
注意：
request 模板中的 stream 必须为 false。ES Inference API 的 completion 任务通过 JSONPath 解析完整响应体，无法处理 SSE 流式返回。
调用推理
Kibana Dev Tools
POST _inference/completion/tencent-llm
{
  "input": "用一句话介绍 Elasticsearch"
}
响应示例
{
  "completion": [
    {
      "result": "Elasticsearch 是一个基于 Lucene 的分布式搜索与分析引擎，擅长处理海量数据的近实时检索。"
    }
  ]
}
推理端点管理
查看推理端点
Kibana Dev Tools
GET _inference/text_embedding/tencent-embedding
查看全部推理端点：
GET _inference/_all
删除推理端点
Kibana Dev Tools
DELETE _inference/text_embedding/tencent-embedding
若该端点已被 semantic_text 字段或 Ingest Pipeline 引用，删除操作会被拒绝。如需强制删除，添加 force 参数：
DELETE _inference/text_embedding/tencent-embedding?force=true
注意：
强制删除后，引用该端点的写入和查询操作将失败，请谨慎操作。建议先用 dry_run 参数确认引用情况。
推理端点速查表
服务
推荐 inference_id
task_type
接口路径
json_parser 核心字段
文本向量化
tencent-embedding
text_embedding
/v1/embeddings
text_embeddings: $.data[*].embedding[*]
重排序
tencent-rerank
rerank
/v1/rerank
relevance_score: $.results[*].relevance_score
精排
aisearch-post-rerank
rerank
/v1/post-rerank
relevance_score: $.results[*].relevance_score
搜索改写
aisearch-query-rewrite
completion
/v1/query/rewrite
completion_result: $.queries
多轮改写
aisearch-multi-round-rewrite
completion
/v1/query/multi-round-rewrite
completion_result: $.content
意图识别
aisearch-intent-recognition
completion
/v1/intent/recognition
completion_result: $.selected_candidates
LLM 对话
tencent-llm
completion
/v1/chat/completions
completion_result: $.choices[*].message.content
注意事项
模型与端点一一对应：request 模板中的 model 字段在创建端点时即固定，调用时无法动态切换。如需使用多个模型，请分别创建推理端点。
占位符不加引号：${input}、${query} 等占位符在 request 模板中不能被引号包裹，否则会被当作字符串字面量而非注入点。
复杂参数需打包为 JSON 字符串：多轮改写的 messages、意图识别的 candidates 无法通过 ES 模板变量直接传递，需打包为 JSON 字符串通过 ${input} 传入。
查询分析模型的超时：若在同步检索链路中串联查询分析多个能力，请评估总耗时是否满足业务要求，并为每个环节设计降级策略（如模型超时时跳过该环节，使用原始 query 继续检索）。
限流：原子服务对每个模型设有默认限流。在 semantic_text 批量写入场景下，建议通过 batch_size 控制单次请求的输入条数，避免触发限流。
计费：通过 ES Inference API 调用原子服务会产生原子模型服务费用，按资源包或按量计费。查询分析与精排均基于 LLM，会消耗 token，在检索链路中全量开启会显著增加成本，建议按业务价值选择性启用。
相关文档
﻿OpenAI 协议调用：通过 OpenAI 兼容协议调用文本向量化、重排序、精排、多模态向量化服务。
﻿资源管理 > API Key：API Key 的创建与管理。

task_type	json_parser 必需字段
`text_embedding`	`text_embeddings`
`rerank`	`relevance_score`（`reranked_index`、`document_text` 可选）
`completion`	`completion_result`

占位符	说明
`${input}`	推理请求中 `input` 字段的输入字符串数组
`${query}`	`rerank` 任务的查询文本
`${top_n}`	`rerank` 任务中返回前 N 条结果的数量
`${return_documents}`	`rerank` 任务中是否返回文档原文
`${api_key}`	引用 `secret_parameters` 中定义的 `api_key`

服务	推荐 inference_id	task_type	接口路径	json_parser 核心字段
文本向量化	`tencent-embedding`	`text_embedding`	`/v1/embeddings`	`text_embeddings: $.data[].embedding[]`
重排序	`tencent-rerank`	`rerank`	`/v1/rerank`	`relevance_score: $.results[*].relevance_score`
精排	`aisearch-post-rerank`	`rerank`	`/v1/post-rerank`	`relevance_score: $.results[*].relevance_score`
搜索改写	`aisearch-query-rewrite`	`completion`	`/v1/query/rewrite`	`completion_result: $.queries`
多轮改写	`aisearch-multi-round-rewrite`	`completion`	`/v1/query/multi-round-rewrite`	`completion_result: $.content`
意图识别	`aisearch-intent-recognition`	`completion`	`/v1/intent/recognition`	`completion_result: $.selected_candidates`
LLM 对话	`tencent-llm`	`completion`	`/v1/chat/completions`	`completion_result: $.choices[*].message.content`

服务	Inference 任务类型	服务类型	说明
文本向量化	`text_embedding`	`openai` `custom`	将文本转换为稠密向量
重排序	`rerank`	`custom`	基于 Cross-Encoder 模型对候选文档重排
大模型精排	`rerank` / `completion`	`custom`	基于 LLM 对文档做 0-4 级相关性评分
搜索改写	`completion`	`custom`	将单个 query 改写为多个检索 query
多轮改写	`completion`	`custom`	结合对话历史消解指代，补全为独立语句
意图识别	`completion`	`custom`	判断用户意图并路由到候选项
LLM 对话	`completion`	`openai` `custom`	大语言模型文本生成

项目	说明
原子服务 Base URL	形如 `https://bj.aisearch.tencentelasticsearch.com`，在资源管理 > API Key 页面获取
ES 集群地址	在控制台实例详情页查看，形如 `http://es-xxxxxxxx.vpc.tencentelasticsearch.com:9200`

字段	必填	说明
`url`	是	原子服务的接口地址
`headers`	是	HTTP 请求头，用于携带认证信息和 Content-Type
`request`	是	请求体模板。需为 JSON 字符串，通过占位符注入运行时参数
`response.json_parser`	是	响应解析规则，使用 JSONPath 表达式从响应中提取结果
`secret_parameters`	是	密钥参数，如 `api_key`。配置后 ES 会加密存储，查询端点信息时不返回明文
`batch_size`	否	`semantic_text` 场景下单次请求的最大输入条数，默认 10

模式	json_parser 配置	返回内容	适用场景
核心结果	指向具体业务字段，如 `$.queries`	仅业务结果	在 ES 搜索管道中直接消费
完整响应	`$.completion_result`	完整 JSON 字符串（含 model、usage 等）	需要 token 用量、置信度等完整信息

分数	等级	含义
4	核心答案	文档直接、完整地回答了用户问题
3	核心论据/方法	文档提供了构建答案所需的核心方法、关键论据或关键范例
2	背景知识	文档提供了有用的背景信息或相关上下文，能丰富答案但非核心
1	提及但无价值	文档提及了问题关键词，但信息空洞或与问题无关
0	完全无关	文档内容与用户问题的领域完全不相关

格式	示例	适用场景
纯字符串	`"腾讯云ES支持自动扩缩容"`	无标题信息，ES `rerank` 任务默认形式
JSON 字符串	`"{\\"content\\":\\"...\\",\\"title\\":\\"弹性伸缩\\"}"`	需保留标题，ES `rerank` 任务下的推荐形式
对象	`{"content": "...", "title": "弹性伸缩"}`	直接通过 OpenAI 协议调用时使用

字段	类型	必填	说明
`query`	string	是	当前轮用户问题
`messages`	object[]	否	历史对话，每个元素含 `role`（`user` / `assistant`）和 `content`

ES Inference API 调用原子服务

本页目录：

概述

前提条件

通用说明

服务地址

custom 服务配置说明

请求模板占位符

复杂参数的传递方式

双解析模式

文本向量化（Embedding）

支持的模型

创建推理端点

调用推理

响应示例

使用举例

重排序（Rerank）

支持的模型

创建推理端点

调用推理

响应示例

使用举例

大模型精排（Post Rerank）

支持的模型

评分标准

文档格式说明

创建推理端点

方式一：rerank 任务类型（推荐）

方式二：completion 任务类型（获取完整响应）

调用推理

响应示例

搜索改写（Query Rewrite）

支持的模型

创建推理端点

方式一：仅提取核心结果

方式二：获取完整响应

调用推理

响应示例

多轮改写（Multi Round Rewrite）

支持的模型

input 参数格式

创建推理端点

方式一：仅提取核心结果

方式二：获取完整响应

调用推理

响应示例

意图识别（Intent Recognition）

支持的模型

input 参数格式

创建推理端点

方式一：仅提取核心结果

方式二：获取完整响应

调用推理

响应示例

使用建议

LLM 对话（Completion）

支持的模型

创建推理端点

调用推理

响应示例

推理端点管理

查看推理端点

删除推理端点

推理端点速查表

注意事项

相关文档