文档 · 向量

免费的 embedding 接口怎么用?别名不会偷偷换模型

作者:tokenexchage 团队 · 最后更新:2026-10-17

/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。

  1. 在控制台创建 API 密钥。
  2. 向 https://tokenexchage.com/v1/embeddings 发 POST,model 写 auto/embed,input 收字符串或字符串数组。
  3. 从返回的 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 建了索引,后来接新服务时默认用了别的模型,结果不是检索变差,是检索变成随机的——两个模型的向量不在同一个坐标系里,距离算出来没有意义。

向量存进去之后原始文本也要留一份。检索出来的结果最终要给人看,只有向量没法展示;而且模型升级、重建索引时,原文是你唯一能重新生成向量的东西。

延伸阅读

常见问题

auto/embed 和直接写模型名有什么区别?

写模型名就锁定到那个具体模型;写 auto/embed 锁定到别名,而别名背后的模型不会在你不知情的时候更换。换模型是破坏性变更,会以 auto/embed-v2 这样的新名字发布,老名字继续可用。

为什么 auto/embed 只有一个候选?

不同的 embedding 模型不共享坐标系。实测三个候选,两两之间的同句余弦相似度只有 0.003 / 0.010 / 0.006,基本是 0。换模型会让已有索引失效,而且返回里看不出任何异常。所以模型不可用时直接报错,不降级。

返回的向量是多少维?

1024 维。

这个名字以后会指向别的模型吗?

不会。它只在当前模型被上游下线时换成新的别名版本,而不是原地改指向。

其他能力

同一套命名,一个能力一个别名,都在 /v1/models 里:

rerank

auto/rerank

按相关度重排检索结果

tts

auto/tts

文字转语音

asr

auto/asr

语音转文字

image

auto/image

文生图

video

auto/video

文生视频,异步