Embeddings

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

状态语义：stateless; an Idempotency-Key adds a 24 hour record of the key, its request fingerprint and how far the request got, and no part of the request or the answer

查看原始契约偏差（英文）

这些是源码契约中的逐条证据。日常接入先看本页示例、字段表和 Profile 覆盖矩阵；排查兼容性边界时 再展开核对原文。

• gateway routes model names
• unknown request fields are rejected before provider I/O
• provider-specific unsupported fields are rejected before provider I/O
• Idempotency-Key is optional and buys at-most-once execution upstream, not response replay: a repeat of a key whose request finished answers 409 idempotency_completed rather than the original answer, because the answer is not stored
• a repeat while the first request is still running, or after one whose outcome nobody can determine, answers 409 idempotency_in_progress; it is a refusal rather than a wait, because holding a socket against another request’s outcome is not something this gateway does
• the same key with a different request body answers 409 idempotency_conflict, and keys are scoped to one Project so two Projects may use the same external key
• a request with no Idempotency-Key behaves exactly as before and writes nothing durable; the key is what buys the record
• a request the gateway refuses on its own — a capability filter, a token limit, a Project budget — never reached the upstream and gives its key back, so a retry is answered by the limit it broke rather than by a conflict about a call nobody made
• a key is remembered for 24 hours, whatever state its request ended in, after which the same key is free again — including for a different request

请求示例

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
• Idempotency-Key

请求字段

怎么读这张表

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

请求字段

字段	不支持该字段的 Provider Profile	组合级限制
model	—	—
input	bedrock.runtime.invoke.titan-embed-text-v2.v1	—
encoding_format	bigmodel.cn.chat-embeddings.v1、gemini.generate-content.text.v1beta、bedrock.runtime.invoke.titan-embed-text-v2.v1	1 见脚注 1
dimensions	bedrock.runtime.invoke.titan-embed-text-v2.v1	—
user	bigmodel.cn.chat-embeddings.v1、gemini.generate-content.text.v1beta、bedrock.runtime.invoke.titan-embed-text-v2.v1	2 见脚注 2

响应字段

object data model usage

Provider Profile 契约覆盖与本构建可用性

端点成熟度不提升单个 Profile

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

本页存在成熟度分歧

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

有契约，不代表本构建可创建

bedrock.runtime.invoke.titan-embed-text-v2.v1 已实现且保留在兼容性契约中，但被 Halro 08af8c8b0b10 的 served Profile matrix 隐藏，Admin 写路径也会拒绝创建。 新实例不能把这些 Profile 配置成 Deployment；已有记录只保留启动与删除通道。

Provider Profile 契约覆盖与本构建可用性

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

已声明的变换

bigmodel.cn.chat-embeddings.v1

• 操作结论：OpenAI 形状的 Embedding 请求发往中国大陆 /api/paas/v4/embeddings 路径。 原始契约：the OpenAI-shaped embedding body is sent to the mainland /api/paas/v4/embeddings route
• 操作结论：encoding_format 和 user 必须省略；一旦出现会在 Provider I/O 前拒绝。 原始契约：encoding_format and user are omitted only when absent and otherwise rejected before provider I/O

gemini.generate-content.text.v1beta

• 操作结论：Gemini 未返回 usage 时 Halro 会本地估算 Token；报表必须保留估算标记，不能当作 Provider 实报。 原始契约：token usage is locally estimated when Gemini omits usage

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

• 操作结论：输入只允许单个字符串；不要提交字符串数组或其他输入形状。 原始契约：only one string input is accepted
• 操作结论：dimensions 只允许 256、512 或 1024；其他值不要提交。 原始契约：dimensions are limited to 256, 512, or 1024
• 操作结论：原生请求返回归一化浮点 Embedding；调用方不要请求其他编码或非归一化输出。 原始契约：native requests force normalized float embeddings
• 操作结论：Halro 把 Bedrock inputTextTokenCount 映射到 OpenAI usage；客户端从标准 usage 字段读取输入 Token。 原始契约：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 的证据。

最佳实践

索引版本与 Rerank 规划边界见案例九：Embedding 索引与 Rerank 规划边界。

---

本页的字段表、覆盖矩阵与偏差列表由 Halro 08af8c8b0b10 的兼容性契约生成 （scripts/generate-api-pages.mjs，当前副本摘要 db249a88ce62e5b7…）。

字段的类型、是否必填与语义说明尚未进入契约，因此本页只列字段名。

Footnotes

1. encoding_format 的组合级限制：

   • bigmodel.cn.chat-embeddings.v1：encoding_format 和 user 必须省略；一旦出现会在 Provider I/O 前拒绝。 原始契约：encoding_format and user are omitted only when absent and otherwise rejected before provider I/O
   ↩

2. user 的组合级限制：

   • bigmodel.cn.chat-embeddings.v1：encoding_format 和 user 必须省略；一旦出现会在 Provider I/O 前拒绝。 原始契约：encoding_format and user are omitted only when absent and otherwise rejected before provider I/O
   ↩