TokenHub文本向量化与重排序完全指南:/v1/embeddings与/v1/rerank多协议支持详解
TokenHub文本向量化与重排序完全指南:/v1/embeddings与/v1/rerank多协议支持详解
TokenHub 为企业 AI 网关提供了开箱即用的文本向量化与重排序能力:POST /v1/embeddings 负责文本 Embedding,POST /v1/rerank 负责 Rerank 重排序。两个端点复用同一套 API Key 鉴权、路由、限流与请求审计体系,并且内置 OpenAI、Cohere、Jina、Voyage、DashScope、TEI、Gemini 等多协议适配——无论上游是自托管的 vLLM/Xinference,还是商用 Cohere/Voyage 服务,都只需一次配置即可统一接入。
为什么需要统一的文本向量化网关 🧭
RAG、语义检索、知识库问答等场景都绕不开两件事:把文本变成向量(Embedding),以及把候选文档重新打分排序(Rerank)。如果没有网关,你会面临这些痛点:
- 协议碎片化:OpenAI、Cohere、Jina、Voyage 各家的请求字段、路径、返回格式都不一样
- 用量黑箱:谁调了向量化接口、消耗了多少、花了多少钱,无从追溯
- 向量空间混乱:不同部署的向量互相比较,检索结果不可靠
TokenHub 的做法是:客户端只对接 /v1/embeddings 和 /v1/rerank 两个标准端点,协议差异全部由网关吸收;同时每个请求都会经过模型权限校验、TPM 预留、安全钩子和审计落盘。
/v1/embeddings:文本向量化端点详解 ✨
一个请求长什么样
最简请求只需 model 加文本(单条或数组均可):
{"model":"public-embedding","input":["第一条文本","第二条文本"],"dimensions":1024,"encoding_format":"float"}
批量输入会逐条返回稠密向量,且严格保留 index 与输入一一对应;上游返回数量、索引或维度不符时,网关会直接报错而不是静默放行。
可选参数速查
| 参数 | 取值 | 说明 |
|---|---|---|
dimensions |
1–65536 | 指定输出向量维度 |
encoding_format |
float / base64 |
向量编码格式 |
input_type |
query / document |
区分查询与文档语义 |
task |
协议相关 | 与 input_type 二选一,不能同时传 |
normalized / truncation / late_chunking / user |
— | 按上游协议支持情况透传 |
关键约束:单次最多 2048 条输入(个别协议上限更低);不支持的参数会被明确拒绝,而不是悄悄丢弃;稀疏向量、量化输出、多模态和异步 Batch 暂不在该端点范围内。
官方文档:docs/embeddings.md(中文版见 docs/zh-CN/embeddings.md)。
Embedding 多协议支持:一次配置接入 6 种上游 🌐
在 Provider 高级设置中的 Text embedding settings 选择 embedding_protocol,网关会自动完成请求/响应的协议转换。各协议默认路径如下:
| 协议 | Base URL 结尾 | 默认路径 | 适用场景 |
|---|---|---|---|
openai |
/v1 |
/embeddings |
OpenAI、SiliconFlow、vLLM/Xinference 兼容端点 |
cohere |
/v2 |
/embed |
Cohere 原生(要求 input_type 或 task) |
jina / voyage |
/v1 |
/embeddings |
任务与维度字段自动映射为原生名 |
dashscope |
/api/v1 |
/services/embeddings/text-embedding/text-embedding |
阿里百炼原生接口,每次 10 条上限 |
tei |
服务根地址 | /embed |
Hugging Face TEI 自托管服务 |
| Gemini 原生 | Gemini 基础地址 | :embedContent / :batchEmbedContents |
独立文本保持独立请求,不合并批次 |
留空则使用目录默认或 OpenAI 兼容协议;自定义渠道(如自部署模型服务)建议明确选择实际协议。embedding_path 可覆盖默认路径——注意它是相对路径,追加到 Base URL 上,不改变主机与凭据。
💡 本地部署示例:OpenAI 兼容端点
http://model-host:8000/v1/embeddings,Base URL 填http://model-host:8000/v1,协议选openai,路径留空即可。
向量空间:保证"向量可比"的关键 🔍
TokenHub 对向量兼容性的判断非常严格:默认要求 Provider、上游模型、适配器类型、Base URL、Embedding 协议与路径完全一致,路由才共享同一个向量空间。如果确认多个部署使用了等价模型版本,可在 Provider 中配置 embedding_spaces:
{"my-embedding-model": "space-v1"}
注意两点:
- 仅维度相同不等于空间相同,必须管理员确认兼容后才能共用空间 ID
- 空间冲突时请求返回
409 embedding_space_conflict;更换空间意味着业务侧要重建向量索引,TokenHub 本身从不改动外部索引
空间契约的实现细节可以参考 backend/internal/server/embedding_routes.go。
/v1/rerank:重排序端点详解 🎯
请求与响应
POST /v1/rerank 接收一个查询和一串候选文档,返回带相关性得分的结果:
{"model":"public-reranker","query":"如何续期证书?","documents":["续期说明","一篇无关文档"],"top_n":1,"return_documents":true}
响应中的 results 保留原始 index 与 relevance_score,return_documents 为 true 时带回 document.text。几个行为要点:
documents必须包含 1–2048 条非空文本;top_n介于 1 与文档数之间,不传则返回全部- 分数不做跨模型归一化,不同 Reranker 模型的得分不可直接比较
- 空查询、非法
top_n、无效的top_n/索引缺失都会显式报错 - 当前仅支持纯文本,图片、视频与异步任务不在本期范围
官方文档:docs/rerank.md(中文版见 docs/zh-CN/rerank.md)。
Rerank 协议支持对照表
在 Advanced → Text rerank settings 中按实际部署选择协议:
| 协议 | Base URL 结尾 | 默认端点 | 说明 |
|---|---|---|---|
jina |
/v1 |
/rerank |
Jina、SiliconFlow 及 vLLM/Xinference 兼容部署 |
cohere |
/v2 |
/rerank |
Cohere 文本重排,按 search unit 计费 |
voyage |
/v1 |
/rerank |
top_n 自动映射为 top_k |
qwen |
区域兼容地址 | /reranks |
阿里 qwen3-rerank |
dashscope |
/api/v1 |
/services/rerank/text-rerank/text-rerank |
阿里 gte-rerank-v2 原生封装 |
tei |
服务根地址 | /rerank |
Hugging Face TEI,文档映射为 texts |
instruction 参数在 Jina 兼容/Qwen/DashScope 场景下可用,truncation 适用于 Voyage 与 TEI——最终以所选模型的实际能力为准,不支持的选项会显式失败。自定义 openai-compatible/local 渠道若无厂商目录,自动采用 Jina 兼容的 /rerank 契约。
重排端点的完整执行链路(鉴权 → 隐私钩子 → 护栏 → 路由 → 缓存 → 计费)实现在 backend/internal/server/gateway_rerank_http.go。
计费与用量治理:每一笔向量调用都可追溯 📊
向量化与重排序请求同样纳入 TokenHub 的成本治理:
- 两侧定价:发布路由时需同时配置租户侧 Embedding 价格与供应商侧输入价格;确认自托管模型免费时,需显式设置
metadata.retrieval_pricing_confirmed="true",历史空零值不视为确认 - 用量诚实:上游未报告用量时保持"未报告",绝不拿估算值冒充实测数据
- 缓存复用:Embedding/Rerank 结果可通过缓存钩子复用,缓存键绑定向量空间与调用方范围,命中后免去重复上游调用
- 审计留痕:每次请求的载荷、错误、用量证据都保存在请求详情中,方便事后对账
常见问题快速排查 🛠️
Q:调用返回 501 provider_capability_not_supported?
说明所有候选线路都被运行时筛选排除,且尚未发出任何上游请求。查看 error.details.reasons 中的原因码逐项修复:
| 原因码 | 检查项 |
|---|---|
provider_capability_or_protocol_unsupported |
渠道是否支持对应 Embedding/Rerank 协议 |
tenant_price_not_configured |
对外模型是否配置了价格或明确确认免费 |
upstream_model_inventory_missing |
渠道库存是否有匹配的上游模型记录 |
upstream_model_modality_mismatch |
库存模型类型是否为 embedding |
upstream_text_input_unsupported |
库存是否支持文本输入 |
Q:返回 409 embedding_space_conflict?
多线路向量空间不一致。移除不兼容线路,或确认兼容后为相同模型配置同一空间 ID。
Q:如何发布前验证上游连通性?
管理员可用 POST /api/admin/playground/rerank(或对应 Embedding 预检)以管理会话直接测试上游模型,查看响应与用量证据,无需等租户侧验收。
总结
TokenHub 的 /v1/embeddings 与 /v1/rerank 把最碎片化的两件事——多协议向量/重排接入和用量治理——收敛成了两个干净的端点。核心要点回顾:
- 客户端零适配:标准端点 + API Key,OpenAI SDK 的
client.embeddings.create直接可用 - 协议全覆盖:Embedding 6 种协议 + Gemini 原生,Rerank 6 种协议,本地自托管与商用服务通吃
- 空间严格契约:向量可比性由网关强制保证,冲突显式报错
- 全程可治理:权限、限流、计费、审计与 RAG 业务链路完全打通
更多细节可查阅 docs/semantic-routing.md 与 docs/architecture.md,了解语义路由与网关整体架构设计。




