# 向量

> /v1/embeddings：输入的写法、默认开着的缓存，以及批量向量化的建议。

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

```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": "<向量模型的 id>",
    "input": ["铁电材料的畴壁迁移", "钙钛矿太阳能电池的稳定性"]
  }'
```

Python：

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

| 字段 | 必填 | 说明 |
|---|---|---|
| `model` | 是 | 向量模型的 id，在[模型中心](https://www.scirouter.cn/models)或 `/v1/models` 里找 |
| `input` | 是 | 一个字符串，或字符串数组（一次向量化多条） |
| `metadata` / `user` | 否 | 归因标签，不转给上游，见「可观测性」 |
| 其他字段 | 否 | 原样转给上游（例如 `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": "<向量模型的 id>",
  "usage": { "prompt_tokens": 24, "total_tokens": 24 },
  "scirouter": { "request_id": "req_…", "cache": "miss", "…": "…" }
}
```

`data` 按 `index` 与输入一一对应。按输入 token 计费。

## 默认走缓存

**向量接口默认开着响应缓存**：同样的模型、同样的输入必然得到同样的向量，第二次起直接返回、**不计费**。
批量向量化一批会重复出现的文本时，这能省下不少。

不想要时带请求头 `X-SciRouter-Cache: disabled`。细节见「缓存与幂等」。

## 批量的建议

- 一次传一个数组比逐条调用快，也更不容易撞上每分钟请求数的限频；
- 但单次请求体不能超过 4 MB（413 `payload_too_large`），上游对单批条数也常有上限——
  超长的列表请切成几百条一批；
- 批量任务带上 `Idempotency-Key`，网络抖动后重试不会重复扣费（见「缓存与幂等」）。