Embeddings

POST /v1/embeddings  compatible  语义操作 embed  契约修订 1

状态语义：stateless

已声明的偏差

逐条来自契约，不是补充说明：

• gateway routes model names
• unknown request fields are rejected before provider I/O
• provider-specific unsupported fields are rejected before provider I/O

请求示例

curl

curl https://halro.example.com/v1/embeddings \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "embed", "input": ["第一段文本", "第二段文本"] }'

Python

import os
from openai import OpenAI

client = OpenAI(base_url="https://halro.example.com/v1", api_key=os.environ["HALRO_GATEWAY_KEY"],
                timeout=60.0, max_retries=0)
response = client.embeddings.create(model="embed", input=["第一段文本", "第二段文本"])
print(len(response.data), "个向量，维度", len(response.data[0].embedding))

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://halro.example.com/v1", apiKey: process.env.HALRO_GATEWAY_KEY,
  timeout: 60_000, maxRetries: 0,
});
const response = await client.embeddings.create({
  model: "embed", input: ["第一段文本", "第二段文本"],
});
console.log(response.data.length, "个向量，维度", response.data[0].embedding.length);

SDK 默认会自动重试

官方 SDK 默认会重试 2 次。Halro 在发出上游请求之前就把预算预留落盘，因此客户端的 静默重试会产生多次独立的预留与结算。示例把它关掉，由你自己决定重试策略 —— 见重试、超时与幂等。

请求头

• Authorization
• Content-Type

请求字段

怎么读这张表

第 2 列沉默不等于支持 —— 契约只记录已声明的限制，没列出的 Profile 是「未声明限制」， 不是「已验证支持」。第 3 列是组合级限制：某些拒绝规则在字段粒度上表达不出来 （例如某个 Profile 拒绝「带工具的流式请求」，而 tools 与 stream 单看都支持）。 字段的类型、是否必填与语义说明当前不在契约里，见页脚说明。

字段	不支持该字段的 Provider Profile	组合级限制
model	—	—
input	bedrock.runtime.invoke.titan-embed-text-v2.v1	—
encoding_format	gemini.generate-content.text.v1beta、bedrock.runtime.invoke.titan-embed-text-v2.v1	—
dimensions	bedrock.runtime.invoke.titan-embed-text-v2.v1	—
user	gemini.generate-content.text.v1beta、bedrock.runtime.invoke.titan-embed-text-v2.v1	—

响应字段

object data model usage

可路由的 Provider Profile 及各自成熟度

端点成熟度不提升单个 Profile

顶部的 compatible 徽章说的是端点，不是下面每一行。每行的成熟度取自该 Profile 自己的覆盖记录。

本页存在成熟度分歧

bedrock.runtime.invoke.titan-embed-text-v2.v1 的成熟度是 experimental，低于端点的 compatible。

Provider Profile	成熟度	不支持的请求字段
openai.chat-embeddings.v1	compatible	未声明
azure-openai.chat-embeddings.v1	compatible	未声明
openai-compatible.chat-embeddings.v1	compatible	未声明
gemini.generate-content.text.v1beta	compatible	encoding_format、user
bedrock.runtime.invoke.titan-embed-text-v2.v1	experimental	input、encoding_format、dimensions、user

已声明的变换

gemini.generate-content.text.v1beta

• token usage is locally estimated when Gemini omits usage

bedrock.runtime.invoke.titan-embed-text-v2.v1

• only one string input is accepted
• dimensions are limited to 256, 512, or 1024
• native requests force normalized float embeddings
• Bedrock inputTextTokenCount is mapped to OpenAI usage

证据

已验证的证据：gateway_contract、provider_transport_fixture、sdk_blackbox

SDK 黑盒协议桩矩阵

openai-go、openai-node、openai-python

警告

该矩阵只证明这些 SDK 版本能序列化请求、并消费 Halro 声明的响应与流形状。它跑的是协议桩， 不经过真实 Runtime 路由、Gateway Key 认证、路由选择、能力过滤、脱敏与预算核算， 不能被引为端到端网关或真实 Provider 的证据。

---

本页的字段表、覆盖矩阵与偏差列表由 Halro 7117fdc38491 的兼容性契约生成 （scripts/generate-api-pages.mjs，契约摘要 9f8a5c57f76ae870…）。 字段的类型、是否必填与语义说明尚未进入契约，因此本页只列字段名。