文档 · 向量
免费的 embedding 接口怎么用?别名不会偷偷换模型
/v1/models 里列着四条向量条目。三条是可以直接调用的模型名;剩下一条是别名 auto/embed,它只指向一个模型,永远不变。它不会把你的请求悄悄转给别人——这个限制是故意的,下面说它挡掉了什么。
一句话定义
auto/embed 是一种 tokenexchage 提供的向量化能力别名:把一段文本变成 1024 个维度的向量。它背后只有 1 个模型,不会在你不知情的时候更换;请求的必填参数是 2 个(model 与 input),返回形状沿用 OpenAI 的 {data, model, usage},已经会调 embedding 的客户端不用改解析代码。
关键数字
| 向量维度 | 1024 |
| 别名背后的候选模型数 | 1 |
| 接口 | POST /v1/embeddings |
| 返回形状 | OpenAI 的 {data, model, usage} |
三步接入
国际区账号请把 base_url 换成 https://alli.website/v1,请求形状与下面完全一致。用国际区 key 打 tokenexchage.com 会返回 401 invalid customer key。
- 在控制台创建 API 密钥。
- 向
https://tokenexchage.com/v1/embeddings发 POST,model写auto/embed,input收字符串或字符串数组。 - 从返回的
data[i].embedding取向量,长度为 1024。
怎么调
curl https://tokenexchage.com/v1/embeddings \
-H "Authorization: Bearer sk-你的key" \
-H "Content-Type: application/json" \
-d '{"model":"auto/embed","input":"今天天气不错"}'
from openai import OpenAI
client = OpenAI(
base_url="https://tokenexchage.com/v1",
api_key="sk-你的key",
)
r = client.embeddings.create(
model="auto/embed",
input=["第一段", "第二段"],
)
print(len(r.data[0].embedding)) # 1024
input 收字符串,也收字符串数组。返回是 OpenAI 的形状({data, model, usage}),已经会调 embedding 的客户端不用改任何一行解析代码。
为什么没有降级链
大多数路由层把「模型挂了」当成「请求挂了」,于是换下一个候选重试。对话场景里这没坏处——换个模型照样能回答问题,而且你看得出来答的人变了。
向量场景里,这么干会把你的数据毁掉。
不同的 embedding 模型不共享坐标系。我们实测过三个候选,它们返回的都是 1024 维向量——长度一样、类型一样、JSON 一样。把同一句话分别喂给三个模型,比一比:
同句跨模型余弦相似度
A 与 B 0.003
A 与 C 0.010
B 与 C 0.006
基本就是 0。它们是三个互相正交的向量空间,只是恰好维数相同——也正因为「恰好相同」,这个故障极难发现:返回里没有任何一处看着不对。
用 A 把文档灌进索引,用 B 去查。结果不是检索变差,是检索变成随机的。没有报错、没有告警,你几周之后觉得搜索结果怎么不对劲,才发现。
所以 auto/embed 只有一个候选。那个模型不可用时,请求直接失败并说明原因。在「悄悄把索引污染掉」和「报错」之间,报错是唯一安全的选择。
那三个数是怎么量出来的、以及一段可以在你自己端点上复现的代码,写在 Three 1024-Dimension Embedding Models, Three Coordinate Systems(英文)。
模型要换的时候怎么办
把别名背后的 embedding 模型换掉,是破坏性变更,不是升级。所以它会以新名字发布——auto/embed-v2——老名字继续可用。
于是你的选择是明确的:
锁死 auto/embed | 底下什么都不动 |
| 换到新名字 | 你自己挑时间,重建索引,切换期两个都能用 |
不会发生的事是:别名在某天夜里被重新指向。
参数与返回
| 项 | 值 |
|---|---|
| 模型别名 | auto/embed |
| 维度 | 1024 |
| 端点 | POST /v1/embeddings |
| 鉴权 | Authorization: Bearer sk-… |
| 返回 | OpenAI 形状 {data, model, usage} |
| 别名背后的候选数 | 1 |
清单里另外三条——qwen-embed/text-embedding-v3、text-embedding-v4、qwen3.7-text-embedding——可以直接按名字调用,想做实验或者已经统一到某一个上面都行。别名的存在只是为了让生产代码有个稳定的东西可锁。
向量接口目前限时免费。要变的话会先在本页公告再生效,已有的 key 不受影响。
什么场景适合用向量
向量化解决的是「意思相近但字面不同」的匹配问题。字面检索(关键词、正则、模糊匹配)在用户换个说法时就失效:搜「怎么退订」匹配不到「取消订阅的入口在哪」。把两边都转成向量再比距离,这类问题就消失了。
实际用得多的是四类场景。语义检索:把文档切片后转成向量存进索引,查询时转成向量做最近邻。去重与聚类:同一批文本两两算距离,阈值以下归为一组,用来清理重复内容或做主题归类。推荐:把用户历史行为和候选内容都转成向量,按距离排序。分类:拿少量标注样本的向量均值当类中心,新样本比距离就能归类,不需要训练模型。
不适合的场景也要说清楚。需要精确匹配的(订单号、身份证号、代码标识符)不要用向量——这类字符串改一个字符就是完全不同的东西,而向量会认为它们很接近。需要解释「为什么匹配」的也不适合,向量只给距离不给理由。
怎么判断检索效果好不好
不要凭感觉。先准备一批真实查询,每条人工标出「应该返回哪几条」,这叫黄金集。然后看两个数:命中率(应该返回的结果,有多少真的出现在前 K 条里)和排序质量(应该返回的结果,平均排在第几位)。同一个查询在两个索引上跑,数字差多少一目了然。
黄金集不需要大,五十到一百条查询就足够看出问题的量级。真正容易出错的是拿测试集调参、再拿同一批测试集汇报——那数字是虚的。留一部分查询不参与调整,只用来看最终效果。
接入时容易踩的坑
文本切片的方式直接影响效果。切得太碎,一句话被拆成两半,语义丢失;切得太大,一段里混了好几个主题,向量变成平均值,谁也不像。常见做法是按段落或小标题切,每片控制在几百字,相邻片段留一点重叠。
入库前把查询和文档用同一个模型转成向量。这条听起来废话,实际踩的人不少:先用 A 建了索引,后来接新服务时默认用了别的模型,结果不是检索变差,是检索变成随机的——两个模型的向量不在同一个坐标系里,距离算出来没有意义。
向量存进去之后原始文本也要留一份。检索出来的结果最终要给人看,只有向量没法展示;而且模型升级、重建索引时,原文是你唯一能重新生成向量的东西。
延伸阅读
- OpenAI API Reference —— 本页接口沿用的请求形状
- schema.org —— 本页结构化数据所用的类型定义
- Sitemap 协议 —— 站点页面的收录约定
常见问题
auto/embed 和直接写模型名有什么区别?
写模型名就锁定到那个具体模型;写 auto/embed 锁定到别名,而别名背后的模型不会在你不知情的时候更换。换模型是破坏性变更,会以 auto/embed-v2 这样的新名字发布,老名字继续可用。
为什么 auto/embed 只有一个候选?
不同的 embedding 模型不共享坐标系。实测三个候选,两两之间的同句余弦相似度只有 0.003 / 0.010 / 0.006,基本是 0。换模型会让已有索引失效,而且返回里看不出任何异常。所以模型不可用时直接报错,不降级。
返回的向量是多少维?
1024 维。
这个名字以后会指向别的模型吗?
不会。它只在当前模型被上游下线时换成新的别名版本,而不是原地改指向。
其他能力
同一套命名,一个能力一个别名,都在 /v1/models 里: