SageMaker 是 AWS 的托管模型服务,你可以往上面部署任意模型——包括用 OpenAI API 格式包装的模型。9.1 让 ES 的 SageMaker 推理服务支持 OpenAI 格式的嵌入请求。这条改动小众,但它揭示了一个挺有意思的设计。
说明
来源和边界先交代:本文的依据出自 v9.4.2 标签下的官方文件(9.1.0.yml、SageMakerSchemas.java、SageMakerService.java),文中引用的原文均来自这些文件。示例取自官方示例;哪些是文档写明、哪些是我的推断,正文里逐处标注。
实测环境:本地另起一个 Elasticsearch 9.4.2 单节点实例(官方 tar 包,端口 9200,独立 path.data),安全特性与机器学习均关闭;repository-s3 / repository-gcs 随发行包内置,仓库创建统一加 verify=false 跳过 AWS / GCS 连通性校验。文末「在 9.4.2 上跑一遍」里的命令与响应均取自该实例。
图 1:官方文件 9.1.0.yml(v9.4.2 标签)。来源:GitHub elastic/elasticsearch v9.4.2 9.1.0.yml
官方条目
9.1 的 changelog 标为 enhancement(9.1.0.yml 第 1118–1121 行 @ v9.4.2),area: Machine Learning:
[ML] Integrate SageMaker with OpenAI Embeddings
只有一行 summary。下面的内容来自源码——源码里的设计比这条 summary 有意思得多。
图 2:官方文件 SageMakerSchemas.java(v9.4.2 标签)。来源:GitHub elastic/elasticsearch v9.4.2 SageMakerSchemas.java
先说 SageMaker 推理服务的特殊性
ES 的推理服务(inference service)通常对接确定的外部服务:OpenAI、Cohere、Voyage AI……每个服务有自己的 API 格式,ES 为它们各写一个适配。
SageMaker 不一样。 它是 AWS 的模型托管平台——你在上面部署什么模型,它就提供什么能力。ES 无法预知你部署的 API 长什么样。
所以 SageMaker 服务的适配不能写死一种格式,得能应付多种。
图 3:官方文件 SageMakerService.java(v9.4.2 标签)。来源:GitHub elastic/elasticsearch v9.4.2 SageMakerService.java
为什么会有这种组合
看到"SageMaker + OpenAI 格式"可能会觉得奇怪——既然要用 OpenAI 格式,为什么不直接连 OpenAI?
这是个合理的疑问,按理解说几种情况(这些是推断,不是官方列举的场景):
一,数据不出自有环境。 有些团队不能把数据发到外部 API,但可以在自己的 AWS 账号里部署模型。SageMaker 提供了这种可能——模型跑在账号下,数据不出去。
二,用开源模型但沿用 OpenAI 的接口约定。 现在不少开源嵌入模型服务器都提供 OpenAI 兼容的 API(这是个事实上的接口标准)。部署在 SageMaker 上,对外就是 OpenAI 格式。
三,统一的接入方式。 如果团队已经在用 OpenAI 格式的客户端和工具,让 SageMaker 上的模型也用同一格式,下游不用改。
这三条的共同点:要的是"格式兼容"带来的便利,同时保留"自己托管"的控制力。
所以这条改动服务的是"用自己的部署、但接口沿用 OpenAI 约定"这个需求,不是"用 OpenAI"这个需求。理解这一点,才知道它对谁有用。
(说明:以上是推断的适用场景,官方条目没有列举。是否适合你,要看你自己的部署情况。)
schema 注册表
这个难题的解法在源码里很清楚(SageMakerSchemas.java 第 45–52 行,源码 @ v9.4.2):
/*
* Add new model API to the register call.
*/
schemas = register(
new OpenAiTextEmbeddingPayload(),
new OpenAiCompletionPayload(),
new ElasticTextEmbeddingPayload(),
new ElasticSparseEmbeddingPayload(),
new ElasticCompletionPayload(),
new ElasticRerankPayload()
);
一个注册表,里面六个 payload 实现。 类的注释写得很直白:
The mapping and registry for all supported model API.
"所有支持的模型 API 的映射和注册表"——这就是应对"不知道用户部署了什么"的办法:预先支持若干种常见格式,让用户选。
本篇加的是哪一个
OpenAiTextEmbeddingPayload —— OpenAI 格式的文本嵌入。
在 schema/openai/ 子包下,同目录还有 OpenAiCompletionPayload(补全)。也就是说 OpenAI 格式的支持分两类:嵌入和补全。
本篇的条目说的是"Embeddings",对应的是前者。
六种 schema 分别是什么
从注册表的名字就能看出全貌——这本身就是设计的优点:
| Payload | 格式 | 任务 |
|---|---|---|
OpenAiTextEmbeddingPayload | OpenAI | 文本嵌入 |
OpenAiCompletionPayload | OpenAI | 补全 |
ElasticTextEmbeddingPayload | Elastic | 文本嵌入 |
ElasticSparseEmbeddingPayload | Elastic | 稀疏嵌入 |
ElasticCompletionPayload | Elastic | 补全 |
ElasticRerankPayload | Elastic | 重排 |
两大类格式(OpenAI / Elastic)× 三种任务(嵌入 / 补全 / 重排)。
这个表格本身就很说明问题:同样是"文本嵌入",既有 OpenAI 格式也有 Elastic 格式可选。因为 SageMaker 上跑什么取决于用户,ES 只能都准备好。
下游怎么用注册表
注册表不是摆设,后面几行就用起来了(第 54–66 行):
streamSchemas = schemas.entrySet()
.stream()
.filter(e -> e.getValue() instanceof SageMakerStreamSchema)
.collect(...);
tasksByApi = schemas.keySet()
.stream()
.collect(Collectors.groupingBy(TaskAndApi::api, Collectors.mapping(TaskAndApi::taskType, Collectors.toSet())));
supportedTaskTypes = EnumSet.copyOf(schemas.keySet().stream().map(TaskAndApi::taskType).collect(Collectors.toSet()));
三件事:
- 筛出支持流式的 schema(
instanceof SageMakerStreamSchema); - 按 API 分组任务(
tasksByApi); - 算出支持的任务类型全集(
supportedTaskTypes)。
最后这个会被 SageMakerService.supportedTaskTypes() 用到(第 147–148 行,源码 @ v9.4.2):
public EnumSet<TaskType> supportedTaskTypes() {
return schemas.supportedTaskTypes();
}
"支持哪些任务类型"是从注册表推导出来的,不是硬编码的。 加一个新 schema,支持的任务类型自动更新。
这是个好设计——加格式只需要改一处( register(...) 调用),不用到处补判断。源码注释里那句 "Add new model API to the register call" 就是在告诉后来者:加新格式,改这里就行。
这种"注册表"思路能推广到哪
上面说这个设计有普遍价值,这里具体说——什么情况下该用它。
适用条件:你要对接一个外部系统,而它的形态你是无法预知的,但可以枚举出常见的几种。
对照三种解法:
一,写一个通用抽象。 试图用一套结构表达所有可能。问题是——要么太宽(什么都表示得了,但什么都不精确),要么不断膨胀(每来一种新格式就加分支,最后变成一堆 if-else)。
二,让用户自己提供转换逻辑(比如让用户写脚本)。灵活,但把复杂度推给了用户,而且每个用户都要重复做。
三,列一批已知格式让用户选(本篇的做法)。覆盖够用、每种精确、扩展点集中在一处。
判断第三种在多数情况下最优,理由是它把"穷举"的成本从"每次处理"降到了"新增一种时改一处"。
它也有代价:遇到注册表里没有的格式就没辙——用户只能等支持,或者绕道。所以选这条路的前提是:你能覆盖住绝大多数实际用法。
SageMaker 这个例子恰好满足:上面部署的模型虽然多样,但用 OpenAI 或 Elastic 格式包装的占了绝大多数,所以列六种就够用。
判断依据:一份枚举能不能覆盖 80% 以上的场景? 能 → 用注册表;不能 → 得考虑让用户扩展。
对使用者意味着什么
如果你在 SageMaker 上部署了用 OpenAI 格式包装的嵌入模型,现在可以直接对接。
具体做法:创建推理端点时用 api 指定对应的 API 格式,让 ES 知道该用哪个 payload 来组装请求(该参数名已从文末实测的服务注册表读到)。
什么时候需要这条改动:
- 用 SageMaker 托管模型;
- 部署的模型暴露的是 OpenAI 兼容的 API;
- 需要用它做文本嵌入(比如生成向量存进
semantic_text)。
不需要的情况:
- 用 Elastic 自己的格式——那走
ElasticTextEmbeddingPayload; - 直接用 OpenAI 官方服务——那不需要 SageMaker;
- 部署的是稀疏嵌入模型——注册表里稀疏嵌入只有 Elastic 格式(
ElasticSparseEmbeddingPayload)。
第三条值得留意:OpenAI 格式这边只覆盖了密集嵌入和补全,稀疏嵌入要靠 Elastic 格式——我的建议是按模型输出类型选 schema,别默认 OpenAI。
这条展示了"应对未知"的一种解法
这条改动很小众,但它背后的设计思路有普遍价值。
问题是:ES 要对接一个它无法预知内容的服务。
解法是:不做统一抽象,而是列一批已知格式让用户选。
这个取舍是对的,理由:
- 强行做统一抽象,要么抽象得太宽(什么都能表示但什么都不精确),要么不断扩展(维护成本爆炸);
- 列一批已知格式,覆盖面够用,且每种都精确;
- 加新格式的成本被隔离在一处( register 调用)。
这是一种"承认无法穷举,但把扩展点做便宜"的做法。讲 tdigest 字段类型那篇里是类似的思路——为特定计算专门设计存储,也是放弃通用性换精确和效率。两者都是"不做万能方案,但让加一种变得便宜"。
和别的推理服务改动放一起看
9.x 在推理服务上持续投入,前面写过几篇相关的:
| 篇 | 内容 |
|---|---|
| 那篇 | 聚合度量的推导规则 |
| 那篇 | none 分块策略 |
| 那篇 | 自适应分配缩到 0 |
| 本篇 | SageMaker 支持 OpenAI 嵌入格式 |
前三条是"怎么更好地用推理",本篇是"能接哪些推理"——属于扩展接入范围。
判断这个方向会继续:推理服务的接入面是 ES 在 AI 场景下的竞争力之一。支持的格式越多,用户越不需要自己写转换层——而"自己写转换层"正是这类集成里最容易积累技术债的地方。
在 9.4.2 上跑一遍
服务注册表本身就是个可查询的接口,不用起 SageMaker 端点也能验。
图 4:9.4.2 单节点实例的实测输出。/_inference/_services?task_type=text_embedding 列出 19 种服务且包含 amazon_sagemaker;该条目带 5 种任务类型与 13 个配置项(含 api);用不存在的服务名建端点报 Unknown service [no_such_service]。
curl -s 'http://localhost:9200/_inference/_services?task_type=text_embedding' \
| jq -c '{count:length, sagemaker:(any(.[]; .service=="amazon_sagemaker"))}'
# {"count":19,"sagemaker":true}
curl -s 'http://localhost:9200/_inference/_services?task_type=text_embedding' \
| jq -c '.[] | select(.service=="amazon_sagemaker") | {task_types, configurations:(.configurations|keys)}'
# {"task_types":["text_embedding","sparse_embedding","rerank","completion","chat_completion"],"configurations":["access_key","api","batch_size",...]}
curl -s -X PUT 'http://localhost:9200/_inference/text_embedding/bad-svc' -H 'Content-Type: application/json' \
-d '{"service":"no_such_service","service_settings":{"model":"x"}}' | jq -r '.error.root_cause[0].reason'
# Unknown service [no_such_service]
图 4 把「靠 schema 注册表而非写死」落到了可查询的接口上,正文标「创建端点时的参数名未核对」的那一项也读到了:配置项清单里有 api。不存在的服务名在注册表里查不到,端点创建直接被拒。
边界:
- 图 4 出自 9.4.2 单节点实例,没有真实 SageMaker 服务与凭据,创建端点的完整流程未跑通;
- 六种 schema 各自的请求格式细节未逐个查看;
- 注册表只查了
text_embedding一种任务类型。
写在最后
一条小众但设计清晰的改动。
一,SageMaker 是模型托管平台,ES 无法预知你部署了什么 API——所以它没写死一种适配,而是用"schema 注册表"预先支持若干种格式让你选。
二,9.1 加的是 OpenAI 格式的文本嵌入(OpenAiTextEmbeddingPayload)。注册表里一共六种,按"格式 × 任务"可分为 OpenAI 和 Elastic 两类格式,覆盖嵌入、补全、重排三类任务。我的建议是选之前先看清自己部署的 API 属于哪一类。
三,"支持哪些任务类型"从注册表推导,源码注释就是这么告诉后来者的,不是硬编码——加新格式只需改一处注册调用。
另外诚实标注一处:这六种 schema 各自的请求格式细节未逐个查看。
参考
- changelog 9.1.0:[ML] Integrate SageMaker with OpenAI Embeddings(第 1118–1121 行)@ v9.4.2
SageMakerSchemas.java:schema 注册表与派生逻辑(第 45–66 行)@ v9.4.2SageMakerService.java:supportedTaskTypes()从注册表取值(第 147–148 行)@ v9.4.2OpenAiTextEmbeddingPayload.java:本篇新增的 payload @ v9.4.2
本文对照 Elasticsearch
v9.4.2标签的 changelog 与源码核对,引文与代码逐字取自原文。「在 9.4.2 上跑一遍」里已实际查询服务注册表:text_embedding列出 19 种服务、包含amazon_sagemaker,该条目带 5 种任务类型与 13 个配置项(含api),不存在的服务名报Unknown service [no_such_service]。创建推理端点时指定 API 格式的参数名已从注册表读到为api;六种 schema 各自的请求格式细节未逐个查看;实际配置与使用流程未实测(缺 SageMaker 凭据)。
