创建 Embeddings 请求导读
Embeddings 解决的是检索、相似度、聚类和索引，不是生成。先把用途分清，很多误用就会自然消失。
POST/v1/embeddings
embeddings 接口最容易被误用成“另一种生成 API”。实际上它的职责更底层： 把文本映射成向量，用于检索、RAG、去重、相似度和聚类。你要先分清 检索任务 和 生成任务，接口选择才不会错。
最值得先看的参数
| Name | Type | Required | Description |
|---|---|---|---|
model | string | Required | embeddings 模型标识。不要直接沿用选择生成模型的方式来选它。 |
input | string | string[] | Required | 单条或批量输入。批量时返回顺序会和输入顺序对应。 |
encoding_format | string | 向量编码格式。对接下游向量库时要确认格式要求。 | |
dimensions | integer | 目标维度。只有部分模型支持缩维，不要默认每个模型都能改。 | |
user | string | 可选归因字段。适合做内部追踪，不是业务主键。 |
最小请求
bash
curl -X POST https://api.therouter.ai/v1/embeddings \
-H "Authorization: Bearer $THEROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/text-embedding-3-small",
"input": [
"incident postmortem",
"deploy rollback checklist"
]
}'批量输入的关键语义
批量 embeddings 的返回顺序会对应输入顺序。这意味着你应该把索引、原始文本和返回向量一起保存， 不要假设下游系统会替你自动做正确映射。
什么时候它是正确选择
- 你在做检索、RAG、相似度搜索或文档聚类。
- 你需要把文本内容映射成可检索向量，而不是直接生成回答。
- 你想把上游 OpenAI-compatible embeddings 调用迁到统一路由层。
最容易犯的错
text
1. 用 embeddings 接口做生成任务。
2. 批量输入后没有保留输入顺序映射。
3. 直接沿用选择生成模型的方式去选 embeddings 模型。
4. dimensions 改了，却没确认下游索引结构是否同步更新。