Elasticsearch 推理 API 增加了开放的可定制服务

Elasticsearch2025-10-17 11:05

作者：来自 Elastic Jonathan Buttner

学习如何利用新的自定义服务集成，通过 Elasticsearch 开放推理 API 实现无缝的 REST API 模型集成。

测试 Elastic 的先进开箱即用功能。深入了解我们的示例笔记本，开始免费的云试用，或立即在本地机器上体验 Elastic。

我们很高兴地宣布 Elasticsearch 开放推理 API 的最新功能：可定制集成！任何可以通过 REST API 访问的模型都可以与新的自定义推理服务集成。无论该模型是本地托管还是在云端运行，只需一个 URL 和几行 JSON 来定义 API 格式，你现在就可以配置一个新的推理服务。自定义服务同时支持稀疏和稠密文本嵌入以及重新排序任务类型。

创建可定制推理端点

要创建一个自定义服务推理端点，我们需要先确定几个关键组件，然后才能发出 PUT 请求。确定这些组件后，我们将使用 Kibana 的控制台在不需要设置 IDE 的情况下在 Elasticsearch 中执行命令。下面的请求展示了创建请求的高级格式。

bash 复制代码 
`

1.  PUT _inference/text_embedding/inference_service_name
2.  {
3.      "service": "custom",
4.      "service_settings": {
5.          "secret_parameters": {
6.             <secrets>
7.          },
8.          "url": <url>,
9.          "headers": {
10.             <headers>
11.          },
12.          "request": <body definition>,
13.          "response": {
14.              "json_parser": {
15.                  "text_embeddings": <response path>
16.              }
17.          },
18.          "input_type": {
19.              "translation": {
20.                 <translation mapping>
21.              },
22.              "default": "query"
23.          }
24.      }
25.  }

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

以下是每个字段的简要说明

  • secret_parameters 会被安全存储，应包含任何敏感信息，如 API 密钥

  • url 定义连接外部服务的路径

  • headers 定义在后续推理请求中需要包含的 HTTP 头

  • request 定义要发送的模板请求体

  • response 定义一个类似 JSONPath 的字符串，用于指定如何从响应中提取嵌入向量

  • input_type 定义从 Elasticsearch 输入类型到第三方服务所需值的映射。在生成文本嵌入时，确保使用正确的上下文非常重要。

自定义服务的完整文档可在此处查看：
www.elastic.co/docs/api/do...

理解请求字段

在这篇博客中，我们将使用自定义服务连接到 NVIDIA NIM，这是来自 Nvidia 的新推理服务，用于 GPU 加速推理。

要确定自定义服务创建请求字段的值，我们需要了解 NVIDIA API 的请求和响应模式。

NVIDIA 支持用于生成文本嵌入的 OpenAI 兼容模式。API 参考在此说明：
docs.nvidia.com/nim/nemo-re...

我们将使用来自 NVIDIA 的此示例请求来定义我们的自定义服务推理端点：
build.nvidia.com/nvidia/nv-e...

arduino 复制代码 
`

1.  curl -X POST https://integrate.api.nvidia.com/v1/embeddings \
2.    -H "Content-Type: application/json" \
3.    -H "Authorization: Bearer $API_KEY_REQUIRED_IF_EXECUTING_OUTSIDE_NGC" \
4.    -d '{
5.      "input": ["The quick brown fox jumps over the lazy dog"],
6.      "model": "nvidia/nv-embedqa-e5-v5",
7.      "input_type": "query",
8.      "encoding_format": "float",
9.      "truncate": "NONE"
10.    }'

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

下面我们将讨论从请求中需要的部分，以及它们在自定义服务创建请求中的样子。

URL

我们用于生成文本嵌入的 URL 是 integrate.api.nvidia.com/v1/embeddin...

要在自定义服务中设置该 URL，我们将使用 url 字段。

json 复制代码 
`"url": "https://integrate.api.nvidia.com/v1/embeddings"`AI写代码

Headers

示例中的 NVIDIA 请求需要一些头信息来定义内容类型和身份验证。

要在自定义服务中包含这些信息，我们将使用 headers 和 secret_parameters 字段，如下所示：

bash 复制代码 
`

1.  "secret_parameters": {
2.      "api_key": "<your api key>"
3.  },
4.  "headers": {
5.      "Authorization": "Bearer ${api_key}",
6.      "Content-Type": "application/json"
7.  }

`AI写代码

确保将 <your api key> 替换为实际的 API 密钥，并用双引号括起来。我们稍后会讨论 ${api_key} 模板的含义。

Body

我们将使用示例请求主体中的大多数字段，来构建一个字符串，用于生成推理 API 发送给 NVIDIA 的实际请求体。

swift 复制代码 
`"request": "{\"input\": ${input}, \"model\": \"nvidia/nv-embedqa-e5-v5\", \"input_type\": ${input_type}, \"encoding_format\": \"float\", \"truncate\": \"NONE\"}"`AI写代码

我们没有在此请求中包含输入文本，因为自定义服务创建请求仅用于配置推理 API 将如何构造并发送到 NVIDIA 的请求。我们会在稍后的另一个请求中生成嵌入时再包含输入文本。我们还移除了 "input_type": "query"，并将其替换为一个模板，以便可以根据使用的请求上下文动态填充（如果我们确定它始终与查询相关，也可以直接设置为 "query"）。我们将在博客后面介绍自定义服务 input_type 字段的工作方式。

理解响应字段

要完成自定义服务定义，我们需要确定 NVIDIA API 响应中嵌入向量的路径。

以下是一个示例响应：

(docs.nvidia.com/nim/nemo-re...)

markdown 复制代码 
`

1.  {
2.    "object": "list",
3.    "data": [
4.      {
5.        "index": 0,
6.        "embedding": [
7.          0.0010356903076171875, -0.017669677734375,
8.          // ...
9.          -0.0178985595703125
10.        ],
11.        "object": "embedding"
12.      }
13.    ],
14.    "model": "nvidia/nv-embedqa-e5-v5",
15.    "usage": {
16.      "prompt_tokens": 0,
17.      "total_tokens": 0
18.    }
19.  }

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

自定义服务需要一个类似 JSONPath 的字符串 (en.wikipedia.org/wiki/JSONPa... 用来指示如何提取嵌入向量。对于此响应格式，该字符串为$.data[*].embedding[*]。

  • $ 表示对象的根

  • .（点/句点）表示查找嵌套字段

  • data[*] 表示查找名为 data 的字段，[*] 表示该字段应作为数组处理

  • embedding[*] 的处理方式与 data[*] 相同

综合起来

现在我们理解了 NVIDIA 请求和响应模式，就可以使用这些部分来构建创建请求。自定义服务的 PUT 请求将是：

swift 复制代码 
`

1.  PUT _inference/text_embedding/inference_service_name
2.  {
3.      "service": "custom",
4.      "service_settings": {
5.          "secret_parameters": {
6.              "api_key": "<your api key>"
7.          },
8.          "url": "https://integrate.api.nvidia.com/v1/embeddings",
9.          "headers": {
10.              "Authorization": "Bearer ${api_key}",
11.              "Content-Type": "application/json"
12.          },
13.          "request": "{\"input\": ${input}, \"model\": \"nvidia/nv-embedqa-e5-v5\", \"input_type\": ${input_type}, \"encoding_format\": \"float\", \"truncate\": \"NONE\"}",
14.          "response": {
15.              "json_parser": {
16.                  "text_embeddings": "$.data[*].embedding[*]"
17.              }
18.          },
19.          "input_type": {
20.              "translation": {
21.                  "search": "query",
22.                  "ingest": "passage"
23.              },
24.              "default": "query"
25.          }
26.      }
27.  }

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

模板

模板提供了一种方法，可以将值的定义推迟到发送请求到外部服务时再确定。模板是形如 ${some_name} 的字符串。它以美元符号和左花括号 ${ 开始，以右花括号 } 结束。当自定义服务构建发送给 NVIDIA 的请求时，它会将模板替换为在 secret_parameters 和 task_settings 对象中指定的值。模板通过查找花括号内的字符串，在 secret_parameters 和 task_settings 中匹配对应的值。例如，${api_key} 模板将被替换为 secret_parameters 中定义的 API 密钥。如果 API 密钥的值是 abc，Authorization 头的值将是 Bearer abc。

有几个内置模板：

  • ${input} 指的是来自后续推理请求的 input 字段的输入字符串数组

  • ${input_type} 指输入类型的转换值。NVIDIA 支持搜索请求使用 query，导入请求使用 passage。如果 Elasticsearch 尝试发送一个未在转换映射中定义的键（如 classification），将使用默认值（此处为 query）

  • ${query} 指 rerank 任务类型所需的输入查询 www.elastic.co/docs/api/do...

更多内置模板信息可见：
www.elastic.co/docs/api/do...

当我们执行创建自定义服务推理端点请求时，应得到如下响应：

swift 复制代码 
`

1.  {
2.      "inference_id": "inference_service_name",
3.      "task_type": "text_embedding",
4.      "service": "custom",
5.      "service_settings": {
6.          "similarity": "dot_product",
7.          "dimensions": 1024,
8.          "url": "https://integrate.api.nvidia.com/v1/embeddings",
9.          "headers": {
10.              "Authorization": "Bearer ${api_key}",
11.              "Content-Type": "application/json"
12.          },
13.          "request": "{\"input\": ${input}, \"model\": \"nvidia/nv-embedqa-e5-v5\", \"input_type\": ${input_type}, \"encoding_format\": \"float\", \"truncate\": \"NONE\"}",
14.          "response": {
15.              "json_parser": {
16.                  "text_embeddings": "$.data[*].embedding[*]",
17.                  "embedding_type": "float"
18.              }
19.          },
20.          "input_type": {
21.              "translation": {
22.                  "ingest": "passage",
23.                  "search": "query"
24.              },
25.              "default": "query"
26.          },
27.          "rate_limit": {
28.              "requests_per_minute": 10000
29.          },
30.          "batch_size": 10
31.      },
32.      "chunking_settings": {
33.          "strategy": "word",
34.          "max_chunk_size": 250,
35.          "overlap": 100
36.      }
37.  }

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

现在我们已经创建了自定义服务推理端点，让我们使用它生成一些文本嵌入。

bash 复制代码 
`

1.  POST _inference/text_embedding/inference_service_name
2.  {
3.      "input": ["The quick brown fox jumps over the lazy dog"]
4.  }

7.  The response is the float embedding.
8.  {
9.      "text_embedding": [
10.          {
11.              "embedding": [
12.                  -0.033294678,
13.                  -0.010848999
14.                  ...
15.              ]
16.          }
17.  }

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

总结

通过 Elastic 开放推理 API，连接新的推理提供者或定制服务现在变得简单无缝。有关如何利用自定义服务集成的更多示例，请查看：
www.elastic.co/docs/api/do...

我们持续将最先进的 AI 工具和提供者引入 Elasticsearch，希望你对我们的自定义服务集成和我们一样感到兴奋！前往 Elasticsearch Labs，探索使用 Elastic 构建生成式 AI 搜索应用。

原文：www.elastic.co/search-labs...

相关推荐
Elastic 中国社区官方博客1 天前
通过混合搜索重排序提升多语言嵌入模型的相关性
大数据·数据库·人工智能·elasticsearch·搜索引擎·ai·全文检索
liliangcsdn1 天前
如何使用elasticdump进行elasticsearch数据还原
大数据·elasticsearch·搜索引擎
lijun_xiao20091 天前
elasticsearch学习笔记-02
笔记·学习·elasticsearch
Elasticsearch1 天前
Elasticsearch：相关性在 AI 代理上下文工程中的影响
elasticsearch
一周困⁸天.2 天前
Elasticsearch+Logstash+Filebeat+Kibana部署【7.1.1版本】
大数据·elk·elasticsearch·jenkins
数据与后端架构提升之路2 天前
Elasticsearch 与 Faiss 联合驱动自动驾驶场景检索：高效语义匹配 PB 级视频数据
elasticsearch·自动驾驶·faiss
小雨的光2 天前
QuickEsView
spring boot·elasticsearch·es可视化
xiaobangsky2 天前
Elasticsearch安装使用
elasticsearch·jenkins
熙客2 天前
Elasticsearch：分布式搜索引擎数据库
分布式·elasticsearch·搜索引擎
哦你看看2 天前
Elasticsearch+Logstash+Filebeat+Kibana部署[7.17.3版本]
大数据·elasticsearch·搜索引擎
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03综合整理：pdf预览显示：你尝试预览的文件可能对你的计算机有害。如果你信任此文件以及其来源，请打开此文件以看其内容，如何解决以正常预览文件04Linux下V2Ray安装配置指南05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06npm使用国内淘宝镜像的方法07《大数据技术原理与应用》实验报告三 熟悉HBase常用操作08BongoCat - 跨平台键盘猫动画工具09NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南10GitLab 零基础入门指南：从安装到项目管理全流程