# 向量

> POST /v1/embeddings 的请求与响应、默认开启的按条缓存，以及批量调用的限制。

来源：https://www.scirouter.cn/docs/embeddings · 更新于 2026-10-24

```http
POST https://api.scirouter.cn/v1/embeddings
```

将文本转换为向量，用于检索、聚类与去重。请求与响应格式与 OpenAI Embeddings 一致。

## 请求

```bash
curl https://api.scirouter.cn/v1/embeddings \
  -H "Authorization: Bearer $SCIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_EMBEDDING_MODEL_ID",
    "input": ["铁电材料的畴壁迁移", "钙钛矿太阳能电池的稳定性"]
  }'
```

Python：

```python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["SCIROUTER_API_KEY"], base_url="https://api.scirouter.cn/v1")

resp = client.embeddings.create(
    model="YOUR_EMBEDDING_MODEL_ID",
    input=["铁电材料的畴壁迁移", "钙钛矿太阳能电池的稳定性"],
)
vectors = [item.embedding for item in resp.data]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `model` | 是 | 向量模型的 id，见[模型中心](https://www.scirouter.cn/models)或 [`GET /models`](https://www.scirouter.cn/docs/models) |
| `input` | 是 | 字符串、字符串数组（一次向量化多条），或 token 数组（`[1, 2, 3]` 为一条，`[[1, 2], [3]]` 为多条） |
| `metadata` / `user` | 否 | 归因标签，不转给上游，见[可观测性](https://www.scirouter.cn/docs/observability) |
| 其他字段 | 否 | 原样转给上游，如 `dimensions`、`encoding_format`，上游支持时生效 |

## 响应

```json
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456] },
    { "object": "embedding", "index": 1, "embedding": [0.0789, 0.0012] }
  ],
  "model": "YOUR_EMBEDDING_MODEL_ID",
  "usage": { "prompt_tokens": 24, "total_tokens": 24 },
  "scirouter": { "request_id": "req_…", "cache": "miss", "cost_quota": 480, "…": "…" }
}
```

数值为示例，`embedding` 只列出前两维。

| 字段 | 说明 |
|---|---|
| `data` | 按 `index` 与输入一一对应 |
| `usage` | 全部输入的 token 数，包括来自缓存的条目 |
| `scirouter.cost_quota` | 本次实际扣除的配额。按输入 token 计费，来自缓存的条目不计费 |
| `scirouter.cache` | `hit` / `partial` / `miss` / `bypass` |

## 按条缓存

向量接口默认开启响应缓存，每条输入分别缓存，默认保存 24 小时。命中条件为同一 API Key、同一模型，且其他参数相同（如 `dimensions` / `encoding_format`）。

- 同一段文字在任一批次、任一位置都能命中。
- 一批中只有未命中的条目发给上游，结果按原顺序拼回。此时响应头为 `X-SciRouter-Cache: PARTIAL`，`scirouter.cache_items` 给出命中的条数。
- 命中的条目不计费，但请求仍计入每分钟请求数。
- 不同 API Key 之间不共享缓存。

| 请求头 | 取值 | 作用 |
|---|---|---|
| `X-SciRouter-Cache` | `disabled` | 不使用缓存 |
| `Cache-Control` | `no-store` | 不使用缓存 |
| `Cache-Control` | `no-cache` | 刷新缓存，不读取旧结果 |

缓存规则见[缓存与幂等](https://www.scirouter.cn/docs/caching)。

## 批量调用

一次传入数组比逐条调用快，也更不容易触发每分钟请求数的限频。单次请求受以下限制：

| 限制 | 上限 | 超出时 |
|---|---|---|
| 请求体 | 4 MB | 413 `payload_too_large` |
| 一批输入的 token 估算 | 套餐的每分钟 token 上限 | 400 `validation_failed`，`details.reason` 为 `plan_tpm_exceeded`、`param` 为 `input`，`details.limit` 为上限、`details.estimated` 为估算 |
| 单批条数 | 上游通常有上限 | — |

列表较长时按几百条一批切分。

**批量任务带上 `Idempotency-Key`**：成功的结果保存 24 小时，同键重试直接返回该次结果（响应头 `Idempotent-Replayed: true`），不重复扣费，见[缓存与幂等](https://www.scirouter.cn/docs/caching)。