# 创建向量

来源: https://platform.lyrouter.com/ai_gateway/docs/embeddings
更新日期: 2026-10-19

把一段或多段文本转换成向量，适合检索增强（RAG）、语义搜索和去重；需要按与查询的相关度给文档排序时，用[文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank)。接口采用 OpenAI Embeddings API 的格式，OpenAI SDK 的 `client.embeddings.create()` 把 Base URL 设为 `https://api.lyrouter.com/v1` 即可使用；请求和响应都是 JSON，不支持流式。网关只把 `model` 换成服务商的真实模型名，其余字段原样转发，所以参数和响应格式以模型所属服务商为准。

`POST /v1/embeddings`

## 鉴权

在请求头中携带 API Key：

```text
Authorization: Bearer <API Key>
```

`Bearer` 区分大小写。也可以改用 `x-api-key: <API Key>`，两者同时存在时只读 `Authorization`。API Key 在工作空间的 **API 密钥** 页面创建，只用于 LYRouter 鉴权，不会转发给上游服务商。完整说明见[接入地址与鉴权](https://platform.lyrouter.com/ai_gateway/docs/call-gateway)，环境变量 `LYROUTER_API_KEY` 的设置见[完成第一次模型调用](https://platform.lyrouter.com/ai_gateway/docs/quickstart)。

## 请求头

| 请求头 | 必填 | 说明 |
| --- | --- | --- |
| `Content-Type` | 是 | `application/json`，其他类型返回 400 |

## 请求体

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 向量模型 ID，获取方法见下文「选择模型」。请始终写明：不写时使用工作空间的默认模型，而默认模型通常是对话模型，落到它上面会返回 400 `unsupported_model_api` 或上游的错误，见下文「网关行为」 |
| `input` | string \| array | 是 | 一段文本，或文本数组（一次生成多条向量）。单次条数、单条长度上限由服务商决定 |
| `encoding_format` | string | 否 | `float`（数字数组）或 `base64`。透传给上游，是否支持取决于模型 |
| `dimensions` | integer | 否 | 输出向量的维度。透传给上游，是否生效取决于模型 |
| `user` | string | 否 | 终端用户标识。透传给上游，是否生效取决于模型 |

表中没有列出的字段原样转发给上游，是否生效取决于模型。

### 选择模型

可用的向量模型以工作空间的模型广场为准：在模型广场搜索 `embedding` 等关键词，复制模型 ID 替换示例中的 `MODEL_ID`。

也可以用 [`GET /v1/models`](https://platform.lyrouter.com/ai_gateway/docs/models) 筛选。返回的每个模型带 `api_types` 字段，含 `embeddings` 的可调用本接口：

```bash
curl -s https://api.lyrouter.com/v1/models \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  | jq -r '.data[] | select((.api_types // []) | index("embeddings")) | .id'
```

模型没有声明 `api_types` 时不会出现在筛选结果里，可以在模型广场确认。字段说明见[列出模型](https://platform.lyrouter.com/ai_gateway/docs/models)，筛选重排模型的方法见[文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank)。

## 请求示例

**请求示例**

cURL:
```bash
curl https://api.lyrouter.com/v1/embeddings \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "input": ["LYRouter 是可信模型服务与 Token 治理平台", "用一个 API Key 调用多家模型"],
    "encoding_format": "float"
  }'
```

Python:
```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
)
result = client.embeddings.create(
    model="MODEL_ID",
    input=["LYRouter 是可信模型服务与 Token 治理平台", "用一个 API Key 调用多家模型"],
    encoding_format="float",
)
for item in result.data:
    print(item.index, len(item.embedding))
print(result.usage)
```

Node.js:
```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
});
const result = await client.embeddings.create({
  model: "MODEL_ID",
  input: ["LYRouter 是可信模型服务与 Token 治理平台", "用一个 API Key 调用多家模型"],
  encoding_format: "float",
});
for (const item of result.data) {
  console.log(item.index, item.embedding.length);
}
console.log(result.usage);
```

OpenAI 官方 SDK 在没有指定 `encoding_format` 时会请求 `base64` 并在本地解码。如果上游不支持 `base64` 而报错，像上例一样显式传 `encoding_format="float"`。

## 响应

成功时返回一个 `list` 对象，`data` 中每条输入对应一个向量；出错时返回 `error` 对象。下面的 200 是 OpenAI 兼容服务商的典型响应（向量已截短），400 是请求落到了不支持向量接口的模型（多为默认模型，见下文「网关行为」），403 是模型没有在本工作空间开通且工作空间没有设置默认模型。

**响应示例**

200:
```json
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789] },
    { "object": "embedding", "index": 1, "embedding": [-0.0211, 0.0334, 0.0102] }
  ],
  "model": "MODEL_ID",
  "usage": { "prompt_tokens": 19, "total_tokens": 19 }
}
```

400:
```json
{
  "error": {
    "message": "This model does not support the embeddings API",
    "type": "invalid_request_error",
    "code": "unsupported_model_api"
  }
}
```

403:
```json
{
  "error": {
    "message": "Model is not available in the model plaza",
    "type": "access_denied",
    "code": "model_not_available"
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `data[].index` | 对应 `input` 数组中的位置，按它对齐，不要依赖返回顺序 |
| `data[].embedding` | 向量。`encoding_format` 为 `base64` 时是 Base64 字符串 |
| `model` | 上游返回的模型名，可能与请求中的模型 ID 写法不同；实际使用的模型以日志的「模型（实际）」为准 |
| `usage.prompt_tokens` | 本次输入的 Token 数，即计费数量。在[日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中记为「输入（缓存未命中）」，「输出」「输入（缓存命中）」「显式缓存创建」均为 0 |
| `usage.total_tokens` | 与 `prompt_tokens` 相同 |

### 计费

按输入 Token 数计费，取自响应的 `usage.prompt_tokens`。单价以模型广场为准，每次调用的实际费用在[日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中查看。费用估算方法见[调用费用与缓存计费](https://platform.lyrouter.com/ai_gateway/docs/estimate)。

## 网关行为

- **请求原样转发**：网关只把 `model` 换成通道的真实模型名，其余字段原样转发（通过虚拟模型调用时见下文）。网关会重新编码 JSON：对象的键按固定顺序排列，数字最多保留 14 位有效数字。
- **通道回退**：同一模型有多个通道时，按工作空间的[路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing)依次尝试，前一个通道失败就换下一个。
- **默认模型兜底**：工作空间在智能路由中设置了默认模型时，下面三种情况会落到默认模型上。默认模型通常是对话模型，此时得到的是报错，而不是你预期的结果（默认模型声明了 `api_types` 时，网关返回 400 `This model does not support the embeddings API`；没有声明时，请求会转发给上游，由上游报错，见下文「常见错误」）：
  - 请求没写 `model`；
  - `model` 写错，或该模型没有在本工作空间开通；
  - 该模型的所有通道都失败了。这时上游的真实报错被默认模型的报错取代，请到日志详情的「上游调用尝试」查看前面每次尝试的原因。
- **虚拟模型与 Auto**：[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets)可以用于本接口，前提是它的模型列表全部是向量模型；虚拟模型的系统提示词不会注入，但设置的推理参数会按字段名合并进请求体，因此给向量接口使用的虚拟模型不要设置推理参数。[`lyrouter/auto`](https://platform.lyrouter.com/ai_gateway/docs/auto) 的候选是对话模型，不要用于本接口。目前网关不会拒绝这类请求：请求会挂起约 2 分钟，之后返回 HTTP 200，响应体是上游的原生错误（如 `{"vectors":null,"base_resp":{"status_code":2013,...}}`）而不是向量列表，只看状态码的程序会误以为成功；使用 HTTP/2 时连接还可能中途断开。
- **安全围栏**：[安全围栏](https://platform.lyrouter.com/ai_gateway/docs/guardrails)的封禁、模型访问控制和客户端访问控制照常生效；敏感信息、提示词注入和意图安全检测不作用于本接口。

## 常见错误

错误响应为 `{"error":{"message":"...","type":"...","code":"..."}}`，`code` 只有部分错误才有。

| 状态码 | `error.message` | `error.code` | 原因与处理 |
| --- | --- | --- | --- |
| 400 | `This model does not support the embeddings API` | `unsupported_model_api` | 所用模型声明了 `api_types` 且不支持向量接口，多为请求落到了默认模型，见上文「默认模型兜底」。写上正确的向量模型 ID |
| 400 | `you must provide a model parameter` | `missing_model` | 没写 `model`，工作空间也没有默认模型 |
| 400 | `unsupported content-type: <类型>, only application/json is supported` | — | `Content-Type` 不是 JSON。响应体是一行纯文本，但响应头 `Content-Type` 目前是 `application/json`，解析前先判断正文是否为 JSON |
| 403 | `Model is not available in the model plaza` | `model_not_available` | 模型没有在本工作空间开通，且没有设置默认模型。请管理员在模型广场开通，或换用已开通的模型 |
| 503 | `all routed candidates exhausted` | `no_route_candidate` | 找不到可服务这次请求的通道，见[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable) |

- 输入超长、条数超限等由上游服务商返回，状态码和报错原文由上游决定。
- 用没有声明 `api_types` 的对话模型（见[列出模型](https://platform.lyrouter.com/ai_gateway/docs/models)）调用本接口时，不会收到 400 `unsupported_model_api`：请求会转发给上游，由上游报错，可能要等待较长时间。例如某对话模型约 60 秒后返回上游的 404 ``Unsupported model `<模型>` for OpenAI compatibility mode.``，`error.code` 为 `model_not_supported`。
- 网关先解析模型，再检查 `Content-Type`：没写 `model` 或模型没有开通时，先返回模型相关的错误（400 `missing_model`、403 `model_not_available`）；模型有效时才返回 400 `unsupported content-type: …`。
- 401 / 403 鉴权问题见[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)，429 见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。完整列表见[错误码与请求标识](https://platform.lyrouter.com/ai_gateway/docs/errors)。