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...

相关推荐
麦麦麦造20 小时前
小小 Postgres，何以替代 Redis、MongoDB 甚至 ES？
redis·mongodb·elasticsearch·postgresql
Zzz 小生20 小时前
Claude Code学习笔记(四)-助你快速搭建首个Python项目
大数据·数据库·elasticsearch
斯普信专业组1 天前
使用Reindex迁移Elasticsearch集群数据详解（下）
大数据·elasticsearch
JAVA学习通1 天前
OJ竞赛平台----C端题目列表
java·开发语言·jvm·vue.js·elasticsearch
Elasticsearch2 天前
根据用户行为数据中的判断列表在 Elasticsearch 中训练 LTR 模型
elasticsearch
失散132 天前
分布式专题——45 ElasticSearch基础数据管理详解
java·分布式·elasticsearch·架构
今天头发还在吗2 天前
解决 Git 推送冲突：使用 Rebase 整合远程更改
大数据·git·elasticsearch
橘子在努力2 天前
【橘子ES】如何本地调试ES源码
elasticsearch·搜索引擎
柳贯一(逆流河版)2 天前
ElasticSearch 实战：全文检索与数据聚合分析的完整指南
大数据·elasticsearch·全文检索
热门推荐
01GitHub 镜像站点02BongoCat - 跨平台键盘猫动画工具03两千字总结：Codex 国内如何安装和使用的教程，以及如何设置中文回答04UV安装并设置国内源05Linux下V2Ray安装配置指南06GitLab 零基础入门指南：从安装到项目管理全流程07在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）08windows找不到gpedit.msc（本地组策略编辑器）0946个Nano-banana 精选提示词，持续更新中10UV 工具安装与国内镜像源配置指南