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

Elastic 中国社区官方博客2025-10-18 16:33

作者：来自 Elastic Jonathan Buttner

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

更多阅读：Elasticsearch：创建一个定制的 DeepSeek 嵌入推理端点

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

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

创建可定制推理端点

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

复制代码 
PUT _inference/text_embedding/inference_service_name
{
    "service": "custom",
    "service_settings": {
        "secret_parameters": {
           <secrets>
        },
        "url": <url>,
        "headers": {
           <headers>
        },
        "request": <body definition>,
        "response": {
            "json_parser": {
                "text_embeddings": <response path>
            }
        },
        "input_type": {
            "translation": {
               <translation mapping>
            },
            "default": "query"
        }
    }
}

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

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

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

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

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

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

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

自定义服务的完整文档可在此处查看：
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put-custom

理解请求字段

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

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

NVIDIA 支持用于生成文本嵌入的 OpenAI 兼容模式。API 参考在此说明：
https://docs.nvidia.com/nim/nemo-retriever/text-embedding/latest/reference.html

我们将使用来自 NVIDIA 的此示例请求来定义我们的自定义服务推理端点：
https://build.nvidia.com/nvidia/nv-embedqa-e5-v5?snippet_tab=Shell

复制代码 
curl -X POST https://integrate.api.nvidia.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY_REQUIRED_IF_EXECUTING_OUTSIDE_NGC" \
  -d '{
    "input": ["The quick brown fox jumps over the lazy dog"],
    "model": "nvidia/nv-embedqa-e5-v5",
    "input_type": "query",
    "encoding_format": "float",
    "truncate": "NONE"
  }'

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

URL

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

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

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

Headers

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

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

复制代码 
"secret_parameters": {
    "api_key": "<your api key>"
},
"headers": {
    "Authorization": "Bearer ${api_key}",
    "Content-Type": "application/json"
}

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

Body

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

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

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

理解响应字段

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

以下是一个示例响应：

(https://docs.nvidia.com/nim/nemo-retriever/text-embedding/latest/reference.html#generate-embeddings)

复制代码 
{
  "object": "list",
  "data": [
    {
      "index": 0,
      "embedding": [
        0.0010356903076171875, -0.017669677734375,
        // ...
        -0.0178985595703125
      ],
      "object": "embedding"
    }
  ],
  "model": "nvidia/nv-embedqa-e5-v5",
  "usage": {
    "prompt_tokens": 0,
    "total_tokens": 0
  }
}

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

  • $ 表示对象的根

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

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

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

综合起来

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

复制代码 
PUT _inference/text_embedding/inference_service_name
{
    "service": "custom",
    "service_settings": {
        "secret_parameters": {
            "api_key": "<your api key>"
        },
        "url": "https://integrate.api.nvidia.com/v1/embeddings",
        "headers": {
            "Authorization": "Bearer ${api_key}",
            "Content-Type": "application/json"
        },
        "request": "{\"input\": ${input}, \"model\": \"nvidia/nv-embedqa-e5-v5\", \"input_type\": ${input_type}, \"encoding_format\": \"float\", \"truncate\": \"NONE\"}",
        "response": {
            "json_parser": {
                "text_embeddings": "$.data[*].embedding[*]"
            }
        },
        "input_type": {
            "translation": {
                "search": "query",
                "ingest": "passage"
            },
            "default": "query"
        }
    }
}

模板

模板提供了一种方法，可以将值的定义推迟到发送请求到外部服务时再确定。模板是形如 ${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 任务类型所需的输入查询 https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-rerank

更多内置模板信息可见：
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put-custom

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

复制代码 
{
    "inference_id": "inference_service_name",
    "task_type": "text_embedding",
    "service": "custom",
    "service_settings": {
        "similarity": "dot_product",
        "dimensions": 1024,
        "url": "https://integrate.api.nvidia.com/v1/embeddings",
        "headers": {
            "Authorization": "Bearer ${api_key}",
            "Content-Type": "application/json"
        },
        "request": "{\"input\": ${input}, \"model\": \"nvidia/nv-embedqa-e5-v5\", \"input_type\": ${input_type}, \"encoding_format\": \"float\", \"truncate\": \"NONE\"}",
        "response": {
            "json_parser": {
                "text_embeddings": "$.data[*].embedding[*]",
                "embedding_type": "float"
            }
        },
        "input_type": {
            "translation": {
                "ingest": "passage",
                "search": "query"
            },
            "default": "query"
        },
        "rate_limit": {
            "requests_per_minute": 10000
        },
        "batch_size": 10
    },
    "chunking_settings": {
        "strategy": "word",
        "max_chunk_size": 250,
        "overlap": 100
    }
}

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

复制代码 
POST _inference/text_embedding/inference_service_name
{
    "input": ["The quick brown fox jumps over the lazy dog"]
}


The response is the float embedding.
{
    "text_embedding": [
        {
            "embedding": [
                -0.033294678,
                -0.010848999
                ...
            ]
        }
}

总结

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

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

原文：https://www.elastic.co/search-labs/blog/elasticsearch-inference-api-custom-rest-integration

相关推荐
TGITCIC1 天前
金融RAG落地之痛：不在模型，而在数据结构
人工智能·ai大模型·ai agent·ai智能体·开源大模型·金融ai·金融rag
lpfasd1231 天前
git-团队协作基础
chrome·git·elasticsearch
安审若无1 天前
图数据库neoj4安装部署使用
linux·运维·数据库
fenglllle1 天前
mybatis-plus SQL 注入漏洞导致版本升级引发的问题
数据库·sql·mybatis
呆呆小金人1 天前
SQL字段对齐：性能优化与数据准确的关键
大数据·数据仓库·sql·数据库开发·etl·etl工程师
learning-striving1 天前
SQL server创建数据表
数据库·sql·mysql·sql server
Yeats_Liao1 天前
时序数据库系列（三）：InfluxDB数据写入Line Protocol详解
数据库·后端·时序数据库
天地之于壹炁兮1 天前
编程I/O入门指南：核心操作全解析
数据库·windows·microsoft
切糕师学AI1 天前
SQL中的函数索引/表达式索引
数据库·sql·mysql·postgresql·oracle
武子康1 天前
Java-166 Neo4j 安装与最小闭环 | 10 分钟跑通 + 远程访问 Docker neo4j.conf
java·数据库·sql·docker·系统架构·nosql·neo4j
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03综合整理：pdf预览显示：你尝试预览的文件可能对你的计算机有害。如果你信任此文件以及其来源，请打开此文件以看其内容，如何解决以正常预览文件04BongoCat - 跨平台键盘猫动画工具05Linux下V2Ray安装配置指南06jdk21下载、安装（Windows、Linux、macOS）07安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）08npm使用国内淘宝镜像的方法09PyCharm 社区版全平台安装指南10NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南