Embeddings 接口是什么
嵌入接口把文本转成向量：向 /v1/embeddings 发一个请求，请求体里给模型名与输入文本，返回每条输入对应的向量。输入既可以是单条字符串，也可以是字符串数组，批量处理能显著降低请求次数。接口本身很简单，工程重点在于批量大小、失败重试、用量统计，以及保证入库与查询用的是同一个模型。
基本信息
| 请求路径 | 多数服务为 /v1/embeddings |
|---|---|
| 方法 | POST，请求体为 JSON |
| 核心字段 | 模型名与输入内容，输入支持字符串或数组 |
| 返回结构 | 每条输入对应一个向量及序号 |
| 维度 | 由模型决定，部分模型支持指定降维 |
| 批量 | 支持一次处理多条，单批条数与总长度上限见官方文档 |
请求与返回怎么读
| 字段 | 含义 | 注意 |
|---|---|---|
| 模型名 | 指定使用的嵌入模型 | 入库与查询必须一致 |
| 输入 | 单条文本或文本数组 | 数组顺序与返回序号对应 |
| 向量 | 浮点数数组，长度即维度 | 维度需与向量表定义匹配 |
| 序号 | 该项在输入数组中的位置 | 批量时用于对齐原文 |
| 用量 | 本次消耗的 token 数 | 用于成本统计与限流预估 |
典型使用场景
- 知识库入库：把文档片段批量转成向量写入检索库
- 在线查询：把用户问题向量化后做近邻检索
- 文本聚类与去重：为大量短文本生成向量做分组
- 推荐召回：为内容与用户画像生成向量做匹配
- 语义校验：通过向量距离发现相似或重复内容
单条与批量调用
单条与批量调用
curl -s https://api.openai.com/v1/embeddings -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"model":"text-embedding-3-small","input":"订单已发货"}' # 单条
# 批量：把输入换成字符串数组，一次提交多条
# input 用数组时，返回条目的序号与输入下标一一对应
# 向量维度要与建表定义一致，改模型等于重建整张向量表批量处理的注意事项
| 事项 | 做法 | 原因 |
|---|---|---|
| 单批条数 | 按文档上限设置，留出余量 | 超限请求会整体失败 |
| 文本长度 | 超长片段先切分或截断 | 超出上限的部分可能被忽略 |
| 失败重试 | 对可恢复错误做退避重试 | 批量写入常受限于速率 |
| 去重 | 相同文本复用同一向量 | 重复向量化纯属浪费 |
| 顺序对齐 | 按返回序号回填原文与元数据 | 顺序错位会造成数据错乱 |
向量化通常在入库阶段完成，属于离线批量任务：把速率控制与断点续跑做扎实，比追求单批更大更实用。
更换嵌入模型必须重建全部向量：新旧向量不在同一空间，混用会让检索结果变得毫无意义。