Embedding Model Group

Embedding Model Group 是 Model Group 在 /v1/embeddings 场景下的对应资源：应用调用一个稳定名称，背后是一个或多个 embedding backend，通过 fallback 或负载均衡路由。它和 chat model group 是两类独立的资源——embedding group 的 routing config、capability 和向量输出都是 embedding 专属的，不能和 chat model group 混用。

调用 Embedding Model Group

curl https://api.modelplane.dev/v1/embeddings \
  -H "Authorization: Bearer YOUR_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embed",
    "input": ["Summarize this incident report."]
  }'

model 是 embedding group 名称，约定和 chat model group 一致。路由、fallback 和 backend 选择的工作方式也完全相同——区别只在于名称背后配置了什么。

为什么 Dimensions 很重要

维度不同的向量不只是"不兼容"这么简单——大多数向量库不会拒绝维度不一致的向量，你依然可以拿去做比较，只是结果没有意义。假设你用一个 3072 维的模型给文档语料做了 embedding 并存入索引。某天你的 embedding provider 出故障，查询请求 fallback 到了一个 1536 维的模型。向量库不会拒绝这个维度不匹配的查询向量，只会返回没有意义的结果——排序莫名其妙地错、本该匹配的文档消失，而且没有任何报错告诉你原因。这种生产事故看起来像"相关性变差了"，而不是"服务出故障了"，往往要花上几个小时才能追溯到是一次 fallback 引起的。

每个 embedding model group 都声明一个固定的输出向量维度（capability.dimensions），就是为了从根本上杜绝这种情况——它背后的每个 backend 返回的向量都必须是这个维度。网关通过两种方式强制这一点：

• 配置阶段：如果某个 backend 显式声明了不同的维度，会被拒绝——从一开始就不可能配出一对维度不兼容的 fallback。
• 请求阶段：实际返回的向量长度会和 group 声明的维度做比对——一旦不一致（例如 provider 悄悄改变了某个模型的输出维度），请求会明确地以 502 失败，而不是把损坏的向量悄悄写入你的索引。

这让哪些用法变得安全可行

• 真正可用的 embedding fallback，而不只是 chat 才有——搭配两个维度相同、来自不同 provider 的模型，其中一个出故障也不会像未经校验的 fallback 那样有污染索引的风险。
• 负载均衡的批量写入，把高吞吐的 embedding 流程分摊到多个 backend，同时不用担心其中任何一个悄悄塞进一个维度不兼容的向量。
• 按自己的节奏迁移 provider——在新旧 provider 维度相同的前提下，把它们放进同一个负载均衡 group，逐步切流量，再按自己的节奏重新 embed 现有语料，而不是被迫做一次高风险的一次性切换。

查询可用的 Embedding Model Group

使用 GET /v1/models?output_modalities=embeddings 列出你的 API key 可以调用的 embedding model group，包括每个 group 的维度：

curl "https://api.modelplane.dev/v1/models?output_modalities=embeddings" \
  -H "Authorization: Bearer YOUR_GATEWAY_API_KEY"

开发者不需要处理什么

• 具体是哪个 provider 或 backend 处理了某次请求。
• backend 出错或超时时的 fallback 顺序。
• 校验返回向量的维度是否匹配你的索引——网关已经在请求到达你之前拦截了不匹配的情况。

这些都和 chat model group 一样，在 ModelPlane 控制台中管理。